feat: Add planning mode and git operations documentation

- Introduced `mermaid-init.js` for dynamic mermaid diagram rendering based on theme.
- Expanded commands documentation with new sections for Planning & Tasks, Git Operations, and Workflows & Agents.
- Created a new `git.md` file detailing Git operations and auto-commit features.
- Added `planning.md` to describe the Planning Mode for task management.
- Implemented `workflow.md` for saving and orchestrating agent workflows.
- Enhanced `tools.md` with real-time tool execution updates and approval requirements.
- Added unit tests for command handling, action buttons, base block widgets, and block UI components.

Author: starhound

docs/javascripts/mermaid-init.js

@@ -0,0 +1,5 @@
+document$.subscribe(() => {
+  mermaid.initialize({
+    theme: document.body.getAttribute('data-md-color-scheme') === 'slate' ? 'dark' : 'default'
+  });
+})

docs/user/commands.md

@@ -28,6 +28,48 @@ All commands are prefixed with `/` and executed from the input prompt.
 | `/compact` | Summarize conversation to reduce tokens |
 | `/context` | Inspect current AI context messages |
 
+## Planning & Tasks
+
+| Command | Description |
+|---------|-------------|
+| `/plan <goal>` | Generate a plan for the goal |
+| `/plan show` | Show current plan |
+| `/plan approve` | Approve all pending steps |
+| `/plan execute` | Start executing approved steps |
+| `/plan save <name>` | Save plan as workflow template |
+| `/plan load <name>` | Load saved plan |
+| `/todo` | Open task manager |
+| `/todo add <task>` | Add a new task |
+| `/todo list` | List tasks in chat |
+| `/todo done <id>` | Mark task as done |
+| `/todo del <id>` | Delete task |
+
+## Git Operations
+
+| Command | Description |
+|---------|-------------|
+| `/diff [file]` | Show diff for file or all changes |
+| `/commit [message]` | Commit staged changes |
+| `/undo` | Revert last AI commit |
+| `/git log` | Show recent commits |
+| `/git stash` | Stash changes |
+| `/git checkout <file>` | Discard changes |
+
+## Workflows & Agents
+
+| Command | Description |
+|---------|-------------|
+| `/workflow` | Browse workflows |
+| `/workflow run <name>` | Run a workflow |
+| `/workflow save [name]` | Save session as workflow |
+| `/bg <goal>` | Start background task |
+| `/bg list` | List background tasks |
+| `/bg status <id>` | Show task status |
+| `/bg logs <id>` | Show task logs |
+| `/bg cancel <id>` | Cancel running task |
+| `/orchestrate <goal>` | Start multi-agent task |
+| `/agents` | List agent profiles |
+
 ## Prompt/Persona Commands
 
 | Command | Description |
@@ -38,18 +80,6 @@ All commands are prefixed with `/` and executed from the input prompt.
 | `/prompts dir` | Show prompts directory path |
 | `/prompts reload` | Reload prompts from disk |
 
-### Built-in Prompts
-
-| Key | Name | Description |
-|-----|------|-------------|
-| `default` | Default | Balanced assistant |
-| `concise` | Concise | Minimal responses |
-| `agent` | Agent | Task execution optimized |
-| `code` | Orchestration Helper | Automation focus |
-| `devops` | DevOps | System admin focus |
-
-Add custom prompts in `~/.null/prompts/` as `.txt` or `.md` files.
-
 ## Session Commands
 
 | Command | Description |
@@ -62,6 +92,14 @@ Add custom prompts in `~/.null/prompts/` as `.txt` or `.md` files.
 | `/session list` | List saved sessions |
 | `/session new` | Start new session |
 
+## Collaboration
+
+| Command | Description |
+|---------|-------------|
+| `/share` | Share current session |
+| `/share team` | Share to team workspace |
+| `/import <url>` | Import shared session |
+
 ## MCP Commands
 
 | Command | Description |
@@ -75,17 +113,6 @@ Add custom prompts in `~/.null/prompts/` as `.txt` or `.md` files.
 | `/mcp disable <name>` | Disable MCP server |
 | `/mcp reconnect [name]` | Reconnect to server(s) |
 | `/tools` | Browse available MCP tools |
-| `/tools-ui` | (Deprecated) Same as `/tools` |
-
-## Task Management
-
-| Command | Description |
-|---------|-------------|
-| `/todo` | Open task dashboard |
-| `/todo add <task>` | Add a new task |
-| `/todo list` | List tasks in chat |
-| `/todo done <id>` | Mark task as done |
-| `/todo del <id>` | Delete task |
 
 ## Configuration Commands
 
@@ -104,12 +131,29 @@ Add custom prompts in `~/.null/prompts/` as `.txt` or `.md` files.
 | `/ssh-list` | List saved SSH hosts |
 | `/ssh-del <alias>` | Delete SSH host |
 
-## Built-in Shell Commands
-
-These work in CLI mode without `/` prefix:
+## Advanced
 
 | Command | Description |
 |---------|-------------|
-| `cd <path>` | Change directory |
-| `pwd` | Print working directory |
-| `clear` | Clear terminal screen |
+| `/map` | Visualize project architecture |
+| `/cmd <description>` | Translate natural language to shell command |
+| `/explain <command>` | Explain a shell command |
+| `/fix` | Auto-correct the last error |
+| `/watch` | Monitor output for errors and auto-fix |
+
+---
+
+## Global Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl+Space` | Toggle between AI and CLI modes |
+| `Ctrl+P` | Open command palette |
+| `Ctrl+\` | Toggle file sidebar |
+| `Ctrl+R` | History search |
+| `Ctrl+F` | Find in blocks |
+| `Ctrl+L` | Clear screen/history |
+| `F1` | Open Help |
+| `F2` | Select Model |
+| `F3` | Open Settings |
+| `F4` | Manage Providers |

docs/user/git.md

@@ -0,0 +1,77 @@
+# Git Operations
+
+Null Terminal integrates deeply with Git to make version control seamless within your AI workflow. Every AI edit becomes a trackable git operation with auto-generated commit messages.
+
+## Overview
+
+The `GitManager` handles all git interactions, ensuring that changes made by the AI are properly staged, committed, and documented.
+
+## Features
+
+### Auto-Commit
+
+When enabled, the AI will automatically commit changes after writing files. It analyzes the diff and generates a conventional commit message.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 🔄 AI Commit: feat(auth): add JWT refresh token support     │
+├─────────────────────────────────────────────────────────────┤
+│ Files changed: 3                                             │
+│   M src/auth/handler.py (+45, -12)                          │
+│   A src/auth/jwt.py (+120)                                  │
+│   M tests/test_auth.py (+30, -5)                            │
+│ ─────────────────────────────────────────────────────────── │
+│                              [View Diff] [Revert] [Amend]    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Diff Viewer
+
+Inspect changes before or after they are applied.
+
+```bash
+/diff src/auth/handler.py
+```
+
+### Context Awareness
+
+The AI is aware of your repository's state, including:
+- Current branch
+- Modified files
+- Recent commits
+
+This allows for smarter suggestions and context-aware actions.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/diff [file]` | Show diff for file or all changes |
+| `/commit [message]` | Commit staged changes (AI generates message if empty) |
+| `/undo` | Revert the last AI commit |
+| `/git log` | Show recent commits with AI badges |
+| `/git stash` | Stash current changes |
+| `/git checkout <file>` | Discard changes to a file |
+
+## Configuration
+
+Configure git behavior in `~/.null/config.json`:
+
+```json
+{
+  "git": {
+    "auto_commit": true,
+    "commit_format": "conventional",
+    "sign_commits": false,
+    "show_diff_on_commit": true,
+    "allow_revert": true
+  }
+}
+```
+
+## Workflow Example
+
+1.  **AI Change**: You ask the AI to "Refactor the login function".
+2.  **Auto-Commit**: The AI modifies `login.py`. Null Terminal detects the change, stages it, generates a commit message like `refactor(auth): simplify login logic`, and commits it.
+3.  **Review**: You see the commit block. You click "View Diff" to verify the changes.
+4.  **Undo (Optional)**: If the change isn't what you wanted, you type `/undo` to revert the commit and restore the file.

docs/user/index.md

@@ -1,6 +1,6 @@
 # Null Terminal User Guide
 
-Null Terminal is a block-based terminal emulator with integrated multi-provider AI chat and autonomous agent capabilities.
+Null Terminal is a block-based terminal emulator with integrated multi-provider AI chat and autonomous agent capabilities. It bridges the gap between traditional CLI tools and modern AI assistance.
 
 ## Quick Start
 
@@ -27,14 +27,15 @@ Every command and AI interaction creates a distinct "block" in the terminal:
 
 Toggle between modes with `Ctrl+Space` or `/ai`.
 
-### Agent Mode
+### Agent Capabilities
 Enable autonomous task execution where the AI can:
-- Execute shell commands
-- Read and write files
-- Use MCP tools
-- Chain multiple operations together
+- Execute shell commands and file operations
+- **Plan Complex Tasks**: Create roadmaps with `/plan`
+- **Git Integration**: Auto-commit changes with generated messages
+- **Use MCP Tools**: Connect to external services (databases, cloud, etc.)
+- **Orchestrate Workflows**: Run multi-agent tasks
 
-Toggle with `/agent` command.
+Toggle agent mode with `/agent`.
 
 ## Essential Shortcuts
 
@@ -48,28 +49,23 @@ Toggle with `/agent` command.
 | `F3` | Change theme |
 | `Escape` | Cancel current operation |
 
-## Essential Commands
-
-| Command | Description |
-|---------|-------------|
-| `/ai` | Toggle AI mode |
-| `/agent` | Toggle agent mode |
-| `/model` | Select AI model |
-| `/provider` | Configure AI provider |
-| `/config` | Open settings |
-| `/help` | Show help |
-| `/clear` | Clear history |
-| `/export` | Export conversation |
-| `/todo` | Open task dashboard |
-| `/prompts` | Manage system prompts |
+## Feature Highlights
+
+- **Planning Mode**: Review and approve AI plans before execution. [Learn more](planning.md)
+- **Git Operations**: Seamless integration with git workflows. [Learn more](git.md)
+- **Workflows & Agents**: Save sessions and run background tasks. [Learn more](workflow.md)
+- **MCP Integration**: Connect 100+ external tools. [Learn more](mcp.md)
 
 ## Documentation
 
 - [Commands Reference](commands.md) - All slash commands
 - [Keyboard Shortcuts](shortcuts.md) - All keyboard shortcuts
 - [AI Providers](providers.md) - Setting up AI providers
-- [Configuration](configuration.md) - Settings and options
+- [Planning Mode](planning.md) - Task planning and execution
+- [Git Operations](git.md) - Version control integration
+- [Workflows & Agents](workflow.md) - Templates and multi-agent tasks
 - [MCP Servers](mcp.md) - Model Context Protocol setup
+- [Configuration](configuration.md) - Settings and options
 - [Themes](themes.md) - Customizing appearance
 - [Tools & Agent Mode](tools.md) - AI tool use
 - [Sessions](sessions.md) - Saving and loading sessions

docs/user/planning.md

@@ -0,0 +1,79 @@
+# Planning Mode
+
+Null Terminal includes a powerful Planning Mode that allows you to create, review, and execute detailed roadmaps for your AI tasks. This ensures you have control over the AI's approach before any code is written.
+
+## Overview
+
+Planning Mode breaks down complex objectives into a series of actionable steps. You can review the plan, edit specific steps, and execute them sequentially or all at once.
+
+## Usage
+
+To start planning mode, use the `/plan` command followed by your goal:
+
+```bash
+/plan Refactor the authentication module to use JWTs
+```
+
+The AI will analyze your request and generate a structured plan.
+
+### Plan Interface
+
+The plan is displayed as an interactive block in your terminal:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 📋 Plan: Refactor authentication module              [Edit] │
+├─────────────────────────────────────────────────────────────┤
+│ ☑ 1. Read current auth implementation                       │
+│      └─ read_file: src/auth/handler.py                      │
+│ ☐ 2. Identify security vulnerabilities          [Skip] [✓]  │
+│      └─ Analyze for common auth pitfalls                    │
+│ ☐ 3. Create new JWT-based auth module           [Skip] [✓]  │
+│      └─ write_file: src/auth/jwt_handler.py                 │
+│ ☐ 4. Update tests                               [Skip] [✓]  │
+│      └─ Modify existing test cases                          │
+│ ─────────────────────────────────────────────────────────── │
+│                    [Approve All] [Execute] [Cancel]          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Interacting with Plans
+
+- **Approve All**: Accepts the entire plan and begins execution.
+- **Execute**: Starts executing the approved steps.
+- **Edit**: Allows you to modify the plan's goal or steps.
+- **Skip**: Skips a specific step.
+- **✓ (Check)**: Manually marks a step as complete.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/plan <goal>` | Generate a plan for the goal |
+| `/plan show` | Show the current plan |
+| `/plan approve` | Approve all pending steps |
+| `/plan execute` | Start executing approved steps |
+| `/plan save <name>` | Save the current plan as a workflow template |
+| `/plan load <name>` | Load a saved plan |
+
+## Configuration
+
+Planning mode behavior can be customized in your `~/.null/config.json`:
+
+```json
+{
+  "planning": {
+    "enabled": true,
+    "auto_approve_read_only": true,
+    "max_steps": 20,
+    "require_approval": true,
+    "save_plans": true
+  }
+}
+```
+
+## Best Practices
+
+1.  **Be Specific**: The more specific your goal, the better the generated plan.
+2.  **Review Critical Steps**: Pay close attention to steps involving file writes or deletions.
+3.  **Iterate**: Use the edit functionality to refine the plan if the AI misses something.