Add Visual Builder tutorial for the TUI

- New comprehensive tutorial covering smarttools ui
- ASCII art mockups of menu interface
- Documents all keyboard shortcuts
- Explains UI backends (urwid, snack, dialog)
- Comparison table: CLI vs Visual Builder use cases
- Updated getting-started to mention both UI and CLI options
- Added visual-builder to documentation TOC

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

src/smarttools/web/docs_content.py

@@ -27,8 +27,9 @@ Create tools that work with any AI provider and compose them like Unix pipes.</p
 <pre><code class="language-bash"># Install SmartTools
 pip install smarttools
 
-# Create your first tool interactively
+# Create your first tool (choose your style)
-smarttools create
+smarttools ui       # Visual builder with menus
+smarttools create   # CLI wizard
 
 # Or install a tool from the registry
 smarttools registry install official/summarize
@@ -36,6 +37,12 @@ smarttools registry install official/summarize
 # Use it!
 cat article.txt | summarize</code></pre>
 
+<div class="bg-cyan-50 border-l-4 border-cyan-500 p-4 my-4">
+    <p class="font-semibold text-cyan-800">Two Ways to Build</p>
+    <p class="text-cyan-700"><code>smarttools ui</code> launches a visual builder with menus and forms.
+    <code>smarttools create</code> uses a command-line wizard. Both create the same YAML config files.</p>
+</div>
+
 <h2 id="how-it-works">How It Works</h2>
 <p>Each tool is a YAML file that defines:</p>
 <ol>
@@ -69,7 +76,8 @@ output: "{summary}"</code></pre>
 <h2 id="next-steps">Next Steps</h2>
 <ul>
     <li><a href="/docs/installation">Installation Guide</a> - Detailed setup instructions</li>
-    <li><a href="/docs/first-tool">Your First Tool</a> - Step-by-step tutorial</li>
+    <li><a href="/docs/visual-builder">Visual Builder</a> - Build tools with menus (no YAML required)</li>
+    <li><a href="/docs/first-tool">Your First Tool</a> - Step-by-step YAML tutorial</li>
     <li><a href="/docs/providers">Providers</a> - Configure AI providers</li>
     <li><a href="/tools">Browse Tools</a> - Discover community tools</li>
 </ul>
@@ -2065,6 +2073,239 @@ output: "{formatted}"</code></pre>
             ("whats-next", "What's Next?"),
         ],
     },
+
+    "visual-builder": {
+        "title": "The Visual Builder",
+        "description": "Build tools without touching YAML using the terminal UI",
+        "content": """
+<p class="lead">Not everyone wants to write YAML by hand. SmartTools includes a full-featured
+terminal UI that lets you create, edit, and test tools with menus and forms—no text editor required.</p>
+
+<div class="bg-indigo-50 border-l-4 border-indigo-500 p-4 my-6">
+    <p class="font-semibold text-indigo-800">What You'll Learn</p>
+    <ul class="mt-2 text-indigo-700">
+        <li>How to launch and navigate the visual builder</li>
+        <li>Creating tools with point-and-click menus</li>
+        <li>Managing providers without editing config files</li>
+        <li>Testing tools before deploying them</li>
+    </ul>
+</div>
+
+<h2 id="launching">Launching the Visual Builder</h2>
+
+<p>Start the UI with a single command:</p>
+
+<pre><code class="language-bash">smarttools ui</code></pre>
+
+<p>You'll see a menu-driven interface that works in any terminal:</p>
+
+<div class="bg-gray-900 text-gray-100 rounded-lg p-4 my-6 font-mono text-sm">
+<pre>┌─────────────────────────────────────────────────────────┐
+│                  SmartTools Manager                      │
+├─────────────────────────────────────────────────────────┤
+│                                                          │
+│   [ List all tools      ]                               │
+│   [ Create new tool     ]                               │
+│   [ Edit existing tool  ]                               │
+│   [ Delete tool         ]                               │
+│   [ Test tool           ]                               │
+│   [ Manage providers    ]                               │
+│   [ Exit                ]                               │
+│                                                          │
+│         Use ↑↓ to navigate, Enter to select             │
+│                                                          │
+└─────────────────────────────────────────────────────────┘</pre>
+</div>
+
+<div class="bg-cyan-50 border-l-4 border-cyan-500 p-4 my-6">
+    <p class="font-semibold text-cyan-800">Pro Tip: Mouse Support</p>
+    <p class="text-cyan-700">If you have <code>urwid</code> installed (<code>pip install urwid</code>),
+    the UI supports mouse clicks! Just click on menu items instead of using arrow keys.</p>
+</div>
+
+<h2 id="creating-tools">Creating Tools Visually</h2>
+
+<p>Select "Create new tool" to open the tool builder. It has two main sections:</p>
+
+<div class="grid grid-cols-1 md:grid-cols-2 gap-4 my-6">
+    <div class="bg-white border-2 border-green-200 rounded-lg p-4">
+        <p class="font-bold text-green-800">1. Info & Arguments</p>
+        <ul class="text-sm text-green-700 mt-2">
+            <li>Set tool name and description</li>
+            <li>Add custom flags (--format, --max, etc.)</li>
+            <li>Define the output template</li>
+        </ul>
+    </div>
+    <div class="bg-white border-2 border-blue-200 rounded-lg p-4">
+        <p class="font-bold text-blue-800">2. Processing Steps</p>
+        <ul class="text-sm text-blue-700 mt-2">
+            <li>Add prompt steps (with provider selection)</li>
+            <li>Add code steps (Python processing)</li>
+            <li>Reorder steps with move up/down</li>
+        </ul>
+    </div>
+</div>
+
+<h3>Step-by-Step: Creating a Summarizer</h3>
+
+<ol class="space-y-3">
+    <li><strong>Launch:</strong> Run <code>smarttools ui</code></li>
+    <li><strong>Select:</strong> Choose "Create new tool"</li>
+    <li><strong>Info:</strong> Go to "Info & Args", set name to <code>summarize</code></li>
+    <li><strong>Add Argument:</strong> Click "Add Argument", set flag to <code>--length</code>, default to <code>100</code></li>
+    <li><strong>Add Step:</strong> Go to "Steps", select "Add Prompt Step"</li>
+    <li><strong>Provider:</strong> Choose your AI provider (or create one)</li>
+    <li><strong>Prompt:</strong> Enter your prompt template with <code>{input}</code> and <code>{length}</code></li>
+    <li><strong>Save:</strong> Select "Save Tool" from the main menu</li>
+</ol>
+
+<h2 id="managing-providers">Managing Providers</h2>
+
+<p>The UI makes it easy to add, edit, and delete AI providers without touching config files:</p>
+
+<div class="bg-gray-900 text-gray-100 rounded-lg p-4 my-6 font-mono text-sm">
+<pre>┌─────────────────────────────────────────────────────────┐
+│                   Manage Providers                       │
+├─────────────────────────────────────────────────────────┤
+│                                                          │
+│   claude         claude -p                              │
+│   opencode       opencode                                │
+│   mock           echo '[MOCK RESPONSE]'                 │
+│   ────────────────────────────────────────              │
+│   [ + Add New Provider ]                                │
+│   [ ← Back to Main Menu ]                               │
+│                                                          │
+└─────────────────────────────────────────────────────────┘</pre>
+</div>
+
+<p>Select a provider to edit or delete it. Adding a new provider shows a form:</p>
+
+<ul>
+    <li><strong>Name:</strong> Short identifier (e.g., <code>claude</code>)</li>
+    <li><strong>Command:</strong> The CLI command (e.g., <code>claude -p</code>)</li>
+    <li><strong>Description:</strong> What this provider does</li>
+</ul>
+
+<h2 id="testing">Testing Tools</h2>
+
+<p>Before deploying a tool, test it with the built-in mock provider:</p>
+
+<ol>
+    <li>Select "Test tool" from the main menu</li>
+    <li>Choose the tool you want to test</li>
+    <li>Enter test input in the text editor</li>
+    <li>See the result (uses mock provider by default)</li>
+</ol>
+
+<p>This lets you verify your prompts and variable substitution without making real API calls.</p>
+
+<h2 id="keyboard-shortcuts">Keyboard Shortcuts</h2>
+
+<table class="w-full my-4">
+    <thead class="bg-gray-100">
+        <tr>
+            <th class="px-4 py-2 text-left">Key</th>
+            <th class="px-4 py-2 text-left">Action</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr class="border-b">
+            <td class="px-4 py-2"><code>↑</code> / <code>↓</code></td>
+            <td class="px-4 py-2">Navigate menu items</td>
+        </tr>
+        <tr class="border-b">
+            <td class="px-4 py-2"><code>Enter</code></td>
+            <td class="px-4 py-2">Select / confirm</td>
+        </tr>
+        <tr class="border-b">
+            <td class="px-4 py-2"><code>Esc</code></td>
+            <td class="px-4 py-2">Cancel / go back</td>
+        </tr>
+        <tr class="border-b">
+            <td class="px-4 py-2"><code>Tab</code></td>
+            <td class="px-4 py-2">Move to next field (in forms)</td>
+        </tr>
+        <tr>
+            <td class="px-4 py-2"><code>q</code></td>
+            <td class="px-4 py-2">Quit the application</td>
+        </tr>
+    </tbody>
+</table>
+
+<h2 id="ui-backends">UI Backends</h2>
+
+<p>SmartTools automatically uses the best available terminal UI library:</p>
+
+<div class="grid grid-cols-1 md:grid-cols-3 gap-4 my-6 text-sm">
+    <div class="bg-green-50 border border-green-200 rounded-lg p-3">
+        <p class="font-bold text-green-800">urwid (Best)</p>
+        <p class="text-green-700">Mouse support, smooth</p>
+        <p class="text-xs text-green-600 mt-1"><code>pip install urwid</code></p>
+    </div>
+    <div class="bg-blue-50 border border-blue-200 rounded-lg p-3">
+        <p class="font-bold text-blue-800">snack</p>
+        <p class="text-blue-700">BIOS-style dialogs</p>
+        <p class="text-xs text-blue-600 mt-1"><code>apt install python3-newt</code></p>
+    </div>
+    <div class="bg-gray-50 border border-gray-200 rounded-lg p-3">
+        <p class="font-bold text-gray-800">dialog/whiptail</p>
+        <p class="text-gray-700">Fallback option</p>
+        <p class="text-xs text-gray-600 mt-1"><code>apt install dialog</code></p>
+    </div>
+</div>
+
+<h2 id="cli-vs-ui">CLI vs Visual Builder</h2>
+
+<p>When should you use each?</p>
+
+<table class="w-full my-4">
+    <thead class="bg-gray-100">
+        <tr>
+            <th class="px-4 py-2 text-left">Use the UI when...</th>
+            <th class="px-4 py-2 text-left">Use YAML when...</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr class="border-b">
+            <td class="px-4 py-2">You're new to SmartTools</td>
+            <td class="px-4 py-2">You're comfortable with YAML</td>
+        </tr>
+        <tr class="border-b">
+            <td class="px-4 py-2">Building your first few tools</td>
+            <td class="px-4 py-2">Making quick edits</td>
+        </tr>
+        <tr class="border-b">
+            <td class="px-4 py-2">Managing providers</td>
+            <td class="px-4 py-2">Copying tools between machines</td>
+        </tr>
+        <tr>
+            <td class="px-4 py-2">Testing interactively</td>
+            <td class="px-4 py-2">Version control integration</td>
+        </tr>
+    </tbody>
+</table>
+
+<h2 id="next-up">Next Up</h2>
+
+<p>Now that you know both ways to build tools:</p>
+
+<ul>
+    <li><a href="/tutorials/yaml-config">YAML Configuration</a> - Deep dive into the config format</li>
+    <li><a href="/tutorials/arguments">Adding Arguments</a> - Custom flags and options</li>
+    <li><a href="/docs/providers">Providers</a> - Configure AI backends</li>
+</ul>
+""",
+        "headings": [
+            ("launching", "Launching the Visual Builder"),
+            ("creating-tools", "Creating Tools Visually"),
+            ("managing-providers", "Managing Providers"),
+            ("testing", "Testing Tools"),
+            ("keyboard-shortcuts", "Keyboard Shortcuts"),
+            ("ui-backends", "UI Backends"),
+            ("cli-vs-ui", "CLI vs Visual Builder"),
+            ("next-up", "Next Up"),
+        ],
+    },
 }
 
 
@@ -2082,6 +2323,7 @@ def get_toc():
         SimpleNamespace(slug="getting-started", title="Getting Started", children=[
             SimpleNamespace(slug="installation", title="Installation"),
             SimpleNamespace(slug="first-tool", title="Your First Tool"),
+            SimpleNamespace(slug="visual-builder", title="Visual Builder"),
             SimpleNamespace(slug="yaml-config", title="YAML Config"),
         ]),
         SimpleNamespace(slug="arguments", title="Custom Arguments", children=[]),