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.</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">
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": """
+<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",
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 @@
                 <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>
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