clew-code 0.2.1

package/docs/taste.html

@@ -0,0 +1,181 @@
+---
+layout: default
+title: Taste
+nav_order: 14
+---
+
+# Taste
+
+**Local-first preference-learning runtime for Clew.**
+
+Taste learns your coding style from accept/reject/edit/test/lint signals and manual rules. It combines symbolic rules, semantic preference scoring, and contextual bandit optimization to adapt Clew's output to your preferences.
+
+It does **not** fine-tune the base LLM. All learning is local, online, and preference-based.
+
+## What It Learns
+
+- **Code style**: formatting, naming conventions, preferred patterns
+- **Architecture**: module structure, dependency direction, layering
+- **Tooling**: preferred build tools, linters, test frameworks
+- **Testing**: test style, coverage expectations, mocking patterns
+- **Naming**: variable/function/class naming conventions
+- **Security**: safe patterns vs unsafe patterns
+- **Performance**: efficient algorithms, caching, resource management
+- **UI patterns**: component structure, state management, styling approach
+- **Workflow**: commit style, review preferences, deployment habits
+
+## What It Does Not Do
+
+- Does not fine-tune or modify the base LLM
+- Does not send taste data to remote services (all data stays local)
+- Does not automatically block edits without showing a reason
+- Does not replace memory, skills, or CLAUDE.md files
+
+## How It Differs from Other Systems
+
+| System | Purpose | Storage | Scope |
+|--------|---------|---------|-------|
+| **CLAUDE.md** | Project instructions | `.claude/` files | Static project rules |
+| **Memory** | Cross-session facts | `memdir/` | Recall |
+| **Skills** | Reusable procedures | Plugin/skill system | Task automation |
+| **Taste** | Learned preferences | `.clew/taste/` | Adaptive preference optimization |
+
+- Rules are explicit user preferences
+- Memory is facts about the user and project
+- Skills are reusable task procedures
+- Taste is learned, weighted preference signals
+
+## Storage Paths
+
+| Data | Path |
+|------|------|
+| Project profile | `.clew/taste/profile.json` |
+| Project event log | `.clew/taste/events.jsonl` |
+| Project packages | `.clew/taste/packages/` |
+| Global profile | `~/.clew/taste/profile.json` |
+| Global packages | `~/.clew/taste/packages/` |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/taste` | Open interactive menu (arrow-key navigable) |
+| `/taste status` | Print status |
+| `/taste learn <rule>` | Add a manual rule |
+| `/taste forget <id>` | Remove a rule by ID |
+| `/taste profile` | Show full profile with rules |
+| `/taste events` | Show recent learning events |
+| `/taste decay` | Apply confidence decay |
+| `/taste eval` | Run profile self-evaluation |
+| `/taste export` | Export high-confidence rules |
+| `/taste import <file>` | Import rules from file |
+| `/taste on` | Enable taste |
+| `/taste off` | Disable taste |
+
+## Configuration
+
+Settings in `settings.json`:
+
+```json
+{
+  "taste": {
+    "enabled": true,
+    "autoLearn": true,
+    "injectPrompts": true,
+    "validateEdits": true,
+    "minConfidence": 0.55,
+    "maxInjectedRules": 8,
+    "decayEnabled": true,
+    "banditEnabled": true,
+    "neuralScoringEnabled": true
+  }
+}
+```
+
+## Architecture
+
+Taste consists of several subsystems:
+
+1. **Signal Collection** — Captures accept, reject, edit, test, lint, and tool signals from
+   user interactions and converts them into learning events.
+
+2. **Reward Model** — Maps signal types to numeric reward values (accept = +1.0, reject = -1.0,
+   test pass = +0.4, etc.) and computes edit distance rewards dynamically.
+
+3. **Symbolic Engine** — Compiles high-confidence rules into checkable constraints.
+   Rules with confidence >= 0.85 can block edit acceptance. Rules below
+   threshold warn without blocking. Never blocks silently.
+
+4. **Neural Scorer** — Provider-agnostic lexical similarity scoring (Jaccard/TF-IDF)
+   that scores candidate output against active rules. Extensible to use
+   embedding APIs when available.
+
+5. **Contextual Bandit** — Epsilon-greedy bandit with 6 strategy arms (minimal,
+   strict_style, architecture_first, test_first, safety_first, refactor_heavy).
+   Selects optimal strategy based on feedback and context features.
+
+6. **Prompt Injection** — Injects a compact `<clew_taste>` block into the system
+   prompt with relevant rules. Max 8 rules by default, filtered by confidence
+   and sorted by relevance.
+
+7. **Decay Engine** — Gradual confidence reduction for unused rules (half-life
+   based, default 30 days). Prevents stale preferences from persisting.
+
+8. **Event Log** — Append-only JSONL file storing all raw learning events for
+   auditability and regression analysis.
+
+## Continuous RL (Local Online Preference Optimization)
+
+Taste implements **local online preference optimization**:
+
+- **Online**: learns continuously from each interaction, no batch training
+- **Local**: all computation and storage stays on the user's machine
+- **Preference-based**: optimizes for user preferences via reward signals
+- **Multi-objective**: balances style, correctness, safety, and efficiency
+
+The learning loop:
+
+1. User interacts with Clew (accepts, rejects, edits output)
+2. Signal collector captures the interaction as a typed event with reward
+3. Bandit arm updates based on reward signal
+4. Rule confidence adjusts based on positive/negative evidence
+5. Prompt injection adapts to reflect current learned preferences
+6. Decay gradually reduces stale rule confidence
+
+This is **not** LLM fine-tuning. The base model's weights never change.
+Taste adapts the prompt context and edit validation, not the model itself.
+
+## Privacy
+
+- All taste data stays local by default
+- Profiles and event logs are stored in `.clew/taste/` or `~/.clew/taste/`
+- No data is sent to remote services
+- Export/import is explicit and user-initiated
+- Event logs are append-only for auditability
+
+## Integration Points
+
+| Point | Status | Description |
+|-------|--------|-------------|
+| Prompt injection | Implemented | System prompt taste block via `TastePromptInjector` |
+| Edit validation | Implemented | `validateEdit()` called in `FileEditPermissionRequest` |
+| Accept/reject signals | Implemented | Fire-and-forget via `recordAcceptSignal`/`recordRejectSignal` in `PermissionContext` |
+| Test/lint signals | No-op stub | Ready for `PostToolUse` output analysis |
+| Tool result signals | Implemented | `recordToolSignal()` in `toolExecution.ts` |
+| Interactive menu | Implemented | `/taste` Dialog with 11 actions, Spinner loading, input pre-fill |
+| Status line | Implemented | `TasteStatusLine` shown in `PromptInputFooter` |
+| Config live-reload | Implemented | `subscribeToSettingsChanges()` reloads config at runtime |
+| Settings config | Implemented | `taste.*` in `settings.json` |
+
+## Example Usage
+
+```
+/taste                           # Open interactive menu
+/taste learn Use const instead of let
+/taste learn Prefer named exports
+/taste learn Never use any type
+/taste status
+/taste profile
+/taste eval
+/taste export
+```

package/docs/taste1.html

@@ -0,0 +1,177 @@
+---
+layout: default
+title: Clew taste-1
+nav_order: 14
+---
+
+# Clew taste-1
+
+**Local-first preference-learning runtime for ClewCode.**
+
+Clew taste-1 learns the user's coding taste and working style from accept/reject/edit/test/lint signals and manual rules. It combines symbolic rules, semantic preference scoring, and contextual bandit optimization to adapt ClewCode's output to the user's preferences.
+
+It does **not** fine-tune the base LLM. All learning is local, online, and preference-based.
+
+## What It Learns
+
+- **Code style**: formatting, naming conventions, preferred patterns
+- **Architecture**: module structure, dependency direction, layering
+- **Tooling**: preferred build tools, linters, test frameworks
+- **Testing**: test style, coverage expectations, mocking patterns
+- **Naming**: variable/function/class naming conventions
+- **Security**: safe patterns vs unsafe patterns
+- **Performance**: efficient algorithms, caching, resource management
+- **UI patterns**: component structure, state management, styling approach
+- **Workflow**: commit style, review preferences, deployment habits
+
+## What It Does Not Do
+
+- Does not fine-tune or modify the base LLM
+- Does not send taste data to remote services (all data stays local)
+- Does not automatically block edits without showing a reason
+- Does not replace memory, skills, or CLAUDE.md files
+
+## How It Differs from Other Systems
+
+| System | Purpose | Storage | Scope |
+|--------|---------|---------|-------|
+| **CLAUDE.md** | Project instructions | `.claude/` files | Static project rules |
+| **Memory** | Cross-session facts | `memdir/` | Recall |
+| **Skills** | Reusable procedures | Plugin/skill system | Task automation |
+| **taste-1** | Learned preferences | `.clew/taste1/` | Adaptive preference optimization |
+
+- Rules are explicit user preferences
+- Memory is facts about the user and project
+- Skills are reusable task procedures
+- Taste is learned, weighted preference signals
+
+## Storage Paths
+
+| Data | Path |
+|------|------|
+| Project profile | `.clew/taste1/profile.json` |
+| Project event log | `.clew/taste1/events.jsonl` |
+| Project packages | `.clew/taste1/packages/` |
+| Global profile | `~/.clew/taste1/profile.json` |
+| Global packages | `~/.clew/taste1/packages/` |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/taste1` | Show status panel |
+| `/taste1 status` | Print status |
+| `/taste1 learn <rule>` | Add a manual rule |
+| `/taste1 forget <id>` | Remove a rule by ID |
+| `/taste1 profile` | Show full profile with rules |
+| `/taste1 events` | Show recent learning events |
+| `/taste1 decay` | Apply confidence decay |
+| `/taste1 eval` | Run profile self-evaluation |
+| `/taste1 export` | Export high-confidence rules |
+| `/taste1 import <file>` | Import rules from file |
+| `/taste1 on` | Enable taste-1 |
+| `/taste1 off` | Disable taste-1 |
+
+## Configuration
+
+Settings in `settings.json`:
+
+```json
+{
+  "taste1": {
+    "enabled": true,
+    "autoLearn": true,
+    "injectPrompts": true,
+    "validateEdits": true,
+    "minConfidence": 0.55,
+    "maxInjectedRules": 8,
+    "decayEnabled": true,
+    "banditEnabled": true,
+    "neuralScoringEnabled": true
+  }
+}
+```
+
+## Architecture
+
+Clew taste-1 consists of several subsystems:
+
+1. **Signal Collection** — Captures accept, reject, edit, test, lint, and tool signals from
+   user interactions and converts them into learning events.
+
+2. **Reward Model** — Maps signal types to numeric reward values (accept = +1.0, reject = -1.0,
+   test pass = +0.4, etc.) and computes edit distance rewards dynamically.
+
+3. **Symbolic Engine** — Compiles high-confidence rules into checkable constraints.
+   Rules with confidence >= 0.85 can block edit acceptance. Rules below
+   threshold warn without blocking. Never blocks silently.
+
+4. **Neural Scorer** — Provider-agnostic lexical similarity scoring (Jaccard/TF-IDF)
+   that scores candidate output against active rules. Extensible to use
+   embedding APIs when available.
+
+5. **Contextual Bandit** — Epsilon-greedy bandit with 6 strategy arms (minimal,
+   strict_style, architecture_first, test_first, safety_first, refactor_heavy).
+   Selects optimal strategy based on feedback and context features.
+
+6. **Prompt Injection** — Injects a compact `<clew_taste1>` block into the system
+   prompt with relevant rules. Max 8 rules by default, filtered by confidence
+   and sorted by relevance.
+
+7. **Decay Engine** — Gradual confidence reduction for unused rules (half-life
+   based, default 30 days). Prevents stale preferences from persisting.
+
+8. **Event Log** — Append-only JSONL file storing all raw learning events for
+   auditability and regression analysis.
+
+## Continuous RL (Local Online Preference Optimization)
+
+Clew taste-1 implements **local online preference optimization**:
+
+- **Online**: learns continuously from each interaction, no batch training
+- **Local**: all computation and storage stays on the user's machine
+- **Preference-based**: optimizes for user preferences via reward signals
+- **Multi-objective**: balances style, correctness, safety, and efficiency
+
+The learning loop:
+
+1. User interacts with ClewCode (accepts, rejects, edits output)
+2. Signal collector captures the interaction as a typed event with reward
+3. Bandit arm updates based on reward signal
+4. Rule confidence adjusts based on positive/negative evidence
+5. Prompt injection adapts to reflect current learned preferences
+6. Decay gradually reduces stale rule confidence
+
+This is **not** LLM fine-tuning. The base model's weights never change.
+taste-1 adapts the prompt context and edit validation, not the model itself.
+
+## Privacy
+
+- All taste data stays local by default
+- Profiles and event logs are stored in `.clew/taste1/` or `~/.clew/taste1/`
+- No data is sent to remote services
+- Export/import is explicit and user-initiated
+- Event logs are append-only for auditability
+
+## Integration Points
+
+| Point | Status | Description |
+|-------|--------|-------------|
+| Prompt injection | Implemented | System prompt taste block via `TastePromptInjector` |
+| Edit validation | No-op stub | Ready for `PreAcceptEdit` hook wiring |
+| Accept/reject signals | No-op stub | Ready for tool approval flow wiring |
+| Test/lint signals | No-op stub | Ready for `PostToolUse` output analysis |
+| Tool result signals | No-op stub | Ready for `PostToolUse` hook wiring |
+| Settings config | Implemented | `taste1.*` in `settings.json` |
+
+## Example Usage
+
+```
+/taste1 learn Use const instead of let
+/taste1 learn Prefer named exports
+/taste1 learn Never use any type
+/taste1 status
+/taste1 profile
+/taste1 eval
+/taste1 export
+```

package/docs/tools.html

@@ -0,0 +1,168 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Tools — Clew</title>
+  <meta name="description" content="Complete reference for built-in tools in Clew — file operations, shell, search, agents, MCP, and automation.">
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="css/styles.css">
+</head>
+<body>
+<header class="header"><div class="header-inner"><a href="index.html" class="logo"><span>Clew</span></a><nav class="header-nav"><a href="index.html">Home</a><a href="index.html#features">Features</a><a href="index.html#commands">Commands</a><a href="quick-start.html" class="active">Docs</a><a href="https://github.com/JonusNattapong/ClewCode" target="_blank">GitHub</a></nav><button class="menu-btn" id="menuToggle" aria-label="Toggle navigation"><span></span><span></span><span></span></button></div></header>
+<div class="app"><aside class="sidebar" id="sidebar"></aside><div class="sidebar-overlay" id="sidebarOverlay"></div>
+<div class="content-wrap"><main class="content">
+  <div class="breadcrumbs"><a href="index.html">Home</a><span class="sep">/</span><span>Tools</span></div>
+  <h1>Tools</h1>
+  <p class="section-subtitle">Clew provides 50+ built-in tools plus dynamically loaded MCP tools. Tools are invoked by the AI model via <code>tool_use</code> blocks and executed through the <strong>StreamingToolExecutor</strong> with permission gating.</p>
+
+  <h2>How Tools Work</h2>
+  <p>Tools are defined with Zod schemas in <code>src/Tool.ts</code> via the <code>buildTool()</code> helper and registered in <code>src/tools.ts</code>. Each tool declares its input schema, output schema, concurrency safety, read-only status, and permission requirements.</p>
+
+  <pre><code>Model emits tool_use
+  Tool call normalization (toolCallParser.ts)
+  Permission check (permissions.ts)
+  PreToolUse hooks (plugins)
+  Tool execution (StreamingToolExecutor)
+  PostToolUse hooks (plugins)
+  Result returned as tool_result
+  Query loop continues</code></pre>
+
+  <h2>File &amp; Code Operations</h2>
+  <table>
+    <tr><th>Tool</th><th>Description</th><th>Schemas</th></tr>
+    <tr><td><code>Read</code> (FileReadTool)</td><td>Read files with line numbers, supports images, PDFs, Jupyter notebooks</td><td>Zod</td></tr>
+    <tr><td><code>Write</code> (FileWriteTool)</td><td>Create new files with full content</td><td>Zod</td></tr>
+    <tr><td><code>Edit</code> (FileEditTool)</td><td>Exact string replacement edits (surgical, diff-based)</td><td>Zod</td></tr>
+    <tr><td><code>Glob</code> (GlobTool)</td><td>Fast file pattern matching, sorted by modification time</td><td>Zod</td></tr>
+    <tr><td><code>Grep</code> (GrepTool)</td><td>Regex content search with context lines and multiline support</td><td>Zod</td></tr>
+    <tr><td><code>NotebookEdit</code> (NotebookEditTool)</td><td>Edit Jupyter notebook cells (replace, insert, delete)</td><td>Zod</td></tr>
+    <tr><td><code>JsonPath</code> (JsonPathTool)</td><td>Query, validate, format, and transform JSON data</td><td>Zod</td></tr>
+  </table>
+
+  <h2>Shell &amp; System</h2>
+  <table>
+    <tr><th>Tool</th><th>Description</th></tr>
+    <tr><td><code>Bash</code> (BashTool)</td><td>Execute shell commands with timeout, background, sandbox support, and permission gating</td></tr>
+    <tr><td><code>PowerShell</code> (PowerShellTool)</td><td>PowerShell execution on Windows (feature-gated)</td></tr>
+    <tr><td><code>Monitor</code> (MonitorTool)</td><td>Stream stdout/stderr from background tasks in real-time</td></tr>
+    <tr><td><code>TaskOutput</code> (TaskOutputTool)</td><td>Get output from running or completed tasks</td></tr>
+    <tr><td><code>TaskStop</code> (TaskStopTool)</td><td>Stop running background tasks</td></tr>
+  </table>
+
+  <h2>Search &amp; Web</h2>
+  <table>
+    <tr><th>Tool</th><th>Description</th></tr>
+    <tr><td><code>WebSearch</code> (WebSearchTool)</td><td>Multi-provider web search (Tavily, Brave, Serper, SearXNG, DuckDuckGo)</td></tr>
+    <tr><td><code>WebFetch</code> (WebFetchTool)</td><td>Fetch and analyze content from specific URLs</td></tr>
+    <tr><td><code>SessionSearch</code> (SessionSearchTool)</td><td>Full-text search across past session transcripts</td></tr>
+    <tr><td><code>CodeIndex</code> (CodeIndexTool)</td><td>Fuzzy code search across indexed codebase (feature-gated: CODE_INDEX)</td></tr>
+    <tr><td><code>ToolSearch</code> (ToolSearchTool)</td><td>Keyword search for deferred/lazy-loaded tools</td></tr>
+  </table>
+
+  <h2>Browser &amp; Automation</h2>
+  <table>
+    <tr><th>Tool</th><th>Description</th></tr>
+    <tr><td><code>Browser</code> (BrowserTool)</td><td>Stealth Playwright browser — navigate, click, type, screenshot, extract, fill forms</td></tr>
+    <tr><td><code>ComputerUse</code> (ComputerUseTool)</td><td>Windows-only computer use automation (feature-gated: ENABLE_COMPUTER_USE)</td></tr>
+  </table>
+
+  <h2>Agent &amp; Task Management</h2>
+  <table>
+    <tr><th>Tool</th><th>Description</th></tr>
+    <tr><td><code>Skill</code> (SkillTool)</td><td>Invoke skills and prompt-type commands by name</td></tr>
+    <tr><td><code>AskUserQuestion</code> (AskUserQuestionTool)</td><td>Ask the user interactive questions during execution</td></tr>
+    <tr><td><code>SendMessage</code> (SendMessageTool)</td><td>Send messages between agents in coordinator mode</td></tr>
+    <tr><td><code>EnterPlanMode</code> (EnterPlanModeTool)</td><td>Enter structured plan mode for complex tasks</td></tr>
+    <tr><td><code>ExitPlanMode</code> (ExitPlanModeV2Tool)</td><td>Exit plan mode and proceed with implementation</td></tr>
+    <tr><td><code>EnterWorktree / ExitWorktree</code></td><td>Create/exit isolated git worktrees (feature-gated)</td></tr>
+    <tr><td><code>TaskCreate / TaskGet / TaskUpdate / TaskList</code></td><td>Structured task tracking (V2 todo system)</td></tr>
+    <tr><td><code>TodoWrite</code> (TodoWriteTool)</td><td>Write todo items for task tracking</td></tr>
+    <tr><td><code>Config</code> (ConfigTool)</td><td>Configuration management (ant-only)</td></tr>
+    <tr><td><code>Brief</code> (BriefTool)</td><td>Generate brief summaries</td></tr>
+  </table>
+
+  <h2>Scheduled Tasks</h2>
+  <p>Scheduled tasks can be created from the interactive <code>/task</code> form. The form collects a name, project, schedule type, prompt, and storage mode, then creates the matching cron task through the same scheduling runtime used by <code>CronCreate</code>, <code>CronList</code>, and <code>CronDelete</code>.</p>
+
+  <table>
+    <tr><th>User action</th><th>Behavior</th></tr>
+    <tr><td><code>/task</code></td><td>Open the interactive scheduled task form</td></tr>
+    <tr><td>Select <code>Daily</code> around <code>09:00</code></td><td>Create a recurring daily task</td></tr>
+    <tr><td>Select <code>Weekdays</code> around <code>09:00</code></td><td>Create a weekday cron such as <code>0 9 * * 1-5</code></td></tr>
+    <tr><td>Select <code>In N minutes</code> with <code>10</code></td><td>Create a one-shot reminder</td></tr>
+    <tr><td>Select <code>Custom cron</code></td><td>Use a standard 5-field cron expression</td></tr>
+    <tr><td><code>/task scheduled</code></td><td>Open the same form explicitly</td></tr>
+  </table>
+
+  <ul>
+    <li><strong>Durable</strong> storage persists tasks to <code>.claude/scheduled_tasks.json</code> across sessions.</li>
+    <li><strong>Session-only</strong> storage keeps tasks in memory for the current session only.</li>
+    <li>Recurring tasks auto-expire after 30 days unless they are system-created permanent tasks.</li>
+    <li>One-shot tasks auto-delete after firing.</li>
+    <li>Natural language scheduling can still use the model-facing cron tools directly.</li>
+  </ul>
+
+  <pre><code>/task
+Name: Server status
+Schedule: Daily
+Time: 20:00
+Prompt: Check the server status
+Storage: Durable</code></pre>
+
+  <h2>MCP (Model Context Protocol)</h2>
+  <table>
+    <tr><th>Tool</th><th>Description</th></tr>
+    <tr><td><code>ListMcpResources</code> (ListMcpResourcesTool)</td><td>List available resources from connected MCP servers</td></tr>
+    <tr><td><code>ReadMcpResource</code> (ReadMcpResourceTool)</td><td>Read resources exposed by MCP servers</td></tr>
+    <tr><td>MCP-provided tools</td><td>Dynamically loaded tools from MCP servers (filesystem, database, APIs)</td></tr>
+  </table>
+
+  <h2>Feature-Gated Tools</h2>
+  <table>
+    <tr><th>Tool</th><th>Flag</th><th>Description</th></tr>
+    <tr><td><code>LSP</code> (LSPTool)</td><td><code>ENABLE_LSP_TOOL=1</code></td><td>Language Server Protocol integration</td></tr>
+    <tr><td><code>ComputerUse</code></td><td><code>ENABLE_COMPUTER_USE=1</code> (Win)</td><td>Windows GUI automation</td></tr>
+    <tr><td><code>CodeIndex</code></td><td><code>CODE_INDEX</code> feature</td><td>Fuzzy code search</td></tr>
+    <tr><td><code>EnterWorktree / ExitWorktree</code></td><td>Worktree mode</td><td>Git worktree isolation</td></tr>
+    <tr><td><code>TeamCreate / TeamDelete / RequestShutdown</code></td><td>Agent swarms</td><td>Multi-agent team management</td></tr>
+    <tr><td><code>SubscribePrActivity / UnsubscribePrActivity</code></td><td>Agent swarms</td><td>PR activity monitoring</td></tr>
+    <tr><td><code>CronCreate / CronDelete / CronList</code></td><td><code>AGENT_TRIGGERS</code></td><td>Scheduled task triggers</td></tr>
+    <tr><td><code>PushNotification</code></td><td><code>KAIROS</code></td><td>Push notification support</td></tr>
+  </table>
+
+  <h2>Tool Safety &amp; Permissions</h2>
+  <p>Each tool declares:</p>
+  <ul>
+    <li><strong>isEnabled()</strong> — Whether the tool is available in the current build</li>
+    <li><strong>isConcurrencySafe()</strong> — Can run in parallel with other tools</li>
+    <li><strong>isReadOnly()</strong> — Does not modify filesystem</li>
+    <li><strong>isDestructive()</strong> — Performs irreversible operations</li>
+    <li><strong>checkPermissions()</strong> — Tool-specific permission logic</li>
+    <li><strong>validateInput()</strong> — Input validation before execution</li>
+    <li><strong>maxResultSizeChars</strong> — Max result size before disk persistence</li>
+  </ul>
+
+  <p>MCP tools from external servers are merged into the tool pool at runtime via <code>assembleToolPool()</code>. Tools are filtered by deny rules from the permission context.</p>
+
+  <div class="callout callout-info">
+    <strong>CLAUDE_CODE_SIMPLE mode</strong>
+    Setting <code>CLAUDE_CODE_SIMPLE=1</code> or using <code>--bare</code> limits tools to a minimal set: <code>Bash</code>, <code>Read</code>, <code>Edit</code>.
+  </div>
+
+  <footer class="footer">
+    <span>Clew v0.1.2 — Open Source</span>
+    <div class="footer-links">
+      <a href="https://github.com/JonusNattapong/ClewCode">GitHub</a>
+      <a href="https://github.com/JonusNattapong/ClewCode/issues">Issues</a>
+    </div>
+  </footer>
+</main>
+<nav class="toc-sidebar"></nav>
+</div>
+</div>
+<script src="js/main.js"></script>
+</body>
+</html>

package/docs/troubleshooting.html

@@ -0,0 +1,104 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Troubleshooting — Clew</title>
+  <meta name="description" content="Common issues and solutions for Clew — provider keys, build errors, MCP, plugins, and runtime problems.">
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="css/styles.css">
+</head>
+<body>
+<header class="header"><div class="header-inner"><a href="index.html" class="logo"><span>Clew</span></a><nav class="header-nav"><a href="index.html">Home</a><a href="index.html#features">Features</a><a href="index.html#commands">Commands</a><a href="quick-start.html" class="active">Docs</a><a href="https://github.com/JonusNattapong/ClewCode" target="_blank">GitHub</a></nav><button class="menu-btn" id="menuToggle" aria-label="Toggle navigation"><span></span><span></span><span></span></button></div></header>
+<div class="app"><aside class="sidebar" id="sidebar"></aside><div class="sidebar-overlay" id="sidebarOverlay"></div>
+<div class="content-wrap"><main class="content">
+  <div class="breadcrumbs"><a href="index.html">Home</a><span class="sep">/</span><span>Troubleshooting</span></div>
+  <h1>Troubleshooting</h1>
+  <p class="section-subtitle">Start with <code>/doctor</code> — it checks runtime version, provider credentials, config integrity, plugin/MCP status, and Sentry telemetry.</p>
+
+  <h2>Startup Issues</h2>
+  <h3>"command not found: clew"</h3>
+  <p>npm global install path may not be in <code>PATH</code>. Use <code>npx clew-code</code> or <code>bun x clew-code</code> as alternatives.</p>
+
+  <h3>"Bun not found"</h3>
+  <p>Clew requires <a href="https://bun.sh">Bun 1.3+</a> as the runtime for the npm package.</p>
+
+  <h2>Provider Issues</h2>
+
+  <h3>"No API key configured"</h3>
+  <p>Set at least one provider API key as an environment variable. See <a href="providers.html">Providers</a> for the full list.</p>
+  <pre><code>export ANTHROPIC_API_KEY=sk-ant-...
+export DEEPSEEK_API_KEY=sk-...</code></pre>
+  <p>Run <code>/doctor</code> to verify configured providers.</p>
+
+  <h3>"Rate limited" or "Quota exceeded"</h3>
+  <p>Set a fallback model via CLI: <code>--fallback-model &lt;model&gt;</code>. Or use <code>/model</code> to switch to a different provider. For rate limit options during a session, use <code>/rate-limit-options</code>.</p>
+
+  <h2>Build Issues</h2>
+
+  <h3>TypeScript errors during build</h3>
+  <pre><code>bun run build
+# TypeScript errors may exist in uncommitted code or external modules.
+# Run targeted checks:
+bun x tsc --noEmit
+bun test <targeted-path></code></pre>
+
+  <h3>Windows-specific issues</h3>
+  <ul>
+    <li>ripgrep is bundled at <code>src/utils/vendor/ripgrep/x64-win32/rg.exe</code></li>
+    <li>TTY polyfill may be needed for Ink compatibility</li>
+    <li>PowerShell and Bash may behave differently for tool execution</li>
+    <li>Windows argv normalization in <code>src/entry.ts</code></li>
+  </ul>
+
+  <h2>MCP Issues</h2>
+
+  <h3>"MCP server connection failed"</h3>
+  <p>Verify the server command exists and paths are correct. Check JSON config syntax with <code>/mcp</code> command.</p>
+
+  <h3>MCP tools not appearing</h3>
+  <p>Use <code>/mcp</code> to check server status. Tools are loaded at startup via <code>--mcp-config</code> or through <code>assembleToolPool()</code> during server connection. Verify the server implements <code>tools/list</code> correctly.</p>
+
+  <h2>Plugin Issues</h2>
+
+  <h3>Plugin not loading</h3>
+  <p>Check plugin manifest format and location. Use <code>/plugin</code> and <code>/reload-plugins</code> to refresh. For directory-based plugins, use <code>--plugin-dir &lt;path&gt;</code>.</p>
+
+  <h2>Feature Flags</h2>
+  <p>Some features require compile-time or runtime flags:</p>
+  <table>
+    <tr><th>Feature</th><th>Required Flag</th></tr>
+    <tr><td>Bridge mode</td><td><code>BRIDGE_MODE=1</code></td></tr>
+    <tr><td>Voice mode</td><td><code>VOICE_MODE=1</code></td></tr>
+    <tr><td>LSP tool</td><td><code>ENABLE_LSP_TOOL=1</code></td></tr>
+    <tr><td>Computer Use</td><td><code>ENABLE_COMPUTER_USE=1</code> (Windows)</td></tr>
+    <tr><td>Proactive features</td><td><code>KAIROS=1</code></td></tr>
+    <tr><td>Agent triggers</td><td><code>AGENT_TRIGGERS=1</code></td></tr>
+    <tr><td>Code index</td><td><code>CODE_INDEX=1</code></td></tr>
+  </table>
+
+  <h2>Getting Help</h2>
+  <ul>
+    <li><strong>In-app diagnostics:</strong> <code>/doctor</code> — comprehensive environment check</li>
+    <li><strong>Status overview:</strong> <code>/status</code> — version, model, API connectivity, tool statuses</li>
+    <li><strong>GitHub Issues:</strong> Report bugs and feature requests</li>
+    <li><strong>Debug mode:</strong> Run with <code>DEBUG=1</code> or <code>DEBUG=provider:anthropic</code> for detailed logging</li>
+  </ul>
+
+  <footer class="footer">
+    <span>Clew v0.1.2 — Open Source</span>
+    <div class="footer-links">
+      <a href="https://github.com/JonusNattapong/ClewCode">GitHub</a>
+      <a href="https://github.com/JonusNattapong/ClewCode/issues">Issues</a>
+      <a href="https://npmjs.com/package/clew-code">npm</a>
+    </div>
+  </footer>
+</main>
+<nav class="toc-sidebar"></nav>
+</div>
+</div>
+<script src="js/main.js"></script>
+</body>
+</html>