Document agent-first tool workflows

src/cmdforge/web/docs_content.py

@@ -34,6 +34,13 @@ cmdforge create   # CLI wizard
 # Or install a tool from the registry
 cmdforge registry install official/summarize
 
+# Discover tools from scripts or an AI coding assistant
+cmdforge list --json --filter "summarize" --limit 10
+cmdforge registry search "summarize text" --json --limit 5
+
+# Run a one-off prompt without creating a tool
+cat article.txt | cmdforge run-once "Summarize this:\n\n{input}"
+
 # Use it!
 cat article.txt | summarize
 
@@ -46,6 +53,26 @@ cf</code></pre>
     <code>cmdforge create</code> uses a command-line wizard. Both create the same YAML config files.</p>
 </div>
 
+<h2 id="coding-agents">Using CmdForge with Coding Agents</h2>
+<p>CmdForge can expose installed tools to supported coding hosts over MCP. Preview the
+configuration first; CmdForge updates only its marked policy block and does not expose
+tools that you have not explicitly allowed.</p>
+<pre><code class="language-bash">cmdforge mcp configure codex --dry-run
+cmdforge mcp configure codex
+
+# Claude Code is supported too
+cmdforge mcp configure claude-code --dry-run</code></pre>
+<p>For a reusable workflow owned by an application, create it inside that application's
+<code>.cmdforge/</code> directory. Do not modify the CmdForge source repository merely to
+add a tool for another project.</p>
+<pre><code class="language-bash">cd your-project
+cmdforge create classify-docs --project
+
+# Or use the official AI-assisted creator
+cmdforge registry install official/forge-tool
+echo "Create a bounded document classifier" \
+  | forge-tool --name classify-docs --project</code></pre>
+
 <h2 id="how-it-works">How It Works</h2>
 <p>Each tool is a YAML file that defines:</p>
 <ol>
@@ -96,6 +123,7 @@ output: "{summary}"</code></pre>
         "headings": [
             ("what-is-cmdforge", "What is CmdForge?"),
             ("quick-start", "Quick Start"),
+            ("coding-agents", "Using CmdForge with Coding Agents"),
             ("how-it-works", "How It Works"),
             ("next-steps", "Next Steps"),
             ("get-help", "Get Help"),
@@ -160,8 +188,13 @@ pip install -e ".[dev]"</code></pre>
 <p class="lead">Let's create a simple tool that explains code. You'll learn the basics of tool configuration.</p>
 
 <h2 id="create-tool">Create the Tool</h2>
-<p>Run the interactive creator:</p>
-<pre><code class="language-bash">cmdforge create</code></pre>
+<p>Run the interactive creator. Use <code>--project</code> when the tool belongs to the
+current application and should be versioned with it:</p>
+<pre><code class="language-bash"># Personal tool in ~/.cmdforge/
+cmdforge create explain
+
+# Project-owned tool in ./.cmdforge/
+cmdforge create explain --project</code></pre>
 
 <p>Or create the file manually at <code>~/.cmdforge/explain/config.yaml</code>:</p>
 <pre><code class="language-yaml">name: explain
@@ -4004,12 +4037,12 @@ cat file.txt | summarize --provider mock</code></pre>
             <td class="px-4 py-2">Launch the Visual Builder (desktop GUI)</td>
         </tr>
         <tr class="border-b">
-            <td class="px-4 py-2"><code>cmdforge list</code></td>
-            <td class="px-4 py-2">List all installed tools</td>
+            <td class="px-4 py-2"><code>cmdforge list [--json] [--filter QUERY]</code></td>
+            <td class="px-4 py-2">List or machine-search installed tools</td>
         </tr>
         <tr class="border-b">
-            <td class="px-4 py-2"><code>cmdforge create</code></td>
-            <td class="px-4 py-2">Create a new tool (interactive wizard)</td>
+            <td class="px-4 py-2"><code>cmdforge create NAME [--project]</code></td>
+            <td class="px-4 py-2">Create a personal or project-owned tool</td>
         </tr>
         <tr class="border-b">
             <td class="px-4 py-2"><code>cmdforge edit &lt;tool&gt;</code></td>
@@ -4027,6 +4060,10 @@ cat file.txt | summarize --provider mock</code></pre>
             <td class="px-4 py-2"><code>cmdforge run &lt;tool&gt;</code></td>
             <td class="px-4 py-2">Run a tool directly (without wrapper)</td>
         </tr>
+        <tr class="border-b">
+            <td class="px-4 py-2"><code>cmdforge run-once "Instruction {input}"</code></td>
+            <td class="px-4 py-2">Run an ad-hoc prompt without creating a tool</td>
+        </tr>
         <tr class="border-b">
             <td class="px-4 py-2"><code>cmdforge refresh</code></td>
             <td class="px-4 py-2">Regenerate all wrapper scripts</td>

tests/test_web_docs_content.py

@@ -0,0 +1,26 @@
+"""Regression tests for user-facing documentation embedded in the web app."""
+
+from cmdforge.web.docs_content import get_doc
+
+
+def test_getting_started_documents_agent_first_workflow():
+    content = get_doc("getting-started")["content"]
+
+    expected_commands = (
+        "cmdforge list --json --filter",
+        "cmdforge registry search",
+        "cmdforge run-once",
+        "cmdforge create classify-docs --project",
+        "forge-tool --name classify-docs --project",
+        "cmdforge mcp configure codex --dry-run",
+        "cmdforge mcp configure claude-code --dry-run",
+    )
+    for command in expected_commands:
+        assert command in content
+
+
+def test_first_tool_explains_project_ownership():
+    content = get_doc("first-tool")["content"]
+
+    assert "cmdforge create explain --project" in content
+    assert "./.cmdforge/" in content