Harden agent-friendly discovery and one-shot execution

README.md

@@ -129,11 +129,14 @@ Opens the graphical interface where you can create and manage tools visually. Fe
 
 ```bash
 # Tool Management
-cmdforge list              # List all tools
+cmdforge list --filter summarize       # Filter installed tools for humans
+cmdforge list --json --filter summarize --limit 10  # Compact agent catalog
+cmdforge list --json --full --limit 1  # Explicitly include prompts/code
 cmdforge create mytool     # Create new tool
 cmdforge edit mytool       # Edit in $EDITOR
 cmdforge delete mytool     # Delete tool
 cmdforge run mytool        # Run a tool
+cat document.txt | cmdforge run-once "Summarize this:\n\n{input}"
 cmdforge test mytool       # Test with mock provider
 cmdforge check mytool      # Check dependencies (meta-tools)
 cmdforge inspect mytool    # Preflight, contract proposals, safe conformance tests
@@ -200,6 +203,31 @@ frequently repeated pipe pairs. Only tool names, anonymous pipe identifiers,
 counts, and timestamps are kept in `~/.cmdforge/usage.json`; command arguments
 and input/output content are never recorded or transmitted.
 
+### AI Assistant Workflow
+
+For coding assistants, use CmdForge when an installed or registry tool matches
+the task; direct application APIs remain appropriate when the API is part of
+the product being built.
+
+```bash
+# 1. Discover a compact local contract without exposing prompt/code bodies
+cmdforge list --json --filter "commit message" --limit 10
+
+# 2. Search remotely if no local tool fits
+cmdforge registry search "generate commit message" --json --limit 5
+
+# 3. Use a one-shot provider call for genuinely ad-hoc work
+git diff --staged | cmdforge run-once "Write a commit message for:\n\n{input}"
+
+# 4. Promote repeated work into a permanent, reviewable tool
+echo "Create a conventional commit-message tool" | forge-tool --name commit-msg
+```
+
+`run-once` honors `cmdforge config set default_provider NAME`, then selects an
+available configured provider when no default is set. Configure CmdForge as an
+MCP server when the assistant supports MCP so approved tools appear in its
+native tool catalog.
+
 ### Running Tools
 
 Once created, tools work like any Unix command: