From ca6135ac722b9293d93081621b406897d51777ec Mon Sep 17 00:00:00 2001 From: rob Date: Tue, 21 Jul 2026 15:09:01 -0300 Subject: [PATCH] Correct legacy documentation guidance --- src/cmdforge/web/docs_content.py | 12 +- src/cmdforge/web/docs_modern.py | 127 ++++++++++++++++++++ src/cmdforge/web/templates/pages/index.html | 8 +- tests/test_web_docs_content.py | 13 ++ 4 files changed, 151 insertions(+), 9 deletions(-) diff --git a/src/cmdforge/web/docs_content.py b/src/cmdforge/web/docs_content.py index e352afd..0fd6675 100644 --- a/src/cmdforge/web/docs_content.py +++ b/src/cmdforge/web/docs_content.py @@ -583,7 +583,7 @@ from multiple AI providers simultaneously.

from concurrent.futures import ThreadPoolExecutor, as_completed def run_tool(tool_name: str, input_text: str) -> dict: - \"\"\"Run a SmartTool and return its output.\"\"\" + \"\"\"Run a CmdForge tool and return its output.\"\"\" result = subprocess.run( [tool_name], input=input_text, @@ -633,7 +633,7 @@ import subprocess import json from concurrent.futures import ThreadPoolExecutor, as_completed -# Define your perspective tools (each is a SmartTool) +# Define your perspective tools (each is a CmdForge tool) PERSPECTIVES = [ "perspective-optimist", # Focuses on opportunities "perspective-critic", # Identifies problems @@ -791,10 +791,10 @@ project. It implements:

}, "yaml-config": { - "title": "The Anatomy of a SmartTool", - "description": "Master the YAML configuration that powers every SmartTool", + "title": "The Anatomy of a CmdForge Tool", + "description": "Master the YAML configuration that powers every CmdForge tool", "content": """ -

Every SmartTool is just a YAML file with a secret superpower: it turns plain English +

Every CmdForge tool is just a YAML file with a secret superpower: it turns plain English instructions into Unix commands. In the next 10 minutes, you'll understand exactly how that magic works.

@@ -830,7 +830,7 @@ HELLO WORLD!!!

The Five Parts of Every Tool

-

Think of a SmartTool config like a recipe card:

+

Think of a CmdForge tool config like a recipe card:

diff --git a/src/cmdforge/web/docs_modern.py b/src/cmdforge/web/docs_modern.py index 944dcc4..d0c54ff 100644 --- a/src/cmdforge/web/docs_modern.py +++ b/src/cmdforge/web/docs_modern.py @@ -6,6 +6,133 @@ part of the book while retaining the established editorial voice. """ MODERN_DOCS = { + "installation": { + "title": "Installation", + "description": "Install CmdForge, discover an AI provider, and verify the command line", + "parent": "getting-started", + "content": """ +

CmdForge runs on Python 3.10 or newer. The command-line tools and desktop builder +install together; optional extras add MCP, interactive PTY providers, and the registry web stack.

+ +

A Clean Personal Installation

+

pipx keeps CmdForge isolated while placing cmdforge and cf on +your path:

+
pipx install 'cmdforge[all]'
+cmdforge --version
+cmdforge --help
+

A normal virtual environment works just as well:

+
python3.10 -m venv .venv
+. .venv/bin/activate
+python -m pip install 'cmdforge[all]'
+ +

Choose Only the Extras You Need

+ + + + + +
InstallAdds
cmdforgeCLI, desktop GUI, contracts, registry client, and local tool runner
cmdforge[mcp]MCP client steps and MCP server integration
cmdforge[pty]Interactive pseudo-terminal providers
cmdforge[all]All optional runtime features, including the web stack
+ +

Let CmdForge Inspect the Machine

+
cmdforge providers discover
+cmdforge providers discover --add
+cmdforge providers list
+

Discovery recognizes supported coding CLIs, API-key environment variables, and Ollama models. +The built-in mock provider lets you test structure before authenticating a real engine.

+ +

Run a Smoke Test

+
cmdforge create hello --prompt "Reply with a short greeting to {input}"
+echo "Ada" | cmdforge run hello --provider mock
+cmdforge inspect hello
+

If wrapper commands are not on your shell path, add ~/.local/bin or run the explicit +cmdforge run NAME form.

+ +

Install for Development

+
git clone https://gitea.brrd.tech/rob/CmdForge.git
+cd CmdForge
+python -m pip install -e '.[all,dev]'
+pytest tests/ -m "not integration"
+

Continue with Your First Tool, or connect a coding host through +MCP.

+""", + "headings": [ + ("pipx", "A Clean Personal Installation"), + ("extras", "Choose Only the Extras You Need"), + ("provider", "Inspect the Machine"), + ("smoke-test", "Run a Smoke Test"), + ("development", "Install for Development"), + ], + }, + + "provider-setup": { + "title": "Provider Setup", + "description": "Discover and verify local models, coding CLIs, and compatible APIs", + "parent": "providers", + "content": """ +

Provider setup is an inventory, not a pledge of allegiance. Add the engines already +available to you, describe their real trust boundaries, and choose among them per tool or per run.

+ +

Discover Before Installing More Software

+
cmdforge providers discover
+cmdforge providers discover --add
+cmdforge providers check
+

CmdForge looks for supported CLIs on PATH, known API-key environment variables, and +models reported by a local Ollama installation. It never prints the values of discovered API keys.

+ +

Use the Desktop Installer

+
    +
  1. Launch cmdforge.
    2. +
  2. Open Providers in the sidebar.
    3. +
  3. Choose Install Provider… to see available and already installed groups.
    4. +
  4. Review the external installation instructions, then select the provider variants to add.
    5. +
  5. Return to the Providers page and test the saved entry.
    6. +
+

The GUI and CLI edit the same ~/.cmdforge/providers.yaml file.

+ +

Use the Terminal Installer

+
cmdforge providers install
+

The interactive guide detects what is already present, shows installation instructions for what +is missing, and offers maintained provider variants. Since external CLIs change independently, +read the displayed command before approving it.

+ +

A Local-First Starting Point

+

Ollama is a useful choice when material must stay on the computer. After installing Ollama with +its official instructions and pulling a model, let CmdForge discover the exact model:

+
ollama list
+cmdforge providers discover --add
+cmdforge providers list
+

A provider being local is a declared fact you should verify. For sensitive work, enforce it at +runtime with --require-local --no-fallback.

+ +

Add an OpenAI-Compatible API

+
export RESEARCH_API_KEY="..."
+
+cmdforge providers add research-api https://api.example.com/v1 \
+  --type api --model research-model \
+  --api-key-env RESEARCH_API_KEY --locality remote \
+  --capability text --capability structured-json \
+  --data-policy public
+

Only the environment variable name is stored. Keep the key in your normal credential mechanism, +not in providers.yaml.

+ +

Test and Inspect

+
cmdforge providers test research-api
+cmdforge providers list
+cmdforge providers for-tools summarize classify-text
+

Testing confirms availability and a basic response. It does not prove privacy, semantic quality, +or model identity. Record those facts explicitly and use the strict controls in +Provider Policy and Provenance.

+""", + "headings": [ + ("discover", "Discover Before Installing"), + ("desktop", "Use the Desktop Installer"), + ("terminal", "Use the Terminal Installer"), + ("ollama", "A Local-First Starting Point"), + ("api", "Add a Compatible API"), + ("verify", "Test and Inspect"), + ], + }, + "mcp-overview": { "title": "MCP: Tools Without Islands", "description": "Connect CmdForge to the Model Context Protocol in both directions", diff --git a/src/cmdforge/web/templates/pages/index.html b/src/cmdforge/web/templates/pages/index.html index 2e1b003..b79fd19 100644 --- a/src/cmdforge/web/templates/pages/index.html +++ b/src/cmdforge/web/templates/pages/index.html @@ -155,10 +155,12 @@

# Tools can call other tools:

steps:

-

- tool: official/code-review

+

- type: tool

+

tool: official/code-review

output_var: review

-

- tool: rob/summarize

-

input_template: "{review}"

+

- type: tool

+

tool: rob/summarize

+

input: "{review}"

output_var: summary

# Use like any Unix command:

$ cat app.py | my-review-tool

diff --git a/tests/test_web_docs_content.py b/tests/test_web_docs_content.py index 7b78a74..8058889 100644 --- a/tests/test_web_docs_content.py +++ b/tests/test_web_docs_content.py @@ -110,3 +110,16 @@ def test_command_atlas_covers_every_top_level_cli_family(): for command in commands: assert f"cmdforge {command}" in content + + +def test_installation_matches_runtime_and_current_provider_onboarding(): + installation = get_doc("installation")["content"] + provider_setup = get_doc("provider-setup")["content"] + + assert "Python 3.10" in installation + assert "Python 3.8" not in installation + assert "cmdforge[mcp]" in installation + assert "cmdforge providers discover --add" in installation + assert "cmdforge providers discover --add" in provider_setup + assert "--type api" in provider_setup + assert "pip install claude-cli" not in provider_setup