Update help banner with link cutting shortcut

Added "Cut links: Alt+Shift+drag" to help banner.
Shortened other labels to fit.

In NodeGraphQt, connections are cut by:
- Alt+Shift+Left-drag to slice through connections
- Dragging a connection endpoint to empty space

Co-Authored-By: Claude Opus 4.5 <[email protected]>

.gitea/ISSUE_TEMPLATE/bug_report.md

@@ -21,7 +21,7 @@ What should have happened?
 ## Environment
 
 - OS:
-- SmartTools version:
+- CmdForge version:
 - Provider:
 - Docker or native install?
 

.gitea/ISSUE_TEMPLATE/question.md

@@ -1,6 +1,6 @@
 ---
 name: Question
-about: Ask a question about SmartTools
+about: Ask a question about CmdForge
 labels: question
 ---
 

.gitignore

@@ -45,3 +45,6 @@ discussions/
 diagrams/
 *.puml
 .tmp_*
+
+# Documentation symlink (points to project-docs)
+docs

AGENTS.md

@@ -1,25 +1,25 @@
 # Repository Guidelines
 
 ## Project Structure & Module Organization
-- `src/smarttools/` contains the core Python package (CLI entry point, tool model, runner, providers, UI backends).
+- `src/cmdforge/` contains the core Python package (CLI entry point, tool model, runner, providers, UI backends).
 - `tests/` holds pytest suites.
 - `docs/` includes installation, provider setup, examples, and design notes.
 - `examples/` provides sample tools and an installer script.
 - `wiki/` contains additional reference material.
 
 ## Architecture Overview
-- `cli.py` routes subcommands like `list`, `create`, `run`, `test`, `ui`, and `refresh`.
+- `cli/` directory routes subcommands like `list`, `create`, `run`, `test`, and `refresh`.
 - `tool.py` defines tool/step models and handles YAML config loading and wrapper generation.
 - `runner.py` executes steps and performs `{input}`/argument variable substitution.
 - `providers.py` shells out to configured AI provider CLIs (or the `mock` provider).
-- `ui_urwid.py` and `ui_snack.py` provide the TUI implementations, selected by `ui.py`.
+- `gui/` provides the PySide6 desktop GUI with pages for tools, registry, and providers.
 
 ## Build, Test, and Development Commands
-- `pip install -e ".[dev]"` installs SmartTools in editable mode with dev dependencies.
+- `pip install -e ".[dev]"` installs CmdForge in editable mode with dev dependencies.
 - `pytest` runs the full test suite.
 - `pytest tests/test.py::test_name` runs a focused test.
-- `python -m smarttools.cli` runs the CLI module directly.
-- `smarttools ui` launches the TUI (requires `urwid` or `python-newt`).
+- `python -m cmdforge.cli` runs the CLI module directly.
+- `cmdforge` launches the desktop GUI (requires PySide6).
 - `docker-compose build` builds the dev container image.
 - `docker-compose run --rm test` runs tests inside Docker.
 
@@ -38,5 +38,5 @@
 - PRs should include a clear summary, test results (or rationale if tests are skipped), and screenshots when UI behavior changes.
 
 ## Security & Configuration Tips
-- Provider credentials live in `~/.smarttools/providers.yaml`; avoid committing secrets.
-- User tool configs live in `~/.smarttools/<toolname>/config.yaml` and should not be added to the repo.
+- Provider credentials live in `~/.cmdforge/providers.yaml`; avoid committing secrets.
+- User tool configs live in `~/.cmdforge/<toolname>/config.yaml` and should not be added to the repo.

CHANGELOG.md

@@ -0,0 +1 @@
+# Auto-deploy test Tue 13 Jan 2026 03:09:44 AM AST

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-SmartTools is a lightweight personal tool builder for AI-powered CLI commands. It lets users create custom terminal commands that call AI providers, chain prompts with Python code steps, and use them like any Unix pipe command.
+CmdForge is a lightweight personal tool builder for AI-powered CLI commands. It lets users create custom terminal commands that call AI providers, chain prompts with Python code steps, and use them like any Unix pipe command.
 
 ## Development Commands
 
@@ -19,29 +19,30 @@ pytest
 pytest tests/test.py::test_name
 
 # Run the CLI
-python -m smarttools.cli
+python -m cmdforge.cli
 
-# Launch the UI
-smarttools ui
+# Launch the GUI
+cmdforge
 ```
 
 ## Architecture
 
-### Core Modules (`src/smarttools/`)
+### Core Modules (`src/cmdforge/`)
 
-- **cli.py**: Entry point (`smarttools` command). Routes subcommands: list, create, edit, delete, test, run, ui, refresh
+- **cli/**: CLI commands entry points (`cmdforge` command). Routes subcommands: list, create, edit, delete, test, run, refresh
 - **tool.py**: Tool definition dataclasses (`Tool`, `ToolArgument`, `PromptStep`, `CodeStep`), YAML config loading/saving, wrapper script generation
 - **runner.py**: Execution engine. Runs tool steps sequentially, handles variable substitution (`{input}`, `{varname}`), executes Python code steps via `exec()`
-- **providers.py**: Provider abstraction. Calls AI CLI tools via subprocess, reads provider configs from `~/.smarttools/providers.yaml`
-- **ui.py**: UI dispatcher - selects between urwid and snack implementations
-- **ui_urwid.py**: Full TUI implementation using urwid library
-- **ui_snack.py**: Fallback TUI using python-newt/snack
+- **providers.py**: Provider abstraction. Calls AI CLI tools via subprocess, reads provider configs from `~/.cmdforge/providers.yaml`
+- **gui/**: PySide6 desktop GUI
+  - **main_window.py**: Main application window with sidebar navigation
+  - **pages/**: Tools page, Tool Builder, Registry browser, Providers management
+  - **dialogs/**: Step editors, Argument editor, Provider dialog, Connect/Publish dialogs
 
 ### Key Paths
 
-- **Tools storage**: `~/.smarttools/<toolname>/config.yaml`
+- **Tools storage**: `~/.cmdforge/<toolname>/config.yaml`
 - **Wrapper scripts**: `~/.local/bin/<toolname>` (auto-generated bash scripts)
-- **Provider config**: `~/.smarttools/providers.yaml`
+- **Provider config**: `~/.cmdforge/providers.yaml`
 
 ### Tool Structure
 
@@ -67,7 +68,7 @@ Variable substitution is simple string replacement in `runner.py:substitute_vari
 
 ## Provider System
 
-Providers are CLI tools that accept prompts via stdin and output to stdout. Defined in `~/.smarttools/providers.yaml`:
+Providers are CLI tools that accept prompts via stdin and output to stdout. Defined in `~/.cmdforge/providers.yaml`:
 
 ```yaml
 providers:
@@ -78,3 +79,59 @@ providers:
 ```
 
 The `mock` provider is built-in for testing without API calls.
+
+## Web UI & Registry
+
+CmdForge includes a web interface and tool registry:
+
+### Web Modules (`src/cmdforge/web/`)
+
+- **app.py**: Flask app factory, registers blueprints
+- **routes.py**: Main web routes (docs, tutorials, tools, etc.)
+- **forum/**: Community forum blueprint
+  - **models.py**: Forum database schema (categories, topics, replies)
+  - **routes.py**: Forum routes (/forum, /forum/c/<slug>, /forum/t/<id>)
+- **filters.py**: Jinja2 filters (timeago, markdown, etc.)
+- **docs_content.py**: Documentation and tutorial content
+
+### Registry Modules (`src/cmdforge/registry/`)
+
+- **app.py**: Registry API (tool publishing, search, downloads)
+- **db.py**: SQLite schema and queries
+
+### Key URLs
+
+- `/forum` - Community forum
+- `/docs` - Documentation
+- `/tutorials` - Tutorial guides
+- `/tools` - Tool registry browser
+
+### Running the Web UI
+
+```bash
+# Development
+python -m cmdforge.web.app
+
+# Production (example)
+CMDFORGE_REGISTRY_DB=/path/to/db PORT=5050 python -m cmdforge.web.app
+```
+
+## Infrastructure Documentation
+
+For deployment, server details, and operations, see the `docs/` folder:
+
+- **docs/servers.md** - Server IPs (192.168.0.162), SSH access, paths, service commands
+- **docs/deployment.md** - Architecture diagram, deploy process, systemd service config
+- **docs/maintenance.md** - Backups, updates, troubleshooting
+- **docs/architecture.md** - Module structure, data flow diagrams
+
+### Production Server Quick Reference
+
+| Property | Value |
+|----------|-------|
+| Server | 192.168.0.162 (OpenMediaVault) |
+| SSH | `ssh [email protected]` |
+| App Path | `/srv/mergerfs/data_pool/home/rob/cmdforge-registry/` |
+| Service | `systemctl --user status cmdforge-web` |
+| Public URL | https://cmdforge.brrd.tech |
+| Port | 5050 (via Cloudflare tunnel) |

Dockerfile

@@ -1,11 +1,11 @@
-# SmartTools - AI-powered CLI command builder
-# Build: docker build -t smarttools .
-# Run:   docker run -it --rm -v ~/.smarttools:/root/.smarttools smarttools
+# CmdForge - AI-powered CLI command builder
+# Build: docker build -t cmdforge .
+# Run:   docker run -it --rm -v ~/.cmdforge:/root/.cmdforge cmdforge
 
 FROM python:3.12-slim
 
 LABEL maintainer="rob"
-LABEL description="SmartTools - Personal AI-powered CLI command builder"
+LABEL description="CmdForge - Personal AI-powered CLI command builder"
 
 # Install system dependencies
 RUN apt-get update && apt-get install -y --no-install-recommends \
@@ -31,26 +31,26 @@ WORKDIR /app
 COPY pyproject.toml README.md ./
 COPY src/ ./src/
 COPY examples/ ./examples/
-COPY docs/ ./docs/
+COPY tests/ ./tests/
 
-# Install SmartTools and dependencies
-RUN pip install --no-cache-dir -e ".[dev]"
+# Install CmdForge and all dependencies (CLI, TUI, registry)
+RUN pip install --no-cache-dir -e ".[all,dev]"
 
-# Create smarttools directory
-RUN mkdir -p /root/.smarttools /root/.local/bin
+# Create cmdforge directory
+RUN mkdir -p /root/.cmdforge /root/.local/bin
 
 # Install example tools
 RUN python examples/install.py
 
 # Generate CLI wrappers
-RUN smarttools refresh
+RUN cmdforge refresh
 
 # Add local bin to PATH
 ENV PATH="/root/.local/bin:${PATH}"
 
 # Default command - show help
-CMD ["smarttools", "--help"]
+CMD ["cmdforge", "--help"]
 
 # For interactive use:
-# docker run -it --rm smarttools smarttools ui
-# docker run -it --rm smarttools bash
+# docker run -it --rm cmdforge cmdforge ui
+# docker run -it --rm cmdforge bash

Dockerfile.ready

@@ -0,0 +1,98 @@
+# CmdForge - Ready-to-Use Container
+#
+# CmdForge is pre-installed and ready to use immediately.
+# Use this for regular usage after testing the installer.
+#
+# Build:
+#   docker build -f Dockerfile.ready -t cmdforge-ready .
+#
+# Run:
+#   docker run -it --rm cmdforge-ready
+#
+# With persistent storage (keeps your tools and settings):
+#   docker run -it --rm -v cmdforge-data:/home/user/.cmdforge cmdforge-ready
+#
+# Inside the container:
+#   cmdforge ui               # Launch the TUI
+#   cmdforge list             # List installed tools
+#   cmdforge run <tool>       # Run a tool
+
+FROM ubuntu:22.04
+
+LABEL maintainer="rob"
+LABEL description="CmdForge pre-installed and ready to use"
+
+# Prevent interactive prompts during package installation
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    # Python
+    python3 \
+    python3-pip \
+    python3-venv \
+    # Common tools
+    git \
+    curl \
+    vim \
+    less \
+    # For providers that need browser auth
+    firefox \
+    xdg-utils \
+    # X11 for display forwarding
+    libx11-6 \
+    libxext6 \
+    libxrender1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create a non-root user
+RUN useradd -m -s /bin/bash user
+USER user
+WORKDIR /home/user
+
+# Copy CmdForge source
+COPY --chown=user:user . /home/user/CmdForge
+
+# Set up PATH
+RUN mkdir -p /home/user/.local/bin
+ENV PATH="/home/user/.cmdforge-venv/bin:/home/user/.local/bin:${PATH}"
+
+# Install CmdForge in a virtual environment
+RUN python3 -m venv /home/user/.cmdforge-venv && \
+    /home/user/.cmdforge-venv/bin/pip install --upgrade pip && \
+    /home/user/.cmdforge-venv/bin/pip install -e "/home/user/CmdForge[all]"
+
+# Install example tools
+RUN /home/user/.cmdforge-venv/bin/python /home/user/CmdForge/examples/install.py
+
+# Generate CLI wrappers
+RUN /home/user/.cmdforge-venv/bin/cmdforge refresh
+
+# Welcome message
+RUN echo '\n\
+echo ""\n\
+echo "================================================================="\n\
+echo "  CmdForge - Ready to Use"\n\
+echo "================================================================="\n\
+echo ""\n\
+echo "  Commands:"\n\
+echo "    cmdforge ui              # Launch the graphical UI"\n\
+echo "    cmdforge list            # List installed tools"\n\
+echo "    cmdforge run <tool>      # Run a tool"\n\
+echo "    cmdforge create <name>   # Create a new tool"\n\
+echo ""\n\
+echo "  Registry:"\n\
+echo "    cmdforge registry search <query>   # Search for tools"\n\
+echo "    cmdforge registry install <tool>   # Install from registry"\n\
+echo ""\n\
+echo "  Provider setup:"\n\
+echo "    cmdforge providers install         # Set up AI provider"\n\
+echo ""\n\
+echo "================================================================="\n\
+echo ""\n\
+' >> /home/user/.bashrc
+
+WORKDIR /home/user
+
+# Start in interactive bash
+CMD ["/bin/bash"]

Dockerfile.test-install

@@ -0,0 +1,85 @@
+# CmdForge - Test Installation Container
+#
+# This container simulates a fresh computer for testing the installation process.
+# CmdForge source is available but NOT installed - you run the installer yourself.
+#
+# Build:
+#   docker build -f Dockerfile.test-install -t cmdforge-test-install .
+#
+# Run:
+#   docker run -it --rm cmdforge-test-install
+#
+# Inside the container:
+#   ./install.sh              # Run the installer
+#   cmdforge ui               # Launch the UI
+#   cmdforge providers install  # Set up an AI provider
+
+FROM ubuntu:22.04
+
+LABEL maintainer="rob"
+LABEL description="CmdForge installation test environment"
+
+# Prevent interactive prompts during package installation
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Install system dependencies (what a typical dev machine would have)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    # Python
+    python3 \
+    python3-pip \
+    python3-venv \
+    # Common tools a developer would have
+    git \
+    curl \
+    vim \
+    less \
+    # For providers that need browser auth
+    firefox \
+    xdg-utils \
+    # X11 for display forwarding
+    libx11-6 \
+    libxext6 \
+    libxrender1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create a non-root user (simulates typical user setup)
+RUN useradd -m -s /bin/bash testuser
+USER testuser
+WORKDIR /home/testuser
+
+# Copy CmdForge source (owned by testuser)
+COPY --chown=testuser:testuser . /home/testuser/CmdForge
+
+# Set up PATH for local bin (where cmdforge wrappers go)
+RUN mkdir -p /home/testuser/.local/bin
+ENV PATH="/home/testuser/.local/bin:${PATH}"
+
+# Make install script executable
+RUN chmod +x /home/testuser/CmdForge/install.sh
+
+# Welcome message
+RUN echo '\n\
+echo ""\n\
+echo "================================================================="\n\
+echo "  CmdForge Installation Test Environment"\n\
+echo "================================================================="\n\
+echo ""\n\
+echo "  CmdForge source is in: ~/CmdForge"\n\
+echo "  To install, run:"\n\
+echo ""\n\
+echo "    cd ~/CmdForge"\n\
+echo "    ./install.sh"\n\
+echo ""\n\
+echo "  After installation:"\n\
+echo "    cmdforge ui              # Launch the UI"\n\
+echo "    cmdforge list            # List tools"\n\
+echo "    cmdforge providers install  # Set up AI provider"\n\
+echo ""\n\
+echo "================================================================="\n\
+echo ""\n\
+' >> /home/testuser/.bashrc
+
+WORKDIR /home/testuser/CmdForge
+
+# Start in interactive bash
+CMD ["/bin/bash"]

README.md

@@ -1,4 +1,4 @@
-# SmartTools
+# CmdForge
 
 **A lightweight personal tool builder for AI-powered CLI commands.**
 
@@ -20,27 +20,28 @@ echo "Price $49.99, SKU ABC-123" | json-extract --fields "price, sku"
 # Output: {"price": 49.99, "sku": "ABC-123"}
 ```
 
-## Why SmartTools?
+## Why CmdForge?
 
 - **Unix Philosophy** - Tools that do one thing well, composable with pipes
 - **Provider Agnostic** - Works with Claude, GPT, Gemini, DeepSeek, local models
 - **No Lock-in** - Your tools are YAML files, your prompts are yours
 - **Multi-step Pipelines** - Chain AI prompts with Python code for validation
+- **Meta-tools** - Tools can call other tools for powerful composition
 - **12+ Providers Profiled** - We tested them so you don't have to
 
 ## Try It Now (60 seconds)
 
-See SmartTools in action without installing anything on your system:
+See CmdForge in action without installing anything on your system:
 
 ```bash
 # Pull the container
-docker pull gitea.brrd.tech/rob/smarttools:latest
+docker pull gitea.brrd.tech/rob/cmdforge:latest
 
 # Run it
-docker run -it --rm gitea.brrd.tech/rob/smarttools bash
+docker run -it --rm gitea.brrd.tech/rob/cmdforge bash
 
 # Inside the container - install OpenCode (includes free AI models)
-smarttools providers install   # Select option 4, then 'y'
+cmdforge providers install   # Select option 4, then 'y'
 source ~/.bashrc
 
 # Try it! This explains the README using the free Big Pickle model
@@ -55,21 +56,21 @@ For regular use, install natively:
 
 ```bash
 # Clone and install
-git clone https://gitea.brrd.tech/rob/SmartTools.git
-cd SmartTools
+git clone https://gitea.brrd.tech/rob/CmdForge.git
+cd CmdForge
 pip install -e .
 
 # Ensure ~/.local/bin is in PATH
 export PATH="$HOME/.local/bin:$PATH"
 
 # Install an AI provider (interactive guide)
-smarttools providers install
+cmdforge providers install
 
-# Launch the UI
-smarttools ui
+# Launch the GUI
+cmdforge
 
-# Or create your first tool
-smarttools create summarize
+# Or create your first tool via CLI
+cmdforge create summarize
 ```
 
 ## Installation
@@ -77,16 +78,16 @@ smarttools create summarize
 ### Native Install
 
 ```bash
-git clone https://gitea.brrd.tech/rob/SmartTools.git
-cd SmartTools
+git clone https://gitea.brrd.tech/rob/CmdForge.git
+cd CmdForge
 pip install -e .
 ```
 
 ### With Development Dependencies
 
 ```bash
-git clone https://gitea.brrd.tech/rob/SmartTools.git
-cd SmartTools
+git clone https://gitea.brrd.tech/rob/CmdForge.git
+cd CmdForge
 pip install -e ".[dev]"
 ```
 
@@ -94,7 +95,7 @@ pip install -e ".[dev]"
 
 - Python 3.10+
 - At least one AI CLI tool installed (see [Provider Setup](docs/PROVIDERS.md))
-- Optional: `urwid` for the TUI (`pip install urwid`)
+- PySide6 (included automatically - requires display server on Linux)
 
 ### Post-Install
 
@@ -107,29 +108,33 @@ export PATH="$HOME/.local/bin:$PATH"
 Then refresh wrapper scripts:
 
 ```bash
-smarttools refresh
+cmdforge refresh
 ```
 
 ## Usage
 
-### UI Mode (Recommended for Beginners)
+### GUI Mode (Recommended for Beginners)
 
 ```bash
-smarttools ui
+cmdforge
 ```
 
-Navigate with arrow keys, Tab, Enter, and mouse. Create tools visually with the built-in prompt editor.
+Opens the graphical interface where you can create and manage tools visually. Features include:
+- **My Tools** - Browse, create, edit, and delete tools organized by category
+- **Registry** - Search and install community tools from the CmdForge registry
+- **Providers** - Manage AI provider configurations
 
 ### CLI Mode
 
 ```bash
-smarttools list              # List all tools
-smarttools create mytool     # Create new tool
-smarttools edit mytool       # Edit in $EDITOR
-smarttools delete mytool     # Delete tool
-smarttools run mytool        # Run a tool
-smarttools test mytool       # Test with mock provider
-smarttools refresh           # Update executable wrappers
+cmdforge list              # List all tools
+cmdforge create mytool     # Create new tool
+cmdforge edit mytool       # Edit in $EDITOR
+cmdforge delete mytool     # Delete tool
+cmdforge run mytool        # Run a tool
+cmdforge test mytool       # Test with mock provider
+cmdforge check mytool      # Check dependencies (meta-tools)
+cmdforge refresh           # Update executable wrappers
 ```
 
 ### Running Tools
@@ -155,10 +160,10 @@ cat file.txt | mytool --provider mock
 
 ### Composing Tools
 
-SmartTools follows Unix philosophy: each tool does one thing well, and tools chain together for complex workflows.
+CmdForge follows Unix philosophy: each tool does one thing well, and tools chain together for complex workflows.
 
 ```bash
-# Chain SmartTools together
+# Chain CmdForge together
 cat error.log | log-errors | summarize | translate --lang Spanish
 
 # Code review pipeline: focus on changes, review, then summarize
@@ -208,7 +213,7 @@ translate-doc() {
 
 ## Example Tools
 
-SmartTools comes with 28 pre-built examples you can install:
+CmdForge comes with 28 pre-built examples you can install:
 
 ### Text Processing
 
@@ -259,14 +264,14 @@ SmartTools comes with 28 pre-built examples you can install:
 ### Install Example Tools
 
 ```bash
-# Run the example installer (from the SmartTools directory)
+# Run the example installer (from the CmdForge directory)
 python examples/install.py
-smarttools refresh
+cmdforge refresh
 ```
 
 ## Providers
 
-SmartTools works with any AI CLI tool. We've profiled 12 providers:
+CmdForge works with any AI CLI tool. We've profiled 12 providers:
 
 | Provider | Speed | Accuracy | Cost | Best For |
 |----------|-------|----------|------|----------|
@@ -281,7 +286,7 @@ See [docs/PROVIDERS.md](docs/PROVIDERS.md) for setup instructions.
 
 ## Tool Anatomy
 
-A tool is a YAML config file in `~/.smarttools/<name>/config.yaml`:
+A tool is a YAML config file in `~/.cmdforge/<name>/config.yaml`:
 
 ```yaml
 name: summarize
@@ -340,13 +345,44 @@ steps:
 output: "{validated}"
 ```
 
+### Meta-Tools (Tools Calling Tools)
+
+Tools can call other tools as steps, enabling powerful composition:
+
+```yaml
+name: summarize-and-translate
+description: Summarize text then translate the summary
+dependencies:
+  - official/summarize
+  - official/translate
+steps:
+  - type: tool
+    tool: official/summarize
+    input: "{input}"
+    args:
+      max_words: "100"
+    output_var: summary
+
+  - type: tool
+    tool: official/translate
+    input: "{summary}"
+    args:
+      target_language: "{language}"
+    output_var: translated
+output: "{translated}"
+```
+
+Check dependencies before running: `cmdforge check my-meta-tool`
+
+See [docs/META_TOOLS.md](docs/META_TOOLS.md) for full documentation.
+
 ### Variables
 
 | Variable | Description |
 |----------|-------------|
 | `{input}` | The piped/file input |
 | `{argname}` | Custom argument value |
-| `{step_output}` | Output from previous step |
+| `{output_var}` | Output from previous step (prompt, code, or tool) |
 
 ## Shell Integration
 
@@ -377,59 +413,103 @@ vnoremap <leader>fg :!fix-grammar<CR>
 vnoremap <leader>ec :!explain-code<CR>
 ```
 
-## UI Navigation
+## GUI Features
 
-| Action | Keys |
-|--------|------|
-| Cycle sections | `Tab` |
-| Go back | `Escape` |
-| Select | `Enter` or click |
-| Navigate | Arrow keys |
-| **Scroll content** | Mouse wheel |
-| **Scroll up** | Click top of scrollbar |
-| **Scroll down** | Click bottom of scrollbar |
-| **Page up/down** | Click middle of scrollbar |
-| **Select text** | `Shift` + mouse drag |
-| **Copy** | Terminal native (with Shift) |
-| **Paste** | `Ctrl+Shift+V` |
-| **Undo** (code editor) | `Alt+U` |
-| **Redo** (code editor) | `Alt+R` |
+The graphical interface provides a modern desktop experience:
 
-**Tips:**
-- Hold `Shift` while using mouse for terminal-native text selection.
-- Code/Prompt editors have DOS-style scrollbars with `▲` and `▼` arrow buttons.
-- In step dialogs, use `Tab` to cycle between File, Editor, and Output fields.
-- The code editor supports undo/redo (up to 50 states) with `Alt+U` and `Alt+R`.
-- Use the `$EDITOR` button to open code or prompts in your external editor.
+### My Tools Page
+- View all your tools organized by category (Text, Developer, Data, Other)
+- Double-click a tool to edit it
+- Create new tools with the built-in Tool Builder
+- Connect to the registry to publish your tools
 
-## AI-Assisted Code Generation
+### Tool Builder
+- Visual form for creating and editing tools
+- Add arguments with flags and default values
+- Add prompt steps (AI calls) with profile selection
+- Add code steps with **AI-assisted code generation**:
+  - Split view: code editor + AI assist panel
+  - Describe what you want and generate Python code
+  - Shows available variables from arguments and previous steps
+  - Automatic markdown fence stripping from AI responses
 
-When adding or editing a **Code Step**, the dialog includes an AI assist panel:
+### Registry Browser
+- **Browse all** tools on page load (no search required)
+- **Search** by name, description, or keyword
+- **Filter** by category (Text, Developer, Data, Other)
+- **Sort** by popularity, rating, newest, or name
+- **Star ratings** displayed in results and details
+- **Clickable tags** to filter by tag
+- **Installed indicator** (✓) shows which tools you have
+- **Update available** (↑) when newer version exists
+- **Pagination** for browsing large result sets
+- **Publisher info** showing reputation and total downloads
 
-```
-┌─ Code ─────────────┐ ┌─ AI Assisted Auto-adjust ─────────────┐
-│ result = input...  │ │ Provider: [opencode-deepseek] [▼]    │
-│                    │ │ ┌─ Prompt ──────────────────────────┐ │
-│                    │ │ │ Modify this code to...           │ │
-│                    │ │ │ {code}                           │ │
-│                    │ │ └──────────────────────────────────┘ │
-│                    │ │ ┌─ Output & Feedback ───────────────┐ │
-│                    │ │ │ ✓ Code updated successfully!     │ │
-│                    │ │ └──────────────────────────────────┘ │
-│                    │ │         < Auto-adjust >              │
-└────────────────────┘ └───────────────────────────────────────┘
+### Provider Management
+- Add and configure AI providers
+- Test provider connectivity
+- Set default providers for new tools
+
+### Profiles (AI Personas)
+- **Built-in profiles**: Comedian, Technical Writer, Teacher, Concise, Creative, Code Reviewer, Analyst
+- **Custom profiles**: Create your own personas with custom system prompts
+- **Profile selector**: Choose a profile when adding prompt steps to tools
+- **Automatic injection**: Profile system prompts are prepended to your prompts during execution
+
+### Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl+N` | Create new tool |
+| `Ctrl+S` | Save tool (in builder) |
+| `Ctrl+R` | Refresh current page |
+| `Ctrl+1` | Go to My Tools |
+| `Ctrl+2` | Go to Registry |
+| `Ctrl+3` | Go to Providers |
+| `Ctrl+4` | Go to Profiles |
+| `Escape` | Close tool builder |
+| `Ctrl+Q` | Quit application |
+
+## Multi-Step Tool Patterns
+
+CmdForge supports powerful multi-step workflows combining AI and code:
+
+### Code → AI
+Extract or transform data with Python, then pass to AI:
+```yaml
+steps:
+  - type: code
+    code: |
+      # Extract just the error lines
+      errors = [l for l in input_text.split('\n') if 'error' in l.lower()]
+      result = '\n'.join(errors[-10:])  # Last 10 errors
+    output_var: errors
+  - type: prompt
+    prompt: "Explain these errors:\n{errors}"
+    output_var: explanation
 ```
 
-- **Provider**: Select any configured AI provider
-- **Prompt**: Fully editable template - use `{code}` placeholder for current code
-- **Output**: Shows status, success/error messages, and provider feedback
-- **Auto-adjust**: Sends prompt to AI and replaces code with response
-
-This lets you generate or modify Python code using AI directly within the tool builder.
+### AI → Code
+Generate content with AI, then validate/process with Python:
+```yaml
+steps:
+  - type: prompt
+    prompt: "Generate Python code to: {input}"
+    output_var: generated
+  - type: code
+    code: |
+      import ast
+      try:
+          ast.parse(generated)  # Syntax check
+          result = generated
+      except SyntaxError as e:
+          result = f"# Syntax Error: {e}\n{generated}"
+    output_var: validated
+```
 
 ## Philosophy
 
-SmartTools is built on **Unix philosophy**:
+CmdForge is built on **Unix philosophy**:
 
 1. **Do one thing well** - Each tool solves one problem. `summarize` summarizes. `translate` translates. No bloated mega-tools.
 
@@ -444,15 +524,15 @@ SmartTools is built on **Unix philosophy**:
 ## Contributing
 
 ```bash
-git clone https://gitea.brrd.tech/rob/smarttools.git
-cd smarttools
+git clone https://gitea.brrd.tech/rob/cmdforge.git
+cd cmdforge
 pip install -e ".[dev]"
 pytest
 ```
 
 ## Support
 
-If SmartTools saves you time, consider supporting the project:
+If CmdForge saves you time, consider supporting the project:
 
 **Bitcoin:** `3KeLqGv2Xo8jGYkqA1i68a6nXwgQnuJoza`
 
@@ -464,33 +544,66 @@ MIT - Use it, modify it, share it.
 
 ## Docker
 
-### Pre-built Container (Fastest)
+### Pre-installed Container (Recommended)
 
-Pull and run the pre-built image directly:
+Ready-to-use container with CmdForge and 27 example tools pre-installed:
 
 ```bash
-# Pull from registry
-docker pull gitea.brrd.tech/rob/smarttools:latest
+# Build from source
+docker build -f Dockerfile.ready -t cmdforge-ready .
 
-# Run SmartTools
-docker run -it --rm gitea.brrd.tech/rob/smarttools smarttools --help
+# Run interactively
+docker run -it --rm cmdforge-ready
 
-# List available tools
-docker run -it --rm gitea.brrd.tech/rob/smarttools smarttools list
-
-# Interactive shell
-docker run -it --rm gitea.brrd.tech/rob/smarttools bash
+# With persistent storage (keeps your tools between runs)
+docker run -it --rm -v cmdforge-data:/home/user/.cmdforge cmdforge-ready
 ```
 
-### Build from Source
+Inside the container, CmdForge is ready to use:
+```bash
+cmdforge list            # See 27 pre-installed tools
+cmdforge                 # Launch the GUI (requires display)
+cmdforge run summarize   # Run a tool
+```
 
-Alternatively, build the container yourself:
+### Test Installation Container
+
+Simulates a fresh computer for testing the installation process:
 
 ```bash
-# Clone the repo
-git clone https://gitea.brrd.tech/rob/SmartTools.git
-cd SmartTools
+# Build the test container
+docker build -f Dockerfile.test-install -t cmdforge-test-install .
 
+# Run interactively
+docker run -it --rm cmdforge-test-install
+
+# Inside the container - run the installer
+cd ~/CmdForge
+./install.sh
+```
+
+### Interactive Installer
+
+The `install.sh` script provides guided installation:
+
+```bash
+./install.sh              # Full interactive install
+./install.sh --yes        # Non-interactive (accept defaults)
+./install.sh --no-venv    # Install without virtual environment
+./install.sh --no-examples # Skip installing example tools
+```
+
+Features:
+- Creates virtual environment at `~/.cmdforge-venv`
+- Configures PATH in your shell config (bash/zsh/fish)
+- Optionally installs 27 example tools
+- Works on macOS and Linux
+
+### Legacy Container
+
+The original docker-compose setup still works:
+
+```bash
 # Build the container
 docker-compose build
 
@@ -498,7 +611,7 @@ docker-compose build
 docker-compose run --rm test
 
 # Use the CLI
-docker-compose run --rm cli smarttools list
+docker-compose run --rm cli cmdforge list
 
 # Interactive shell
 docker-compose run --rm shell
@@ -518,12 +631,12 @@ xhost +local:docker
 docker run -it --rm \
   -e DISPLAY=$DISPLAY \
   -v /tmp/.X11-unix:/tmp/.X11-unix \
-  -v smarttools-data:/root/.smarttools \
+  -v cmdforge-data:/root/.cmdforge \
   --network host \
-  gitea.brrd.tech/rob/smarttools bash
+  gitea.brrd.tech/rob/cmdforge bash
 
 # Inside the container:
-smarttools providers install
+cmdforge providers install
 ```
 
 **Using docker-compose (build from source):**
@@ -533,14 +646,14 @@ xhost +local:docker
 docker-compose run --rm setup
 
 # Inside the container:
-smarttools providers install
+cmdforge providers install
 ```
 
 **After installing a provider:**
 
 ```bash
 # Test the provider works
-smarttools providers test claude
+cmdforge providers test claude
 ```
 
 **Available Providers:**
@@ -554,7 +667,17 @@ smarttools providers test claude
 
 ## Links
 
+### User Documentation
 - [Installation Guide](docs/INSTALL.md)
 - [Provider Setup](docs/PROVIDERS.md)
 - [Example Tools](docs/EXAMPLES.md)
+- [User Wiki](wiki/Home.md)
+
+### Developer Documentation
+- [Project Overview](docs/PROJECT.md) - Start here to understand the codebase
 - [Design Document](docs/DESIGN.md)
+- [Meta-Tools Design](docs/META_TOOLS.md) - Tools that call other tools
+- [Registry API Design](docs/REGISTRY.md)
+- [Web UI Design](docs/WEB_UI.md)
+- [Deployment Guide](docs/DEPLOYMENT.md)
+- [Architecture Diagrams](docs/diagrams/)

docker-compose.yml

@@ -1,9 +1,9 @@
-# SmartTools - AI-powered CLI command builder
+# CmdForge - AI-powered CLI command builder
 #
 # Quick Start:
 #   docker-compose build          # Build the image
 #   docker-compose run --rm test  # Run tests
-#   docker-compose run --rm cli smarttools list
+#   docker-compose run --rm cli cmdforge list
 #
 # This is a standalone project with no external dependencies.
 
@@ -17,10 +17,10 @@ services:
     build:
       context: .
       dockerfile: Dockerfile
-    image: smarttools:latest
+    image: cmdforge:latest
     volumes:
-      - smarttools-data:/root/.smarttools
-    command: ["smarttools", "--help"]
+      - cmdforge-data:/root/.cmdforge
+    command: ["cmdforge", "--help"]
 
   # ============================================================================
   # Tests
@@ -29,9 +29,9 @@ services:
     build:
       context: .
       dockerfile: Dockerfile
-    image: smarttools:latest
+    image: cmdforge:latest
     volumes:
-      - smarttools-data:/root/.smarttools
+      - cmdforge-data:/root/.cmdforge
     command: ["pytest", "-v"]
 
   # ============================================================================
@@ -41,9 +41,9 @@ services:
     build:
       context: .
       dockerfile: Dockerfile
-    image: smarttools:latest
+    image: cmdforge:latest
     volumes:
-      - smarttools-data:/root/.smarttools
+      - cmdforge-data:/root/.cmdforge
     command: ["/bin/bash"]
     stdin_open: true
     tty: true
@@ -57,11 +57,11 @@ services:
     build:
       context: .
       dockerfile: Dockerfile
-    image: smarttools:latest
+    image: cmdforge:latest
     environment:
       - DISPLAY=${DISPLAY:-:0}
     volumes:
-      - smarttools-data:/root/.smarttools
+      - cmdforge-data:/root/.cmdforge
       - /tmp/.X11-unix:/tmp/.X11-unix:ro
     command: ["/bin/bash"]
     stdin_open: true
@@ -69,8 +69,8 @@ services:
     network_mode: host
 
 volumes:
-  smarttools-data:
-    # Persists ~/.smarttools between container runs
+  cmdforge-data:
+    # Persists ~/.cmdforge between container runs
 
 # ==============================================================================
 # Usage Examples
@@ -83,8 +83,8 @@ volumes:
 #   docker-compose run --rm test
 #
 # Use CLI:
-#   docker-compose run --rm cli smarttools list
-#   docker-compose run --rm cli smarttools run hello-world
+#   docker-compose run --rm cli cmdforge list
+#   docker-compose run --rm cli cmdforge run hello-world
 #
 # Interactive shell:
 #   docker-compose run --rm shell
@@ -93,5 +93,5 @@ volumes:
 #   xhost +local:docker
 #   docker-compose run --rm setup
 #   # Inside container:
-#   smarttools providers install    # Interactive guide
+#   cmdforge providers install    # Interactive guide
 #   # Select a provider, it will install and open browser for auth

examples/install.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-Install all SmartTools example tools.
+Install all CmdForge example tools.
 
 Usage:
     python3 install.py              # Install all tools
@@ -9,7 +9,7 @@ Usage:
     python3 install.py --category dev  # Install category
 
 Run from anywhere:
-    curl -sSL https://gitea.brrd.tech/rob/smarttools/raw/branch/main/examples/install.py | python3
+    curl -sSL https://gitea.brrd.tech/rob/cmdforge/raw/branch/main/examples/install.py | python3
 """
 
 import argparse
@@ -22,7 +22,7 @@ except ImportError:
     print("PyYAML required. Install with: pip install pyyaml")
     sys.exit(1)
 
-TOOLS_DIR = Path.home() / ".smarttools"
+TOOLS_DIR = Path.home() / ".cmdforge"
 
 # All example tool configurations
 TOOLS = {
@@ -298,7 +298,7 @@ def list_tools():
 
 
 def main():
-    parser = argparse.ArgumentParser(description="Install SmartTools example tools")
+    parser = argparse.ArgumentParser(description="Install CmdForge example tools")
     parser.add_argument("tools", nargs="*", help="Specific tools to install (default: all)")
     parser.add_argument("--list", action="store_true", help="List available tools")
     parser.add_argument("--category", "-c", choices=list(CATEGORIES.keys()), help="Install tools from category")
@@ -335,7 +335,7 @@ def main():
             installed += 1
 
     print(f"\nInstalled {installed} tools.")
-    print("\nRun 'smarttools refresh' to create executable wrappers.")
+    print("\nRun 'cmdforge refresh' to create executable wrappers.")
 
 
 if __name__ == "__main__":

gunicorn.conf.py

@@ -0,0 +1,35 @@
+"""Gunicorn configuration for CmdForge web service."""
+
+import os
+
+# Server socket
+bind = "0.0.0.0:" + os.environ.get("PORT", "5050")
+backlog = 2048
+
+# Worker processes
+workers = 2  # Conservative for shared server
+worker_class = "sync"
+worker_connections = 1000
+timeout = 120
+keepalive = 2
+
+# Process naming
+proc_name = "cmdforge-web"
+
+# Logging
+accesslog = "-"  # stdout
+errorlog = "-"   # stderr
+loglevel = "info"
+access_log_format = '%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s"'
+
+# Server mechanics
+daemon = False
+pidfile = None
+umask = 0
+user = None
+group = None
+tmp_upload_dir = None
+
+# SSL (handled by Cloudflare, not needed here)
+keyfile = None
+certfile = None

install.sh

@@ -0,0 +1,413 @@
+#!/bin/bash
+#
+# CmdForge Installer
+#
+# Usage:
+#   ./install.sh              # Interactive installation
+#   ./install.sh --yes        # Accept all defaults (non-interactive)
+#   ./install.sh --no-venv    # Install to system Python (not recommended)
+#   ./install.sh --no-examples # Skip example tools
+#
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+NC='\033[0m' # No Color
+BOLD='\033[1m'
+
+# Configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+VENV_DIR="$HOME/.cmdforge-venv"
+LOCAL_BIN="$HOME/.local/bin"
+MIN_PYTHON_VERSION="3.10"
+
+# Parse arguments
+USE_VENV=true
+INSTALL_EXAMPLES=true
+AUTO_YES=false
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --yes|-y)
+            AUTO_YES=true
+            shift
+            ;;
+        --no-venv)
+            USE_VENV=false
+            shift
+            ;;
+        --no-examples)
+            INSTALL_EXAMPLES=false
+            shift
+            ;;
+        --help|-h)
+            echo "CmdForge Installer"
+            echo ""
+            echo "Usage: ./install.sh [OPTIONS]"
+            echo ""
+            echo "Options:"
+            echo "  --yes, -y       Accept all defaults (non-interactive)"
+            echo "  --no-venv       Install to system Python (not recommended)"
+            echo "  --no-examples   Skip installing example tools"
+            echo "  --help, -h      Show this help message"
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1"
+            echo "Run './install.sh --help' for usage"
+            exit 1
+            ;;
+    esac
+done
+
+# Helper functions
+print_header() {
+    echo ""
+    echo -e "${CYAN}${BOLD}$1${NC}"
+    echo -e "${CYAN}$(printf '=%.0s' {1..60})${NC}"
+}
+
+print_step() {
+    echo -e "${BLUE}[*]${NC} $1"
+}
+
+print_success() {
+    echo -e "${GREEN}[+]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[!]${NC} $1"
+}
+
+print_error() {
+    echo -e "${RED}[X]${NC} $1"
+}
+
+ask_yes_no() {
+    if $AUTO_YES; then
+        return 0
+    fi
+    local prompt="$1"
+    local default="${2:-y}"
+
+    if [[ "$default" == "y" ]]; then
+        prompt="$prompt [Y/n] "
+    else
+        prompt="$prompt [y/N] "
+    fi
+
+    read -r -p "$prompt" response
+    response=${response:-$default}
+
+    [[ "$response" =~ ^[Yy]$ ]]
+}
+
+version_gte() {
+    # Check if version $1 >= version $2
+    printf '%s\n%s\n' "$2" "$1" | sort -V -C
+}
+
+# Start installation
+clear 2>/dev/null || true
+
+echo ""
+echo -e "${CYAN}${BOLD}"
+echo "   ____                _ _____                    "
+echo "  / ___|_ __ ___   __| |  ___|__  _ __ __ _  ___ "
+echo " | |   | '_ \` _ \\ / _\` | |_ / _ \\| '__/ _\` |/ _ \\"
+echo " | |___| | | | | | (_| |  _| (_) | | | (_| |  __/"
+echo "  \\____|_| |_| |_|\\__,_|_|  \\___/|_|  \\__, |\\___|"
+echo "                                      |___/      "
+echo -e "${NC}"
+echo "  AI-powered CLI command builder"
+echo ""
+
+# ==============================================================================
+# Step 1: Check prerequisites
+# ==============================================================================
+print_header "Step 1: Checking Prerequisites"
+
+# Check Python
+print_step "Checking Python version..."
+
+PYTHON_CMD=""
+for cmd in python3 python; do
+    if command -v "$cmd" &> /dev/null; then
+        version=$("$cmd" --version 2>&1 | awk '{print $2}')
+        if version_gte "$version" "$MIN_PYTHON_VERSION"; then
+            PYTHON_CMD="$cmd"
+            break
+        fi
+    fi
+done
+
+if [[ -z "$PYTHON_CMD" ]]; then
+    print_error "Python $MIN_PYTHON_VERSION or higher is required"
+    echo ""
+    echo "Please install Python first:"
+    echo "  Ubuntu/Debian: sudo apt install python3 python3-pip python3-venv"
+    echo "  macOS:         brew install python3"
+    echo "  Windows:       https://www.python.org/downloads/"
+    exit 1
+fi
+
+PYTHON_VERSION=$("$PYTHON_CMD" --version 2>&1 | awk '{print $2}')
+print_success "Python $PYTHON_VERSION found ($PYTHON_CMD)"
+
+# Check pip
+print_step "Checking pip..."
+if ! "$PYTHON_CMD" -m pip --version &> /dev/null; then
+    print_error "pip is not installed"
+    echo ""
+    echo "Please install pip:"
+    echo "  Ubuntu/Debian: sudo apt install python3-pip"
+    echo "  macOS:         python3 -m ensurepip"
+    exit 1
+fi
+print_success "pip is available"
+
+# Check venv module (if using venv)
+if $USE_VENV; then
+    print_step "Checking venv module..."
+    if ! "$PYTHON_CMD" -m venv --help &> /dev/null; then
+        print_warning "venv module not available"
+        echo ""
+        if ask_yes_no "Install python3-venv? (recommended)" "y"; then
+            if command -v apt-get &> /dev/null; then
+                sudo apt-get update && sudo apt-get install -y python3-venv
+            else
+                print_error "Cannot auto-install venv. Please install manually."
+                echo "  Ubuntu/Debian: sudo apt install python3-venv"
+                exit 1
+            fi
+        else
+            print_warning "Continuing without venv (installing to system Python)"
+            USE_VENV=false
+        fi
+    else
+        print_success "venv module is available"
+    fi
+fi
+
+# Check we're in the CmdForge directory
+print_step "Checking CmdForge source..."
+if [[ ! -f "$SCRIPT_DIR/pyproject.toml" ]]; then
+    print_error "Cannot find CmdForge source files"
+    echo "Please run this script from the CmdForge directory"
+    exit 1
+fi
+print_success "CmdForge source found at $SCRIPT_DIR"
+
+# ==============================================================================
+# Step 2: Installation options
+# ==============================================================================
+print_header "Step 2: Installation Options"
+
+if ! $AUTO_YES; then
+    echo ""
+    echo "Installation options:"
+    echo ""
+
+    if $USE_VENV; then
+        echo -e "  ${GREEN}1.${NC} Use virtual environment at $VENV_DIR ${GREEN}(recommended)${NC}"
+    else
+        echo -e "  ${YELLOW}1.${NC} Install to system Python ${YELLOW}(--no-venv specified)${NC}"
+    fi
+
+    if $INSTALL_EXAMPLES; then
+        echo -e "  ${GREEN}2.${NC} Install 28 example tools"
+    else
+        echo -e "  ${YELLOW}2.${NC} Skip example tools ${YELLOW}(--no-examples specified)${NC}"
+    fi
+
+    echo ""
+
+    if ! ask_yes_no "Proceed with installation?" "y"; then
+        echo "Installation cancelled."
+        exit 0
+    fi
+fi
+
+# ==============================================================================
+# Step 3: Create virtual environment (if using)
+# ==============================================================================
+if $USE_VENV; then
+    print_header "Step 3: Setting Up Virtual Environment"
+
+    if [[ -d "$VENV_DIR" ]]; then
+        print_warning "Virtual environment already exists at $VENV_DIR"
+        if ask_yes_no "Remove and recreate?" "n"; then
+            rm -rf "$VENV_DIR"
+        fi
+    fi
+
+    if [[ ! -d "$VENV_DIR" ]]; then
+        print_step "Creating virtual environment..."
+        "$PYTHON_CMD" -m venv "$VENV_DIR"
+        print_success "Virtual environment created at $VENV_DIR"
+    fi
+
+    print_step "Activating virtual environment..."
+    source "$VENV_DIR/bin/activate"
+    print_success "Virtual environment activated"
+
+    # Upgrade pip in venv
+    print_step "Upgrading pip..."
+    pip install --upgrade pip --quiet
+    print_success "pip upgraded"
+else
+    print_header "Step 3: Using System Python"
+    print_warning "Installing to system Python (use --no-venv was specified)"
+fi
+
+# ==============================================================================
+# Step 4: Install CmdForge
+# ==============================================================================
+print_header "Step 4: Installing CmdForge"
+
+print_step "Installing CmdForge and dependencies..."
+cd "$SCRIPT_DIR"
+
+# Install with all optional dependencies
+pip install -e ".[all]" --quiet
+
+print_success "CmdForge installed successfully"
+
+# Verify installation
+print_step "Verifying installation..."
+if command -v cmdforge &> /dev/null; then
+    VERSION=$(cmdforge --version 2>&1 | head -1)
+    print_success "cmdforge command available: $VERSION"
+else
+    print_error "cmdforge command not found in PATH"
+    exit 1
+fi
+
+# ==============================================================================
+# Step 5: Set up PATH
+# ==============================================================================
+print_header "Step 5: Setting Up PATH"
+
+# Create local bin directory
+mkdir -p "$LOCAL_BIN"
+
+# Determine shell config file
+SHELL_CONFIG=""
+if [[ -f "$HOME/.bashrc" ]]; then
+    SHELL_CONFIG="$HOME/.bashrc"
+elif [[ -f "$HOME/.zshrc" ]]; then
+    SHELL_CONFIG="$HOME/.zshrc"
+elif [[ -f "$HOME/.bash_profile" ]]; then
+    SHELL_CONFIG="$HOME/.bash_profile"
+fi
+
+# Check if PATH already includes local bin
+PATH_LINE='export PATH="$HOME/.local/bin:$PATH"'
+PATH_CONFIGURED=false
+
+if [[ -n "$SHELL_CONFIG" ]]; then
+    if grep -q '.local/bin' "$SHELL_CONFIG" 2>/dev/null; then
+        print_success "PATH already configured in $SHELL_CONFIG"
+        PATH_CONFIGURED=true
+    fi
+fi
+
+# Add venv activation if using venv
+if $USE_VENV; then
+    VENV_LINE="source $VENV_DIR/bin/activate"
+    if [[ -n "$SHELL_CONFIG" ]] && ! grep -q "cmdforge-venv" "$SHELL_CONFIG" 2>/dev/null; then
+        print_step "Adding virtual environment activation to $SHELL_CONFIG..."
+        echo "" >> "$SHELL_CONFIG"
+        echo "# CmdForge virtual environment" >> "$SHELL_CONFIG"
+        echo "$VENV_LINE" >> "$SHELL_CONFIG"
+        print_success "Added venv activation to $SHELL_CONFIG"
+    fi
+fi
+
+# Add PATH if not already there
+if ! $PATH_CONFIGURED && [[ -n "$SHELL_CONFIG" ]]; then
+    print_step "Adding ~/.local/bin to PATH in $SHELL_CONFIG..."
+    echo "" >> "$SHELL_CONFIG"
+    echo "# CmdForge tool wrappers" >> "$SHELL_CONFIG"
+    echo "$PATH_LINE" >> "$SHELL_CONFIG"
+    print_success "Added PATH configuration to $SHELL_CONFIG"
+fi
+
+# Export for current session
+export PATH="$LOCAL_BIN:$PATH"
+
+# ==============================================================================
+# Step 6: Create wrapper scripts
+# ==============================================================================
+print_header "Step 6: Creating Tool Wrappers"
+
+print_step "Running cmdforge refresh..."
+cmdforge refresh
+print_success "Wrapper scripts created in $LOCAL_BIN"
+
+# ==============================================================================
+# Step 7: Install example tools (optional)
+# ==============================================================================
+if $INSTALL_EXAMPLES; then
+    print_header "Step 7: Installing Example Tools"
+
+    print_step "Installing 28 example tools..."
+    "$PYTHON_CMD" "$SCRIPT_DIR/examples/install.py"
+
+    print_step "Refreshing wrappers for new tools..."
+    cmdforge refresh
+
+    print_success "Example tools installed"
+else
+    print_header "Step 7: Skipping Example Tools"
+    print_warning "Example tools not installed (use 'python examples/install.py' later)"
+fi
+
+# ==============================================================================
+# Complete!
+# ==============================================================================
+print_header "Installation Complete!"
+
+echo ""
+echo -e "${GREEN}${BOLD}CmdForge has been installed successfully!${NC}"
+echo ""
+
+# Show installed tools count
+TOOL_COUNT=$(cmdforge list 2>/dev/null | grep -c "^" || echo "0")
+echo -e "  ${CYAN}Tools installed:${NC} $TOOL_COUNT"
+echo -e "  ${CYAN}Config location:${NC} ~/.cmdforge/"
+echo -e "  ${CYAN}Tool wrappers:${NC}   ~/.local/bin/"
+if $USE_VENV; then
+    echo -e "  ${CYAN}Virtual env:${NC}     $VENV_DIR"
+fi
+
+echo ""
+echo -e "${BOLD}Next Steps:${NC}"
+echo ""
+echo "  1. Reload your shell (or run: source $SHELL_CONFIG)"
+echo ""
+echo "  2. Set up an AI provider:"
+echo -e "     ${CYAN}cmdforge providers install${NC}"
+echo ""
+echo "  3. Launch the UI:"
+echo -e "     ${CYAN}cmdforge ui${NC}"
+echo ""
+echo "  4. Or try a tool directly:"
+echo -e "     ${CYAN}echo 'Hello world' | eli5${NC}"
+echo ""
+
+if $USE_VENV; then
+    echo -e "${YELLOW}Note:${NC} The virtual environment will be activated automatically"
+    echo "      in new shell sessions. For this session, run:"
+    echo -e "      ${CYAN}source $VENV_DIR/bin/activate${NC}"
+    echo ""
+fi
+
+echo -e "${CYAN}Documentation:${NC} https://pages.brrd.tech/rob/cmdforge/"
+echo -e "${CYAN}Source code:${NC}   https://gitea.brrd.tech/rob/CmdForge"
+echo ""

olddocs/COLLECTIONS.md

@@ -0,0 +1,116 @@
+# CmdForge Collections
+
+Collections are curated groups of tools that can be installed together with a single command.
+
+## Use Cases
+
+1. **Thematic bundles**: "writing-toolkit" with grammar, tone, simplify tools
+2. **Application stacks**: "data-science" with json-extract, csv-insights, etc.
+3. **Source bundles**: "fabric-text" with all Fabric text processing patterns
+4. **Workflow packages**: Tools that work well together for a specific task
+
+## Collection Manifest Format
+
+Collections are defined in the registry repo under `collections/`:
+
+```yaml
+# collections/writing-toolkit.yaml
+name: writing-toolkit
+display_name: Writing Toolkit
+description: Essential tools for writers and editors
+icon: pencil  # Optional icon identifier
+maintainer: official  # Publisher who maintains this collection
+
+tools:
+  - official/fix-grammar
+  - official/simplify
+  - official/tone-shift
+  - official/expand
+  - official/proofread
+
+# Optional: version constraints
+pinned:
+  official/fix-grammar: "^1.0.0"
+
+# Optional: suggested order for documentation
+order:
+  - official/fix-grammar
+  - official/proofread
+  - official/simplify
+  - official/tone-shift
+  - official/expand
+
+tags:
+  - writing
+  - editing
+  - grammar
+```
+
+## CLI Usage
+
+```bash
+# List available collections
+cmdforge collections list
+
+# View collection details
+cmdforge collections info writing-toolkit
+
+# Install all tools in a collection
+cmdforge collections install writing-toolkit
+
+# Install with version constraints from collection
+cmdforge collections install writing-toolkit --pinned
+```
+
+## API Endpoints
+
+```
+GET  /api/v1/collections              # List all collections
+GET  /api/v1/collections/:name        # Get collection details with tool info
+GET  /api/v1/collections/:name/tools  # Get just the tools list
+```
+
+## Database Schema
+
+```sql
+CREATE TABLE collections (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT UNIQUE NOT NULL,
+    display_name TEXT NOT NULL,
+    description TEXT,
+    icon TEXT,
+    maintainer TEXT NOT NULL,
+    tools TEXT NOT NULL,           -- JSON array of tool refs
+    pinned TEXT,                   -- JSON object of version constraints
+    tags TEXT,                     -- JSON array
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX idx_collections_name ON collections(name);
+CREATE INDEX idx_collections_maintainer ON collections(maintainer);
+```
+
+## Web UI
+
+- `/collections` - Browse all collections
+- `/collections/:name` - Collection detail page with tool grid
+- Install button that shows CLI command
+- Filter by tag, maintainer
+
+## Sync from Registry Repo
+
+Collections sync from the registry repo just like tools:
+
+```
+CmdForge-Registry/
+├── tools/
+│   └── ...
+└── collections/
+    ├── writing-toolkit.yaml
+    ├── data-science.yaml
+    ├── fabric-text.yaml
+    └── fabric-code.yaml
+```
+
+The webhook sync process reads `collections/*.yaml` and upserts to database.

olddocs/DEPLOYMENT.md

@@ -0,0 +1,319 @@
+# CmdForge Deployment Guide
+
+This guide covers deploying the CmdForge Registry web application.
+
+## Quick Start (Development)
+
+```bash
+# Clone and install
+git clone https://gitea.brrd.tech/rob/CmdForge.git
+cd CmdForge
+pip install -e ".[dev]"
+
+# Initialize database
+cd src/cmdforge/web
+python -c "from app import create_app; create_app()"
+
+# Run development server
+flask run --port 5050 --host 0.0.0.0
+```
+
+Access at `http://localhost:5050`
+
+## Production Deployment
+
+### Prerequisites
+
+- Python 3.8+
+- pip/pipx
+- nginx (recommended for reverse proxy)
+- systemd (for process management)
+
+### 1. Install Application
+
+```bash
+# Create application directory
+sudo mkdir -p /opt/cmdforge
+sudo chown $USER:$USER /opt/cmdforge
+cd /opt/cmdforge
+
+# Clone repository
+git clone https://gitea.brrd.tech/rob/CmdForge.git .
+
+# Create virtual environment
+python3 -m venv venv
+source venv/bin/activate
+
+# Install dependencies
+pip install -e ".[prod]"
+pip install gunicorn
+```
+
+### 2. Configure Environment
+
+Create `/opt/cmdforge/.env`:
+
+```bash
+# Required
+FLASK_ENV=production
+SECRET_KEY=your-secret-key-here  # Generate with: python -c "import secrets; print(secrets.token_hex(32))"
+
+# Optional
+SENTRY_DSN=https://[email protected]/xxx  # Error monitoring
+SITE_URL=https://cmdforge.brrd.tech  # For sitemap/SEO
+```
+
+### 3. Initialize Database
+
+```bash
+cd /opt/cmdforge/src/cmdforge/web
+python -c "from app import create_app; create_app()"
+```
+
+Database will be created at `data/cmdforge.db`.
+
+### 4. systemd Service
+
+You can run as either a **system service** (requires root) or a **user service** (no root needed).
+
+#### Option A: User Service (Recommended for personal servers)
+
+Create `~/.config/systemd/user/cmdforge-web.service`:
+
+```ini
+[Unit]
+Description=CmdForge Registry Web Application
+After=network.target
+
+[Service]
+Type=simple
+WorkingDirectory=/path/to/cmdforge
+Environment="PATH=/path/to/cmdforge/venv/bin"
+Environment="CMDFORGE_REGISTRY_DB=/tmp/cmdforge-data/registry.db"
+ExecStartPre=/path/to/cmdforge/scripts/db-restore.sh
+ExecStart=/path/to/cmdforge/venv/bin/gunicorn \
+    -c gunicorn.conf.py \
+    cmdforge.web.app:create_web_app()
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+```
+
+Enable and start:
+
+```bash
+# Enable lingering (so service runs without login)
+loginctl enable-linger $USER
+
+# Reload and enable
+systemctl --user daemon-reload
+systemctl --user enable cmdforge-web
+systemctl --user start cmdforge-web
+
+# Check status
+systemctl --user status cmdforge-web
+
+# View logs
+journalctl --user -u cmdforge-web -f
+```
+
+**Note:** The current OMV deployment uses this approach.
+
+#### Option B: System Service (Traditional deployment)
+
+Create `/etc/systemd/system/cmdforge-web.service`:
+
+```ini
+[Unit]
+Description=CmdForge Registry Web Application
+After=network.target
+
+[Service]
+Type=simple
+User=www-data
+Group=www-data
+WorkingDirectory=/opt/cmdforge
+Environment="PATH=/opt/cmdforge/venv/bin"
+EnvironmentFile=/opt/cmdforge/.env
+ExecStart=/opt/cmdforge/venv/bin/gunicorn \
+    --workers 4 \
+    --bind 127.0.0.1:5050 \
+    --access-logfile /var/log/cmdforge/access.log \
+    --error-logfile /var/log/cmdforge/error.log \
+    'cmdforge.web.app:create_app()'
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Enable and start:
+
+```bash
+# Create log directory
+sudo mkdir -p /var/log/cmdforge
+sudo chown www-data:www-data /var/log/cmdforge
+
+# Enable service
+sudo systemctl daemon-reload
+sudo systemctl enable cmdforge-web
+sudo systemctl start cmdforge-web
+
+# Check status
+sudo systemctl status cmdforge-web
+```
+
+### 5. nginx Configuration
+
+Create `/etc/nginx/sites-available/cmdforge`:
+
+```nginx
+server {
+    listen 80;
+    server_name cmdforge.brrd.tech;
+
+    # Redirect HTTP to HTTPS
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name cmdforge.brrd.tech;
+
+    # SSL certificates (use certbot for Let's Encrypt)
+    ssl_certificate /etc/letsencrypt/live/cmdforge.brrd.tech/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/cmdforge.brrd.tech/privkey.pem;
+
+    # SSL settings
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_prefer_server_ciphers on;
+    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
+
+    # Static files (optional - Flask can serve these)
+    location /static/ {
+        alias /opt/cmdforge/src/cmdforge/web/static/;
+        expires 1d;
+        add_header Cache-Control "public, immutable";
+    }
+
+    # Proxy to gunicorn
+    location / {
+        proxy_pass http://127.0.0.1:5050;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+Enable site:
+
+```bash
+sudo ln -s /etc/nginx/sites-available/cmdforge /etc/nginx/sites-enabled/
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+### 6. SSL with Let's Encrypt
+
+```bash
+sudo apt install certbot python3-certbot-nginx
+sudo certbot --nginx -d cmdforge.brrd.tech
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `FLASK_ENV` | Yes | `production` or `development` |
+| `SECRET_KEY` | Yes | Secret key for sessions (32+ chars) |
+| `SENTRY_DSN` | No | Sentry error monitoring DSN |
+| `SITE_URL` | No | Public URL for sitemap generation |
+| `DATABASE_PATH` | No | Override database path (default: `data/cmdforge.db`) |
+
+## Database Backup
+
+```bash
+# Backup
+cp /opt/cmdforge/data/cmdforge.db /backup/cmdforge-$(date +%Y%m%d).db
+
+# Or use SQLite backup command for consistency
+sqlite3 /opt/cmdforge/data/cmdforge.db ".backup '/backup/cmdforge.db'"
+```
+
+## Monitoring
+
+### Logs
+
+```bash
+# For user service (OMV deployment)
+journalctl --user -u cmdforge-web -f
+
+# For system service
+tail -f /var/log/cmdforge/error.log
+tail -f /var/log/cmdforge/access.log
+journalctl -u cmdforge-web -f
+```
+
+### Sentry Integration
+
+The application includes Sentry integration for error monitoring. Set `SENTRY_DSN` environment variable to enable.
+
+### Health Check
+
+```bash
+curl http://localhost:5050/api/v1/tools
+```
+
+## Troubleshooting
+
+### Service won't start
+
+```bash
+# For user service
+journalctl --user -u cmdforge-web -n 50
+systemctl --user status cmdforge-web
+
+# For system service
+journalctl -u cmdforge-web -n 50
+sudo systemctl status cmdforge-web
+
+# Verify Python path
+/path/to/cmdforge/venv/bin/python -c "import cmdforge"
+
+# Test gunicorn manually
+cd /path/to/cmdforge
+source venv/bin/activate
+gunicorn -c gunicorn.conf.py 'cmdforge.web.app:create_web_app()'
+```
+
+### Database errors
+
+```bash
+# Check database exists and is readable
+ls -la /opt/cmdforge/data/cmdforge.db
+
+# Verify permissions
+chown www-data:www-data /opt/cmdforge/data/
+chown www-data:www-data /opt/cmdforge/data/cmdforge.db
+```
+
+### Static files not loading
+
+```bash
+# Rebuild Tailwind CSS
+cd /opt/cmdforge
+npm install
+npm run css:build
+
+# Or use development CSS
+# (static/css/output.css should exist)
+```
+
+## Architecture Diagram
+
+See `docs/diagrams/deployment-architecture.svg` for visual representation.

olddocs/DESIGN.md

@@ -1,10 +1,10 @@
-# SmartTools - Design Document
+# CmdForge - Design Document
 
 > A lightweight personal tool builder for AI-powered CLI commands
 
 ## Overview
 
-SmartTools lets you create custom AI-powered terminal commands. You define a tool once (name, steps, provider), then use it like any Linux command.
+CmdForge lets you create custom AI-powered terminal commands. You define a tool once (name, steps, provider), then use it like any Linux command.
 
 **Example:**
 ```bash
@@ -17,7 +17,7 @@ sum -i text.txt -o summary.txt --max 512
 ### Tool = Directory + Config
 
 ```
-~/.smarttools/
+~/.cmdforge/
   sum/
     config.yaml
     processed.py      # Optional external code file
@@ -46,6 +46,11 @@ steps:
     provider: claude
     output_var: response
 output: "{response}"
+
+# Optional: declare dependencies for meta-tools
+dependencies:
+  - official/summarize
+  - official/translate@^1.0.0    # With version constraint
 ```
 
 ### Step Types
@@ -68,6 +73,17 @@ output: "{response}"
   code_file: processed.py    # Optional: external file storage
 ```
 
+**Tool Step** - Calls another CmdForge tool (meta-tools):
+```yaml
+- type: tool
+  tool: official/summarize    # Tool reference (owner/name or just name for local)
+  input: "{input}"            # Input to pass (supports variable substitution)
+  args:                       # Optional arguments
+    max_words: "100"
+  output_var: summary         # Variable to store the tool's output
+  provider: claude            # Optional: override the called tool's provider
+```
+
 Steps execute in order. Each step's `output_var` becomes available to subsequent steps.
 
 ### Variables
@@ -128,8 +144,8 @@ sum --stdin
 # No input (empty string) - useful for tools using only arguments
 sum --max 100
 
-# Or via smarttools run
-smarttools run sum -i document.txt
+# Or via cmdforge run
+cmdforge run sum -i document.txt
 ```
 
 ### Input Handling
@@ -158,17 +174,18 @@ smarttools run sum -i document.txt
 
 ```bash
 # Launch the UI to manage tools
-smarttools
+cmdforge
 
 # Or use CLI directly:
-smarttools list              # List all tools
-smarttools create sum        # Create new tool (basic)
-smarttools edit sum          # Edit tool config in $EDITOR
-smarttools delete sum        # Delete tool
-smarttools test sum          # Test with mock provider
-smarttools run sum           # Run tool for real
-smarttools refresh           # Refresh all wrapper scripts
-smarttools ui                # Launch interactive UI
+cmdforge list              # List all tools
+cmdforge create sum        # Create new tool (basic)
+cmdforge edit sum          # Edit tool config in $EDITOR
+cmdforge delete sum        # Delete tool
+cmdforge test sum          # Test with mock provider
+cmdforge run sum           # Run tool for real
+cmdforge refresh           # Refresh all wrapper scripts
+cmdforge check sum         # Check dependencies for meta-tools
+cmdforge ui                # Launch interactive UI
 ```
 
 ## Terminal UI
@@ -179,7 +196,7 @@ A BIOS-style terminal UI using `urwid` with full mouse support.
 
 ```
 ┌──────────────────────────────────────┐
-│         SmartTools Manager           │
+│         CmdForge Manager           │
 ├──────────────────────────────────────┤
 │  Tools:                              │
 │  ┌────────────────────────────────┐  │
@@ -256,7 +273,7 @@ The current section's title is highlighted with brackets: `[ Tool Info ]`
 
 **Code Step Features:**
 - **Multiline editor** - Write multi-line Python code
-- **External file storage** - Code is auto-saved to `~/.smarttools/<toolname>/<filename>` on OK
+- **External file storage** - Code is auto-saved to `~/.cmdforge/<toolname>/<filename>` on OK
 - **Load button** - Load code from external file (with confirmation)
 - **Multiple output vars** - Capture multiple variables (comma-separated)
 
@@ -265,7 +282,7 @@ The current section's title is highlighted with brackets: `[ Tool Info ]`
 ### Directory Structure
 
 ```
-smarttools/
+cmdforge/
   __init__.py
   cli.py           # Entry point, argument parsing
   ui.py            # UI dispatcher (chooses urwid/snack/dialog)
@@ -278,7 +295,7 @@ smarttools/
 
 ### Provider System
 
-Providers are defined in `~/.smarttools/providers.yaml`:
+Providers are defined in `~/.cmdforge/providers.yaml`:
 
 ```yaml
 providers:
@@ -297,18 +314,18 @@ The provider command receives the prompt via stdin and outputs to stdout.
 
 ### Wrapper Scripts
 
-When you save a tool, SmartTools creates a wrapper script in `~/.local/bin/`:
+When you save a tool, CmdForge creates a wrapper script in `~/.local/bin/`:
 
 ```bash
 #!/bin/bash
-# SmartTools wrapper for 'sum'
+# CmdForge wrapper for 'sum'
 # Auto-generated - do not edit
-exec /path/to/python -m smarttools.runner sum "$@"
+exec /path/to/python -m cmdforge.runner sum "$@"
 ```
 
 The wrapper uses the full Python path to ensure the correct environment is used.
 
-Use `smarttools refresh` to regenerate all wrapper scripts (e.g., after changing Python environments).
+Use `cmdforge refresh` to regenerate all wrapper scripts (e.g., after changing Python environments).
 
 ### Tool Name Validation
 
@@ -319,12 +336,12 @@ Tool names must:
 
 ## Tool Composition
 
-SmartTools are designed to chain together like any Unix command.
+CmdForge are designed to chain together like any Unix command.
 
 ### External Pipelines (Tool-to-Tool)
 
 ```bash
-# Chain multiple SmartTools
+# Chain multiple CmdForge
 cat logs.txt | log-errors | summarize | translate --lang Japanese
 
 # Mix with standard Unix tools
@@ -389,7 +406,7 @@ Optional fallbacks:
 
 ## Example Workflow
 
-1. Run `smarttools` to open UI
+1. Run `cmdforge` to open UI
 2. Select "Create" to create a new tool
 3. Fill in: name, description, output template
 4. Add arguments (e.g., `--max` with default `500`)

olddocs/EXAMPLES.md

@@ -1,13 +1,13 @@
 # Example Tools
 
-This document contains all 28 pre-built SmartTools with their full configurations.
+This document contains all 28 pre-built CmdForge with their full configurations.
 
 ## Quick Install
 
 ```bash
-# Install all example tools (from the SmartTools directory)
+# Install all example tools (from the CmdForge directory)
 python examples/install.py
-smarttools refresh
+cmdforge refresh
 ```
 
 ## Text Processing Tools
@@ -17,7 +17,7 @@ smarttools refresh
 Condense long documents to key points.
 
 ```yaml
-# ~/.smarttools/summarize/config.yaml
+# ~/.cmdforge/summarize/config.yaml
 name: summarize
 description: Condense long documents to key points
 arguments:
@@ -963,7 +963,7 @@ output: "{result}"
 
 ## Pipeline Recipes
 
-SmartTools chain together like Unix commands. Here are practical examples:
+CmdForge chain together like Unix commands. Here are practical examples:
 
 ### Development Workflows
 

olddocs/INSTALL.md

@@ -1,15 +1,15 @@
 # Installation Guide
 
-Complete installation instructions for SmartTools.
+Complete installation instructions for CmdForge.
 
 ## Quick Install
 
 ```bash
-git clone https://gitea.brrd.tech/rob/SmartTools.git
-cd SmartTools
+git clone https://gitea.brrd.tech/rob/CmdForge.git
+cd CmdForge
 pip install -e .
 export PATH="$HOME/.local/bin:$PATH"
-smarttools providers install
+cmdforge providers install
 ```
 
 ## Detailed Installation
@@ -32,11 +32,11 @@ brew install [email protected]
 python3 --version  # Should be 3.10 or higher
 ```
 
-### Step 2: Install SmartTools
+### Step 2: Install CmdForge
 
 ```bash
-git clone https://gitea.brrd.tech/rob/SmartTools.git
-cd SmartTools
+git clone https://gitea.brrd.tech/rob/CmdForge.git
+cd CmdForge
 pip install -e .
 ```
 
@@ -47,7 +47,7 @@ pip install -e ".[dev]"
 
 ### Step 3: Configure PATH
 
-SmartTools creates executable wrappers in `~/.local/bin/`. Add this to your shell config:
+CmdForge creates executable wrappers in `~/.local/bin/`. Add this to your shell config:
 
 **Bash (~/.bashrc):**
 ```bash
@@ -74,7 +74,7 @@ source ~/.bashrc  # or restart terminal
 You need at least one AI CLI tool. The easiest way is the interactive installer:
 
 ```bash
-smarttools providers install
+cmdforge providers install
 ```
 
 This guides you through installing and authenticating providers.
@@ -110,7 +110,7 @@ gemini  # Opens browser for Google sign-in
 ```bash
 curl -fsSL https://ollama.ai/install.sh | bash
 ollama pull llama3
-smarttools providers add ollama "ollama run llama3" -d "Local Llama 3"
+cmdforge providers add ollama "ollama run llama3" -d "Local Llama 3"
 ```
 
 See [PROVIDERS.md](PROVIDERS.md) for full provider setup instructions.
@@ -118,17 +118,17 @@ See [PROVIDERS.md](PROVIDERS.md) for full provider setup instructions.
 ### Step 5: Verify Installation
 
 ```bash
-# Check SmartTools is installed
-smarttools --version
+# Check CmdForge is installed
+cmdforge --version
 
 # List configured providers
-smarttools providers list
+cmdforge providers list
 
 # Check which providers are available
-smarttools providers check
+cmdforge providers check
 
 # Test with mock provider (no AI needed)
-echo "hello world" | smarttools run --provider mock
+echo "hello world" | cmdforge run --provider mock
 ```
 
 ### Step 6: Create Wrapper Scripts
@@ -136,7 +136,7 @@ echo "hello world" | smarttools run --provider mock
 After installation or any Python environment change:
 
 ```bash
-smarttools refresh
+cmdforge refresh
 ```
 
 This creates executable scripts in `~/.local/bin/` for all your tools.
@@ -147,18 +147,18 @@ This creates executable scripts in `~/.local/bin/` for all your tools.
 
 ```bash
 python examples/install.py
-smarttools refresh
+cmdforge refresh
 ```
 
 ### Manual Install
 
-Copy individual tool configs to `~/.smarttools/<toolname>/config.yaml`.
+Copy individual tool configs to `~/.cmdforge/<toolname>/config.yaml`.
 
 See [EXAMPLES.md](EXAMPLES.md) for all tool configurations.
 
 ## Troubleshooting
 
-### "smarttools: command not found"
+### "cmdforge: command not found"
 
 PATH is not configured. Add to your shell config:
 ```bash
@@ -168,14 +168,14 @@ export PATH="$HOME/.local/bin:$PATH"
 ### "Provider 'X' not found"
 
 1. Check provider is installed: `which claude` or `which opencode`
-2. Check provider is configured: `smarttools providers`
-3. Add missing provider: `smarttools providers add`
+2. Check provider is configured: `cmdforge providers`
+3. Add missing provider: `cmdforge providers add`
 
 ### "Permission denied" on tool execution
 
 Refresh wrapper scripts:
 ```bash
-smarttools refresh
+cmdforge refresh
 ```
 
 ### TUI doesn't start / looks broken
@@ -187,28 +187,28 @@ pip install urwid
 
 Ensure your terminal supports mouse (most modern terminals do).
 
-### Tools work with `smarttools run` but not directly
+### Tools work with `cmdforge run` but not directly
 
 The wrapper scripts may be outdated. Refresh them:
 ```bash
-smarttools refresh
+cmdforge refresh
 ```
 
 ### Python version mismatch
 
-If you have multiple Python versions, ensure SmartTools uses the right one:
+If you have multiple Python versions, ensure CmdForge uses the right one:
 ```bash
-python3.11 -m pip install smarttools
+python3.11 -m pip install cmdforge
 ```
 
 ## Uninstalling
 
 ```bash
 # Remove package
-pip uninstall smarttools
+pip uninstall cmdforge
 
 # Remove config and tools (optional)
-rm -rf ~/.smarttools
+rm -rf ~/.cmdforge
 
 # Remove wrapper scripts (optional)
 rm ~/.local/bin/{summarize,translate,fix-grammar,...}
@@ -217,8 +217,8 @@ rm ~/.local/bin/{summarize,translate,fix-grammar,...}
 ## Upgrading
 
 ```bash
-pip install --upgrade smarttools
-smarttools refresh
+pip install --upgrade cmdforge
+cmdforge refresh
 ```
 
 ## Directory Structure
@@ -226,7 +226,7 @@ smarttools refresh
 After installation:
 
 ```
-~/.smarttools/
+~/.cmdforge/
 ├── providers.yaml          # Provider configurations
 ├── summarize/
 │   └── config.yaml         # Tool config
@@ -236,7 +236,7 @@ After installation:
 └── ...
 
 ~/.local/bin/
-├── smarttools              # Main command
+├── cmdforge              # Main command
 ├── summarize               # Tool wrapper script
 ├── translate               # Tool wrapper script
 └── ...
@@ -246,4 +246,4 @@ After installation:
 
 1. [Set up providers](PROVIDERS.md)
 2. [Browse example tools](EXAMPLES.md)
-3. Run `smarttools ui` to create your first tool
+3. Run `cmdforge ui` to create your first tool

olddocs/META_TOOLS.md

@@ -0,0 +1,249 @@
+# Meta-Tools: Tools That Call Other Tools
+
+Meta-tools are CmdForge tools that can invoke other tools as steps in their workflow. This enables powerful composition and reuse of existing tools.
+
+## Step Type: `tool`
+
+A new step type `tool` allows calling another CmdForge tool from within a tool's workflow.
+
+### Manifest Format
+
+```yaml
+name: summarize-and-translate
+description: Summarize text then translate the summary
+version: 1.0.0
+category: Text
+
+steps:
+  - type: tool
+    tool: official/summarize        # Tool to call (owner/name or just name for local)
+    input: "{input}"                # What to pass as input (supports variable substitution)
+    args:                           # Optional arguments to pass to the tool
+      max_words: "100"
+    output_var: summary             # Variable to store the output
+
+  - type: tool
+    tool: official/translate
+    input: "{summary}"              # Use output from previous step
+    args:
+      target_language: "{language}" # Can use tool's own arguments
+    output_var: translated
+
+output: "{translated}"
+
+arguments:
+  - flag: "--language"
+    variable: language
+    default: "Spanish"
+    description: "Target language for translation"
+```
+
+### Resolution Order
+
+When resolving a tool reference in a `tool` step:
+
+1. **Fully qualified**: `owner/name` - looks up in registry or installed tools
+2. **Local tool**: Just `name` - checks local `~/.cmdforge/<name>/config.yaml` first
+3. **Registry fallback**: If not found locally, checks installed registry tools
+
+### Tool Step Properties
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `type` | Yes | Must be `"tool"` |
+| `tool` | Yes | Tool reference (owner/name or name) |
+| `input` | No | Input to pass to the tool (default: current `{input}`) |
+| `args` | No | Dictionary of arguments to pass |
+| `output_var` | Yes | Variable name to store the tool's output |
+| `provider` | No | Override provider for the called tool |
+
+### Execution
+
+When a `tool` step executes:
+
+1. Resolve the tool reference to find the tool definition
+2. Substitute variables in `input` and `args` values
+3. Execute the tool with the resolved input and arguments
+4. Capture the output in the specified `output_var`
+
+### Error Handling
+
+- If a called tool fails, the parent tool fails with an appropriate error
+- Tool not found errors include helpful installation suggestions
+- Circular dependencies are detected and prevented
+
+## Dependency Resolution
+
+### Declaring Dependencies
+
+Tools can declare their dependencies in the config:
+
+```yaml
+name: my-meta-tool
+dependencies:
+  - official/summarize
+  - official/translate@^1.0.0    # With version constraint
+```
+
+### CLI Integration
+
+```bash
+# Install a tool and its dependencies
+cmdforge install official/summarize-and-translate
+
+# Check if dependencies are satisfied
+cmdforge check my-meta-tool
+
+# Install missing dependencies
+cmdforge install --deps my-meta-tool
+```
+
+### Dependency Checking
+
+Before running a meta-tool, the runner verifies all dependencies are installed:
+
+```python
+def check_dependencies(tool: Tool) -> List[str]:
+    """Returns list of missing dependencies."""
+    missing = []
+    for dep in tool.dependencies:
+        if not is_tool_installed(dep):
+            missing.append(dep)
+    return missing
+```
+
+## Security Considerations
+
+1. **Sandboxing**: Called tools run in the same process context as the parent
+2. **Input validation**: All inputs are treated as untrusted strings
+3. **No shell execution**: Tool references cannot contain shell commands
+4. **Depth limit**: Maximum nesting depth (default: 10) prevents runaway recursion
+
+## Example: Multi-Step Analysis Pipeline
+
+```yaml
+name: code-review-pipeline
+description: Comprehensive code review using multiple specialized tools
+version: 1.0.0
+category: Developer
+
+dependencies:
+  - official/analyze-complexity
+  - official/find-bugs
+  - official/suggest-improvements
+
+steps:
+  # Step 1: Analyze code complexity
+  - type: tool
+    tool: official/analyze-complexity
+    input: "{input}"
+    output_var: complexity_report
+
+  # Step 2: Find potential bugs
+  - type: tool
+    tool: official/find-bugs
+    input: "{input}"
+    output_var: bug_report
+
+  # Step 3: Generate improvement suggestions based on findings
+  - type: tool
+    tool: official/suggest-improvements
+    input: |
+      ## Code:
+      {input}
+
+      ## Complexity Analysis:
+      {complexity_report}
+
+      ## Bug Report:
+      {bug_report}
+    output_var: suggestions
+
+output: |
+  # Code Review Results
+
+  ## Complexity Analysis
+  {complexity_report}
+
+  ## Potential Issues
+  {bug_report}
+
+  ## Improvement Suggestions
+  {suggestions}
+```
+
+## Implementation Notes
+
+### ToolStep Dataclass
+
+```python
+@dataclass
+class ToolStep:
+    """A step that calls another tool."""
+    tool: str                           # Tool reference (owner/name or name)
+    output_var: str                     # Variable to store output
+    input_template: str = "{input}"     # Input template
+    args: Dict[str, str] = field(default_factory=dict)
+    provider: Optional[str] = None      # Provider override
+
+    def to_dict(self) -> dict:
+        d = {
+            "type": "tool",
+            "tool": self.tool,
+            "output_var": self.output_var,
+        }
+        if self.input_template != "{input}":
+            d["input"] = self.input_template
+        if self.args:
+            d["args"] = self.args
+        if self.provider:
+            d["provider"] = self.provider
+        return d
+```
+
+### Execution Function
+
+```python
+def execute_tool_step(
+    step: ToolStep,
+    variables: dict,
+    depth: int = 0,
+    max_depth: int = 10
+) -> tuple[str, bool]:
+    """Execute a tool step by calling another tool."""
+    if depth >= max_depth:
+        return "", False  # Prevent infinite recursion
+
+    # Resolve the tool
+    try:
+        resolved = resolve_tool(step.tool)
+    except ToolNotFoundError:
+        print(f"Error: Tool '{step.tool}' not found", file=sys.stderr)
+        return "", False
+
+    # Prepare input
+    input_text = substitute_variables(step.input_template, variables)
+
+    # Prepare arguments
+    args = {}
+    for key, value in step.args.items():
+        args[key] = substitute_variables(value, variables)
+
+    # Run the tool
+    output, exit_code = run_tool(
+        tool=resolved.tool,
+        input_text=input_text,
+        custom_args=args,
+        provider_override=step.provider,
+        _depth=depth + 1  # Track nesting depth
+    )
+
+    return output, exit_code == 0
+```
+
+## Future Enhancements
+
+- **Parallel tool execution**: Run independent tool steps concurrently
+- **Conditional execution**: Skip steps based on conditions
+- **Tool aliases**: Define shorthand names for frequently used tools
+- **Caching**: Cache tool outputs for identical inputs

olddocs/PROJECT.md

@@ -0,0 +1,180 @@
+# CmdForge Project Overview
+
+This document provides a comprehensive overview of the CmdForge project structure, components, and how everything fits together.
+
+## What is CmdForge?
+
+CmdForge is a personal tool builder for AI-powered CLI commands. It consists of three main components:
+
+1. **CLI Tool** (`cmdforge`) - Create, manage, and run AI-powered command-line tools
+2. **Registry API** - REST API for publishing and discovering tools
+3. **Web UI** - Browser interface for the registry with docs, search, and user dashboard
+
+## Quick Reference
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| CLI | `src/cmdforge/cli.py` | Main entry point for `cmdforge` command |
+| Registry API | `src/cmdforge/registry/` | REST API for tool registry |
+| Web UI | `src/cmdforge/web/` | Flask web application |
+| Tool Storage | `~/.cmdforge/` | User's installed tools |
+| Database | `data/cmdforge.db` | SQLite with FTS5 search |
+
+## Architecture Diagrams
+
+See `docs/diagrams/` for visual representations:
+
+- **system-architecture.svg** - How components interact
+- **deployment-architecture.svg** - Production deployment setup
+- **source-organization.svg** - Code structure
+
+## Source Code Structure
+
+```
+src/cmdforge/
+├── cli.py              # Entry point, subcommand routing
+├── tool.py             # Tool dataclasses, YAML loading
+├── runner.py           # Step execution engine
+├── providers.py        # AI provider abstraction
+├── config.py           # Global configuration
+├── manifest.py         # Tool manifest handling
+│
+├── registry/           # Registry API Server
+│   ├── app.py          # Flask API application
+│   ├── db.py           # Database operations, FTS5 search
+│   ├── rate_limit.py   # API rate limiting
+│   ├── sync.py         # Git sync for tool submissions
+│   ├── categorize.py   # Auto-categorization
+│   └── similarity.py   # Similar tool recommendations
+│
+├── web/                # Web UI Application
+│   ├── app.py          # Flask web app, Sentry integration
+│   ├── routes.py       # Page routes and handlers
+│   ├── auth.py         # Password hashing, login/register
+│   ├── sessions.py     # Session management
+│   ├── docs_content.py # Documentation text content
+│   ├── seo.py          # Sitemap, robots.txt
+│   ├── filters.py      # Jinja template filters
+│   ├── templates/      # Jinja HTML templates
+│   └── static/         # CSS, JS, images
+│
+├── registry_client.py  # CLI client for registry API
+├── resolver.py         # Dependency resolution
+│
+├── ui.py               # TUI dispatcher
+├── ui_urwid.py         # urwid TUI implementation
+└── ui_snack.py         # newt/snack TUI fallback
+```
+
+## Database Schema
+
+SQLite database at `data/cmdforge.db`:
+
+| Table | Purpose |
+|-------|---------|
+| `publishers` | User accounts (username, email, password_hash) |
+| `tools` | Published tools (name, owner, description, config) |
+| `api_tokens` | Authentication tokens for API access |
+| `download_stats` | Tool download tracking |
+| `pageviews` | Analytics for tool detail pages |
+| `tools_fts` | Full-text search index (FTS5) |
+
+## API Endpoints
+
+Base URL: `/api/v1/`
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/tools` | GET | List/search tools |
+| `/tools/<owner>/<name>` | GET | Get tool details |
+| `/tools/<owner>/<name>` | POST | Publish tool (auth required) |
+| `/tools/<owner>/<name>/download` | POST | Record download |
+| `/me` | GET | Current user info |
+| `/tokens` | GET/POST | Manage API tokens |
+
+## Web Routes
+
+| Route | Purpose |
+|-------|---------|
+| `/` | Homepage with featured tools |
+| `/tools` | Tool browser with search |
+| `/tools/<owner>/<name>` | Tool detail page |
+| `/docs/*` | Documentation pages |
+| `/login`, `/register` | Authentication |
+| `/dashboard/*` | User dashboard, token management |
+
+## Key Files to Know
+
+### Configuration
+- `~/.cmdforge/providers.yaml` - AI provider configurations
+- `~/.cmdforge/config.yaml` - Global settings
+- `~/.cmdforge/<tool>/config.yaml` - Individual tool configs
+
+### Development
+- `pyproject.toml` - Package configuration
+- `pytest.ini` - Test configuration
+- `tailwind.config.js` - Tailwind CSS configuration
+
+### Documentation
+- `docs/REGISTRY.md` - Registry design document (comprehensive)
+- `docs/WEB_UI.md` - Web UI design document (comprehensive)
+- `wiki/Home.md` - User-facing wiki documentation
+- `CLAUDE.md` - Development guidance for AI assistants
+
+## Running the Project
+
+### Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run CLI
+python -m cmdforge.cli
+
+# Run web server (development)
+cd src/cmdforge/web
+flask run --port 5050
+```
+
+### Production
+
+```bash
+# Using gunicorn
+gunicorn -w 4 -b 0.0.0.0:5050 'cmdforge.web.app:create_app()'
+
+# Environment variables needed:
+# FLASK_ENV=production
+# SECRET_KEY=<your-secret-key>
+# SENTRY_DSN=<optional-sentry-dsn>
+# SITE_URL=https://your-domain.com
+```
+
+### systemd Service
+
+See `docs/DEPLOYMENT.md` for systemd service configuration.
+
+## Testing
+
+```bash
+# Run all tests
+pytest
+
+# Run specific test
+pytest tests/test_name.py::test_function
+
+# Run with coverage
+pytest --cov=cmdforge
+```
+
+## Design Documents
+
+For detailed design decisions and specifications:
+
+- **docs/REGISTRY.md** - Complete registry API design (Phases 1-8)
+- **docs/WEB_UI.md** - Complete web UI design (Phase 7)
+- **wiki/Home.md** - User documentation for CLI usage
+
+## Archive
+
+Old development discussions and diagrams are preserved in `archive/discussions/` for historical reference.

olddocs/PROVIDERS.md

@@ -1,6 +1,6 @@
 # Provider Setup Guide
 
-SmartTools works with any AI CLI tool that accepts input via stdin or arguments. This guide covers setup for the most popular providers.
+CmdForge works with any AI CLI tool that accepts input via stdin or arguments. This guide covers setup for the most popular providers.
 
 ## Provider Comparison
 
@@ -139,7 +139,7 @@ echo "Hello" | gemini --model gemini-2.5-flash
 The easiest way to install providers:
 
 ```bash
-smarttools providers install
+cmdforge providers install
 ```
 
 This interactive guide:
@@ -151,22 +151,22 @@ This interactive guide:
 ### List Providers
 
 ```bash
-smarttools providers list
+cmdforge providers list
 ```
 
 ### Check Availability
 
 ```bash
-smarttools providers check
+cmdforge providers check
 ```
 
 ### Add Custom Provider
 
 ```bash
-smarttools providers add myname "my-command --args" -d "Description"
+cmdforge providers add myname "my-command --args" -d "Description"
 ```
 
-Or edit `~/.smarttools/providers.yaml`:
+Or edit `~/.cmdforge/providers.yaml`:
 
 ```yaml
 providers:
@@ -242,9 +242,9 @@ cat file.txt | summarize --provider claude-opus
 
 ### "Provider 'X' not found"
 
-1. Check it's in your providers list: `smarttools providers`
+1. Check it's in your providers list: `cmdforge providers`
 2. Verify the command works: `echo "test" | <command>`
-3. Add it: `smarttools providers add`
+3. Add it: `cmdforge providers add`
 
 ### "Command 'X' not found"
 
@@ -273,8 +273,8 @@ echo "Say hello" | claude -p
 echo "Say hello" | ~/.opencode/bin/opencode run
 ```
 
-If it works directly but not in SmartTools, check:
-1. Provider command in `~/.smarttools/providers.yaml`
+If it works directly but not in CmdForge, check:
+1. Provider command in `~/.cmdforge/providers.yaml`
 2. Environment variables are expanded correctly
 
 ## Cost Optimization

olddocs/REGISTRY.md

@@ -1,7 +1,7 @@
-# SmartTools Registry Design
+# CmdForge Registry Design
 
 ## Purpose
-Build a centralized registry for SmartTools to enable discovery, publishing, dependency management, and future curation at scale.
+Build a centralized registry for CmdForge to enable discovery, publishing, dependency management, and future curation at scale.
 
 ## Terminology
 
@@ -9,20 +9,20 @@ Build a centralized registry for SmartTools to enable discovery, publishing, dep
 |------|------------|
 | **Tool definition** | The full YAML file in the registry (`config.yaml`) containing name, steps, arguments, etc. |
 | **Tool config** | The configuration within a tool definition (arguments, steps, provider settings) |
-| **smarttools.yaml** | Project manifest file declaring tool dependencies and overrides |
+| **cmdforge.yaml** | Project manifest file declaring tool dependencies and overrides |
 | **config.yaml** | The tool definition file, both in registry and when installed locally |
 | **Owner** | Immutable namespace slug identifying the publisher (e.g., `rob`, `alice`) |
 | **Publisher** | A registered user who can publish tools to the registry |
 | **Wrapper script** | Auto-generated bash script in `~/.local/bin/` that invokes a tool |
 
-**Canonical naming:** Use `SmartTools-Registry` (capitalized, hyphenated) for the repository name.
+**Canonical naming:** Use `CmdForge-Registry` (capitalized, hyphenated) for the repository name.
 
 ## Diagram References
-- System overview: `discussions/diagrams/smarttools-registry_rob_1.puml`
-- Data flows: `discussions/diagrams/smarttools-registry_rob_5.puml`
+- System overview: `discussions/diagrams/cmdforge-registry_rob_1.puml`
+- Data flows: `discussions/diagrams/cmdforge-registry_rob_5.puml`
 
 ## System Overview
-Users interact via the CLI and a future Web UI. Both call a Registry API hosted at `https://gitea.brrd.tech/api/v1` (future alias: `registry.smarttools.dev/api/v1`). The API syncs from a Gitea-backed registry repo and maintains a SQLite cache/search index.
+Users interact via the CLI and a future Web UI. Both call a Registry API hosted at `https://gitea.brrd.tech/api/v1` (future alias: `cmdforge.brrd.tech/api/v1`). The API syncs from a Gitea-backed registry repo and maintains a SQLite cache/search index.
 
 **Canonical API base path:** `https://gitea.brrd.tech/api/v1`
 
@@ -36,6 +36,8 @@ Core API endpoints:
 - `GET /api/v1/tools/{owner}/{name}/download?version=...`
 - `POST /api/v1/tools` (publish)
 - `GET /api/v1/categories`
+- `GET /api/v1/collections`
+- `GET /api/v1/collections/{name}`
 - `GET /api/v1/stats/popular`
 - `POST /api/v1/webhook/gitea`
 
@@ -166,7 +168,7 @@ tool = ToolSchema.parse(response['data'])  # May fail on new fields
 
 **Client version header:**
 ```
-X-SmartTools-Client: cli/1.2.0
+X-CmdForge-Client: cli/1.2.0
 ```
 Helps server track client versions for deprecation decisions.
 
@@ -181,8 +183,8 @@ If the cache is stale, the API can fall back to repo reads; a warning header may
 Support owner/name from day one:
 - Registry path: `tools/{owner}/{name}/config.yaml`
 - API URL: `/tools/{owner}/{name}`
-- Install: `smarttools registry install rob/summarize`
-- Shorthand: `smarttools registry install summarize` resolves to the official namespace.
+- Install: `cmdforge registry install rob/summarize`
+- Shorthand: `cmdforge registry install summarize` resolves to the official namespace.
 
 PR branches: `submit/{owner}/{name}/{version}`.
 
@@ -227,7 +229,7 @@ tools/
       README.md
 ```
 
-Tool files match the existing SmartTools format. Registry-specific metadata is kept under `registry:`. Deprecation is tool-defined and top-level:
+Tool files match the existing CmdForge format. Registry-specific metadata is kept under `registry:`. Deprecation is tool-defined and top-level:
 ```yaml
 name: summarize
 version: "1.2.0"
@@ -239,7 +241,125 @@ registry:
   downloads: 142
 ```
 
-**Schema compatibility note:** The current SmartTools config parser may reject unknown top-level keys like `deprecated`, `replacement`, and `registry`. Before implementing registry features:
+### Attribution and Source Fields
+
+Tools can include optional source attribution for provenance and licensing:
+
+```yaml
+name: summarize
+version: "1.2.0"
+description: "Summarize text using AI"
+
+# Attribution fields (optional)
+source:
+  type: original           # original, adapted, or imported
+  license: MIT             # SPDX license identifier
+  url: https://example.com/tool-repo
+  author: "Original Author"
+
+  # For adapted/imported tools
+  original_tool: other/original-summarize@1.0.0
+  changes: "Added French language support"
+```
+
+**Source types:**
+
+| Type | Description |
+|------|-------------|
+| `original` | Created from scratch by the publisher |
+| `adapted` | Based on another tool with modifications |
+| `imported` | Direct import of external tool (e.g., from npm/pip) |
+
+**License field:**
+- Uses SPDX identifiers: `MIT`, `Apache-2.0`, `GPL-3.0`, etc.
+- Required for registry publication
+- Validated against SPDX license list
+
+## Collections
+
+Collections are curated groups of tools that can be installed together with a single command.
+
+### Collection Structure
+
+Collections are defined in `collections/{name}.yaml`:
+
+```yaml
+name: text-processing-essentials
+display_name: "Text Processing Essentials"
+description: "Essential tools for text processing and manipulation"
+icon: "📝"
+
+tools:
+  - official/summarize
+  - official/translate
+  - official/fix-grammar
+  - official/simplify
+  - official/tone-shift
+
+# Optional
+curator: official
+tags: ["text", "nlp", "writing"]
+```
+
+### Collections API
+
+**List all collections:**
+```
+GET /api/v1/collections
+
+Response:
+{
+  "data": [
+    {
+      "name": "text-processing-essentials",
+      "display_name": "Text Processing Essentials",
+      "description": "Essential tools for text processing...",
+      "icon": "📝",
+      "tool_count": 5,
+      "curator": "official"
+    }
+  ],
+  "meta": {"page": 1, "per_page": 20, "total": 8}
+}
+```
+
+**Get collection details:**
+```
+GET /api/v1/collections/{name}
+
+Response:
+{
+  "data": {
+    "name": "text-processing-essentials",
+    "display_name": "Text Processing Essentials",
+    "description": "Essential tools for text processing...",
+    "icon": "📝",
+    "curator": "official",
+    "tools": [
+      {"owner": "official", "name": "summarize", "version": "1.2.0", ...},
+      {"owner": "official", "name": "translate", "version": "2.1.0", ...}
+    ]
+  }
+}
+```
+
+### CLI Commands
+
+```bash
+# List available collections
+cmdforge registry collections
+
+# View collection details
+cmdforge registry collections text-processing-essentials
+
+# Install all tools in a collection
+cmdforge registry install --collection text-processing-essentials
+
+# Show what would be installed (dry run)
+cmdforge registry install --collection text-processing-essentials --dry-run
+```
+
+**Schema compatibility note:** The current CmdForge config parser may reject unknown top-level keys like `deprecated`, `replacement`, and `registry`. Before implementing registry features:
 1. Update the YAML parser to ignore unknown keys (permissive mode)
 2. Or explicitly define these fields in the Tool dataclass with defaults
 3. Validate registry-specific fields only when publishing, not when running locally
@@ -346,7 +466,7 @@ When resolving a version constraint:
 ### Prerelease Handling
 
 - Prereleases are **not** returned for `*` or range constraints by default
-- To install prerelease: `smarttools registry install rob/[email protected]`
+- To install prerelease: `cmdforge registry install rob/[email protected]`
 - To allow prereleases in manifest: `version: ">=2.0.0-0"` (the `-0` suffix includes prereleases)
 
 ### Download Endpoint Version Selection
@@ -401,14 +521,14 @@ Response (404):
 ## Tool Resolution Order
 When a tool is invoked, the CLI searches in this order:
 
-1. **Local project**: `./.smarttools/<owner>/<name>/config.yaml` (or `./.smarttools/<name>/` for unnamespaced)
-2. **Global user**: `~/.smarttools/<owner>/<name>/config.yaml`
+1. **Local project**: `./.cmdforge/<owner>/<name>/config.yaml` (or `./.cmdforge/<name>/` for unnamespaced)
+2. **Global user**: `~/.cmdforge/<owner>/<name>/config.yaml`
 3. **Registry**: Fetch from API, install to global, then run
 4. **Error**: `Tool '<toolname>' not found`
 
 Step 3 only occurs if `auto_fetch_from_registry: true` in config (default: true).
 
-**Path convention:** Use `.smarttools/` (with leading dot) for both local and global to maintain consistency.
+**Path convention:** Use `.cmdforge/` (with leading dot) for both local and global to maintain consistency.
 
 Resolution also respects namespacing:
 - `summarize` → searches for any tool named `summarize`, prefers `official/summarize` if exists
@@ -422,7 +542,7 @@ The slug `official` is reserved for curated, high-quality tools maintained by th
 - If no `official/summarize`, falls back to most-downloaded tool named `summarize`
 - To avoid ambiguity, always use full `owner/name` in manifests
 
-Reserved slugs that cannot be registered: `official`, `admin`, `system`, `api`, `registry`, `smarttools`
+Reserved slugs that cannot be registered: `official`, `admin`, `system`, `api`, `registry`, `cmdforge`
 
 ## Auto-Fetch Behavior
 When enabled (`auto_fetch_from_registry: true`), missing tools are automatically fetched:
@@ -436,14 +556,14 @@ $ summarize < file.txt
 ```
 
 Behavior details:
-- Fetches latest stable version unless pinned in `smarttools.yaml`
-- Installs to `~/.smarttools/<owner>/<name>/`
+- Fetches latest stable version unless pinned in `cmdforge.yaml`
+- Installs to `~/.cmdforge/<owner>/<name>/`
 - Generates wrapper script in `~/.local/bin/`
 - Subsequent runs use local copy (no re-fetch)
 
 To disable (require explicit install):
 ```yaml
-# ~/.smarttools/config.yaml
+# ~/.cmdforge/config.yaml
 auto_fetch_from_registry: false
 ```
 
@@ -467,11 +587,11 @@ summarize < file.txt
 # Explicit owner form (always works)
 rob-summarize < file.txt
 
-# Or via smarttools run
-smarttools run rob/summarize < file.txt
+# Or via cmdforge run
+cmdforge run rob/summarize < file.txt
 ```
 
-## Project Manifest (smarttools.yaml)
+## Project Manifest (cmdforge.yaml)
 Defines tool dependencies with optional runtime overrides:
 ```
 name: my-ai-project
@@ -487,7 +607,7 @@ overrides:
 Overrides are applied at runtime and do not mutate installed tool configs.
 
 ## CLI Config and Tokens
-Global config lives in `~/.smarttools/config.yaml`:
+Global config lives in `~/.cmdforge/config.yaml`:
 ```yaml
 registry:
   url: https://gitea.brrd.tech/api/v1    # Must match canonical base path
@@ -540,7 +660,7 @@ Publishing uses registry accounts, not Gitea accounts:
 **Update flow (new version, not overwrite):**
 1. Developer modifies tool locally
 2. Bumps version in `config.yaml` (e.g., `1.2.0` → `1.3.0`)
-3. Runs `smarttools registry publish`
+3. Runs `cmdforge registry publish`
 4. New PR created for `1.3.0`
 5. Old version `1.2.0` remains available
 
@@ -548,7 +668,7 @@ Publishing uses registry accounts, not Gitea accounts:
 Publishers register on the registry website, not Gitea:
 
 **Registration flow:**
-1. User visits `https://gitea.brrd.tech/registry/register` (or future `registry.smarttools.dev`)
+1. User visits `https://gitea.brrd.tech/registry/register` (or future `cmdforge.brrd.tech`)
 2. Creates account with email + password + slug
 3. Receives verification email (optional in v1, but track `verified` status)
 4. Logs into dashboard at `/dashboard`
@@ -690,7 +810,7 @@ Dashboard login uses session cookies (not tokens) for browser auth:
 
 **Cookie settings:**
 ```python
-SESSION_COOKIE_NAME = 'smarttools_session'
+SESSION_COOKIE_NAME = 'cmdforge_session'
 SESSION_COOKIE_HTTPONLY = True      # Prevent JS access
 SESSION_COOKIE_SECURE = True        # HTTPS only in production
 SESSION_COOKIE_SAMESITE = 'Lax'     # CSRF protection
@@ -844,7 +964,7 @@ CREATE TABLE tool_tags (
 
 **CLI first-time publish flow:**
 ```bash
-$ smarttools registry publish
+$ cmdforge registry publish
 
 No registry account configured.
 
@@ -853,7 +973,7 @@ No registry account configured.
 3. Enter your token below
 
 Registry token: ********
-Token saved to ~/.smarttools/config.yaml
+Token saved to ~/.cmdforge/config.yaml
 
 Validating tool...
 ✓ config.yaml is valid
@@ -861,7 +981,7 @@ Validating tool...
 ✓ Version 1.0.0 not yet published
 
 Publishing rob/my-tool@1.0.0...
-✓ PR created: https://gitea.brrd.tech/rob/SmartTools-Registry/pulls/42
+✓ PR created: https://gitea.brrd.tech/rob/CmdForge-Registry/pulls/42
 
 Your tool is pending review. You'll receive an email when it's approved.
 ```
@@ -873,67 +993,67 @@ Full mapping of CLI commands to API calls:
 
 ```bash
 # Search for tools
-$ smarttools registry search <query> [--category=<cat>] [--limit=20]
+$ cmdforge registry search <query> [--category=<cat>] [--limit=20]
     → GET /api/v1/tools/search?q=<query>&category=<cat>&limit=20
 
 # Browse tools (TUI)
-$ smarttools registry browse [--category=<cat>]
+$ cmdforge registry browse [--category=<cat>]
     → GET /api/v1/tools?category=<cat>&page=1
     → GET /api/v1/categories
 
 # View tool details
-$ smarttools registry info <owner/name>
+$ cmdforge registry info <owner/name>
     → GET /api/v1/tools/<owner>/<name>
 
 # Install a tool
-$ smarttools registry install <owner/name> [--version=<ver>]
+$ cmdforge registry install <owner/name> [--version=<ver>]
     → GET /api/v1/tools/<owner>/<name>/download?version=<ver>&install=true
-    → Writes to ~/.smarttools/<owner>/<name>/config.yaml
+    → Writes to ~/.cmdforge/<owner>/<name>/config.yaml
     → Generates ~/.local/bin/<name> wrapper (or <owner>-<name> if collision)
 
 # Uninstall a tool
-$ smarttools registry uninstall <owner/name>
-    → Removes ~/.smarttools/<owner>/<name>/
+$ cmdforge registry uninstall <owner/name>
+    → Removes ~/.cmdforge/<owner>/<name>/
     → Removes wrapper script
 
 # Publish a tool
-$ smarttools registry publish [path] [--dry-run]
+$ cmdforge registry publish [path] [--dry-run]
     → POST /api/v1/tools (with registry token)
     → Returns PR URL
 
 # List my published tools
-$ smarttools registry my-tools
+$ cmdforge registry my-tools
     → GET /api/v1/me/tools (with registry token)
 
 # Update index cache
-$ smarttools registry update
+$ cmdforge registry update
     → GET /api/v1/index.json
-    → Writes to ~/.smarttools/registry/index.json
+    → Writes to ~/.cmdforge/registry/index.json
 ```
 
 ### Project Commands
 
 ```bash
-# Install project dependencies from smarttools.yaml
-$ smarttools install
-    → Reads ./smarttools.yaml
+# Install project dependencies from cmdforge.yaml
+$ cmdforge install
+    → Reads ./cmdforge.yaml
     → For each dependency:
         GET /api/v1/tools/<owner>/<name>/download?version=<constraint>&install=true
-    → Installs to ~/.smarttools/<owner>/<name>/
+    → Installs to ~/.cmdforge/<owner>/<name>/
 
-# Add a dependency to smarttools.yaml
-$ smarttools add <owner/name> [--version=<constraint>]
-    → Adds to ./smarttools.yaml dependencies
+# Add a dependency to cmdforge.yaml
+$ cmdforge add <owner/name> [--version=<constraint>]
+    → Adds to ./cmdforge.yaml dependencies
     → Runs install for that tool
 
 # Show project dependencies status
-$ smarttools deps
-    → Reads ./smarttools.yaml
+$ cmdforge deps
+    → Reads ./cmdforge.yaml
     → Shows installed status for each dependency
-    → Note: "smarttools list" is reserved for listing installed tools
+    → Note: "cmdforge list" is reserved for listing installed tools
 ```
 
-**Command naming note:** `smarttools list` already exists to list locally installed tools. Use `smarttools deps` to show project manifest dependencies.
+**Command naming note:** `cmdforge list` already exists to list locally installed tools. Use `cmdforge deps` to show project manifest dependencies.
 
 ### Flags available on most commands
 
@@ -1081,7 +1201,7 @@ def sync_from_repo_atomic():
 | Lock timeout | Skip this sync, next webhook will retry |
 
 ## Automated CI Validation
-PRs are validated automatically using SmartTools (dogfooding):
+PRs are validated automatically using CmdForge (dogfooding):
 
 ```
 PR Submitted
@@ -1121,16 +1241,16 @@ jobs:
       - name: Validate schema
         run: python scripts/validate_tool.py ${{ github.event.pull_request.head.sha }}
       - name: Security scan
-        run: smarttools run security-scanner < changed_files.txt
+        run: cmdforge run security-scanner < changed_files.txt
       - name: Check duplicates
-        run: smarttools run duplicate-detector < changed_files.txt
+        run: cmdforge run duplicate-detector < changed_files.txt
 ```
 
 ## Registry Repository Structure
-Full structure of the SmartTools-Registry repo:
+Full structure of the CmdForge-Registry repo:
 
 ```
-SmartTools-Registry/
+CmdForge-Registry/
 ├── README.md                        # Registry overview
 ├── CONTRIBUTING.md                  # How to submit tools
 ├── LICENSE
@@ -1151,6 +1271,11 @@ SmartTools-Registry/
 ├── categories/
 │   └── categories.yaml              # Category definitions
 │
+├── collections/                     # Curated tool collections
+│   ├── text-processing-essentials.yaml
+│   ├── developer-toolkit.yaml
+│   └── data-pipeline-basics.yaml
+│
 ├── index.json                       # Auto-generated search index
 │
 ├── .gitea/
@@ -1236,7 +1361,7 @@ CLI generates a persistent anonymous ID on first run:
 import uuid
 import os
 
-CONFIG_PATH = os.path.expanduser("~/.smarttools/config.yaml")
+CONFIG_PATH = os.path.expanduser("~/.cmdforge/config.yaml")
 
 def get_or_create_client_id():
     config = load_config()
@@ -1424,7 +1549,7 @@ def search_tools(q):
       "name": "bar",
       "suggestion": "Did you mean 'rob/bar'?"
     },
-    "docs_url": "https://registry.smarttools.dev/docs/errors#TOOL_NOT_FOUND"
+    "docs_url": "https://cmdforge.brrd.tech/docs/errors#TOOL_NOT_FOUND"
   }
 }
 ```
@@ -1482,17 +1607,17 @@ When `VALIDATION_ERROR` occurs, provide specific field errors:
         }
       ]
     },
-    "docs_url": "https://registry.smarttools.dev/docs/tool-format"
+    "docs_url": "https://cmdforge.brrd.tech/docs/tool-format"
   }
 }
 ```
 
 ### Dependency Resolution Failures
 
-When `smarttools install` fails on a manifest:
+When `cmdforge install` fails on a manifest:
 
 ```bash
-$ smarttools install
+$ cmdforge install
 
 Error: Could not resolve all dependencies
 
@@ -1511,7 +1636,7 @@ Suggestions:
 
 | Component Down | Fallback Behavior |
 |----------------|-------------------|
-| API server | CLI uses `~/.smarttools/registry/index.json` for search |
+| API server | CLI uses `~/.cmdforge/registry/index.json` for search |
 | Gitea repo | API serves from DB cache (may be stale) |
 | FTS5 index | Fall back to LIKE queries (slower but works) |
 | Network | Use locally installed tools, skip registry features |
@@ -1520,9 +1645,9 @@ Suggestions:
 
 ### Publishing UX
 
-- `smarttools registry publish --dry-run` validates locally and shows what would be submitted:
+- `cmdforge registry publish --dry-run` validates locally and shows what would be submitted:
   ```bash
-  $ smarttools registry publish --dry-run
+  $ cmdforge registry publish --dry-run
 
   Validating tool...
   ✓ config.yaml is valid
@@ -1559,7 +1684,7 @@ Suggestions:
 Long-running operations show progress:
 
 ```bash
-$ smarttools install
+$ cmdforge install
 
 Installing project dependencies...
   [1/3] rob/summarize@^1.0.0
@@ -1579,24 +1704,24 @@ Installing project dependencies...
 ```
 
 ```bash
-$ smarttools registry publish
+$ cmdforge registry publish
 
 Submitting rob/summarize@1.1.0...
   Validating... done ✓
   Uploading... done ✓
   Creating PR... done ✓
 
-✓ PR created: https://gitea.brrd.tech/rob/SmartTools-Registry/pulls/42
+✓ PR created: https://gitea.brrd.tech/rob/CmdForge-Registry/pulls/42
 
 Your tool is pending review. You'll receive an email when it's approved.
 ```
 
 ### TUI Browse
 
-`smarttools registry browse` opens a full-screen terminal UI:
+`cmdforge registry browse` opens a full-screen terminal UI:
 
 ```
-┌─ SmartTools Registry ───────────────────────────────────────┐
+┌─ CmdForge Registry ───────────────────────────────────────┐
 │ Search: [________________] [All Categories ▼] [Sort: Popular ▼] │
 ├─────────────────────────────────────────────────────────────┤
 │                                                             │
@@ -1634,9 +1759,9 @@ Your tool is pending review. You'll receive an email when it's approved.
 ### Project Initialization
 
 ```bash
-$ smarttools init
+$ cmdforge init
 
-Creating smarttools.yaml...
+Creating cmdforge.yaml...
 
 Project name [my-project]: my-ai-project
 Version [1.0.0]:
@@ -1652,7 +1777,7 @@ Added rob/summarize@^1.2.0
 
 Add tool (number, or Enter to finish):
 
-✓ Created smarttools.yaml
+✓ Created cmdforge.yaml
 
 name: my-ai-project
 version: "1.0.0"
@@ -1660,7 +1785,7 @@ dependencies:
   - name: rob/summarize
     version: "^1.2.0"
 
-Run 'smarttools install' to install dependencies.
+Run 'cmdforge install' to install dependencies.
 ```
 
 ### Accessibility
@@ -1676,7 +1801,7 @@ Run 'smarttools install' to install dependencies.
 ## Offline Cache
 Cache registry index locally:
 ```
-~/.smarttools/registry/index.json
+~/.cmdforge/registry/index.json
 ```
 Refresh when older than 24 hours; support `--offline` and `--refresh` flags.
 
@@ -1730,12 +1855,14 @@ The registry includes a full website, not just an API:
 
 **Site structure:**
 ```
-registry.smarttools.dev (or gitea.brrd.tech/registry)
+cmdforge.brrd.tech (or gitea.brrd.tech/registry)
 ├── /                           # Landing page
 ├── /tools                      # Browse all tools
 ├── /tools/{owner}/{name}       # Tool detail page
 ├── /categories                 # Browse by category
 ├── /categories/{name}          # Tools in category
+├── /collections                # Browse curated collections
+├── /collections/{name}         # Collection detail page
 ├── /search?q=...               # Search results
 ├── /docs                       # Documentation
 │   ├── /docs/getting-started
@@ -1843,9 +1970,9 @@ def render_readme_safe(readme_raw: str) -> str:
 ## Implementation Phases
 
 ### Phase 1: Foundation
-- Define `smarttools.yaml` manifest format
+- Define `cmdforge.yaml` manifest format
 - Implement tool resolution order (local → global → registry)
-- Create SmartTools-Registry repo on Gitea (bootstrap)
+- Create CmdForge-Registry repo on Gitea (bootstrap)
 - Add 3-5 example tools to seed the registry
 
 ### Phase 2: Core Backend
@@ -1856,22 +1983,22 @@ def render_readme_safe(readme_raw: str) -> str:
 - Set up HMAC verification
 
 ### Phase 3: CLI Commands
-- `smarttools registry search`
-- `smarttools registry install`
-- `smarttools registry info`
-- `smarttools registry browse` (TUI)
+- `cmdforge registry search`
+- `cmdforge registry install`
+- `cmdforge registry info`
+- `cmdforge registry browse` (TUI)
 - Local index caching
 
 ### Phase 4: Publishing
 - Publisher registration (web UI)
 - Token management
-- `smarttools registry publish` command
+- `cmdforge registry publish` command
 - PR creation via Gitea API
 - CI validation workflows
 
 ### Phase 5: Project Dependencies
-- `smarttools install` (from manifest)
-- `smarttools add` command
+- `cmdforge install` (from manifest)
+- `cmdforge add` command
 - Runtime override application
 - Dependency resolution
 

olddocs/WEB_UI.md

@@ -1,10 +1,10 @@
-# SmartTools Web UI Design
+# CmdForge Web UI Design
 
 ## Purpose
-Deliver a professional web front-end that explains SmartTools, helps users discover tools, and supports a collaborative ecosystem. The site should drive sustainable revenue without undermining trust or usability.
+Deliver a professional web front-end that explains CmdForge, helps users discover tools, and supports a collaborative ecosystem. The site should drive sustainable revenue without undermining trust or usability.
 
 ## Mission Alignment
-This web UI serves the broader SmartTools mission: to provide a **universally accessible development ecosystem** that empowers regular people to collaborate and build upon each other's progress rather than compete. Revenue generated supports:
+This web UI serves the broader CmdForge mission: to provide a **universally accessible development ecosystem** that empowers regular people to collaborate and build upon each other's progress rather than compete. Revenue generated supports:
 - Maintaining and expanding the project
 - Future hosting of AI models for users with less access to paid services
 - Building a sustainable, community-first platform
@@ -131,14 +131,14 @@ Use an 8px base grid for consistent spacing:
 
 ### Landing Page (`/`)
 
-**Purpose:** Convert visitors to users by clearly communicating SmartTools' value proposition and providing immediate paths to explore.
+**Purpose:** Convert visitors to users by clearly communicating CmdForge' value proposition and providing immediate paths to explore.
 
-**Reference mockup:** `discussions/diagrams/smarttools-registry_rob_6.svg`
+**Reference mockup:** `discussions/diagrams/cmdforge-registry_rob_6.svg`
 
 #### Section 1: Hero (Above the Fold)
 ```
 ┌─────────────────────────────────────────────────────────────────┐
-│  [SmartTools]  Docs  Tutorials  Registry  Community  About  🔍  │
+│  [CmdForge]  Docs  Tutorials  Registry  Community  About  🔍  │
 ├─────────────────────────────────────────────────────────────────┤
 │                                                                  │
 │    Build Custom AI Commands in YAML                              │
@@ -147,7 +147,7 @@ Use an 8px base grid for consistent spacing:
 │    provider. Provider-agnostic and composable.                   │
 │                                                                  │
 │    ┌──────────────────────────────────────────────────────┐     │
-│    │ $ pip install smarttools && smarttools init          │ [📋]│
+│    │ $ pip install cmdforge && cmdforge init          │ [📋]│
 │    └──────────────────────────────────────────────────────┘     │
 │                                                                  │
 │    [Get Started]  [View Tutorials]                               │
@@ -158,7 +158,7 @@ Use an 8px base grid for consistent spacing:
 **Content:**
 - **Headline:** "Build Custom AI Commands in YAML" (benefit-focused, differentiating)
 - **Subheadline:** "Create Unix-style pipeable tools that work with any AI provider. Provider-agnostic and composable for ultimate flexibility."
-- **Install snippet:** `pip install smarttools && smarttools init` with copy button
+- **Install snippet:** `pip install cmdforge && cmdforge init` with copy button
 - **Primary CTA:** "Get Started" → links to `/docs/getting-started` (indigo background)
 - **Secondary CTA:** "View Tutorials" → links to `/tutorials` (outlined, cyan border)
 
@@ -167,10 +167,10 @@ Use an 8px base grid for consistent spacing:
 - Maximum content width: 1100px centered
 - Install snippet: monospace font, light gray background (#E0E0E0), copy icon on right
 
-#### Section 2: Three Pillars (Why SmartTools?)
+#### Section 2: Three Pillars (Why CmdForge?)
 ```
 ┌─────────────────────────────────────────────────────────────────┐
-│  Why SmartTools?                                                 │
+│  Why CmdForge?                                                 │
 ├──────────────────┬──────────────────┬────────────────────────────┤
 │   [✓] Easy       │   [⚡] Powerful   │   [👥] Community           │
 │                  │                  │                            │
@@ -267,7 +267,7 @@ Use an 8px base grid for consistent spacing:
 #### Section 6: Footer Ad Zone (Optional)
 ```
 ┌─────────────────────────────────────────────────────────────────┐
-│  [Advertisement: Support SmartTools Development]                 │
+│  [Advertisement: Support CmdForge Development]                 │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
@@ -279,12 +279,12 @@ Use an 8px base grid for consistent spacing:
 #### Section 7: Footer
 ```
 ┌─────────────────────────────────────────────────────────────────┐
-│  SmartTools                                                      │
+│  CmdForge                                                      │
 │  ─────────────────────────────────────────────────────────────  │
 │  Docs  |  Registry  |  Community  |  About  |  Donate           │
 │  Privacy  |  Terms  |  GitHub  |  Twitter                        │
 │                                                                  │
-│  © 2025 SmartTools. Open source under MIT License.              │
+│  © 2025 CmdForge. Open source under MIT License.              │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
@@ -511,7 +511,7 @@ Use an 8px base grid for consistent spacing:
 │  ⬇ 1,234 downloads                    │
 │                                       │
 │  ┌─────────────────────────────────┐  │
-│  │ smarttools run owner/tool       │  │
+│  │ cmdforge run owner/tool       │  │
 │  └─────────────────────────────────┘  │
 └───────────────────────────────────────┘
 ```
@@ -637,7 +637,7 @@ Registry > owner > tool-name > v1.2.0
 
 **Inline Code:**
 ```html
-<code>smarttools run foo</code>
+<code>cmdforge run foo</code>
 ```
 - Background: Light gray (#F3F4F6)
 - Font: Monospace
@@ -1011,14 +1011,14 @@ Publisher dashboard uses auth endpoints:
 
 Landing page:
 ```html
-<title>SmartTools - Build Custom AI Commands in YAML</title>
+<title>CmdForge - Build Custom AI Commands in YAML</title>
 <meta name="description" content="Create Unix-style pipeable tools that work with any AI provider. Provider-agnostic, composable, and community-driven.">
-<meta name="keywords" content="ai cli tools, yaml automation, ai commands, smarttools">
+<meta name="keywords" content="ai cli tools, yaml automation, ai commands, cmdforge">
 ```
 
 Tool detail page:
 ```html
-<title>{tool-name} by {owner} - SmartTools Registry</title>
+<title>{tool-name} by {owner} - CmdForge Registry</title>
 <meta name="description" content="{tool description, max 160 chars}">
 ```
 
@@ -1036,7 +1036,7 @@ Tool detail page:
     "@type": "Person",
     "name": "owner-name"
   },
-  "downloadUrl": "https://registry.smarttools.dev/tools/owner/summarize",
+  "downloadUrl": "https://cmdforge.brrd.tech/tools/owner/summarize",
   "softwareVersion": "1.2.0",
   "aggregateRating": {
     "@type": "AggregateRating",
@@ -1051,12 +1051,12 @@ Tool detail page:
 {
   "@context": "https://schema.org",
   "@type": "Organization",
-  "name": "SmartTools",
-  "url": "https://smarttools.dev",
-  "logo": "https://smarttools.dev/logo.png",
+  "name": "CmdForge",
+  "url": "https://cmdforge.dev",
+  "logo": "https://cmdforge.dev/logo.png",
   "sameAs": [
-    "https://github.com/your-org/smarttools",
-    "https://twitter.com/smarttools"
+    "https://github.com/your-org/cmdforge",
+    "https://twitter.com/cmdforge"
   ]
 }
 ```
@@ -1066,7 +1066,7 @@ Tool detail page:
 {
   "@context": "https://schema.org",
   "@type": "TechArticle",
-  "headline": "Getting Started with SmartTools",
+  "headline": "Getting Started with CmdForge",
   "author": {"@type": "Person", "name": "Author Name"},
   "datePublished": "2025-01-15",
   "dateModified": "2025-01-20"
@@ -1077,18 +1077,18 @@ Tool detail page:
 
 ```html
 <!-- Open Graph -->
-<meta property="og:title" content="SmartTools - AI CLI Tools">
+<meta property="og:title" content="CmdForge - AI CLI Tools">
 <meta property="og:description" content="Build custom AI commands...">
-<meta property="og:image" content="https://smarttools.dev/og-image.png">
-<meta property="og:url" content="https://smarttools.dev">
+<meta property="og:image" content="https://cmdforge.dev/og-image.png">
+<meta property="og:url" content="https://cmdforge.dev">
 <meta property="og:type" content="website">
 
 <!-- Twitter Card -->
 <meta name="twitter:card" content="summary_large_image">
-<meta name="twitter:site" content="@smarttools">
-<meta name="twitter:title" content="SmartTools">
+<meta name="twitter:site" content="@cmdforge">
+<meta name="twitter:title" content="CmdForge">
 <meta name="twitter:description" content="Build custom AI commands...">
-<meta name="twitter:image" content="https://smarttools.dev/twitter-card.png">
+<meta name="twitter:image" content="https://cmdforge.dev/twitter-card.png">
 ```
 
 ### Sitemap
@@ -1104,12 +1104,12 @@ Auto-generate `sitemap.xml`:
 <?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
   <url>
-    <loc>https://smarttools.dev/</loc>
+    <loc>https://cmdforge.dev/</loc>
     <priority>1.0</priority>
     <changefreq>daily</changefreq>
   </url>
   <url>
-    <loc>https://smarttools.dev/tools</loc>
+    <loc>https://cmdforge.dev/tools</loc>
     <priority>0.9</priority>
     <changefreq>daily</changefreq>
   </url>
@@ -1129,7 +1129,7 @@ Disallow: /register
 Disallow: /dashboard
 Disallow: /api/
 
-Sitemap: https://smarttools.dev/sitemap.xml
+Sitemap: https://cmdforge.dev/sitemap.xml
 ```
 
 ### Canonical URLs
@@ -1297,11 +1297,11 @@ The web UI consumes these existing API endpoints:
 
 ## Diagram References
 
-- Landing page mockup: `discussions/diagrams/smarttools-registry_rob_6.svg`
-- System overview: `discussions/diagrams/smarttools-registry_rob_1.puml`
-- Data flows: `discussions/diagrams/smarttools-registry_rob_5.puml`
-- Web UI strategy: `discussions/diagrams/smarttools-web-ui-strategy.puml`
-- UI visual strategy: `discussions/diagrams/smarttools-web-ui-visual-strategy.puml`
+- Landing page mockup: `discussions/diagrams/cmdforge-registry_rob_6.svg`
+- System overview: `discussions/diagrams/cmdforge-registry_rob_1.puml`
+- Data flows: `discussions/diagrams/cmdforge-registry_rob_5.puml`
+- Web UI strategy: `discussions/diagrams/cmdforge-web-ui-strategy.puml`
+- UI visual strategy: `discussions/diagrams/cmdforge-web-ui-visual-strategy.puml`
 
 ## Deployment Guide
 
@@ -1315,8 +1315,8 @@ The web UI consumes these existing API endpoints:
 
 ```bash
 # Clone the repository
-git clone https://gitea.brrd.tech/rob/SmartTools.git
-cd SmartTools
+git clone https://gitea.brrd.tech/rob/CmdForge.git
+cd CmdForge
 
 # Create virtual environment
 python3 -m venv venv
@@ -1326,7 +1326,7 @@ source venv/bin/activate
 pip install -e ".[registry]"
 
 # Run the web server
-python -m smarttools.web.app
+python -m cmdforge.web.app
 ```
 
 The server will start on `http://localhost:5000`.
@@ -1337,47 +1337,47 @@ The server will start on `http://localhost:5000`.
 
 ```bash
 # Required
-export SMARTTOOLS_REGISTRY_DB=/path/to/registry.db
+export CMDFORGE_REGISTRY_DB=/path/to/registry.db
 export PORT=5050
 
 # Optional
-export SMARTTOOLS_ENV=production  # Enables secure cookies
-export SMARTTOOLS_SHOW_ADS=true   # Enable ad placeholders
+export CMDFORGE_ENV=production  # Enables secure cookies
+export CMDFORGE_SHOW_ADS=true   # Enable ad placeholders
 ```
 
 #### 2. Database Location
 
-By default, the registry uses `~/.smarttools/registry.db`. For production:
+By default, the registry uses `~/.cmdforge/registry.db`. For production:
 
 ```bash
 # Create dedicated directory
-mkdir -p /var/lib/smarttools
-export SMARTTOOLS_REGISTRY_DB=/var/lib/smarttools/registry.db
+mkdir -p /var/lib/cmdforge
+export CMDFORGE_REGISTRY_DB=/var/lib/cmdforge/registry.db
 ```
 
 **Note**: If using a merged filesystem (e.g., mergerfs), store the database on a single disk or in `/tmp` to avoid SQLite WAL mode issues:
 
 ```bash
-export SMARTTOOLS_REGISTRY_DB=/tmp/smarttools-registry/registry.db
+export CMDFORGE_REGISTRY_DB=/tmp/cmdforge-registry/registry.db
 ```
 
 #### 3. Running with systemd
 
-Create `/etc/systemd/system/smarttools-registry.service`:
+Create `/etc/systemd/system/cmdforge-registry.service`:
 
 ```ini
 [Unit]
-Description=SmartTools Registry Web Server
+Description=CmdForge Registry Web Server
 After=network.target
 
 [Service]
 Type=simple
-User=smarttools
-WorkingDirectory=/opt/smarttools
-Environment=SMARTTOOLS_REGISTRY_DB=/var/lib/smarttools/registry.db
+User=cmdforge
+WorkingDirectory=/opt/cmdforge
+Environment=CMDFORGE_REGISTRY_DB=/var/lib/cmdforge/registry.db
 Environment=PORT=5050
-Environment=SMARTTOOLS_ENV=production
-ExecStart=/opt/smarttools/venv/bin/python -m smarttools.web.app
+Environment=CMDFORGE_ENV=production
+ExecStart=/opt/cmdforge/venv/bin/python -m cmdforge.web.app
 Restart=always
 RestartSec=5
 
@@ -1387,8 +1387,8 @@ WantedBy=multi-user.target
 
 ```bash
 sudo systemctl daemon-reload
-sudo systemctl enable smarttools-registry
-sudo systemctl start smarttools-registry
+sudo systemctl enable cmdforge-registry
+sudo systemctl start cmdforge-registry
 ```
 
 #### 4. Reverse Proxy (nginx)
@@ -1396,7 +1396,7 @@ sudo systemctl start smarttools-registry
 ```nginx
 server {
     listen 80;
-    server_name registry.smarttools.dev;
+    server_name cmdforge.brrd.tech;
 
     location / {
         proxy_pass http://127.0.0.1:5050;
@@ -1407,7 +1407,7 @@ server {
     }
 
     location /static {
-        alias /opt/smarttools/src/smarttools/web/static;
+        alias /opt/cmdforge/src/cmdforge/web/static;
         expires 1y;
         add_header Cache-Control "public, immutable";
     }
@@ -1417,7 +1417,7 @@ server {
 #### 5. SSL with Certbot
 
 ```bash
-sudo certbot --nginx -d registry.smarttools.dev
+sudo certbot --nginx -d cmdforge.brrd.tech
 ```
 
 ### Tailwind CSS Build
@@ -1429,8 +1429,8 @@ The CSS is pre-built and committed. To rebuild after changes:
 npm install
 
 # Build for production
-npx tailwindcss -i src/smarttools/web/static/css/input.css \
-                -o src/smarttools/web/static/css/main.css \
+npx tailwindcss -i src/cmdforge/web/static/css/input.css \
+                -o src/cmdforge/web/static/css/main.css \
                 --minify
 ```
 
@@ -1447,7 +1447,7 @@ curl http://localhost:5050/api/v1/tools
 |-------|----------|
 | `disk I/O error` | Move database to non-merged filesystem |
 | Port already in use | Change PORT environment variable |
-| 500 errors | Check `/tmp/smarttools.log` for stack traces |
+| 500 errors | Check `/tmp/cmdforge.log` for stack traces |
 | Static files not loading | Verify static folder path in deployment |
 
 ## Future Considerations (Phase 8+)

package.json

@@ -1,9 +1,9 @@
 {
-  "name": "smarttools-web",
+  "name": "cmdforge-web",
   "private": true,
   "scripts": {
-    "css:build": "tailwindcss -i src/smarttools/web/static/src/input.css -o src/smarttools/web/static/css/main.css --minify",
-    "css:watch": "tailwindcss -i src/smarttools/web/static/src/input.css -o src/smarttools/web/static/css/main.css --watch"
+    "css:build": "tailwindcss -i src/cmdforge/web/static/src/input.css -o src/cmdforge/web/static/css/main.css --minify",
+    "css:watch": "tailwindcss -i src/cmdforge/web/static/src/input.css -o src/cmdforge/web/static/css/main.css --watch"
   },
   "devDependencies": {
     "tailwindcss": "^3.4.19"

patches/UPSTREAM_ISSUE.md

@@ -0,0 +1,80 @@
+# PySide6 6.7+ Compatibility Issue: setSelectionArea API Change
+
+## Issue
+
+When using NodeGraphQt-QuiltiX-fork with PySide6 6.7+, dragging a rubber band selection in the node graph causes repeated TypeError exceptions:
+
+```
+TypeError: 'PySide6.QtWidgets.QGraphicsScene.setSelectionArea' called with wrong argument types:
+  PySide6.QtWidgets.QGraphicsScene.setSelectionArea(QPainterPath, ItemSelectionMode)
+Supported signatures:
+  PySide6.QtWidgets.QGraphicsScene.setSelectionArea(PySide6.QtGui.QPainterPath, PySide6.QtGui.QTransform)
+  PySide6.QtWidgets.QGraphicsScene.setSelectionArea(PySide6.QtGui.QPainterPath, PySide6.QtCore.Qt.ItemSelectionOperation = Instance(Qt.ReplaceSelection), PySide6.QtCore.Qt.ItemSelectionMode = Instance(Qt.IntersectsItemShape), PySide6.QtGui.QTransform = Default(QTransform))
+```
+
+## Root Cause
+
+The `QGraphicsScene.setSelectionArea()` method signature changed in PySide6 6.7. The old signature allowed:
+
+```python
+setSelectionArea(path, mode)  # mode = Qt.ItemSelectionMode
+```
+
+The new signature requires:
+
+```python
+setSelectionArea(path, operation, mode)  # operation = Qt.ItemSelectionOperation
+```
+
+## Affected File
+
+`NodeGraphQt/widgets/viewer.py` line 524-526
+
+## Current Code
+
+```python
+self.scene().setSelectionArea(
+    path, QtCore.Qt.IntersectsItemShape
+)
+```
+
+## Fix
+
+```python
+self.scene().setSelectionArea(
+    path, QtCore.Qt.ReplaceSelection,
+    QtCore.Qt.IntersectsItemShape
+)
+```
+
+## Environment
+
+- Python: 3.12
+- PySide6: 6.6.3.1 (installed by NodeGraphQt-QuiltiX-fork, but issue affects 6.7+)
+- NodeGraphQt-QuiltiX-fork: 0.7.0
+
+## Workaround
+
+Apply this patch after installation:
+
+```python
+# In viewer.py, change line 524-526 from:
+self.scene().setSelectionArea(
+    path, QtCore.Qt.IntersectsItemShape
+)
+
+# To:
+self.scene().setSelectionArea(
+    path, QtCore.Qt.ReplaceSelection,
+    QtCore.Qt.IntersectsItemShape
+)
+```
+
+## Related
+
+This issue may also exist in:
+- Original NodeGraphQt
+- OdenGraphQt
+- Other forks
+
+The fix is backward compatible with older PySide6 versions that support the 3-argument signature.

patches/nodegraphqt_pyside6_compat.patch

@@ -0,0 +1,13 @@
+--- a/NodeGraphQt/widgets/viewer.py
++++ b/NodeGraphQt/widgets/viewer.py
+@@ -521,8 +521,10 @@ class NodeViewer(QtWidgets.QGraphicsView):
+                 path = QtGui.QPainterPath()
+                 path.addRect(map_rect)
+                 self._rubber_band.setGeometry(rect)
++                # PySide6 6.7+ requires ItemSelectionOperation parameter
+                 self.scene().setSelectionArea(
+-                    path, QtCore.Qt.IntersectsItemShape
++                    path, QtCore.Qt.ReplaceSelection,
++                    QtCore.Qt.IntersectsItemShape
+                 )
+                 self.scene().update(map_rect)

pyproject.toml

@@ -3,9 +3,9 @@ requires = ["setuptools>=61.0", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
-name = "smarttools"
+name = "cmdforge"
 version = "0.1.0"
-description = "A lightweight personal tool builder for AI-powered CLI commands"
+description = "Build custom AI-powered CLI commands in YAML"
 readme = "README.md"
 license = {text = "MIT"}
 requires-python = ">=3.10"
@@ -32,35 +32,41 @@ classifiers = [
 dependencies = [
     "PyYAML>=6.0",
     "requests>=2.28",
+    "PySide6>=6.5",
 ]
 
 [project.optional-dependencies]
-tui = [
-    "urwid>=2.1.0",
-]
 dev = [
     "pytest>=7.0",
     "pytest-cov>=4.0",
-    "urwid>=2.1.0",
 ]
 registry = [
     "Flask>=2.3",
     "argon2-cffi>=21.0",
+    "sentry-sdk[flask]>=1.0",
+    "gunicorn>=21.0",
+]
+flow = [
+    "NodeGraphQt-QuiltiX-fork[pyside6]>=0.7.0",
+    "setuptools",  # Required for distutils compatibility
 ]
 all = [
-    "urwid>=2.1.0",
     "Flask>=2.3",
     "argon2-cffi>=21.0",
+    "sentry-sdk[flask]>=1.0",
+    "gunicorn>=21.0",
+    "NodeGraphQt-QuiltiX-fork[pyside6]>=0.7.0",
+    "setuptools",
 ]
 
 [project.scripts]
-smarttools = "smarttools.cli:main"
+cmdforge = "cmdforge.cli:main"
 
 [project.urls]
-Homepage = "https://gitea.brrd.tech/rob/smarttools"
-Documentation = "https://gitea.brrd.tech/rob/smarttools#readme"
-Repository = "https://gitea.brrd.tech/rob/smarttools.git"
-Issues = "https://gitea.brrd.tech/rob/smarttools/issues"
+Homepage = "https://cmdforge.brrd.tech"
+Documentation = "https://cmdforge.brrd.tech/docs"
+Repository = "https://gitea.brrd.tech/rob/CmdForge.git"
+Issues = "https://gitea.brrd.tech/rob/CmdForge/issues"
 
 [tool.setuptools.packages.find]
 where = ["src"]

registry-seeds/official/code-review/README.md

@@ -0,0 +1,21 @@
+# code-review
+
+Review code for issues, risks, and improvements.
+
+## Usage
+
+```bash
+code-review --language python --focus bugs,security --severity medium < app.py
+```
+
+## Arguments
+
+- `--language`: Programming language or `auto`.
+- `--focus`: Comma-separated focus areas (e.g., `bugs,security,performance`).
+- `--severity`: Minimum severity level (`low`, `medium`, `high`).
+
+## Examples
+
+```bash
+cat main.go | code-review --language go --focus performance --severity high
+```

registry-seeds/official/code-review/config.yaml

@@ -0,0 +1,37 @@
+name: code-review
+version: "1.0.0"
+description: "Review code for issues and improvements"
+category: code-analysis
+tags:
+  - code
+  - review
+  - quality
+arguments:
+  - name: language
+    flag: "--language"
+    default: "auto"
+    description: "Programming language (e.g., python, javascript, go)"
+  - name: focus
+    flag: "--focus"
+    default: "bugs,security,performance"
+    description: "Comma-separated focus areas"
+  - name: severity
+    flag: "--severity"
+    default: "medium"
+    description: "Minimum severity: low, medium, high"
+steps:
+  - type: prompt
+    provider: "claude"
+    template: |
+      You are a senior code reviewer.
+      Language: {language}
+      Focus areas: {focus}
+      Minimum severity: {severity}
+
+      Review the following code. Identify issues, risks, and improvements.
+      Provide a concise, prioritized list with suggestions.
+
+      Code:
+      {input}
+    output_var: review
+output: "{review}"

registry-seeds/official/explain/README.md

@@ -0,0 +1,20 @@
+# explain
+
+Explain code or concepts clearly with adjustable audience and format.
+
+## Usage
+
+```bash
+explain --audience beginner --format step-by-step < snippet.txt
+```
+
+## Arguments
+
+- `--audience`: Audience level (`beginner`, `general`, `expert`).
+- `--format`: Output format (`paragraph`, `bullet`, `step-by-step`).
+
+## Examples
+
+```bash
+echo "Explain recursion" | explain --audience general --format bullet
+```

registry-seeds/official/explain/config.yaml

@@ -0,0 +1,29 @@
+name: explain
+version: "1.0.0"
+description: "Explain code or concepts clearly"
+category: education
+tags:
+  - explanation
+  - learning
+  - code
+arguments:
+  - name: audience
+    flag: "--audience"
+    default: "general"
+    description: "Audience level: beginner, general, expert"
+  - name: format
+    flag: "--format"
+    default: "paragraph"
+    description: "Output format: paragraph, bullet, or step-by-step"
+steps:
+  - type: prompt
+    provider: "claude"
+    template: |
+      You are a clear and concise explainer.
+      Audience: {audience}
+      Format: {format}
+
+      Explain the following content:
+      {input}
+    output_var: explanation
+output: "{explanation}"

registry-seeds/official/summarize/README.md

@@ -0,0 +1,20 @@
+# summarize
+
+Summarize text using AI. Designed for quick overviews, briefs, or executive summaries.
+
+## Usage
+
+```bash
+summarize --max-length 200 --style neutral < input.txt
+```
+
+## Arguments
+
+- `--max-length`: Maximum length of the summary in words. Default: `200`.
+- `--style`: Summary style. Options: `neutral`, `bullet`, `executive`.
+
+## Examples
+
+```bash
+cat report.txt | summarize --max-length 120 --style executive
+```

registry-seeds/official/summarize/config.yaml

@@ -0,0 +1,29 @@
+name: summarize
+version: "1.0.0"
+description: "Summarize text using AI"
+category: text-processing
+tags:
+  - summarization
+  - text
+  - ai
+arguments:
+  - name: max_length
+    flag: "--max-length"
+    default: "200"
+    description: "Maximum length of the summary in words"
+  - name: style
+    flag: "--style"
+    default: "neutral"
+    description: "Summary style: neutral, bullet, or executive"
+steps:
+  - type: prompt
+    provider: "claude"
+    template: |
+      You are a helpful assistant that summarizes text.
+      Style: {style}
+      Max length: {max_length} words.
+
+      Summarize the following text:
+      {input}
+    output_var: summary
+output: "{summary}"

registry-seeds/official/translate/README.md

@@ -0,0 +1,21 @@
+# translate
+
+Translate text between languages using AI.
+
+## Usage
+
+```bash
+translate --from auto --to en --tone neutral < input.txt
+```
+
+## Arguments
+
+- `--from`: Source language (e.g., `en`, `es`, `fr`) or `auto`.
+- `--to`: Target language (e.g., `en`, `es`, `fr`).
+- `--tone`: Translation tone: `neutral`, `formal`, `casual`.
+
+## Examples
+
+```bash
+echo "Hola mundo" | translate --from es --to en --tone formal
+```

registry-seeds/official/translate/config.yaml

@@ -0,0 +1,34 @@
+name: translate
+version: "1.0.0"
+description: "Translate text between languages using AI"
+category: text-processing
+tags:
+  - translation
+  - localization
+  - text
+arguments:
+  - name: from_language
+    flag: "--from"
+    default: "auto"
+    description: "Source language (e.g., en, es, fr) or auto"
+  - name: to_language
+    flag: "--to"
+    default: "en"
+    description: "Target language (e.g., en, es, fr)"
+  - name: tone
+    flag: "--tone"
+    default: "neutral"
+    description: "Tone: neutral, formal, or casual"
+steps:
+  - type: prompt
+    provider: "claude"
+    template: |
+      You are a translation assistant.
+      Translate from: {from_language}
+      Translate to: {to_language}
+      Tone: {tone}
+
+      Translate the following text:
+      {input}
+    output_var: translation
+output: "{translation}"

scripts/fabric-sync.service

@@ -0,0 +1,29 @@
+[Unit]
+Description=CmdForge Fabric Pattern Sync
+Documentation=https://pages.brrd.tech/rob/cmdforge/
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+User=rob
+Group=rob
+WorkingDirectory=/home/rob/PycharmProjects/CmdForge
+
+# Use the project's virtual environment
+ExecStart=/home/rob/PycharmProjects/CmdForge/.venv/bin/python scripts/fabric_sync.py --sync
+
+# Logging
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=fabric-sync
+
+# Security hardening
+NoNewPrivileges=yes
+ProtectSystem=strict
+ProtectHome=read-only
+ReadWritePaths=/var/lib/cmdforge /home/rob/.cmdforge
+PrivateTmp=yes
+
+[Install]
+WantedBy=multi-user.target

scripts/fabric-sync.timer

@@ -0,0 +1,14 @@
+[Unit]
+Description=Daily Fabric Pattern Sync for CmdForge
+Documentation=https://pages.brrd.tech/rob/cmdforge/
+
+[Timer]
+# Run daily at 3 AM
+OnCalendar=*-*-* 03:00:00
+# Randomize start time by up to 1 hour to avoid thundering herd
+RandomizedDelaySec=3600
+# Run immediately if we missed a scheduled run
+Persistent=true
+
+[Install]
+WantedBy=timers.target

scripts/fabric_sync.py

@@ -0,0 +1,556 @@
+#!/usr/bin/env python3
+"""
+Scheduled Fabric pattern sync for CmdForge.
+
+Monitors the Fabric repository for new/updated patterns and syncs them
+to the CmdForge registry through the vetting pipeline.
+
+Usage:
+    # Check for new patterns (dry run)
+    python scripts/fabric_sync.py --dry-run
+
+    # Sync new patterns to registry
+    python scripts/fabric_sync.py --sync
+
+    # Check status of tracked patterns
+    python scripts/fabric_sync.py --status
+
+    # Force resync of specific patterns
+    python scripts/fabric_sync.py --force summarize extract_wisdom
+
+    # Run as daemon with interval
+    python scripts/fabric_sync.py --daemon --interval 3600
+
+Setup for cron (daily sync):
+    0 3 * * * /path/to/venv/bin/python /path/to/scripts/fabric_sync.py --sync >> /var/log/fabric_sync.log 2>&1
+
+Setup for systemd timer:
+    See scripts/fabric-sync.service and scripts/fabric-sync.timer
+"""
+
+import argparse
+import hashlib
+import json
+import logging
+import os
+import subprocess
+import sys
+import time
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s [%(levelname)s] %(message)s',
+    datefmt='%Y-%m-%d %H:%M:%S'
+)
+logger = logging.getLogger(__name__)
+
+# Constants
+FABRIC_REPO = "https://github.com/danielmiessler/fabric.git"
+DEFAULT_SYNC_DIR = Path("/var/lib/cmdforge/fabric-sync")
+DEFAULT_STATE_FILE = DEFAULT_SYNC_DIR / "sync_state.json"
+DEFAULT_PROVIDER = "opencode-pickle"
+
+
+@dataclass
+class PatternState:
+    """State of a single pattern."""
+    name: str
+    hash: str  # SHA256 of system.md content
+    synced_at: Optional[str] = None
+    version: str = "1.0.0"
+    status: str = "pending"  # pending, synced, failed, skipped
+
+
+@dataclass
+class SyncState:
+    """Overall sync state."""
+    last_check: Optional[str] = None
+    last_sync: Optional[str] = None
+    repo_commit: Optional[str] = None
+    patterns: dict = field(default_factory=dict)  # name -> PatternState as dict
+
+    def to_dict(self) -> dict:
+        return {
+            "last_check": self.last_check,
+            "last_sync": self.last_sync,
+            "repo_commit": self.repo_commit,
+            "patterns": self.patterns,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "SyncState":
+        return cls(
+            last_check=data.get("last_check"),
+            last_sync=data.get("last_sync"),
+            repo_commit=data.get("repo_commit"),
+            patterns=data.get("patterns", {}),
+        )
+
+
+def load_state(state_file: Path) -> SyncState:
+    """Load sync state from file."""
+    if state_file.exists():
+        with open(state_file) as f:
+            data = json.load(f)
+            return SyncState.from_dict(data)
+    return SyncState()
+
+
+def save_state(state: SyncState, state_file: Path):
+    """Save sync state to file."""
+    state_file.parent.mkdir(parents=True, exist_ok=True)
+    with open(state_file, "w") as f:
+        json.dump(state.to_dict(), f, indent=2)
+
+
+def clone_or_update_repo(sync_dir: Path) -> tuple[Path, str]:
+    """Clone or update the Fabric repository.
+
+    Returns:
+        Tuple of (patterns_dir, commit_hash)
+    """
+    fabric_dir = sync_dir / "fabric"
+    patterns_dir = fabric_dir / "data" / "patterns"
+
+    if fabric_dir.exists():
+        logger.info("Updating existing Fabric clone...")
+        subprocess.run(
+            ["git", "-C", str(fabric_dir), "fetch", "--quiet"],
+            check=True,
+            capture_output=True
+        )
+        subprocess.run(
+            ["git", "-C", str(fabric_dir), "reset", "--hard", "origin/main", "--quiet"],
+            check=True,
+            capture_output=True
+        )
+    else:
+        logger.info("Cloning Fabric repository...")
+        sync_dir.mkdir(parents=True, exist_ok=True)
+        subprocess.run(
+            ["git", "clone", "--depth", "1", FABRIC_REPO, str(fabric_dir)],
+            check=True,
+            capture_output=True
+        )
+
+    # Get current commit hash
+    result = subprocess.run(
+        ["git", "-C", str(fabric_dir), "rev-parse", "HEAD"],
+        capture_output=True,
+        text=True
+    )
+    commit_hash = result.stdout.strip()[:12]
+
+    return patterns_dir, commit_hash
+
+
+def hash_pattern(pattern_dir: Path) -> Optional[str]:
+    """Calculate hash of pattern content."""
+    system_md = pattern_dir / "system.md"
+    if not system_md.exists():
+        return None
+
+    content = system_md.read_bytes()
+    return hashlib.sha256(content).hexdigest()[:16]
+
+
+def scan_patterns(patterns_dir: Path) -> dict[str, str]:
+    """Scan all patterns and return name -> hash mapping."""
+    patterns = {}
+    for entry in sorted(patterns_dir.iterdir()):
+        if entry.is_dir():
+            pattern_hash = hash_pattern(entry)
+            if pattern_hash:
+                patterns[entry.name] = pattern_hash
+    return patterns
+
+
+def find_changes(
+    current_patterns: dict[str, str],
+    state: SyncState
+) -> tuple[list[str], list[str], list[str]]:
+    """Find new, updated, and removed patterns.
+
+    Returns:
+        Tuple of (new_patterns, updated_patterns, removed_patterns)
+    """
+    new_patterns = []
+    updated_patterns = []
+    removed_patterns = []
+
+    # Check for new and updated
+    for name, current_hash in current_patterns.items():
+        if name not in state.patterns:
+            new_patterns.append(name)
+        elif state.patterns[name].get("hash") != current_hash:
+            updated_patterns.append(name)
+
+    # Check for removed
+    for name in state.patterns:
+        if name not in current_patterns:
+            removed_patterns.append(name)
+
+    return new_patterns, updated_patterns, removed_patterns
+
+
+def vet_pattern(pattern_dir: Path, provider: str = DEFAULT_PROVIDER) -> tuple[bool, str]:
+    """Run vetting pipeline on a pattern.
+
+    Returns:
+        Tuple of (passed, reason)
+    """
+    try:
+        # Try to import the vetting pipeline
+        script_dir = Path(__file__).parent
+        sys.path.insert(0, str(script_dir))
+
+        from import_fabric import create_tool_config, clean_prompt, get_category, pattern_to_display_name
+
+        # Read pattern
+        system_md = pattern_dir / "system.md"
+        system_prompt = system_md.read_text()
+
+        # Create config
+        config = create_tool_config(pattern_dir.name, system_prompt, provider)
+
+        # Run scrutiny
+        try:
+            from scrutiny import vet_tool, VetResult
+            report = vet_tool(config, str(pattern_dir))
+
+            if report.result == VetResult.REJECT:
+                return False, f"Rejected: {report.suggestions[0] if report.suggestions else 'quality too low'}"
+            elif report.result == VetResult.REVIEW:
+                return True, f"Approved (needs review): score {report.overall_score:.2f}"
+            else:
+                return True, f"Approved: score {report.overall_score:.2f}"
+        except ImportError:
+            # Scrutiny not available - basic validation
+            if len(system_prompt.strip()) < 50:
+                return False, "Pattern too short"
+            return True, "Basic validation passed"
+
+    except Exception as e:
+        return False, f"Vetting error: {e}"
+
+
+def sync_pattern(
+    pattern_dir: Path,
+    output_dir: Path,
+    provider: str,
+    state: SyncState,
+    dry_run: bool = False
+) -> bool:
+    """Sync a single pattern.
+
+    Returns:
+        True if successful
+    """
+    name = pattern_dir.name
+    pattern_hash = hash_pattern(pattern_dir)
+
+    # Vet the pattern
+    passed, reason = vet_pattern(pattern_dir, provider)
+
+    if not passed:
+        logger.warning(f"  ✗ {name}: {reason}")
+        state.patterns[name] = {
+            "name": name,
+            "hash": pattern_hash,
+            "status": "failed",
+            "reason": reason,
+            "synced_at": datetime.now(timezone.utc).isoformat(),
+        }
+        return False
+
+    if dry_run:
+        logger.info(f"  [DRY RUN] Would sync: {name} ({reason})")
+        return True
+
+    # Import the pattern
+    try:
+        script_dir = Path(__file__).parent
+        sys.path.insert(0, str(script_dir))
+
+        from import_fabric import import_pattern
+
+        success = import_pattern(
+            name,
+            pattern_dir.parent,
+            output_dir,
+            provider,
+            dry_run=False,
+            registry_format=False,
+        )
+
+        if success:
+            logger.info(f"  ✓ {name}: {reason}")
+            state.patterns[name] = {
+                "name": name,
+                "hash": pattern_hash,
+                "status": "synced",
+                "synced_at": datetime.now(timezone.utc).isoformat(),
+            }
+            return True
+        else:
+            logger.error(f"  ✗ {name}: Import failed")
+            state.patterns[name] = {
+                "name": name,
+                "hash": pattern_hash,
+                "status": "failed",
+                "reason": "Import failed",
+                "synced_at": datetime.now(timezone.utc).isoformat(),
+            }
+            return False
+
+    except Exception as e:
+        logger.error(f"  ✗ {name}: {e}")
+        state.patterns[name] = {
+            "name": name,
+            "hash": pattern_hash,
+            "status": "failed",
+            "reason": str(e),
+            "synced_at": datetime.now(timezone.utc).isoformat(),
+        }
+        return False
+
+
+def run_sync(
+    sync_dir: Path,
+    output_dir: Path,
+    state_file: Path,
+    provider: str,
+    dry_run: bool = False,
+    force_patterns: list[str] = None
+) -> dict:
+    """Run the sync process.
+
+    Returns:
+        Summary dict with counts
+    """
+    # Load state
+    state = load_state(state_file)
+
+    # Clone/update repo
+    patterns_dir, commit_hash = clone_or_update_repo(sync_dir)
+
+    # Scan patterns
+    current_patterns = scan_patterns(patterns_dir)
+    logger.info(f"Found {len(current_patterns)} patterns in Fabric repo (commit {commit_hash})")
+
+    # Find changes
+    if force_patterns:
+        new_patterns = [p for p in force_patterns if p in current_patterns]
+        updated_patterns = []
+        removed_patterns = []
+    else:
+        new_patterns, updated_patterns, removed_patterns = find_changes(current_patterns, state)
+
+    logger.info(f"Changes: {len(new_patterns)} new, {len(updated_patterns)} updated, {len(removed_patterns)} removed")
+
+    # Update state timestamp
+    state.last_check = datetime.now(timezone.utc).isoformat()
+    state.repo_commit = commit_hash
+
+    # Process new and updated patterns
+    to_sync = new_patterns + updated_patterns
+    synced = 0
+    failed = 0
+
+    if to_sync:
+        logger.info(f"\nSyncing {len(to_sync)} patterns...")
+        for name in to_sync:
+            pattern_dir = patterns_dir / name
+            if sync_pattern(pattern_dir, output_dir, provider, state, dry_run):
+                synced += 1
+            else:
+                failed += 1
+
+    # Mark removed patterns
+    for name in removed_patterns:
+        if name in state.patterns:
+            state.patterns[name]["status"] = "removed"
+
+    # Save state
+    if not dry_run:
+        state.last_sync = datetime.now(timezone.utc).isoformat()
+        save_state(state, state_file)
+        logger.info(f"\nState saved to {state_file}")
+
+    # Summary
+    summary = {
+        "total_patterns": len(current_patterns),
+        "new": len(new_patterns),
+        "updated": len(updated_patterns),
+        "removed": len(removed_patterns),
+        "synced": synced,
+        "failed": failed,
+        "commit": commit_hash,
+    }
+
+    logger.info(f"\nSync complete: {synced} synced, {failed} failed")
+
+    return summary
+
+
+def print_status(state_file: Path):
+    """Print current sync status."""
+    state = load_state(state_file)
+
+    print(f"\nFabric Sync Status")
+    print(f"{'=' * 50}")
+    print(f"Last check: {state.last_check or 'Never'}")
+    print(f"Last sync:  {state.last_sync or 'Never'}")
+    print(f"Repo commit: {state.repo_commit or 'Unknown'}")
+
+    if state.patterns:
+        # Count by status
+        by_status = {}
+        for p in state.patterns.values():
+            status = p.get("status", "unknown")
+            by_status[status] = by_status.get(status, 0) + 1
+
+        print(f"\nPatterns: {len(state.patterns)} total")
+        for status, count in sorted(by_status.items()):
+            print(f"  {status}: {count}")
+
+        # Show failed patterns
+        failed = [p for p in state.patterns.values() if p.get("status") == "failed"]
+        if failed:
+            print(f"\nFailed patterns:")
+            for p in failed[:10]:
+                print(f"  - {p['name']}: {p.get('reason', 'Unknown error')}")
+            if len(failed) > 10:
+                print(f"  ... and {len(failed) - 10} more")
+    else:
+        print("\nNo patterns tracked yet. Run --sync to start.")
+
+
+def daemon_loop(
+    sync_dir: Path,
+    output_dir: Path,
+    state_file: Path,
+    provider: str,
+    interval: int
+):
+    """Run sync in a loop."""
+    logger.info(f"Starting daemon mode with {interval}s interval")
+
+    while True:
+        try:
+            run_sync(sync_dir, output_dir, state_file, provider)
+        except Exception as e:
+            logger.error(f"Sync failed: {e}")
+
+        logger.info(f"Sleeping for {interval}s...")
+        time.sleep(interval)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Scheduled Fabric pattern sync for CmdForge",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__
+    )
+
+    parser.add_argument(
+        "--sync",
+        action="store_true",
+        help="Run sync process"
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be synced without making changes"
+    )
+    parser.add_argument(
+        "--status",
+        action="store_true",
+        help="Show current sync status"
+    )
+    parser.add_argument(
+        "--force",
+        nargs="+",
+        metavar="PATTERN",
+        help="Force resync of specific patterns"
+    )
+    parser.add_argument(
+        "--daemon",
+        action="store_true",
+        help="Run in daemon mode"
+    )
+    parser.add_argument(
+        "--interval",
+        type=int,
+        default=3600,
+        help="Sync interval in seconds for daemon mode (default: 3600)"
+    )
+    parser.add_argument(
+        "--sync-dir",
+        type=Path,
+        default=DEFAULT_SYNC_DIR,
+        help=f"Directory for sync data (default: {DEFAULT_SYNC_DIR})"
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=Path.home() / ".cmdforge",
+        help="Output directory for synced tools (default: ~/.cmdforge)"
+    )
+    parser.add_argument(
+        "--state-file",
+        type=Path,
+        help="State file path (default: <sync-dir>/sync_state.json)"
+    )
+    parser.add_argument(
+        "--provider",
+        default=DEFAULT_PROVIDER,
+        help=f"Default provider for tools (default: {DEFAULT_PROVIDER})"
+    )
+
+    args = parser.parse_args()
+
+    # Set state file default
+    state_file = args.state_file or (args.sync_dir / "sync_state.json")
+
+    if args.status:
+        print_status(state_file)
+        return 0
+
+    if args.daemon:
+        daemon_loop(
+            args.sync_dir,
+            args.output,
+            state_file,
+            args.provider,
+            args.interval
+        )
+        return 0
+
+    if args.sync or args.dry_run or args.force:
+        summary = run_sync(
+            args.sync_dir,
+            args.output,
+            state_file,
+            args.provider,
+            dry_run=args.dry_run,
+            force_patterns=args.force
+        )
+
+        if summary["failed"] > 0:
+            return 1
+        return 0
+
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/health_check.py

@@ -0,0 +1,116 @@
+"""Basic health check for the CmdForge Registry API and DB."""
+
+from __future__ import annotations
+
+import json
+import sys
+import sqlite3
+from datetime import datetime, timedelta
+from pathlib import Path
+from urllib.request import Request, urlopen
+from urllib.error import URLError, HTTPError
+
+
+def _add_src_to_path() -> None:
+    repo_root = Path(__file__).resolve().parents[1]
+    sys.path.insert(0, str(repo_root / "src"))
+
+
+def _get_registry_url() -> str:
+    from cmdforge.config import get_registry_url
+
+    return get_registry_url().rstrip("/")
+
+
+def _get_db_path() -> Path:
+    from cmdforge.registry.db import get_db_path
+
+    return get_db_path()
+
+
+def check_api(url: str) -> str | None:
+    endpoint = f"{url}/tools?limit=1"
+    try:
+        req = Request(endpoint, headers={"Accept": "application/json"})
+        with urlopen(req, timeout=5) as resp:
+            if resp.status != 200:
+                return f"API unhealthy: status {resp.status}"
+            payload = json.loads(resp.read().decode("utf-8"))
+            if "data" not in payload:
+                return "API unhealthy: missing data field"
+    except HTTPError as exc:
+        return f"API unhealthy: HTTP {exc.code}"
+    except URLError as exc:
+        return f"API unhealthy: {exc.reason}"
+    except Exception as exc:
+        return f"API unhealthy: {exc}"
+    return None
+
+
+def check_db(db_path: Path) -> str | None:
+    if not db_path.exists():
+        return f"DB missing: {db_path}"
+    if not db_path.is_file():
+        return f"DB path is not a file: {db_path}"
+    try:
+        with db_path.open("rb"):
+            pass
+    except OSError as exc:
+        return f"DB not readable: {exc}"
+    return None
+
+
+def check_last_sync(db_path: Path) -> str | None:
+    try:
+        conn = sqlite3.connect(db_path)
+        try:
+            row = conn.execute("SELECT MAX(processed_at) FROM webhook_log").fetchone()
+        finally:
+            conn.close()
+    except sqlite3.Error as exc:
+        return f"DB error: {exc}"
+
+    if not row or not row[0]:
+        return "No webhook sync recorded in webhook_log"
+
+    raw = str(row[0]).replace("Z", "+00:00")
+    try:
+        last_sync = datetime.fromisoformat(raw)
+    except ValueError:
+        return f"Invalid sync timestamp: {row[0]}"
+
+    if datetime.utcnow() - last_sync > timedelta(hours=1):
+        return f"Last sync too old: {last_sync.isoformat()}"
+    return None
+
+
+def main() -> int:
+    _add_src_to_path()
+    errors = []
+
+    registry_url = _get_registry_url()
+    db_path = _get_db_path()
+
+    api_error = check_api(registry_url)
+    if api_error:
+        errors.append(api_error)
+
+    db_error = check_db(db_path)
+    if db_error:
+        errors.append(db_error)
+    else:
+        sync_error = check_last_sync(db_path)
+        if sync_error:
+            errors.append(sync_error)
+
+    if errors:
+        for err in errors:
+            print(err, file=sys.stderr)
+        return 1
+
+    print("Health check OK")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/import_fabric.py

@@ -0,0 +1,388 @@
+#!/usr/bin/env python3
+"""
+Import Fabric patterns as CmdForge tools.
+
+Usage:
+    # Import all patterns
+    python scripts/import_fabric.py --all
+
+    # Import specific pattern(s)
+    python scripts/import_fabric.py summarize extract_wisdom
+
+    # List available patterns
+    python scripts/import_fabric.py --list
+
+    # Dry run (show what would be created)
+    python scripts/import_fabric.py --all --dry-run
+
+    # Specify output directory
+    python scripts/import_fabric.py --all --output /tmp/fabric-tools
+
+    # Specify default provider
+    python scripts/import_fabric.py --all --provider opencode-deepseek
+"""
+
+import argparse
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+
+# Fabric repo URL
+FABRIC_REPO = "https://github.com/danielmiessler/fabric.git"
+
+# Default provider for imported tools
+DEFAULT_PROVIDER = "opencode-pickle"
+
+# Category mapping based on pattern name prefixes/keywords
+CATEGORY_RULES = [
+    (r"^analyze_", "Data"),
+    (r"^extract_", "Data"),
+    (r"^create_", "Developer"),
+    (r"^write_", "Text"),
+    (r"^improve_", "Text"),
+    (r"^summarize", "Text"),
+    (r"^explain_", "Text"),
+    (r"^review_", "Developer"),
+    (r"^code", "Developer"),
+    (r"^debug", "Developer"),
+    (r"^test", "Developer"),
+    (r"rate_", "Data"),
+    (r"json", "Data"),
+    (r"csv", "Data"),
+    (r"sql", "Data"),
+    (r"translate", "Text"),
+    (r"transcri", "Text"),
+]
+
+
+def get_category(pattern_name: str) -> str:
+    """Determine category based on pattern name."""
+    name_lower = pattern_name.lower()
+    for regex, category in CATEGORY_RULES:
+        if re.search(regex, name_lower):
+            return category
+    return "Other"
+
+
+def pattern_to_display_name(pattern_name: str) -> str:
+    """Convert pattern name to display name."""
+    # Replace underscores with spaces and title case
+    return pattern_name.replace("_", " ").title()
+
+
+def clean_prompt(prompt: str) -> str:
+    """Clean up the Fabric prompt for use in CmdForge."""
+    # Remove trailing INPUT: placeholder (we'll add {input} ourselves)
+    prompt = prompt.strip()
+
+    # Remove various forms of input placeholder at the end
+    for suffix in ["INPUT:", "# INPUT", "# INPUT:", "INPUT"]:
+        if prompt.endswith(suffix):
+            prompt = prompt[:-len(suffix)].strip()
+
+    return prompt
+
+
+def create_tool_config(
+    pattern_name: str,
+    system_prompt: str,
+    provider: str = DEFAULT_PROVIDER,
+) -> dict:
+    """Create a CmdForge tool config from a Fabric pattern."""
+
+    cleaned_prompt = clean_prompt(system_prompt)
+    display_name = pattern_to_display_name(pattern_name)
+    category = get_category(pattern_name)
+
+    # Build the full prompt with input placeholder
+    full_prompt = f"{cleaned_prompt}\n\n{{input}}"
+
+    config = {
+        "name": pattern_name,
+        "description": f"{display_name} - imported from Fabric patterns",
+        "version": "1.0.0",
+        "category": category,
+
+        # Attribution - marks this as an imported tool
+        "source": {
+            "type": "imported",
+            "license": "MIT",
+            "url": "https://github.com/danielmiessler/fabric",
+            "author": "Daniel Miessler",
+            "original_tool": f"fabric/patterns/{pattern_name}",
+        },
+
+        "arguments": [],
+
+        "steps": [
+            {
+                "type": "prompt",
+                "prompt": full_prompt,
+                "provider": provider,
+                "output_var": "response",
+            }
+        ],
+
+        "output": "{response}",
+    }
+
+    return config
+
+
+def clone_fabric(target_dir: Path) -> Path:
+    """Clone or update Fabric repo, return patterns directory."""
+    fabric_dir = target_dir / "fabric"
+    patterns_dir = fabric_dir / "data" / "patterns"
+
+    if fabric_dir.exists():
+        print(f"Using existing Fabric clone at {fabric_dir}")
+        # Pull latest
+        subprocess.run(
+            ["git", "-C", str(fabric_dir), "pull", "--quiet"],
+            check=False
+        )
+    else:
+        print(f"Cloning Fabric to {fabric_dir}...")
+        subprocess.run(
+            ["git", "clone", "--depth", "1", FABRIC_REPO, str(fabric_dir)],
+            check=True,
+            capture_output=True
+        )
+
+    if not patterns_dir.exists():
+        raise RuntimeError(f"Patterns directory not found at {patterns_dir}")
+
+    return patterns_dir
+
+
+def list_patterns(patterns_dir: Path) -> list[str]:
+    """List all available pattern names."""
+    patterns = []
+    for entry in sorted(patterns_dir.iterdir()):
+        if entry.is_dir() and (entry / "system.md").exists():
+            patterns.append(entry.name)
+    return patterns
+
+
+def import_pattern(
+    pattern_name: str,
+    patterns_dir: Path,
+    output_dir: Path,
+    provider: str,
+    dry_run: bool = False,
+    registry_format: bool = False,
+    namespace: str = "official",
+) -> bool:
+    """Import a single pattern. Returns True on success."""
+    pattern_path = patterns_dir / pattern_name
+    system_md = pattern_path / "system.md"
+
+    if not system_md.exists():
+        print(f"  ✗ Pattern '{pattern_name}' not found", file=sys.stderr)
+        return False
+
+    # Read the system prompt
+    system_prompt = system_md.read_text()
+
+    # Create tool config
+    config = create_tool_config(pattern_name, system_prompt, provider)
+
+    # Output directory for this tool
+    if registry_format:
+        # Registry format: tools/<namespace>/<name>/config.yaml
+        tool_dir = output_dir / "tools" / namespace / pattern_name
+    else:
+        # Local format: <output>/<name>/config.yaml
+        tool_dir = output_dir / pattern_name
+    config_file = tool_dir / "config.yaml"
+
+    if dry_run:
+        print(f"  [DRY RUN] Would create: {config_file}")
+        print(f"            Category: {config['category']}")
+        print(f"            Provider: {provider}")
+        return True
+
+    # Create tool directory
+    tool_dir.mkdir(parents=True, exist_ok=True)
+
+    # Write config.yaml with proper multi-line string handling
+    class LiteralStr(str):
+        pass
+
+    def literal_representer(dumper, data):
+        return dumper.represent_scalar('tag:yaml.org,2002:str', data, style='|')
+
+    yaml.add_representer(LiteralStr, literal_representer)
+
+    # Convert the prompt to literal style
+    config["steps"][0]["prompt"] = LiteralStr(config["steps"][0]["prompt"])
+
+    with open(config_file, "w") as f:
+        yaml.dump(config, f, default_flow_style=False, sort_keys=False, allow_unicode=True)
+
+    # Create a basic README.md
+    readme_content = f"""# {pattern_to_display_name(pattern_name)}
+
+{config['description']}
+
+## Usage
+
+```bash
+cat input.txt | {pattern_name}
+```
+
+## Source
+
+This tool was imported from [Fabric](https://github.com/danielmiessler/fabric) patterns.
+
+- **Original pattern**: `{pattern_name}`
+- **Author**: Daniel Miessler
+- **License**: MIT
+"""
+    (tool_dir / "README.md").write_text(readme_content)
+
+    print(f"  ✓ {pattern_name} -> {tool_dir}")
+    return True
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Import Fabric patterns as CmdForge tools",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__
+    )
+
+    parser.add_argument(
+        "patterns",
+        nargs="*",
+        help="Pattern name(s) to import"
+    )
+    parser.add_argument(
+        "--all",
+        action="store_true",
+        help="Import all patterns"
+    )
+    parser.add_argument(
+        "--list",
+        action="store_true",
+        help="List available patterns"
+    )
+    parser.add_argument(
+        "--output", "-o",
+        type=Path,
+        default=Path.home() / ".cmdforge",
+        help="Output directory (default: ~/.cmdforge)"
+    )
+    parser.add_argument(
+        "--provider", "-p",
+        default=DEFAULT_PROVIDER,
+        help=f"Default provider for tools (default: {DEFAULT_PROVIDER})"
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be created without writing files"
+    )
+    parser.add_argument(
+        "--fabric-dir",
+        type=Path,
+        default=Path("/tmp/fabric-import"),
+        help="Directory to clone Fabric repo (default: /tmp/fabric-import)"
+    )
+    parser.add_argument(
+        "--registry",
+        action="store_true",
+        help="Output in registry format (tools/official/<name>/config.yaml)"
+    )
+    parser.add_argument(
+        "--namespace",
+        default="official",
+        help="Namespace for registry format (default: official)"
+    )
+
+    args = parser.parse_args()
+
+    # Validate arguments
+    if not args.list and not args.all and not args.patterns:
+        parser.error("Specify pattern names, --all, or --list")
+
+    # Clone/update Fabric
+    args.fabric_dir.mkdir(parents=True, exist_ok=True)
+    patterns_dir = clone_fabric(args.fabric_dir)
+
+    # List mode
+    if args.list:
+        patterns = list_patterns(patterns_dir)
+        print(f"\nAvailable Fabric patterns ({len(patterns)}):\n")
+
+        # Group by category
+        by_category = {}
+        for p in patterns:
+            cat = get_category(p)
+            by_category.setdefault(cat, []).append(p)
+
+        for cat in sorted(by_category.keys()):
+            print(f"  {cat}:")
+            for p in sorted(by_category[cat]):
+                print(f"    - {p}")
+            print()
+
+        return 0
+
+    # Determine which patterns to import
+    if args.all:
+        to_import = list_patterns(patterns_dir)
+    else:
+        to_import = args.patterns
+
+    if not to_import:
+        print("No patterns to import.", file=sys.stderr)
+        return 1
+
+    print(f"\nImporting {len(to_import)} pattern(s) to {args.output}")
+    print(f"Provider: {args.provider}")
+    if args.dry_run:
+        print("(DRY RUN - no files will be written)\n")
+    else:
+        print()
+
+    # Import each pattern
+    success = 0
+    failed = 0
+
+    for pattern in to_import:
+        if import_pattern(
+            pattern,
+            patterns_dir,
+            args.output,
+            args.provider,
+            args.dry_run,
+            args.registry,
+            args.namespace
+        ):
+            success += 1
+        else:
+            failed += 1
+
+    print(f"\nDone: {success} imported, {failed} failed")
+
+    if not args.dry_run and success > 0:
+        print(f"\nNext steps:")
+        print(f"  1. Review generated tools in {args.output}")
+        print(f"  2. Run 'cmdforge refresh' to create wrapper scripts")
+        print(f"  3. Test with: cmdforge test <pattern_name>")
+        print(f"  4. Publish with: cmdforge registry publish {args.output}/<pattern_name>")
+
+    return 0 if failed == 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/patch_nodegraphqt.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""Patch NodeGraphQt for PySide6 6.7+ compatibility.
+
+The setSelectionArea() API changed in PySide6 6.7 to require an
+ItemSelectionOperation parameter. This script patches the installed
+NodeGraphQt package to work with newer PySide6 versions.
+
+Issue: setSelectionArea(path, mode) -> setSelectionArea(path, operation, mode)
+
+Usage:
+    python scripts/patch_nodegraphqt.py
+
+This can be run after `pip install NodeGraphQt-QuiltiX-fork[pyside6]`
+"""
+
+import sys
+import site
+from pathlib import Path
+
+
+def find_viewer_file():
+    """Find the NodeGraphQt viewer.py file in site-packages."""
+    # Check common locations
+    for site_dir in site.getsitepackages() + [site.getusersitepackages()]:
+        viewer_path = Path(site_dir) / "NodeGraphQt" / "widgets" / "viewer.py"
+        if viewer_path.exists():
+            return viewer_path
+
+    # Check virtual environment
+    venv_path = Path(sys.prefix) / "lib"
+    for python_dir in venv_path.glob("python*"):
+        viewer_path = python_dir / "site-packages" / "NodeGraphQt" / "widgets" / "viewer.py"
+        if viewer_path.exists():
+            return viewer_path
+
+    return None
+
+
+def patch_file(viewer_path: Path) -> bool:
+    """Apply the PySide6 compatibility patch."""
+    content = viewer_path.read_text()
+
+    # Check if already patched
+    if "Qt.ReplaceSelection" in content:
+        print(f"Already patched: {viewer_path}")
+        return True
+
+    # The old code pattern
+    old_code = """self.scene().setSelectionArea(
+                    path, QtCore.Qt.IntersectsItemShape
+                )"""
+
+    # The new code with ItemSelectionOperation
+    new_code = """self.scene().setSelectionArea(
+                    path, QtCore.Qt.ReplaceSelection,
+                    QtCore.Qt.IntersectsItemShape
+                )"""
+
+    if old_code not in content:
+        print(f"Warning: Could not find code to patch in {viewer_path}")
+        print("The file may have a different format or already be modified.")
+        return False
+
+    # Apply patch
+    patched_content = content.replace(old_code, new_code)
+
+    # Backup original
+    backup_path = viewer_path.with_suffix(".py.bak")
+    if not backup_path.exists():
+        viewer_path.rename(backup_path)
+        print(f"Backup created: {backup_path}")
+
+    # Write patched file
+    viewer_path.write_text(patched_content)
+    print(f"Patched successfully: {viewer_path}")
+    return True
+
+
+def main():
+    print("NodeGraphQt PySide6 Compatibility Patch")
+    print("=" * 40)
+
+    viewer_path = find_viewer_file()
+
+    if not viewer_path:
+        print("Error: Could not find NodeGraphQt installation.")
+        print("Make sure NodeGraphQt-QuiltiX-fork is installed:")
+        print("  pip install 'NodeGraphQt-QuiltiX-fork[pyside6]'")
+        return 1
+
+    print(f"Found: {viewer_path}")
+
+    if patch_file(viewer_path):
+        print("\nPatch applied successfully!")
+        print("The rubber band selection should now work in PySide6 6.7+")
+        return 0
+    else:
+        print("\nPatch failed.")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/scrutiny.py

@@ -0,0 +1,507 @@
+#!/usr/bin/env python3
+"""
+Tool vetting/scrutiny module for CmdForge.
+
+Performs AI-powered analysis of tools to assess quality and safety:
+- Honesty: Does the tool do what it claims?
+- Transparency: Is the prompt clear and understandable?
+- Scope: Is the tool appropriately scoped?
+- Efficiency: Is the prompt well-structured?
+- Safety: Are there any concerning patterns?
+
+Usage:
+    # Vet a single tool
+    python scripts/scrutiny.py path/to/tool/config.yaml
+
+    # Vet all tools in directory
+    python scripts/scrutiny.py --all ~/.cmdforge/
+
+    # Output as JSON
+    python scripts/scrutiny.py --json path/to/tool/config.yaml
+
+    # Use specific provider for analysis
+    python scripts/scrutiny.py --provider claude path/to/tool/config.yaml
+"""
+
+import argparse
+import json
+import sys
+from dataclasses import dataclass, field, asdict
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+
+class VetResult(Enum):
+    """Vetting decision."""
+    APPROVE = "approve"      # Auto-approve - meets all criteria
+    REVIEW = "review"        # Needs human review - some concerns
+    REJECT = "reject"        # Auto-reject - fails criteria
+    ERROR = "error"          # Could not vet
+
+
+@dataclass
+class VetScore:
+    """Individual score for a vetting criterion."""
+    criterion: str
+    score: float  # 0.0 to 1.0
+    max_score: float = 1.0
+    notes: str = ""
+    concerns: list[str] = field(default_factory=list)
+
+
+@dataclass
+class VetReport:
+    """Complete vetting report for a tool."""
+    tool_name: str
+    tool_path: str
+    result: VetResult
+    overall_score: float  # 0.0 to 1.0
+    scores: list[VetScore] = field(default_factory=list)
+    suggestions: list[str] = field(default_factory=list)
+    error: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization."""
+        d = asdict(self)
+        d['result'] = self.result.value
+        return d
+
+
+# Thresholds for auto-approve/reject
+APPROVE_THRESHOLD = 0.8   # Score >= 0.8 -> auto-approve
+REJECT_THRESHOLD = 0.3    # Score < 0.3 -> auto-reject
+
+
+def load_tool_config(path: Path) -> Optional[dict]:
+    """Load tool configuration from YAML file."""
+    if path.is_dir():
+        config_file = path / "config.yaml"
+    else:
+        config_file = path
+
+    if not config_file.exists():
+        return None
+
+    with open(config_file) as f:
+        return yaml.safe_load(f)
+
+
+def vet_honesty(config: dict) -> VetScore:
+    """Check if tool description matches what it actually does."""
+    score = VetScore(criterion="honesty", score=0.0, notes="")
+    concerns = []
+
+    name = config.get("name", "")
+    description = config.get("description", "")
+    steps = config.get("steps", [])
+
+    # Check that description exists
+    if not description:
+        concerns.append("Missing description")
+        score.score = 0.3
+    else:
+        score.score = 0.6
+
+    # Check that steps exist
+    if not steps:
+        concerns.append("No execution steps defined")
+        score.score = min(score.score, 0.2)
+    else:
+        # Check if description keywords appear in prompts
+        desc_words = set(description.lower().split())
+        prompt_text = ""
+        for step in steps:
+            if step.get("type") == "prompt":
+                prompt_text += step.get("prompt", "").lower() + " "
+
+        # Simple keyword overlap check
+        prompt_words = set(prompt_text.split())
+        overlap = desc_words & prompt_words
+        meaningful_overlap = overlap - {"the", "a", "an", "and", "or", "is", "to", "for", "of", "in"}
+
+        if len(meaningful_overlap) >= 2:
+            score.score = min(1.0, score.score + 0.3)
+            score.notes = f"Description matches prompt content ({len(meaningful_overlap)} keywords)"
+        else:
+            concerns.append("Description may not match actual behavior")
+
+    score.concerns = concerns
+    return score
+
+
+def vet_transparency(config: dict) -> VetScore:
+    """Check if the tool's behavior is clear and understandable."""
+    score = VetScore(criterion="transparency", score=0.0, notes="")
+    concerns = []
+
+    steps = config.get("steps", [])
+
+    if not steps:
+        concerns.append("No steps to analyze")
+        score.concerns = concerns
+        return score
+
+    # Analyze each step
+    total_prompt_length = 0
+    has_clear_instructions = False
+
+    for step in steps:
+        if step.get("type") == "prompt":
+            prompt = step.get("prompt", "")
+            total_prompt_length += len(prompt)
+
+            # Check for clear instruction patterns
+            instruction_patterns = [
+                "you are", "your task", "please", "analyze", "extract",
+                "summarize", "create", "write", "explain", "review"
+            ]
+            prompt_lower = prompt.lower()
+            if any(p in prompt_lower for p in instruction_patterns):
+                has_clear_instructions = True
+
+    # Score based on findings
+    if has_clear_instructions:
+        score.score += 0.5
+        score.notes = "Contains clear instructions"
+
+    if total_prompt_length > 50:
+        score.score += 0.3
+        score.notes += "; Substantial prompt content"
+    elif total_prompt_length > 0:
+        score.score += 0.1
+        concerns.append("Very short prompt - may lack clarity")
+
+    # Check for output variable naming
+    for step in steps:
+        output_var = step.get("output_var", "")
+        if output_var and output_var != "response":
+            score.score += 0.2
+            score.notes += "; Descriptive output variable"
+            break
+
+    score.score = min(1.0, score.score)
+    score.concerns = concerns
+    return score
+
+
+def vet_scope(config: dict) -> VetScore:
+    """Check if tool is appropriately scoped (not too broad/narrow)."""
+    score = VetScore(criterion="scope", score=0.0, notes="")
+    concerns = []
+
+    description = config.get("description", "")
+    steps = config.get("steps", [])
+    arguments = config.get("arguments", [])
+
+    # Start with base score
+    score.score = 0.5
+
+    # Single-step tools are well-scoped
+    if len(steps) == 1:
+        score.score += 0.2
+        score.notes = "Single-step tool - focused scope"
+    elif len(steps) <= 3:
+        score.score += 0.1
+        score.notes = "Multi-step tool with reasonable complexity"
+    else:
+        concerns.append(f"Complex tool with {len(steps)} steps - may be over-scoped")
+        score.score -= 0.1
+
+    # Check for overly generic descriptions
+    generic_terms = ["everything", "anything", "all", "any task", "general purpose"]
+    desc_lower = description.lower()
+    if any(term in desc_lower for term in generic_terms):
+        concerns.append("Description suggests overly broad scope")
+        score.score -= 0.2
+
+    # Arguments indicate configurable scope (good)
+    if arguments:
+        score.score += 0.1
+        score.notes += "; Configurable via arguments"
+
+    score.score = max(0.0, min(1.0, score.score))
+    score.concerns = concerns
+    return score
+
+
+def vet_efficiency(config: dict) -> VetScore:
+    """Check if prompt is well-structured and efficient."""
+    score = VetScore(criterion="efficiency", score=0.0, notes="")
+    concerns = []
+
+    steps = config.get("steps", [])
+
+    # Analyze prompts
+    for step in steps:
+        if step.get("type") == "prompt":
+            prompt = step.get("prompt", "")
+
+            # Check for excessive repetition
+            words = prompt.lower().split()
+            word_counts = {}
+            for word in words:
+                if len(word) > 4:  # Only check meaningful words
+                    word_counts[word] = word_counts.get(word, 0) + 1
+
+            max_repetition = max(word_counts.values()) if word_counts else 0
+            if max_repetition > 5:
+                concerns.append(f"Repetitive language detected ({max_repetition}x)")
+                score.score = max(0.0, score.score - 0.2)
+
+            # Check for structured output hints
+            structure_patterns = [
+                "markdown", "json", "format", "structure", "sections",
+                "bullet", "numbered", "list", "table"
+            ]
+            if any(p in prompt.lower() for p in structure_patterns):
+                score.score += 0.3
+                score.notes = "Specifies output structure"
+
+            # Reasonable length (not too short, not excessive)
+            if 100 <= len(prompt) <= 5000:
+                score.score += 0.4
+            elif len(prompt) < 100:
+                concerns.append("Very short prompt - may lack guidance")
+                score.score += 0.2
+            else:
+                concerns.append("Very long prompt - may be inefficient")
+                score.score += 0.2
+
+    # Base score if steps exist
+    if steps:
+        score.score += 0.3
+
+    score.score = min(1.0, score.score)
+    score.concerns = concerns
+    return score
+
+
+def vet_safety(config: dict) -> VetScore:
+    """Check for concerning patterns in the tool."""
+    score = VetScore(criterion="safety", score=1.0, notes="No safety concerns")
+    concerns = []
+
+    steps = config.get("steps", [])
+
+    # Check for code steps
+    code_step_count = 0
+    for step in steps:
+        if step.get("type") == "code":
+            code_step_count += 1
+            code = step.get("code", "")
+
+            # Check for potentially dangerous patterns
+            dangerous_patterns = [
+                ("subprocess", "Executes shell commands"),
+                ("os.system", "Executes shell commands"),
+                ("eval(", "Dynamic code execution"),
+                ("exec(", "Dynamic code execution"),
+                ("open(", "File operations"),
+                ("requests.", "Network requests"),
+                ("urllib", "Network requests"),
+                ("shutil.rmtree", "Recursive deletion"),
+            ]
+
+            for pattern, concern in dangerous_patterns:
+                if pattern in code:
+                    concerns.append(f"Code contains {concern.lower()}")
+                    score.score -= 0.15
+
+    if code_step_count > 0:
+        score.notes = f"Contains {code_step_count} code step(s)"
+        if not concerns:
+            score.notes += " - no dangerous patterns detected"
+
+    score.score = max(0.0, score.score)
+    score.concerns = concerns
+    return score
+
+
+def vet_tool(config: dict, tool_path: str) -> VetReport:
+    """Perform complete vetting of a tool."""
+    name = config.get("name", "unknown")
+
+    # Run all checks
+    scores = [
+        vet_honesty(config),
+        vet_transparency(config),
+        vet_scope(config),
+        vet_efficiency(config),
+        vet_safety(config),
+    ]
+
+    # Calculate overall score (weighted average)
+    weights = {
+        "honesty": 0.25,
+        "transparency": 0.20,
+        "scope": 0.15,
+        "efficiency": 0.15,
+        "safety": 0.25,
+    }
+
+    total_weight = sum(weights.values())
+    weighted_sum = sum(s.score * weights.get(s.criterion, 0.1) for s in scores)
+    overall_score = weighted_sum / total_weight
+
+    # Determine result
+    if overall_score >= APPROVE_THRESHOLD:
+        result = VetResult.APPROVE
+    elif overall_score < REJECT_THRESHOLD:
+        result = VetResult.REJECT
+    else:
+        result = VetResult.REVIEW
+
+    # Collect all concerns for suggestions
+    suggestions = []
+    for s in scores:
+        for concern in s.concerns:
+            suggestions.append(f"[{s.criterion}] {concern}")
+
+    return VetReport(
+        tool_name=name,
+        tool_path=tool_path,
+        result=result,
+        overall_score=overall_score,
+        scores=scores,
+        suggestions=suggestions,
+    )
+
+
+def vet_directory(directory: Path, provider: Optional[str] = None) -> list[VetReport]:
+    """Vet all tools in a directory."""
+    reports = []
+
+    for entry in directory.iterdir():
+        config_file = None
+        if entry.is_dir():
+            config_file = entry / "config.yaml"
+        elif entry.suffix in [".yaml", ".yml"]:
+            config_file = entry
+
+        if config_file and config_file.exists():
+            config = load_tool_config(config_file)
+            if config:
+                report = vet_tool(config, str(entry))
+                reports.append(report)
+
+    return reports
+
+
+def print_report(report: VetReport, verbose: bool = False):
+    """Print a vetting report to console."""
+    # Result emoji
+    result_emoji = {
+        VetResult.APPROVE: "✅",
+        VetResult.REVIEW: "⚠️",
+        VetResult.REJECT: "❌",
+        VetResult.ERROR: "💥",
+    }
+
+    emoji = result_emoji.get(report.result, "❓")
+    print(f"\n{emoji} {report.tool_name}: {report.result.value.upper()} (score: {report.overall_score:.2f})")
+
+    if verbose or report.result != VetResult.APPROVE:
+        print(f"   Path: {report.tool_path}")
+
+        # Print individual scores
+        for score in report.scores:
+            bar = "█" * int(score.score * 10) + "░" * (10 - int(score.score * 10))
+            print(f"   {score.criterion:12} [{bar}] {score.score:.2f}")
+            if score.concerns:
+                for concern in score.concerns:
+                    print(f"      ⚠ {concern}")
+
+        # Print suggestions
+        if report.suggestions and verbose:
+            print("   Suggestions:")
+            for suggestion in report.suggestions:
+                print(f"      • {suggestion}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Vet CmdForge tools for quality and safety",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__
+    )
+
+    parser.add_argument(
+        "path",
+        type=Path,
+        nargs="?",
+        help="Tool config file or directory to vet"
+    )
+    parser.add_argument(
+        "--all",
+        action="store_true",
+        help="Vet all tools in directory"
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output as JSON"
+    )
+    parser.add_argument(
+        "--verbose", "-v",
+        action="store_true",
+        help="Show detailed output"
+    )
+    parser.add_argument(
+        "--provider",
+        default=None,
+        help="AI provider for enhanced analysis (future feature)"
+    )
+
+    args = parser.parse_args()
+
+    if not args.path:
+        parser.error("Please specify a path to vet")
+
+    # Collect reports
+    reports = []
+
+    if args.all or args.path.is_dir():
+        reports = vet_directory(args.path, args.provider)
+    else:
+        config = load_tool_config(args.path)
+        if not config:
+            print(f"Error: Could not load tool config from {args.path}", file=sys.stderr)
+            return 1
+        report = vet_tool(config, str(args.path))
+        reports.append(report)
+
+    if not reports:
+        print("No tools found to vet", file=sys.stderr)
+        return 1
+
+    # Output
+    if args.json:
+        output = [r.to_dict() for r in reports]
+        print(json.dumps(output, indent=2))
+    else:
+        # Summary
+        approved = sum(1 for r in reports if r.result == VetResult.APPROVE)
+        review = sum(1 for r in reports if r.result == VetResult.REVIEW)
+        rejected = sum(1 for r in reports if r.result == VetResult.REJECT)
+
+        print(f"Vetting {len(reports)} tool(s)...")
+
+        for report in reports:
+            print_report(report, args.verbose)
+
+        print(f"\n{'─' * 40}")
+        print(f"Summary: {approved} approved, {review} need review, {rejected} rejected")
+
+        # Return code based on results
+        if rejected > 0:
+            return 2
+        elif review > 0:
+            return 1
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/similarity.py

@@ -0,0 +1,441 @@
+#!/usr/bin/env python3
+"""
+Duplicate detection for CmdForge tools using text similarity.
+
+Finds tools that may be duplicates or very similar to existing tools.
+Uses TF-IDF vectorization and cosine similarity for comparison.
+
+Usage:
+    # Check a tool against all existing tools
+    python scripts/similarity.py path/to/tool/config.yaml
+
+    # Check against tools in a specific directory
+    python scripts/similarity.py path/to/tool/config.yaml --against ~/.cmdforge/
+
+    # Find all similar pairs in a directory
+    python scripts/similarity.py --scan ~/.cmdforge/
+
+    # Set similarity threshold (default: 0.7)
+    python scripts/similarity.py --threshold 0.8 path/to/tool/config.yaml
+
+    # Output as JSON
+    python scripts/similarity.py --json path/to/tool/config.yaml
+"""
+
+import argparse
+import json
+import math
+import re
+import sys
+from collections import Counter
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+
+@dataclass
+class SimilarityMatch:
+    """A similarity match between two tools."""
+    tool1_name: str
+    tool1_path: str
+    tool2_name: str
+    tool2_path: str
+    similarity: float  # 0.0 to 1.0
+    match_type: str  # "duplicate", "similar", "related"
+
+    def to_dict(self) -> dict:
+        return {
+            "tool1": {"name": self.tool1_name, "path": self.tool1_path},
+            "tool2": {"name": self.tool2_name, "path": self.tool2_path},
+            "similarity": self.similarity,
+            "match_type": self.match_type,
+        }
+
+
+@dataclass
+class ToolText:
+    """Extracted text from a tool for similarity comparison."""
+    name: str
+    path: str
+    text: str
+    tokens: list[str] = field(default_factory=list)
+    tfidf: dict = field(default_factory=dict)
+
+
+# Similarity thresholds
+DUPLICATE_THRESHOLD = 0.9   # >= 0.9 is likely a duplicate
+SIMILAR_THRESHOLD = 0.7     # >= 0.7 is very similar
+RELATED_THRESHOLD = 0.5     # >= 0.5 is related
+
+
+def load_tool_config(path: Path) -> Optional[dict]:
+    """Load tool configuration from YAML file."""
+    if path.is_dir():
+        config_file = path / "config.yaml"
+    else:
+        config_file = path
+
+    if not config_file.exists():
+        return None
+
+    with open(config_file) as f:
+        return yaml.safe_load(f)
+
+
+def extract_tool_text(config: dict, path: str) -> ToolText:
+    """Extract all meaningful text from a tool config."""
+    texts = []
+
+    # Name and description
+    name = config.get("name", "")
+    texts.append(name)
+    texts.append(config.get("description", ""))
+
+    # Category and tags
+    texts.append(config.get("category", ""))
+    tags = config.get("tags", [])
+    if isinstance(tags, list):
+        texts.extend(tags)
+
+    # Steps - extract prompts and code
+    for step in config.get("steps", []):
+        if step.get("type") == "prompt":
+            texts.append(step.get("prompt", ""))
+        elif step.get("type") == "code":
+            # Extract meaningful parts from code (comments, strings)
+            code = step.get("code", "")
+            # Add variable names
+            texts.append(code)
+
+    # Arguments
+    for arg in config.get("arguments", []):
+        texts.append(arg.get("flag", ""))
+        texts.append(arg.get("description", ""))
+        texts.append(arg.get("variable", ""))
+
+    # Combine and clean
+    combined = " ".join(texts)
+    return ToolText(name=name, path=path, text=combined)
+
+
+def tokenize(text: str) -> list[str]:
+    """Tokenize text into words, removing stopwords."""
+    # Convert to lowercase and extract words
+    words = re.findall(r'\b[a-z]{2,}\b', text.lower())
+
+    # Remove common stopwords
+    stopwords = {
+        "the", "a", "an", "and", "or", "but", "in", "on", "at", "to", "for",
+        "of", "with", "by", "from", "as", "is", "was", "are", "were", "been",
+        "be", "have", "has", "had", "do", "does", "did", "will", "would",
+        "could", "should", "may", "might", "must", "shall", "can", "this",
+        "that", "these", "those", "it", "its", "you", "your", "we", "our",
+        "they", "their", "he", "his", "she", "her", "if", "then", "else",
+        "when", "where", "which", "who", "what", "how", "all", "each",
+        "every", "both", "few", "more", "most", "other", "some", "such",
+        "no", "not", "only", "same", "so", "than", "too", "very", "just",
+        "also", "now", "here", "there", "any", "into", "out", "up", "down",
+    }
+
+    return [w for w in words if w not in stopwords]
+
+
+def compute_tfidf(documents: list[ToolText]) -> None:
+    """Compute TF-IDF vectors for all documents (modifies in place)."""
+    # Tokenize all documents
+    for doc in documents:
+        doc.tokens = tokenize(doc.text)
+
+    # Compute document frequencies
+    doc_freq = Counter()
+    for doc in documents:
+        unique_tokens = set(doc.tokens)
+        doc_freq.update(unique_tokens)
+
+    num_docs = len(documents)
+
+    # Compute TF-IDF for each document
+    for doc in documents:
+        term_freq = Counter(doc.tokens)
+        total_terms = len(doc.tokens) or 1
+
+        tfidf = {}
+        for term, count in term_freq.items():
+            tf = count / total_terms
+            # Add 1 to avoid division by zero
+            idf = math.log((num_docs + 1) / (doc_freq[term] + 1)) + 1
+            tfidf[term] = tf * idf
+
+        doc.tfidf = tfidf
+
+
+def cosine_similarity(vec1: dict, vec2: dict) -> float:
+    """Compute cosine similarity between two TF-IDF vectors."""
+    # Get all terms
+    all_terms = set(vec1.keys()) | set(vec2.keys())
+
+    if not all_terms:
+        return 0.0
+
+    # Compute dot product and magnitudes
+    dot_product = 0.0
+    mag1 = 0.0
+    mag2 = 0.0
+
+    for term in all_terms:
+        v1 = vec1.get(term, 0.0)
+        v2 = vec2.get(term, 0.0)
+        dot_product += v1 * v2
+        mag1 += v1 * v1
+        mag2 += v2 * v2
+
+    mag1 = math.sqrt(mag1)
+    mag2 = math.sqrt(mag2)
+
+    if mag1 == 0 or mag2 == 0:
+        return 0.0
+
+    return dot_product / (mag1 * mag2)
+
+
+def classify_similarity(score: float) -> str:
+    """Classify similarity score into a match type."""
+    if score >= DUPLICATE_THRESHOLD:
+        return "duplicate"
+    elif score >= SIMILAR_THRESHOLD:
+        return "similar"
+    elif score >= RELATED_THRESHOLD:
+        return "related"
+    return "different"
+
+
+def find_similar(tool: ToolText, corpus: list[ToolText], threshold: float = RELATED_THRESHOLD) -> list[SimilarityMatch]:
+    """Find tools in corpus similar to the given tool."""
+    matches = []
+
+    for other in corpus:
+        if other.path == tool.path:
+            continue
+
+        similarity = cosine_similarity(tool.tfidf, other.tfidf)
+
+        if similarity >= threshold:
+            match_type = classify_similarity(similarity)
+            matches.append(SimilarityMatch(
+                tool1_name=tool.name,
+                tool1_path=tool.path,
+                tool2_name=other.name,
+                tool2_path=other.path,
+                similarity=similarity,
+                match_type=match_type,
+            ))
+
+    # Sort by similarity descending
+    matches.sort(key=lambda m: m.similarity, reverse=True)
+    return matches
+
+
+def scan_directory(directory: Path, threshold: float = RELATED_THRESHOLD) -> list[SimilarityMatch]:
+    """Scan a directory for similar tool pairs."""
+    # Load all tools
+    tools = []
+    for entry in directory.iterdir():
+        config_file = None
+        if entry.is_dir():
+            config_file = entry / "config.yaml"
+        elif entry.suffix in [".yaml", ".yml"]:
+            config_file = entry
+
+        if config_file and config_file.exists():
+            config = load_tool_config(config_file)
+            if config:
+                tool_text = extract_tool_text(config, str(entry))
+                tools.append(tool_text)
+
+    if len(tools) < 2:
+        return []
+
+    # Compute TF-IDF
+    compute_tfidf(tools)
+
+    # Find all similar pairs
+    matches = []
+    seen_pairs = set()
+
+    for tool in tools:
+        for other in tools:
+            if tool.path >= other.path:  # Avoid duplicates
+                continue
+
+            pair_key = (tool.path, other.path)
+            if pair_key in seen_pairs:
+                continue
+            seen_pairs.add(pair_key)
+
+            similarity = cosine_similarity(tool.tfidf, other.tfidf)
+
+            if similarity >= threshold:
+                match_type = classify_similarity(similarity)
+                matches.append(SimilarityMatch(
+                    tool1_name=tool.name,
+                    tool1_path=tool.path,
+                    tool2_name=other.name,
+                    tool2_path=other.path,
+                    similarity=similarity,
+                    match_type=match_type,
+                ))
+
+    # Sort by similarity descending
+    matches.sort(key=lambda m: m.similarity, reverse=True)
+    return matches
+
+
+def load_corpus(directory: Path) -> list[ToolText]:
+    """Load all tools from a directory as ToolText objects."""
+    tools = []
+
+    for entry in directory.iterdir():
+        config_file = None
+        if entry.is_dir():
+            config_file = entry / "config.yaml"
+        elif entry.suffix in [".yaml", ".yml"]:
+            config_file = entry
+
+        if config_file and config_file.exists():
+            config = load_tool_config(config_file)
+            if config:
+                tool_text = extract_tool_text(config, str(entry))
+                tools.append(tool_text)
+
+    return tools
+
+
+def print_match(match: SimilarityMatch, verbose: bool = False):
+    """Print a similarity match to console."""
+    # Match type emoji
+    type_emoji = {
+        "duplicate": "🔴",
+        "similar": "🟠",
+        "related": "🟡",
+    }
+
+    emoji = type_emoji.get(match.match_type, "⚪")
+    bar = "█" * int(match.similarity * 20) + "░" * (20 - int(match.similarity * 20))
+
+    print(f"  {emoji} {match.match_type.upper()} [{bar}] {match.similarity:.2%}")
+    print(f"     {match.tool1_name} <-> {match.tool2_name}")
+
+    if verbose:
+        print(f"     Paths: {match.tool1_path}")
+        print(f"            {match.tool2_path}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Find similar/duplicate CmdForge tools",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__
+    )
+
+    parser.add_argument(
+        "path",
+        type=Path,
+        nargs="?",
+        help="Tool config file to check"
+    )
+    parser.add_argument(
+        "--against",
+        type=Path,
+        default=Path.home() / ".cmdforge",
+        help="Directory to compare against (default: ~/.cmdforge)"
+    )
+    parser.add_argument(
+        "--scan",
+        type=Path,
+        metavar="DIR",
+        help="Scan directory for all similar pairs"
+    )
+    parser.add_argument(
+        "--threshold", "-t",
+        type=float,
+        default=RELATED_THRESHOLD,
+        help=f"Similarity threshold (default: {RELATED_THRESHOLD})"
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output as JSON"
+    )
+    parser.add_argument(
+        "--verbose", "-v",
+        action="store_true",
+        help="Show detailed output"
+    )
+
+    args = parser.parse_args()
+
+    matches = []
+
+    if args.scan:
+        # Scan mode - find all similar pairs
+        print(f"Scanning {args.scan} for similar tools...")
+        matches = scan_directory(args.scan, args.threshold)
+    elif args.path:
+        # Check single tool against corpus
+        config = load_tool_config(args.path)
+        if not config:
+            print(f"Error: Could not load tool config from {args.path}", file=sys.stderr)
+            return 1
+
+        tool_text = extract_tool_text(config, str(args.path))
+
+        # Load corpus
+        corpus = load_corpus(args.against)
+        if not corpus:
+            print(f"No tools found in {args.against}", file=sys.stderr)
+            return 1
+
+        # Add the new tool to corpus for TF-IDF computation
+        all_tools = corpus + [tool_text]
+        compute_tfidf(all_tools)
+
+        print(f"Checking {tool_text.name} against {len(corpus)} existing tools...")
+        matches = find_similar(tool_text, corpus, args.threshold)
+    else:
+        parser.error("Specify a tool path or use --scan")
+
+    # Output
+    if args.json:
+        output = [m.to_dict() for m in matches]
+        print(json.dumps(output, indent=2))
+    else:
+        if not matches:
+            print("\n✅ No similar tools found above threshold")
+        else:
+            print(f"\nFound {len(matches)} match(es):\n")
+            for match in matches:
+                print_match(match, args.verbose)
+
+            # Summary by type
+            duplicates = sum(1 for m in matches if m.match_type == "duplicate")
+            similar = sum(1 for m in matches if m.match_type == "similar")
+            related = sum(1 for m in matches if m.match_type == "related")
+
+            print(f"\n{'─' * 40}")
+            print(f"Summary: {duplicates} duplicates, {similar} similar, {related} related")
+
+    # Return code
+    has_duplicates = any(m.match_type == "duplicate" for m in matches)
+    has_similar = any(m.match_type == "similar" for m in matches)
+
+    if has_duplicates:
+        return 2
+    elif has_similar:
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/sync_to_db.py

@@ -16,8 +16,8 @@ import yaml
 # Allow running from repo root
 sys.path.append(str(Path(__file__).resolve().parents[1] / "src"))
 
-from smarttools.registry.db import connect_db, query_one
-from smarttools.registry.sync import ensure_publisher, normalize_tags
+from cmdforge.registry.db import connect_db, query_one
+from cmdforge.registry.sync import ensure_publisher, normalize_tags
 
 
 def load_yaml(path: Path) -> Dict[str, Any]:

scripts/test_nodegraph.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""Test script for NodeGraphQt integration."""
+
+import sys
+from PySide6.QtWidgets import QApplication, QMainWindow, QVBoxLayout, QWidget
+from NodeGraphQt import NodeGraph, BaseNode
+
+
+class InputNode(BaseNode):
+    """Node representing tool input."""
+
+    __identifier__ = 'cmdforge.nodes'
+    NODE_NAME = 'Input'
+
+    def __init__(self):
+        super().__init__()
+        self.set_color(100, 100, 180)  # Blue-ish
+        self.add_output('input', color=(180, 180, 250))
+        self.add_output('file', color=(180, 180, 250))
+
+
+class PromptNode(BaseNode):
+    """Node representing a prompt step."""
+
+    __identifier__ = 'cmdforge.nodes'
+    NODE_NAME = 'Prompt'
+
+    def __init__(self):
+        super().__init__()
+        self.set_color(80, 120, 180)  # Indigo-ish
+        self.add_input('in', color=(180, 180, 250))
+        self.add_output('response', color=(180, 250, 180))
+
+        # Add properties
+        self.add_text_input('provider', 'Provider', text='claude')
+        self.add_text_input('output_var', 'Output Var', text='response')
+
+
+class CodeNode(BaseNode):
+    """Node representing a code step."""
+
+    __identifier__ = 'cmdforge.nodes'
+    NODE_NAME = 'Code'
+
+    def __init__(self):
+        super().__init__()
+        self.set_color(80, 160, 100)  # Green-ish
+        self.add_input('in', color=(180, 250, 180))
+        self.add_output('result', color=(250, 220, 180))
+
+        # Add properties
+        self.add_text_input('output_var', 'Output Var', text='result')
+
+
+class OutputNode(BaseNode):
+    """Node representing tool output."""
+
+    __identifier__ = 'cmdforge.nodes'
+    NODE_NAME = 'Output'
+
+    def __init__(self):
+        super().__init__()
+        self.set_color(180, 120, 80)  # Orange-ish
+        self.add_input('in', color=(250, 220, 180))
+
+
+def main():
+    app = QApplication(sys.argv)
+
+    # Create main window
+    window = QMainWindow()
+    window.setWindowTitle('CmdForge Flow Visualization - Prototype')
+    window.setGeometry(100, 100, 1000, 700)
+
+    # Create node graph
+    graph = NodeGraph()
+
+    # Register our custom nodes
+    graph.register_node(InputNode)
+    graph.register_node(PromptNode)
+    graph.register_node(CodeNode)
+    graph.register_node(OutputNode)
+
+    # Get the graph widget
+    graph_widget = graph.widget
+
+    # Set as central widget
+    window.setCentralWidget(graph_widget)
+
+    # Create a sample tool visualization
+    input_node = graph.create_node('cmdforge.nodes.InputNode', name='Input')
+    input_node.set_pos(-300, 0)
+
+    prompt_node = graph.create_node('cmdforge.nodes.PromptNode', name='Summarize')
+    prompt_node.set_pos(-50, 0)
+    prompt_node.set_property('provider', 'claude')
+    prompt_node.set_property('output_var', 'response')
+
+    code_node = graph.create_node('cmdforge.nodes.CodeNode', name='Format')
+    code_node.set_pos(200, 0)
+    code_node.set_property('output_var', 'formatted')
+
+    output_node = graph.create_node('cmdforge.nodes.OutputNode', name='Output')
+    output_node.set_pos(450, 0)
+
+    # Connect nodes
+    input_node.output(0).connect_to(prompt_node.input(0))
+    prompt_node.output(0).connect_to(code_node.input(0))
+    code_node.output(0).connect_to(output_node.input(0))
+
+    # Auto-layout
+    graph.auto_layout_nodes()
+
+    # Fit view
+    graph.fit_to_selection()
+
+    window.show()
+
+    print("Flow visualization prototype running...")
+    print("Nodes created: Input -> Prompt -> Code -> Output")
+    print("Close the window to exit.")
+
+    sys.exit(app.exec())
+
+
+if __name__ == '__main__':
+    main()

scripts/vet_pipeline.py

@@ -0,0 +1,379 @@
+#!/usr/bin/env python3
+"""
+Auto-vetting pipeline for CmdForge tool submissions.
+
+Combines scrutiny (quality checks) and similarity (duplicate detection)
+to automatically triage incoming tools:
+- Auto-approve: High quality, no duplicates
+- Auto-reject: Low quality or exact duplicates
+- Review queue: Needs human review
+
+Usage:
+    # Vet a single tool
+    python scripts/vet_pipeline.py path/to/tool/config.yaml
+
+    # Vet with custom thresholds
+    python scripts/vet_pipeline.py --approve-threshold 0.85 path/to/tool/config.yaml
+
+    # Process all tools in import directory
+    python scripts/vet_pipeline.py --batch /tmp/fabric-import/
+
+    # Output detailed JSON report
+    python scripts/vet_pipeline.py --json path/to/tool/config.yaml
+"""
+
+import argparse
+import json
+import sys
+from dataclasses import dataclass, asdict
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+# Import our vetting modules
+from scrutiny import (
+    VetResult as ScrutinyResult,
+    VetReport,
+    load_tool_config,
+    vet_tool,
+)
+from similarity import (
+    ToolText,
+    SimilarityMatch,
+    extract_tool_text,
+    load_corpus,
+    compute_tfidf,
+    find_similar,
+    DUPLICATE_THRESHOLD,
+    SIMILAR_THRESHOLD,
+)
+
+
+class PipelineDecision(Enum):
+    """Final pipeline decision."""
+    AUTO_APPROVE = "auto_approve"
+    AUTO_REJECT = "auto_reject"
+    NEEDS_REVIEW = "needs_review"
+    ERROR = "error"
+
+
+@dataclass
+class PipelineResult:
+    """Complete pipeline result for a tool."""
+    tool_name: str
+    tool_path: str
+    decision: PipelineDecision
+    reason: str
+    scrutiny_report: Optional[VetReport] = None
+    similarity_matches: list = None
+    suggestions: list = None
+
+    def __post_init__(self):
+        if self.similarity_matches is None:
+            self.similarity_matches = []
+        if self.suggestions is None:
+            self.suggestions = []
+
+    def to_dict(self) -> dict:
+        d = {
+            "tool_name": self.tool_name,
+            "tool_path": self.tool_path,
+            "decision": self.decision.value,
+            "reason": self.reason,
+            "suggestions": self.suggestions,
+        }
+        if self.scrutiny_report:
+            d["scrutiny"] = self.scrutiny_report.to_dict()
+        if self.similarity_matches:
+            d["similar_tools"] = [m.to_dict() for m in self.similarity_matches]
+        return d
+
+
+# Pipeline thresholds
+DEFAULT_APPROVE_THRESHOLD = 0.8
+DEFAULT_REJECT_THRESHOLD = 0.3
+
+
+def run_pipeline(
+    tool_path: Path,
+    corpus_dir: Path,
+    approve_threshold: float = DEFAULT_APPROVE_THRESHOLD,
+    reject_threshold: float = DEFAULT_REJECT_THRESHOLD,
+) -> PipelineResult:
+    """Run the complete vetting pipeline on a tool."""
+
+    # Load tool config
+    config = load_tool_config(tool_path)
+    if not config:
+        return PipelineResult(
+            tool_name="unknown",
+            tool_path=str(tool_path),
+            decision=PipelineDecision.ERROR,
+            reason=f"Could not load tool config from {tool_path}",
+        )
+
+    tool_name = config.get("name", "unknown")
+
+    # Phase 1: Scrutiny (quality checks)
+    scrutiny_report = vet_tool(config, str(tool_path))
+
+    # Phase 2: Similarity check
+    tool_text = extract_tool_text(config, str(tool_path))
+    corpus = load_corpus(corpus_dir) if corpus_dir.exists() else []
+
+    similarity_matches = []
+    if corpus:
+        all_tools = corpus + [tool_text]
+        compute_tfidf(all_tools)
+        similarity_matches = find_similar(tool_text, corpus, threshold=0.5)
+
+    # Phase 3: Decision logic
+    decision, reason, suggestions = make_decision(
+        scrutiny_report,
+        similarity_matches,
+        approve_threshold,
+        reject_threshold,
+    )
+
+    return PipelineResult(
+        tool_name=tool_name,
+        tool_path=str(tool_path),
+        decision=decision,
+        reason=reason,
+        scrutiny_report=scrutiny_report,
+        similarity_matches=similarity_matches,
+        suggestions=suggestions,
+    )
+
+
+def make_decision(
+    scrutiny: VetReport,
+    similarity_matches: list[SimilarityMatch],
+    approve_threshold: float,
+    reject_threshold: float,
+) -> tuple[PipelineDecision, str, list[str]]:
+    """Make final decision based on scrutiny and similarity results."""
+
+    suggestions = list(scrutiny.suggestions) if scrutiny.suggestions else []
+    score = scrutiny.overall_score
+
+    # Check for exact duplicates first
+    duplicates = [m for m in similarity_matches if m.match_type == "duplicate"]
+    if duplicates:
+        dupe = duplicates[0]
+        return (
+            PipelineDecision.AUTO_REJECT,
+            f"Duplicate of existing tool '{dupe.tool2_name}' ({dupe.similarity:.0%} match)",
+            suggestions + [f"Consider updating {dupe.tool2_name} instead of creating a new tool"],
+        )
+
+    # Check for very similar tools
+    similar = [m for m in similarity_matches if m.match_type == "similar"]
+    if similar:
+        # If high quality + similar, might be an improved version - needs review
+        if score >= approve_threshold:
+            sim = similar[0]
+            return (
+                PipelineDecision.NEEDS_REVIEW,
+                f"High quality but similar to '{sim.tool2_name}' ({sim.similarity:.0%})",
+                suggestions + [f"Review whether this improves on {sim.tool2_name}"],
+            )
+        else:
+            sim = similar[0]
+            return (
+                PipelineDecision.NEEDS_REVIEW,
+                f"Similar to existing tool '{sim.tool2_name}' ({sim.similarity:.0%})",
+                suggestions + [f"Consider if this duplicates {sim.tool2_name}"],
+            )
+
+    # No duplicates or very similar tools - decide based on quality
+    if scrutiny.result == ScrutinyResult.REJECT or score < reject_threshold:
+        return (
+            PipelineDecision.AUTO_REJECT,
+            f"Quality score too low ({score:.2f} < {reject_threshold})",
+            suggestions,
+        )
+
+    if scrutiny.result == ScrutinyResult.APPROVE and score >= approve_threshold:
+        return (
+            PipelineDecision.AUTO_APPROVE,
+            f"High quality score ({score:.2f}) with no similar tools",
+            suggestions,
+        )
+
+    # Middle ground - needs review
+    return (
+        PipelineDecision.NEEDS_REVIEW,
+        f"Quality score {score:.2f} - needs human review",
+        suggestions,
+    )
+
+
+def print_result(result: PipelineResult, verbose: bool = False):
+    """Print pipeline result to console."""
+    decision_emoji = {
+        PipelineDecision.AUTO_APPROVE: "✅",
+        PipelineDecision.AUTO_REJECT: "❌",
+        PipelineDecision.NEEDS_REVIEW: "⚠️",
+        PipelineDecision.ERROR: "💥",
+    }
+
+    decision_color = {
+        PipelineDecision.AUTO_APPROVE: "\033[92m",  # Green
+        PipelineDecision.AUTO_REJECT: "\033[91m",   # Red
+        PipelineDecision.NEEDS_REVIEW: "\033[93m",  # Yellow
+        PipelineDecision.ERROR: "\033[91m",         # Red
+    }
+
+    reset = "\033[0m"
+    emoji = decision_emoji.get(result.decision, "❓")
+    color = decision_color.get(result.decision, "")
+
+    print(f"\n{emoji} {color}{result.tool_name}: {result.decision.value.upper()}{reset}")
+    print(f"   {result.reason}")
+
+    if verbose:
+        print(f"   Path: {result.tool_path}")
+
+        if result.scrutiny_report:
+            print(f"\n   Quality Scores:")
+            for score in result.scrutiny_report.scores:
+                bar = "█" * int(score.score * 10) + "░" * (10 - int(score.score * 10))
+                print(f"      {score.criterion:12} [{bar}] {score.score:.2f}")
+
+        if result.similarity_matches:
+            print(f"\n   Similar Tools:")
+            for match in result.similarity_matches[:3]:
+                print(f"      • {match.tool2_name} ({match.similarity:.0%} {match.match_type})")
+
+        if result.suggestions:
+            print(f"\n   Suggestions:")
+            for suggestion in result.suggestions[:5]:
+                print(f"      • {suggestion}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Run auto-vetting pipeline on CmdForge tools",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__
+    )
+
+    parser.add_argument(
+        "path",
+        type=Path,
+        nargs="?",
+        help="Tool config file or directory to vet"
+    )
+    parser.add_argument(
+        "--batch",
+        type=Path,
+        metavar="DIR",
+        help="Process all tools in directory"
+    )
+    parser.add_argument(
+        "--corpus",
+        type=Path,
+        default=Path.home() / ".cmdforge",
+        help="Directory of existing tools for comparison (default: ~/.cmdforge)"
+    )
+    parser.add_argument(
+        "--approve-threshold",
+        type=float,
+        default=DEFAULT_APPROVE_THRESHOLD,
+        help=f"Score threshold for auto-approve (default: {DEFAULT_APPROVE_THRESHOLD})"
+    )
+    parser.add_argument(
+        "--reject-threshold",
+        type=float,
+        default=DEFAULT_REJECT_THRESHOLD,
+        help=f"Score threshold for auto-reject (default: {DEFAULT_REJECT_THRESHOLD})"
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output as JSON"
+    )
+    parser.add_argument(
+        "--verbose", "-v",
+        action="store_true",
+        help="Show detailed output"
+    )
+
+    args = parser.parse_args()
+
+    if not args.path and not args.batch:
+        parser.error("Specify a tool path or use --batch")
+
+    results = []
+
+    if args.batch:
+        # Batch mode
+        batch_dir = args.batch
+        if not batch_dir.exists():
+            print(f"Error: Directory {batch_dir} does not exist", file=sys.stderr)
+            return 1
+
+        print(f"Processing tools in {batch_dir}...")
+
+        for entry in sorted(batch_dir.iterdir()):
+            config_file = None
+            if entry.is_dir():
+                config_file = entry / "config.yaml"
+            elif entry.suffix in [".yaml", ".yml"]:
+                config_file = entry
+
+            if config_file and config_file.exists():
+                result = run_pipeline(
+                    config_file,
+                    args.corpus,
+                    args.approve_threshold,
+                    args.reject_threshold,
+                )
+                results.append(result)
+    else:
+        # Single tool mode
+        result = run_pipeline(
+            args.path,
+            args.corpus,
+            args.approve_threshold,
+            args.reject_threshold,
+        )
+        results.append(result)
+
+    # Output
+    if args.json:
+        output = [r.to_dict() for r in results]
+        print(json.dumps(output, indent=2))
+    else:
+        for result in results:
+            print_result(result, args.verbose)
+
+        # Summary
+        if len(results) > 1:
+            approved = sum(1 for r in results if r.decision == PipelineDecision.AUTO_APPROVE)
+            rejected = sum(1 for r in results if r.decision == PipelineDecision.AUTO_REJECT)
+            review = sum(1 for r in results if r.decision == PipelineDecision.NEEDS_REVIEW)
+            errors = sum(1 for r in results if r.decision == PipelineDecision.ERROR)
+
+            print(f"\n{'═' * 50}")
+            print(f"Pipeline Summary: {len(results)} tools processed")
+            print(f"  ✅ Auto-approved: {approved}")
+            print(f"  ⚠️  Needs review: {review}")
+            print(f"  ❌ Auto-rejected: {rejected}")
+            if errors:
+                print(f"  💥 Errors: {errors}")
+
+    # Return codes
+    has_rejected = any(r.decision == PipelineDecision.AUTO_REJECT for r in results)
+    has_review = any(r.decision == PipelineDecision.NEEDS_REVIEW for r in results)
+
+    if has_rejected:
+        return 2
+    elif has_review:
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

src/cmdforge/__init__.py

@@ -0,0 +1,3 @@
+"""CmdForge - A lightweight personal tool builder for AI-powered CLI commands."""
+
+__version__ = "0.1.0"

src/cmdforge/cli.py

@@ -0,0 +1,11 @@
+"""CLI entry point for CmdForge.
+
+This module is a thin wrapper for backwards compatibility.
+The actual implementation is in the cli/ package.
+"""
+
+from .cli import main
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(main())

src/cmdforge/cli/__init__.py

@@ -0,0 +1,271 @@
+"""CLI entry point for CmdForge."""
+
+import argparse
+import sys
+
+from .. import __version__
+
+from .tool_commands import (
+    cmd_list, cmd_create, cmd_edit, cmd_delete, cmd_test, cmd_run,
+    cmd_ui, cmd_refresh, cmd_docs, cmd_check
+)
+from .provider_commands import cmd_providers
+from .registry_commands import cmd_registry
+from .project_commands import cmd_deps, cmd_install_deps, cmd_add, cmd_init
+from .config_commands import cmd_config
+
+
+def main():
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="cmdforge",
+        description="A lightweight personal tool builder for AI-powered CLI commands"
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # No command = launch UI
+    # 'list' command
+    p_list = subparsers.add_parser("list", help="List all tools")
+    p_list.set_defaults(func=cmd_list)
+
+    # 'create' command
+    p_create = subparsers.add_parser("create", help="Create a new tool")
+    p_create.add_argument("name", help="Tool name")
+    p_create.add_argument("-d", "--description", help="Tool description")
+    p_create.add_argument("-p", "--prompt", help="Prompt template")
+    p_create.add_argument("--provider", help="AI provider (default: mock)")
+    p_create.add_argument("-f", "--force", action="store_true", help="Overwrite existing")
+    p_create.set_defaults(func=cmd_create)
+
+    # 'edit' command
+    p_edit = subparsers.add_parser("edit", help="Edit a tool config")
+    p_edit.add_argument("name", help="Tool name")
+    p_edit.set_defaults(func=cmd_edit)
+
+    # 'delete' command
+    p_delete = subparsers.add_parser("delete", help="Delete a tool")
+    p_delete.add_argument("name", help="Tool name")
+    p_delete.add_argument("-f", "--force", action="store_true", help="Skip confirmation")
+    p_delete.set_defaults(func=cmd_delete)
+
+    # 'test' command
+    p_test = subparsers.add_parser("test", help="Test a tool with mock provider")
+    p_test.add_argument("name", help="Tool name")
+    p_test.add_argument("-i", "--input", help="Input file for testing")
+    p_test.add_argument("--dry-run", action="store_true", help="Show prompt only")
+    p_test.set_defaults(func=cmd_test)
+
+    # 'run' command
+    p_run = subparsers.add_parser("run", help="Run a tool")
+    p_run.add_argument("name", help="Tool name")
+    p_run.add_argument("-i", "--input", help="Input file (reads from stdin if piped)")
+    p_run.add_argument("-o", "--output", help="Output file (writes to stdout if omitted)")
+    p_run.add_argument("--stdin", action="store_true", help="Read input interactively (type then Ctrl+D)")
+    p_run.add_argument("-p", "--provider", help="Override provider")
+    p_run.add_argument("--dry-run", action="store_true", help="Show what would happen without executing")
+    p_run.add_argument("--show-prompt", action="store_true", help="Show prompts in addition to output")
+    p_run.add_argument("-v", "--verbose", action="store_true", help="Show debug information")
+    p_run.add_argument("tool_args", nargs="*", help="Additional tool-specific arguments")
+    p_run.set_defaults(func=cmd_run)
+
+    # 'ui' command (explicit)
+    p_ui = subparsers.add_parser("ui", help="Launch interactive UI")
+    p_ui.set_defaults(func=cmd_ui)
+
+    # 'refresh' command
+    p_refresh = subparsers.add_parser("refresh", help="Refresh all wrapper scripts")
+    p_refresh.set_defaults(func=cmd_refresh)
+
+    # 'docs' command
+    p_docs = subparsers.add_parser("docs", help="View or edit tool documentation")
+    p_docs.add_argument("name", help="Tool name")
+    p_docs.add_argument("-e", "--edit", action="store_true", help="Edit/create README in $EDITOR")
+    p_docs.set_defaults(func=cmd_docs)
+
+    # 'check' command
+    p_check = subparsers.add_parser("check", help="Check dependencies for a tool (meta-tools)")
+    p_check.add_argument("name", help="Tool name")
+    p_check.set_defaults(func=cmd_check)
+
+    # 'providers' command
+    p_providers = subparsers.add_parser("providers", help="Manage AI providers")
+    providers_sub = p_providers.add_subparsers(dest="providers_cmd", help="Provider commands")
+
+    # providers list
+    p_prov_list = providers_sub.add_parser("list", help="List all providers and their status")
+    p_prov_list.set_defaults(func=cmd_providers)
+
+    # providers check
+    p_prov_check = providers_sub.add_parser("check", help="Check which providers are available")
+    p_prov_check.set_defaults(func=cmd_providers)
+
+    # providers install
+    p_prov_install = providers_sub.add_parser("install", help="Interactive guide to install AI providers")
+    p_prov_install.set_defaults(func=cmd_providers)
+
+    # providers add
+    p_prov_add = providers_sub.add_parser("add", help="Add or update a provider")
+    p_prov_add.add_argument("name", help="Provider name")
+    p_prov_add.add_argument("command", help="Command to run (e.g., 'claude -p')")
+    p_prov_add.add_argument("-d", "--description", help="Provider description")
+    p_prov_add.set_defaults(func=cmd_providers)
+
+    # providers remove
+    p_prov_remove = providers_sub.add_parser("remove", help="Remove a provider")
+    p_prov_remove.add_argument("name", help="Provider name")
+    p_prov_remove.set_defaults(func=cmd_providers)
+
+    # providers test
+    p_prov_test = providers_sub.add_parser("test", help="Test a provider")
+    p_prov_test.add_argument("name", help="Provider name")
+    p_prov_test.set_defaults(func=cmd_providers)
+
+    # Default for providers with no subcommand
+    p_providers.set_defaults(func=lambda args: cmd_providers(args) if args.providers_cmd else (setattr(args, 'providers_cmd', 'list') or cmd_providers(args)))
+
+    # -------------------------------------------------------------------------
+    # Registry Commands
+    # -------------------------------------------------------------------------
+    p_registry = subparsers.add_parser("registry", help="Registry commands (search, install, publish)")
+    registry_sub = p_registry.add_subparsers(dest="registry_cmd", help="Registry commands")
+
+    # registry search
+    p_reg_search = registry_sub.add_parser("search", help="Search for tools")
+    p_reg_search.add_argument("query", help="Search query")
+    p_reg_search.add_argument("-c", "--category", help="Filter by category")
+    p_reg_search.add_argument("-t", "--tag", action="append", dest="tags", help="Filter by tag (repeatable, AND logic)")
+    p_reg_search.add_argument("-o", "--owner", help="Filter by publisher/owner")
+    p_reg_search.add_argument("--min-downloads", type=int, help="Minimum downloads")
+    p_reg_search.add_argument("--popular", action="store_true", help="Shortcut for --min-downloads 100")
+    p_reg_search.add_argument("--new", action="store_true", help="Shortcut for --max-downloads 10")
+    p_reg_search.add_argument("--since", help="Published after date (YYYY-MM-DD)")
+    p_reg_search.add_argument("--before", help="Published before date (YYYY-MM-DD)")
+    p_reg_search.add_argument("-s", "--sort", choices=["relevance", "downloads", "published_at", "name"], default="relevance", help="Sort by field")
+    p_reg_search.add_argument("-l", "--limit", type=int, help="Max results (default: 20)")
+    p_reg_search.add_argument("--json", action="store_true", help="Output as JSON")
+    p_reg_search.add_argument("--show-facets", action="store_true", help="Show category/tag counts")
+    p_reg_search.add_argument("--deprecated", action="store_true", help="Include deprecated tools")
+    p_reg_search.set_defaults(func=cmd_registry)
+
+    # registry tags
+    p_reg_tags = registry_sub.add_parser("tags", help="List available tags")
+    p_reg_tags.add_argument("-c", "--category", help="Filter tags by category")
+    p_reg_tags.add_argument("-l", "--limit", type=int, default=50, help="Max tags to show (default: 50)")
+    p_reg_tags.add_argument("--json", action="store_true", help="Output as JSON")
+    p_reg_tags.set_defaults(func=cmd_registry)
+
+    # registry install
+    p_reg_install = registry_sub.add_parser("install", help="Install a tool from registry")
+    p_reg_install.add_argument("tool", help="Tool to install (owner/name or name)")
+    p_reg_install.add_argument("-v", "--version", help="Version constraint")
+    p_reg_install.set_defaults(func=cmd_registry)
+
+    # registry uninstall
+    p_reg_uninstall = registry_sub.add_parser("uninstall", help="Uninstall a tool")
+    p_reg_uninstall.add_argument("tool", help="Tool to uninstall (owner/name)")
+    p_reg_uninstall.set_defaults(func=cmd_registry)
+
+    # registry info
+    p_reg_info = registry_sub.add_parser("info", help="Show tool information")
+    p_reg_info.add_argument("tool", help="Tool name (owner/name)")
+    p_reg_info.set_defaults(func=cmd_registry)
+
+    # registry update
+    p_reg_update = registry_sub.add_parser("update", help="Update local index cache")
+    p_reg_update.set_defaults(func=cmd_registry)
+
+    # registry publish
+    p_reg_publish = registry_sub.add_parser("publish", help="Publish a tool to registry")
+    p_reg_publish.add_argument("path", nargs="?", help="Path to tool directory (default: current dir)")
+    p_reg_publish.add_argument("--dry-run", action="store_true", help="Validate without publishing")
+    p_reg_publish.set_defaults(func=cmd_registry)
+
+    # registry my-tools
+    p_reg_mytools = registry_sub.add_parser("my-tools", help="List your published tools")
+    p_reg_mytools.set_defaults(func=cmd_registry)
+
+    # registry browse
+    p_reg_browse = registry_sub.add_parser("browse", help="Browse tools (TUI)")
+    p_reg_browse.set_defaults(func=cmd_registry)
+
+    # registry config (admin settings management)
+    p_reg_config = registry_sub.add_parser("config", help="Manage registry settings (admin)")
+    p_reg_config.add_argument("action", nargs="?", choices=["list", "get", "set"], default="list",
+                              help="Action to perform (default: list)")
+    p_reg_config.add_argument("key", nargs="?", help="Setting key (for get/set)")
+    p_reg_config.add_argument("value", nargs="?", help="Setting value (for set)")
+    p_reg_config.add_argument("--json", action="store_true", help="Output as JSON")
+    p_reg_config.add_argument("--category", "-c", help="Filter by category (for list)")
+    p_reg_config.set_defaults(func=cmd_registry)
+
+    # Default for registry with no subcommand
+    p_registry.set_defaults(func=lambda args: cmd_registry(args) if args.registry_cmd else (setattr(args, 'registry_cmd', None) or cmd_registry(args)))
+
+    # -------------------------------------------------------------------------
+    # Project Commands
+    # -------------------------------------------------------------------------
+
+    # 'deps' command
+    p_deps = subparsers.add_parser("deps", help="Show project dependencies")
+    p_deps.set_defaults(func=cmd_deps)
+
+    # 'install' command (for dependencies)
+    p_install = subparsers.add_parser("install", help="Install dependencies from cmdforge.yaml")
+    p_install.set_defaults(func=cmd_install_deps)
+
+    # 'add' command
+    p_add = subparsers.add_parser("add", help="Add a tool to project dependencies")
+    p_add.add_argument("tool", help="Tool to add (owner/name)")
+    p_add.add_argument("-v", "--version", help="Version constraint (default: *)")
+    p_add.add_argument("--no-install", action="store_true", help="Don't install after adding")
+    p_add.set_defaults(func=cmd_add)
+
+    # 'init' command
+    p_init = subparsers.add_parser("init", help="Initialize cmdforge.yaml")
+    p_init.add_argument("-n", "--name", help="Project name")
+    p_init.add_argument("-v", "--version", help="Project version")
+    p_init.add_argument("-f", "--force", action="store_true", help="Overwrite existing")
+    p_init.set_defaults(func=cmd_init)
+
+    # -------------------------------------------------------------------------
+    # Config Commands
+    # -------------------------------------------------------------------------
+    p_config = subparsers.add_parser("config", help="Manage configuration")
+    config_sub = p_config.add_subparsers(dest="config_cmd", help="Config commands")
+
+    # config show
+    p_cfg_show = config_sub.add_parser("show", help="Show current configuration")
+    p_cfg_show.set_defaults(func=cmd_config)
+
+    # config set-token
+    p_cfg_token = config_sub.add_parser("set-token", help="Set registry authentication token")
+    p_cfg_token.add_argument("token", help="Registry token")
+    p_cfg_token.set_defaults(func=cmd_config)
+
+    # config set
+    p_cfg_set = config_sub.add_parser("set", help="Set a configuration value")
+    p_cfg_set.add_argument("key", help="Config key")
+    p_cfg_set.add_argument("value", help="Config value")
+    p_cfg_set.set_defaults(func=cmd_config)
+
+    # config connect
+    p_cfg_connect = config_sub.add_parser("connect", help="Connect this app to your CmdForge account")
+    p_cfg_connect.add_argument("username", help="Your CmdForge username")
+    p_cfg_connect.set_defaults(func=cmd_config)
+
+    # Default for config with no subcommand
+    p_config.set_defaults(func=lambda args: cmd_config(args) if args.config_cmd else (setattr(args, 'config_cmd', 'show') or cmd_config(args)))
+
+    args = parser.parse_args()
+
+    # If no command, launch UI
+    if args.command is None:
+        return cmd_ui(args)
+
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

src/cmdforge/cli/__main__.py

@@ -0,0 +1,7 @@
+"""Allow running the CLI as a module."""
+
+import sys
+from . import main
+
+if __name__ == "__main__":
+    sys.exit(main())

src/cmdforge/cli/config_commands.py

@@ -0,0 +1,167 @@
+"""Configuration commands."""
+
+import socket
+import sys
+import time
+
+from ..config import load_config, save_config, set_registry_token, get_registry_url
+
+
+def cmd_config(args):
+    """Manage CmdForge configuration."""
+    if args.config_cmd == "show":
+        return _cmd_config_show(args)
+    elif args.config_cmd == "set-token":
+        return _cmd_config_set_token(args)
+    elif args.config_cmd == "set":
+        return _cmd_config_set(args)
+    elif args.config_cmd == "connect":
+        return _cmd_config_connect(args)
+    else:
+        print("Config commands:")
+        print("  show                 Show current configuration")
+        print("  connect <username>   Connect this app to your CmdForge account")
+        print("  set-token <token>    Set registry authentication token")
+        print("  set <key> <value>    Set a configuration value")
+        return 0
+
+
+def _cmd_config_show(args):
+    """Show current configuration."""
+    config = load_config()
+    print("CmdForge Configuration:")
+    print(f"  Registry URL: {config.registry.url}")
+    print(f"  Token: {'***' if config.registry.token else '(not set)'}")
+    print(f"  Client ID: {config.client_id}")
+    print(f"  Auto-fetch: {config.auto_fetch_from_registry}")
+    if config.default_provider:
+        print(f"  Default provider: {config.default_provider}")
+    return 0
+
+
+def _cmd_config_set_token(args):
+    """Set registry authentication token."""
+    token = args.token
+    set_registry_token(token)
+    print("Registry token saved.")
+    return 0
+
+
+def _cmd_config_set(args):
+    """Set a configuration value."""
+    config = load_config()
+    key = args.key
+    value = args.value
+
+    if key == "auto_fetch":
+        config.auto_fetch_from_registry = value.lower() in ("true", "1", "yes")
+    elif key == "default_provider":
+        config.default_provider = value if value else None
+    elif key == "registry_url":
+        config.registry.url = value
+    else:
+        print(f"Unknown config key: {key}")
+        print("Available keys: auto_fetch, default_provider, registry_url")
+        return 1
+
+    save_config(config)
+    print(f"Set {key} = {value}")
+    return 0
+
+
+def _cmd_config_connect(args):
+    """Connect this app to a CmdForge account via web pairing."""
+    try:
+        import requests
+    except ImportError:
+        print("Error: requests library required. Install with: pip install requests")
+        return 1
+
+    username = args.username
+    hostname = socket.gethostname()
+    registry_url = get_registry_url()
+
+    # Remove trailing /api/v1 if present to get base URL
+    base_url = registry_url.rstrip("/")
+    if base_url.endswith("/api/v1"):
+        base_url = base_url[:-7]
+
+    pairing_url = f"{base_url}/api/v1/pairing/check/{username}"
+
+    print(f"Connecting to CmdForge as @{username}...")
+    print(f"Device: {hostname}")
+    print()
+    print("Waiting for approval from the web interface...")
+    print("Go to https://cmdforge.brrd.tech/dashboard/connected-apps")
+    print("and click 'Connect New App', then 'I've Run the Command'")
+    print()
+    print("Press Ctrl+C to cancel")
+    print()
+
+    # Poll for pairing status
+    max_attempts = 150  # 5 minutes at 2-second intervals
+    attempt = 0
+
+    try:
+        while attempt < max_attempts:
+            attempt += 1
+            try:
+                response = requests.get(
+                    pairing_url,
+                    params={"hostname": hostname},
+                    timeout=10
+                )
+
+                if response.status_code == 200:
+                    data = response.json()
+                    status = data.get("data", {}).get("status")
+
+                    if status == "connected":
+                        token = data.get("data", {}).get("token")
+                        if token:
+                            set_registry_token(token)
+                            print("\nConnected successfully!")
+                            print(f"Your device '{hostname}' is now linked to @{username}")
+                            print("\nYou can now publish tools with: cmdforge registry publish")
+                            return 0
+                        else:
+                            print("\nError: Pairing completed but no token received")
+                            return 1
+                    elif status == "pending":
+                        # Still waiting, continue polling
+                        pass
+                    elif status == "expired":
+                        print("\nPairing request expired. Please try again.")
+                        return 1
+                    elif status == "not_found":
+                        # No pending pairing yet, continue waiting
+                        pass
+                    else:
+                        # Unknown status, keep waiting
+                        pass
+
+                elif response.status_code == 404:
+                    # No pairing found yet, keep waiting
+                    pass
+                else:
+                    # Server error, but keep trying
+                    pass
+
+            except requests.exceptions.RequestException:
+                # Network error, keep trying
+                pass
+
+            # Show progress indicator
+            dots = "." * ((attempt % 3) + 1)
+            sys.stdout.write(f"\rWaiting{dots}   ")
+            sys.stdout.flush()
+
+            time.sleep(2)
+
+        print("\n\nTimed out waiting for approval.")
+        print("Please initiate the connection from the web interface first.")
+        return 1
+
+    except KeyboardInterrupt:
+        print("\n\nConnection cancelled.")
+        return 1

src/cmdforge/cli/project_commands.py

@@ -0,0 +1,202 @@
+"""Project management commands."""
+
+import sys
+from pathlib import Path
+
+from ..manifest import (
+    load_manifest, save_manifest, create_manifest, find_manifest,
+    MANIFEST_FILENAME
+)
+from ..resolver import (
+    find_tool, install_from_registry, ToolSpec
+)
+
+
+def cmd_deps(args):
+    """Show project dependencies from cmdforge.yaml."""
+    manifest = load_manifest()
+
+    if manifest is None:
+        print("No cmdforge.yaml found in current project.")
+        print("Create one with: cmdforge init")
+        return 1
+
+    print(f"Project: {manifest.name} v{manifest.version}")
+    print()
+
+    if not manifest.dependencies:
+        print("No dependencies defined.")
+        print("Add one with: cmdforge add <owner/name>")
+        return 0
+
+    print(f"Dependencies ({len(manifest.dependencies)}):")
+    print()
+
+    for dep in manifest.dependencies:
+        # Check if installed
+        installed = find_tool(dep.name)
+        status = "[installed]" if installed else "[not installed]"
+
+        print(f"  {dep.name}")
+        print(f"    Version: {dep.version}")
+        print(f"    Status: {status}")
+        print()
+
+    if manifest.overrides:
+        print("Overrides:")
+        for name, override in manifest.overrides.items():
+            if override.provider:
+                print(f"  {name}: provider={override.provider}")
+
+    return 0
+
+
+def cmd_install_deps(args):
+    """Install dependencies from cmdforge.yaml."""
+    from ..registry_client import RegistryError
+
+    manifest = load_manifest()
+
+    if manifest is None:
+        print("No cmdforge.yaml found in current project.")
+        print("Create one with: cmdforge init")
+        return 1
+
+    if not manifest.dependencies:
+        print("No dependencies to install.")
+        return 0
+
+    print(f"Installing dependencies for {manifest.name}...")
+    print()
+
+    failed = []
+    installed = []
+
+    for i, dep in enumerate(manifest.dependencies, 1):
+        print(f"[{i}/{len(manifest.dependencies)}] {dep.name}@{dep.version}")
+
+        # Check if already installed
+        existing = find_tool(dep.name)
+        if existing:
+            print(f"  Already installed: {existing.full_name}")
+            installed.append(dep.name)
+            continue
+
+        try:
+            print(f"  Downloading...")
+            resolved = install_from_registry(dep.name, dep.version)
+            print(f"  Installed: {resolved.full_name}@{resolved.version}")
+            installed.append(dep.name)
+        except RegistryError as e:
+            if e.code == "TOOL_NOT_FOUND":
+                print(f"  Not found in registry")
+            elif e.code == "VERSION_NOT_FOUND" or e.code == "CONSTRAINT_UNSATISFIABLE":
+                print(f"  Version {dep.version} not available")
+            elif e.code == "CONNECTION_ERROR":
+                print(f"  Connection failed (check network)")
+            else:
+                print(f"  Failed: {e.message}")
+            failed.append(dep.name)
+        except Exception as e:
+            print(f"  Failed: {e}")
+            failed.append(dep.name)
+
+    print()
+    print(f"Installed {len(installed)} tools")
+
+    if failed:
+        print(f"Failed: {', '.join(failed)}")
+        return 1
+
+    return 0
+
+
+def cmd_add(args):
+    """Add a tool to project dependencies."""
+    from ..registry_client import RegistryError
+
+    tool_spec = args.tool
+    version = args.version or "*"
+
+    # Find or create manifest
+    manifest_path = find_manifest()
+    if manifest_path:
+        manifest = load_manifest(manifest_path)
+    else:
+        # Create in current directory
+        manifest = create_manifest(name=Path.cwd().name)
+        manifest_path = Path.cwd() / MANIFEST_FILENAME
+
+    # Parse tool spec
+    parsed = ToolSpec.parse(tool_spec)
+    full_name = parsed.full_name
+
+    # Add dependency
+    manifest.add_dependency(full_name, version)
+
+    # Save
+    save_manifest(manifest, manifest_path)
+    print(f"Added {full_name}@{version} to {manifest_path.name}")
+
+    # Install if requested
+    if not args.no_install:
+        print(f"Installing {full_name}...")
+        try:
+            resolved = install_from_registry(tool_spec, version if version != "*" else None)
+            print(f"Installed: {resolved.full_name}@{resolved.version}")
+        except RegistryError as e:
+            if e.code == "TOOL_NOT_FOUND":
+                print(f"Tool not found in registry.", file=sys.stderr)
+                print(f"It's been added to your dependencies - you can install it manually later.", file=sys.stderr)
+            elif e.code == "CONNECTION_ERROR":
+                print(f"Could not connect to registry.", file=sys.stderr)
+                print("Run 'cmdforge install' to try again later.", file=sys.stderr)
+            else:
+                print(f"Install failed: {e.message}", file=sys.stderr)
+                print("Run 'cmdforge install' to try again.", file=sys.stderr)
+        except Exception as e:
+            print(f"Install failed: {e}", file=sys.stderr)
+            print("Run 'cmdforge install' to try again.", file=sys.stderr)
+
+    return 0
+
+
+def cmd_init(args):
+    """Initialize a new cmdforge.yaml."""
+    manifest_path = Path.cwd() / MANIFEST_FILENAME
+
+    if manifest_path.exists() and not args.force:
+        print(f"{MANIFEST_FILENAME} already exists. Use --force to overwrite.")
+        return 1
+
+    # Get project name
+    default_name = Path.cwd().name
+    if args.name:
+        name = args.name
+    else:
+        try:
+            name = input(f"Project name [{default_name}]: ").strip() or default_name
+        except (EOFError, KeyboardInterrupt):
+            print()
+            name = default_name
+
+    # Get version
+    if args.version:
+        version = args.version
+    else:
+        try:
+            version = input("Version [1.0.0]: ").strip() or "1.0.0"
+        except (EOFError, KeyboardInterrupt):
+            print()
+            version = "1.0.0"
+
+    # Create manifest
+    manifest = create_manifest(name=name, version=version)
+    save_manifest(manifest, manifest_path)
+
+    print(f"Created {MANIFEST_FILENAME}")
+    print()
+    print("Add dependencies with: cmdforge add <owner/name>")
+    print("Install them with: cmdforge install")
+
+    return 0

src/cmdforge/cli/provider_commands.py

@@ -0,0 +1,307 @@
+"""Provider management commands."""
+
+import shutil
+import subprocess
+from pathlib import Path
+
+from ..providers import load_providers, add_provider, delete_provider, Provider, call_provider
+
+
+PROVIDER_INSTALL_INFO = {
+    "claude": {
+        "group": "Anthropic Claude",
+        "install_cmd": "npm install -g @anthropic-ai/claude-code",
+        "requires": "Node.js 18+ and npm",
+        "setup": "Run 'claude' - opens browser for sign-in (auto-saves auth tokens)",
+        "cost": "Pay-per-use (billed to your Anthropic account)",
+        "variants": ["claude", "claude-haiku", "claude-opus", "claude-sonnet"],
+    },
+    "codex": {
+        "group": "OpenAI Codex",
+        "install_cmd": "npm install -g @openai/codex",
+        "requires": "Node.js 18+ and npm",
+        "setup": "Run 'codex' - opens browser for sign-in (auto-saves auth tokens)",
+        "cost": "Pay-per-use (billed to your OpenAI account)",
+        "variants": ["codex"],
+    },
+    "gemini": {
+        "group": "Google Gemini",
+        "install_cmd": "npm install -g @google/gemini-cli",
+        "requires": "Node.js 18+ and npm",
+        "setup": "Run 'gemini' - opens browser for Google sign-in",
+        "cost": "Free tier available, pay-per-use for more",
+        "variants": ["gemini", "gemini-flash"],
+    },
+    "opencode": {
+        "group": "OpenCode (75+ providers)",
+        "install_cmd": "curl -fsSL https://opencode.ai/install | bash",
+        "requires": "curl, bash",
+        "setup": "Run 'opencode' - opens browser to connect more providers",
+        "cost": "4 FREE models included (Big Pickle, GLM-4.7, Grok Code Fast 1, MiniMax M2.1), 75+ more available",
+        "variants": ["opencode-pickle", "opencode-deepseek", "opencode-nano", "opencode-reasoner", "opencode-grok"],
+    },
+    "ollama": {
+        "group": "Ollama (Local LLMs)",
+        "install_cmd": "curl -fsSL https://ollama.ai/install.sh | bash",
+        "requires": "curl, bash, 8GB+ RAM (GPU recommended)",
+        "setup": "Run 'ollama pull llama3' to download a model, then add provider",
+        "cost": "FREE (runs entirely on your machine)",
+        "variants": [],
+        "custom": True,
+        "post_install_note": "After installing, add the provider:\n  cmdforge providers add ollama 'ollama run llama3' -d 'Local Llama 3'",
+    },
+}
+
+
+def cmd_providers(args):
+    """Manage AI providers."""
+    if args.providers_cmd == "install":
+        return _cmd_providers_install(args)
+    elif args.providers_cmd == "list":
+        return _cmd_providers_list(args)
+    elif args.providers_cmd == "add":
+        return _cmd_providers_add(args)
+    elif args.providers_cmd == "remove":
+        return _cmd_providers_remove(args)
+    elif args.providers_cmd == "test":
+        return _cmd_providers_test(args)
+    elif args.providers_cmd == "check":
+        return _cmd_providers_check(args)
+    return 0
+
+
+def _cmd_providers_install(args):
+    """Interactive guide to install AI providers."""
+    print("=" * 60)
+    print("CmdForge Provider Installation Guide")
+    print("=" * 60)
+    print()
+
+    # Check what's already installed
+    providers = load_providers()
+    installed_groups = set()
+    for p in providers:
+        if p.name.lower() == "mock":
+            continue
+        cmd_parts = p.command.split()[0]
+        cmd_expanded = cmd_parts.replace("$HOME", str(Path.home())).replace("~", str(Path.home()))
+        if shutil.which(cmd_expanded) or Path(cmd_expanded).exists():
+            # Find which group this belongs to
+            for group, info in PROVIDER_INSTALL_INFO.items():
+                if p.name in info.get("variants", []):
+                    installed_groups.add(group)
+
+    # Show available provider groups
+    print("Available AI Provider Groups:\n")
+    options = []
+    for i, (key, info) in enumerate(PROVIDER_INSTALL_INFO.items(), 1):
+        status = "[INSTALLED]" if key in installed_groups else ""
+        print(f"  {i}. {info['group']} {status}")
+        print(f"     Cost: {info['cost']}")
+        print(f"     Models: {', '.join(info['variants']) if info['variants'] else 'Custom'}")
+        print()
+        options.append(key)
+
+    print("  0. Cancel")
+    print()
+
+    try:
+        choice = input("Select a provider to install (1-{}, or 0 to cancel): ".format(len(options)))
+        choice = int(choice)
+    except (ValueError, EOFError):
+        print("Cancelled.")
+        return 0
+
+    if choice == 0 or choice > len(options):
+        print("Cancelled.")
+        return 0
+
+    selected = options[choice - 1]
+    info = PROVIDER_INSTALL_INFO[selected]
+
+    print()
+    print("=" * 60)
+    print(f"Installing: {info['group']}")
+    print("=" * 60)
+    print()
+    print(f"Requirements: {info['requires']}")
+    print(f"Install command: {info['install_cmd']}")
+    print(f"Post-install: {info['setup']}")
+    print()
+
+    try:
+        confirm = input("Run installation command? (y/N): ").strip().lower()
+    except EOFError:
+        confirm = "n"
+
+    if confirm == "y":
+        print()
+        print(f"Running: {info['install_cmd']}")
+        print("-" * 40)
+        result = subprocess.run(info['install_cmd'], shell=True)
+        print("-" * 40)
+
+        if result.returncode == 0:
+            # Refresh PATH to pick up newly installed tools
+            import os
+            new_paths = []
+
+            # Common install locations that might have been added
+            potential_paths = [
+                Path.home() / ".opencode" / "bin",  # OpenCode
+                Path.home() / ".local" / "bin",      # pip/pipx installs
+                Path("/usr/local/bin"),              # Ollama, system installs
+            ]
+
+            # Also try to get npm global bin path
+            try:
+                npm_result = subprocess.run(
+                    ["npm", "bin", "-g"],
+                    capture_output=True, text=True, timeout=5
+                )
+                if npm_result.returncode == 0:
+                    npm_bin = npm_result.stdout.strip()
+                    if npm_bin:
+                        potential_paths.append(Path(npm_bin))
+            except (subprocess.TimeoutExpired, FileNotFoundError):
+                pass
+
+            current_path = os.environ.get("PATH", "")
+            for p in potential_paths:
+                if p.exists() and str(p) not in current_path:
+                    new_paths.append(str(p))
+
+            if new_paths:
+                os.environ["PATH"] = ":".join(new_paths) + ":" + current_path
+
+            print()
+            print("Installation completed!")
+            print()
+            print("IMPORTANT: Refresh your shell PATH before continuing:")
+            print("  source ~/.bashrc")
+            print()
+            print(f"Next steps:")
+            print(f"  1. source ~/.bashrc   (required!)")
+            print(f"  2. {info['setup']}")
+            if info.get('post_install_note'):
+                print(f"  3. {info['post_install_note']}")
+                print(f"  4. Test with: cmdforge providers test {selected}")
+            else:
+                print(f"  3. Test with: cmdforge providers test {info['variants'][0] if info['variants'] else selected}")
+        else:
+            print()
+            print(f"Installation failed (exit code {result.returncode})")
+            print("Try running the command manually:")
+            print(f"  {info['install_cmd']}")
+    else:
+        print()
+        print("To install manually, run:")
+        print(f"  {info['install_cmd']}")
+        print()
+        print(f"Then: {info['setup']}")
+
+    return 0
+
+
+def _cmd_providers_list(args):
+    """List all providers and their status."""
+    providers = load_providers()
+    print(f"Configured providers ({len(providers)}):\n")
+    for p in providers:
+        # Mock provider is always available
+        if p.name.lower() == "mock":
+            print(f"  [+] {p.name}")
+            print(f"      Command: (built-in)")
+            print(f"      Status: OK (always available)")
+            if p.description:
+                print(f"      Info: {p.description}")
+            print()
+            continue
+
+        # Check if command exists
+        cmd_parts = p.command.split()[0]
+        cmd_expanded = cmd_parts.replace("$HOME", str(Path.home())).replace("~", str(Path.home()))
+        exists = shutil.which(cmd_expanded) is not None or Path(cmd_expanded).exists()
+        status = "OK" if exists else "NOT FOUND"
+        status_icon = "+" if exists else "-"
+
+        print(f"  [{status_icon}] {p.name}")
+        print(f"      Command: {p.command}")
+        print(f"      Status: {status}")
+        if p.description:
+            print(f"      Info: {p.description}")
+        print()
+    return 0
+
+
+def _cmd_providers_add(args):
+    """Add or update a provider."""
+    name = args.name
+    command = args.command
+    description = args.description or ""
+
+    provider = Provider(name, command, description)
+    add_provider(provider)
+    print(f"Provider '{name}' added/updated.")
+    return 0
+
+
+def _cmd_providers_remove(args):
+    """Remove a provider."""
+    name = args.name
+    if delete_provider(name):
+        print(f"Provider '{name}' removed.")
+        return 0
+    else:
+        print(f"Provider '{name}' not found.")
+        return 1
+
+
+def _cmd_providers_test(args):
+    """Test a provider."""
+    name = args.name
+    print(f"Testing provider '{name}'...")
+    result = call_provider(name, "Say 'hello' and nothing else.", timeout=30)
+    if result.success:
+        print(f"SUCCESS: {result.text[:200]}...")
+    else:
+        print(f"FAILED: {result.error}")
+    return 0 if result.success else 1
+
+
+def _cmd_providers_check(args):
+    """Check which providers are available."""
+    providers = load_providers()
+    print("Checking all providers...\n")
+    available = []
+    missing = []
+
+    for p in providers:
+        # Mock provider is always available (handled specially)
+        if p.name.lower() == "mock":
+            available.append(p.name)
+            print(f"  [+] {p.name}: OK (built-in)")
+            continue
+
+        cmd_parts = p.command.split()[0]
+        cmd_expanded = cmd_parts.replace("$HOME", str(Path.home())).replace("~", str(Path.home()))
+        exists = shutil.which(cmd_expanded) is not None or Path(cmd_expanded).exists()
+
+        if exists:
+            available.append(p.name)
+            print(f"  [+] {p.name}: OK")
+        else:
+            missing.append(p.name)
+            print(f"  [-] {p.name}: NOT FOUND ({cmd_parts})")
+
+    print(f"\nSummary: {len(available)} available, {len(missing)} missing")
+    if len(available) == 1 and available[0] == "mock":
+        print(f"\nNo real AI providers found. Install one of these:")
+        print(f"  - claude: npm install -g @anthropic-ai/claude-cli")
+        print(f"  - codex: pip install openai-codex")
+        print(f"  - gemini: pip install google-generative-ai")
+        print(f"\nMeanwhile, use mock provider for testing:")
+        print(f"  echo 'test' | summarize --provider mock")
+    elif missing:
+        print(f"\nAvailable providers: {', '.join(available)}")
+    return 0

src/cmdforge/cli/registry_commands.py

@@ -0,0 +1,665 @@
+"""Registry commands."""
+
+import json
+import sys
+from pathlib import Path
+
+import yaml
+
+from ..config import load_config, set_registry_token
+from ..resolver import install_from_registry, uninstall_tool, ToolSpec
+
+
+def cmd_registry(args):
+    """Handle registry subcommands."""
+    from ..registry_client import RegistryClient, RegistryError, RateLimitError, get_client
+
+    if args.registry_cmd == "search":
+        return _cmd_registry_search(args)
+    elif args.registry_cmd == "tags":
+        return _cmd_registry_tags(args)
+    elif args.registry_cmd == "install":
+        return _cmd_registry_install(args)
+    elif args.registry_cmd == "uninstall":
+        return _cmd_registry_uninstall(args)
+    elif args.registry_cmd == "info":
+        return _cmd_registry_info(args)
+    elif args.registry_cmd == "update":
+        return _cmd_registry_update(args)
+    elif args.registry_cmd == "publish":
+        return _cmd_registry_publish(args)
+    elif args.registry_cmd == "my-tools":
+        return _cmd_registry_my_tools(args)
+    elif args.registry_cmd == "browse":
+        return _cmd_registry_browse(args)
+    elif args.registry_cmd == "config":
+        return _cmd_registry_config(args)
+    else:
+        # Default: show registry help
+        print("Registry commands:")
+        print("  search <query>     Search for tools")
+        print("  tags               List available tags")
+        print("  install <tool>     Install a tool")
+        print("  uninstall <tool>   Uninstall a tool")
+        print("  info <tool>        Show tool information")
+        print("  update             Update local index cache")
+        print("  publish [path]     Publish a tool")
+        print("  my-tools           List your published tools")
+        print("  browse             Browse tools (TUI)")
+        print("  config [action]    Manage registry settings (admin)")
+        return 0
+
+
+def _cmd_registry_search(args):
+    """Search for tools in the registry."""
+    from ..registry_client import RegistryError, get_client
+
+    try:
+        client = get_client()
+
+        # Handle shortcut flags
+        min_downloads = getattr(args, 'min_downloads', None)
+        max_downloads = None
+        if getattr(args, 'popular', False):
+            min_downloads = 100
+        if getattr(args, 'new', False):
+            max_downloads = 10
+
+        results = client.search_tools(
+            query=args.query,
+            category=getattr(args, 'category', None),
+            tags=getattr(args, 'tags', None),
+            owner=getattr(args, 'owner', None),
+            min_downloads=min_downloads,
+            max_downloads=max_downloads,
+            published_after=getattr(args, 'since', None),
+            published_before=getattr(args, 'before', None),
+            include_deprecated=getattr(args, 'deprecated', False),
+            include_facets=getattr(args, 'show_facets', False),
+            per_page=args.limit or 20,
+            sort=getattr(args, 'sort', 'relevance')
+        )
+
+        # JSON output
+        if getattr(args, 'json', False):
+            output = {
+                "query": args.query,
+                "total": results.total,
+                "results": results.data
+            }
+            if results.facets:
+                output["facets"] = results.facets
+            print(json.dumps(output, indent=2))
+            return 0
+
+        if not results.data:
+            print(f"No tools found matching '{args.query}'")
+            return 0
+
+        print(f"Found {results.total} tools matching \"{args.query}\":")
+
+        # Show facets summary if requested
+        if results.facets:
+            cats = results.facets.get("categories", [])[:5]
+            tags = results.facets.get("tags", [])[:5]
+            if cats:
+                cat_str = ", ".join(f"{c['name']} ({c['count']})" for c in cats)
+                print(f"\nCategories: {cat_str}")
+            if tags:
+                tag_str = ", ".join(f"{t['name']} ({t['count']})" for t in tags)
+                print(f"Top Tags: {tag_str}")
+
+        print()
+        for tool in results.data:
+            owner = tool.get("owner", "")
+            name = tool.get("name", "")
+            version = tool.get("version", "")
+            desc = tool.get("description", "")
+            downloads = tool.get("downloads", 0)
+            tags = tool.get("tags", [])
+
+            print(f"  {owner}/{name} v{version}")
+            print(f"    {desc[:60]}{'...' if len(desc) > 60 else ''}")
+            if tags:
+                print(f"    Tags: {', '.join(tags[:5])}")
+            print(f"    Downloads: {downloads:,}")
+            print()
+
+        if results.total_pages > 1:
+            print(f"Showing page {results.page}/{results.total_pages}")
+
+    except RegistryError as e:
+        if e.code == "CONNECTION_ERROR":
+            print("Could not connect to the registry.", file=sys.stderr)
+            print("Check your internet connection or try again later.", file=sys.stderr)
+        elif e.code == "RATE_LIMITED":
+            print(f"Rate limited. Please wait and try again.", file=sys.stderr)
+        else:
+            print(f"Error: {e.message}", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"Error searching registry: {e}", file=sys.stderr)
+        print("If the problem persists, check: cmdforge config show", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+def _cmd_registry_tags(args):
+    """List available tags."""
+    from ..registry_client import RegistryError, get_client
+
+    try:
+        client = get_client()
+        tags = client.get_tags(
+            category=getattr(args, 'category', None),
+            limit=getattr(args, 'limit', 50)
+        )
+
+        # JSON output
+        if getattr(args, 'json', False):
+            print(json.dumps({"tags": tags}, indent=2))
+            return 0
+
+        if not tags:
+            print("No tags found")
+            return 0
+
+        print(f"Available tags ({len(tags)}):\n")
+        for tag in tags:
+            print(f"  {tag['name']:20} ({tag['count']} tools)")
+
+    except RegistryError as e:
+        if e.code == "CONNECTION_ERROR":
+            print("Could not connect to the registry.", file=sys.stderr)
+        else:
+            print(f"Error: {e.message}", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+def _cmd_registry_install(args):
+    """Install a tool from the registry."""
+    from ..registry_client import RegistryError
+    from ..tool import BIN_DIR
+
+    tool_spec = args.tool
+    version = args.version
+
+    print(f"Installing {tool_spec}...")
+
+    try:
+        resolved = install_from_registry(tool_spec, version)
+        print(f"Installed: {resolved.full_name}@{resolved.version}")
+        print(f"Location: {resolved.path}")
+
+        # Show wrapper info
+        wrapper_name = resolved.tool.name
+        if resolved.owner:
+            # Check for collision
+            short_wrapper = BIN_DIR / resolved.tool.name
+            if short_wrapper.exists():
+                wrapper_name = f"{resolved.owner}-{resolved.tool.name}"
+
+        print(f"\nRun with: {wrapper_name}")
+
+    except RegistryError as e:
+        if e.code == "TOOL_NOT_FOUND":
+            print(f"Tool '{tool_spec}' not found in the registry.", file=sys.stderr)
+            print(f"Try: cmdforge registry search {tool_spec.split('/')[-1]}", file=sys.stderr)
+        elif e.code == "VERSION_NOT_FOUND" or e.code == "CONSTRAINT_UNSATISFIABLE":
+            print(f"Error: {e.message}", file=sys.stderr)
+            if e.details and "available_versions" in e.details:
+                versions = e.details["available_versions"]
+                print(f"Available versions: {', '.join(versions[:5])}", file=sys.stderr)
+                if e.details.get("latest_stable"):
+                    print(f"Latest stable: {e.details['latest_stable']}", file=sys.stderr)
+        elif e.code == "CONNECTION_ERROR":
+            print("Could not connect to the registry.", file=sys.stderr)
+            print("Check your internet connection or try again later.", file=sys.stderr)
+        else:
+            print(f"Error: {e.message}", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"Error installing tool: {e}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+def _cmd_registry_uninstall(args):
+    """Uninstall a tool."""
+    tool_spec = args.tool
+
+    print(f"Uninstalling {tool_spec}...")
+
+    if uninstall_tool(tool_spec):
+        print(f"Uninstalled: {tool_spec}")
+    else:
+        print(f"Tool '{tool_spec}' not found", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+def _cmd_registry_info(args):
+    """Show tool information."""
+    from ..registry_client import RegistryError, get_client
+
+    tool_spec = args.tool
+
+    try:
+        # Parse the tool spec
+        parsed = ToolSpec.parse(tool_spec)
+        owner = parsed.owner or "official"
+
+        client = get_client()
+        tool_info = client.get_tool(owner, parsed.name)
+
+        print(f"{tool_info.owner}/{tool_info.name} v{tool_info.version}")
+        print("=" * 50)
+        print(f"Description: {tool_info.description}")
+        print(f"Category: {tool_info.category}")
+        print(f"Tags: {', '.join(tool_info.tags)}")
+        print(f"Downloads: {tool_info.downloads}")
+        print(f"Published: {tool_info.published_at}")
+
+        if tool_info.deprecated:
+            print()
+            print(f"DEPRECATED: {tool_info.deprecated_message}")
+            if tool_info.replacement:
+                print(f"Use instead: {tool_info.replacement}")
+
+        # Show versions
+        versions = client.get_tool_versions(owner, parsed.name)
+        if versions:
+            print(f"\nVersions: {', '.join(versions[:5])}")
+            if len(versions) > 5:
+                print(f"  ...and {len(versions) - 5} more")
+
+        print(f"\nInstall: cmdforge registry install {tool_info.owner}/{tool_info.name}")
+
+    except RegistryError as e:
+        if e.code == "TOOL_NOT_FOUND":
+            print(f"Tool '{tool_spec}' not found in the registry.", file=sys.stderr)
+            print(f"Try: cmdforge registry search {parsed.name}", file=sys.stderr)
+        elif e.code == "CONNECTION_ERROR":
+            print("Could not connect to the registry.", file=sys.stderr)
+            print("Check your internet connection or try again later.", file=sys.stderr)
+        else:
+            print(f"Error: {e.message}", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"Error fetching tool info: {e}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+def _cmd_registry_update(args):
+    """Update local index cache."""
+    from ..registry_client import RegistryError, get_client
+
+    print("Updating registry index...")
+
+    try:
+        client = get_client()
+        index = client.get_index(force_refresh=True)
+
+        tool_count = index.get("tool_count", len(index.get("tools", [])))
+        generated = index.get("generated_at", "unknown")
+
+        print(f"Index updated: {tool_count} tools")
+        print(f"Generated: {generated}")
+
+    except RegistryError as e:
+        if e.code == "CONNECTION_ERROR":
+            print("Could not connect to the registry.", file=sys.stderr)
+            print("Check your internet connection or try again later.", file=sys.stderr)
+        elif e.code == "RATE_LIMITED":
+            print("Rate limited. Please wait a moment and try again.", file=sys.stderr)
+        else:
+            print(f"Error: {e.message}", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"Error updating index: {e}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+def _cmd_registry_publish(args):
+    """Publish a tool to the registry."""
+    from ..registry_client import RegistryError, get_client
+
+    # Read tool from current directory or specified path
+    tool_path = Path(args.path) if args.path else Path.cwd()
+
+    if tool_path.is_dir():
+        config_path = tool_path / "config.yaml"
+    else:
+        config_path = tool_path
+        tool_path = config_path.parent
+
+    if not config_path.exists():
+        print(f"Error: config.yaml not found in {tool_path}", file=sys.stderr)
+        return 1
+
+    # Read config
+    config_yaml = config_path.read_text()
+
+    # Read README if exists
+    readme_path = tool_path / "README.md"
+    readme = readme_path.read_text() if readme_path.exists() else ""
+
+    # Validate
+    try:
+        data = yaml.safe_load(config_yaml)
+        name = data.get("name", "")
+        version = data.get("version", "")
+        if not name or not version:
+            print("Error: config.yaml must have 'name' and 'version' fields", file=sys.stderr)
+            return 1
+    except yaml.YAMLError as e:
+        print(f"Error: Invalid YAML in config.yaml: {e}", file=sys.stderr)
+        return 1
+
+    if args.dry_run:
+        print("Dry run - validating only")
+        print()
+        print(f"Would publish:")
+        print(f"  Name: {name}")
+        print(f"  Version: {version}")
+        print(f"  Config: {len(config_yaml)} bytes")
+        print(f"  README: {len(readme)} bytes")
+        return 0
+
+    # Check for token
+    config = load_config()
+    if not config.registry.token:
+        print("No registry token configured.")
+        print()
+        print("To publish tools, you need an account:")
+        print("  1. Register at: https://cmdforge.brrd.tech/register")
+        print("  2. Log in and go to Dashboard > Tokens")
+        print("  3. Generate an API token")
+        print("  4. Enter your token below (or run: cmdforge config set-token <token>)")
+        print()
+
+        try:
+            token = input("Registry token: ").strip()
+            if not token:
+                print("Cancelled.")
+                return 1
+            set_registry_token(token)
+            print("Token saved.")
+        except (EOFError, KeyboardInterrupt):
+            print("\nCancelled.")
+            return 1
+
+    print(f"Publishing {name}@{version}...")
+
+    try:
+        client = get_client()
+        result = client.publish_tool(config_yaml, readme)
+
+        pr_url = result.get("pr_url", "")
+        status = result.get("status", "")
+
+        if status == "published" or result.get("version"):
+            print(f"Published: {result.get('owner', '')}/{result.get('name', '')}@{result.get('version', version)}")
+        elif pr_url:
+            print(f"PR created: {pr_url}")
+            print("Your tool is pending review.")
+        else:
+            print("Published successfully!")
+
+        # Show suggestions if provided (from Phase 6 smart features)
+        suggestions = result.get("suggestions", {})
+        if suggestions:
+            print()
+
+            # Category suggestion
+            cat_suggestion = suggestions.get("category")
+            if cat_suggestion and cat_suggestion.get("suggested"):
+                confidence = cat_suggestion.get("confidence", 0)
+                print(f"Suggested category: {cat_suggestion['suggested']} ({confidence:.0%} confidence)")
+
+            # Similar tools warning
+            similar = suggestions.get("similar_tools", [])
+            if similar:
+                print("Similar existing tools:")
+                for tool in similar[:3]:
+                    similarity = tool.get("similarity", 0)
+                    print(f"  - {tool.get('name', 'unknown')} ({similarity:.0%} similar)")
+
+    except RegistryError as e:
+        if e.code == "UNAUTHORIZED":
+            print("Authentication failed.", file=sys.stderr)
+            print("Your token may have expired. Generate a new one from the registry.", file=sys.stderr)
+        elif e.code == "INVALID_CONFIG":
+            print(f"Invalid tool config: {e.message}", file=sys.stderr)
+            print("Check your config.yaml for errors.", file=sys.stderr)
+        elif e.code == "VERSION_EXISTS":
+            print(f"Version already exists: {e.message}", file=sys.stderr)
+            print("Bump the version in config.yaml and try again.", file=sys.stderr)
+        elif e.code == "CONNECTION_ERROR":
+            print("Could not connect to the registry.", file=sys.stderr)
+            print("Check your internet connection or try again later.", file=sys.stderr)
+        elif e.code == "RATE_LIMITED":
+            print("Rate limited. Please wait a moment and try again.", file=sys.stderr)
+        else:
+            print(f"Error: {e.message}", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"Error publishing: {e}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+def _cmd_registry_my_tools(args):
+    """List your published tools."""
+    from ..registry_client import RegistryError, get_client
+
+    try:
+        client = get_client()
+        tools = client.get_my_tools()
+
+        if not tools:
+            print("You haven't published any tools yet.")
+            print("Publish your first tool with: cmdforge registry publish")
+            return 0
+
+        print(f"Your published tools ({len(tools)}):\n")
+        for tool in tools:
+            status = "[DEPRECATED]" if tool.deprecated else ""
+            print(f"  {tool.owner}/{tool.name} v{tool.version} {status}")
+            print(f"    Downloads: {tool.downloads}")
+            print()
+
+    except RegistryError as e:
+        if e.code == "UNAUTHORIZED":
+            print("Not logged in. Set your registry token first:", file=sys.stderr)
+            print("  cmdforge config set-token <token>", file=sys.stderr)
+            print()
+            print("Don't have a token? Register at the registry website.", file=sys.stderr)
+        elif e.code == "CONNECTION_ERROR":
+            print("Could not connect to the registry.", file=sys.stderr)
+            print("Check your internet connection or try again later.", file=sys.stderr)
+        elif e.code == "RATE_LIMITED":
+            print("Rate limited. Please wait a moment and try again.", file=sys.stderr)
+        else:
+            print(f"Error: {e.message}", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+def _cmd_registry_browse(args):
+    """Browse tools (GUI)."""
+    from ..gui import run_gui
+    # Launch GUI - it will open to Registry page
+    return run_gui()
+
+
+def _cmd_registry_config(args):
+    """Manage registry settings (admin only)."""
+    from ..registry_client import RegistryError, get_client
+
+    action = getattr(args, 'action', 'list')
+    key = getattr(args, 'key', None)
+    value = getattr(args, 'value', None)
+    as_json = getattr(args, 'json', False)
+    category = getattr(args, 'category', None)
+
+    try:
+        client = get_client()
+
+        if action == "list":
+            return _config_list(client, as_json, category)
+        elif action == "get":
+            if not key:
+                print("Error: key is required for 'get' action", file=sys.stderr)
+                print("Usage: cmdforge registry config get <key>", file=sys.stderr)
+                return 1
+            return _config_get(client, key, as_json)
+        elif action == "set":
+            if not key or value is None:
+                print("Error: key and value are required for 'set' action", file=sys.stderr)
+                print("Usage: cmdforge registry config set <key> <value>", file=sys.stderr)
+                return 1
+            return _config_set(client, key, value)
+
+    except RegistryError as e:
+        if e.code == "UNAUTHORIZED":
+            print("Authentication failed.", file=sys.stderr)
+            print("This command requires admin privileges.", file=sys.stderr)
+            print("Set your admin token with: cmdforge config set-token <token>", file=sys.stderr)
+        elif e.code == "FORBIDDEN":
+            print("Access denied. Admin privileges required.", file=sys.stderr)
+        elif e.code == "CONNECTION_ERROR":
+            print("Could not connect to the registry.", file=sys.stderr)
+        else:
+            print(f"Error: {e.message}", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+def _config_list(client, as_json, category=None):
+    """List all settings."""
+    # Use the admin settings endpoint
+    response = client._request("GET", "/admin/settings")
+    settings = response.get("settings", [])
+
+    # Filter by category if specified
+    if category:
+        settings = [s for s in settings if s.get("category") == category]
+
+    if as_json:
+        print(json.dumps({"settings": settings}, indent=2))
+        return 0
+
+    if not settings:
+        print("No settings found.")
+        return 0
+
+    # Group by category
+    by_category = {}
+    for s in settings:
+        cat = s.get("category", "general")
+        if cat not in by_category:
+            by_category[cat] = []
+        by_category[cat].append(s)
+
+    print("Registry Settings")
+    print("=" * 60)
+
+    for cat, cat_settings in sorted(by_category.items()):
+        print(f"\n[{cat.upper()}]")
+        for s in cat_settings:
+            key = s.get("key", "")
+            value = s.get("value")
+            value_type = s.get("value_type", "string")
+            desc = s.get("description", "")
+            is_default = s.get("is_default", True)
+
+            # Format value display
+            if value_type == "bool":
+                value_str = "true" if value else "false"
+            else:
+                value_str = str(value)
+
+            status = "" if is_default else " (modified)"
+            print(f"  {key}")
+            print(f"    Value: {value_str}{status}")
+            if desc:
+                print(f"    {desc}")
+
+    print()
+    print("Use 'cmdforge registry config get <key>' to see a setting's value")
+    print("Use 'cmdforge registry config set <key> <value>' to change a setting")
+    return 0
+
+
+def _config_get(client, key, as_json):
+    """Get a specific setting."""
+    response = client._request("GET", f"/admin/settings/{key}")
+
+    if as_json:
+        print(json.dumps(response, indent=2))
+        return 0
+
+    setting = response.get("setting", {})
+    print(f"Key: {setting.get('key', key)}")
+    print(f"Value: {setting.get('value')}")
+    print(f"Type: {setting.get('value_type', 'string')}")
+    print(f"Category: {setting.get('category', 'general')}")
+    if setting.get('description'):
+        print(f"Description: {setting['description']}")
+    if setting.get('updated_at'):
+        print(f"Last updated: {setting['updated_at'][:19]} by {setting.get('updated_by', 'system')}")
+
+    return 0
+
+
+def _config_set(client, key, value):
+    """Set a setting value."""
+    # Try to parse value as appropriate type
+    parsed_value = value
+
+    # Try to parse as bool
+    if value.lower() in ("true", "false"):
+        parsed_value = value.lower() == "true"
+    # Try to parse as number
+    else:
+        try:
+            if "." in value:
+                parsed_value = float(value)
+            else:
+                parsed_value = int(value)
+        except ValueError:
+            # Keep as string
+            pass
+
+    response = client._request("PUT", f"/admin/settings/{key}", json={"value": parsed_value})
+
+    if response.get("success"):
+        print(f"Setting '{key}' updated successfully.")
+        print(f"New value: {response.get('setting', {}).get('value', parsed_value)}")
+    else:
+        print(f"Failed to update setting: {response.get('error', 'Unknown error')}", file=sys.stderr)
+        return 1
+
+    return 0

src/cmdforge/cli/tool_commands.py

@@ -0,0 +1,393 @@
+"""Tool management commands."""
+
+import sys
+from pathlib import Path
+
+from ..tool import (
+    list_tools, load_tool, save_tool, delete_tool, get_tools_dir,
+    Tool, ToolArgument, PromptStep, CodeStep, ToolStep
+)
+from ..gui import run_gui
+
+
+def cmd_list(args):
+    """List all tools."""
+    tools = list_tools()
+
+    if not tools:
+        print("No tools found.")
+        print("Create your first tool with: cmdforge ui")
+        return 0
+
+    print(f"Available tools ({len(tools)}):\n")
+    for name in tools:
+        tool = load_tool(name)
+        if tool:
+            # Show source indicator for imported tools
+            source_marker = ""
+            if tool.source and tool.source.type == "imported":
+                source_marker = " [imported]"
+            elif tool.source and tool.source.type == "forked":
+                source_marker = " [forked]"
+
+            print(f"  {name}{source_marker}")
+            print(f"    {tool.description or 'No description'}")
+
+            # Show arguments
+            if tool.arguments:
+                args_str = ", ".join(arg.flag for arg in tool.arguments)
+                print(f"    Arguments: {args_str}")
+
+            # Show steps
+            if tool.steps:
+                step_info = []
+                for step in tool.steps:
+                    if isinstance(step, PromptStep):
+                        step_info.append(f"PROMPT[{step.provider}]")
+                    elif isinstance(step, CodeStep):
+                        step_info.append("CODE")
+                    elif isinstance(step, ToolStep):
+                        step_info.append(f"TOOL[{step.tool}]")
+                print(f"    Steps: {' -> '.join(step_info)}")
+
+            print()
+
+    return 0
+
+
+def cmd_create(args):
+    """Create a new tool (basic CLI creation - use 'ui' for full builder)."""
+    name = args.name
+
+    # Check if already exists
+    existing = load_tool(name)
+    if existing and not args.force:
+        print(f"Error: Tool '{name}' already exists. Use --force to overwrite.")
+        return 1
+
+    # Create a tool with a single prompt step
+    steps = []
+    if args.prompt:
+        steps.append(PromptStep(
+            prompt=args.prompt,
+            provider=args.provider or "mock",
+            output_var="response"
+        ))
+
+    tool = Tool(
+        name=name,
+        description=args.description or "",
+        arguments=[],
+        steps=steps,
+        output="{response}" if steps else "{input}"
+    )
+
+    path = save_tool(tool)
+    print(f"Created tool '{name}'")
+    print(f"Config: {path}")
+    print(f"\nUse 'cmdforge ui' to add arguments, steps, and customize.")
+    print(f"Or run: {name} < input.txt")
+
+    return 0
+
+
+def cmd_edit(args):
+    """Edit a tool (opens in $EDITOR or nano)."""
+    import os
+    import subprocess
+
+    tool = load_tool(args.name)
+    if not tool:
+        print(f"Error: Tool '{args.name}' not found.")
+        return 1
+
+    config_path = get_tools_dir() / args.name / "config.yaml"
+
+    editor = os.environ.get("EDITOR", "nano")
+
+    try:
+        subprocess.run([editor, str(config_path)], check=True)
+        print(f"Tool '{args.name}' updated.")
+        return 0
+    except subprocess.CalledProcessError:
+        print(f"Error: Editor failed.")
+        return 1
+    except FileNotFoundError:
+        print(f"Error: Editor '{editor}' not found. Set $EDITOR environment variable.")
+        return 1
+
+
+def cmd_delete(args):
+    """Delete a tool."""
+    if not load_tool(args.name):
+        print(f"Error: Tool '{args.name}' not found.")
+        return 1
+
+    if not args.force:
+        confirm = input(f"Delete tool '{args.name}'? [y/N] ")
+        if confirm.lower() != 'y':
+            print("Cancelled.")
+            return 0
+
+    if delete_tool(args.name):
+        print(f"Deleted tool '{args.name}'.")
+        return 0
+    else:
+        print(f"Error: Failed to delete '{args.name}'.")
+        return 1
+
+
+def cmd_test(args):
+    """Test a tool with mock provider."""
+    tool = load_tool(args.name)
+    if not tool:
+        print(f"Error: Tool '{args.name}' not found.")
+        return 1
+
+    from ..runner import run_tool
+
+    # Read test input
+    if args.input:
+        input_text = Path(args.input).read_text()
+    else:
+        print("Enter test input (Ctrl+D to end):")
+        input_text = sys.stdin.read()
+
+    print("\n--- Running with mock provider ---\n")
+
+    output, code = run_tool(
+        tool=tool,
+        input_text=input_text,
+        custom_args={},
+        provider_override="mock",
+        dry_run=args.dry_run,
+        show_prompt=True,
+        verbose=True
+    )
+
+    if output:
+        print("\n--- Output ---\n")
+        print(output)
+
+    return code
+
+
+def cmd_run(args):
+    """Run a tool."""
+    from ..runner import run_tool
+
+    tool = load_tool(args.name)
+    if not tool:
+        print(f"Error: Tool '{args.name}' not found.", file=sys.stderr)
+        return 1
+
+    # Read input
+    if args.input:
+        # Read from file
+        input_path = Path(args.input)
+        if not input_path.exists():
+            print(f"Error: Input file not found: {args.input}", file=sys.stderr)
+            return 1
+        input_text = input_path.read_text()
+    elif args.stdin:
+        # Explicit interactive input requested
+        print("Reading from stdin (Ctrl+D to end):", file=sys.stderr)
+        input_text = sys.stdin.read()
+    elif not sys.stdin.isatty():
+        # Stdin is piped - read it
+        input_text = sys.stdin.read()
+    else:
+        # No input provided - use empty string
+        input_text = ""
+
+    # Collect custom args from remaining arguments
+    custom_args = {}
+    if args.tool_args:
+        # Parse tool-specific arguments
+        i = 0
+        while i < len(args.tool_args):
+            arg = args.tool_args[i]
+            if arg.startswith('--'):
+                key = arg[2:].replace('-', '_')
+                if i + 1 < len(args.tool_args) and not args.tool_args[i + 1].startswith('--'):
+                    custom_args[key] = args.tool_args[i + 1]
+                    i += 2
+                else:
+                    custom_args[key] = True
+                    i += 1
+            elif arg.startswith('-'):
+                key = arg[1:].replace('-', '_')
+                if i + 1 < len(args.tool_args) and not args.tool_args[i + 1].startswith('-'):
+                    custom_args[key] = args.tool_args[i + 1]
+                    i += 2
+                else:
+                    custom_args[key] = True
+                    i += 1
+            else:
+                i += 1
+
+    # Run tool
+    output, code = run_tool(
+        tool=tool,
+        input_text=input_text,
+        custom_args=custom_args,
+        provider_override=args.provider,
+        dry_run=args.dry_run,
+        show_prompt=args.show_prompt,
+        verbose=args.verbose
+    )
+
+    # Write output
+    if code == 0 and output:
+        if args.output:
+            Path(args.output).write_text(output)
+        else:
+            print(output)
+
+    return code
+
+
+def cmd_ui(args):
+    """Launch the interactive GUI."""
+    return run_gui()
+
+
+def cmd_refresh(args):
+    """Refresh all wrapper scripts with the current Python path."""
+    from ..tool import create_wrapper_script
+
+    tools = list_tools()
+    if not tools:
+        print("No tools found.")
+        return 0
+
+    print(f"Refreshing wrapper scripts for {len(tools)} tools...")
+    for name in tools:
+        path = create_wrapper_script(name)
+        print(f"  {name} -> {path}")
+
+    print("\nDone. Wrapper scripts updated to use current Python interpreter.")
+    return 0
+
+
+def cmd_docs(args):
+    """View or edit tool documentation."""
+    import os
+    import subprocess
+
+    tool = load_tool(args.name)
+    if not tool:
+        print(f"Error: Tool '{args.name}' not found.")
+        return 1
+
+    readme_path = get_tools_dir() / args.name / "README.md"
+
+    if args.edit:
+        # Edit/create README
+        editor = os.environ.get("EDITOR", "nano")
+
+        # Create a template if README doesn't exist
+        if not readme_path.exists():
+            template = f"""# {args.name}
+
+{tool.description or 'No description provided.'}
+
+## Usage
+
+```bash
+echo "input" | {args.name}
+```
+
+## Arguments
+
+| Flag | Default | Description |
+|------|---------|-------------|
+"""
+            for arg in tool.arguments:
+                template += f"| `{arg.flag}` | {arg.default or ''} | {arg.description or ''} |\n"
+
+            template += """
+## Examples
+
+```bash
+# Example 1
+```
+
+## Requirements
+
+- List any dependencies here
+"""
+            readme_path.write_text(template)
+            print(f"Created template: {readme_path}")
+
+        try:
+            subprocess.run([editor, str(readme_path)], check=True)
+            print(f"Documentation updated: {readme_path}")
+            return 0
+        except subprocess.CalledProcessError:
+            print("Error: Editor failed.")
+            return 1
+        except FileNotFoundError:
+            print(f"Error: Editor '{editor}' not found. Set $EDITOR environment variable.")
+            return 1
+    else:
+        # View README
+        if not readme_path.exists():
+            print(f"No documentation found for '{args.name}'.")
+            print(f"Create it with: cmdforge docs {args.name} --edit")
+            return 1
+
+        print(readme_path.read_text())
+        return 0
+
+
+def cmd_check(args):
+    """Check dependencies for a tool (meta-tools)."""
+    from ..runner import check_dependencies
+    from ..tool import ToolStep
+
+    tool = load_tool(args.name)
+    if not tool:
+        print(f"Error: Tool '{args.name}' not found.")
+        return 1
+
+    # Check if this is a meta-tool
+    has_tool_steps = any(isinstance(s, ToolStep) for s in tool.steps)
+    has_deps = bool(tool.dependencies)
+
+    if not has_tool_steps and not has_deps:
+        print(f"Tool '{args.name}' has no dependencies (not a meta-tool).")
+        return 0
+
+    print(f"Checking dependencies for '{args.name}'...")
+    print()
+
+    # Show declared dependencies
+    if tool.dependencies:
+        print("Declared dependencies:")
+        for dep in tool.dependencies:
+            print(f"  - {dep}")
+        print()
+
+    # Show tool steps
+    if has_tool_steps:
+        print("Tool steps (implicit dependencies):")
+        for i, step in enumerate(tool.steps):
+            if isinstance(step, ToolStep):
+                print(f"  Step {i+1}: {step.tool}")
+        print()
+
+    # Check which are missing
+    missing = check_dependencies(tool)
+
+    if missing:
+        print(f"Missing dependencies ({len(missing)}):")
+        for dep in missing:
+            print(f"  - {dep}")
+        print()
+        print("Install with:")
+        print(f"  cmdforge install {' '.join(missing)}")
+        return 1
+    else:
+        print("All dependencies are satisfied.")
+        return 0

src/cmdforge/config.py

@@ -1,6 +1,6 @@
-"""Global configuration handling for SmartTools.
+"""Global configuration handling for CmdForge.
 
-Manages ~/.smarttools/config.yaml with registry settings, tokens, and preferences.
+Manages ~/.cmdforge/config.yaml with registry settings, tokens, and preferences.
 """
 
 import uuid
@@ -12,11 +12,11 @@ import yaml
 
 
 # Default configuration directory
-CONFIG_DIR = Path.home() / ".smarttools"
+CONFIG_DIR = Path.home() / ".cmdforge"
 CONFIG_FILE = CONFIG_DIR / "config.yaml"
 
 # Default registry URL (canonical base path)
-DEFAULT_REGISTRY_URL = "https://gitea.brrd.tech/api/v1"
+DEFAULT_REGISTRY_URL = "https://cmdforge.brrd.tech/api/v1"
 
 
 @dataclass
@@ -41,7 +41,7 @@ class RegistryConfig:
 
 @dataclass
 class Config:
-    """Global SmartTools configuration."""
+    """Global CmdForge configuration."""
     registry: RegistryConfig = field(default_factory=RegistryConfig)
     client_id: str = ""
     auto_fetch_from_registry: bool = True

src/cmdforge/gui/__init__.py

@@ -0,0 +1,18 @@
+"""PySide6 GUI for CmdForge."""
+
+import sys
+
+
+def run_gui():
+    """Launch the CmdForge GUI application."""
+    from PySide6.QtWidgets import QApplication
+    from .main_window import MainWindow
+
+    app = QApplication(sys.argv)
+    app.setApplicationName("CmdForge")
+    app.setOrganizationName("CmdForge")
+
+    window = MainWindow()
+    window.show()
+
+    return app.exec()

src/cmdforge/gui/dialogs/__init__.py

@@ -0,0 +1 @@
+"""GUI dialogs."""

src/cmdforge/gui/dialogs/argument_dialog.py

@@ -0,0 +1,104 @@
+"""Argument editor dialog."""
+
+from PySide6.QtWidgets import (
+    QDialog, QVBoxLayout, QFormLayout, QLineEdit,
+    QCheckBox, QPushButton, QHBoxLayout, QLabel
+)
+
+from ...tool import ToolArgument
+
+
+class ArgumentDialog(QDialog):
+    """Dialog for editing tool arguments."""
+
+    def __init__(self, parent, argument: ToolArgument = None):
+        super().__init__(parent)
+        self.setWindowTitle("Edit Argument" if argument else "Add Argument")
+        self.setMinimumWidth(400)
+        self._argument = argument
+        self._setup_ui()
+
+        if argument:
+            self._load_argument(argument)
+
+    def _setup_ui(self):
+        """Set up the UI."""
+        layout = QVBoxLayout(self)
+        layout.setSpacing(16)
+
+        # Form
+        form = QFormLayout()
+        form.setSpacing(12)
+
+        self.flag_input = QLineEdit()
+        self.flag_input.setPlaceholderText("--input, -i")
+        form.addRow("Flag:", self.flag_input)
+
+        self.var_input = QLineEdit()
+        self.var_input.setPlaceholderText("input_text")
+        form.addRow("Variable:", self.var_input)
+
+        self.default_input = QLineEdit()
+        self.default_input.setPlaceholderText("(optional)")
+        form.addRow("Default:", self.default_input)
+
+        self.desc_input = QLineEdit()
+        self.desc_input.setPlaceholderText("(optional)")
+        form.addRow("Description:", self.desc_input)
+
+        layout.addLayout(form)
+
+        # Help text
+        help_text = QLabel(
+            "The flag is how users specify this argument (e.g. --input).\n"
+            "The variable name is used in prompts and templates as ${variable}."
+        )
+        help_text.setStyleSheet("color: #718096; font-size: 11px;")
+        help_text.setWordWrap(True)
+        layout.addWidget(help_text)
+
+        # Buttons
+        buttons = QHBoxLayout()
+        buttons.addStretch()
+
+        self.btn_cancel = QPushButton("Cancel")
+        self.btn_cancel.setObjectName("secondary")
+        self.btn_cancel.clicked.connect(self.reject)
+        buttons.addWidget(self.btn_cancel)
+
+        self.btn_ok = QPushButton("OK")
+        self.btn_ok.clicked.connect(self._validate_and_accept)
+        buttons.addWidget(self.btn_ok)
+
+        layout.addLayout(buttons)
+
+    def _load_argument(self, arg: ToolArgument):
+        """Load argument data into form."""
+        self.flag_input.setText(arg.flag)
+        self.var_input.setText(arg.variable)
+        self.default_input.setText(arg.default or "")
+        self.desc_input.setText(arg.description or "")
+
+    def _validate_and_accept(self):
+        """Validate input and accept."""
+        flag = self.flag_input.text().strip()
+        variable = self.var_input.text().strip()
+
+        if not flag:
+            self.flag_input.setFocus()
+            return
+
+        if not variable:
+            self.var_input.setFocus()
+            return
+
+        self.accept()
+
+    def get_argument(self) -> ToolArgument:
+        """Get the argument from form data."""
+        return ToolArgument(
+            flag=self.flag_input.text().strip(),
+            variable=self.var_input.text().strip(),
+            default=self.default_input.text().strip() or None,
+            description=self.desc_input.text().strip() or ""
+        )

src/cmdforge/gui/dialogs/connect_dialog.py

@@ -0,0 +1,234 @@
+"""Connect to registry dialog."""
+
+import socket
+import time
+import requests
+from PySide6.QtWidgets import (
+    QDialog, QVBoxLayout, QLabel, QPushButton,
+    QHBoxLayout, QLineEdit, QProgressBar, QTextEdit
+)
+from PySide6.QtCore import Qt, QThread, Signal, QTimer
+
+from ...config import load_config, save_config, get_registry_url, set_registry_token
+
+
+class PairingWorker(QThread):
+    """Background worker for pairing flow."""
+    success = Signal(str)  # token
+    error = Signal(str)
+    status = Signal(str)
+
+    def __init__(self, username: str):
+        super().__init__()
+        self.username = username
+        self.hostname = socket.gethostname()
+        self._stop = False
+
+    def stop(self):
+        self._stop = True
+
+    def run(self):
+        try:
+            registry_url = get_registry_url()
+
+            # Remove trailing /api/v1 if present to get base URL
+            base_url = registry_url.rstrip("/")
+            if base_url.endswith("/api/v1"):
+                base_url = base_url[:-7]
+
+            pairing_url = f"{base_url}/api/v1/pairing/check/{self.username}"
+
+            self.status.emit(f"Connecting to {base_url}...")
+
+            # Poll for pairing status
+            max_attempts = 150  # 5 minutes at 2-second intervals
+            attempt = 0
+
+            while attempt < max_attempts:
+                if self._stop:
+                    return
+
+                attempt += 1
+                try:
+                    response = requests.get(
+                        pairing_url,
+                        params={"hostname": self.hostname},
+                        timeout=10
+                    )
+
+                    if response.status_code == 200:
+                        data = response.json()
+                        status = data.get("data", {}).get("status")
+
+                        if status == "connected":
+                            token = data.get("data", {}).get("token")
+                            if token:
+                                self.success.emit(token)
+                                return
+                            else:
+                                self.error.emit("Pairing completed but no token received")
+                                return
+                        elif status == "expired":
+                            self.error.emit("Pairing request expired. Please try again.")
+                            return
+                        elif status == "pending":
+                            self.status.emit(f"Pairing pending, approve in web UI... ({attempt})")
+                        elif status == "not_found":
+                            self.status.emit(f"Waiting for web UI pairing... ({attempt})")
+                        else:
+                            self.status.emit(f"Status: {status} ({attempt})")
+                    elif response.status_code == 404:
+                        self.status.emit(f"Waiting for web approval... ({attempt})")
+                    else:
+                        self.status.emit(f"Server returned {response.status_code}")
+
+                except requests.exceptions.RequestException:
+                    self.status.emit(f"Network error, retrying... ({attempt})")
+
+                time.sleep(2)
+
+            self.error.emit("Timed out waiting for approval")
+
+        except Exception as e:
+            self.error.emit(str(e))
+
+
+class ConnectDialog(QDialog):
+    """Dialog for connecting to registry."""
+
+    def __init__(self, parent):
+        super().__init__(parent)
+        self.setWindowTitle("Connect to Registry")
+        self.setMinimumWidth(450)
+        self._worker = None
+        self._setup_ui()
+
+    def _setup_ui(self):
+        """Set up the UI."""
+        layout = QVBoxLayout(self)
+        layout.setSpacing(16)
+
+        # Title
+        title = QLabel("Connect Your Account")
+        title.setStyleSheet("font-size: 16px; font-weight: 600;")
+        layout.addWidget(title)
+
+        # Instructions
+        self.instructions = QLabel(
+            "To publish tools, connect your CmdForge account.\n\n"
+            "1. Enter your CmdForge username below\n"
+            "2. Click Connect\n"
+            "3. Go to cmdforge.brrd.tech/dashboard/connected-apps\n"
+            "4. Click 'Connect New App' and approve this device"
+        )
+        self.instructions.setWordWrap(True)
+        layout.addWidget(self.instructions)
+
+        # Username input
+        username_layout = QHBoxLayout()
+        username_label = QLabel("Username:")
+        self.username_input = QLineEdit()
+        self.username_input.setPlaceholderText("your-username")
+        self.username_input.returnPressed.connect(self._start_pairing)
+        username_layout.addWidget(username_label)
+        username_layout.addWidget(self.username_input, 1)
+        layout.addLayout(username_layout)
+
+        # Device info
+        hostname = socket.gethostname()
+        device_label = QLabel(f"Device: {hostname}")
+        device_label.setStyleSheet("color: #718096; font-size: 12px;")
+        layout.addWidget(device_label)
+
+        # Status
+        self.status_label = QLabel("")
+        self.status_label.setStyleSheet("color: #718096;")
+        layout.addWidget(self.status_label)
+
+        # Log area for debugging
+        self.log_area = QTextEdit()
+        self.log_area.setReadOnly(True)
+        self.log_area.setMaximumHeight(120)
+        self.log_area.setStyleSheet("font-family: monospace; font-size: 11px; background: #f7fafc;")
+        self.log_area.hide()
+        layout.addWidget(self.log_area)
+
+        # Progress
+        self.progress = QProgressBar()
+        self.progress.setRange(0, 0)  # Indeterminate
+        self.progress.hide()
+        layout.addWidget(self.progress)
+
+        # Buttons
+        buttons = QHBoxLayout()
+        buttons.addStretch()
+
+        self.btn_cancel = QPushButton("Cancel")
+        self.btn_cancel.setObjectName("secondary")
+        self.btn_cancel.clicked.connect(self._cancel)
+        buttons.addWidget(self.btn_cancel)
+
+        self.btn_connect = QPushButton("Connect")
+        self.btn_connect.clicked.connect(self._start_pairing)
+        buttons.addWidget(self.btn_connect)
+
+        layout.addLayout(buttons)
+
+    def _start_pairing(self):
+        """Start the pairing flow."""
+        username = self.username_input.text().strip()
+        if not username:
+            self.status_label.setText("Please enter your username")
+            self.status_label.setStyleSheet("color: #e53e3e;")
+            return
+
+        self.btn_connect.setEnabled(False)
+        self.username_input.setEnabled(False)
+        self.progress.show()
+        self.log_area.clear()
+        self.log_area.show()
+        self.status_label.setStyleSheet("color: #718096;")
+
+        self._worker = PairingWorker(username)
+        self._worker.success.connect(self._on_success)
+        self._worker.error.connect(self._on_error)
+        self._worker.status.connect(self._on_status)
+        self._worker.start()
+
+    def _on_success(self, token: str):
+        """Handle successful pairing."""
+        set_registry_token(token)
+
+        self.progress.hide()
+        self.status_label.setText("Connected successfully!")
+        self.status_label.setStyleSheet("color: #38a169; font-weight: 600;")
+
+        QTimer.singleShot(1000, self.accept)
+
+    def _on_error(self, error: str):
+        """Handle error."""
+        self.progress.hide()
+        self.btn_connect.setEnabled(True)
+        self.username_input.setEnabled(True)
+        self.status_label.setText(f"Error: {error}")
+        self.status_label.setStyleSheet("color: #e53e3e;")
+
+    def _on_status(self, status: str):
+        """Handle status update."""
+        self.status_label.setText(status)
+        # Also append to log for debugging
+        self.log_area.append(status)
+
+    def _cancel(self):
+        """Cancel pairing."""
+        if self._worker:
+            self._worker.stop()
+            self._worker.wait(1000)
+        self.reject()
+
+    def closeEvent(self, event):
+        """Handle close."""
+        if self._worker:
+            self._worker.stop()
+            self._worker.wait(1000)
+        super().closeEvent(event)

src/cmdforge/gui/dialogs/provider_dialog.py

@@ -0,0 +1,101 @@
+"""Provider editor dialog."""
+
+from PySide6.QtWidgets import (
+    QDialog, QVBoxLayout, QFormLayout, QLineEdit,
+    QPushButton, QHBoxLayout, QLabel
+)
+
+from ...providers import Provider, add_provider
+
+
+class ProviderDialog(QDialog):
+    """Dialog for adding/editing providers."""
+
+    def __init__(self, parent, name: str = None, provider: Provider = None):
+        super().__init__(parent)
+        self.setWindowTitle("Edit Provider" if provider else "Add Provider")
+        self.setMinimumWidth(450)
+        self._editing = provider is not None
+        self._original_name = name
+        self._setup_ui()
+
+        if provider:
+            self._load_provider(name, provider)
+
+    def _setup_ui(self):
+        """Set up the UI."""
+        layout = QVBoxLayout(self)
+        layout.setSpacing(16)
+
+        # Form
+        form = QFormLayout()
+        form.setSpacing(12)
+
+        self.name_input = QLineEdit()
+        self.name_input.setPlaceholderText("claude")
+        form.addRow("Name:", self.name_input)
+
+        self.cmd_input = QLineEdit()
+        self.cmd_input.setPlaceholderText("claude-cli")
+        form.addRow("Command:", self.cmd_input)
+
+        self.desc_input = QLineEdit()
+        self.desc_input.setPlaceholderText("Claude AI via claude-cli")
+        form.addRow("Description:", self.desc_input)
+
+        layout.addLayout(form)
+
+        # Help text
+        help_text = QLabel(
+            "The command should accept input on stdin and output to stdout.\n"
+            "Example commands: claude-cli, sgpt, llm, mods"
+        )
+        help_text.setStyleSheet("color: #718096; font-size: 11px;")
+        help_text.setWordWrap(True)
+        layout.addWidget(help_text)
+
+        layout.addStretch()
+
+        # Buttons
+        buttons = QHBoxLayout()
+        buttons.addStretch()
+
+        self.btn_cancel = QPushButton("Cancel")
+        self.btn_cancel.setObjectName("secondary")
+        self.btn_cancel.clicked.connect(self.reject)
+        buttons.addWidget(self.btn_cancel)
+
+        self.btn_ok = QPushButton("Save")
+        self.btn_ok.clicked.connect(self._save)
+        buttons.addWidget(self.btn_ok)
+
+        layout.addLayout(buttons)
+
+    def _load_provider(self, name: str, provider: Provider):
+        """Load provider data into form."""
+        self.name_input.setText(name)
+        self.name_input.setEnabled(False)  # Can't rename
+        self.cmd_input.setText(provider.command)
+        self.desc_input.setText(provider.description or "")
+
+    def _save(self):
+        """Save the provider."""
+        name = self.name_input.text().strip()
+        command = self.cmd_input.text().strip()
+
+        if not name:
+            self.name_input.setFocus()
+            return
+
+        if not command:
+            self.cmd_input.setFocus()
+            return
+
+        description = self.desc_input.text().strip() or None
+
+        try:
+            add_provider(name, command, description)
+            self.accept()
+        except Exception as e:
+            from PySide6.QtWidgets import QMessageBox
+            QMessageBox.critical(self, "Error", f"Failed to save provider:\n{e}")

src/cmdforge/gui/dialogs/publish_dialog.py

@@ -0,0 +1,182 @@
+"""Publish tool dialog."""
+
+from PySide6.QtWidgets import (
+    QDialog, QVBoxLayout, QLabel, QPushButton,
+    QHBoxLayout, QLineEdit, QTextEdit, QFormLayout,
+    QProgressBar, QMessageBox, QComboBox
+)
+from PySide6.QtCore import QThread, Signal
+
+from ...tool import Tool
+from ...registry_client import RegistryClient, RegistryError
+from ...config import load_config
+
+
+class PublishWorker(QThread):
+    """Background worker for publishing."""
+    success = Signal(dict)
+    error = Signal(str)
+
+    def __init__(self, tool_data: dict):
+        super().__init__()
+        self.tool_data = tool_data
+
+    def run(self):
+        try:
+            config = load_config()
+            client = RegistryClient()
+            client.token = config.registry.token
+
+            result = client.publish_tool(self.tool_data)
+            self.success.emit(result)
+        except Exception as e:
+            self.error.emit(str(e))
+
+
+class PublishDialog(QDialog):
+    """Dialog for publishing a tool."""
+
+    def __init__(self, parent, tool: Tool):
+        super().__init__(parent)
+        self.setWindowTitle("Publish Tool")
+        self.setMinimumSize(500, 400)
+        self._tool = tool
+        self._worker = None
+        self._setup_ui()
+
+    def _setup_ui(self):
+        """Set up the UI."""
+        layout = QVBoxLayout(self)
+        layout.setSpacing(16)
+
+        # Title
+        title = QLabel(f"Publish '{self._tool.name}'")
+        title.setStyleSheet("font-size: 16px; font-weight: 600;")
+        layout.addWidget(title)
+
+        # Form
+        form = QFormLayout()
+        form.setSpacing(12)
+
+        # Version
+        self.version_input = QLineEdit()
+        self.version_input.setText("1.0.0")
+        self.version_input.setPlaceholderText("1.0.0")
+        form.addRow("Version:", self.version_input)
+
+        # Category
+        self.category_combo = QComboBox()
+        self.category_combo.setEditable(True)
+        categories = [
+            "Text Processing", "Code", "Data", "System",
+            "Writing", "Analysis", "Productivity", "Other"
+        ]
+        self.category_combo.addItems(categories)
+        if self._tool.category:
+            idx = self.category_combo.findText(self._tool.category)
+            if idx >= 0:
+                self.category_combo.setCurrentIndex(idx)
+            else:
+                self.category_combo.setCurrentText(self._tool.category)
+        form.addRow("Category:", self.category_combo)
+
+        # Tags
+        self.tags_input = QLineEdit()
+        self.tags_input.setPlaceholderText("ai, text, productivity (comma separated)")
+        form.addRow("Tags:", self.tags_input)
+
+        layout.addLayout(form)
+
+        # Description
+        desc_label = QLabel("Description:")
+        layout.addWidget(desc_label)
+
+        self.desc_input = QTextEdit()
+        self.desc_input.setPlaceholderText("Describe what your tool does...")
+        self.desc_input.setPlainText(self._tool.description or "")
+        self.desc_input.setMaximumHeight(100)
+        layout.addWidget(self.desc_input)
+
+        # Status
+        self.status_label = QLabel("")
+        self.status_label.setStyleSheet("color: #718096;")
+        layout.addWidget(self.status_label)
+
+        # Progress
+        self.progress = QProgressBar()
+        self.progress.setRange(0, 0)
+        self.progress.hide()
+        layout.addWidget(self.progress)
+
+        layout.addStretch()
+
+        # Buttons
+        buttons = QHBoxLayout()
+        buttons.addStretch()
+
+        self.btn_cancel = QPushButton("Cancel")
+        self.btn_cancel.setObjectName("secondary")
+        self.btn_cancel.clicked.connect(self.reject)
+        buttons.addWidget(self.btn_cancel)
+
+        self.btn_publish = QPushButton("Publish")
+        self.btn_publish.clicked.connect(self._publish)
+        buttons.addWidget(self.btn_publish)
+
+        layout.addLayout(buttons)
+
+    def _publish(self):
+        """Publish the tool."""
+        version = self.version_input.text().strip()
+        if not version:
+            QMessageBox.warning(self, "Validation", "Version is required")
+            return
+
+        description = self.desc_input.toPlainText().strip()
+        if not description:
+            QMessageBox.warning(self, "Validation", "Description is required")
+            return
+
+        category = self.category_combo.currentText()
+        tags = [t.strip() for t in self.tags_input.text().split(",") if t.strip()]
+
+        # Build tool data for publishing
+        tool_data = {
+            "name": self._tool.name,
+            "version": version,
+            "description": description,
+            "category": category,
+            "tags": tags,
+            "definition": self._tool.to_dict() if hasattr(self._tool, 'to_dict') else {}
+        }
+
+        self.btn_publish.setEnabled(False)
+        self.btn_cancel.setEnabled(False)
+        self.progress.show()
+        self.status_label.setText("Publishing...")
+
+        self._worker = PublishWorker(tool_data)
+        self._worker.success.connect(self._on_success)
+        self._worker.error.connect(self._on_error)
+        self._worker.start()
+
+    def _on_success(self, result: dict):
+        """Handle publish success."""
+        self.progress.hide()
+        self.status_label.setText("Published successfully!")
+        self.status_label.setStyleSheet("color: #38a169; font-weight: 600;")
+
+        QMessageBox.information(
+            self, "Success",
+            f"Tool '{self._tool.name}' has been published.\n\n"
+            f"It will be available after review."
+        )
+        self.accept()
+
+    def _on_error(self, error: str):
+        """Handle publish error."""
+        self.progress.hide()
+        self.btn_publish.setEnabled(True)
+        self.btn_cancel.setEnabled(True)
+        self.status_label.setText(f"Error: {error}")
+        self.status_label.setStyleSheet("color: #e53e3e;")

src/cmdforge/gui/dialogs/step_dialog.py

@@ -0,0 +1,426 @@
+"""Step editor dialogs."""
+
+import ast
+
+from PySide6.QtWidgets import (
+    QDialog, QVBoxLayout, QFormLayout, QLineEdit,
+    QComboBox, QPushButton, QHBoxLayout, QLabel,
+    QPlainTextEdit, QSplitter, QGroupBox, QTextEdit, QMessageBox
+)
+from PySide6.QtCore import Qt, QThread, Signal
+
+from ...tool import PromptStep, CodeStep
+from ...providers import load_providers, call_provider
+from ...profiles import list_profiles
+
+
+class PromptStepDialog(QDialog):
+    """Dialog for editing prompt steps."""
+
+    def __init__(self, parent, step: PromptStep = None):
+        super().__init__(parent)
+        self.setWindowTitle("Edit Prompt Step" if step else "Add Prompt Step")
+        self.setMinimumSize(500, 400)
+        self._step = step
+        self._setup_ui()
+
+        if step:
+            self._load_step(step)
+
+    def _setup_ui(self):
+        """Set up the UI."""
+        layout = QVBoxLayout(self)
+        layout.setSpacing(16)
+
+        # Form
+        form = QFormLayout()
+        form.setSpacing(12)
+
+        # Step name (optional)
+        self.name_input = QLineEdit()
+        self.name_input.setPlaceholderText("Optional display name")
+        form.addRow("Step name:", self.name_input)
+
+        # Provider selection
+        self.provider_combo = QComboBox()
+        providers = load_providers()
+        for provider in sorted(providers, key=lambda p: p.name):
+            self.provider_combo.addItem(provider.name)
+        # Add common defaults if not present
+        for default in ["claude", "gpt", "mock"]:
+            if self.provider_combo.findText(default) < 0:
+                self.provider_combo.addItem(default)
+        form.addRow("Provider:", self.provider_combo)
+
+        # Profile selection
+        self.profile_combo = QComboBox()
+        profiles = list_profiles()
+        for profile in profiles:
+            self.profile_combo.addItem(profile.name)
+            # Set tooltip with description
+            idx = self.profile_combo.count() - 1
+            self.profile_combo.setItemData(idx, profile.description, Qt.ToolTipRole)
+        form.addRow("Profile:", self.profile_combo)
+
+        # Output variable
+        self.output_input = QLineEdit()
+        self.output_input.setPlaceholderText("response")
+        self.output_input.setText("response")
+        form.addRow("Output variable:", self.output_input)
+
+        layout.addLayout(form)
+
+        # Prompt text
+        prompt_label = QLabel("Prompt template:")
+        layout.addWidget(prompt_label)
+
+        self.prompt_input = QPlainTextEdit()
+        self.prompt_input.setPlaceholderText(
+            "Enter your prompt here...\n\n"
+            "Use {input} for stdin input.\n"
+            "Use {variable} for argument values.\n"
+            "Use {prev_output} for previous step output."
+        )
+        layout.addWidget(self.prompt_input, 1)
+
+        # Buttons
+        buttons = QHBoxLayout()
+        buttons.addStretch()
+
+        self.btn_cancel = QPushButton("Cancel")
+        self.btn_cancel.setObjectName("secondary")
+        self.btn_cancel.clicked.connect(self.reject)
+        buttons.addWidget(self.btn_cancel)
+
+        self.btn_ok = QPushButton("OK")
+        self.btn_ok.clicked.connect(self._validate_and_accept)
+        buttons.addWidget(self.btn_ok)
+
+        layout.addLayout(buttons)
+
+    def _load_step(self, step: PromptStep):
+        """Load step data into form."""
+        # Load name
+        if step.name:
+            self.name_input.setText(step.name)
+
+        idx = self.provider_combo.findText(step.provider)
+        if idx >= 0:
+            self.provider_combo.setCurrentIndex(idx)
+        else:
+            self.provider_combo.setCurrentText(step.provider)
+
+        # Load profile
+        if step.profile:
+            idx = self.profile_combo.findText(step.profile)
+            if idx >= 0:
+                self.profile_combo.setCurrentIndex(idx)
+
+        self.output_input.setText(step.output_var)
+        self.prompt_input.setPlainText(step.prompt)
+
+    def _validate_and_accept(self):
+        """Validate and accept."""
+        prompt = self.prompt_input.toPlainText().strip()
+        if not prompt:
+            self.prompt_input.setFocus()
+            return
+
+        output = self.output_input.text().strip()
+        if not output:
+            self.output_input.setFocus()
+            return
+
+        self.accept()
+
+    def get_step(self) -> PromptStep:
+        """Get the step from form data."""
+        profile = self.profile_combo.currentText()
+        # Don't store "None" profile
+        if profile == "None":
+            profile = None
+        # Get name, use None if empty
+        name = self.name_input.text().strip() or None
+        return PromptStep(
+            prompt=self.prompt_input.toPlainText(),
+            provider=self.provider_combo.currentText(),
+            output_var=self.output_input.text().strip(),
+            profile=profile,
+            name=name
+        )
+
+
+class AIGenerateWorker(QThread):
+    """Background worker for AI code generation."""
+    finished = Signal(str)
+    error = Signal(str)
+
+    def __init__(self, provider: str, prompt: str):
+        super().__init__()
+        self.provider = provider
+        self.prompt = prompt
+
+    def run(self):
+        try:
+            result = call_provider(self.provider, self.prompt)
+            if result.success:
+                self.finished.emit(result.text)
+            else:
+                self.error.emit(result.error or "Unknown error")
+        except Exception as e:
+            self.error.emit(str(e))
+
+
+class CodeStepDialog(QDialog):
+    """Dialog for editing code steps with AI assist."""
+
+    def __init__(self, parent, step: CodeStep = None, available_vars: list = None):
+        super().__init__(parent)
+        self.setWindowTitle("Edit Code Step" if step else "Add Code Step")
+        self.setMinimumSize(900, 600)
+        self._step = step
+        self._available_vars = available_vars or ["input"]
+        self._worker = None
+        self._setup_ui()
+
+        if step:
+            self._load_step(step)
+
+    def _setup_ui(self):
+        """Set up the UI with code editor and AI assist panel."""
+        layout = QVBoxLayout(self)
+        layout.setSpacing(12)
+
+        # Top: Step name and Output variable
+        form = QFormLayout()
+        form.setSpacing(8)
+
+        # Step name (optional)
+        self.name_input = QLineEdit()
+        self.name_input.setPlaceholderText("Optional display name")
+        form.addRow("Step name:", self.name_input)
+
+        self.output_input = QLineEdit()
+        self.output_input.setPlaceholderText("result")
+        self.output_input.setText("result")
+        form.addRow("Output variable:", self.output_input)
+        layout.addLayout(form)
+
+        # Available variables display
+        vars_text = ", ".join(self._available_vars)
+        vars_label = QLabel(f"Available variables: {vars_text}")
+        vars_label.setStyleSheet("color: #718096; font-size: 11px;")
+        layout.addWidget(vars_label)
+
+        # Main splitter: Code editor | AI Assist
+        splitter = QSplitter(Qt.Horizontal)
+
+        # Left: Code editor
+        code_group = QGroupBox("Code")
+        code_layout = QVBoxLayout(code_group)
+
+        self.code_input = QPlainTextEdit()
+        self.code_input.setPlaceholderText(
+            "# Python code here\n"
+            "# Access input with: input\n"
+            "# Access args with their variable names\n\n"
+            "result = input.upper()"
+        )
+        font = self.code_input.font()
+        font.setFamily("Consolas, Monaco, monospace")
+        self.code_input.setFont(font)
+        code_layout.addWidget(self.code_input)
+
+        splitter.addWidget(code_group)
+
+        # Right: AI Assist panel
+        ai_group = QGroupBox("AI Assisted Code Generation")
+        ai_layout = QVBoxLayout(ai_group)
+        ai_layout.setSpacing(8)
+
+        # Provider selector
+        provider_layout = QHBoxLayout()
+        provider_layout.addWidget(QLabel("Provider:"))
+        self.ai_provider_combo = QComboBox()
+        providers = load_providers()
+        for provider in sorted(providers, key=lambda p: p.name):
+            self.ai_provider_combo.addItem(provider.name)
+        # Add common defaults if not present
+        for default in ["claude", "gpt", "mock"]:
+            if self.ai_provider_combo.findText(default) < 0:
+                self.ai_provider_combo.addItem(default)
+        self.ai_provider_combo.setMinimumWidth(150)
+        provider_layout.addWidget(self.ai_provider_combo)
+        provider_layout.addStretch()
+        ai_layout.addLayout(provider_layout)
+
+        # Prompt editor
+        prompt_label = QLabel("Describe what you want the code to do:")
+        ai_layout.addWidget(prompt_label)
+
+        self.ai_prompt_input = QPlainTextEdit()
+        self.ai_prompt_input.setPlaceholderText(
+            "Example: Parse the input as JSON and extract the 'name' field"
+        )
+        # Set default prompt template
+        self._set_default_prompt()
+        ai_layout.addWidget(self.ai_prompt_input, 2)
+
+        # Generate button
+        btn_layout = QHBoxLayout()
+        self.btn_generate = QPushButton("Generate Code")
+        self.btn_generate.clicked.connect(self._generate_code)
+        self.btn_generate.setMinimumHeight(32)
+        btn_layout.addStretch()
+        btn_layout.addWidget(self.btn_generate)
+        btn_layout.addStretch()
+        ai_layout.addLayout(btn_layout)
+
+        # Output/feedback area
+        feedback_label = QLabel("AI Response:")
+        ai_layout.addWidget(feedback_label)
+
+        self.ai_output = QTextEdit()
+        self.ai_output.setReadOnly(True)
+        self.ai_output.setPlaceholderText("AI response will appear here...")
+        self.ai_output.setMaximumHeight(100)
+        ai_layout.addWidget(self.ai_output, 1)
+
+        splitter.addWidget(ai_group)
+        splitter.setSizes([450, 450])
+
+        layout.addWidget(splitter, 1)
+
+        # Bottom: OK/Cancel buttons
+        buttons = QHBoxLayout()
+        buttons.addStretch()
+
+        self.btn_cancel = QPushButton("Cancel")
+        self.btn_cancel.setObjectName("secondary")
+        self.btn_cancel.clicked.connect(self.reject)
+        buttons.addWidget(self.btn_cancel)
+
+        self.btn_ok = QPushButton("OK")
+        self.btn_ok.clicked.connect(self._validate_and_accept)
+        buttons.addWidget(self.btn_ok)
+
+        layout.addLayout(buttons)
+
+    def _set_default_prompt(self):
+        """Set the default AI prompt template."""
+        vars_formatted = ', '.join(f'"{{{v}}}"' for v in self._available_vars)
+        default_prompt = f"""Write inline Python code (NOT a function definition) according to my instruction.
+
+The code runs directly with variable substitution. Assign any available variables to a local variable first using triple quotes for multi-line content safety.
+
+Example:
+my_var = \"\"\"{{input}}\"\"\"
+result = my_var.upper()
+
+INSTRUCTION: [Describe what you want the code to do]
+
+CURRENT CODE:
+{{code}}
+
+AVAILABLE VARIABLES: {vars_formatted}
+
+IMPORTANT: Return ONLY executable inline Python code. No function definitions, no markdown fencing, no explanations - just the code."""
+        self.ai_prompt_input.setPlainText(default_prompt)
+
+    def _generate_code(self):
+        """Generate code using AI."""
+        prompt_template = self.ai_prompt_input.toPlainText().strip()
+        if not prompt_template:
+            self.ai_output.setHtml("<span style='color: #e53e3e;'>Please enter a prompt</span>")
+            return
+
+        # Replace {code} placeholder with current code
+        current_code = self.code_input.toPlainText().strip() or "# No code yet"
+        prompt = prompt_template.replace("{code}", current_code)
+
+        provider = self.ai_provider_combo.currentText()
+
+        # Disable button and show loading state
+        self.btn_generate.setEnabled(False)
+        self.btn_generate.setText("Generating...")
+        self.ai_output.setHtml(f"<span style='color: #718096;'>Calling {provider}...</span>")
+
+        # Start worker thread
+        self._worker = AIGenerateWorker(provider, prompt)
+        self._worker.finished.connect(self._on_generate_finished)
+        self._worker.error.connect(self._on_generate_error)
+        self._worker.start()
+
+    def _on_generate_finished(self, result: str):
+        """Handle successful AI generation."""
+        self.btn_generate.setEnabled(True)
+        self.btn_generate.setText("Generate Code")
+
+        # Clean up the result - strip markdown code fences if present
+        code = result.strip()
+        if code.startswith("```python"):
+            code = code[9:]
+        elif code.startswith("```"):
+            code = code[3:]
+        if code.endswith("```"):
+            code = code[:-3]
+        code = code.strip()
+
+        # Update code editor
+        self.code_input.setPlainText(code)
+
+        # Show success message
+        self.ai_output.setHtml(
+            f"<span style='color: #38a169;'>Code generated successfully!</span><br>"
+            f"<span style='color: #718096;'>Response length: {len(result)} chars</span>"
+        )
+
+    def _on_generate_error(self, error: str):
+        """Handle AI generation error."""
+        self.btn_generate.setEnabled(True)
+        self.btn_generate.setText("Generate Code")
+        self.ai_output.setHtml(f"<span style='color: #e53e3e;'>Error: {error}</span>")
+
+    def _load_step(self, step: CodeStep):
+        """Load step data into form."""
+        # Load name
+        if step.name:
+            self.name_input.setText(step.name)
+        self.output_input.setText(step.output_var)
+        self.code_input.setPlainText(step.code)
+
+    def _validate_and_accept(self):
+        """Validate and accept."""
+        code = self.code_input.toPlainText().strip()
+        if not code:
+            self.code_input.setFocus()
+            return
+
+        output = self.output_input.text().strip()
+        if not output:
+            self.output_input.setFocus()
+            return
+
+        # Syntax check the Python code
+        try:
+            ast.parse(code)
+        except SyntaxError as e:
+            line_info = f" (line {e.lineno})" if e.lineno else ""
+            QMessageBox.warning(
+                self, "Syntax Error",
+                f"Python syntax error{line_info}:\n\n{e.msg}"
+            )
+            self.code_input.setFocus()
+            return
+
+        self.accept()
+
+    def get_step(self) -> CodeStep:
+        """Get the step from form data."""
+        # Get name, use None if empty
+        name = self.name_input.text().strip() or None
+        return CodeStep(
+            code=self.code_input.toPlainText(),
+            output_var=self.output_input.text().strip(),
+            name=name
+        )

src/cmdforge/gui/main_window.py

@@ -0,0 +1,249 @@
+"""Main window for CmdForge GUI."""
+
+from PySide6.QtWidgets import (
+    QMainWindow, QWidget, QHBoxLayout, QVBoxLayout,
+    QListWidget, QListWidgetItem, QStackedWidget,
+    QStatusBar, QLabel, QSplitter
+)
+from PySide6.QtCore import Qt, QSize, QSettings
+from PySide6.QtGui import QIcon, QFont, QShortcut, QKeySequence
+
+from .styles import STYLESHEET
+
+
+class MainWindow(QMainWindow):
+    """Main application window with sidebar navigation."""
+
+    def __init__(self):
+        super().__init__()
+        self.setWindowTitle("CmdForge")
+        self.setMinimumSize(1000, 700)
+        self.resize(1200, 800)
+
+        # Apply stylesheet
+        self.setStyleSheet(STYLESHEET)
+
+        # Settings for persistence
+        self._settings = QSettings("CmdForge", "CmdForge")
+
+        # Central widget
+        central = QWidget()
+        self.setCentralWidget(central)
+
+        # Main layout
+        layout = QHBoxLayout(central)
+        layout.setContentsMargins(0, 0, 0, 0)
+        layout.setSpacing(0)
+
+        # Sidebar
+        self.sidebar = QListWidget()
+        self.sidebar.setObjectName("sidebar")
+        self.sidebar.setFixedWidth(180)
+        self.sidebar.setFocusPolicy(Qt.NoFocus)
+        self._setup_sidebar()
+
+        # Stacked pages
+        self.pages = QStackedWidget()
+        self.pages.setObjectName("content_area")
+
+        # Add pages (lazy load to avoid import issues)
+        self._setup_pages()
+
+        # Add to layout
+        layout.addWidget(self.sidebar)
+        layout.addWidget(self.pages, 1)
+
+        # Status bar
+        self.status_bar = QStatusBar()
+        self.setStatusBar(self.status_bar)
+        self.status_bar.showMessage("Ready")
+
+        # Connect sidebar
+        self.sidebar.currentRowChanged.connect(self._on_page_changed)
+        self.sidebar.setCurrentRow(0)
+
+        # Setup keyboard shortcuts
+        self._setup_shortcuts()
+
+        # Restore window geometry
+        self._restore_geometry()
+
+    def _setup_sidebar(self):
+        """Set up sidebar navigation items."""
+        items = [
+            ("CmdForge", "Welcome to CmdForge"),
+            ("Tools", "Manage your tools"),
+            ("Registry", "Browse and install tools"),
+            ("Providers", "Configure AI providers"),
+            ("Profiles", "AI persona profiles"),
+        ]
+
+        font = QFont()
+        font.setPointSize(11)
+
+        for i, (name, tooltip) in enumerate(items):
+            item = QListWidgetItem(name)
+            item.setFont(font)
+            item.setToolTip(tooltip)
+            item.setSizeHint(QSize(180, 48))
+            # Style the CmdForge item differently
+            if i == 0:
+                bold_font = QFont(font)
+                bold_font.setBold(True)
+                item.setFont(bold_font)
+            self.sidebar.addItem(item)
+
+    def _setup_pages(self):
+        """Set up content pages."""
+        # Import pages here to avoid circular imports
+        from .pages.welcome_page import WelcomePage
+        from .pages.tools_page import ToolsPage
+        from .pages.registry_page import RegistryPage
+        from .pages.providers_page import ProvidersPage
+        from .pages.profiles_page import ProfilesPage
+
+        self.welcome_page = WelcomePage(self)
+        self.tools_page = ToolsPage(self)
+        self.registry_page = RegistryPage(self)
+        self.providers_page = ProvidersPage(self)
+        self.profiles_page = ProfilesPage(self)
+
+        self.pages.addWidget(self.welcome_page)
+        self.pages.addWidget(self.tools_page)
+        self.pages.addWidget(self.registry_page)
+        self.pages.addWidget(self.providers_page)
+        self.pages.addWidget(self.profiles_page)
+
+    def _on_page_changed(self, index: int):
+        """Handle page changes."""
+        self.pages.setCurrentIndex(index)
+
+        # Refresh page if it has a refresh method
+        current_page = self.pages.currentWidget()
+        if hasattr(current_page, 'refresh'):
+            current_page.refresh()
+
+    def show_status(self, message: str, timeout: int = 5000):
+        """Show a status bar message."""
+        self.status_bar.showMessage(message, timeout)
+
+    def navigate_to(self, page_name: str):
+        """Navigate to a specific page by name."""
+        page_map = {
+            "welcome": 0,
+            "cmdforge": 0,
+            "tools": 1,
+            "registry": 2,
+            "providers": 3,
+            "profiles": 4,
+        }
+        if page_name.lower() in page_map:
+            self.sidebar.setCurrentRow(page_map[page_name.lower()])
+
+    def open_tool_builder(self, tool_name: str = None):
+        """Open the tool builder page for creating or editing a tool."""
+        from .pages.tool_builder_page import ToolBuilderPage
+
+        # Create builder page
+        builder = ToolBuilderPage(self, tool_name)
+
+        # Add to stack and switch to it
+        index = self.pages.addWidget(builder)
+        self.pages.setCurrentIndex(index)
+
+        # Hide sidebar selection
+        self.sidebar.clearSelection()
+
+    def close_tool_builder(self):
+        """Close the tool builder and return to tools page."""
+        # Remove builder page from stack
+        current = self.pages.currentWidget()
+        if hasattr(current, '__class__') and current.__class__.__name__ == 'ToolBuilderPage':
+            self.pages.removeWidget(current)
+            current.deleteLater()
+
+        # Return to tools page
+        self.sidebar.setCurrentRow(0)
+        self.tools_page.refresh()
+
+    def _setup_shortcuts(self):
+        """Set up keyboard shortcuts."""
+        # Ctrl+N: New tool
+        shortcut_new = QShortcut(QKeySequence("Ctrl+N"), self)
+        shortcut_new.activated.connect(self._shortcut_new_tool)
+
+        # Ctrl+S: Save (when in tool builder)
+        shortcut_save = QShortcut(QKeySequence("Ctrl+S"), self)
+        shortcut_save.activated.connect(self._shortcut_save)
+
+        # Escape: Go back
+        shortcut_escape = QShortcut(QKeySequence("Escape"), self)
+        shortcut_escape.activated.connect(self._shortcut_escape)
+
+        # Ctrl+1/2/3/4: Navigate pages
+        shortcut_page1 = QShortcut(QKeySequence("Ctrl+1"), self)
+        shortcut_page1.activated.connect(lambda: self.sidebar.setCurrentRow(0))
+
+        shortcut_page2 = QShortcut(QKeySequence("Ctrl+2"), self)
+        shortcut_page2.activated.connect(lambda: self.sidebar.setCurrentRow(1))
+
+        shortcut_page3 = QShortcut(QKeySequence("Ctrl+3"), self)
+        shortcut_page3.activated.connect(lambda: self.sidebar.setCurrentRow(2))
+
+        shortcut_page4 = QShortcut(QKeySequence("Ctrl+4"), self)
+        shortcut_page4.activated.connect(lambda: self.sidebar.setCurrentRow(3))
+
+        # Ctrl+R: Refresh current page
+        shortcut_refresh = QShortcut(QKeySequence("Ctrl+R"), self)
+        shortcut_refresh.activated.connect(self._shortcut_refresh)
+
+        # Ctrl+Q: Quit
+        shortcut_quit = QShortcut(QKeySequence("Ctrl+Q"), self)
+        shortcut_quit.activated.connect(self.close)
+
+    def _shortcut_new_tool(self):
+        """Handle Ctrl+N: Create new tool."""
+        self.open_tool_builder()
+        self.show_status("Creating new tool... (Ctrl+S to save)")
+
+    def _shortcut_save(self):
+        """Handle Ctrl+S: Save current tool."""
+        current = self.pages.currentWidget()
+        if hasattr(current, 'save_tool'):
+            current.save_tool()
+
+    def _shortcut_escape(self):
+        """Handle Escape: Go back or close builder."""
+        current = self.pages.currentWidget()
+        if hasattr(current, '__class__') and current.__class__.__name__ == 'ToolBuilderPage':
+            self.close_tool_builder()
+        else:
+            # Could close dialogs if any are open
+            pass
+
+    def _shortcut_refresh(self):
+        """Handle Ctrl+R: Refresh current page."""
+        current = self.pages.currentWidget()
+        if hasattr(current, 'refresh'):
+            current.refresh()
+            self.show_status("Refreshed")
+
+    def _restore_geometry(self):
+        """Restore window geometry from settings."""
+        geometry = self._settings.value("geometry")
+        if geometry:
+            self.restoreGeometry(geometry)
+
+        state = self._settings.value("windowState")
+        if state:
+            self.restoreState(state)
+
+    def _save_geometry(self):
+        """Save window geometry to settings."""
+        self._settings.setValue("geometry", self.saveGeometry())
+        self._settings.setValue("windowState", self.saveState())
+
+    def closeEvent(self, event):
+        """Handle window close - save geometry."""
+        self._save_geometry()
+        super().closeEvent(event)

src/cmdforge/gui/pages/__init__.py

@@ -0,0 +1,9 @@
+"""GUI pages."""
+
+from .welcome_page import WelcomePage
+from .tools_page import ToolsPage
+from .tool_builder_page import ToolBuilderPage
+from .registry_page import RegistryPage
+from .providers_page import ProvidersPage
+
+__all__ = ["WelcomePage", "ToolsPage", "ToolBuilderPage", "RegistryPage", "ProvidersPage"]

src/cmdforge/gui/pages/profiles_page.py

@@ -0,0 +1,250 @@
+"""Profiles page - manage AI persona profiles."""
+
+from PySide6.QtWidgets import (
+    QWidget, QVBoxLayout, QHBoxLayout, QListWidget, QListWidgetItem,
+    QPushButton, QLabel, QGroupBox, QTextEdit, QLineEdit,
+    QFormLayout, QMessageBox, QSplitter
+)
+from PySide6.QtCore import Qt
+
+from ...profiles import list_profiles, save_profile, delete_profile, Profile
+
+
+class ProfilesPage(QWidget):
+    """Profiles management page."""
+
+    def __init__(self, main_window):
+        super().__init__()
+        self.main_window = main_window
+        self._setup_ui()
+        self.refresh()
+
+    def _setup_ui(self):
+        """Set up the UI."""
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(24, 24, 24, 24)
+        layout.setSpacing(16)
+
+        # Header
+        header = QHBoxLayout()
+        title = QLabel("Profiles")
+        title.setObjectName("heading")
+        header.addWidget(title)
+
+        header.addStretch()
+
+        self.btn_new = QPushButton("New Profile")
+        self.btn_new.clicked.connect(self._new_profile)
+        header.addWidget(self.btn_new)
+
+        layout.addLayout(header)
+
+        # Description
+        desc = QLabel(
+            "AI persona profiles inject system instructions into prompts. "
+            "Select a profile when creating a prompt step to customize the AI's behavior."
+        )
+        desc.setWordWrap(True)
+        desc.setStyleSheet("color: #718096;")
+        layout.addWidget(desc)
+
+        # Main content splitter
+        splitter = QSplitter(Qt.Horizontal)
+
+        # Left: Profile list
+        left = QWidget()
+        left_layout = QVBoxLayout(left)
+        left_layout.setContentsMargins(0, 0, 0, 0)
+
+        self.profile_list = QListWidget()
+        self.profile_list.currentItemChanged.connect(self._on_profile_selected)
+        left_layout.addWidget(self.profile_list)
+
+        splitter.addWidget(left)
+
+        # Right: Profile details/editor
+        right = QWidget()
+        right_layout = QVBoxLayout(right)
+        right_layout.setContentsMargins(0, 0, 0, 0)
+
+        # Details group
+        details_box = QGroupBox("Profile Details")
+        details_layout = QFormLayout(details_box)
+        details_layout.setSpacing(12)
+
+        self.name_input = QLineEdit()
+        self.name_input.setPlaceholderText("Profile name")
+        details_layout.addRow("Name:", self.name_input)
+
+        self.desc_input = QLineEdit()
+        self.desc_input.setPlaceholderText("Brief description")
+        details_layout.addRow("Description:", self.desc_input)
+
+        right_layout.addWidget(details_box)
+
+        # System prompt group
+        prompt_box = QGroupBox("System Prompt")
+        prompt_layout = QVBoxLayout(prompt_box)
+
+        self.prompt_input = QTextEdit()
+        self.prompt_input.setPlaceholderText(
+            "Enter the system instructions that will be injected into prompts.\n\n"
+            "Example: You are a helpful assistant who explains things clearly..."
+        )
+        prompt_layout.addWidget(self.prompt_input)
+
+        right_layout.addWidget(prompt_box, 1)
+
+        # Action buttons
+        actions = QHBoxLayout()
+
+        self.btn_save = QPushButton("Save")
+        self.btn_save.clicked.connect(self._save_profile)
+        self.btn_save.setEnabled(False)
+        actions.addWidget(self.btn_save)
+
+        self.btn_delete = QPushButton("Delete")
+        self.btn_delete.setObjectName("danger")
+        self.btn_delete.clicked.connect(self._delete_profile)
+        self.btn_delete.setEnabled(False)
+        actions.addWidget(self.btn_delete)
+
+        actions.addStretch()
+
+        right_layout.addLayout(actions)
+
+        splitter.addWidget(right)
+        splitter.setSizes([300, 500])
+
+        layout.addWidget(splitter, 1)
+
+        # Status label
+        self.status_label = QLabel("")
+        self.status_label.setStyleSheet("color: #718096; font-style: italic;")
+        layout.addWidget(self.status_label)
+
+    def refresh(self):
+        """Refresh the profile list."""
+        self.profile_list.clear()
+        profiles = list_profiles()
+
+        for profile in profiles:
+            item = QListWidgetItem()
+            if profile.builtin:
+                item.setText(f"{profile.name} (built-in)")
+            else:
+                item.setText(profile.name)
+            item.setData(Qt.UserRole, profile)
+            self.profile_list.addItem(item)
+
+        self._clear_form()
+        self.status_label.setText(f"{len(profiles)} profiles available")
+
+    def _on_profile_selected(self, current, previous):
+        """Handle profile selection."""
+        if not current:
+            self._clear_form()
+            return
+
+        profile = current.data(Qt.UserRole)
+        self._load_profile(profile)
+
+    def _load_profile(self, profile: Profile):
+        """Load profile into form."""
+        self.name_input.setText(profile.name)
+        self.desc_input.setText(profile.description)
+        self.prompt_input.setPlainText(profile.system_prompt)
+
+        # Built-in profiles can't be edited
+        is_builtin = profile.builtin
+        self.name_input.setEnabled(not is_builtin)
+        self.desc_input.setEnabled(not is_builtin)
+        self.prompt_input.setEnabled(not is_builtin)
+        self.btn_save.setEnabled(not is_builtin)
+        self.btn_delete.setEnabled(not is_builtin and profile.name != "None")
+
+        if is_builtin:
+            self.status_label.setText("Built-in profile (read-only)")
+        else:
+            self.status_label.setText("Custom profile")
+
+    def _clear_form(self):
+        """Clear the form."""
+        self.name_input.clear()
+        self.name_input.setEnabled(True)
+        self.desc_input.clear()
+        self.desc_input.setEnabled(True)
+        self.prompt_input.clear()
+        self.prompt_input.setEnabled(True)
+        self.btn_save.setEnabled(False)
+        self.btn_delete.setEnabled(False)
+
+    def _new_profile(self):
+        """Start creating a new profile."""
+        self.profile_list.clearSelection()
+        self._clear_form()
+        self.name_input.setFocus()
+        self.btn_save.setEnabled(True)
+        self.status_label.setText("Creating new profile...")
+
+    def _save_profile(self):
+        """Save the current profile."""
+        name = self.name_input.text().strip()
+        if not name:
+            QMessageBox.warning(self, "Validation", "Profile name is required")
+            return
+
+        if name == "None":
+            QMessageBox.warning(self, "Validation", "'None' is a reserved profile name")
+            return
+
+        description = self.desc_input.text().strip()
+        system_prompt = self.prompt_input.toPlainText().strip()
+
+        if not system_prompt:
+            QMessageBox.warning(self, "Validation", "System prompt is required")
+            return
+
+        profile = Profile(
+            name=name,
+            description=description,
+            system_prompt=system_prompt
+        )
+
+        try:
+            save_profile(profile)
+            self.main_window.show_status(f"Saved profile '{name}'")
+            self.refresh()
+            # Select the saved profile
+            for i in range(self.profile_list.count()):
+                item = self.profile_list.item(i)
+                if item.data(Qt.UserRole).name == name:
+                    self.profile_list.setCurrentItem(item)
+                    break
+        except Exception as e:
+            QMessageBox.critical(self, "Error", f"Failed to save profile:\n{e}")
+
+    def _delete_profile(self):
+        """Delete the selected profile."""
+        current = self.profile_list.currentItem()
+        if not current:
+            return
+
+        profile = current.data(Qt.UserRole)
+        if profile.builtin:
+            QMessageBox.warning(self, "Error", "Cannot delete built-in profiles")
+            return
+
+        reply = QMessageBox.question(
+            self, "Confirm Delete",
+            f"Delete profile '{profile.name}'?\n\nThis cannot be undone.",
+            QMessageBox.Yes | QMessageBox.No,
+            QMessageBox.No
+        )
+
+        if reply == QMessageBox.Yes:
+            if delete_profile(profile.name):
+                self.main_window.show_status(f"Deleted profile '{profile.name}'")
+                self.refresh()
+            else:
+                QMessageBox.warning(self, "Error", "Failed to delete profile")

src/cmdforge/gui/pages/providers_page.py

@@ -0,0 +1,214 @@
+"""Providers page - manage AI providers."""
+
+from PySide6.QtWidgets import (
+    QWidget, QVBoxLayout, QHBoxLayout, QTableWidget,
+    QTableWidgetItem, QHeaderView, QPushButton, QLabel,
+    QMessageBox
+)
+from PySide6.QtCore import Qt
+
+from ...providers import Provider, load_providers, delete_provider
+
+
+class ProvidersPage(QWidget):
+    """Provider management page."""
+
+    def __init__(self, main_window):
+        super().__init__()
+        self.main_window = main_window
+        self._setup_ui()
+
+    def _setup_ui(self):
+        """Set up the UI."""
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(24, 24, 24, 24)
+        layout.setSpacing(16)
+
+        # Header
+        header = QWidget()
+        header_layout = QHBoxLayout(header)
+        header_layout.setContentsMargins(0, 0, 0, 0)
+
+        title = QLabel("AI Providers")
+        title.setObjectName("heading")
+        header_layout.addWidget(title)
+
+        header_layout.addStretch()
+
+        self.btn_add = QPushButton("Add Provider")
+        self.btn_add.clicked.connect(self._add_provider)
+        header_layout.addWidget(self.btn_add)
+
+        layout.addWidget(header)
+
+        # Description
+        desc = QLabel(
+            "Providers are external AI commands that CmdForge tools can use. "
+            "Each provider wraps a CLI tool that accepts input on stdin and outputs to stdout."
+        )
+        desc.setWordWrap(True)
+        desc.setStyleSheet("color: #718096;")
+        layout.addWidget(desc)
+
+        # Providers table
+        self.table = QTableWidget()
+        self.table.setColumnCount(3)
+        self.table.setHorizontalHeaderLabels(["Name", "Command", "Description"])
+        self.table.horizontalHeader().setSectionResizeMode(0, QHeaderView.ResizeToContents)
+        self.table.horizontalHeader().setSectionResizeMode(1, QHeaderView.Stretch)
+        self.table.horizontalHeader().setSectionResizeMode(2, QHeaderView.Stretch)
+        self.table.setSelectionBehavior(QTableWidget.SelectRows)
+        self.table.setSelectionMode(QTableWidget.SingleSelection)
+        self.table.verticalHeader().setVisible(False)
+        self.table.itemSelectionChanged.connect(self._on_selection_changed)
+        layout.addWidget(self.table, 1)
+
+        # Action buttons
+        buttons = QWidget()
+        btn_layout = QHBoxLayout(buttons)
+        btn_layout.setContentsMargins(0, 0, 0, 0)
+        btn_layout.setSpacing(12)
+
+        self.btn_edit = QPushButton("Edit")
+        self.btn_edit.setObjectName("secondary")
+        self.btn_edit.clicked.connect(self._edit_provider)
+        self.btn_edit.setEnabled(False)
+        btn_layout.addWidget(self.btn_edit)
+
+        self.btn_delete = QPushButton("Delete")
+        self.btn_delete.setObjectName("danger")
+        self.btn_delete.clicked.connect(self._delete_provider)
+        self.btn_delete.setEnabled(False)
+        btn_layout.addWidget(self.btn_delete)
+
+        btn_layout.addStretch()
+
+        self.btn_test = QPushButton("Test")
+        self.btn_test.clicked.connect(self._test_provider)
+        self.btn_test.setEnabled(False)
+        btn_layout.addWidget(self.btn_test)
+
+        layout.addWidget(buttons)
+
+    def refresh(self):
+        """Refresh the provider list."""
+        providers = load_providers()
+
+        self.table.setRowCount(len(providers))
+        for row, provider in enumerate(sorted(providers, key=lambda p: p.name)):
+            name_item = QTableWidgetItem(provider.name)
+            name_item.setData(Qt.UserRole, provider)
+            self.table.setItem(row, 0, name_item)
+            self.table.setItem(row, 1, QTableWidgetItem(provider.command))
+            self.table.setItem(row, 2, QTableWidgetItem(provider.description or ""))
+
+        self._on_selection_changed()
+
+    def _on_selection_changed(self):
+        """Handle selection change."""
+        has_selection = len(self.table.selectedItems()) > 0
+        self.btn_edit.setEnabled(has_selection)
+        self.btn_delete.setEnabled(has_selection)
+        self.btn_test.setEnabled(has_selection)
+
+    def _get_selected_provider(self) -> tuple:
+        """Get selected provider name and object."""
+        items = self.table.selectedItems()
+        if not items:
+            return None, None
+
+        row = items[0].row()
+        name_item = self.table.item(row, 0)
+        return name_item.text(), name_item.data(Qt.UserRole)
+
+    def _add_provider(self):
+        """Add a new provider."""
+        from ..dialogs.provider_dialog import ProviderDialog
+        dialog = ProviderDialog(self)
+        if dialog.exec():
+            self.refresh()
+            self.main_window.show_status("Provider added")
+
+    def _edit_provider(self):
+        """Edit selected provider."""
+        name, provider = self._get_selected_provider()
+        if not name:
+            return
+
+        from ..dialogs.provider_dialog import ProviderDialog
+        dialog = ProviderDialog(self, name, provider)
+        if dialog.exec():
+            self.refresh()
+            self.main_window.show_status("Provider updated")
+
+    def _delete_provider(self):
+        """Delete selected provider."""
+        name, _ = self._get_selected_provider()
+        if not name:
+            return
+
+        reply = QMessageBox.question(
+            self,
+            "Delete Provider",
+            f"Are you sure you want to delete provider '{name}'?",
+            QMessageBox.Yes | QMessageBox.No,
+            QMessageBox.No
+        )
+
+        if reply == QMessageBox.Yes:
+            try:
+                delete_provider(name)
+                self.refresh()
+                self.main_window.show_status(f"Deleted provider '{name}'")
+            except Exception as e:
+                QMessageBox.critical(self, "Error", f"Failed to delete provider:\n{e}")
+
+    def _test_provider(self):
+        """Test selected provider."""
+        name, provider = self._get_selected_provider()
+        if not name or not provider:
+            return
+
+        import subprocess
+        import shutil
+
+        # Check if command exists
+        cmd_parts = provider.command.split()
+        if not cmd_parts:
+            QMessageBox.warning(self, "Invalid", "Provider has no command configured")
+            return
+
+        exe = cmd_parts[0]
+        if not shutil.which(exe):
+            QMessageBox.warning(
+                self, "Not Found",
+                f"Command '{exe}' not found in PATH.\n\n"
+                "Make sure the provider is installed and accessible."
+            )
+            return
+
+        # Try running with --help or similar
+        try:
+            result = subprocess.run(
+                cmd_parts + ["--help"],
+                capture_output=True,
+                text=True,
+                timeout=5
+            )
+            QMessageBox.information(
+                self, "Provider Test",
+                f"Provider '{name}' is available.\n\n"
+                f"Command: {provider.command}\n"
+                f"Exit code: {result.returncode}"
+            )
+        except subprocess.TimeoutExpired:
+            QMessageBox.information(
+                self, "Provider Test",
+                f"Provider '{name}' command exists but timed out.\n"
+                "This may be normal for interactive commands."
+            )
+        except Exception as e:
+            QMessageBox.warning(
+                self, "Provider Test",
+                f"Error testing provider:\n{e}"
+            )

src/cmdforge/gui/pages/registry_page.py

@@ -0,0 +1,583 @@
+"""Registry page - browse and install tools from registry."""
+
+from PySide6.QtWidgets import (
+    QWidget, QVBoxLayout, QHBoxLayout, QLineEdit,
+    QPushButton, QTableWidget, QTableWidgetItem, QLabel,
+    QHeaderView, QGroupBox, QTextBrowser, QSplitter, QMessageBox,
+    QComboBox, QFrame
+)
+from PySide6.QtCore import Qt, QThread, Signal
+from PySide6.QtGui import QColor
+
+from ...registry_client import RegistryClient, RegistryError
+from ...config import load_config
+from ...tool import list_tools, load_tool
+
+
+class SearchWorker(QThread):
+    """Background worker for registry search."""
+    finished = Signal(object)  # PaginatedResponse
+    error = Signal(str)
+
+    def __init__(self, query: str = "", category: str = None, sort: str = "downloads",
+                 tags: list = None, page: int = 1, per_page: int = 20):
+        super().__init__()
+        self.query = query
+        self.category = category
+        self.sort = sort
+        self.tags = tags
+        self.page = page
+        self.per_page = per_page
+
+    def run(self):
+        try:
+            client = RegistryClient()
+            category = self.category if self.category and self.category != "All" else None
+
+            # Use list_tools for browsing (no query/tags), search_tools for searching
+            if not self.query and not self.tags:
+                result = client.list_tools(
+                    category=category,
+                    page=self.page,
+                    per_page=self.per_page,
+                    sort=self.sort
+                )
+            else:
+                result = client.search_tools(
+                    self.query,
+                    category=category,
+                    tags=self.tags,
+                    page=self.page,
+                    per_page=self.per_page,
+                    sort=self.sort,
+                    include_facets=True
+                )
+            self.finished.emit(result)
+        except Exception as e:
+            self.error.emit(str(e))
+
+
+class InstallWorker(QThread):
+    """Background worker for tool installation."""
+    finished = Signal(str)
+    error = Signal(str)
+
+    def __init__(self, owner: str, name: str):
+        super().__init__()
+        self.owner = owner
+        self.name = name
+
+    def run(self):
+        try:
+            client = RegistryClient()
+            client.install_tool(self.owner, self.name)
+            self.finished.emit(f"{self.owner}/{self.name}")
+        except Exception as e:
+            self.error.emit(str(e))
+
+
+class RegistryPage(QWidget):
+    """Registry browser page."""
+
+    def __init__(self, main_window):
+        super().__init__()
+        self.main_window = main_window
+        self._search_worker = None
+        self._install_worker = None
+        self._selected_tool = None
+        self._current_page = 1
+        self._total_pages = 1
+        self._current_tags = []
+        self._installed_tools = {}  # name -> version
+        self._setup_ui()
+
+    def _setup_ui(self):
+        """Set up the UI."""
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(24, 24, 24, 24)
+        layout.setSpacing(16)
+
+        # Header
+        header = QHBoxLayout()
+        title = QLabel("Tool Registry")
+        title.setObjectName("heading")
+        header.addWidget(title)
+        header.addStretch()
+
+        # Browse all button
+        self.btn_browse = QPushButton("Browse All")
+        self.btn_browse.clicked.connect(self._browse_all)
+        header.addWidget(self.btn_browse)
+
+        layout.addLayout(header)
+
+        # Search and filters row
+        filters_box = QWidget()
+        filters_layout = QHBoxLayout(filters_box)
+        filters_layout.setContentsMargins(0, 0, 0, 0)
+        filters_layout.setSpacing(12)
+
+        # Search input
+        self.search_input = QLineEdit()
+        self.search_input.setPlaceholderText("Search tools...")
+        self.search_input.returnPressed.connect(self._do_search)
+        filters_layout.addWidget(self.search_input, 2)
+
+        # Category filter
+        cat_label = QLabel("Category:")
+        filters_layout.addWidget(cat_label)
+        self.category_combo = QComboBox()
+        self.category_combo.addItems(["All", "Text", "Developer", "Data", "Other"])
+        self.category_combo.setMinimumWidth(100)
+        self.category_combo.currentTextChanged.connect(self._on_filter_changed)
+        filters_layout.addWidget(self.category_combo)
+
+        # Sort dropdown
+        sort_label = QLabel("Sort:")
+        filters_layout.addWidget(sort_label)
+        self.sort_combo = QComboBox()
+        self.sort_combo.addItem("Most Popular", "downloads")
+        self.sort_combo.addItem("Newest", "published_at")
+        self.sort_combo.addItem("Name (A-Z)", "name")
+        self.sort_combo.setMinimumWidth(120)
+        self.sort_combo.currentIndexChanged.connect(self._on_filter_changed)
+        filters_layout.addWidget(self.sort_combo)
+
+        # Search button
+        self.btn_search = QPushButton("Search")
+        self.btn_search.clicked.connect(self._do_search)
+        filters_layout.addWidget(self.btn_search)
+
+        layout.addWidget(filters_box)
+
+        # Active tags display
+        self.tags_widget = QWidget()
+        self.tags_layout = QHBoxLayout(self.tags_widget)
+        self.tags_layout.setContentsMargins(0, 0, 0, 0)
+        self.tags_layout.setSpacing(8)
+        self.tags_label = QLabel("Filtering by tags:")
+        self.tags_label.setStyleSheet("color: #718096;")
+        self.tags_layout.addWidget(self.tags_label)
+        self.tags_layout.addStretch()
+        self.tags_widget.hide()
+        layout.addWidget(self.tags_widget)
+
+        # Content splitter
+        splitter = QSplitter(Qt.Horizontal)
+
+        # Left: Results table
+        left = QWidget()
+        left_layout = QVBoxLayout(left)
+        left_layout.setContentsMargins(0, 0, 0, 0)
+
+        self.results_table = QTableWidget()
+        self.results_table.setColumnCount(6)
+        self.results_table.setHorizontalHeaderLabels(["", "Name", "Owner", "Rating", "Downloads", "Version"])
+        self.results_table.horizontalHeader().setSectionResizeMode(0, QHeaderView.Fixed)
+        self.results_table.setColumnWidth(0, 30)  # Installed indicator
+        self.results_table.horizontalHeader().setSectionResizeMode(1, QHeaderView.Stretch)
+        self.results_table.horizontalHeader().setSectionResizeMode(2, QHeaderView.ResizeToContents)
+        self.results_table.horizontalHeader().setSectionResizeMode(3, QHeaderView.ResizeToContents)
+        self.results_table.horizontalHeader().setSectionResizeMode(4, QHeaderView.ResizeToContents)
+        self.results_table.horizontalHeader().setSectionResizeMode(5, QHeaderView.ResizeToContents)
+        self.results_table.setSelectionBehavior(QTableWidget.SelectRows)
+        self.results_table.setSelectionMode(QTableWidget.SingleSelection)
+        self.results_table.verticalHeader().setVisible(False)
+        self.results_table.itemSelectionChanged.connect(self._on_selection_changed)
+        left_layout.addWidget(self.results_table)
+
+        # Pagination controls
+        pagination = QWidget()
+        pag_layout = QHBoxLayout(pagination)
+        pag_layout.setContentsMargins(0, 8, 0, 0)
+
+        self.btn_prev = QPushButton("← Previous")
+        self.btn_prev.clicked.connect(self._prev_page)
+        self.btn_prev.setEnabled(False)
+        pag_layout.addWidget(self.btn_prev)
+
+        pag_layout.addStretch()
+
+        self.page_label = QLabel("Page 1 of 1")
+        self.page_label.setStyleSheet("color: #718096;")
+        pag_layout.addWidget(self.page_label)
+
+        pag_layout.addStretch()
+
+        self.btn_next = QPushButton("Next →")
+        self.btn_next.clicked.connect(self._next_page)
+        self.btn_next.setEnabled(False)
+        pag_layout.addWidget(self.btn_next)
+
+        left_layout.addWidget(pagination)
+
+        splitter.addWidget(left)
+
+        # Right: Tool details
+        right = QWidget()
+        right_layout = QVBoxLayout(right)
+        right_layout.setContentsMargins(0, 0, 0, 0)
+
+        details_box = QGroupBox("Tool Details")
+        details_layout = QVBoxLayout(details_box)
+
+        self.details_text = QTextBrowser()
+        self.details_text.setOpenExternalLinks(False)
+        self.details_text.anchorClicked.connect(self._on_tag_clicked)
+        details_layout.addWidget(self.details_text)
+
+        right_layout.addWidget(details_box, 1)
+
+        # Action buttons
+        actions = QHBoxLayout()
+
+        self.btn_install = QPushButton("Install")
+        self.btn_install.clicked.connect(self._install_tool)
+        self.btn_install.setEnabled(False)
+        actions.addWidget(self.btn_install)
+
+        self.btn_update = QPushButton("Update Available")
+        self.btn_update.clicked.connect(self._install_tool)
+        self.btn_update.setEnabled(False)
+        self.btn_update.setStyleSheet("background-color: #48bb78; color: white;")
+        self.btn_update.hide()
+        actions.addWidget(self.btn_update)
+
+        right_layout.addLayout(actions)
+
+        splitter.addWidget(right)
+        splitter.setSizes([550, 450])
+
+        layout.addWidget(splitter, 1)
+
+        # Status label
+        self.status_label = QLabel("")
+        self.status_label.setStyleSheet("color: #718096;")
+        layout.addWidget(self.status_label)
+
+    def refresh(self):
+        """Refresh on page enter - load popular tools."""
+        self._load_installed_tools()
+        self._browse_all()
+
+    def _load_installed_tools(self):
+        """Load list of installed tools and their versions."""
+        self._installed_tools = {}
+        for name in list_tools():
+            tool = load_tool(name)
+            if tool:
+                self._installed_tools[name] = tool.version or "1.0.0"
+
+    def _browse_all(self):
+        """Browse all tools (no search query)."""
+        self.search_input.clear()
+        self._current_page = 1
+        self._do_search()
+
+    def _on_filter_changed(self):
+        """Handle filter/sort change."""
+        self._current_page = 1
+        self._do_search()
+
+    def _do_search(self):
+        """Perform search with current filters."""
+        query = self.search_input.text().strip()
+        category = self.category_combo.currentText()
+        sort = self.sort_combo.currentData()
+
+        self.btn_search.setEnabled(False)
+        self.btn_browse.setEnabled(False)
+        self.status_label.setText("Searching...")
+        self.results_table.setRowCount(0)
+
+        self._search_worker = SearchWorker(
+            query=query,
+            category=category,
+            sort=sort,
+            tags=self._current_tags if self._current_tags else None,
+            page=self._current_page,
+            per_page=20
+        )
+        self._search_worker.finished.connect(self._on_search_complete)
+        self._search_worker.error.connect(self._on_search_error)
+        self._search_worker.start()
+
+    def _on_search_complete(self, result):
+        """Handle search results."""
+        self.btn_search.setEnabled(True)
+        self.btn_browse.setEnabled(True)
+
+        tools = result.data
+        self._total_pages = result.total_pages or 1
+        total = result.total or len(tools)
+
+        self.status_label.setText(f"Found {total} tools")
+        self.page_label.setText(f"Page {self._current_page} of {self._total_pages}")
+
+        # Update pagination buttons
+        self.btn_prev.setEnabled(self._current_page > 1)
+        self.btn_next.setEnabled(self._current_page < self._total_pages)
+
+        self.results_table.setRowCount(len(tools))
+        for row, tool in enumerate(tools):
+            tool_name = tool.get("name", "")
+
+            # Installed indicator
+            installed_item = QTableWidgetItem()
+            if tool_name in self._installed_tools:
+                installed_version = self._installed_tools[tool_name]
+                registry_version = tool.get("version", "1.0.0")
+                if installed_version != registry_version:
+                    installed_item.setText("↑")  # Update available
+                    installed_item.setToolTip(f"Update available: {installed_version} → {registry_version}")
+                    installed_item.setForeground(QColor("#48bb78"))
+                else:
+                    installed_item.setText("✓")
+                    installed_item.setToolTip("Installed")
+                    installed_item.setForeground(QColor("#4299e1"))
+            installed_item.setTextAlignment(Qt.AlignCenter)
+            self.results_table.setItem(row, 0, installed_item)
+
+            # Name
+            name_item = QTableWidgetItem(tool_name)
+            name_item.setData(Qt.UserRole, tool)
+            self.results_table.setItem(row, 1, name_item)
+
+            # Owner
+            self.results_table.setItem(row, 2, QTableWidgetItem(tool.get("owner", "")))
+
+            # Rating (stars)
+            rating = tool.get("average_rating", 0) or 0
+            rating_count = tool.get("rating_count", 0) or 0
+            stars = self._rating_to_stars(rating)
+            rating_item = QTableWidgetItem(f"{stars} ({rating_count})")
+            rating_item.setToolTip(f"{rating:.1f}/5 from {rating_count} ratings")
+            self.results_table.setItem(row, 3, rating_item)
+
+            # Downloads
+            downloads = tool.get("downloads", 0)
+            downloads_str = self._format_downloads(downloads)
+            self.results_table.setItem(row, 4, QTableWidgetItem(downloads_str))
+
+            # Version
+            self.results_table.setItem(row, 5, QTableWidgetItem(tool.get("version", "1.0.0")))
+
+    def _rating_to_stars(self, rating: float) -> str:
+        """Convert rating to star display."""
+        if rating <= 0:
+            return "☆☆☆☆☆"
+        full_stars = int(rating)
+        half_star = rating - full_stars >= 0.5
+        empty_stars = 5 - full_stars - (1 if half_star else 0)
+        return "★" * full_stars + ("½" if half_star else "") + "☆" * empty_stars
+
+    def _format_downloads(self, downloads: int) -> str:
+        """Format download count."""
+        if downloads >= 1000000:
+            return f"{downloads/1000000:.1f}M"
+        elif downloads >= 1000:
+            return f"{downloads/1000:.1f}K"
+        return str(downloads)
+
+    def _on_search_error(self, error: str):
+        """Handle search error."""
+        self.btn_search.setEnabled(True)
+        self.btn_browse.setEnabled(True)
+        self.status_label.setText(f"Error: {error}")
+
+    def _prev_page(self):
+        """Go to previous page."""
+        if self._current_page > 1:
+            self._current_page -= 1
+            self._do_search()
+
+    def _next_page(self):
+        """Go to next page."""
+        if self._current_page < self._total_pages:
+            self._current_page += 1
+            self._do_search()
+
+    def _on_selection_changed(self):
+        """Handle selection change."""
+        items = self.results_table.selectedItems()
+        if not items:
+            self._selected_tool = None
+            self.details_text.clear()
+            self.btn_install.setEnabled(False)
+            self.btn_update.hide()
+            return
+
+        row = items[0].row()
+        name_item = self.results_table.item(row, 1)
+        tool = name_item.data(Qt.UserRole)
+        self._selected_tool = tool
+        self._show_tool_details(tool)
+
+        # Check if installed / update available
+        tool_name = tool.get("name", "")
+        if tool_name in self._installed_tools:
+            installed_version = self._installed_tools[tool_name]
+            registry_version = tool.get("version", "1.0.0")
+            if installed_version != registry_version:
+                self.btn_install.hide()
+                self.btn_update.show()
+                self.btn_update.setEnabled(True)
+                self.btn_update.setText(f"Update ({installed_version} → {registry_version})")
+            else:
+                self.btn_install.setText("Reinstall")
+                self.btn_install.setEnabled(True)
+                self.btn_install.show()
+                self.btn_update.hide()
+        else:
+            self.btn_install.setText("Install")
+            self.btn_install.setEnabled(True)
+            self.btn_install.show()
+            self.btn_update.hide()
+
+    def _show_tool_details(self, tool: dict):
+        """Show tool details."""
+        lines = []
+        owner = tool.get('owner', '')
+        name = tool.get('name', '')
+
+        lines.append(f"<h2>{owner}/{name}</h2>")
+
+        if tool.get("description"):
+            lines.append(f"<p style='color: #4a5568;'>{tool.get('description')}</p>")
+
+        # Rating display
+        rating = tool.get("average_rating", 0) or 0
+        rating_count = tool.get("rating_count", 0) or 0
+        stars = self._rating_to_stars(rating)
+        lines.append(f"<p><strong>Rating:</strong> {stars} ({rating:.1f}/5 from {rating_count} reviews)</p>")
+
+        lines.append(f"<p><strong>Version:</strong> {tool.get('version', '1.0.0')}</p>")
+        lines.append(f"<p><strong>Downloads:</strong> {tool.get('downloads', 0):,}</p>")
+
+        if tool.get("category"):
+            lines.append(f"<p><strong>Category:</strong> {tool.get('category')}</p>")
+
+        # Clickable tags
+        if tool.get("tags"):
+            tags_html = []
+            for tag in tool.get("tags", []):
+                tags_html.append(
+                    f'<a href="tag:{tag}" style="background: #edf2f7; padding: 2px 8px; '
+                    f'border-radius: 4px; text-decoration: none; color: #4a5568; margin-right: 4px;">{tag}</a>'
+                )
+            lines.append(f"<p><strong>Tags:</strong> {''.join(tags_html)}</p>")
+
+        # Publisher info
+        if tool.get("publisher_reputation"):
+            rep = tool.get("publisher_reputation", {})
+            lines.append(f"<p style='margin-top: 16px; color: #718096; font-size: 12px;'>"
+                        f"Publisher: @{owner} · {rep.get('total_tools', 0)} tools · "
+                        f"{rep.get('total_downloads', 0):,} total downloads</p>")
+
+        # Installed status
+        tool_name = tool.get("name", "")
+        if tool_name in self._installed_tools:
+            installed_version = self._installed_tools[tool_name]
+            registry_version = tool.get("version", "1.0.0")
+            if installed_version != registry_version:
+                lines.append(f"<p style='color: #48bb78; font-weight: 600;'>"
+                            f"✓ Installed (v{installed_version}) - Update available!</p>")
+            else:
+                lines.append(f"<p style='color: #4299e1;'>✓ Installed (v{installed_version})</p>")
+
+        self.details_text.setHtml("\n".join(lines))
+
+    def _on_tag_clicked(self, url):
+        """Handle tag click to filter by tag."""
+        tag = url.toString().replace("tag:", "")
+        if tag not in self._current_tags:
+            self._current_tags.append(tag)
+            self._update_tags_display()
+            self._current_page = 1
+            self._do_search()
+
+    def _update_tags_display(self):
+        """Update the active tags display."""
+        # Clear existing tag buttons
+        while self.tags_layout.count() > 2:
+            item = self.tags_layout.takeAt(2)
+            if item.widget():
+                item.widget().deleteLater()
+
+        if self._current_tags:
+            self.tags_widget.show()
+            for tag in self._current_tags:
+                tag_btn = QPushButton(f"{tag} ×")
+                tag_btn.setStyleSheet(
+                    "background: #4299e1; color: white; border: none; "
+                    "padding: 4px 8px; border-radius: 4px;"
+                )
+                tag_btn.clicked.connect(lambda checked, t=tag: self._remove_tag(t))
+                self.tags_layout.insertWidget(self.tags_layout.count() - 1, tag_btn)
+
+            # Add clear all button
+            clear_btn = QPushButton("Clear all")
+            clear_btn.setStyleSheet("color: #e53e3e;")
+            clear_btn.setFlat(True)
+            clear_btn.clicked.connect(self._clear_tags)
+            self.tags_layout.insertWidget(self.tags_layout.count() - 1, clear_btn)
+        else:
+            self.tags_widget.hide()
+
+    def _remove_tag(self, tag: str):
+        """Remove a tag from the filter."""
+        if tag in self._current_tags:
+            self._current_tags.remove(tag)
+            self._update_tags_display()
+            self._current_page = 1
+            self._do_search()
+
+    def _clear_tags(self):
+        """Clear all tag filters."""
+        self._current_tags = []
+        self._update_tags_display()
+        self._current_page = 1
+        self._do_search()
+
+    def _install_tool(self):
+        """Install selected tool."""
+        if not self._selected_tool:
+            return
+
+        owner = self._selected_tool.get("owner", "")
+        name = self._selected_tool.get("name", "")
+
+        self.btn_install.setEnabled(False)
+        self.btn_update.setEnabled(False)
+        self.status_label.setText(f"Installing {owner}/{name}...")
+
+        self._install_worker = InstallWorker(owner, name)
+        self._install_worker.finished.connect(self._on_install_complete)
+        self._install_worker.error.connect(self._on_install_error)
+        self._install_worker.start()
+
+    def _on_install_complete(self, tool_id: str):
+        """Handle install complete."""
+        self.btn_install.setEnabled(True)
+        self.status_label.setText(f"Installed {tool_id}")
+        self.main_window.show_status(f"Installed {tool_id}")
+
+        # Refresh installed tools list
+        self._load_installed_tools()
+
+        # Update the display
+        if self._selected_tool:
+            self._show_tool_details(self._selected_tool)
+            self._on_selection_changed()
+
+        # Refresh the table to update indicators
+        self._do_search()
+
+        QMessageBox.information(self, "Success", f"Successfully installed {tool_id}")
+
+    def _on_install_error(self, error: str):
+        """Handle install error."""
+        self.btn_install.setEnabled(True)
+        self.btn_update.setEnabled(True)
+        self.status_label.setText(f"Error: {error}")
+        QMessageBox.critical(self, "Install Error", f"Failed to install tool:\n{error}")

src/cmdforge/gui/pages/tool_builder_page.py

@@ -0,0 +1,655 @@
+"""Tool builder page - create and edit tools."""
+
+from PySide6.QtWidgets import (
+    QWidget, QVBoxLayout, QHBoxLayout, QFormLayout,
+    QLineEdit, QTextEdit, QComboBox, QPushButton,
+    QGroupBox, QListWidget, QListWidgetItem, QLabel,
+    QMessageBox, QSplitter, QFrame, QStackedWidget,
+    QButtonGroup
+)
+from PySide6.QtCore import Qt
+
+from ...tool import (
+    Tool, ToolArgument, PromptStep, CodeStep,
+    load_tool, save_tool, validate_tool_name, DEFAULT_CATEGORIES
+)
+
+
+class ToolBuilderPage(QWidget):
+    """Tool builder/editor page."""
+
+    def __init__(self, main_window, tool_name: str = None):
+        super().__init__()
+        self.main_window = main_window
+        self.editing = tool_name is not None
+        self.original_name = tool_name
+        self._tool = None
+        self._flow_widget = None  # Lazy-loaded
+
+        self._setup_ui()
+
+        if tool_name:
+            self._load_tool(tool_name)
+
+    def _setup_ui(self):
+        """Set up the UI."""
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(24, 24, 24, 24)
+        layout.setSpacing(16)
+
+        # Header
+        header = QWidget()
+        header_layout = QHBoxLayout(header)
+        header_layout.setContentsMargins(0, 0, 0, 0)
+
+        title = QLabel("Edit Tool" if self.editing else "Create Tool")
+        title.setObjectName("heading")
+        header_layout.addWidget(title)
+
+        header_layout.addStretch()
+
+        self.btn_cancel = QPushButton("Cancel")
+        self.btn_cancel.setObjectName("secondary")
+        self.btn_cancel.clicked.connect(self._cancel)
+        header_layout.addWidget(self.btn_cancel)
+
+        self.btn_save = QPushButton("Save")
+        self.btn_save.clicked.connect(self._save)
+        header_layout.addWidget(self.btn_save)
+
+        layout.addWidget(header)
+
+        # Main form splitter
+        splitter = QSplitter(Qt.Horizontal)
+
+        # Left: Basic info
+        left = QWidget()
+        left_layout = QVBoxLayout(left)
+        left_layout.setContentsMargins(0, 0, 0, 0)
+        left_layout.setSpacing(16)
+
+        # Basic info group
+        info_box = QGroupBox("Basic Information")
+        info_layout = QFormLayout(info_box)
+        info_layout.setSpacing(12)
+
+        self.name_input = QLineEdit()
+        self.name_input.setPlaceholderText("my-tool")
+        info_layout.addRow("Name:", self.name_input)
+
+        self.desc_input = QLineEdit()
+        self.desc_input.setPlaceholderText("A brief description of what this tool does")
+        info_layout.addRow("Description:", self.desc_input)
+
+        self.category_combo = QComboBox()
+        self.category_combo.setEditable(True)
+        for cat in DEFAULT_CATEGORIES:
+            self.category_combo.addItem(cat)
+        info_layout.addRow("Category:", self.category_combo)
+
+        left_layout.addWidget(info_box)
+
+        # Arguments group
+        args_box = QGroupBox("Arguments")
+        args_layout = QVBoxLayout(args_box)
+
+        self.args_list = QListWidget()
+        self.args_list.itemDoubleClicked.connect(self._edit_argument)
+        args_layout.addWidget(self.args_list)
+
+        args_btns = QHBoxLayout()
+        self.btn_add_arg = QPushButton("Add")
+        self.btn_add_arg.clicked.connect(self._add_argument)
+        args_btns.addWidget(self.btn_add_arg)
+
+        self.btn_edit_arg = QPushButton("Edit")
+        self.btn_edit_arg.setObjectName("secondary")
+        self.btn_edit_arg.clicked.connect(self._edit_argument)
+        args_btns.addWidget(self.btn_edit_arg)
+
+        self.btn_del_arg = QPushButton("Delete")
+        self.btn_del_arg.setObjectName("danger")
+        self.btn_del_arg.clicked.connect(self._delete_argument)
+        args_btns.addWidget(self.btn_del_arg)
+
+        args_btns.addStretch()
+        args_layout.addLayout(args_btns)
+
+        left_layout.addWidget(args_box)
+
+        splitter.addWidget(left)
+
+        # Right: Steps and output
+        right = QWidget()
+        right_layout = QVBoxLayout(right)
+        right_layout.setContentsMargins(0, 0, 0, 0)
+        right_layout.setSpacing(16)
+
+        # Steps group with view toggle
+        steps_box = QGroupBox("Steps")
+        steps_layout = QVBoxLayout(steps_box)
+
+        # View toggle header
+        view_header = QHBoxLayout()
+
+        self.btn_list_view = QPushButton("List")
+        self.btn_list_view.setCheckable(True)
+        self.btn_list_view.setChecked(True)
+        self.btn_list_view.setObjectName("viewToggle")
+        self.btn_list_view.clicked.connect(lambda: self._set_view_mode(0))
+
+        self.btn_flow_view = QPushButton("Flow")
+        self.btn_flow_view.setCheckable(True)
+        self.btn_flow_view.setObjectName("viewToggle")
+        self.btn_flow_view.clicked.connect(lambda: self._set_view_mode(1))
+
+        # Button group for mutual exclusivity
+        self.view_group = QButtonGroup(self)
+        self.view_group.addButton(self.btn_list_view, 0)
+        self.view_group.addButton(self.btn_flow_view, 1)
+
+        view_header.addWidget(self.btn_list_view)
+        view_header.addWidget(self.btn_flow_view)
+        view_header.addStretch()
+        steps_layout.addLayout(view_header)
+
+        # Stacked widget for list/flow views
+        self.steps_stack = QStackedWidget()
+
+        # List view (index 0)
+        list_container = QWidget()
+        list_layout = QVBoxLayout(list_container)
+        list_layout.setContentsMargins(0, 0, 0, 0)
+
+        self.steps_list = QListWidget()
+        self.steps_list.itemDoubleClicked.connect(self._edit_step)
+        # Enable drag-drop reordering
+        self.steps_list.setDragDropMode(QListWidget.InternalMove)
+        self.steps_list.setDefaultDropAction(Qt.MoveAction)
+        self.steps_list.model().rowsMoved.connect(self._on_steps_reordered)
+        list_layout.addWidget(self.steps_list)
+
+        self.steps_stack.addWidget(list_container)
+
+        # Flow view placeholder (index 1) - lazy loaded
+        flow_placeholder = QLabel("Loading flow visualization...")
+        flow_placeholder.setAlignment(Qt.AlignCenter)
+        flow_placeholder.setStyleSheet("color: #718096; padding: 40px;")
+        self.steps_stack.addWidget(flow_placeholder)
+
+        steps_layout.addWidget(self.steps_stack)
+
+        # Step action buttons
+        steps_btns = QHBoxLayout()
+        self.btn_add_prompt = QPushButton("Add Prompt")
+        self.btn_add_prompt.clicked.connect(self._add_prompt_step)
+        steps_btns.addWidget(self.btn_add_prompt)
+
+        self.btn_add_code = QPushButton("Add Code")
+        self.btn_add_code.clicked.connect(self._add_code_step)
+        steps_btns.addWidget(self.btn_add_code)
+
+        self.btn_edit_step = QPushButton("Edit")
+        self.btn_edit_step.setObjectName("secondary")
+        self.btn_edit_step.clicked.connect(self._edit_step)
+        steps_btns.addWidget(self.btn_edit_step)
+
+        self.btn_del_step = QPushButton("Delete")
+        self.btn_del_step.setObjectName("danger")
+        self.btn_del_step.clicked.connect(self._delete_step)
+        steps_btns.addWidget(self.btn_del_step)
+
+        steps_btns.addStretch()
+        steps_layout.addLayout(steps_btns)
+
+        right_layout.addWidget(steps_box, 1)  # Steps box gets stretch priority
+
+        # Output group
+        output_box = QGroupBox("Output Template")
+        output_layout = QVBoxLayout(output_box)
+
+        self.output_input = QTextEdit()
+        self.output_input.setPlaceholderText("Use {variable} to reference step outputs, e.g. {response}")
+        self.output_input.setPlainText("{response}")  # Default value
+        self.output_input.setMinimumHeight(80)
+        self.output_input.setMaximumHeight(120)
+        output_layout.addWidget(self.output_input)
+
+        right_layout.addWidget(output_box, 0)  # Output box stays fixed size
+
+        splitter.addWidget(right)
+        splitter.setSizes([400, 600])
+
+        layout.addWidget(splitter, 1)
+
+    def _set_view_mode(self, mode: int):
+        """Switch between list (0) and flow (1) views."""
+        if mode == 1 and self._flow_widget is None:
+            # Lazy-load flow widget
+            self._init_flow_widget()
+
+        self.steps_stack.setCurrentIndex(mode)
+
+        # Update flow widget if visible
+        if mode == 1 and self._flow_widget:
+            self._flow_widget.set_tool(self._tool)
+
+    def _init_flow_widget(self):
+        """Initialize the flow visualization widget."""
+        try:
+            from ..widgets.flow_graph import FlowGraphWidget
+            self._flow_widget = FlowGraphWidget()
+            self._flow_widget.node_double_clicked.connect(self._on_flow_node_double_clicked)
+            self._flow_widget.steps_deleted.connect(self._on_flow_steps_deleted)
+            self._flow_widget.steps_reordered.connect(self._on_flow_steps_reordered)
+
+            # Replace placeholder
+            old_widget = self.steps_stack.widget(1)
+            self.steps_stack.removeWidget(old_widget)
+            old_widget.deleteLater()
+            self.steps_stack.insertWidget(1, self._flow_widget)
+
+            # Set current tool
+            if self._tool:
+                self._flow_widget.set_tool(self._tool)
+        except ImportError as e:
+            # NodeGraphQt not available
+            error_label = QLabel(f"Flow visualization unavailable:\n{e}")
+            error_label.setAlignment(Qt.AlignCenter)
+            error_label.setStyleSheet("color: #e53e3e; padding: 40px;")
+            old_widget = self.steps_stack.widget(1)
+            self.steps_stack.removeWidget(old_widget)
+            old_widget.deleteLater()
+            self.steps_stack.insertWidget(1, error_label)
+
+    def _on_flow_node_double_clicked(self, step_index: int, step_type: str):
+        """Handle double-click on a flow node."""
+        if not self._tool or step_index < 0 or step_index >= len(self._tool.steps):
+            return
+
+        step = self._tool.steps[step_index]
+        self._edit_step_at_index(step_index, step)
+
+    def _on_flow_steps_deleted(self, indices: list):
+        """Handle step deletion from flow view."""
+        if not self._tool:
+            return
+
+        # Delete steps in reverse order (indices are already sorted reverse)
+        for idx in indices:
+            if 0 <= idx < len(self._tool.steps):
+                del self._tool.steps[idx]
+
+        # Refresh the list view (flow view will be refreshed by set_tool)
+        self._refresh_steps()
+
+    def _on_flow_steps_reordered(self, new_order: list):
+        """Handle step reordering from flow view.
+
+        Args:
+            new_order: List of old indices in new order.
+                       e.g., [0, 2, 1] means step 0 stays first,
+                       step 2 moves to second, step 1 moves to third.
+        """
+        if not self._tool or not self._tool.steps:
+            return
+
+        # Reorder steps according to new_order
+        old_steps = self._tool.steps[:]
+        new_steps = [old_steps[i] for i in new_order if i < len(old_steps)]
+
+        # Validate the new order
+        warnings = self._validate_step_order(new_steps)
+
+        if warnings:
+            # Show warning but allow the reorder
+            warning_msg = "Variable dependency warnings:\n\n" + "\n".join(warnings)
+            warning_msg += "\n\nThe reorder has been applied. You may need to fix these issues."
+            QMessageBox.warning(self, "Dependency Warning", warning_msg)
+
+        self._tool.steps = new_steps
+
+        # Refresh both views
+        self._refresh_steps()
+
+    def _load_tool(self, name: str):
+        """Load an existing tool for editing."""
+        tool = load_tool(name)
+        if not tool:
+            QMessageBox.critical(self, "Error", f"Tool '{name}' not found")
+            self._cancel()
+            return
+
+        self._tool = tool
+        self.name_input.setText(tool.name)
+        self.name_input.setEnabled(False)  # Can't rename
+        self.desc_input.setText(tool.description or "")
+
+        # Set category
+        if tool.category:
+            idx = self.category_combo.findText(tool.category)
+            if idx >= 0:
+                self.category_combo.setCurrentIndex(idx)
+            else:
+                self.category_combo.setCurrentText(tool.category)
+
+        # Load arguments
+        self._refresh_arguments()
+
+        # Load steps
+        self._refresh_steps()
+
+        # Set output
+        self.output_input.setPlainText(tool.output or "{response}")
+
+    def _refresh_arguments(self):
+        """Refresh arguments list."""
+        self.args_list.clear()
+        if self._tool and self._tool.arguments:
+            for arg in self._tool.arguments:
+                item = QListWidgetItem(f"{arg.flag} → ${arg.variable}")
+                item.setData(Qt.UserRole, arg)
+                self.args_list.addItem(item)
+
+    def _refresh_steps(self):
+        """Refresh steps list and flow view."""
+        self.steps_list.clear()
+        if self._tool and self._tool.steps:
+            # Count steps by type for default naming
+            prompt_count = 0
+            code_count = 0
+
+            # Track available variables for dependency checking
+            available_vars = {"input"}
+            if self._tool.arguments:
+                for arg in self._tool.arguments:
+                    if arg.variable:
+                        available_vars.add(arg.variable)
+
+            for i, step in enumerate(self._tool.steps, 1):
+                if isinstance(step, PromptStep):
+                    prompt_count += 1
+                    # Use custom name if set, otherwise default per-type naming
+                    step_name = step.name if step.name else f"Prompt {prompt_count}"
+                    text = f"{i}. {step_name} [{step.provider}] → ${step.output_var}"
+                elif isinstance(step, CodeStep):
+                    code_count += 1
+                    step_name = step.name if step.name else f"Code {code_count}"
+                    text = f"{i}. {step_name} [python] → ${step.output_var}"
+                else:
+                    text = f"{i}. Unknown step"
+
+                item = QListWidgetItem(text)
+                item.setData(Qt.UserRole, step)
+
+                # Check for broken dependencies
+                refs = self._get_step_variable_refs(step)
+                broken_refs = [r for r in refs if r not in available_vars]
+                if broken_refs:
+                    # Mark item with warning color and tooltip
+                    item.setForeground(Qt.red)
+                    item.setToolTip(f"Missing variables: {', '.join(broken_refs)}")
+
+                self.steps_list.addItem(item)
+
+                # Add this step's output to available vars for next iteration
+                if hasattr(step, 'output_var') and step.output_var:
+                    for var in step.output_var.split(','):
+                        available_vars.add(var.strip())
+
+        # Update flow widget if initialized
+        if self._flow_widget:
+            self._flow_widget.set_tool(self._tool)
+
+    def _add_argument(self):
+        """Add a new argument."""
+        from ..dialogs.argument_dialog import ArgumentDialog
+        dialog = ArgumentDialog(self)
+        if dialog.exec():
+            arg = dialog.get_argument()
+            if not self._tool:
+                self._tool = Tool(name="", description="", arguments=[], steps=[], output="{response}")
+            self._tool.arguments.append(arg)
+            self._refresh_arguments()
+
+    def _edit_argument(self):
+        """Edit selected argument."""
+        items = self.args_list.selectedItems()
+        if not items:
+            return
+
+        arg = items[0].data(Qt.UserRole)
+        idx = self.args_list.row(items[0])
+
+        from ..dialogs.argument_dialog import ArgumentDialog
+        dialog = ArgumentDialog(self, arg)
+        if dialog.exec():
+            self._tool.arguments[idx] = dialog.get_argument()
+            self._refresh_arguments()
+
+    def _delete_argument(self):
+        """Delete selected argument."""
+        items = self.args_list.selectedItems()
+        if not items:
+            return
+
+        idx = self.args_list.row(items[0])
+        del self._tool.arguments[idx]
+        self._refresh_arguments()
+
+    def _get_available_vars(self, up_to_step: int = -1) -> list:
+        """Get available variables for a step.
+
+        Args:
+            up_to_step: Include variables from steps before this index.
+                       -1 means include all existing steps (for new steps).
+        """
+        vars_list = ["input"]
+
+        # Add argument variables
+        if self._tool and self._tool.arguments:
+            for arg in self._tool.arguments:
+                if arg.variable and arg.variable not in vars_list:
+                    vars_list.append(arg.variable)
+
+        # Add output variables from previous steps
+        if self._tool and self._tool.steps:
+            steps_to_check = self._tool.steps if up_to_step < 0 else self._tool.steps[:up_to_step]
+            for step in steps_to_check:
+                if hasattr(step, 'output_var') and step.output_var:
+                    # Handle comma-separated output vars
+                    for var in step.output_var.split(','):
+                        var = var.strip()
+                        if var and var not in vars_list:
+                            vars_list.append(var)
+
+        return vars_list
+
+    def _add_prompt_step(self):
+        """Add a prompt step."""
+        from ..dialogs.step_dialog import PromptStepDialog
+        dialog = PromptStepDialog(self)
+        if dialog.exec():
+            step = dialog.get_step()
+            if not self._tool:
+                self._tool = Tool(name="", description="", arguments=[], steps=[], output="{response}")
+            self._tool.steps.append(step)
+            self._refresh_steps()
+
+    def _add_code_step(self):
+        """Add a code step."""
+        from ..dialogs.step_dialog import CodeStepDialog
+        available_vars = self._get_available_vars()
+        dialog = CodeStepDialog(self, available_vars=available_vars)
+        if dialog.exec():
+            step = dialog.get_step()
+            if not self._tool:
+                self._tool = Tool(name="", description="", arguments=[], steps=[], output="{response}")
+            self._tool.steps.append(step)
+            self._refresh_steps()
+
+    def _edit_step(self):
+        """Edit selected step from list view."""
+        items = self.steps_list.selectedItems()
+        if not items:
+            return
+
+        step = items[0].data(Qt.UserRole)
+        idx = self.steps_list.row(items[0])
+        self._edit_step_at_index(idx, step)
+
+    def _edit_step_at_index(self, idx: int, step):
+        """Edit a step at a specific index."""
+        if isinstance(step, PromptStep):
+            from ..dialogs.step_dialog import PromptStepDialog
+            dialog = PromptStepDialog(self, step)
+        elif isinstance(step, CodeStep):
+            from ..dialogs.step_dialog import CodeStepDialog
+            available_vars = self._get_available_vars(up_to_step=idx)
+            dialog = CodeStepDialog(self, step, available_vars=available_vars)
+        else:
+            return
+
+        if dialog.exec():
+            self._tool.steps[idx] = dialog.get_step()
+            self._refresh_steps()
+
+    def _delete_step(self):
+        """Delete selected step."""
+        items = self.steps_list.selectedItems()
+        if not items:
+            return
+
+        idx = self.steps_list.row(items[0])
+        del self._tool.steps[idx]
+        self._refresh_steps()
+
+    def _on_steps_reordered(self, parent, start, end, dest, row):
+        """Handle step reordering via drag-drop."""
+        if not self._tool or not self._tool.steps:
+            return
+
+        # Rebuild steps list from current list widget order
+        new_steps = []
+        for i in range(self.steps_list.count()):
+            item = self.steps_list.item(i)
+            step = item.data(Qt.UserRole)
+            if step:
+                new_steps.append(step)
+
+        # Validate the new order
+        warnings = self._validate_step_order(new_steps)
+
+        if warnings:
+            # Show warning but allow the reorder
+            warning_msg = "Variable dependency warnings:\n\n" + "\n".join(warnings)
+            warning_msg += "\n\nThe reorder has been applied. You may need to fix these issues."
+            QMessageBox.warning(self, "Dependency Warning", warning_msg)
+
+        # Apply the new order
+        self._tool.steps = new_steps
+
+        # Refresh to update numbering and flow view
+        self._refresh_steps()
+
+    def _validate_step_order(self, steps: list) -> list:
+        """Validate step order for variable dependencies.
+
+        Returns a list of warning messages for broken dependencies.
+        """
+        warnings = []
+
+        # Track available variables at each position
+        available = {"input"}
+
+        # Add argument variables
+        if self._tool and self._tool.arguments:
+            for arg in self._tool.arguments:
+                if arg.variable:
+                    available.add(arg.variable)
+
+        for i, step in enumerate(steps):
+            # Get variables this step references
+            refs = self._get_step_variable_refs(step)
+
+            # Check for undefined references
+            for ref in refs:
+                if ref not in available:
+                    step_name = step.name if step.name else f"Step {i+1}"
+                    warnings.append(f"{step_name}: references '{{{ref}}}' which is not defined yet")
+
+            # Add this step's output to available vars
+            if hasattr(step, 'output_var') and step.output_var:
+                for var in step.output_var.split(','):
+                    available.add(var.strip())
+
+        return warnings
+
+    def _get_step_variable_refs(self, step) -> set:
+        """Extract variable references from a step.
+
+        Parses {variable} patterns from prompt templates.
+        Note: CodeSteps are NOT parsed because variables are available directly
+        as Python variables, and {var} in code is typically Python f-string
+        or .format() syntax, not CmdForge substitution.
+        """
+        import re
+        refs = set()
+
+        # Pattern to match {variable} but not {{escaped}}
+        pattern = r'\{(\w+)\}'
+
+        if isinstance(step, PromptStep):
+            # Parse prompt template - these ARE CmdForge substitutions
+            matches = re.findall(pattern, step.prompt or "")
+            refs.update(matches)
+        # CodeStep: Don't parse - variables are available as Python vars directly
+        # and {var} syntax is typically Python string formatting
+
+        return refs
+
+    def _save(self):
+        """Save the tool."""
+        name = self.name_input.text().strip()
+        if not name:
+            QMessageBox.warning(self, "Validation", "Tool name is required")
+            return
+
+        # Validate name
+        error = validate_tool_name(name)
+        if error:
+            QMessageBox.warning(self, "Validation", error)
+            return
+
+        description = self.desc_input.text().strip()
+        category = self.category_combo.currentText()
+        output = self.output_input.toPlainText().strip() or "{response}"
+
+        # Build tool object
+        tool = Tool(
+            name=name,
+            description=description,
+            category=category,
+            arguments=self._tool.arguments if self._tool else [],
+            steps=self._tool.steps if self._tool else [],
+            output=output
+        )
+
+        # Preserve source if editing
+        if self._tool and self._tool.source:
+            tool.source = self._tool.source
+
+        try:
+            save_tool(tool)
+            self.main_window.show_status(f"Saved tool '{name}'")
+            self.main_window.close_tool_builder()
+        except Exception as e:
+            QMessageBox.critical(self, "Error", f"Failed to save tool:\n{e}")
+
+    def _cancel(self):
+        """Cancel and return to tools page."""
+        self.main_window.close_tool_builder()
+
+    def save_tool(self):
+        """Public method for keyboard shortcut to save the tool."""
+        self._save()

src/cmdforge/gui/pages/tools_page.py

@@ -0,0 +1,331 @@
+"""Tools page - main view for managing tools."""
+
+from collections import defaultdict
+from PySide6.QtWidgets import (
+    QWidget, QVBoxLayout, QHBoxLayout, QSplitter,
+    QTreeWidget, QTreeWidgetItem, QTextEdit, QLabel,
+    QPushButton, QGroupBox, QMessageBox, QFrame
+)
+from PySide6.QtCore import Qt
+from PySide6.QtGui import QFont
+
+from ...tool import (
+    Tool, ToolArgument, PromptStep, CodeStep, ToolStep,
+    list_tools, load_tool, delete_tool, DEFAULT_CATEGORIES
+)
+from ...config import load_config
+
+
+class ToolsPage(QWidget):
+    """Main tools management page."""
+
+    def __init__(self, main_window):
+        super().__init__()
+        self.main_window = main_window
+        self._current_tool = None
+        self._setup_ui()
+        self.refresh()
+
+    def _setup_ui(self):
+        """Set up the UI."""
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(24, 24, 24, 24)
+        layout.setSpacing(16)
+
+        # Header
+        header = QWidget()
+        header_layout = QHBoxLayout(header)
+        header_layout.setContentsMargins(0, 0, 0, 0)
+
+        title = QLabel("My Tools")
+        title.setObjectName("heading")
+        header_layout.addWidget(title)
+
+        header_layout.addStretch()
+
+        # Connection status
+        config = load_config()
+        if config.registry.token:
+            status = QLabel("Connected to Registry")
+            status.setStyleSheet("color: #38a169; font-weight: 500;")
+        else:
+            status = QLabel("Not connected")
+            status.setStyleSheet("color: #718096;")
+        header_layout.addWidget(status)
+
+        layout.addWidget(header)
+
+        # Main content splitter
+        splitter = QSplitter(Qt.Horizontal)
+
+        # Left side: Tool list
+        left = QWidget()
+        left_layout = QVBoxLayout(left)
+        left_layout.setContentsMargins(0, 0, 0, 0)
+        left_layout.setSpacing(8)
+
+        self.tool_tree = QTreeWidget()
+        self.tool_tree.setHeaderHidden(True)
+        self.tool_tree.setIndentation(16)
+        self.tool_tree.setRootIsDecorated(True)
+        self.tool_tree.itemSelectionChanged.connect(self._on_selection_changed)
+        self.tool_tree.itemDoubleClicked.connect(self._on_double_click)
+        left_layout.addWidget(self.tool_tree, 1)
+
+        splitter.addWidget(left)
+
+        # Right side: Info panel
+        right = QWidget()
+        right_layout = QVBoxLayout(right)
+        right_layout.setContentsMargins(0, 0, 0, 0)
+        right_layout.setSpacing(16)
+
+        # Tool info
+        info_box = QGroupBox("Tool Details")
+        info_layout = QVBoxLayout(info_box)
+
+        self.info_text = QTextEdit()
+        self.info_text.setReadOnly(True)
+        self.info_text.setPlaceholderText("Select a tool to view details")
+        info_layout.addWidget(self.info_text)
+
+        right_layout.addWidget(info_box, 1)
+
+        splitter.addWidget(right)
+
+        # Set splitter sizes
+        splitter.setSizes([350, 650])
+
+        layout.addWidget(splitter, 1)
+
+        # Action buttons
+        buttons = QWidget()
+        btn_layout = QHBoxLayout(buttons)
+        btn_layout.setContentsMargins(0, 0, 0, 0)
+        btn_layout.setSpacing(12)
+
+        self.btn_create = QPushButton("Create")
+        self.btn_create.clicked.connect(self._create_tool)
+        btn_layout.addWidget(self.btn_create)
+
+        self.btn_edit = QPushButton("Edit")
+        self.btn_edit.setObjectName("secondary")
+        self.btn_edit.clicked.connect(self._edit_tool)
+        self.btn_edit.setEnabled(False)
+        btn_layout.addWidget(self.btn_edit)
+
+        self.btn_delete = QPushButton("Delete")
+        self.btn_delete.setObjectName("danger")
+        self.btn_delete.clicked.connect(self._delete_tool)
+        self.btn_delete.setEnabled(False)
+        btn_layout.addWidget(self.btn_delete)
+
+        btn_layout.addStretch()
+
+        # Connect/Publish button
+        config = load_config()
+        if config.registry.token:
+            self.btn_publish = QPushButton("Publish")
+            self.btn_publish.clicked.connect(self._publish_tool)
+            self.btn_publish.setEnabled(False)
+        else:
+            self.btn_publish = QPushButton("Connect")
+            self.btn_publish.clicked.connect(self._connect_registry)
+        btn_layout.addWidget(self.btn_publish)
+
+        layout.addWidget(buttons)
+
+    def refresh(self):
+        """Refresh the tool list."""
+        self.tool_tree.clear()
+        self._current_tool = None
+        self.info_text.clear()
+
+        tools = list_tools()
+
+        # Group tools by category
+        tools_by_category = defaultdict(list)
+        for name in tools:
+            tool = load_tool(name)
+            if tool:
+                category = tool.category if tool.category else "Other"
+                tools_by_category[category].append((name, tool))
+
+        # Build tree with categories
+        all_categories = list(DEFAULT_CATEGORIES)
+        for cat in tools_by_category:
+            if cat not in all_categories:
+                all_categories.append(cat)
+
+        for category in all_categories:
+            if category in tools_by_category and tools_by_category[category]:
+                # Category item
+                cat_item = QTreeWidgetItem([category])
+                cat_item.setExpanded(True)
+                font = cat_item.font(0)
+                font.setBold(True)
+                cat_item.setFont(0, font)
+                cat_item.setFlags(cat_item.flags() & ~Qt.ItemIsSelectable)
+
+                # Tools in category
+                for name, tool in sorted(tools_by_category[category], key=lambda x: x[0]):
+                    tool_item = QTreeWidgetItem([name])
+                    tool_item.setData(0, Qt.UserRole, name)
+                    if tool.source and tool.source.type == "imported":
+                        tool_item.setToolTip(0, f"Imported from {tool.source.url or 'registry'}")
+                    cat_item.addChild(tool_item)
+
+                self.tool_tree.addTopLevelItem(cat_item)
+
+        # Update button states
+        self._update_buttons()
+
+        if not tools:
+            self.info_text.setPlaceholderText(
+                "No tools found.\n\nClick 'Create' to build your first tool, "
+                "or browse the Registry to install community tools."
+            )
+
+    def _on_selection_changed(self):
+        """Handle tool selection change."""
+        items = self.tool_tree.selectedItems()
+        if not items:
+            self._current_tool = None
+            self.info_text.clear()
+            self._update_buttons()
+            return
+
+        item = items[0]
+        tool_name = item.data(0, Qt.UserRole)
+        if not tool_name:
+            self._current_tool = None
+            self.info_text.clear()
+            self._update_buttons()
+            return
+
+        tool = load_tool(tool_name)
+        if tool:
+            self._current_tool = tool
+            self._show_tool_info(tool)
+        self._update_buttons()
+
+    def _on_double_click(self, item, column):
+        """Handle double-click on tool."""
+        tool_name = item.data(0, Qt.UserRole)
+        if tool_name:
+            self._edit_tool()
+
+    def _show_tool_info(self, tool: Tool):
+        """Display tool information."""
+        lines = []
+
+        # Name and description
+        lines.append(f"<h2 style='margin: 0 0 8px 0; color: #2d3748;'>{tool.name}</h2>")
+        if tool.description:
+            lines.append(f"<p style='color: #4a5568; margin-bottom: 16px;'>{tool.description}</p>")
+
+        # Source info
+        if tool.source:
+            source_type = tool.source.type
+            if source_type == "imported":
+                source_url = tool.source.url or "registry"
+                lines.append(f"<p style='color: #718096; font-size: 12px;'>Imported from {source_url}</p>")
+            elif source_type == "forked":
+                lines.append(f"<p style='color: #718096; font-size: 12px;'>Forked from {tool.source.original_tool}</p>")
+
+        # Arguments
+        if tool.arguments:
+            lines.append("<h3 style='color: #4a5568; margin-top: 16px;'>Arguments</h3>")
+            lines.append("<ul style='margin: 8px 0;'>")
+            for arg in tool.arguments:
+                default = f" (default: {arg.default})" if arg.default else ""
+                lines.append(f"<li><code>{arg.flag}</code> → <code>${arg.variable}</code>{default}</li>")
+            lines.append("</ul>")
+
+        # Steps
+        if tool.steps:
+            lines.append("<h3 style='color: #4a5568; margin-top: 16px;'>Steps</h3>")
+            lines.append("<ol style='margin: 8px 0;'>")
+            for i, step in enumerate(tool.steps, 1):
+                if isinstance(step, PromptStep):
+                    lines.append(f"<li><strong>Prompt</strong> using <code>{step.provider}</code> → <code>${step.output_var}</code></li>")
+                elif isinstance(step, CodeStep):
+                    lines.append(f"<li><strong>Code</strong> (python) → <code>${step.output_var}</code></li>")
+                elif isinstance(step, ToolStep):
+                    lines.append(f"<li><strong>Tool</strong>: <code>{step.tool}</code> → <code>${step.output_var}</code></li>")
+            lines.append("</ol>")
+
+        # Output
+        if tool.output:
+            lines.append("<h3 style='color: #4a5568; margin-top: 16px;'>Output Template</h3>")
+            output_escaped = tool.output.replace("<", "&lt;").replace(">", "&gt;")
+            lines.append(f"<pre style='background: #edf2f7; padding: 8px; border-radius: 4px;'>{output_escaped}</pre>")
+
+        # Category
+        if tool.category:
+            lines.append(f"<p style='color: #718096; font-size: 12px; margin-top: 16px;'>Category: {tool.category}</p>")
+
+        self.info_text.setHtml("\n".join(lines))
+
+    def _update_buttons(self):
+        """Update button enabled states."""
+        has_selection = self._current_tool is not None
+        self.btn_edit.setEnabled(has_selection)
+        self.btn_delete.setEnabled(has_selection)
+
+        config = load_config()
+        if config.registry.token:
+            self.btn_publish.setEnabled(has_selection)
+
+    def _create_tool(self):
+        """Create a new tool."""
+        self.main_window.open_tool_builder()
+
+    def _edit_tool(self):
+        """Edit the selected tool."""
+        if self._current_tool:
+            self.main_window.open_tool_builder(self._current_tool.name)
+
+    def _delete_tool(self):
+        """Delete the selected tool."""
+        if not self._current_tool:
+            return
+
+        reply = QMessageBox.question(
+            self,
+            "Delete Tool",
+            f"Are you sure you want to delete '{self._current_tool.name}'?\n\n"
+            "This will remove the tool configuration and wrapper script.",
+            QMessageBox.Yes | QMessageBox.No,
+            QMessageBox.No
+        )
+
+        if reply == QMessageBox.Yes:
+            try:
+                delete_tool(self._current_tool.name)
+                self.main_window.show_status(f"Deleted tool '{self._current_tool.name}'")
+                self.refresh()
+            except Exception as e:
+                QMessageBox.critical(self, "Error", f"Failed to delete tool:\n{e}")
+
+    def _connect_registry(self):
+        """Open connect dialog."""
+        from ..dialogs.connect_dialog import ConnectDialog
+        dialog = ConnectDialog(self)
+        if dialog.exec():
+            self.refresh()
+            self.main_window.show_status("Connected to registry")
+            # Recreate publish button
+            self.btn_publish.setText("Publish")
+            self.btn_publish.clicked.disconnect()
+            self.btn_publish.clicked.connect(self._publish_tool)
+
+    def _publish_tool(self):
+        """Publish the selected tool."""
+        if not self._current_tool:
+            return
+
+        from ..dialogs.publish_dialog import PublishDialog
+        dialog = PublishDialog(self, self._current_tool)
+        if dialog.exec():
+            self.main_window.show_status(f"Published '{self._current_tool.name}'")

src/cmdforge/gui/pages/welcome_page.py

@@ -0,0 +1,175 @@
+"""Welcome page - CmdForge landing page."""
+
+from PySide6.QtWidgets import (
+    QWidget, QVBoxLayout, QHBoxLayout, QLabel, QPushButton,
+    QFrame, QGridLayout, QSizePolicy
+)
+from PySide6.QtCore import Qt
+
+
+class WelcomePage(QWidget):
+    """CmdForge welcome/landing page."""
+
+    def __init__(self, main_window):
+        super().__init__()
+        self.main_window = main_window
+        self._setup_ui()
+
+    def _setup_ui(self):
+        """Set up the UI."""
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(48, 48, 48, 48)
+        layout.setSpacing(32)
+
+        # Top spacer
+        layout.addStretch(1)
+
+        # Logo/title
+        title = QLabel("CmdForge")
+        title.setStyleSheet("""
+            font-size: 48px;
+            font-weight: bold;
+            color: #667eea;
+        """)
+        title.setAlignment(Qt.AlignCenter)
+        layout.addWidget(title)
+
+        # Tagline
+        tagline = QLabel("Build AI-powered command-line tools")
+        tagline.setStyleSheet("""
+            font-size: 18px;
+            color: #718096;
+        """)
+        tagline.setAlignment(Qt.AlignCenter)
+        layout.addWidget(tagline)
+
+        layout.addSpacing(24)
+
+        # Quick actions
+        actions_container = QWidget()
+        actions_container.setMaximumWidth(600)
+        actions_layout = QGridLayout(actions_container)
+        actions_layout.setSpacing(16)
+
+        # Create tool card
+        create_card = self._create_action_card(
+            "Create Tool",
+            "Build a new AI-powered command-line tool with prompts, code, and data flow",
+            "New Tool",
+            self._on_create_tool
+        )
+        actions_layout.addWidget(create_card, 0, 0)
+
+        # Browse registry card
+        registry_card = self._create_action_card(
+            "Browse Registry",
+            "Discover and install tools shared by the community",
+            "Open Registry",
+            self._on_browse_registry
+        )
+        actions_layout.addWidget(registry_card, 0, 1)
+
+        # Manage tools card
+        tools_card = self._create_action_card(
+            "My Tools",
+            "View, edit, and run your existing tools",
+            "Open Tools",
+            self._on_open_tools
+        )
+        actions_layout.addWidget(tools_card, 1, 0)
+
+        # Providers card
+        providers_card = self._create_action_card(
+            "AI Providers",
+            "Configure AI backends like Claude, GPT, and custom providers",
+            "Configure",
+            self._on_open_providers
+        )
+        actions_layout.addWidget(providers_card, 1, 1)
+
+        # Center the actions container
+        actions_wrapper = QHBoxLayout()
+        actions_wrapper.addStretch()
+        actions_wrapper.addWidget(actions_container)
+        actions_wrapper.addStretch()
+        layout.addLayout(actions_wrapper)
+
+        # Bottom spacer
+        layout.addStretch(2)
+
+        # Footer
+        footer = QLabel("CmdForge - AI Tool Builder")
+        footer.setStyleSheet("color: #a0aec0; font-size: 12px;")
+        footer.setAlignment(Qt.AlignCenter)
+        layout.addWidget(footer)
+
+    def _create_action_card(self, title: str, description: str, button_text: str, callback) -> QFrame:
+        """Create an action card widget."""
+        card = QFrame()
+        card.setStyleSheet("""
+            QFrame {
+                background-color: white;
+                border: 1px solid #e2e8f0;
+                border-radius: 8px;
+                padding: 16px;
+            }
+            QFrame:hover {
+                border-color: #667eea;
+            }
+        """)
+        card.setMinimumSize(260, 140)
+
+        layout = QVBoxLayout(card)
+        layout.setContentsMargins(16, 16, 16, 16)
+        layout.setSpacing(8)
+
+        # Title
+        title_label = QLabel(title)
+        title_label.setStyleSheet("font-size: 16px; font-weight: 600; color: #2d3748; border: none;")
+        layout.addWidget(title_label)
+
+        # Description
+        desc_label = QLabel(description)
+        desc_label.setWordWrap(True)
+        desc_label.setStyleSheet("font-size: 13px; color: #718096; border: none;")
+        layout.addWidget(desc_label, 1)
+
+        # Button
+        btn = QPushButton(button_text)
+        btn.clicked.connect(callback)
+        btn.setStyleSheet("""
+            QPushButton {
+                background-color: #667eea;
+                color: white;
+                border: none;
+                border-radius: 4px;
+                padding: 8px 16px;
+                font-weight: 500;
+            }
+            QPushButton:hover {
+                background-color: #5a67d8;
+            }
+        """)
+        layout.addWidget(btn)
+
+        return card
+
+    def _on_create_tool(self):
+        """Handle create tool action."""
+        self.main_window.open_tool_builder()
+
+    def _on_browse_registry(self):
+        """Handle browse registry action."""
+        self.main_window.navigate_to("registry")
+
+    def _on_open_tools(self):
+        """Handle open tools action."""
+        self.main_window.navigate_to("tools")
+
+    def _on_open_providers(self):
+        """Handle open providers action."""
+        self.main_window.navigate_to("providers")
+
+    def refresh(self):
+        """Refresh the page (nothing to refresh)."""
+        pass

src/cmdforge/gui/styles.py

@@ -0,0 +1,398 @@
+"""Modern stylesheet for CmdForge GUI."""
+
+STYLESHEET = """
+/* Main Window */
+QMainWindow {
+    background-color: #f5f5f5;
+}
+
+/* Sidebar */
+#sidebar {
+    background-color: #2d3748;
+    border: none;
+    min-width: 180px;
+    max-width: 180px;
+}
+
+#sidebar::item {
+    color: #e2e8f0;
+    padding: 12px 16px;
+    border: none;
+    border-left: 3px solid transparent;
+}
+
+#sidebar::item:selected {
+    background-color: #4a5568;
+    border-left: 3px solid #667eea;
+    color: white;
+}
+
+#sidebar::item:hover:!selected {
+    background-color: #3d4a5c;
+}
+
+/* Content area */
+QWidget#content_area {
+    background-color: #f7fafc;
+}
+
+/* Buttons */
+QPushButton {
+    background-color: #667eea;
+    color: white;
+    border: none;
+    border-radius: 6px;
+    padding: 8px 16px;
+    font-weight: 500;
+    min-height: 32px;
+}
+
+QPushButton:hover {
+    background-color: #5a67d8;
+}
+
+QPushButton:pressed {
+    background-color: #4c51bf;
+}
+
+QPushButton:disabled {
+    background-color: #a0aec0;
+}
+
+QPushButton#secondary {
+    background-color: #e2e8f0;
+    color: #4a5568;
+}
+
+QPushButton#secondary:hover {
+    background-color: #cbd5e0;
+}
+
+QPushButton#danger {
+    background-color: #e53e3e;
+}
+
+QPushButton#danger:hover {
+    background-color: #c53030;
+}
+
+/* View toggle buttons */
+QPushButton#viewToggle {
+    background-color: #e2e8f0;
+    color: #4a5568;
+    border-radius: 4px;
+    padding: 6px 12px;
+    min-height: 24px;
+    min-width: 60px;
+}
+
+QPushButton#viewToggle:checked {
+    background-color: #667eea;
+    color: white;
+}
+
+QPushButton#viewToggle:hover:!checked {
+    background-color: #cbd5e0;
+}
+
+/* Input fields */
+QLineEdit, QTextEdit, QPlainTextEdit {
+    border: 1px solid #e2e8f0;
+    border-radius: 6px;
+    padding: 8px 12px;
+    background-color: white;
+    selection-background-color: #667eea;
+}
+
+QLineEdit:focus, QTextEdit:focus, QPlainTextEdit:focus {
+    border-color: #667eea;
+    outline: none;
+}
+
+/* Combo boxes */
+QComboBox {
+    border: 1px solid #e2e8f0;
+    border-radius: 6px;
+    padding: 8px 12px;
+    background-color: white;
+    min-height: 20px;
+}
+
+QComboBox:focus {
+    border-color: #667eea;
+}
+
+QComboBox::drop-down {
+    border: none;
+    width: 24px;
+}
+
+QComboBox::down-arrow {
+    image: none;
+    border-left: 5px solid transparent;
+    border-right: 5px solid transparent;
+    border-top: 6px solid #718096;
+    margin-right: 8px;
+}
+
+QComboBox QAbstractItemView {
+    border: 1px solid #e2e8f0;
+    background-color: white;
+    selection-background-color: #667eea;
+}
+
+/* Lists and Trees */
+QListWidget, QTreeWidget, QTableWidget {
+    border: 1px solid #e2e8f0;
+    border-radius: 6px;
+    background-color: white;
+    outline: none;
+}
+
+QListWidget::item, QTreeWidget::item {
+    padding: 8px 12px;
+    border: none;
+}
+
+QListWidget::item:selected, QTreeWidget::item:selected {
+    background-color: #667eea;
+    color: white;
+}
+
+QListWidget::item:hover:!selected, QTreeWidget::item:hover:!selected {
+    background-color: #edf2f7;
+}
+
+/* Table Widget */
+QTableWidget {
+    gridline-color: #e2e8f0;
+}
+
+QTableWidget::item {
+    padding: 8px;
+}
+
+QTableWidget::item:selected {
+    background-color: #667eea;
+    color: white;
+}
+
+QHeaderView::section {
+    background-color: #f7fafc;
+    padding: 8px 12px;
+    border: none;
+    border-bottom: 1px solid #e2e8f0;
+    font-weight: 600;
+    color: #4a5568;
+}
+
+/* Group boxes */
+QGroupBox {
+    font-weight: 600;
+    border: 1px solid #e2e8f0;
+    border-radius: 8px;
+    margin-top: 12px;
+    padding-top: 12px;
+    background-color: white;
+}
+
+QGroupBox::title {
+    subcontrol-origin: margin;
+    subcontrol-position: top left;
+    left: 12px;
+    padding: 0 8px;
+    color: #2d3748;
+}
+
+/* Labels */
+QLabel {
+    color: #2d3748;
+}
+
+QLabel#heading {
+    font-size: 18px;
+    font-weight: 600;
+    color: #1a202c;
+}
+
+QLabel#subheading {
+    font-size: 14px;
+    color: #718096;
+}
+
+QLabel#label {
+    font-weight: 500;
+    color: #4a5568;
+}
+
+/* Scrollbars */
+QScrollBar:vertical {
+    background-color: #f7fafc;
+    width: 12px;
+    border-radius: 6px;
+}
+
+QScrollBar::handle:vertical {
+    background-color: #cbd5e0;
+    border-radius: 6px;
+    min-height: 30px;
+}
+
+QScrollBar::handle:vertical:hover {
+    background-color: #a0aec0;
+}
+
+QScrollBar::add-line:vertical, QScrollBar::sub-line:vertical {
+    height: 0;
+}
+
+QScrollBar:horizontal {
+    background-color: #f7fafc;
+    height: 12px;
+    border-radius: 6px;
+}
+
+QScrollBar::handle:horizontal {
+    background-color: #cbd5e0;
+    border-radius: 6px;
+    min-width: 30px;
+}
+
+QScrollBar::handle:horizontal:hover {
+    background-color: #a0aec0;
+}
+
+QScrollBar::add-line:horizontal, QScrollBar::sub-line:horizontal {
+    width: 0;
+}
+
+/* Status bar */
+QStatusBar {
+    background-color: #f7fafc;
+    border-top: 1px solid #e2e8f0;
+    color: #718096;
+}
+
+/* Splitter */
+QSplitter::handle {
+    background-color: #e2e8f0;
+}
+
+QSplitter::handle:horizontal {
+    width: 2px;
+}
+
+QSplitter::handle:vertical {
+    height: 2px;
+}
+
+/* Tabs */
+QTabWidget::pane {
+    border: 1px solid #e2e8f0;
+    border-radius: 6px;
+    background-color: white;
+}
+
+QTabBar::tab {
+    background-color: #edf2f7;
+    border: 1px solid #e2e8f0;
+    border-bottom: none;
+    padding: 8px 16px;
+    margin-right: 2px;
+    border-top-left-radius: 6px;
+    border-top-right-radius: 6px;
+}
+
+QTabBar::tab:selected {
+    background-color: white;
+    border-bottom: 1px solid white;
+}
+
+QTabBar::tab:hover:!selected {
+    background-color: #e2e8f0;
+}
+
+/* Dialogs */
+QDialog {
+    background-color: #f7fafc;
+}
+
+/* Message boxes */
+QMessageBox {
+    background-color: #f7fafc;
+}
+
+QMessageBox QPushButton {
+    min-width: 80px;
+}
+
+/* Tool tips */
+QToolTip {
+    background-color: #2d3748;
+    color: white;
+    border: none;
+    padding: 6px 10px;
+    border-radius: 4px;
+}
+
+/* Progress bar */
+QProgressBar {
+    border: 1px solid #e2e8f0;
+    border-radius: 6px;
+    background-color: #edf2f7;
+    text-align: center;
+    height: 20px;
+}
+
+QProgressBar::chunk {
+    background-color: #667eea;
+    border-radius: 5px;
+}
+
+/* Spin boxes */
+QSpinBox, QDoubleSpinBox {
+    border: 1px solid #e2e8f0;
+    border-radius: 6px;
+    padding: 8px 12px;
+    background-color: white;
+}
+
+QSpinBox:focus, QDoubleSpinBox:focus {
+    border-color: #667eea;
+}
+
+/* Check boxes and radio buttons */
+QCheckBox, QRadioButton {
+    spacing: 8px;
+    color: #2d3748;
+}
+
+QCheckBox::indicator, QRadioButton::indicator {
+    width: 18px;
+    height: 18px;
+}
+
+QCheckBox::indicator:unchecked {
+    border: 2px solid #cbd5e0;
+    border-radius: 4px;
+    background-color: white;
+}
+
+QCheckBox::indicator:checked {
+    border: 2px solid #667eea;
+    border-radius: 4px;
+    background-color: #667eea;
+}
+
+QRadioButton::indicator:unchecked {
+    border: 2px solid #cbd5e0;
+    border-radius: 9px;
+    background-color: white;
+}
+
+QRadioButton::indicator:checked {
+    border: 2px solid #667eea;
+    border-radius: 9px;
+    background-color: #667eea;
+}
+"""

src/cmdforge/gui/widgets/__init__.py

@@ -0,0 +1,5 @@
+"""Custom widgets for CmdForge GUI."""
+
+from .flow_graph import FlowGraphWidget
+
+__all__ = ['FlowGraphWidget']

src/cmdforge/gui/widgets/flow_graph.py

@@ -0,0 +1,512 @@
+"""Flow visualization widget using NodeGraphQt."""
+
+from typing import Optional, List
+
+from PySide6.QtWidgets import QWidget, QVBoxLayout, QLabel, QMenu
+from PySide6.QtCore import Signal, Qt, QTimer, QEvent, QPropertyAnimation, QEasingCurve
+from PySide6.QtGui import QKeyEvent, QAction
+
+from NodeGraphQt import NodeGraph, BaseNode
+
+from ...tool import Tool, PromptStep, CodeStep
+
+
+# =============================================================================
+# Custom Node Types
+# =============================================================================
+
+class CmdForgeBaseNode(BaseNode):
+    """Base class for CmdForge nodes with common styling."""
+
+    __identifier__ = 'cmdforge'
+
+    def __init__(self):
+        super().__init__()
+        # Store reference to the step data
+        self._step_data = None
+        self._step_index = -1
+
+
+class InputNode(CmdForgeBaseNode):
+    """Node representing tool input (stdin and arguments)."""
+
+    NODE_NAME = 'Input'
+
+    def __init__(self):
+        super().__init__()
+        self.set_color(90, 90, 160)  # Indigo
+        # Default output for stdin
+        self.add_output('input', color=(180, 180, 250))
+
+    def set_arguments(self, arguments: list):
+        """Add output ports for each argument variable."""
+        for arg in arguments:
+            if arg.variable:
+                # Check if port already exists
+                existing = [p.name() for p in self.output_ports()]
+                if arg.variable not in existing:
+                    self.add_output(arg.variable, color=(180, 180, 250))
+
+
+class PromptNode(CmdForgeBaseNode):
+    """Node representing a prompt step."""
+
+    NODE_NAME = 'Prompt'
+
+    def __init__(self):
+        super().__init__()
+        self.set_color(102, 126, 234)  # Indigo (matching CmdForge theme)
+        self.add_input('in', color=(180, 180, 250), multi_input=True)
+        self.add_output('out', color=(180, 250, 180))
+
+        # Add properties for display
+        self.add_text_input('provider', 'Provider', text='claude')
+        self.add_text_input('output_var', 'Output', text='response')
+
+    def set_step(self, step: PromptStep, index: int):
+        """Configure node from a PromptStep."""
+        self._step_data = step
+        self._step_index = index
+        self.set_property('provider', step.provider or 'claude')
+        self.set_property('output_var', step.output_var or 'response')
+        # Update output port name
+        if self.output_ports():
+            self.output_ports()[0]._name = step.output_var or 'response'
+
+
+class CodeNode(CmdForgeBaseNode):
+    """Node representing a code step."""
+
+    NODE_NAME = 'Code'
+
+    def __init__(self):
+        super().__init__()
+        self.set_color(72, 187, 120)  # Green
+        self.add_input('in', color=(180, 250, 180), multi_input=True)
+        self.add_output('out', color=(250, 220, 180))
+
+        # Add properties
+        self.add_text_input('output_var', 'Output', text='result')
+
+    def set_step(self, step: CodeStep, index: int):
+        """Configure node from a CodeStep."""
+        self._step_data = step
+        self._step_index = index
+        self.set_property('output_var', step.output_var or 'result')
+        # Update output port name
+        if self.output_ports():
+            self.output_ports()[0]._name = step.output_var or 'result'
+
+
+class OutputNode(CmdForgeBaseNode):
+    """Node representing tool output."""
+
+    NODE_NAME = 'Output'
+
+    def __init__(self):
+        super().__init__()
+        self.set_color(237, 137, 54)  # Orange
+        self.add_input('in', color=(250, 220, 180), multi_input=True)
+
+
+# =============================================================================
+# Flow Graph Widget
+# =============================================================================
+
+class FlowGraphWidget(QWidget):
+    """Widget for visualizing tool flow as a node graph."""
+
+    # Emitted when a node is double-clicked (step_index, step_type)
+    node_double_clicked = Signal(int, str)
+
+    # Emitted when the flow structure changes
+    flow_changed = Signal()
+
+    # Emitted when steps are deleted from flow view (list of step indices)
+    steps_deleted = Signal(list)
+
+    # Emitted when steps are reordered (new order as list of step indices)
+    steps_reordered = Signal(list)
+
+    def __init__(self, parent=None):
+        super().__init__(parent)
+        self._tool: Optional[Tool] = None
+        self._graph: Optional[NodeGraph] = None
+        self._input_node = None
+        self._output_node = None
+        self._step_nodes: List[CmdForgeBaseNode] = []
+        self._rebuilding = False  # Flag to ignore signals during rebuild
+
+        self._setup_ui()
+
+    def _setup_ui(self):
+        """Set up the UI."""
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(0, 0, 0, 0)
+        layout.setSpacing(0)
+
+        # Create node graph
+        self._graph = NodeGraph()
+
+        # Register custom node types
+        self._graph.register_node(InputNode)
+        self._graph.register_node(PromptNode)
+        self._graph.register_node(CodeNode)
+        self._graph.register_node(OutputNode)
+
+        # Connect signals
+        self._graph.node_double_clicked.connect(self._on_node_double_clicked)
+        self._graph.nodes_deleted.connect(self._on_nodes_deleted)
+        self._graph.port_disconnected.connect(self._on_port_disconnected)
+
+        # Add graph widget
+        layout.addWidget(self._graph.widget, 1)
+
+        # Install event filter to catch F key and focus events on the graph widget
+        self._graph.widget.installEventFilter(self)
+
+        # Create floating help banner (overlay on graph widget)
+        self._help_banner = QLabel(self._graph.widget)
+        self._help_banner.setText(
+            "Pan: Middle-drag  |  "
+            "Zoom: Scroll  |  "
+            "Select: Click/drag  |  "
+            "Edit: Double-click  |  "
+            "Cut links: Alt+Shift+drag  |  "
+            "Select All: A  |  "
+            "Fit: F"
+        )
+        self._help_banner.setStyleSheet("""
+            QLabel {
+                background-color: rgba(45, 55, 72, 0.9);
+                color: #e2e8f0;
+                font-size: 11px;
+                padding: 8px 16px;
+                border-radius: 4px;
+            }
+        """)
+        self._help_banner.adjustSize()
+        self._help_banner.hide()
+
+        # Animation for fading
+        self._fade_animation = QPropertyAnimation(self._help_banner, b"windowOpacity")
+        self._fade_animation.setDuration(500)
+        self._fade_animation.setEasingCurve(QEasingCurve.InOutQuad)
+
+        # Timer for auto-hide
+        self._hide_timer = QTimer(self)
+        self._hide_timer.setSingleShot(True)
+        self._hide_timer.timeout.connect(self._fade_out_banner)
+
+        # Track if mouse is over banner
+        self._help_banner.setMouseTracking(True)
+        self._help_banner.enterEvent = self._on_banner_enter
+        self._help_banner.leaveEvent = self._on_banner_leave
+
+        # Set up context menu
+        self._graph.widget.setContextMenuPolicy(Qt.CustomContextMenu)
+        self._graph.widget.customContextMenuRequested.connect(self._show_context_menu)
+
+    def set_tool(self, tool: Optional[Tool]):
+        """Set the tool to visualize."""
+        self._tool = tool
+        self._rebuild_graph()
+
+    def _rebuild_graph(self):
+        """Rebuild the graph from the tool data."""
+        if not self._graph:
+            return
+
+        # Set flag to ignore signals during rebuild
+        self._rebuilding = True
+
+        try:
+            # Clear existing nodes
+            self._graph.clear_session()
+        except Exception:
+            pass  # Ignore errors during clear
+
+        self._input_node = None
+        self._output_node = None
+        self._step_nodes = []
+
+        if not self._tool:
+            self._rebuilding = False
+            return
+
+        # Create input node
+        self._input_node = self._graph.create_node(
+            'cmdforge.InputNode',
+            name='Input',
+            pos=[-300, 0]
+        )
+        if self._tool.arguments:
+            self._input_node.set_arguments(self._tool.arguments)
+
+        # Create step nodes
+        x_pos = 0
+        prev_node = self._input_node
+
+        # Count steps by type for default naming
+        prompt_count = 0
+        code_count = 0
+
+        for i, step in enumerate(self._tool.steps or []):
+            if isinstance(step, PromptStep):
+                prompt_count += 1
+                # Use custom name if set, otherwise default to "Prompt N" (per type)
+                node_name = step.name if step.name else f'Prompt {prompt_count}'
+                node = self._graph.create_node(
+                    'cmdforge.PromptNode',
+                    name=node_name,
+                    pos=[x_pos, 0]
+                )
+                node.set_step(step, i)
+            elif isinstance(step, CodeStep):
+                code_count += 1
+                # Use custom name if set, otherwise default to "Code N" (per type)
+                node_name = step.name if step.name else f'Code {code_count}'
+                node = self._graph.create_node(
+                    'cmdforge.CodeNode',
+                    name=node_name,
+                    pos=[x_pos, 0]
+                )
+                node.set_step(step, i)
+            else:
+                continue
+
+            self._step_nodes.append(node)
+
+            # Connect to previous node
+            if prev_node and prev_node.output_ports():
+                prev_node.output_ports()[0].connect_to(node.input_ports()[0])
+
+            prev_node = node
+            x_pos += 250
+
+        # Create output node
+        self._output_node = self._graph.create_node(
+            'cmdforge.OutputNode',
+            name='Output',
+            pos=[x_pos, 0]
+        )
+
+        # Connect last step to output
+        if prev_node and prev_node.output_ports():
+            prev_node.output_ports()[0].connect_to(self._output_node.input_ports()[0])
+
+        # Auto-layout and fit view
+        self._graph.auto_layout_nodes()
+
+        # Select all nodes then fit to selection, then clear selection
+        all_nodes = self._graph.all_nodes()
+        for node in all_nodes:
+            node.set_selected(True)
+
+        # Use a timer to fit after the widget is fully rendered
+        # Also clears the rebuilding flag after everything settles
+        QTimer.singleShot(50, self._fit_and_clear_selection)
+
+    def _fit_and_clear_selection(self):
+        """Fit view to all nodes and clear selection."""
+        if self._graph:
+            self._graph.fit_to_selection()
+            # Clear selection
+            self._graph.clear_selection()
+
+        # Clear rebuilding flag - now safe to handle user interactions
+        self._rebuilding = False
+
+    def select_all_nodes(self):
+        """Select all nodes in the graph."""
+        if not self._graph:
+            return
+
+        all_nodes = self._graph.all_nodes()
+        for node in all_nodes:
+            node.set_selected(True)
+
+    def fit_selection(self):
+        """Fit view to show selected nodes (or all if none selected)."""
+        if not self._graph:
+            return
+
+        selected = self._graph.selected_nodes()
+        if not selected:
+            # No selection - fit all nodes
+            all_nodes = self._graph.all_nodes()
+            if not all_nodes:
+                return
+            for node in all_nodes:
+                node.set_selected(True)
+            self._graph.fit_to_selection()
+            self._graph.clear_selection()
+        else:
+            # Fit to current selection (don't clear it)
+            self._graph.fit_to_selection()
+
+    def keyPressEvent(self, event: QKeyEvent):
+        """Handle keyboard shortcuts."""
+        if event.key() == Qt.Key_F:
+            self.fit_selection()
+            event.accept()
+        elif event.key() == Qt.Key_A:
+            self.select_all_nodes()
+            event.accept()
+        else:
+            super().keyPressEvent(event)
+
+    def showEvent(self, event):
+        """Handle widget becoming visible."""
+        super().showEvent(event)
+        # Show help banner when flow view becomes visible
+        QTimer.singleShot(100, self._show_help_banner)
+
+    def eventFilter(self, obj, event):
+        """Filter events from the graph widget to catch keyboard shortcuts."""
+        if event.type() == QEvent.KeyPress:
+            if event.key() == Qt.Key_F:
+                self.fit_selection()
+                return True  # Event handled
+            elif event.key() == Qt.Key_A:
+                self.select_all_nodes()
+                return True  # Event handled
+        elif event.type() == QEvent.Enter:
+            # Show banner when mouse enters the graph area
+            self._show_help_banner()
+        return super().eventFilter(obj, event)
+
+    def _show_help_banner(self):
+        """Show the help banner with fade effect."""
+        if not self._help_banner or not self._graph:
+            return
+
+        # Make sure size is calculated
+        self._help_banner.adjustSize()
+
+        # Position at top center of the graph widget
+        parent_width = self._graph.widget.width()
+        banner_width = self._help_banner.width()
+        x = max(10, (parent_width - banner_width) // 2)
+        self._help_banner.move(x, 10)
+
+        # Raise to front and show
+        self._help_banner.raise_()
+        self._help_banner.show()
+
+        # Start auto-hide timer
+        self._hide_timer.start(3000)  # Hide after 3 seconds
+
+    def _fade_out_banner(self):
+        """Fade out the help banner."""
+        if self._help_banner and self._help_banner.isVisible():
+            # Use a simple hide with timer since windowOpacity doesn't work well on child widgets
+            self._help_banner.hide()
+
+    def _on_banner_enter(self, event):
+        """Mouse entered banner - stop hide timer."""
+        self._hide_timer.stop()
+
+    def _on_banner_leave(self, event):
+        """Mouse left banner - restart hide timer."""
+        self._hide_timer.start(1500)  # Hide 1.5 seconds after mouse leaves
+
+    def _show_context_menu(self, pos):
+        """Show context menu."""
+        menu = QMenu(self._graph.widget)
+
+        select_all_action = QAction("Select All (A)", menu)
+        select_all_action.triggered.connect(self.select_all_nodes)
+        menu.addAction(select_all_action)
+
+        fit_action = QAction("Fit Selection (F)", menu)
+        fit_action.triggered.connect(self.fit_selection)
+        menu.addAction(fit_action)
+
+        menu.exec_(self._graph.widget.mapToGlobal(pos))
+
+    def _on_node_double_clicked(self, node):
+        """Handle node double-click."""
+        if hasattr(node, '_step_index') and node._step_index >= 0:
+            step_type = 'prompt' if isinstance(node, PromptNode) else 'code'
+            self.node_double_clicked.emit(node._step_index, step_type)
+
+    def _on_nodes_deleted(self, nodes):
+        """Handle node deletion from the graph."""
+        # Ignore during rebuild
+        if self._rebuilding:
+            return
+
+        # Collect step indices of deleted step nodes (not Input/Output nodes)
+        deleted_indices = []
+        for node in nodes:
+            if hasattr(node, '_step_index') and node._step_index >= 0:
+                deleted_indices.append(node._step_index)
+
+        if deleted_indices:
+            # Sort in reverse order so we delete from end first
+            deleted_indices.sort(reverse=True)
+            self.steps_deleted.emit(deleted_indices)
+            self.flow_changed.emit()
+
+    def _on_port_disconnected(self, input_port, output_port):
+        """Handle port disconnection - reorder steps.
+
+        When a connection is broken:
+        1. The node that lost its input moves to the end
+        2. The chain reconnects (previous node → next node)
+        3. Disconnected node attaches at the end before Output
+        """
+        # Ignore during rebuild
+        if self._rebuilding:
+            return
+
+        if not self._tool or not self._tool.steps:
+            return
+
+        # Get the nodes involved
+        # input_port belongs to the node that lost its input
+        # output_port belongs to the node that was providing the input
+        disconnected_node = input_port.node()
+        source_node = output_port.node()
+
+        # Only handle step nodes (not Input/Output)
+        if not hasattr(disconnected_node, '_step_index') or disconnected_node._step_index < 0:
+            return
+
+        disconnected_idx = disconnected_node._step_index
+
+        # Find the node that the disconnected node was connected to (its output target)
+        next_node = None
+        if disconnected_node.output_ports():
+            out_port = disconnected_node.output_ports()[0]
+            connected_ports = out_port.connected_ports()
+            if connected_ports:
+                next_node = connected_ports[0].node()
+
+        # Build new order: move disconnected step to end
+        old_order = list(range(len(self._tool.steps)))
+        old_order.remove(disconnected_idx)
+        old_order.append(disconnected_idx)
+
+        # Reconnect the graph visually
+        # Connect source to next (if next is a step node)
+        if next_node and hasattr(next_node, '_step_index') and next_node._step_index >= 0:
+            if source_node.output_ports() and next_node.input_ports():
+                source_node.output_ports()[0].connect_to(next_node.input_ports()[0])
+
+        # Connect the last step (before disconnected) to disconnected node
+        # and disconnected node to output
+        # This will be handled by the rebuild after reorder
+
+        # Emit the new order
+        self.steps_reordered.emit(old_order)
+        self.flow_changed.emit()
+
+    def refresh(self):
+        """Refresh the graph from current tool data."""
+        self._rebuild_graph()
+
+    def get_graph(self) -> Optional[NodeGraph]:
+        """Get the underlying NodeGraph instance."""
+        return self._graph

src/cmdforge/manifest.py

@@ -1,4 +1,4 @@
-"""Project manifest (smarttools.yaml) handling.
+"""Project manifest (cmdforge.yaml) handling.
 
 Manages project-level tool dependencies and overrides.
 """
@@ -11,7 +11,7 @@ from typing import Optional, List, Dict
 import yaml
 
 
-MANIFEST_FILENAME = "smarttools.yaml"
+MANIFEST_FILENAME = "cmdforge.yaml"
 
 
 @dataclass
@@ -76,7 +76,7 @@ class ToolOverride:
 
 @dataclass
 class Manifest:
-    """Project manifest (smarttools.yaml)."""
+    """Project manifest (cmdforge.yaml)."""
     name: str = "my-project"
     version: str = "1.0.0"
     dependencies: List[Dependency] = field(default_factory=list)
@@ -144,7 +144,7 @@ class Manifest:
 
 def find_manifest(start_dir: Optional[Path] = None) -> Optional[Path]:
     """
-    Find smarttools.yaml by searching up from start_dir.
+    Find cmdforge.yaml by searching up from start_dir.
 
     Args:
         start_dir: Directory to start searching from (default: cwd)
@@ -201,7 +201,7 @@ def save_manifest(manifest: Manifest, path: Optional[Path] = None) -> Path:
 
     Args:
         manifest: Manifest to save
-        path: Path to save to (default: ./smarttools.yaml)
+        path: Path to save to (default: ./cmdforge.yaml)
 
     Returns:
         Path where manifest was saved

src/cmdforge/profiles.py

@@ -0,0 +1,177 @@
+"""AI persona profiles for prompt injection."""
+
+import os
+from dataclasses import dataclass, field
+from typing import Optional, List
+from pathlib import Path
+
+import yaml
+
+from .config import get_config_dir
+
+
+@dataclass
+class Profile:
+    """An AI persona profile with system instructions."""
+    name: str
+    description: str = ""
+    system_prompt: str = ""
+    tags: List[str] = field(default_factory=list)
+    builtin: bool = False  # True for default profiles
+
+    def to_dict(self) -> dict:
+        d = {
+            "name": self.name,
+            "description": self.description,
+            "system_prompt": self.system_prompt,
+        }
+        if self.tags:
+            d["tags"] = self.tags
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict, builtin: bool = False) -> "Profile":
+        return cls(
+            name=data.get("name", ""),
+            description=data.get("description", ""),
+            system_prompt=data.get("system_prompt", ""),
+            tags=data.get("tags", []),
+            builtin=builtin
+        )
+
+
+# Built-in default profiles
+DEFAULT_PROFILES = [
+    Profile(
+        name="None",
+        description="No profile - use prompt as-is",
+        system_prompt="",
+        builtin=True
+    ),
+    Profile(
+        name="Comedian",
+        description="Witty and humorous, but stays informative",
+        system_prompt="""You are a witty and humorous assistant who uses humor to make information more engaging and memorable. You're able to be serious when it matters, but you naturally inject levity and clever observations into your responses. You are an expert at explaining things clearly while keeping the reader entertained.""",
+        tags=["creative", "engaging"],
+        builtin=True
+    ),
+    Profile(
+        name="Technical Writer",
+        description="Precise, structured, uses proper terminology",
+        system_prompt="""You are a professional technical writer who prioritizes clarity, precision, and proper structure. You use correct terminology, organize information logically with headers and bullet points when appropriate, and ensure accuracy in all technical details. You write documentation that is both comprehensive and accessible.""",
+        tags=["technical", "documentation"],
+        builtin=True
+    ),
+    Profile(
+        name="Teacher",
+        description="Patient, explains step-by-step, uses analogies",
+        system_prompt="""You are a patient and experienced teacher who excels at breaking down complex topics into understandable parts. You explain concepts step-by-step, use relatable analogies and examples, and check for understanding. You adapt your explanations to the learner's level and never make them feel bad for not knowing something.""",
+        tags=["educational", "patient"],
+        builtin=True
+    ),
+    Profile(
+        name="Concise",
+        description="Brief responses, bullet points, no fluff",
+        system_prompt="""You are a direct and efficient communicator who values brevity. You get straight to the point, use bullet points and short sentences, and avoid unnecessary filler words or lengthy explanations. Every word you write serves a purpose. You provide complete information in the most compact form possible.""",
+        tags=["brief", "efficient"],
+        builtin=True
+    ),
+    Profile(
+        name="Creative",
+        description="Imaginative, thinks outside the box",
+        system_prompt="""You are a highly creative thinker who approaches problems from unexpected angles. You generate novel ideas, make unique connections between concepts, and aren't afraid to suggest unconventional solutions. You balance creativity with practicality, ensuring your ideas are both innovative and actionable.""",
+        tags=["creative", "innovative"],
+        builtin=True
+    ),
+    Profile(
+        name="Code Reviewer",
+        description="Critical eye, suggests improvements, follows best practices",
+        system_prompt="""You are an experienced code reviewer with a keen eye for quality. You identify potential bugs, security issues, and performance problems. You suggest improvements based on best practices and design patterns. You explain the reasoning behind your suggestions and prioritize the most impactful changes. You're constructive, not harsh.""",
+        tags=["developer", "code"],
+        builtin=True
+    ),
+    Profile(
+        name="Analyst",
+        description="Data-driven, objective, thorough analysis",
+        system_prompt="""You are a meticulous analyst who examines information thoroughly and objectively. You consider multiple perspectives, identify patterns and trends, and support your conclusions with evidence. You present findings in a clear, structured manner and acknowledge uncertainties or limitations in your analysis.""",
+        tags=["analytical", "objective"],
+        builtin=True
+    ),
+]
+
+
+def get_profiles_dir() -> Path:
+    """Get the profiles directory path."""
+    profiles_dir = Path(get_config_dir()) / "profiles"
+    profiles_dir.mkdir(parents=True, exist_ok=True)
+    return profiles_dir
+
+
+def load_profile(name: str) -> Optional[Profile]:
+    """Load a profile by name."""
+    # Check built-in profiles first
+    for profile in DEFAULT_PROFILES:
+        if profile.name.lower() == name.lower():
+            return profile
+
+    # Check user profiles
+    profile_path = get_profiles_dir() / f"{name}.yaml"
+    if profile_path.exists():
+        try:
+            with open(profile_path) as f:
+                data = yaml.safe_load(f)
+                return Profile.from_dict(data)
+        except Exception:
+            return None
+
+    return None
+
+
+def save_profile(profile: Profile) -> None:
+    """Save a user profile."""
+    if profile.builtin:
+        raise ValueError("Cannot save built-in profiles")
+
+    profile_path = get_profiles_dir() / f"{profile.name}.yaml"
+    with open(profile_path, "w") as f:
+        yaml.safe_dump(profile.to_dict(), f, default_flow_style=False)
+
+
+def delete_profile(name: str) -> bool:
+    """Delete a user profile."""
+    # Can't delete built-in profiles
+    for profile in DEFAULT_PROFILES:
+        if profile.name.lower() == name.lower():
+            return False
+
+    profile_path = get_profiles_dir() / f"{name}.yaml"
+    if profile_path.exists():
+        profile_path.unlink()
+        return True
+    return False
+
+
+def list_profiles() -> List[Profile]:
+    """List all available profiles (built-in + user)."""
+    profiles = list(DEFAULT_PROFILES)
+
+    # Load user profiles
+    profiles_dir = get_profiles_dir()
+    if profiles_dir.exists():
+        for path in profiles_dir.glob("*.yaml"):
+            try:
+                with open(path) as f:
+                    data = yaml.safe_load(f)
+                    profile = Profile.from_dict(data)
+                    # Don't add duplicates of built-in names
+                    if not any(p.name.lower() == profile.name.lower() for p in profiles):
+                        profiles.append(profile)
+            except Exception:
+                continue
+
+    return profiles
+
+
+def get_profile_names() -> List[str]:
+    """Get list of all profile names."""
+    return [p.name for p in list_profiles()]

src/cmdforge/providers.py

@@ -1,6 +1,7 @@
 """Provider abstraction for AI CLI tools."""
 
 import os
+import shlex
 import subprocess
 import shutil
 from dataclasses import dataclass, field
@@ -11,7 +12,7 @@ import yaml
 
 
 # Default providers config location
-PROVIDERS_FILE = Path.home() / ".smarttools" / "providers.yaml"
+PROVIDERS_FILE = Path.home() / ".cmdforge" / "providers.yaml"
 
 
 @dataclass
@@ -160,21 +161,27 @@ def call_provider(provider_name: str, prompt: str, timeout: int = 300) -> Provid
         return ProviderResult(
             text="",
             success=False,
-            error=f"Provider '{provider_name}' not found. Use 'smarttools providers' to manage providers."
+            error=f"Provider '{provider_name}' not found. Use 'cmdforge providers' to manage providers."
         )
 
     # Parse command (expand environment variables)
     cmd = os.path.expandvars(provider.command)
 
-    # Check if base command exists
-    base_cmd = cmd.split()[0]
+    # Check if base command exists (use shlex for proper quote handling)
+    try:
+        cmd_parts = shlex.split(cmd)
+        base_cmd = cmd_parts[0] if cmd_parts else cmd.split()[0]
+    except ValueError:
+        # shlex failed (unbalanced quotes, etc.) - fall back to simple split
+        base_cmd = cmd.split()[0]
+
     # Expand ~ for the which check
     base_cmd_expanded = os.path.expanduser(base_cmd)
     if not shutil.which(base_cmd_expanded) and not os.path.isfile(base_cmd_expanded):
         return ProviderResult(
             text="",
             success=False,
-            error=f"Command '{base_cmd}' not found. Is it installed and in PATH?\n\nTo install AI providers, run: smarttools providers install"
+            error=f"Command '{base_cmd}' not found. Is it installed and in PATH?\n\nTo install AI providers, run: cmdforge providers install"
         )
 
     try:
@@ -190,7 +197,7 @@ def call_provider(provider_name: str, prompt: str, timeout: int = 300) -> Provid
         if result.returncode != 0:
             error_msg = f"Provider exited with code {result.returncode}: {result.stderr}"
             if "not found" in result.stderr.lower() or "not installed" in result.stderr.lower():
-                error_msg += "\n\nTo install AI providers, run: smarttools providers install"
+                error_msg += "\n\nTo install AI providers, run: cmdforge providers install"
             return ProviderResult(
                 text="",
                 success=False,
@@ -217,14 +224,14 @@ def call_provider(provider_name: str, prompt: str, timeout: int = 300) -> Provid
                           f"To fix this, either:\n"
                           f"  1. Run 'opencode' to connect the {provider_id} provider\n"
                           f"  2. Use --provider to pick a different model (e.g., --provider opencode-pickle)\n"
-                          f"  3. Run 'smarttools ui' to edit the tool's default provider"
+                          f"  3. Run 'cmdforge ui' to edit the tool's default provider"
                 )
 
             stderr_hint = f" (stderr: {stderr[:200]}...)" if len(stderr) > 200 else (f" (stderr: {stderr})" if stderr else "")
             return ProviderResult(
                 text="",
                 success=False,
-                error=f"Provider returned empty output{stderr_hint}.\n\nThis may mean the model is not available. Try a different provider or run: smarttools providers install"
+                error=f"Provider returned empty output{stderr_hint}.\n\nThis may mean the model is not available. Try a different provider or run: cmdforge providers install"
             )
 
         return ProviderResult(text=result.stdout, success=True)

src/cmdforge/registry/db.py

@@ -0,0 +1,537 @@
+"""SQLite storage and schema setup for the registry API."""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+from pathlib import Path
+from typing import Iterable
+
+
+SCHEMA_SQL = """
+CREATE TABLE IF NOT EXISTS publishers (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    email TEXT UNIQUE NOT NULL,
+    password_hash TEXT NOT NULL,
+    slug TEXT UNIQUE NOT NULL,
+    display_name TEXT NOT NULL,
+    bio TEXT,
+    website TEXT,
+    verified BOOLEAN DEFAULT FALSE,
+    locked_until TIMESTAMP,
+    failed_login_attempts INTEGER DEFAULT 0,
+    role TEXT DEFAULT 'user',
+    banned INTEGER DEFAULT 0,
+    banned_at TIMESTAMP,
+    banned_by TEXT,
+    ban_reason TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS api_tokens (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    publisher_id INTEGER NOT NULL REFERENCES publishers(id),
+    token_hash TEXT NOT NULL,
+    name TEXT NOT NULL,
+    last_used_at TIMESTAMP,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    revoked_at TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS tools (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    owner TEXT NOT NULL,
+    name TEXT NOT NULL,
+    version TEXT NOT NULL,
+    description TEXT,
+    category TEXT,
+    tags TEXT,
+    config_yaml TEXT NOT NULL,
+    readme TEXT,
+    publisher_id INTEGER NOT NULL REFERENCES publishers(id),
+    deprecated BOOLEAN DEFAULT FALSE,
+    deprecated_message TEXT,
+    replacement TEXT,
+    downloads INTEGER DEFAULT 0,
+    scrutiny_status TEXT DEFAULT 'pending',
+    scrutiny_report TEXT,
+    source TEXT,
+    source_url TEXT,
+    source_json TEXT,
+    visibility TEXT DEFAULT 'public',
+    moderation_status TEXT DEFAULT 'pending',
+    moderation_note TEXT,
+    moderated_by TEXT,
+    moderated_at TIMESTAMP,
+    published_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE(owner, name, version)
+);
+
+CREATE TABLE IF NOT EXISTS download_stats (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    tool_id INTEGER NOT NULL REFERENCES tools(id),
+    client_id TEXT NOT NULL,
+    downloaded_at DATE NOT NULL,
+    UNIQUE(tool_id, client_id, downloaded_at)
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS tools_fts USING fts5(
+    name, description, tags, readme,
+    content='tools',
+    content_rowid='id'
+);
+
+CREATE TRIGGER IF NOT EXISTS tools_ai AFTER INSERT ON tools BEGIN
+    INSERT INTO tools_fts(rowid, name, description, tags, readme)
+    VALUES (new.id, new.name, new.description, new.tags, new.readme);
+END;
+
+CREATE TRIGGER IF NOT EXISTS tools_ad AFTER DELETE ON tools BEGIN
+    INSERT INTO tools_fts(tools_fts, rowid, name, description, tags, readme)
+    VALUES ('delete', old.id, old.name, old.description, old.tags, old.readme);
+END;
+
+CREATE TRIGGER IF NOT EXISTS tools_au AFTER UPDATE ON tools BEGIN
+    INSERT INTO tools_fts(tools_fts, rowid, name, description, tags, readme)
+    VALUES ('delete', old.id, old.name, old.description, old.tags, old.readme);
+    INSERT INTO tools_fts(rowid, name, description, tags, readme)
+    VALUES (new.id, new.name, new.description, new.tags, new.readme);
+END;
+
+CREATE TABLE IF NOT EXISTS pending_prs (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    publisher_id INTEGER NOT NULL REFERENCES publishers(id),
+    owner TEXT NOT NULL,
+    name TEXT NOT NULL,
+    version TEXT NOT NULL,
+    pr_number INTEGER NOT NULL,
+    pr_url TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending',
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE(owner, name, version)
+);
+
+CREATE TABLE IF NOT EXISTS webhook_log (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    delivery_id TEXT UNIQUE NOT NULL,
+    event_type TEXT NOT NULL,
+    processed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS web_sessions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id TEXT UNIQUE NOT NULL,
+    publisher_id INTEGER REFERENCES publishers(id),
+    data TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    expires_at TIMESTAMP NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_tools_owner_name ON tools(owner, name);
+CREATE INDEX IF NOT EXISTS idx_tools_owner ON tools(owner);
+CREATE INDEX IF NOT EXISTS idx_tools_category ON tools(category);
+CREATE INDEX IF NOT EXISTS idx_tools_published_at ON tools(published_at DESC);
+CREATE INDEX IF NOT EXISTS idx_tools_downloads ON tools(downloads DESC);
+CREATE INDEX IF NOT EXISTS idx_tools_owner_name_version ON tools(owner, name, version);
+CREATE INDEX IF NOT EXISTS idx_tools_sort_stable ON tools(downloads DESC, published_at DESC, id DESC);
+
+CREATE INDEX IF NOT EXISTS idx_publishers_slug ON publishers(slug);
+CREATE INDEX IF NOT EXISTS idx_publishers_email ON publishers(email);
+
+CREATE INDEX IF NOT EXISTS idx_api_tokens_hash ON api_tokens(token_hash);
+CREATE INDEX IF NOT EXISTS idx_api_tokens_publisher ON api_tokens(publisher_id);
+
+CREATE INDEX IF NOT EXISTS idx_web_sessions_id ON web_sessions(session_id);
+CREATE INDEX IF NOT EXISTS idx_web_sessions_expires ON web_sessions(expires_at);
+
+-- Web UI tables (Phase 7)
+
+CREATE TABLE IF NOT EXISTS announcements (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    title TEXT NOT NULL,
+    body TEXT NOT NULL,
+    published BOOLEAN DEFAULT FALSE,
+    published_at TIMESTAMP,
+    created_by INTEGER REFERENCES publishers(id),
+    updated_by INTEGER REFERENCES publishers(id),
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS featured_tools (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    tool_id INTEGER NOT NULL REFERENCES tools(id),
+    placement TEXT NOT NULL DEFAULT 'homepage',
+    priority INTEGER DEFAULT 0,
+    start_at TIMESTAMP,
+    end_at TIMESTAMP,
+    status TEXT DEFAULT 'active',
+    created_by INTEGER REFERENCES publishers(id),
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS featured_contributors (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    publisher_id INTEGER NOT NULL REFERENCES publishers(id),
+    bio_override TEXT,
+    placement TEXT NOT NULL DEFAULT 'homepage',
+    start_at TIMESTAMP,
+    end_at TIMESTAMP,
+    status TEXT DEFAULT 'active',
+    created_by INTEGER REFERENCES publishers(id),
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS reports (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    tool_id INTEGER NOT NULL REFERENCES tools(id),
+    reporter_id INTEGER REFERENCES publishers(id),
+    reporter_ip TEXT,
+    reason TEXT NOT NULL,
+    details TEXT,
+    status TEXT DEFAULT 'pending',
+    resolved_by INTEGER REFERENCES publishers(id),
+    resolved_at TIMESTAMP,
+    resolution_note TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS audit_log (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    action TEXT NOT NULL,
+    target_type TEXT NOT NULL,
+    target_id TEXT NOT NULL,
+    actor_id TEXT NOT NULL,
+    details TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- App pairing for simplified connection flow
+CREATE TABLE IF NOT EXISTS pairing_requests (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    publisher_id INTEGER NOT NULL REFERENCES publishers(id),
+    pairing_code TEXT UNIQUE NOT NULL,
+    token_hash TEXT,
+    token_plain TEXT,
+    hostname TEXT,
+    status TEXT DEFAULT 'pending',
+    expires_at TIMESTAMP NOT NULL,
+    claimed_at TIMESTAMP,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_pairing_code ON pairing_requests(pairing_code, status);
+CREATE INDEX IF NOT EXISTS idx_pairing_publisher ON pairing_requests(publisher_id, status);
+
+CREATE TABLE IF NOT EXISTS consents (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    client_id TEXT,
+    publisher_id INTEGER REFERENCES publishers(id),
+    analytics_consent BOOLEAN DEFAULT FALSE,
+    ads_consent BOOLEAN DEFAULT FALSE,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE(client_id),
+    UNIQUE(publisher_id)
+);
+
+CREATE TABLE IF NOT EXISTS content_pages (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    slug TEXT UNIQUE NOT NULL,
+    title TEXT NOT NULL,
+    description TEXT,
+    content_type TEXT NOT NULL DEFAULT 'doc',
+    body TEXT,
+    published BOOLEAN DEFAULT FALSE,
+    published_at TIMESTAMP,
+    created_by INTEGER REFERENCES publishers(id),
+    updated_by INTEGER REFERENCES publishers(id),
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_announcements_published ON announcements(published, published_at DESC);
+CREATE INDEX IF NOT EXISTS idx_featured_tools_placement ON featured_tools(placement, status, priority DESC);
+CREATE INDEX IF NOT EXISTS idx_featured_contributors_placement ON featured_contributors(placement, status);
+CREATE INDEX IF NOT EXISTS idx_reports_status ON reports(status, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_content_pages_type ON content_pages(content_type, published);
+CREATE INDEX IF NOT EXISTS idx_audit_log_target ON audit_log(target_type, target_id);
+CREATE INDEX IF NOT EXISTS idx_audit_log_actor ON audit_log(actor_id);
+CREATE INDEX IF NOT EXISTS idx_audit_log_created ON audit_log(created_at DESC);
+-- Note: idx_tools_moderation, idx_publishers_role, idx_publishers_banned are created
+-- in migrate_db() to support upgrading existing databases without these columns
+
+CREATE TABLE IF NOT EXISTS pageviews (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    path TEXT NOT NULL,
+    referrer TEXT,
+    user_agent TEXT,
+    ip_hash TEXT,
+    viewed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_pageviews_path ON pageviews(path, viewed_at DESC);
+CREATE INDEX IF NOT EXISTS idx_pageviews_date ON pageviews(date(viewed_at), path);
+
+-- Collections (groups of tools that can be installed together)
+CREATE TABLE IF NOT EXISTS collections (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT UNIQUE NOT NULL,
+    display_name TEXT NOT NULL,
+    description TEXT,
+    icon TEXT,
+    maintainer TEXT NOT NULL,
+    tools TEXT NOT NULL,
+    pinned TEXT,
+    tags TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_collections_name ON collections(name);
+CREATE INDEX IF NOT EXISTS idx_collections_maintainer ON collections(maintainer);
+
+-- Reviews and Ratings System
+CREATE TABLE IF NOT EXISTS reviews (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    tool_id INTEGER NOT NULL REFERENCES tools(id) ON DELETE CASCADE,
+    reviewer_id INTEGER NOT NULL REFERENCES publishers(id),
+    rating INTEGER NOT NULL CHECK(rating >= 1 AND rating <= 5),
+    title TEXT,
+    content TEXT,
+    helpful_count INTEGER DEFAULT 0,
+    unhelpful_count INTEGER DEFAULT 0,
+    status TEXT DEFAULT 'published',
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE(tool_id, reviewer_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_reviews_tool ON reviews(tool_id, status);
+CREATE INDEX IF NOT EXISTS idx_reviews_reviewer ON reviews(reviewer_id);
+
+CREATE TABLE IF NOT EXISTS review_votes (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    review_id INTEGER NOT NULL REFERENCES reviews(id) ON DELETE CASCADE,
+    voter_id TEXT NOT NULL,
+    vote_type TEXT NOT NULL CHECK(vote_type IN ('helpful', 'unhelpful')),
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE(review_id, voter_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_review_votes_review ON review_votes(review_id);
+
+-- Issue Tracking (bugs, security, compatibility)
+CREATE TABLE IF NOT EXISTS tool_issues (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    tool_id INTEGER NOT NULL REFERENCES tools(id) ON DELETE CASCADE,
+    reporter_id INTEGER REFERENCES publishers(id),
+    issue_type TEXT NOT NULL CHECK(issue_type IN ('bug', 'security', 'compatibility')),
+    severity TEXT DEFAULT 'medium' CHECK(severity IN ('low', 'medium', 'high', 'critical')),
+    title TEXT NOT NULL,
+    description TEXT,
+    status TEXT DEFAULT 'open' CHECK(status IN ('open', 'confirmed', 'fixed', 'wontfix', 'duplicate')),
+    resolved_by INTEGER REFERENCES publishers(id),
+    resolved_at TIMESTAMP,
+    resolution_note TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_issues_tool ON tool_issues(tool_id, status);
+CREATE INDEX IF NOT EXISTS idx_issues_type ON tool_issues(issue_type, severity);
+
+-- Tool Stats Cache (for fast queries)
+CREATE TABLE IF NOT EXISTS tool_stats (
+    tool_id INTEGER PRIMARY KEY REFERENCES tools(id) ON DELETE CASCADE,
+    average_rating REAL DEFAULT 0,
+    rating_count INTEGER DEFAULT 0,
+    rating_1 INTEGER DEFAULT 0,
+    rating_2 INTEGER DEFAULT 0,
+    rating_3 INTEGER DEFAULT 0,
+    rating_4 INTEGER DEFAULT 0,
+    rating_5 INTEGER DEFAULT 0,
+    unique_users INTEGER DEFAULT 0,
+    open_issues INTEGER DEFAULT 0,
+    security_issues INTEGER DEFAULT 0,
+    last_updated TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Publisher Stats Cache (for fast queries)
+CREATE TABLE IF NOT EXISTS publisher_stats (
+    publisher_id INTEGER PRIMARY KEY REFERENCES publishers(id) ON DELETE CASCADE,
+    tool_count INTEGER DEFAULT 0,
+    total_downloads INTEGER DEFAULT 0,
+    average_rating REAL DEFAULT 0,
+    total_reviews INTEGER DEFAULT 0,
+    trust_score REAL DEFAULT 0,
+    badges TEXT,
+    last_updated TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Tool Usage Tracking (unique users)
+CREATE TABLE IF NOT EXISTS tool_usage (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    tool_id INTEGER NOT NULL REFERENCES tools(id) ON DELETE CASCADE,
+    user_hash TEXT NOT NULL,
+    first_used_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    last_used_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    use_count INTEGER DEFAULT 1,
+    UNIQUE(tool_id, user_hash)
+);
+
+CREATE INDEX IF NOT EXISTS idx_usage_tool ON tool_usage(tool_id);
+
+-- Admin Configuration Settings
+CREATE TABLE IF NOT EXISTS registry_settings (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    value_type TEXT DEFAULT 'string',
+    description TEXT,
+    category TEXT DEFAULT 'general',
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_by TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_settings_category ON registry_settings(category);
+"""
+
+
+def get_db_path() -> Path:
+    default_path = Path.home() / ".cmdforge" / "registry" / "registry.db"
+    return Path(os.environ.get("CMDFORGE_REGISTRY_DB", default_path))
+
+
+def ensure_db_directory(path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+
+def connect_db(path: Path | None = None) -> sqlite3.Connection:
+    db_path = path or get_db_path()
+    ensure_db_directory(db_path)
+    conn = sqlite3.connect(db_path)
+    conn.row_factory = sqlite3.Row
+    # WAL mode provides better concurrency but may not work on all filesystems
+    # (e.g., some FUSE filesystems like mergerfs). Fall back gracefully.
+    try:
+        conn.execute("PRAGMA journal_mode=WAL;")
+    except sqlite3.OperationalError:
+        # Fall back to DELETE journal mode which works everywhere
+        conn.execute("PRAGMA journal_mode=DELETE;")
+    conn.execute("PRAGMA foreign_keys=ON;")
+    return conn
+
+
+def init_db(conn: sqlite3.Connection) -> None:
+    conn.executescript(SCHEMA_SQL)
+    conn.commit()
+    # Run migrations for existing databases
+    migrate_db(conn)
+
+
+def migrate_db(conn: sqlite3.Connection) -> None:
+    """Add missing columns to existing tables (for schema updates)."""
+    # Get existing columns in tools table
+    cursor = conn.execute("PRAGMA table_info(tools)")
+    tools_cols = {row[1] for row in cursor.fetchall()}
+
+    # Get existing columns in publishers table
+    cursor = conn.execute("PRAGMA table_info(publishers)")
+    publishers_cols = {row[1] for row in cursor.fetchall()}
+
+    # Tools table migrations (column_name, type, default)
+    tools_migrations = [
+        ("scrutiny_status", "TEXT", "'pending'"),
+        ("scrutiny_report", "TEXT", "NULL"),
+        ("source", "TEXT", "NULL"),
+        ("source_url", "TEXT", "NULL"),
+        ("source_json", "TEXT", "NULL"),
+        ("visibility", "TEXT", "'public'"),
+        ("moderation_status", "TEXT", "'pending'"),
+        ("moderation_note", "TEXT", "NULL"),
+        ("moderated_by", "TEXT", "NULL"),
+        ("moderated_at", "TIMESTAMP", "NULL"),
+    ]
+
+    for col_name, col_type, default in tools_migrations:
+        if col_name not in tools_cols:
+            try:
+                conn.execute(f"ALTER TABLE tools ADD COLUMN {col_name} {col_type} DEFAULT {default}")
+                conn.commit()
+            except sqlite3.OperationalError:
+                pass  # Column might already exist or other issue
+
+    # Publishers table migrations
+    publishers_migrations = [
+        ("role", "TEXT", "'user'"),
+        ("banned", "INTEGER", "0"),
+        ("banned_at", "TIMESTAMP", "NULL"),
+        ("banned_by", "TEXT", "NULL"),
+        ("ban_reason", "TEXT", "NULL"),
+    ]
+
+    for col_name, col_type, default in publishers_migrations:
+        if col_name not in publishers_cols:
+            try:
+                conn.execute(f"ALTER TABLE publishers ADD COLUMN {col_name} {col_type} DEFAULT {default}")
+                conn.commit()
+            except sqlite3.OperationalError:
+                pass
+
+    # API tokens table migrations (for Connected Apps feature)
+    cursor = conn.execute("PRAGMA table_info(api_tokens)")
+    tokens_cols = {row[1] for row in cursor.fetchall()}
+
+    tokens_migrations = [
+        ("hostname", "TEXT", "NULL"),
+    ]
+
+    for col_name, col_type, default in tokens_migrations:
+        if col_name not in tokens_cols:
+            try:
+                conn.execute(f"ALTER TABLE api_tokens ADD COLUMN {col_name} {col_type} DEFAULT {default}")
+                conn.commit()
+            except sqlite3.OperationalError:
+                pass
+
+    # Grandfather existing tools: set moderation_status to 'approved' for tools that have NULL
+    # This ensures existing tools remain visible after migration
+    try:
+        conn.execute("""
+            UPDATE tools
+            SET moderation_status = 'approved'
+            WHERE moderation_status IS NULL OR moderation_status = 'pending'
+        """)
+        conn.commit()
+    except sqlite3.OperationalError:
+        pass
+
+    # Ensure indexes exist
+    try:
+        conn.execute("CREATE INDEX IF NOT EXISTS idx_tools_owner ON tools(owner)")
+        conn.execute("CREATE INDEX IF NOT EXISTS idx_tools_moderation ON tools(moderation_status, visibility)")
+        conn.execute("CREATE INDEX IF NOT EXISTS idx_publishers_role ON publishers(role)")
+        conn.execute("CREATE INDEX IF NOT EXISTS idx_publishers_banned ON publishers(banned)")
+        conn.execute("CREATE INDEX IF NOT EXISTS idx_audit_log_target ON audit_log(target_type, target_id)")
+        conn.execute("CREATE INDEX IF NOT EXISTS idx_audit_log_actor ON audit_log(actor_id)")
+        conn.execute("CREATE INDEX IF NOT EXISTS idx_audit_log_created ON audit_log(created_at DESC)")
+        conn.commit()
+    except sqlite3.OperationalError:
+        pass
+
+
+def query_one(conn: sqlite3.Connection, sql: str, params: Iterable | None = None):
+    cur = conn.execute(sql, params or [])
+    return cur.fetchone()
+
+
+def query_all(conn: sqlite3.Connection, sql: str, params: Iterable | None = None):
+    cur = conn.execute(sql, params or [])
+    return cur.fetchall()
+
+
+def execute(conn: sqlite3.Connection, sql: str, params: Iterable | None = None) -> None:
+    conn.execute(sql, params or [])
+    conn.commit()

src/cmdforge/registry/scrutiny.py

@@ -0,0 +1,588 @@
+"""Tool scrutiny system for automated review of published tools.
+
+This module analyzes tools on publish to verify:
+1. Honesty - Does the tool do what its description claims?
+2. Transparency - Is behavior visible or hidden/obfuscated?
+3. Scope - Does the code stay within expected bounds?
+4. Efficiency - Are AI calls necessary or wasteful?
+"""
+
+from __future__ import annotations
+
+import base64
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional, Tuple
+
+import yaml
+
+
+class CheckResult(Enum):
+    PASS = "pass"
+    WARNING = "warning"
+    FAIL = "fail"
+
+
+@dataclass
+class Finding:
+    """A single finding from scrutiny analysis."""
+    check: str
+    result: CheckResult
+    message: str
+    suggestion: Optional[str] = None
+    location: Optional[str] = None  # e.g., "step 2", "code block"
+
+
+@dataclass
+class ScrutinyReport:
+    """Complete scrutiny report for a tool."""
+    tool_name: str
+    findings: List[Finding] = field(default_factory=list)
+    optimizations: List[Any] = field(default_factory=list)  # OptimizationSuggestion list
+
+    @property
+    def passed(self) -> bool:
+        """Tool passes if no FAIL results."""
+        return not any(f.result == CheckResult.FAIL for f in self.findings)
+
+    @property
+    def has_warnings(self) -> bool:
+        return any(f.result == CheckResult.WARNING for f in self.findings)
+
+    @property
+    def decision(self) -> str:
+        """Auto-approve, flag for review, or reject."""
+        if any(f.result == CheckResult.FAIL for f in self.findings):
+            return "reject"
+        if any(f.result == CheckResult.WARNING for f in self.findings):
+            return "review"
+        return "approve"
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = {
+            "tool_name": self.tool_name,
+            "decision": self.decision,
+            "passed": self.passed,
+            "has_warnings": self.has_warnings,
+            "findings": [
+                {
+                    "check": f.check,
+                    "result": f.result.value,
+                    "message": f.message,
+                    "suggestion": f.suggestion,
+                    "location": f.location,
+                }
+                for f in self.findings
+            ],
+        }
+
+        # Add optimization suggestions if any
+        if self.optimizations:
+            result["optimizations"] = [
+                {
+                    "operation": opt.operation,
+                    "current_prompt": opt.current_prompt,
+                    "optimized_code": opt.optimized_code,
+                    "tradeoffs": opt.tradeoffs,
+                    "location": opt.location,
+                    "action": "optional",
+                }
+                for opt in self.optimizations
+            ]
+
+        return result
+
+
+# Keywords that indicate specific behaviors
+BEHAVIOR_KEYWORDS = {
+    "summarize": ["summary", "summarize", "condense", "brief", "shorten", "tldr"],
+    "translate": ["translate", "translation", "language", "convert to"],
+    "explain": ["explain", "clarify", "describe", "what is", "how does"],
+    "fix": ["fix", "correct", "repair", "grammar", "spelling"],
+    "generate": ["generate", "create", "write", "produce", "make"],
+    "extract": ["extract", "pull", "find", "identify", "parse"],
+    "analyze": ["analyze", "review", "examine", "check", "audit"],
+    "convert": ["convert", "transform", "format", "change to"],
+}
+
+# Patterns that suggest obfuscation or suspicious behavior
+SUSPICIOUS_PATTERNS = [
+    (r'base64\.(b64decode|decodebytes)', "Base64 decoding detected"),
+    (r'exec\s*\(', "Dynamic code execution with exec()"),
+    (r'eval\s*\(', "Dynamic code execution with eval()"),
+    (r'__import__\s*\(', "Dynamic import detected"),
+    (r'subprocess\.(run|call|Popen)', "Subprocess execution detected"),
+    (r'os\.(system|popen|exec)', "OS command execution detected"),
+    (r'requests\.(get|post|put|delete)', "Network request detected"),
+    (r'urllib', "URL library usage detected"),
+    (r'socket\.', "Raw socket usage detected"),
+    (r'\\x[0-9a-fA-F]{2}', "Hex-encoded strings detected"),
+]
+
+# File/system access patterns
+SCOPE_PATTERNS = [
+    (r'open\s*\([^)]*["\']/', "Absolute path file access"),
+    (r'open\s*\([^)]*~', "Home directory file access"),
+    (r'\.ssh', "SSH directory access"),
+    (r'\.aws', "AWS credentials access"),
+    (r'\.env', "Environment file access"),
+    (r'/etc/', "System config access"),
+    (r'os\.environ', "Environment variable access"),
+    (r'keyring|password|credential', "Credential-related access"),
+]
+
+# Operations that could be done with code (with tradeoffs)
+# Format: (prompt_pattern, operation_name, code_template, code_benefit, ai_benefit)
+CODE_OPTIMIZATIONS = [
+    (
+        r'count (the |how many )?words',
+        "Word counting",
+        'word_count = len(input.split())',
+        "Faster, no API cost, deterministic",
+        "Handles edge cases (hyphenated words, contractions, numbers as words)",
+    ),
+    (
+        r'count (the |how many )?(lines|line)',
+        "Line counting",
+        'line_count = len(input.strip().split("\\n"))',
+        "Instant, no API cost",
+        "Could interpret 'meaningful lines' vs blank lines",
+    ),
+    (
+        r'count (the |how many )?(characters?|chars?)',
+        "Character counting",
+        'char_count = len(input)',
+        "Instant, no API cost",
+        "Could exclude whitespace or count 'visible' characters",
+    ),
+    (
+        r'convert.*(to|into) json',
+        "JSON conversion",
+        'import json\nresult = json.dumps(data, indent=2)',
+        "Reliable, no API cost, handles valid input perfectly",
+        "Can interpret messy/partial data and fix formatting issues",
+    ),
+    (
+        r'parse.*(json|the json)',
+        "JSON parsing",
+        'import json\nresult = json.loads(input)',
+        "Fast, no API cost, strict validation",
+        "Can fix malformed JSON, handle comments, trailing commas",
+    ),
+    (
+        r'convert.*(to|into) csv',
+        "CSV conversion",
+        'import csv\nimport io\n# ... csv.writer conversion',
+        "Reliable for structured data",
+        "Can infer structure from unstructured text",
+    ),
+    (
+        r'(extract|find|get) (all )?(emails?|email addresses)',
+        "Email extraction",
+        'import re\nemails = re.findall(r"[\\w.+-]+@[\\w.-]+\\.[a-zA-Z]{2,}", input)',
+        "Fast, consistent pattern matching",
+        "Handles obfuscated emails (user [at] domain), context-aware",
+    ),
+    (
+        r'(extract|find|get) (all )?(urls?|links?)',
+        "URL extraction",
+        'import re\nurls = re.findall(r"https?://[^\\s<>\"]+", input)',
+        "Fast, consistent pattern matching",
+        "Handles partial URLs, context-aware link detection",
+    ),
+    (
+        r'(uppercase|to upper|make upper)',
+        "Uppercase conversion",
+        'result = input.upper()',
+        "Instant, no API cost",
+        "Language-aware (Turkish İ/i, Greek σ/ς edge cases)",
+    ),
+    (
+        r'(lowercase|to lower|make lower)',
+        "Lowercase conversion",
+        'result = input.lower()',
+        "Instant, no API cost",
+        "Language-aware case handling",
+    ),
+    (
+        r'(capitalize|title case)',
+        "Title case conversion",
+        'result = input.title()',
+        "Instant, no API cost",
+        "Knows style rules (articles, prepositions)",
+    ),
+    (
+        r'(reverse|reversed?) (the |this )?(text|string|order)',
+        "Text reversal",
+        'result = input[::-1]',
+        "Instant, no API cost",
+        "Could reverse by word, sentence, or paragraph intelligently",
+    ),
+    (
+        r'(sort|sorted?) (the |these |this )?(lines?|items?|list)',
+        "Sorting",
+        'result = "\\n".join(sorted(input.strip().split("\\n")))',
+        "Fast, deterministic alphabetical sort",
+        "Can sort by meaning ('sort by importance', 'by date mentioned')",
+    ),
+    (
+        r'remove (duplicate|duplicated?) (lines?|items?)',
+        "Deduplication",
+        'seen = set()\nresult = "\\n".join(x for x in input.split("\\n") if not (x in seen or seen.add(x)))',
+        "Fast, exact matching",
+        "Can detect semantic duplicates ('USA' vs 'United States')",
+    ),
+    (
+        r'(remove|strip|trim) (whitespace|spaces|blank)',
+        "Whitespace removal",
+        'result = " ".join(input.split())',
+        "Instant, predictable",
+        "Could preserve meaningful spacing, format-aware",
+    ),
+    (
+        r'split (by|on|into)',
+        "Text splitting",
+        '# result = input.split(delimiter)',
+        "Fast, exact delimiter matching",
+        "Can split by meaning ('split into paragraphs about each topic')",
+    ),
+]
+
+
+def analyze_tool(config_yaml: str, description: str) -> ScrutinyReport:
+    """Run full scrutiny analysis on a tool.
+
+    Args:
+        config_yaml: The tool's YAML configuration
+        description: The tool's description
+
+    Returns:
+        ScrutinyReport with all findings
+    """
+    try:
+        config = yaml.safe_load(config_yaml) or {}
+    except yaml.YAMLError:
+        return ScrutinyReport(
+            tool_name="unknown",
+            findings=[Finding(
+                check="parse",
+                result=CheckResult.FAIL,
+                message="Invalid YAML configuration",
+            )]
+        )
+
+    tool_name = config.get("name", "unknown")
+    report = ScrutinyReport(tool_name=tool_name)
+
+    # Run all checks
+    report.findings.extend(check_honesty(config, description))
+    report.findings.extend(check_transparency(config))
+    report.findings.extend(check_scope(config))
+
+    # Efficiency check returns findings and optimizations
+    efficiency_findings, optimizations = check_efficiency(config)
+    report.findings.extend(efficiency_findings)
+    report.optimizations = optimizations
+
+    # If no findings, add a pass
+    if not report.findings:
+        report.findings.append(Finding(
+            check="overall",
+            result=CheckResult.PASS,
+            message="All checks passed",
+        ))
+
+    return report
+
+
+def check_honesty(config: Dict[str, Any], description: str) -> List[Finding]:
+    """Check if tool behavior matches its description.
+
+    Analyzes prompts and compares against description claims.
+    """
+    findings = []
+    steps = config.get("steps", [])
+    description_lower = description.lower()
+
+    # Extract all prompt text
+    all_prompts = ""
+    for step in steps:
+        if step.get("type") == "prompt":
+            all_prompts += " " + (step.get("prompt") or "").lower()
+
+    # Detect what the description claims
+    claimed_behaviors = set()
+    for behavior, keywords in BEHAVIOR_KEYWORDS.items():
+        if any(kw in description_lower for kw in keywords):
+            claimed_behaviors.add(behavior)
+
+    # Detect what prompts actually do
+    actual_behaviors = set()
+    for behavior, keywords in BEHAVIOR_KEYWORDS.items():
+        if any(kw in all_prompts for kw in keywords):
+            actual_behaviors.add(behavior)
+
+    # Check for mismatches
+    claimed_not_done = claimed_behaviors - actual_behaviors
+    done_not_claimed = actual_behaviors - claimed_behaviors
+
+    if claimed_not_done:
+        findings.append(Finding(
+            check="honesty",
+            result=CheckResult.WARNING,
+            message=f"Description claims '{', '.join(claimed_not_done)}' but prompts don't reflect this",
+            suggestion="Update description to accurately reflect tool behavior",
+        ))
+
+    if done_not_claimed and claimed_behaviors:
+        # Only warn if tool claims to do something specific but also does other things
+        findings.append(Finding(
+            check="honesty",
+            result=CheckResult.WARNING,
+            message=f"Prompts include '{', '.join(done_not_claimed)}' not mentioned in description",
+            suggestion="Update description to include all tool capabilities",
+        ))
+
+    # Check for empty or minimal prompts
+    for i, step in enumerate(steps):
+        if step.get("type") == "prompt":
+            prompt = step.get("prompt", "").strip()
+            if len(prompt) < 10:
+                findings.append(Finding(
+                    check="honesty",
+                    result=CheckResult.WARNING,
+                    message="Prompt is unusually short",
+                    location=f"step {i + 1}",
+                ))
+
+    if not findings:
+        findings.append(Finding(
+            check="honesty",
+            result=CheckResult.PASS,
+            message="Description matches observed behavior",
+        ))
+
+    return findings
+
+
+def check_transparency(config: Dict[str, Any]) -> List[Finding]:
+    """Check for obfuscated or hidden behavior.
+
+    Looks for encoded strings, dynamic execution, etc.
+    """
+    findings = []
+    steps = config.get("steps", [])
+
+    for i, step in enumerate(steps):
+        if step.get("type") == "code":
+            code = step.get("code", "")
+            location = f"step {i + 1}"
+
+            # Check for suspicious patterns
+            for pattern, description in SUSPICIOUS_PATTERNS:
+                if re.search(pattern, code, re.IGNORECASE):
+                    # Determine severity
+                    if "exec" in pattern or "eval" in pattern:
+                        result = CheckResult.FAIL
+                        msg = f"{description} - potential code injection risk"
+                    elif "socket" in pattern or "subprocess" in pattern:
+                        result = CheckResult.WARNING
+                        msg = f"{description} - flagged for manual review"
+                    else:
+                        result = CheckResult.WARNING
+                        msg = description
+
+                    findings.append(Finding(
+                        check="transparency",
+                        result=result,
+                        message=msg,
+                        location=location,
+                    ))
+
+            # Check for obfuscated variable names
+            obfuscated = re.findall(r'\b([a-z])\1{2,}\b|\b[a-z]{1,2}\d+\b', code)
+            if len(obfuscated) > 3:
+                findings.append(Finding(
+                    check="transparency",
+                    result=CheckResult.WARNING,
+                    message="Multiple obfuscated variable names detected",
+                    location=location,
+                    suggestion="Use descriptive variable names",
+                ))
+
+            # Check for very long single lines (possible obfuscation)
+            for line_num, line in enumerate(code.split('\n'), 1):
+                if len(line) > 500:
+                    findings.append(Finding(
+                        check="transparency",
+                        result=CheckResult.WARNING,
+                        message=f"Unusually long code line ({len(line)} chars)",
+                        location=f"{location}, line {line_num}",
+                    ))
+
+    if not findings:
+        findings.append(Finding(
+            check="transparency",
+            result=CheckResult.PASS,
+            message="No obfuscation detected",
+        ))
+
+    return findings
+
+
+def check_scope(config: Dict[str, Any]) -> List[Finding]:
+    """Check if code accesses unexpected resources.
+
+    Flags file system, network, or credential access.
+    """
+    findings = []
+    steps = config.get("steps", [])
+    tool_name = config.get("name", "").lower()
+    description = config.get("description", "").lower()
+
+    for i, step in enumerate(steps):
+        if step.get("type") == "code":
+            code = step.get("code", "")
+            location = f"step {i + 1}"
+
+            for pattern, description_text in SCOPE_PATTERNS:
+                if re.search(pattern, code, re.IGNORECASE):
+                    # Check if this access seems expected based on tool name/description
+                    is_expected = False
+                    if "ssh" in pattern and ("ssh" in tool_name or "ssh" in description):
+                        is_expected = True
+                    if "env" in pattern and ("env" in tool_name or "environment" in description):
+                        is_expected = True
+                    if "file" in description_text.lower() and ("file" in tool_name or "file" in description):
+                        is_expected = True
+
+                    if not is_expected:
+                        # Credential access is always flagged
+                        if "credential" in pattern or ".ssh" in pattern or ".aws" in pattern:
+                            result = CheckResult.FAIL
+                            suggestion = "Remove credential access or justify in description"
+                        else:
+                            result = CheckResult.WARNING
+                            suggestion = "Document this access in tool description"
+
+                        findings.append(Finding(
+                            check="scope",
+                            result=result,
+                            message=description_text,
+                            location=location,
+                            suggestion=suggestion,
+                        ))
+
+    if not findings:
+        findings.append(Finding(
+            check="scope",
+            result=CheckResult.PASS,
+            message="No unexpected resource access",
+        ))
+
+    return findings
+
+
+@dataclass
+class OptimizationSuggestion:
+    """A code optimization suggestion for an AI prompt."""
+    operation: str
+    current_prompt: str
+    optimized_code: str
+    tradeoffs: Dict[str, str]
+    location: str
+
+
+def check_efficiency(config: Dict[str, Any]) -> List[Finding]:
+    """Check for AI calls that could optionally be pure code.
+
+    Generates optimization suggestions with tradeoffs - these are
+    informational, not penalties. Authors can choose to keep AI
+    for valid reasons.
+    """
+    findings = []
+    steps = config.get("steps", [])
+    optimizations = []
+
+    for i, step in enumerate(steps):
+        if step.get("type") == "prompt":
+            prompt = step.get("prompt", "")
+            prompt_lower = prompt.lower()
+            location = f"step {i + 1}"
+
+            # Check against known optimizable patterns
+            for pattern, operation, code, code_benefit, ai_benefit in CODE_OPTIMIZATIONS:
+                if re.search(pattern, prompt_lower):
+                    optimizations.append(OptimizationSuggestion(
+                        operation=operation,
+                        current_prompt=prompt.strip()[:200],  # Truncate for display
+                        optimized_code=code,
+                        tradeoffs={
+                            "code": code_benefit,
+                            "ai": ai_benefit,
+                        },
+                        location=location,
+                    ))
+                    break  # One suggestion per step
+
+    # Add optimization suggestions as findings (not warnings - optional)
+    for opt in optimizations:
+        findings.append(Finding(
+            check="efficiency",
+            result=CheckResult.PASS,  # Not a warning - it's a suggestion
+            message=f"Optional optimization: {opt.operation} could use code",
+            location=opt.location,
+            suggestion=f"Code: {opt.optimized_code}",
+        ))
+
+    # Check for all-AI tools (informational, not a warning)
+    code_steps = [s for s in steps if s.get("type") == "code"]
+    prompt_steps = [s for s in steps if s.get("type") == "prompt"]
+
+    if prompt_steps and not code_steps and len(prompt_steps) > 3:
+        findings.append(Finding(
+            check="efficiency",
+            result=CheckResult.PASS,  # Informational
+            message=f"Tool has {len(prompt_steps)} AI steps - consider if any could be code",
+            suggestion="Mixing AI and code steps can reduce API costs",
+        ))
+
+    if not findings:
+        findings.append(Finding(
+            check="efficiency",
+            result=CheckResult.PASS,
+            message="AI usage appears appropriate",
+        ))
+
+    return findings, optimizations
+
+
+def get_optimization_details(optimizations: List[OptimizationSuggestion]) -> List[Dict[str, Any]]:
+    """Convert optimization suggestions to serializable format."""
+    return [
+        {
+            "operation": opt.operation,
+            "current_prompt": opt.current_prompt,
+            "optimized_code": opt.optimized_code,
+            "tradeoffs": opt.tradeoffs,
+            "location": opt.location,
+            "action": "optional",  # Author chooses
+        }
+        for opt in optimizations
+    ]
+
+
+def scrutinize_tool(config_yaml: str, description: str, readme: Optional[str] = None) -> Dict[str, Any]:
+    """Main entry point for tool scrutiny.
+
+    Args:
+        config_yaml: The tool's YAML configuration
+        description: The tool's description
+        readme: Optional README content (for additional context)
+
+    Returns:
+        Dictionary with scrutiny results
+    """
+    report = analyze_tool(config_yaml, description)
+    return report.to_dict()

src/cmdforge/registry/settings.py

@@ -0,0 +1,399 @@
+"""Registry settings management.
+
+Provides configurable settings for vetting, moderation, and sync.
+Settings are stored in the database and can be modified via admin API.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from .db import query_one, query_all
+
+
+@dataclass
+class Setting:
+    """A single configuration setting."""
+    key: str
+    value: Any
+    value_type: str  # string, int, float, bool, json
+    description: str
+    category: str
+    updated_at: Optional[str] = None
+    updated_by: Optional[str] = None
+
+
+# Default settings with descriptions
+DEFAULT_SETTINGS: List[Setting] = [
+    # Vetting thresholds
+    Setting(
+        key="vetting.approve_threshold",
+        value=0.8,
+        value_type="float",
+        description="Quality score threshold for auto-approval (0.0-1.0)",
+        category="vetting",
+    ),
+    Setting(
+        key="vetting.reject_threshold",
+        value=0.3,
+        value_type="float",
+        description="Quality score threshold for auto-rejection (0.0-1.0)",
+        category="vetting",
+    ),
+
+    # Vetting weights
+    Setting(
+        key="vetting.weight.honesty",
+        value=0.25,
+        value_type="float",
+        description="Weight for honesty check (description matches behavior)",
+        category="vetting",
+    ),
+    Setting(
+        key="vetting.weight.transparency",
+        value=0.20,
+        value_type="float",
+        description="Weight for transparency check (no obfuscation)",
+        category="vetting",
+    ),
+    Setting(
+        key="vetting.weight.scope",
+        value=0.15,
+        value_type="float",
+        description="Weight for scope check (appropriate boundaries)",
+        category="vetting",
+    ),
+    Setting(
+        key="vetting.weight.efficiency",
+        value=0.15,
+        value_type="float",
+        description="Weight for efficiency check (prompt quality)",
+        category="vetting",
+    ),
+    Setting(
+        key="vetting.weight.safety",
+        value=0.25,
+        value_type="float",
+        description="Weight for safety check (no dangerous patterns)",
+        category="vetting",
+    ),
+
+    # Similarity detection
+    Setting(
+        key="similarity.duplicate_threshold",
+        value=0.9,
+        value_type="float",
+        description="Similarity score to consider tools as duplicates (0.0-1.0)",
+        category="similarity",
+    ),
+    Setting(
+        key="similarity.similar_threshold",
+        value=0.7,
+        value_type="float",
+        description="Similarity score to flag tools as similar (0.0-1.0)",
+        category="similarity",
+    ),
+    Setting(
+        key="similarity.related_threshold",
+        value=0.5,
+        value_type="float",
+        description="Similarity score to flag tools as related (0.0-1.0)",
+        category="similarity",
+    ),
+
+    # Fabric sync
+    Setting(
+        key="sync.enabled",
+        value=False,
+        value_type="bool",
+        description="Enable scheduled Fabric pattern sync",
+        category="sync",
+    ),
+    Setting(
+        key="sync.interval_hours",
+        value=24,
+        value_type="int",
+        description="Hours between Fabric sync runs",
+        category="sync",
+    ),
+    Setting(
+        key="sync.auto_approve",
+        value=False,
+        value_type="bool",
+        description="Auto-approve synced Fabric patterns (skip moderation)",
+        category="sync",
+    ),
+    Setting(
+        key="sync.default_provider",
+        value="claude",
+        value_type="string",
+        description="Default AI provider for synced patterns",
+        category="sync",
+    ),
+
+    # Moderation
+    Setting(
+        key="moderation.require_review",
+        value=True,
+        value_type="bool",
+        description="Require manual review for public tools",
+        category="moderation",
+    ),
+    Setting(
+        key="moderation.auto_approve_private",
+        value=True,
+        value_type="bool",
+        description="Auto-approve private/unlisted tools",
+        category="moderation",
+    ),
+    Setting(
+        key="moderation.max_pending_per_user",
+        value=10,
+        value_type="int",
+        description="Maximum pending tools per user before rate limiting",
+        category="moderation",
+    ),
+
+    # Rate limits (can override defaults)
+    Setting(
+        key="rate_limit.publish.limit",
+        value=20,
+        value_type="int",
+        description="Max publish requests per window",
+        category="rate_limits",
+    ),
+    Setting(
+        key="rate_limit.publish.window",
+        value=3600,
+        value_type="int",
+        description="Publish rate limit window in seconds",
+        category="rate_limits",
+    ),
+]
+
+
+def _convert_value(value: str, value_type: str) -> Any:
+    """Convert stored string value to appropriate type."""
+    if value_type == "int":
+        return int(value)
+    elif value_type == "float":
+        return float(value)
+    elif value_type == "bool":
+        return value.lower() in ("true", "1", "yes")
+    elif value_type == "json":
+        return json.loads(value)
+    return value
+
+
+def _serialize_value(value: Any, value_type: str) -> str:
+    """Serialize value for storage."""
+    if value_type == "bool":
+        return "true" if value else "false"
+    elif value_type == "json":
+        return json.dumps(value)
+    return str(value)
+
+
+def get_setting(conn: sqlite3.Connection, key: str) -> Optional[Any]:
+    """Get a single setting value.
+
+    Returns the default if not set in database.
+    """
+    row = query_one(
+        conn,
+        "SELECT value, value_type FROM registry_settings WHERE key = ?",
+        [key],
+    )
+
+    if row:
+        return _convert_value(row["value"], row["value_type"])
+
+    # Return default if exists
+    for setting in DEFAULT_SETTINGS:
+        if setting.key == key:
+            return setting.value
+
+    return None
+
+
+def get_settings_by_category(conn: sqlite3.Connection, category: str) -> Dict[str, Any]:
+    """Get all settings for a category as a dict."""
+    result = {}
+
+    # Start with defaults
+    for setting in DEFAULT_SETTINGS:
+        if setting.category == category:
+            result[setting.key] = setting.value
+
+    # Override with DB values
+    rows = query_all(
+        conn,
+        "SELECT key, value, value_type FROM registry_settings WHERE category = ?",
+        [category],
+    )
+    for row in rows:
+        result[row["key"]] = _convert_value(row["value"], row["value_type"])
+
+    return result
+
+
+def get_all_settings(conn: sqlite3.Connection) -> List[Dict[str, Any]]:
+    """Get all settings with their current values and metadata."""
+    result = []
+
+    # Get all DB settings
+    db_settings = {}
+    rows = query_all(conn, "SELECT * FROM registry_settings")
+    for row in rows:
+        db_settings[row["key"]] = dict(row)
+
+    # Build combined list
+    for default in DEFAULT_SETTINGS:
+        if default.key in db_settings:
+            row = db_settings[default.key]
+            result.append({
+                "key": default.key,
+                "value": _convert_value(row["value"], row["value_type"]),
+                "value_type": row["value_type"],
+                "description": default.description,
+                "category": default.category,
+                "updated_at": row["updated_at"],
+                "updated_by": row["updated_by"],
+                "is_default": False,
+            })
+        else:
+            result.append({
+                "key": default.key,
+                "value": default.value,
+                "value_type": default.value_type,
+                "description": default.description,
+                "category": default.category,
+                "updated_at": None,
+                "updated_by": None,
+                "is_default": True,
+            })
+
+    return result
+
+
+def set_setting(
+    conn: sqlite3.Connection,
+    key: str,
+    value: Any,
+    updated_by: Optional[str] = None,
+) -> bool:
+    """Set a setting value.
+
+    Returns True if successful, False if key is not a valid setting.
+    """
+    # Find the setting definition
+    setting_def = None
+    for s in DEFAULT_SETTINGS:
+        if s.key == key:
+            setting_def = s
+            break
+
+    if not setting_def:
+        return False
+
+    # Validate and convert value
+    try:
+        if setting_def.value_type == "int":
+            value = int(value)
+        elif setting_def.value_type == "float":
+            value = float(value)
+            # Validate range for thresholds
+            if "threshold" in key or "weight" in key:
+                if not 0.0 <= value <= 1.0:
+                    return False
+        elif setting_def.value_type == "bool":
+            if isinstance(value, str):
+                value = value.lower() in ("true", "1", "yes")
+            else:
+                value = bool(value)
+    except (ValueError, TypeError):
+        return False
+
+    serialized = _serialize_value(value, setting_def.value_type)
+    now = datetime.now(timezone.utc).isoformat()
+
+    conn.execute(
+        """
+        INSERT INTO registry_settings (key, value, value_type, description, category, updated_at, updated_by)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(key) DO UPDATE SET
+            value = excluded.value,
+            updated_at = excluded.updated_at,
+            updated_by = excluded.updated_by
+        """,
+        [key, serialized, setting_def.value_type, setting_def.description,
+         setting_def.category, now, updated_by],
+    )
+    conn.commit()
+    return True
+
+
+def reset_setting(conn: sqlite3.Connection, key: str) -> bool:
+    """Reset a setting to its default value (remove from DB)."""
+    conn.execute("DELETE FROM registry_settings WHERE key = ?", [key])
+    conn.commit()
+    return True
+
+
+def reset_all_settings(conn: sqlite3.Connection) -> int:
+    """Reset all settings to defaults. Returns count of reset settings."""
+    cursor = conn.execute("SELECT COUNT(*) FROM registry_settings")
+    count = cursor.fetchone()[0]
+    conn.execute("DELETE FROM registry_settings")
+    conn.commit()
+    return count
+
+
+def get_vetting_config(conn: sqlite3.Connection) -> Dict[str, Any]:
+    """Get vetting configuration as a structured dict.
+
+    This is the main entry point for the scrutiny system to get config.
+    """
+    return {
+        "approve_threshold": get_setting(conn, "vetting.approve_threshold"),
+        "reject_threshold": get_setting(conn, "vetting.reject_threshold"),
+        "weights": {
+            "honesty": get_setting(conn, "vetting.weight.honesty"),
+            "transparency": get_setting(conn, "vetting.weight.transparency"),
+            "scope": get_setting(conn, "vetting.weight.scope"),
+            "efficiency": get_setting(conn, "vetting.weight.efficiency"),
+            "safety": get_setting(conn, "vetting.weight.safety"),
+        },
+    }
+
+
+def get_similarity_config(conn: sqlite3.Connection) -> Dict[str, float]:
+    """Get similarity detection configuration."""
+    return {
+        "duplicate_threshold": get_setting(conn, "similarity.duplicate_threshold"),
+        "similar_threshold": get_setting(conn, "similarity.similar_threshold"),
+        "related_threshold": get_setting(conn, "similarity.related_threshold"),
+    }
+
+
+def get_sync_config(conn: sqlite3.Connection) -> Dict[str, Any]:
+    """Get Fabric sync configuration."""
+    return {
+        "enabled": get_setting(conn, "sync.enabled"),
+        "interval_hours": get_setting(conn, "sync.interval_hours"),
+        "auto_approve": get_setting(conn, "sync.auto_approve"),
+        "default_provider": get_setting(conn, "sync.default_provider"),
+    }
+
+
+def get_moderation_config(conn: sqlite3.Connection) -> Dict[str, Any]:
+    """Get moderation configuration."""
+    return {
+        "require_review": get_setting(conn, "moderation.require_review"),
+        "auto_approve_private": get_setting(conn, "moderation.auto_approve_private"),
+        "max_pending_per_user": get_setting(conn, "moderation.max_pending_per_user"),
+    }

src/cmdforge/registry/stats.py

@@ -0,0 +1,463 @@
+"""Stats calculation functions for tools and publishers."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timedelta
+from typing import Dict, List, Optional, Any
+
+import sqlite3
+
+
+# Badge definitions
+BADGES = {
+    "verified": {
+        "name": "Verified",
+        "icon": "shield-check",
+        "color": "blue",
+        "description": "Verified publisher identity",
+    },
+    "trusted": {
+        "name": "Trusted",
+        "icon": "award",
+        "color": "gold",
+        "description": "Trust score above 80",
+    },
+    "prolific": {
+        "name": "Prolific",
+        "icon": "layers",
+        "color": "purple",
+        "description": "Published 10+ tools",
+    },
+    "veteran": {
+        "name": "Veteran",
+        "icon": "clock",
+        "color": "gray",
+        "description": "Member for 1+ year",
+    },
+    "popular": {
+        "name": "Popular",
+        "icon": "trending-up",
+        "color": "green",
+        "description": "1000+ total downloads",
+    },
+    "responsive": {
+        "name": "Responsive",
+        "icon": "message-circle",
+        "color": "cyan",
+        "description": "Resolves 90%+ of issues",
+    },
+    "top_rated": {
+        "name": "Top Rated",
+        "icon": "star",
+        "color": "yellow",
+        "description": "Average rating 4.5+",
+    },
+}
+
+
+def refresh_tool_stats(conn: sqlite3.Connection, tool_id: int) -> Dict[str, Any]:
+    """Recalculate and cache stats for a tool.
+
+    Returns the updated stats dict.
+    """
+    cursor = conn.cursor()
+
+    # Get rating stats
+    cursor.execute("""
+        SELECT
+            COUNT(*) as rating_count,
+            COALESCE(AVG(rating), 0) as average_rating,
+            SUM(CASE WHEN rating = 1 THEN 1 ELSE 0 END) as rating_1,
+            SUM(CASE WHEN rating = 2 THEN 1 ELSE 0 END) as rating_2,
+            SUM(CASE WHEN rating = 3 THEN 1 ELSE 0 END) as rating_3,
+            SUM(CASE WHEN rating = 4 THEN 1 ELSE 0 END) as rating_4,
+            SUM(CASE WHEN rating = 5 THEN 1 ELSE 0 END) as rating_5
+        FROM reviews
+        WHERE tool_id = ? AND status = 'published'
+    """, [tool_id])
+    rating_row = cursor.fetchone()
+
+    # Get unique users count
+    cursor.execute("""
+        SELECT COUNT(DISTINCT user_hash) as unique_users
+        FROM tool_usage
+        WHERE tool_id = ?
+    """, [tool_id])
+    usage_row = cursor.fetchone()
+
+    # Get issue counts
+    cursor.execute("""
+        SELECT
+            SUM(CASE WHEN status = 'open' THEN 1 ELSE 0 END) as open_issues,
+            SUM(CASE WHEN status = 'open' AND issue_type = 'security' THEN 1 ELSE 0 END) as security_issues
+        FROM tool_issues
+        WHERE tool_id = ?
+    """, [tool_id])
+    issues_row = cursor.fetchone()
+
+    stats = {
+        "tool_id": tool_id,
+        "average_rating": round(rating_row[1], 2) if rating_row else 0,
+        "rating_count": rating_row[0] if rating_row else 0,
+        "rating_1": rating_row[2] or 0 if rating_row else 0,
+        "rating_2": rating_row[3] or 0 if rating_row else 0,
+        "rating_3": rating_row[4] or 0 if rating_row else 0,
+        "rating_4": rating_row[5] or 0 if rating_row else 0,
+        "rating_5": rating_row[6] or 0 if rating_row else 0,
+        "unique_users": usage_row[0] if usage_row else 0,
+        "open_issues": issues_row[0] or 0 if issues_row else 0,
+        "security_issues": issues_row[1] or 0 if issues_row else 0,
+        "last_updated": datetime.utcnow().isoformat(),
+    }
+
+    # Upsert into tool_stats
+    cursor.execute("""
+        INSERT INTO tool_stats (
+            tool_id, average_rating, rating_count,
+            rating_1, rating_2, rating_3, rating_4, rating_5,
+            unique_users, open_issues, security_issues, last_updated
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(tool_id) DO UPDATE SET
+            average_rating = excluded.average_rating,
+            rating_count = excluded.rating_count,
+            rating_1 = excluded.rating_1,
+            rating_2 = excluded.rating_2,
+            rating_3 = excluded.rating_3,
+            rating_4 = excluded.rating_4,
+            rating_5 = excluded.rating_5,
+            unique_users = excluded.unique_users,
+            open_issues = excluded.open_issues,
+            security_issues = excluded.security_issues,
+            last_updated = excluded.last_updated
+    """, [
+        tool_id, stats["average_rating"], stats["rating_count"],
+        stats["rating_1"], stats["rating_2"], stats["rating_3"],
+        stats["rating_4"], stats["rating_5"],
+        stats["unique_users"], stats["open_issues"], stats["security_issues"],
+        stats["last_updated"],
+    ])
+    conn.commit()
+
+    return stats
+
+
+def get_tool_stats(conn: sqlite3.Connection, tool_id: int) -> Optional[Dict[str, Any]]:
+    """Get cached stats for a tool, refreshing if stale or missing."""
+    cursor = conn.cursor()
+
+    cursor.execute("""
+        SELECT * FROM tool_stats WHERE tool_id = ?
+    """, [tool_id])
+    row = cursor.fetchone()
+
+    if not row:
+        # No cached stats, calculate fresh
+        return refresh_tool_stats(conn, tool_id)
+
+    # Check if stale (older than 1 hour)
+    try:
+        last_updated = datetime.fromisoformat(row[11])  # last_updated column
+        if datetime.utcnow() - last_updated > timedelta(hours=1):
+            return refresh_tool_stats(conn, tool_id)
+    except (ValueError, TypeError):
+        return refresh_tool_stats(conn, tool_id)
+
+    return {
+        "tool_id": row[0],
+        "average_rating": row[1],
+        "rating_count": row[2],
+        "rating_1": row[3],
+        "rating_2": row[4],
+        "rating_3": row[5],
+        "rating_4": row[6],
+        "rating_5": row[7],
+        "unique_users": row[8],
+        "open_issues": row[9],
+        "security_issues": row[10],
+        "last_updated": row[11],
+    }
+
+
+def calculate_trust_score(
+    tool_count: int,
+    total_downloads: int,
+    average_rating: float,
+    total_reviews: int,
+    issues_resolved_pct: float,
+    tenure_days: int,
+    is_verified: bool,
+) -> float:
+    """Calculate publisher trust score (0-100).
+
+    Scoring breakdown:
+    - Tenure: max 20 points (5 points per year, max 4 years)
+    - Tools: max 20 points (2 points per tool, max 10 tools)
+    - Rating: max 30 points ((avg_rating / 5) * 30, requires min 3 reviews)
+    - Downloads: max 15 points (logarithmic scale)
+    - Issue response: max 10 points (resolved % * 10)
+    - Verified bonus: 5 points
+    """
+    score = 0.0
+
+    # Tenure score (max 20)
+    years = min(tenure_days / 365, 4)
+    score += years * 5
+
+    # Tools contribution (max 20)
+    score += min(tool_count, 10) * 2
+
+    # Rating score (max 30, requires minimum reviews)
+    if total_reviews >= 3:
+        score += (average_rating / 5) * 30
+    elif total_reviews > 0:
+        # Partial credit for few reviews
+        score += (average_rating / 5) * 15
+
+    # Downloads score (max 15, logarithmic)
+    if total_downloads > 0:
+        import math
+        # log10(1000) = 3, so 1000 downloads = 15 points
+        download_score = min(math.log10(total_downloads + 1) * 5, 15)
+        score += download_score
+
+    # Issue response score (max 10)
+    score += issues_resolved_pct * 10
+
+    # Verified bonus (5 points)
+    if is_verified:
+        score += 5
+
+    return round(min(100, score), 1)
+
+
+def calculate_badges(
+    is_verified: bool,
+    trust_score: float,
+    tool_count: int,
+    tenure_days: int,
+    total_downloads: int,
+    issues_resolved_pct: float,
+    average_rating: float,
+    total_reviews: int,
+) -> List[str]:
+    """Determine which badges a publisher has earned."""
+    earned = []
+
+    if is_verified:
+        earned.append("verified")
+
+    if trust_score >= 80:
+        earned.append("trusted")
+
+    if tool_count >= 10:
+        earned.append("prolific")
+
+    if tenure_days >= 365:
+        earned.append("veteran")
+
+    if total_downloads >= 1000:
+        earned.append("popular")
+
+    if issues_resolved_pct >= 0.9:
+        earned.append("responsive")
+
+    if average_rating >= 4.5 and total_reviews >= 5:
+        earned.append("top_rated")
+
+    return earned
+
+
+def refresh_publisher_stats(conn: sqlite3.Connection, publisher_id: int) -> Dict[str, Any]:
+    """Recalculate and cache stats for a publisher.
+
+    Returns the updated stats dict.
+    """
+    cursor = conn.cursor()
+
+    # Get publisher info
+    cursor.execute("""
+        SELECT verified, created_at FROM publishers WHERE id = ?
+    """, [publisher_id])
+    pub_row = cursor.fetchone()
+    if not pub_row:
+        return {}
+
+    is_verified = bool(pub_row[0])
+    try:
+        created_at = datetime.fromisoformat(pub_row[1].replace("Z", "+00:00").replace("+00:00", ""))
+        tenure_days = (datetime.utcnow() - created_at).days
+    except (ValueError, TypeError, AttributeError):
+        tenure_days = 0
+
+    # Get tool stats
+    cursor.execute("""
+        SELECT
+            COUNT(DISTINCT t.id) as tool_count,
+            COALESCE(SUM(t.downloads), 0) as total_downloads
+        FROM tools t
+        WHERE t.publisher_id = ? AND t.moderation_status = 'approved'
+    """, [publisher_id])
+    tools_row = cursor.fetchone()
+    tool_count = tools_row[0] if tools_row else 0
+    total_downloads = tools_row[1] if tools_row else 0
+
+    # Get aggregate rating across all tools
+    cursor.execute("""
+        SELECT
+            COUNT(*) as total_reviews,
+            COALESCE(AVG(r.rating), 0) as average_rating
+        FROM reviews r
+        JOIN tools t ON r.tool_id = t.id
+        WHERE t.publisher_id = ? AND r.status = 'published'
+    """, [publisher_id])
+    reviews_row = cursor.fetchone()
+    total_reviews = reviews_row[0] if reviews_row else 0
+    average_rating = round(reviews_row[1], 2) if reviews_row else 0
+
+    # Get issue resolution rate
+    cursor.execute("""
+        SELECT
+            COUNT(*) as total_issues,
+            SUM(CASE WHEN i.status IN ('fixed', 'wontfix', 'duplicate') THEN 1 ELSE 0 END) as resolved_issues
+        FROM tool_issues i
+        JOIN tools t ON i.tool_id = t.id
+        WHERE t.publisher_id = ?
+    """, [publisher_id])
+    issues_row = cursor.fetchone()
+    total_issues = issues_row[0] if issues_row else 0
+    resolved_issues = issues_row[1] or 0 if issues_row else 0
+    issues_resolved_pct = resolved_issues / total_issues if total_issues > 0 else 1.0
+
+    # Calculate trust score
+    trust_score = calculate_trust_score(
+        tool_count=tool_count,
+        total_downloads=total_downloads,
+        average_rating=average_rating,
+        total_reviews=total_reviews,
+        issues_resolved_pct=issues_resolved_pct,
+        tenure_days=tenure_days,
+        is_verified=is_verified,
+    )
+
+    # Calculate badges
+    badges = calculate_badges(
+        is_verified=is_verified,
+        trust_score=trust_score,
+        tool_count=tool_count,
+        tenure_days=tenure_days,
+        total_downloads=total_downloads,
+        issues_resolved_pct=issues_resolved_pct,
+        average_rating=average_rating,
+        total_reviews=total_reviews,
+    )
+
+    stats = {
+        "publisher_id": publisher_id,
+        "tool_count": tool_count,
+        "total_downloads": total_downloads,
+        "average_rating": average_rating,
+        "total_reviews": total_reviews,
+        "trust_score": trust_score,
+        "badges": badges,
+        "tenure_days": tenure_days,
+        "is_verified": is_verified,
+        "last_updated": datetime.utcnow().isoformat(),
+    }
+
+    # Upsert into publisher_stats
+    cursor.execute("""
+        INSERT INTO publisher_stats (
+            publisher_id, tool_count, total_downloads, average_rating,
+            total_reviews, trust_score, badges, last_updated
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(publisher_id) DO UPDATE SET
+            tool_count = excluded.tool_count,
+            total_downloads = excluded.total_downloads,
+            average_rating = excluded.average_rating,
+            total_reviews = excluded.total_reviews,
+            trust_score = excluded.trust_score,
+            badges = excluded.badges,
+            last_updated = excluded.last_updated
+    """, [
+        publisher_id, tool_count, total_downloads, average_rating,
+        total_reviews, trust_score, json.dumps(badges),
+        stats["last_updated"],
+    ])
+    conn.commit()
+
+    return stats
+
+
+def get_publisher_stats(conn: sqlite3.Connection, publisher_id: int) -> Optional[Dict[str, Any]]:
+    """Get cached stats for a publisher, refreshing if stale or missing."""
+    cursor = conn.cursor()
+
+    cursor.execute("""
+        SELECT * FROM publisher_stats WHERE publisher_id = ?
+    """, [publisher_id])
+    row = cursor.fetchone()
+
+    if not row:
+        # No cached stats, calculate fresh
+        return refresh_publisher_stats(conn, publisher_id)
+
+    # Check if stale (older than 1 hour)
+    try:
+        last_updated = datetime.fromisoformat(row[7])  # last_updated column
+        if datetime.utcnow() - last_updated > timedelta(hours=1):
+            return refresh_publisher_stats(conn, publisher_id)
+    except (ValueError, TypeError):
+        return refresh_publisher_stats(conn, publisher_id)
+
+    badges = []
+    try:
+        badges = json.loads(row[6]) if row[6] else []
+    except (json.JSONDecodeError, TypeError):
+        pass
+
+    return {
+        "publisher_id": row[0],
+        "tool_count": row[1],
+        "total_downloads": row[2],
+        "average_rating": row[3],
+        "total_reviews": row[4],
+        "trust_score": row[5],
+        "badges": badges,
+        "last_updated": row[7],
+    }
+
+
+def track_tool_usage(conn: sqlite3.Connection, tool_id: int, client_id: str) -> None:
+    """Track a tool usage (download/run) for unique user counting."""
+    import hashlib
+
+    # Hash the client_id for privacy
+    user_hash = hashlib.sha256(client_id.encode()).hexdigest()[:16]
+
+    cursor = conn.cursor()
+    cursor.execute("""
+        INSERT INTO tool_usage (tool_id, user_hash, first_used_at, last_used_at, use_count)
+        VALUES (?, ?, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP, 1)
+        ON CONFLICT(tool_id, user_hash) DO UPDATE SET
+            last_used_at = CURRENT_TIMESTAMP,
+            use_count = use_count + 1
+    """, [tool_id, user_hash])
+    conn.commit()
+
+
+def format_count(count: int) -> str:
+    """Format a count for display (e.g., 1234 -> '1.2K')."""
+    if count < 1000:
+        return str(count)
+    elif count < 10000:
+        return f"{count / 1000:.1f}K"
+    elif count < 1000000:
+        return f"{count // 1000}K"
+    else:
+        return f"{count / 1000000:.1f}M"
+
+
+def get_badge_info(badge_id: str) -> Optional[Dict[str, str]]:
+    """Get display info for a badge."""
+    return BADGES.get(badge_id)

src/cmdforge/registry/sync.py

@@ -19,22 +19,22 @@ from .db import connect_db, query_one
 
 
 def get_repo_dir() -> Path:
-    default_dir = Path.home() / ".smarttools" / "registry" / "repo"
-    return Path(os.environ.get("SMARTTOOLS_REGISTRY_REPO_DIR", default_dir))
+    default_dir = Path.home() / ".cmdforge" / "registry" / "repo"
+    return Path(os.environ.get("CMDFORGE_REGISTRY_REPO_DIR", default_dir))
 
 
 def get_repo_url() -> str:
-    return os.environ.get("SMARTTOOLS_REGISTRY_REPO_URL", "https://gitea.brrd.tech/rob/SmartTools-Registry.git")
+    return os.environ.get("CMDFORGE_REGISTRY_REPO_URL", "https://gitea.brrd.tech/rob/CmdForge-Registry.git")
 
 
 def get_repo_branch() -> str:
-    return os.environ.get("SMARTTOOLS_REGISTRY_REPO_BRANCH", "main")
+    return os.environ.get("CMDFORGE_REGISTRY_REPO_BRANCH", "main")
 
 
 def get_categories_cache_path() -> Path:
     return Path(os.environ.get(
-        "SMARTTOOLS_REGISTRY_CATEGORIES_CACHE",
-        Path.home() / ".smarttools" / "registry" / "categories_cache.json",
+        "CMDFORGE_REGISTRY_CATEGORIES_CACHE",
+        Path.home() / ".cmdforge" / "registry" / "categories_cache.json",
     ))
 
 
@@ -173,6 +173,52 @@ def sync_categories(repo_dir: Path) -> None:
     cache_path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
 
 
+def sync_collections(conn, repo_dir: Path) -> None:
+    """Sync collections from registry repo to database."""
+    collections_dir = repo_dir / "collections"
+    if not collections_dir.exists():
+        return
+
+    for collection_path in collections_dir.glob("*.yaml"):
+        try:
+            data = load_yaml(collection_path)
+            name = data.get("name") or collection_path.stem
+            display_name = data.get("display_name") or name
+            description = data.get("description")
+            icon = data.get("icon")
+            maintainer = data.get("maintainer") or "official"
+            tools = data.get("tools") or []
+            pinned = data.get("pinned") or {}
+            tags = data.get("tags") or []
+
+            tools_json = json.dumps(tools)
+            pinned_json = json.dumps(pinned) if pinned else None
+            tags_json = json.dumps(tags) if tags else None
+
+            existing = query_one(conn, "SELECT id FROM collections WHERE name = ?", [name])
+            if existing:
+                conn.execute(
+                    """
+                    UPDATE collections
+                    SET display_name = ?, description = ?, icon = ?, maintainer = ?,
+                        tools = ?, pinned = ?, tags = ?, updated_at = ?
+                    WHERE id = ?
+                    """,
+                    [display_name, description, icon, maintainer, tools_json,
+                     pinned_json, tags_json, datetime.utcnow().isoformat(), existing["id"]],
+                )
+            else:
+                conn.execute(
+                    """
+                    INSERT INTO collections (name, display_name, description, icon, maintainer, tools, pinned, tags)
+                    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                    """,
+                    [name, display_name, description, icon, maintainer, tools_json, pinned_json, tags_json],
+                )
+        except Exception:
+            continue
+
+
 def sync_from_repo() -> Tuple[bool, str]:
     repo_dir = get_repo_dir()
     clone_or_update_repo(repo_dir)
@@ -195,6 +241,7 @@ def sync_from_repo() -> Tuple[bool, str]:
                 upsert_tool(conn, owner, name, data, config_text, readme_text)
             except Exception:
                 continue
+        sync_collections(conn, repo_dir)
         conn.commit()
     finally:
         conn.close()
@@ -249,7 +296,7 @@ def process_webhook(body: bytes, headers: Dict[str, str], secret: str, timeout:
         if is_delivery_processed(conn, delivery_id):
             return 200, {"data": {"status": "already_processed"}}
 
-        lock_path = Path.home() / ".smarttools" / "registry" / "locks" / "webhook.lock"
+        lock_path = Path.home() / ".cmdforge" / "registry" / "locks" / "webhook.lock"
         if not acquire_lock(lock_path, timeout):
             return 200, {"data": {"status": "skipped", "reason": "sync_in_progress"}}
 

src/cmdforge/registry_client.py

@@ -1,4 +1,4 @@
-"""Registry API client for SmartTools.
+"""Registry API client for CmdForge.
 
 Handles all HTTP communication with the registry server.
 """
@@ -63,6 +63,7 @@ class PaginatedResponse:
     per_page: int = 20
     total: int = 0
     total_pages: int = 0
+    facets: Optional[Dict] = None  # Category/tag/owner counts when requested
 
 
 @dataclass
@@ -114,7 +115,7 @@ class DownloadResult:
 
 
 class RegistryClient:
-    """Client for interacting with the SmartTools registry API."""
+    """Client for interacting with the CmdForge registry API."""
 
     def __init__(
         self,
@@ -141,8 +142,8 @@ class RegistryClient:
         # Session for connection pooling
         self._session = requests.Session()
         self._session.headers.update({
-            "User-Agent": "SmartTools-CLI/1.0",
-            "X-SmartTools-Client": "cli/1.0.0",
+            "User-Agent": "CmdForge-CLI/1.0",
+            "X-CmdForge-Client": "cli/1.0.0",
             "Accept": "application/json"
         })
 
@@ -198,7 +199,7 @@ class RegistryClient:
             if not self.token:
                 raise RegistryError(
                     code="UNAUTHORIZED",
-                    message="Authentication required. Set registry token with 'smarttools config set-token'",
+                    message="Authentication required. Set registry token with 'cmdforge config set-token'",
                     http_status=401
                 )
             headers.update(self._auth_headers())
@@ -329,6 +330,15 @@ class RegistryClient:
         self,
         query: str,
         category: Optional[str] = None,
+        categories: Optional[List[str]] = None,
+        tags: Optional[List[str]] = None,
+        owner: Optional[str] = None,
+        min_downloads: Optional[int] = None,
+        max_downloads: Optional[int] = None,
+        published_after: Optional[str] = None,
+        published_before: Optional[str] = None,
+        include_deprecated: bool = False,
+        include_facets: bool = False,
         page: int = 1,
         per_page: int = 20,
         sort: str = "relevance"
@@ -338,15 +348,24 @@ class RegistryClient:
 
         Args:
             query: Search query
-            category: Filter by category
+            category: Filter by single category (backward compat)
+            categories: Filter by multiple categories (OR logic)
+            tags: Filter by tags (AND logic - must have all)
+            owner: Filter by publisher/owner
+            min_downloads: Minimum download count
+            max_downloads: Maximum download count
+            published_after: Published after date (ISO format)
+            published_before: Published before date (ISO format)
+            include_deprecated: Include deprecated tools
+            include_facets: Include category/tag/owner counts in response
             page: Page number
             per_page: Items per page
             sort: Sort field (relevance, downloads, published_at)
 
         Returns:
-            PaginatedResponse with matching tools
+            PaginatedResponse with matching tools (and facets if requested)
         """
-        params = {
+        params: Dict[str, Any] = {
             "q": query,
             "page": page,
             "per_page": min(per_page, 100),
@@ -354,6 +373,24 @@ class RegistryClient:
         }
         if category:
             params["category"] = category
+        if categories:
+            params["categories"] = ",".join(categories)
+        if tags:
+            params["tags"] = ",".join(tags)
+        if owner:
+            params["owner"] = owner
+        if min_downloads is not None:
+            params["min_downloads"] = min_downloads
+        if max_downloads is not None:
+            params["max_downloads"] = max_downloads
+        if published_after:
+            params["published_after"] = published_after
+        if published_before:
+            params["published_before"] = published_before
+        if include_deprecated:
+            params["deprecated"] = "true"
+        if include_facets:
+            params["include_facets"] = "true"
 
         response = self._request("GET", "/tools/search", params=params)
 
@@ -368,9 +405,37 @@ class RegistryClient:
             page=meta.get("page", page),
             per_page=meta.get("per_page", per_page),
             total=meta.get("total", 0),
-            total_pages=meta.get("total_pages", 0)
+            total_pages=meta.get("total_pages", 0),
+            facets=data.get("facets")
         )
 
+    def get_tags(
+        self,
+        category: Optional[str] = None,
+        limit: int = 100
+    ) -> List[Dict]:
+        """
+        Get all tags with usage counts.
+
+        Args:
+            category: Filter tags by category
+            limit: Maximum tags to return
+
+        Returns:
+            List of tag objects with name and count
+        """
+        params: Dict[str, Any] = {"limit": min(limit, 500)}
+        if category:
+            params["category"] = category
+
+        response = self._request("GET", "/tags", params=params)
+
+        if response.status_code != 200:
+            self._handle_error_response(response)
+
+        data = response.json()
+        return data.get("data", [])
+
     def get_tool(self, owner: str, name: str) -> ToolInfo:
         """
         Get detailed information about a tool.
@@ -500,7 +565,8 @@ class RegistryClient:
         self,
         config_yaml: str,
         readme: str = "",
-        dry_run: bool = False
+        dry_run: bool = False,
+        visibility: str = "public"
     ) -> Dict[str, Any]:
         """
         Publish a tool to the registry.
@@ -509,6 +575,7 @@ class RegistryClient:
             config_yaml: Tool configuration YAML content
             readme: README.md content
             dry_run: If True, validate without publishing
+            visibility: Tool visibility - "public", "private", or "unlisted"
 
         Returns:
             Dict with PR URL or validation results
@@ -516,7 +583,8 @@ class RegistryClient:
         payload = {
             "config": config_yaml,
             "readme": readme,
-            "dry_run": dry_run
+            "dry_run": dry_run,
+            "visibility": visibility
         }
 
         response = self._request(

src/cmdforge/resolver.py

@@ -1,12 +1,13 @@
 """Tool resolution with proper search order.
 
 Implements the tool resolution order:
-1. Local project: ./.smarttools/<owner>/<name>/config.yaml
-2. Global user: ~/.smarttools/<owner>/<name>/config.yaml
+1. Local project: ./.cmdforge/<owner>/<name>/config.yaml
+2. Global user: ~/.cmdforge/<owner>/<name>/config.yaml
 3. Registry: Fetch from API, install to global, then run
 4. Error if not found
 """
 
+import logging
 import re
 import sys
 from dataclasses import dataclass
@@ -19,9 +20,11 @@ from .tool import Tool, TOOLS_DIR, get_bin_dir, BIN_DIR
 from .config import is_auto_fetch_enabled, load_config
 from .manifest import load_manifest
 
+logger = logging.getLogger(__name__)
+
 
 # Local project tools directories (support both legacy and documented paths)
-LOCAL_TOOLS_DIRS = [Path(".smarttools"), Path("smarttools")]
+LOCAL_TOOLS_DIRS = [Path(".cmdforge"), Path("cmdforge")]
 
 
 @dataclass
@@ -362,8 +365,10 @@ class ToolResolver:
 
         except ImportError:
             # Registry client not available
+            logger.debug("Registry client not available")
             return None
         except Exception as e:
+            logger.warning(f"Registry fetch failed: {e}")
             if self.verbose:
                 print(f"Registry fetch failed: {e}", file=sys.stderr)
             return None
@@ -431,9 +436,9 @@ class ToolResolver:
         python_path = sys.executable
 
         script = f"""#!/bin/bash
-# SmartTools wrapper for '{owner}/{name}'
+# CmdForge wrapper for '{owner}/{name}'
 # Auto-generated - do not edit
-exec {python_path} -m smarttools.runner {owner}/{name} "$@"
+exec {python_path} -m cmdforge.runner {owner}/{name} "$@"
 """
 
         wrapper_path.write_text(script)
@@ -445,9 +450,9 @@ exec {python_path} -m smarttools.runner {owner}/{name} "$@"
         """Extract owner from existing wrapper script."""
         try:
             content = wrapper_path.read_text()
-            # Look for pattern: smarttools.runner owner/name
+            # Look for pattern: cmdforge.runner owner/name
             # Owner slugs can contain lowercase alphanumeric and hyphens
-            match = re.search(r'smarttools\.runner\s+([a-z0-9][a-z0-9-]*)/([a-zA-Z0-9_-]+)', content)
+            match = re.search(r'cmdforge\.runner\s+([a-z0-9][a-z0-9-]*)/([a-zA-Z0-9_-]+)', content)
             if match:
                 return match.group(1)
             return None
@@ -464,7 +469,28 @@ exec {python_path} -m smarttools.runner {owner}/{name} "$@"
                 data = self._convert_legacy_format(data)
 
             return Tool.from_dict(data)
+        except yaml.YAMLError as e:
+            logger.warning(f"YAML error in {config_path}: {e}")
+            if self.verbose:
+                print(f"Error loading tool from '{config_path}': YAML syntax error", file=sys.stderr)
+                if hasattr(e, 'problem_mark') and e.problem_mark:
+                    mark = e.problem_mark
+                    print(f"  Line {mark.line + 1}, column {mark.column + 1}", file=sys.stderr)
+                    try:
+                        lines = config_path.read_text().split('\n')
+                        if mark.line < len(lines):
+                            print(file=sys.stderr)
+                            if mark.line > 0:
+                                print(f"    {mark.line}: {lines[mark.line - 1]}", file=sys.stderr)
+                            print(f"  > {mark.line + 1}: {lines[mark.line]}", file=sys.stderr)
+                            print(f"    {' ' * (mark.column + 4)}^", file=sys.stderr)
+                    except Exception:
+                        pass
+                if hasattr(e, 'problem') and e.problem:
+                    print(f"\n  Problem: {e.problem}", file=sys.stderr)
+            return None
         except Exception as e:
+            logger.warning(f"Error loading tool from {config_path}: {e}")
             if self.verbose:
                 print(f"Error loading tool from {config_path}: {e}", file=sys.stderr)
             return None

src/cmdforge/runner.py

@@ -5,26 +5,98 @@ import sys
 from pathlib import Path
 from typing import Optional
 
-from .tool import Tool, PromptStep, CodeStep
+from .tool import Tool, PromptStep, CodeStep, ToolStep
 from .providers import call_provider, mock_provider
 from .resolver import resolve_tool, ToolNotFoundError, ToolSpec
 from .manifest import load_manifest
+from .profiles import load_profile
+
+# Maximum recursion depth for nested tool calls
+MAX_TOOL_DEPTH = 10
+
+
+def check_dependencies(tool: Tool, checked: set = None) -> list[str]:
+    """
+    Check if all dependencies for a tool are available.
+
+    Args:
+        tool: Tool to check dependencies for
+        checked: Set of already checked tools (prevents infinite loops)
+
+    Returns:
+        List of missing dependency tool references
+    """
+    if checked is None:
+        checked = set()
+
+    missing = []
+
+    # Check explicit dependencies
+    for dep in tool.dependencies:
+        if dep in checked:
+            continue
+        checked.add(dep)
+
+        try:
+            resolved = resolve_tool(dep)
+            # Recursively check nested dependencies
+            nested_missing = check_dependencies(resolved.tool, checked)
+            missing.extend(nested_missing)
+        except ToolNotFoundError:
+            missing.append(dep)
+
+    # Also check tool steps for implicit dependencies
+    for step in tool.steps:
+        if isinstance(step, ToolStep):
+            tool_ref = step.tool
+            if tool_ref in checked:
+                continue
+            checked.add(tool_ref)
+
+            try:
+                resolved = resolve_tool(tool_ref)
+                # Recursively check nested dependencies
+                nested_missing = check_dependencies(resolved.tool, checked)
+                missing.extend(nested_missing)
+            except ToolNotFoundError:
+                missing.append(tool_ref)
+
+    return missing
 
 
 def substitute_variables(template: str, variables: dict) -> str:
     """
     Substitute {variable} placeholders in a template.
 
+    Supports escaping: use {{ for literal { and }} for literal }
+
     Args:
         template: String with {var} placeholders
         variables: Dict of variable name -> value
 
     Returns:
         String with placeholders replaced
+
+    Examples:
+        >>> substitute_variables("Hello {name}", {"name": "World"})
+        'Hello World'
+        >>> substitute_variables("Use {{braces}}", {"braces": "nope"})
+        'Use {braces}'
     """
-    result = template
+    # Use unique placeholders for escaped braces
+    ESCAPE_OPEN = "\x00\x01OPEN\x01\x00"
+    ESCAPE_CLOSE = "\x00\x01CLOSE\x01\x00"
+
+    # First, replace escaped braces with placeholders
+    result = template.replace("{{", ESCAPE_OPEN).replace("}}", ESCAPE_CLOSE)
+
+    # Now do variable substitution
     for name, value in variables.items():
         result = result.replace(f"{{{name}}}", str(value) if value else "")
+
+    # Finally, restore escaped braces as single braces
+    result = result.replace(ESCAPE_OPEN, "{").replace(ESCAPE_CLOSE, "}")
+
     return result
 
 
@@ -43,6 +115,13 @@ def execute_prompt_step(step: PromptStep, variables: dict, provider_override: st
     # Build prompt with variable substitution
     prompt = substitute_variables(step.prompt, variables)
 
+    # Inject profile system prompt if specified
+    if step.profile:
+        profile = load_profile(step.profile)
+        if profile and profile.system_prompt:
+            # Prepend system prompt to user prompt
+            prompt = f"{profile.system_prompt}\n\n---\n\n{prompt}"
+
     # Call provider
     provider = provider_override or step.provider
 
@@ -58,13 +137,14 @@ def execute_prompt_step(step: PromptStep, variables: dict, provider_override: st
     return result.text, True
 
 
-def execute_code_step(step: CodeStep, variables: dict) -> tuple[dict, bool]:
+def execute_code_step(step: CodeStep, variables: dict, step_num: int = 0) -> tuple[dict, bool]:
     """
     Execute a code step.
 
     Args:
         step: The code step to execute
         variables: Current variable values (available in code)
+        step_num: Step number for error reporting
 
     Returns:
         Tuple of (output_vars_dict, success)
@@ -88,10 +168,123 @@ def execute_code_step(step: CodeStep, variables: dict) -> tuple[dict, bool]:
         return outputs, True
 
     except Exception as e:
-        print(f"Error in code step: {e}", file=sys.stderr)
+        import traceback
+        code_lines = code.split('\n')
+
+        # Extract line number from traceback
+        error_line = None
+        tb = traceback.extract_tb(e.__traceback__)
+        for frame in tb:
+            if frame.filename == '<string>':  # exec'd code
+                error_line = frame.lineno
+                break
+
+        print(f"Error in code step (step {step_num}):", file=sys.stderr)
+        print(f"  {type(e).__name__}: {e}", file=sys.stderr)
+
+        if error_line and 0 < error_line <= len(code_lines):
+            print(file=sys.stderr)
+            # Show context: line before, error line, line after
+            start = max(0, error_line - 2)
+            end = min(len(code_lines), error_line + 1)
+            for i in range(start, end):
+                marker = ">>>" if i == error_line - 1 else "   "
+                print(f"  {marker} {i+1}: {code_lines[i]}", file=sys.stderr)
+
+        print(file=sys.stderr)
+        print(f"  Available variables: {list(variables.keys())}", file=sys.stderr)
         return {}, False
 
 
+def _print_call_stack(call_stack: list, error_msg: str) -> None:
+    """Print the tool call stack for error reporting."""
+    if len(call_stack) > 1:
+        print("Error in tool chain:", file=sys.stderr)
+        for i, (name, step_num) in enumerate(call_stack):
+            indent = "  " * i
+            arrow = "-> " if i > 0 else ""
+            step_info = f" (step {step_num})" if step_num else ""
+            print(f"{indent}{arrow}{name}{step_info}", file=sys.stderr)
+        print(f"{'  ' * len(call_stack)}{error_msg}", file=sys.stderr)
+    else:
+        print(f"Error: {error_msg}", file=sys.stderr)
+
+
+def execute_tool_step(
+    step: ToolStep,
+    variables: dict,
+    depth: int = 0,
+    provider_override: Optional[str] = None,
+    dry_run: bool = False,
+    verbose: bool = False,
+    call_stack: Optional[list] = None
+) -> tuple[str, bool]:
+    """
+    Execute a tool step by calling another tool.
+
+    Args:
+        step: The tool step to execute
+        variables: Current variable values
+        depth: Current recursion depth
+        provider_override: Override provider for nested calls
+        dry_run: Just show what would happen
+        verbose: Show debug info
+        call_stack: List of (tool_name, step_num) tuples for error reporting
+
+    Returns:
+        Tuple of (output_value, success)
+    """
+    if call_stack is None:
+        call_stack = []
+
+    if depth >= MAX_TOOL_DEPTH:
+        _print_call_stack(call_stack, f"Maximum tool nesting depth ({MAX_TOOL_DEPTH}) exceeded")
+        return "", False
+
+    # Resolve the tool reference
+    try:
+        resolved = resolve_tool(step.tool)
+        nested_tool = resolved.tool
+    except ToolNotFoundError as e:
+        _print_call_stack(call_stack, f"Tool '{step.tool}' not found")
+        print(f"Hint: Install it with: cmdforge install {step.tool}", file=sys.stderr)
+        return "", False
+
+    # Prepare input by substituting variables
+    input_text = substitute_variables(step.input_template, variables)
+
+    # Prepare arguments by substituting variables in arg values
+    custom_args = {}
+    for key, value in step.args.items():
+        custom_args[key] = substitute_variables(str(value), variables)
+
+    # Determine effective provider (step override > parent override)
+    effective_provider = step.provider or provider_override
+
+    if verbose:
+        print(f"[verbose] Tool step: calling {step.tool}", file=sys.stderr)
+        print(f"[verbose]   Input length: {len(input_text)} chars", file=sys.stderr)
+        print(f"[verbose]   Args: {list(custom_args.keys())}", file=sys.stderr)
+
+    if dry_run:
+        return f"[DRY RUN - would call tool {step.tool}]", True
+
+    # Run the nested tool
+    output, exit_code = run_tool(
+        tool=nested_tool,
+        input_text=input_text,
+        custom_args=custom_args,
+        provider_override=effective_provider,
+        dry_run=dry_run,
+        show_prompt=False,
+        verbose=verbose,
+        _depth=depth + 1,
+        _call_stack=call_stack
+    )
+
+    return output, exit_code == 0
+
+
 def run_tool(
     tool: Tool,
     input_text: str,
@@ -99,7 +292,9 @@ def run_tool(
     provider_override: Optional[str] = None,
     dry_run: bool = False,
     show_prompt: bool = False,
-    verbose: bool = False
+    verbose: bool = False,
+    _depth: int = 0,
+    _call_stack: Optional[list] = None
 ) -> tuple[str, int]:
     """
     Execute a tool.
@@ -112,10 +307,25 @@ def run_tool(
         dry_run: Just show what would happen
         show_prompt: Show prompts in addition to output
         verbose: Show debug info
+        _depth: Internal recursion depth tracker
+        _call_stack: Internal call stack for error reporting
 
     Returns:
         Tuple of (output_text, exit_code)
     """
+    # Initialize call stack
+    if _call_stack is None:
+        _call_stack = []
+    current_stack = _call_stack + [(tool.name, None)]
+
+    # Check dependencies on first level only (not for nested calls)
+    if _depth == 0 and (tool.dependencies or any(isinstance(s, ToolStep) for s in tool.steps)):
+        missing = check_dependencies(tool)
+        if missing:
+            print(f"Warning: Missing dependencies: {', '.join(missing)}", file=sys.stderr)
+            print(f"Install with: cmdforge install {' '.join(missing)}", file=sys.stderr)
+            # Continue anyway - the actual step execution will fail with a better error
+
     # Initialize variables with input and arguments
     variables = {"input": input_text}
 
@@ -137,7 +347,14 @@ def run_tool(
     # Execute each step
     for i, step in enumerate(tool.steps):
         if verbose:
-            step_type = "PROMPT" if isinstance(step, PromptStep) else "CODE"
+            if isinstance(step, PromptStep):
+                step_type = "PROMPT"
+            elif isinstance(step, CodeStep):
+                step_type = "CODE"
+            elif isinstance(step, ToolStep):
+                step_type = f"TOOL({step.tool})"
+            else:
+                step_type = "UNKNOWN"
             print(f"[verbose] Step {i+1}: {step_type} -> {{{step.output_var}}}", file=sys.stderr)
 
         if isinstance(step, PromptStep):
@@ -167,12 +384,34 @@ def run_tool(
                 for var in [v.strip() for v in step.output_var.split(',')]:
                     variables[var] = "[DRY RUN - would execute code]"
             else:
-                outputs, success = execute_code_step(step, variables)
+                outputs, success = execute_code_step(step, variables, step_num=i+1)
                 if not success:
                     return "", 1
                 # Merge all output vars into variables
                 variables.update(outputs)
 
+        elif isinstance(step, ToolStep):
+            if verbose or dry_run:
+                print(f"=== TOOL (Step {i+1}) -> {{{step.output_var}}} ===", file=sys.stderr)
+                print(f"  Calling: {step.tool}", file=sys.stderr)
+                print(f"  Args: {step.args}", file=sys.stderr)
+                print("=== END TOOL ===", file=sys.stderr)
+
+            # Update call stack with current step number
+            step_stack = _call_stack + [(tool.name, i + 1)]
+            output, success = execute_tool_step(
+                step,
+                variables,
+                depth=_depth,
+                provider_override=provider_override,
+                dry_run=dry_run,
+                verbose=verbose,
+                call_stack=step_stack
+            )
+            if not success:
+                return "", 3
+            variables[step.output_var] = output
+
     # Generate final output
     output = substitute_variables(tool.output, variables)
 
@@ -191,7 +430,7 @@ def create_argument_parser(tool: Tool) -> argparse.ArgumentParser:
     """
     parser = argparse.ArgumentParser(
         prog=tool.name,
-        description=tool.description or f"SmartTools: {tool.name}"
+        description=tool.description or f"CmdForge: {tool.name}"
     )
 
     # Universal flags
@@ -225,7 +464,7 @@ def create_argument_parser(tool: Tool) -> argparse.ArgumentParser:
 def main():
     """Entry point for tool execution via wrapper script."""
     if len(sys.argv) < 2:
-        print("Usage: python -m smarttools.runner <tool_name> [args...]", file=sys.stderr)
+        print("Usage: python -m cmdforge.runner <tool_name> [args...]", file=sys.stderr)
         sys.exit(1)
 
     tool_spec = sys.argv[1]

src/cmdforge/tool.py

@@ -10,7 +10,7 @@ import yaml
 
 
 # Default tools directory
-TOOLS_DIR = Path.home() / ".smarttools"
+TOOLS_DIR = Path.home() / ".cmdforge"
 
 # Default bin directory for wrapper scripts
 BIN_DIR = Path.home() / ".local" / "bin"
@@ -49,6 +49,8 @@ class PromptStep:
     provider: str       # Provider name
     output_var: str     # Variable to store output
     prompt_file: Optional[str] = None  # Optional filename for external prompt
+    profile: Optional[str] = None  # Optional AI persona profile name
+    name: Optional[str] = None  # Optional display name for the step
 
     def to_dict(self) -> dict:
         d = {
@@ -59,6 +61,10 @@ class PromptStep:
         }
         if self.prompt_file:
             d["prompt_file"] = self.prompt_file
+        if self.profile:
+            d["profile"] = self.profile
+        if self.name:
+            d["name"] = self.name
         return d
 
     @classmethod
@@ -67,7 +73,9 @@ class PromptStep:
             prompt=data["prompt"],
             provider=data["provider"],
             output_var=data["output_var"],
-            prompt_file=data.get("prompt_file")
+            prompt_file=data.get("prompt_file"),
+            profile=data.get("profile"),
+            name=data.get("name")
         )
 
 
@@ -77,6 +85,7 @@ class CodeStep:
     code: str           # Python code (inline or loaded from file)
     output_var: str     # Variable name(s) to capture (comma-separated for multiple)
     code_file: Optional[str] = None  # Optional filename for external code
+    name: Optional[str] = None  # Optional display name for the step
 
     def to_dict(self) -> dict:
         d = {
@@ -86,6 +95,8 @@ class CodeStep:
         }
         if self.code_file:
             d["code_file"] = self.code_file
+        if self.name:
+            d["name"] = self.name
         return d
 
     @classmethod
@@ -93,11 +104,82 @@ class CodeStep:
         return cls(
             code=data.get("code", ""),
             output_var=data["output_var"],
-            code_file=data.get("code_file")
+            code_file=data.get("code_file"),
+            name=data.get("name")
         )
 
 
-Step = PromptStep | CodeStep
+@dataclass
+class ToolStep:
+    """A step that calls another tool."""
+    tool: str                      # Tool reference (owner/name or just name)
+    output_var: str                # Variable to store output
+    input_template: str = "{input}"  # Input template (supports variable substitution)
+    args: dict = field(default_factory=dict)  # Arguments to pass to the tool
+    provider: Optional[str] = None  # Provider override for the called tool
+    name: Optional[str] = None  # Optional display name for the step
+
+    def to_dict(self) -> dict:
+        d = {
+            "type": "tool",
+            "tool": self.tool,
+            "output_var": self.output_var,
+        }
+        if self.input_template != "{input}":
+            d["input"] = self.input_template
+        if self.args:
+            d["args"] = self.args
+        if self.provider:
+            d["provider"] = self.provider
+        if self.name:
+            d["name"] = self.name
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ToolStep":
+        return cls(
+            tool=data["tool"],
+            output_var=data["output_var"],
+            input_template=data.get("input", "{input}"),
+            args=data.get("args", {}),
+            provider=data.get("provider"),
+            name=data.get("name")
+        )
+
+
+Step = PromptStep | CodeStep | ToolStep
+
+
+@dataclass
+class ToolSource:
+    """Attribution and source information for imported/external tools."""
+    type: str = "original"  # "original", "imported", "forked"
+    license: Optional[str] = None
+    url: Optional[str] = None
+    author: Optional[str] = None
+    original_tool: Optional[str] = None  # e.g., "fabric/patterns/extract_wisdom"
+
+    def to_dict(self) -> dict:
+        d = {"type": self.type}
+        if self.license:
+            d["license"] = self.license
+        if self.url:
+            d["url"] = self.url
+        if self.author:
+            d["author"] = self.author
+        if self.original_tool:
+            d["original_tool"] = self.original_tool
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ToolSource":
+        return cls(
+            type=data.get("type", "original"),
+            license=data.get("license"),
+            url=data.get("url"),
+            author=data.get("author"),
+            original_tool=data.get("original_tool"),
+        )
 
 
 # Default categories for organizing tools
@@ -106,13 +188,16 @@ DEFAULT_CATEGORIES = ["Text", "Developer", "Data", "Other"]
 
 @dataclass
 class Tool:
-    """A SmartTools tool definition."""
+    """A CmdForge tool definition."""
     name: str
     description: str = ""
     category: str = "Other"  # Tool category for organization
     arguments: List[ToolArgument] = field(default_factory=list)
     steps: List[Step] = field(default_factory=list)
     output: str = "{input}"  # Output template
+    dependencies: List[str] = field(default_factory=list)  # Required tools for meta-tools
+    source: Optional[ToolSource] = None  # Attribution for imported/external tools
+    version: str = ""  # Tool version
 
     @classmethod
     def from_dict(cls, data: dict) -> "Tool":
@@ -126,6 +211,13 @@ class Tool:
                 steps.append(PromptStep.from_dict(step))
             elif step.get("type") == "code":
                 steps.append(CodeStep.from_dict(step))
+            elif step.get("type") == "tool":
+                steps.append(ToolStep.from_dict(step))
+
+        # Parse source attribution if present
+        source = None
+        if "source" in data:
+            source = ToolSource.from_dict(data["source"])
 
         return cls(
             name=data["name"],
@@ -133,7 +225,10 @@ class Tool:
             category=data.get("category", "Other"),
             arguments=arguments,
             steps=steps,
-            output=data.get("output", "{input}")
+            output=data.get("output", "{input}"),
+            dependencies=data.get("dependencies", []),
+            source=source,
+            version=data.get("version", ""),
         )
 
     def to_dict(self) -> dict:
@@ -141,9 +236,16 @@ class Tool:
             "name": self.name,
             "description": self.description,
         }
+        if self.version:
+            d["version"] = self.version
         # Only include category if it's not the default
         if self.category and self.category != "Other":
             d["category"] = self.category
+        # Include source attribution if present
+        if self.source:
+            d["source"] = self.source.to_dict()
+        if self.dependencies:
+            d["dependencies"] = self.dependencies
         d["arguments"] = [arg.to_dict() for arg in self.arguments]
         d["steps"] = [step.to_dict() for step in self.steps]
         d["output"] = self.output
@@ -230,8 +332,34 @@ def load_tool(name: str) -> Optional[Tool]:
             }
 
         return Tool.from_dict(data)
+    except yaml.YAMLError as e:
+        import sys
+        print(f"Error loading tool '{name}': YAML syntax error", file=sys.stderr)
+        if hasattr(e, 'problem_mark') and e.problem_mark:
+            mark = e.problem_mark
+            print(f"  Line {mark.line + 1}, column {mark.column + 1}", file=sys.stderr)
+            # Show the problematic line with context
+            try:
+                lines = config_path.read_text().split('\n')
+                if mark.line < len(lines):
+                    print(file=sys.stderr)
+                    # Show line before for context
+                    if mark.line > 0:
+                        print(f"    {mark.line}: {lines[mark.line - 1]}", file=sys.stderr)
+                    print(f"  > {mark.line + 1}: {lines[mark.line]}", file=sys.stderr)
+                    print(f"    {' ' * (mark.column + 4)}^", file=sys.stderr)
+            except Exception:
+                pass
+        if hasattr(e, 'problem') and e.problem:
+            print(f"\n  Problem: {e.problem}", file=sys.stderr)
+        return None
+    except KeyError as e:
+        import sys
+        print(f"Error loading tool '{name}': Missing required field {e}", file=sys.stderr)
+        return None
     except Exception as e:
-        print(f"Error loading tool {name}: {e}")
+        import sys
+        print(f"Error loading tool '{name}': {e}", file=sys.stderr)
         return None
 
 
@@ -275,13 +403,13 @@ def create_wrapper_script(name: str) -> Path:
     bin_dir = get_bin_dir()
     wrapper_path = bin_dir / name
 
-    # Use the current Python interpreter to ensure smarttools is available
+    # Use the current Python interpreter to ensure cmdforge is available
     python_path = sys.executable
 
     script = f"""#!/bin/bash
-# SmartTools wrapper for '{name}'
+# CmdForge wrapper for '{name}'
 # Auto-generated - do not edit
-exec {python_path} -m smarttools.runner {name} "$@"
+exec {python_path} -m cmdforge.runner {name} "$@"
 """
 
     wrapper_path.write_text(script)

src/cmdforge/web/__init__.py

@@ -1,4 +1,4 @@
-"""Web UI blueprint for SmartTools."""
+"""Web UI blueprint for CmdForge."""
 
 import os
 from flask import Blueprint

src/cmdforge/web/app.py

@@ -1,4 +1,4 @@
-"""Web app factory for SmartTools UI."""
+"""Web app factory for CmdForge UI."""
 
 from __future__ import annotations
 
@@ -7,12 +7,30 @@ import secrets
 
 from flask import Flask, render_template, session
 
-from smarttools.registry import app as registry_app
+# Initialize Sentry before importing Flask app (if DSN is configured)
+_sentry_dsn = os.environ.get("SENTRY_DSN")
+if _sentry_dsn:
+    try:
+        import sentry_sdk
+        from sentry_sdk.integrations.flask import FlaskIntegration
+
+        sentry_sdk.init(
+            dsn=_sentry_dsn,
+            integrations=[FlaskIntegration()],
+            traces_sample_rate=float(os.environ.get("SENTRY_TRACES_RATE", "0.1")),
+            profiles_sample_rate=float(os.environ.get("SENTRY_PROFILES_RATE", "0.1")),
+            environment=os.environ.get("CMDFORGE_ENV", "development"),
+            send_default_pii=False,  # Privacy: don't send user IPs, emails, etc.
+        )
+    except ImportError:
+        pass  # sentry-sdk not installed
+
+from cmdforge.registry import app as registry_app
 
 from . import web_bp
 from .auth import login, register, logout
 from .filters import register_filters
-from .seo import sitemap_response, robots_txt
+from .forum import forum_bp
 from .sessions import SQLiteSessionInterface, cleanup_expired_sessions
 
 
@@ -23,12 +41,13 @@ def create_web_app() -> Flask:
     from . import routes  # noqa: F401
 
     app.register_blueprint(web_bp)
+    app.register_blueprint(forum_bp)
 
     # Session configuration
-    app.session_interface = SQLiteSessionInterface(cookie_name="smarttools_session")
-    app.config["SESSION_COOKIE_NAME"] = "smarttools_session"
-    app.config["SESSION_COOKIE_SECURE"] = os.environ.get("SMARTTOOLS_ENV") == "production"
-    app.config["SHOW_ADS"] = os.environ.get("SMARTTOOLS_SHOW_ADS", "").lower() == "true"
+    app.session_interface = SQLiteSessionInterface(cookie_name="cmdforge_session")
+    app.config["SESSION_COOKIE_NAME"] = "cmdforge_session"
+    app.config["SESSION_COOKIE_SECURE"] = os.environ.get("CMDFORGE_ENV") == "production"
+    app.config["SHOW_ADS"] = os.environ.get("CMDFORGE_SHOW_ADS", "").lower() == "true"
 
     # CSRF token generator
     app.config["CSRF_GENERATOR"] = lambda: secrets.token_urlsafe(32)
@@ -46,10 +65,6 @@ def create_web_app() -> Flask:
 
     cleanup_expired_sessions()
 
-    # SEO routes
-    app.add_url_rule("/sitemap.xml", endpoint="web.sitemap", view_func=sitemap_response)
-    app.add_url_rule("/robots.txt", endpoint="web.robots", view_func=robots_txt)
-
     # Error handlers
     @app.errorhandler(404)
     def not_found_error(error):

src/cmdforge/web/filters.py

@@ -2,9 +2,13 @@
 
 from __future__ import annotations
 
+import html
+import re
 from datetime import datetime, timezone
 from typing import TYPE_CHECKING
 
+from markupsafe import Markup
+
 if TYPE_CHECKING:
     from flask import Flask
 
@@ -129,12 +133,104 @@ def truncate_words(text: str | None, length: int = 20, suffix: str = "...") -> s
     return " ".join(words[:length]) + suffix
 
 
+def render_markdown(text: str | None) -> Markup:
+    """Render markdown to HTML with safe defaults.
+
+    Supports basic markdown:
+    - **bold** and *italic*
+    - `inline code` and ```code blocks```
+    - [links](url)
+    - Lists (- item or 1. item)
+    - > blockquotes
+    - Paragraphs (double newline)
+    """
+    if not text:
+        return Markup("")
+
+    # Escape HTML first for safety
+    text = html.escape(text)
+
+    # Code blocks (```...```)
+    def replace_code_block(match):
+        code = match.group(1)
+        return f'<pre class="bg-gray-900 text-gray-100 rounded-lg p-4 overflow-x-auto my-4 text-sm"><code>{code}</code></pre>'
+
+    text = re.sub(r"```(\w*)\n?([\s\S]*?)```", lambda m: replace_code_block(type("", (), {"group": lambda s, i: m.group(2) if i == 1 else m.group(1)})()), text)
+
+    # Inline code (`...`)
+    text = re.sub(r"`([^`]+)`", r'<code class="bg-gray-100 text-indigo-600 px-1.5 py-0.5 rounded text-sm font-mono">\1</code>', text)
+
+    # Bold (**...**)
+    text = re.sub(r"\*\*([^*]+)\*\*", r"<strong>\1</strong>", text)
+
+    # Italic (*...*)
+    text = re.sub(r"\*([^*]+)\*", r"<em>\1</em>", text)
+
+    # Links [text](url) - only allow http/https URLs
+    def replace_link(match):
+        link_text = match.group(1)
+        url = match.group(2)
+        if url.startswith(("http://", "https://", "/")):
+            return f'<a href="{url}" class="text-indigo-600 hover:text-indigo-800 underline" rel="nofollow noopener" target="_blank">{link_text}</a>'
+        return match.group(0)
+
+    text = re.sub(r"\[([^\]]+)\]\(([^)]+)\)", replace_link, text)
+
+    # Blockquotes (> ...)
+    lines = text.split("\n")
+    result_lines = []
+    in_blockquote = False
+    blockquote_lines = []
+
+    for line in lines:
+        if line.startswith("&gt; "):  # Escaped >
+            if not in_blockquote:
+                in_blockquote = True
+                blockquote_lines = []
+            blockquote_lines.append(line[5:])
+        else:
+            if in_blockquote:
+                result_lines.append(f'<blockquote class="border-l-4 border-gray-300 pl-4 italic text-gray-600 my-4">{" ".join(blockquote_lines)}</blockquote>')
+                in_blockquote = False
+                blockquote_lines = []
+            result_lines.append(line)
+
+    if in_blockquote:
+        result_lines.append(f'<blockquote class="border-l-4 border-gray-300 pl-4 italic text-gray-600 my-4">{" ".join(blockquote_lines)}</blockquote>')
+
+    text = "\n".join(result_lines)
+
+    # Unordered lists (- item)
+    text = re.sub(r"^- (.+)$", r'<li class="ml-4">\1</li>', text, flags=re.MULTILINE)
+    text = re.sub(r"(<li[^>]*>.*</li>\n?)+", r'<ul class="list-disc list-inside my-4">\g<0></ul>', text)
+
+    # Ordered lists (1. item)
+    text = re.sub(r"^\d+\. (.+)$", r'<li class="ml-4">\1</li>', text, flags=re.MULTILINE)
+
+    # Paragraphs (double newline)
+    paragraphs = re.split(r"\n\n+", text)
+    formatted = []
+    for p in paragraphs:
+        p = p.strip()
+        if p:
+            # Don't wrap if it's already a block element
+            if p.startswith(("<pre", "<ul", "<ol", "<blockquote", "<li")):
+                formatted.append(p)
+            else:
+                # Convert single newlines to <br> within paragraphs
+                p = p.replace("\n", "<br>\n")
+                formatted.append(f'<p class="mb-4">{p}</p>')
+
+    return Markup("\n".join(formatted))
+
+
 def register_filters(app: Flask) -> None:
     """Register all custom filters with a Flask app."""
     app.jinja_env.filters["timeago"] = timeago
     app.jinja_env.filters["format_number"] = format_number
     app.jinja_env.filters["date_format"] = date_format
     app.jinja_env.filters["truncate_words"] = truncate_words
+    app.jinja_env.filters["markdown"] = render_markdown
 
     # Global functions
     app.jinja_env.globals["now"] = datetime.utcnow

src/cmdforge/web/forum/__init__.py

@@ -0,0 +1,5 @@
+"""Forum blueprint for CmdForge community discussions."""
+
+from .routes import forum_bp
+
+__all__ = ["forum_bp"]

src/cmdforge/web/forum/models.py

@@ -0,0 +1,245 @@
+"""Forum database models and schema."""
+
+from __future__ import annotations
+
+import re
+import sqlite3
+from typing import Any
+
+from cmdforge.registry.db import connect_db, query_one, query_all
+
+
+FORUM_SCHEMA = """
+CREATE TABLE IF NOT EXISTS forum_categories (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    slug TEXT UNIQUE NOT NULL,
+    name TEXT NOT NULL,
+    description TEXT,
+    icon TEXT,
+    sort_order INTEGER DEFAULT 0,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS forum_topics (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    category_id INTEGER NOT NULL REFERENCES forum_categories(id),
+    title TEXT NOT NULL,
+    slug TEXT NOT NULL,
+    author_name TEXT NOT NULL,
+    author_email TEXT,
+    content TEXT NOT NULL,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    is_pinned INTEGER DEFAULT 0,
+    is_locked INTEGER DEFAULT 0,
+    view_count INTEGER DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS forum_replies (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    topic_id INTEGER NOT NULL REFERENCES forum_topics(id) ON DELETE CASCADE,
+    author_name TEXT NOT NULL,
+    author_email TEXT,
+    content TEXT NOT NULL,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    is_solution INTEGER DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS idx_forum_topics_category ON forum_topics(category_id);
+CREATE INDEX IF NOT EXISTS idx_forum_topics_updated ON forum_topics(updated_at DESC);
+CREATE INDEX IF NOT EXISTS idx_forum_replies_topic ON forum_replies(topic_id);
+"""
+
+DEFAULT_CATEGORIES = [
+    ("general", "General Discussion", "Chat about anything CmdForge related", "chat", 1),
+    ("help", "Help & Support", "Get help with installation, configuration, or usage", "question", 2),
+    ("showcase", "Showcase", "Share tools and projects you've built with CmdForge", "star", 3),
+    ("ideas", "Ideas & Feedback", "Suggest features and improvements", "lightbulb", 4),
+    ("tutorials", "Tutorials & Guides", "Community-written guides and how-tos", "book", 5),
+]
+
+
+def init_forum_schema(conn: sqlite3.Connection) -> None:
+    """Initialize forum tables."""
+    conn.executescript(FORUM_SCHEMA)
+    conn.commit()
+
+
+def seed_categories(conn: sqlite3.Connection) -> None:
+    """Seed default forum categories if they don't exist."""
+    for slug, name, description, icon, sort_order in DEFAULT_CATEGORIES:
+        existing = query_one(
+            conn, "SELECT id FROM forum_categories WHERE slug = ?", [slug]
+        )
+        if not existing:
+            conn.execute(
+                """INSERT INTO forum_categories (slug, name, description, icon, sort_order)
+                   VALUES (?, ?, ?, ?, ?)""",
+                [slug, name, description, icon, sort_order],
+            )
+    conn.commit()
+
+
+def slugify(text: str) -> str:
+    """Convert text to URL-friendly slug."""
+    text = text.lower().strip()
+    text = re.sub(r"[^\w\s-]", "", text)
+    text = re.sub(r"[-\s]+", "-", text)
+    return text[:100]  # Limit length
+
+
+def get_categories_with_stats(conn: sqlite3.Connection) -> list[dict[str, Any]]:
+    """Get all categories with topic counts and latest activity."""
+    rows = query_all(
+        conn,
+        """
+        SELECT
+            c.*,
+            COUNT(t.id) as topic_count,
+            COALESCE(SUM((SELECT COUNT(*) FROM forum_replies r WHERE r.topic_id = t.id)), 0) as reply_count,
+            MAX(COALESCE(t.updated_at, c.created_at)) as latest_activity
+        FROM forum_categories c
+        LEFT JOIN forum_topics t ON t.category_id = c.id
+        GROUP BY c.id
+        ORDER BY c.sort_order
+        """,
+    )
+    return [dict(row) for row in rows]
+
+
+def get_category_by_slug(conn: sqlite3.Connection, slug: str) -> dict[str, Any] | None:
+    """Get a category by slug."""
+    row = query_one(conn, "SELECT * FROM forum_categories WHERE slug = ?", [slug])
+    return dict(row) if row else None
+
+
+def get_topics_for_category(
+    conn: sqlite3.Connection, category_id: int, page: int = 1, per_page: int = 20
+) -> tuple[list[dict[str, Any]], int]:
+    """Get topics for a category with pagination."""
+    offset = (page - 1) * per_page
+
+    # Get total count
+    count_row = query_one(
+        conn,
+        "SELECT COUNT(*) as total FROM forum_topics WHERE category_id = ?",
+        [category_id],
+    )
+    total = count_row["total"] if count_row else 0
+
+    # Get topics with reply counts
+    rows = query_all(
+        conn,
+        """
+        SELECT
+            t.*,
+            (SELECT COUNT(*) FROM forum_replies WHERE topic_id = t.id) as reply_count,
+            (SELECT MAX(created_at) FROM forum_replies WHERE topic_id = t.id) as last_reply_at
+        FROM forum_topics t
+        WHERE t.category_id = ?
+        ORDER BY t.is_pinned DESC, COALESCE(
+            (SELECT MAX(created_at) FROM forum_replies WHERE topic_id = t.id),
+            t.updated_at
+        ) DESC
+        LIMIT ? OFFSET ?
+        """,
+        [category_id, per_page, offset],
+    )
+    return [dict(row) for row in rows], total
+
+
+def get_topic_by_id(conn: sqlite3.Connection, topic_id: int) -> dict[str, Any] | None:
+    """Get a topic by ID."""
+    row = query_one(conn, "SELECT * FROM forum_topics WHERE id = ?", [topic_id])
+    return dict(row) if row else None
+
+
+def get_replies_for_topic(conn: sqlite3.Connection, topic_id: int) -> list[dict[str, Any]]:
+    """Get all replies for a topic."""
+    rows = query_all(
+        conn,
+        "SELECT * FROM forum_replies WHERE topic_id = ? ORDER BY created_at",
+        [topic_id],
+    )
+    return [dict(row) for row in rows]
+
+
+def create_topic(
+    conn: sqlite3.Connection,
+    category_id: int,
+    title: str,
+    content: str,
+    author_name: str,
+    author_email: str | None = None,
+) -> int:
+    """Create a new topic and return its ID."""
+    slug = slugify(title)
+    cursor = conn.execute(
+        """INSERT INTO forum_topics
+           (category_id, title, slug, author_name, author_email, content)
+           VALUES (?, ?, ?, ?, ?, ?)""",
+        [category_id, title, slug, author_name, author_email, content],
+    )
+    conn.commit()
+    return cursor.lastrowid
+
+
+def create_reply(
+    conn: sqlite3.Connection,
+    topic_id: int,
+    content: str,
+    author_name: str,
+    author_email: str | None = None,
+) -> int:
+    """Create a new reply and return its ID."""
+    cursor = conn.execute(
+        """INSERT INTO forum_replies (topic_id, author_name, author_email, content)
+           VALUES (?, ?, ?, ?)""",
+        [topic_id, author_name, author_email, content],
+    )
+    # Update topic's updated_at timestamp
+    conn.execute(
+        "UPDATE forum_topics SET updated_at = CURRENT_TIMESTAMP WHERE id = ?",
+        [topic_id],
+    )
+    conn.commit()
+    return cursor.lastrowid
+
+
+def increment_view_count(conn: sqlite3.Connection, topic_id: int) -> None:
+    """Increment a topic's view count."""
+    conn.execute(
+        "UPDATE forum_topics SET view_count = view_count + 1 WHERE id = ?",
+        [topic_id],
+    )
+    conn.commit()
+
+
+def get_recent_topics(conn: sqlite3.Connection, limit: int = 5) -> list[dict[str, Any]]:
+    """Get the most recently active topics across all categories."""
+    rows = query_all(
+        conn,
+        """
+        SELECT
+            t.*,
+            c.name as category_name,
+            c.slug as category_slug,
+            (SELECT COUNT(*) FROM forum_replies WHERE topic_id = t.id) as reply_count
+        FROM forum_topics t
+        JOIN forum_categories c ON c.id = t.category_id
+        ORDER BY t.updated_at DESC
+        LIMIT ?
+        """,
+        [limit],
+    )
+    return [dict(row) for row in rows]
+
+
+def get_forum_stats(conn: sqlite3.Connection) -> dict[str, int]:
+    """Get overall forum statistics."""
+    topics = query_one(conn, "SELECT COUNT(*) as count FROM forum_topics")
+    replies = query_one(conn, "SELECT COUNT(*) as count FROM forum_replies")
+    return {
+        "topics": topics["count"] if topics else 0,
+        "replies": replies["count"] if replies else 0,
+    }

src/cmdforge/web/forum/routes.py

@@ -0,0 +1,291 @@
+"""Forum blueprint routes."""
+
+from __future__ import annotations
+
+import html
+import re
+from functools import wraps
+from typing import Callable
+
+from flask import (
+    Blueprint,
+    abort,
+    flash,
+    g,
+    redirect,
+    render_template,
+    request,
+    session,
+    url_for,
+)
+
+from cmdforge.registry.db import connect_db
+
+from .models import (
+    create_reply,
+    create_topic,
+    get_categories_with_stats,
+    get_category_by_slug,
+    get_forum_stats,
+    get_recent_topics,
+    get_replies_for_topic,
+    get_topic_by_id,
+    get_topics_for_category,
+    increment_view_count,
+    init_forum_schema,
+    seed_categories,
+)
+
+forum_bp = Blueprint(
+    "forum",
+    __name__,
+    url_prefix="/forum",
+    template_folder="../templates/forum",
+)
+
+
+def get_db():
+    """Get database connection, creating forum tables if needed."""
+    if "forum_db" not in g:
+        g.forum_db = connect_db()
+        init_forum_schema(g.forum_db)
+        seed_categories(g.forum_db)
+    return g.forum_db
+
+
+@forum_bp.before_request
+def before_request():
+    """Set up database connection before each request."""
+    g.forum_db = get_db()
+
+
+@forum_bp.teardown_request
+def teardown_request(exception):
+    """Close database connection after each request."""
+    db = g.pop("forum_db", None)
+    if db is not None:
+        db.close()
+
+
+def validate_content(content: str, min_length: int = 10, max_length: int = 50000) -> str | None:
+    """Validate content and return error message if invalid."""
+    if not content or len(content.strip()) < min_length:
+        return f"Content must be at least {min_length} characters."
+    if len(content) > max_length:
+        return f"Content must be less than {max_length} characters."
+    return None
+
+
+def validate_name(name: str) -> str | None:
+    """Validate author name and return error message if invalid."""
+    if not name or len(name.strip()) < 2:
+        return "Name must be at least 2 characters."
+    if len(name) > 100:
+        return "Name must be less than 100 characters."
+    # Basic sanitization - allow letters, numbers, spaces, and common punctuation
+    if not re.match(r"^[\w\s\-'.]+$", name, re.UNICODE):
+        return "Name contains invalid characters."
+    return None
+
+
+def validate_email(email: str | None) -> str | None:
+    """Validate email if provided."""
+    if not email:
+        return None  # Email is optional
+    if len(email) > 254:
+        return "Email is too long."
+    if not re.match(r"^[^@]+@[^@]+\.[^@]+$", email):
+        return "Invalid email format."
+    return None
+
+
+def validate_title(title: str) -> str | None:
+    """Validate topic title."""
+    if not title or len(title.strip()) < 5:
+        return "Title must be at least 5 characters."
+    if len(title) > 200:
+        return "Title must be less than 200 characters."
+    return None
+
+
+def honeypot_check(func: Callable) -> Callable:
+    """Decorator to check honeypot field for spam prevention."""
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        # If the honeypot field is filled, it's likely a bot
+        if request.form.get("website_url"):  # Hidden field bots often fill
+            # Silently redirect without processing
+            return redirect(url_for("forum.index"))
+        return func(*args, **kwargs)
+    return wrapper
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Forum Index - List all categories
+# ─────────────────────────────────────────────────────────────────────────────
+@forum_bp.route("/")
+def index():
+    """Forum home - list all categories with stats."""
+    db = get_db()
+    categories = get_categories_with_stats(db)
+    recent_topics = get_recent_topics(db, limit=5)
+    stats = get_forum_stats(db)
+
+    return render_template(
+        "forum/index.html",
+        categories=categories,
+        recent_topics=recent_topics,
+        stats=stats,
+    )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Category View - List topics in a category
+# ─────────────────────────────────────────────────────────────────────────────
+@forum_bp.route("/c/<slug>")
+def category(slug: str):
+    """List topics in a category."""
+    db = get_db()
+    cat = get_category_by_slug(db, slug)
+    if not cat:
+        abort(404)
+
+    page = request.args.get("page", 1, type=int)
+    per_page = 20
+    topics, total = get_topics_for_category(db, cat["id"], page, per_page)
+
+    total_pages = (total + per_page - 1) // per_page
+
+    return render_template(
+        "forum/category.html",
+        category=cat,
+        topics=topics,
+        page=page,
+        total_pages=total_pages,
+        total=total,
+    )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Topic View - View a topic and its replies
+# ─────────────────────────────────────────────────────────────────────────────
+@forum_bp.route("/t/<int:topic_id>/<slug>")
+def topic(topic_id: int, slug: str):
+    """View a topic and its replies."""
+    db = get_db()
+    t = get_topic_by_id(db, topic_id)
+    if not t:
+        abort(404)
+
+    # Redirect to correct slug if wrong
+    if t["slug"] != slug:
+        return redirect(url_for("forum.topic", topic_id=topic_id, slug=t["slug"]))
+
+    # Increment view count (simple - could add session check to prevent refresh abuse)
+    view_key = f"viewed_topic_{topic_id}"
+    if not session.get(view_key):
+        increment_view_count(db, topic_id)
+        session[view_key] = True
+
+    replies = get_replies_for_topic(db, topic_id)
+    cat = get_category_by_slug(db, "")  # We need to get by ID
+    cat_row = db.execute(
+        "SELECT * FROM forum_categories WHERE id = ?", [t["category_id"]]
+    ).fetchone()
+    cat = dict(cat_row) if cat_row else None
+
+    return render_template(
+        "forum/topic.html",
+        topic=t,
+        replies=replies,
+        category=cat,
+    )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# New Topic - Create a new topic
+# ─────────────────────────────────────────────────────────────────────────────
+@forum_bp.route("/c/<slug>/new", methods=["GET", "POST"])
+@honeypot_check
+def new_topic(slug: str):
+    """Create a new topic in a category."""
+    db = get_db()
+    cat = get_category_by_slug(db, slug)
+    if not cat:
+        abort(404)
+
+    error = None
+    form_data = {}
+
+    if request.method == "POST":
+        title = request.form.get("title", "").strip()
+        content = request.form.get("content", "").strip()
+        author_name = request.form.get("author_name", "").strip()
+        author_email = request.form.get("author_email", "").strip() or None
+
+        form_data = {
+            "title": title,
+            "content": content,
+            "author_name": author_name,
+            "author_email": author_email or "",
+        }
+
+        # Validate inputs
+        error = (
+            validate_title(title)
+            or validate_content(content)
+            or validate_name(author_name)
+            or validate_email(author_email)
+        )
+
+        if not error:
+            topic_id = create_topic(
+                db, cat["id"], title, content, author_name, author_email
+            )
+            from .models import slugify
+            topic_slug = slugify(title)
+            flash("Topic created successfully!", "success")
+            return redirect(url_for("forum.topic", topic_id=topic_id, slug=topic_slug))
+
+    return render_template(
+        "forum/new_topic.html",
+        category=cat,
+        error=error,
+        form_data=form_data,
+    )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Reply - Add a reply to a topic
+# ─────────────────────────────────────────────────────────────────────────────
+@forum_bp.route("/t/<int:topic_id>/reply", methods=["POST"])
+@honeypot_check
+def reply(topic_id: int):
+    """Add a reply to a topic."""
+    db = get_db()
+    t = get_topic_by_id(db, topic_id)
+    if not t:
+        abort(404)
+
+    if t["is_locked"]:
+        flash("This topic is locked and cannot receive new replies.", "error")
+        return redirect(url_for("forum.topic", topic_id=topic_id, slug=t["slug"]))
+
+    content = request.form.get("content", "").strip()
+    author_name = request.form.get("author_name", "").strip()
+    author_email = request.form.get("author_email", "").strip() or None
+
+    # Validate inputs
+    error = (
+        validate_content(content)
+        or validate_name(author_name)
+        or validate_email(author_email)
+    )
+
+    if error:
+        flash(error, "error")
+    else:
+        create_reply(db, topic_id, content, author_name, author_email)
+        flash("Reply posted successfully!", "success")
+
+    return redirect(url_for("forum.topic", topic_id=topic_id, slug=t["slug"]))