Correct legacy documentation guidance
This commit is contained in:
parent
af3701b10b
commit
ca6135ac72
|
|
@ -583,7 +583,7 @@ from multiple AI providers simultaneously.</p>
|
|||
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:</p>
|
|||
},
|
||||
|
||||
"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": """
|
||||
<p class="lead">Every SmartTool is just a YAML file with a secret superpower: it turns plain English
|
||||
<p class="lead">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.</p>
|
||||
|
||||
<div class="bg-indigo-50 border-l-4 border-indigo-500 p-4 my-6">
|
||||
|
|
@ -830,7 +830,7 @@ HELLO WORLD!!!</code></pre>
|
|||
|
||||
<h2 id="the-five-parts">The Five Parts of Every Tool</h2>
|
||||
|
||||
<p>Think of a SmartTool config like a recipe card:</p>
|
||||
<p>Think of a CmdForge tool config like a recipe card:</p>
|
||||
|
||||
<div class="grid grid-cols-1 md:grid-cols-2 gap-4 my-6">
|
||||
<div class="bg-white border rounded-lg p-4">
|
||||
|
|
|
|||
|
|
@ -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": """
|
||||
<p class="lead">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.</p>
|
||||
|
||||
<h2 id="pipx">A Clean Personal Installation</h2>
|
||||
<p><code>pipx</code> keeps CmdForge isolated while placing <code>cmdforge</code> and <code>cf</code> on
|
||||
your path:</p>
|
||||
<pre><code class="language-bash">pipx install 'cmdforge[all]'
|
||||
cmdforge --version
|
||||
cmdforge --help</code></pre>
|
||||
<p>A normal virtual environment works just as well:</p>
|
||||
<pre><code class="language-bash">python3.10 -m venv .venv
|
||||
. .venv/bin/activate
|
||||
python -m pip install 'cmdforge[all]'</code></pre>
|
||||
|
||||
<h2 id="extras">Choose Only the Extras You Need</h2>
|
||||
<table class="w-full my-5"><thead class="bg-gray-100"><tr><th>Install</th><th>Adds</th></tr></thead><tbody>
|
||||
<tr class="border-b"><td><code>cmdforge</code></td><td>CLI, desktop GUI, contracts, registry client, and local tool runner</td></tr>
|
||||
<tr class="border-b"><td><code>cmdforge[mcp]</code></td><td>MCP client steps and MCP server integration</td></tr>
|
||||
<tr class="border-b"><td><code>cmdforge[pty]</code></td><td>Interactive pseudo-terminal providers</td></tr>
|
||||
<tr><td><code>cmdforge[all]</code></td><td>All optional runtime features, including the web stack</td></tr>
|
||||
</tbody></table>
|
||||
|
||||
<h2 id="provider">Let CmdForge Inspect the Machine</h2>
|
||||
<pre><code class="language-bash">cmdforge providers discover
|
||||
cmdforge providers discover --add
|
||||
cmdforge providers list</code></pre>
|
||||
<p>Discovery recognizes supported coding CLIs, API-key environment variables, and Ollama models.
|
||||
The built-in <code>mock</code> provider lets you test structure before authenticating a real engine.</p>
|
||||
|
||||
<h2 id="smoke-test">Run a Smoke Test</h2>
|
||||
<pre><code class="language-bash">cmdforge create hello --prompt "Reply with a short greeting to {input}"
|
||||
echo "Ada" | cmdforge run hello --provider mock
|
||||
cmdforge inspect hello</code></pre>
|
||||
<p>If wrapper commands are not on your shell path, add <code>~/.local/bin</code> or run the explicit
|
||||
<code>cmdforge run NAME</code> form.</p>
|
||||
|
||||
<h2 id="development">Install for Development</h2>
|
||||
<pre><code class="language-bash">git clone https://gitea.brrd.tech/rob/CmdForge.git
|
||||
cd CmdForge
|
||||
python -m pip install -e '.[all,dev]'
|
||||
pytest tests/ -m "not integration"</code></pre>
|
||||
<p>Continue with <a href="/docs/first-tool">Your First Tool</a>, or connect a coding host through
|
||||
<a href="/docs/mcp-overview">MCP</a>.</p>
|
||||
""",
|
||||
"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": """
|
||||
<p class="lead">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.</p>
|
||||
|
||||
<h2 id="discover">Discover Before Installing More Software</h2>
|
||||
<pre><code class="language-bash">cmdforge providers discover
|
||||
cmdforge providers discover --add
|
||||
cmdforge providers check</code></pre>
|
||||
<p>CmdForge looks for supported CLIs on <code>PATH</code>, known API-key environment variables, and
|
||||
models reported by a local Ollama installation. It never prints the values of discovered API keys.</p>
|
||||
|
||||
<h2 id="desktop">Use the Desktop Installer</h2>
|
||||
<ol>
|
||||
<li>Launch <code>cmdforge</code>.</li>
|
||||
<li>Open <strong>Providers</strong> in the sidebar.</li>
|
||||
<li>Choose <strong>Install Provider…</strong> to see available and already installed groups.</li>
|
||||
<li>Review the external installation instructions, then select the provider variants to add.</li>
|
||||
<li>Return to the Providers page and test the saved entry.</li>
|
||||
</ol>
|
||||
<p>The GUI and CLI edit the same <code>~/.cmdforge/providers.yaml</code> file.</p>
|
||||
|
||||
<h2 id="terminal">Use the Terminal Installer</h2>
|
||||
<pre><code class="language-bash">cmdforge providers install</code></pre>
|
||||
<p>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.</p>
|
||||
|
||||
<h2 id="ollama">A Local-First Starting Point</h2>
|
||||
<p>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:</p>
|
||||
<pre><code class="language-bash">ollama list
|
||||
cmdforge providers discover --add
|
||||
cmdforge providers list</code></pre>
|
||||
<p>A provider being local is a declared fact you should verify. For sensitive work, enforce it at
|
||||
runtime with <code>--require-local --no-fallback</code>.</p>
|
||||
|
||||
<h2 id="api">Add an OpenAI-Compatible API</h2>
|
||||
<pre><code class="language-bash">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</code></pre>
|
||||
<p>Only the environment variable name is stored. Keep the key in your normal credential mechanism,
|
||||
not in <code>providers.yaml</code>.</p>
|
||||
|
||||
<h2 id="verify">Test and Inspect</h2>
|
||||
<pre><code class="language-bash">cmdforge providers test research-api
|
||||
cmdforge providers list
|
||||
cmdforge providers for-tools summarize classify-text</code></pre>
|
||||
<p>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
|
||||
<a href="/docs/provider-policy">Provider Policy and Provenance</a>.</p>
|
||||
""",
|
||||
"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",
|
||||
|
|
|
|||
|
|
@ -155,10 +155,12 @@
|
|||
<div class="bg-gray-900 rounded-lg p-4 font-mono text-sm">
|
||||
<p class="text-gray-400"># Tools can call other tools:</p>
|
||||
<p class="text-yellow-400">steps:</p>
|
||||
<p class="text-gray-300"> - tool: official/code-review</p>
|
||||
<p class="text-gray-300"> - type: tool</p>
|
||||
<p class="text-gray-300"> tool: official/code-review</p>
|
||||
<p class="text-gray-300"> output_var: review</p>
|
||||
<p class="text-gray-300"> - tool: rob/summarize</p>
|
||||
<p class="text-gray-300"> input_template: "{review}"</p>
|
||||
<p class="text-gray-300"> - type: tool</p>
|
||||
<p class="text-gray-300"> tool: rob/summarize</p>
|
||||
<p class="text-gray-300"> input: "{review}"</p>
|
||||
<p class="text-gray-300"> output_var: summary</p>
|
||||
<p class="text-gray-400 mt-2"># Use like any Unix command:</p>
|
||||
<p class="text-green-400">$ cat app.py | my-review-tool</p>
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue