clew-code 0.2.28 → 0.2.30

package/scripts/comment-on-duplicates.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+#
+# Comments on a GitHub issue with a list of potential duplicates.
+# Usage: ./comment-on-duplicates.sh --potential-duplicates 456 789 101
+#
+# The base issue number is read from the workflow event payload.
+#
+
+set -euo pipefail
+
+REPO="JonusNattapong/ClaudeCode"
+
+# Read from event payload so the issue number is bound to the triggering event.
+# Falls back to workflow_dispatch inputs for manual runs.
+BASE_ISSUE=$(jq -r '.issue.number // .inputs.issue_number // empty' "${GITHUB_EVENT_PATH:?GITHUB_EVENT_PATH not set}")
+if ! [[ "$BASE_ISSUE" =~ ^[0-9]+$ ]]; then
+  echo "Error: no issue number in event payload" >&2
+  exit 1
+fi
+
+DUPLICATES=()
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --potential-duplicates)
+      shift
+      while [[ $# -gt 0 && ! "$1" =~ ^-- ]]; do
+        DUPLICATES+=("$1")
+        shift
+      done
+      ;;
+    *)
+      echo "Error: unknown argument (only --potential-duplicates is accepted)" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Validate duplicates
+if [[ ${#DUPLICATES[@]} -eq 0 ]]; then
+  echo "Error: --potential-duplicates requires at least one issue number" >&2
+  exit 1
+fi
+
+if [[ ${#DUPLICATES[@]} -gt 3 ]]; then
+  echo "Error: --potential-duplicates accepts at most 3 issues" >&2
+  exit 1
+fi
+
+for dup in "${DUPLICATES[@]}"; do
+  if ! [[ "$dup" =~ ^[0-9]+$ ]]; then
+    echo "Error: duplicate issue must be a number, got: $dup" >&2
+    exit 1
+  fi
+done
+
+# Validate that base issue exists
+if ! gh issue view "$BASE_ISSUE" --repo "$REPO" &>/dev/null; then
+  echo "Error: issue #$BASE_ISSUE does not exist in $REPO" >&2
+  exit 1
+fi
+
+# Validate that all duplicate issues exist
+for dup in "${DUPLICATES[@]}"; do
+  if ! gh issue view "$dup" --repo "$REPO" &>/dev/null; then
+    echo "Error: issue #$dup does not exist in $REPO" >&2
+    exit 1
+  fi
+done
+
+# Build comment body
+COUNT=${#DUPLICATES[@]}
+if [[ $COUNT -eq 1 ]]; then
+  HEADER="Found 1 possible duplicate issue:"
+else
+  HEADER="Found $COUNT possible duplicate issues:"
+fi
+
+BODY="$HEADER"$'\n\n'
+INDEX=1
+for dup in "${DUPLICATES[@]}"; do
+  BODY+="$INDEX. https://github.com/$REPO/issues/$dup"$'\n'
+  ((INDEX++))
+done
+
+BODY+=$'\n'"This issue will be automatically closed as a duplicate in 3 days."$'\n\n'
+BODY+="- If your issue is a duplicate, please close it and 👍 the existing issue instead"$'\n'
+BODY+="- To prevent auto-closure, add a comment or 👎 this comment"$'\n\n'
+BODY+="🤖 Generated with [Claude Code](https://claude.ai/code)"
+
+# Post the comment
+gh issue comment "$BASE_ISSUE" --repo "$REPO" --body "$BODY"
+
+echo "Posted duplicate comment on issue #$BASE_ISSUE"

package/scripts/edit-issue-labels.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+#
+# Edits labels on a GitHub issue.
+# Usage: ./edit-issue-labels.sh --add-label bug --add-label needs-triage --remove-label untriaged
+#
+# The issue number is read from the workflow event payload.
+#
+
+set -euo pipefail
+
+# Read from event payload so the issue number is bound to the triggering event.
+# Falls back to workflow_dispatch inputs for manual runs.
+ISSUE=$(jq -r '.issue.number // .inputs.issue_number // empty' "${GITHUB_EVENT_PATH:?GITHUB_EVENT_PATH not set}")
+if ! [[ "$ISSUE" =~ ^[0-9]+$ ]]; then
+  echo "Error: no issue number in event payload" >&2
+  exit 1
+fi
+
+ADD_LABELS=()
+REMOVE_LABELS=()
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --add-label)
+      ADD_LABELS+=("$2")
+      shift 2
+      ;;
+    --remove-label)
+      REMOVE_LABELS+=("$2")
+      shift 2
+      ;;
+    *)
+      echo "Error: unknown argument (only --add-label and --remove-label are accepted)" >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [[ ${#ADD_LABELS[@]} -eq 0 && ${#REMOVE_LABELS[@]} -eq 0 ]]; then
+  exit 1
+fi
+
+# Fetch valid labels from the repo
+VALID_LABELS=$(gh label list --limit 500 --json name --jq '.[].name')
+
+# Filter to only labels that exist in the repo
+FILTERED_ADD=()
+for label in "${ADD_LABELS[@]}"; do
+  if echo "$VALID_LABELS" | grep -qxF "$label"; then
+    FILTERED_ADD+=("$label")
+  fi
+done
+
+FILTERED_REMOVE=()
+for label in "${REMOVE_LABELS[@]}"; do
+  if echo "$VALID_LABELS" | grep -qxF "$label"; then
+    FILTERED_REMOVE+=("$label")
+  fi
+done
+
+if [[ ${#FILTERED_ADD[@]} -eq 0 && ${#FILTERED_REMOVE[@]} -eq 0 ]]; then
+  exit 0
+fi
+
+# Build gh command arguments
+GH_ARGS=("issue" "edit" "$ISSUE")
+
+for label in "${FILTERED_ADD[@]}"; do
+  GH_ARGS+=("--add-label" "$label")
+done
+
+for label in "${FILTERED_REMOVE[@]}"; do
+  GH_ARGS+=("--remove-label" "$label")
+done
+
+gh "${GH_ARGS[@]}"
+
+if [[ ${#FILTERED_ADD[@]} -gt 0 ]]; then
+  echo "Added: ${FILTERED_ADD[*]}"
+fi
+if [[ ${#FILTERED_REMOVE[@]} -gt 0 ]]; then
+  echo "Removed: ${FILTERED_REMOVE[*]}"
+fi

package/scripts/final-peer-rename.mjs

@@ -0,0 +1,46 @@
+const fs = require('fs');
+const path = require('path');
+
+function walk(dir) {
+  const r = [];
+  for (const e of fs.readdirSync(dir, {withFileTypes:true})) {
+    const f = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (!e.name.startsWith('.') && e.name !== 'node_modules' && e.name !== 'dist') r.push(...walk(f));
+    } else if (e.name.endsWith('.ts') || e.name.endsWith('.tsx')) r.push(f);
+  }
+  return r;
+}
+
+const files = walk('src');
+let count = 0;
+for (const f of files) {
+  let c = fs.readFileSync(f, 'utf-8');
+  const orig = c;
+
+  c = c.replace(/\/peer\//g, '/swarm/');
+  c = c.replace(/\bPeer(Broadcast|Disconnect|Discover|Join|ListMessages|ListRoles|Ping|Run|SendMessage|SetName|SetRole|Share|Spawn|Info|Help|Server|Store|Discovery|StatusLine|Type)Tool\b/g, 'Swarm$1Tool');
+  c = c.replace(/\bPeer(Broadcast|Disconnect|Discover|Join|ListMessages|ListRoles|Ping|Run|SendMessage|SetName|SetRole|Share|Spawn|Info|Help|Server|Store|Discovery|StatusLine|Type)\b/g, 'Swarm$1');
+  c = c.replace(/\bProcessPeer(Provider|Tool)/g, 'ProcessSwarm$1');
+  c = c.replace(/\bCodexPeer/g, 'CodexSwarm');
+  c = c.replace(/\bgetProcessPeerProvider\b/g, 'getProcessSwarmProvider');
+  c = c.replace(/\bgetProcessPeerProviderIds\b/g, 'getProcessSwarmProviderIds');
+  c = c.replace(/\bmyPeerId\b/g, 'mySwarmId');
+  c = c.replace(/\bpeerId\b/g, 'swarmId');
+  c = c.replace(/\bPEER_(\w+)_TOOL_NAME\b/g, 'SWARM_$1_TOOL_NAME');
+  c = c.replace(/\bpeer(Server|Store|Discovery|Port|Name|Info|List|Count|Connection|Sharing|Health)\b/g, 'swarm$1');
+  c = c.replace(/\bgetGlobalPeer(Server|Store)\b/g, 'getGlobalSwarm$1');
+  c = c.replace(/\bnotifyPeerFeedback\b/g, 'notifySwarmFeedback');
+  c = c.replace(/\bsetPeerFeedbackHandler\b/g, 'setSwarmFeedbackHandler');
+  c = c.replace(/\bPeerFeedback\b/g, 'SwarmFeedback');
+  c = c.replace(/\bpeer-feedback/g, 'swarm-feedback');
+  c = c.replace(/\bpeerFeedback/g, 'swarmFeedback');
+  c = c.replace(/\/peer\b/g, '/swarm');
+  c = c.replace(/['"]peer-/g, (m) => m.replace('peer-', 'swarm-'));
+  c = c.replace(/\bspawnPeerTerminal\b/g, 'spawnSwarmTerminal');
+  c = c.replace(/\bparseProcessPeerRunArgs\b/g, 'parseProcessSwarmRunArgs');
+  c = c.replace(/\bProcessPeerRunArgs\b/g, 'ProcessSwarmRunArgs');
+
+  if (c !== orig) { fs.writeFileSync(f, c, 'utf-8'); count++; }
+}
+console.log('Updated:', count, 'files');

package/scripts/fix-encoding.mjs

@@ -0,0 +1,83 @@
+/**
+ * Fix mojibake encoding in all docs HTML files.
+ *
+ * Problem: Files were double-encoded — original UTF-8 bytes were
+ * misinterpreted as CP1252 then re-encoded as UTF-8, producing
+ * characters like — instead of — and ค instead of ค.
+ *
+ * This script reverses the damage by mapping each Unicode char
+ * back to its CP1252 byte and re-decoding as UTF-8.
+ * Legitimate Unicode characters (Thai, arrows, emoji) pass through.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const cp1252 = new Map([
+  [0x20ac, 0x80], [0x201a, 0x82], [0x0192, 0x83], [0x201e, 0x84],
+  [0x2026, 0x85], [0x2020, 0x86], [0x2021, 0x87], [0x02c6, 0x88],
+  [0x2030, 0x89], [0x0160, 0x8a], [0x2039, 0x8b], [0x0152, 0x8c],
+  [0x017d, 0x8e], [0x2018, 0x91], [0x2019, 0x92], [0x201c, 0x93],
+  [0x201d, 0x94], [0x2022, 0x95], [0x2013, 0x96], [0x2014, 0x97],
+  [0x02dc, 0x98], [0x2122, 0x99], [0x0161, 0x9a], [0x203a, 0x9b],
+  [0x0153, 0x9c], [0x017e, 0x9e], [0x0178, 0x9f],
+]);
+
+function fixMojibake(text) {
+  if (text.charCodeAt(0) === 0xfeff) text = text.slice(1); // strip BOM
+
+  const bytes = [];
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (code <= 0xff) {
+      bytes.push(code);
+    } else if (cp1252.has(code)) {
+      bytes.push(cp1252.get(code));
+    } else {
+      const buf = Buffer.from(text[i], 'utf-8');
+      for (const b of buf) bytes.push(b);
+    }
+  }
+  return Buffer.from(bytes).toString('utf-8');
+}
+
+// Walk docs/ recursively
+function walk(dir) {
+  const results = [];
+  const list = fs.readdirSync(dir);
+  for (const entry of list) {
+    const full = path.join(dir, entry);
+    const stat = fs.statSync(full);
+    if (stat.isDirectory()) {
+      results.push(...walk(full));
+    } else if (entry.endsWith('.html')) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+const files = walk('docs');
+let changed = 0;
+let errors = 0;
+
+for (const f of files) {
+  try {
+    const content = fs.readFileSync(f, 'utf-8');
+    const fixed = fixMojibake(content);
+
+    // skip if no change
+    if (fixed === content) {
+      console.log(`  ✓  ${f} — already clean`);
+      continue;
+    }
+
+    fs.writeFileSync(f, fixed, 'utf-8');
+    console.log(`  ✔  ${f}`);
+    changed++;
+  } catch (err) {
+    console.error(`  ✘  ${f}: ${err.message}`);
+    errors++;
+  }
+}
+
+console.log(`\nDone: ${changed} files fixed, ${errors} errors`);

package/scripts/fix-inconsistencies.mjs

@@ -0,0 +1,67 @@
+/**
+ * Normalize all HTML files to consistent structure:
+ * - Empty header (JS-injected)
+ * - main.js script at end of body
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const docsDir = path.resolve(__dirname, '../docs');
+
+function walk(dir) {
+  const results = [];
+  const list = fs.readdirSync(dir);
+  for (const entry of list) {
+    const full = path.join(dir, entry);
+    const stat = fs.statSync(full);
+    if (stat.isDirectory()) results.push(...walk(full));
+    else if (entry.endsWith('.html')) results.push(full);
+  }
+  return results;
+}
+
+function relativePath(from, to) {
+  const rel = path.relative(path.dirname(from), to);
+  return rel.startsWith('.') ? rel : './' + rel;
+}
+
+const files = walk(docsDir);
+let fixed = 0;
+
+for (const filePath of files) {
+  let c = fs.readFileSync(filePath, 'utf-8');
+  const name = path.basename(filePath);
+
+  // Skip landing page (different structure by design)
+  if (name === 'index.html' || name === 'index.th.html') continue;
+
+  // Fix 1: Replace inline header with empty header
+  if (!c.includes('<header class="header"></header>')) {
+    c = c.replace(/<header class="header">[\s\S]*?<\/header>\s*/,
+      '<header class="header"></header>\n');
+  }
+
+  // Fix 2: Add main.js if missing
+  if (!c.includes('main.js')) {
+    const jsRelPath = relativePath(filePath, path.join(docsDir, 'js/main.js'));
+    c = c.replace('</body>', `<script src="${jsRelPath}"></script>\n</body>`);
+  }
+
+  // Fix 3: Ensure Google Fonts includes Noto Sans Thai for .th.html files
+  if (name.endsWith('.th.html') && !c.includes('Noto+Sans+Thai')) {
+    c = c.replace(
+      /family=JetBrains\+Mono:[^"'&]+/,
+      '$&, &family=Noto+Sans+Thai:wght@400;500;600;700'
+    );
+  }
+
+  // Fix 4: Clean up old lang-wrap styles in features/internals
+  c = c.replace(/<div class="lang-wrap">[\s\S]*?<\/div>\s*<\/div>\s*/, '');
+
+  fs.writeFileSync(filePath, c, 'utf-8');
+  fixed++;
+}
+
+console.log(`Normalized ${fixed} files`);

package/scripts/generate-docs.ts

@@ -0,0 +1,307 @@
+/**
+ * generate-docs.ts — Auto-generate HTML documentation from source code.
+ *
+ * Run: bun run scripts/generate-docs.ts
+ * Reads source data and writes to docs/generated/
+ *
+ * Currently generates:
+ * - providers.json  →  docs/generated/providers.html  (provider reference table)
+ * - tool prompts    →  docs/generated/tools.html       (tool reference with prompts)
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..');
+const SRC = join(ROOT, 'src');
+const DOCS = join(ROOT, 'docs');
+const OUT = join(DOCS, 'generated');
+
+if (!existsSync(OUT)) mkdirSync(OUT, { recursive: true });
+
+// ── Helpers ──
+
+function html( Title: string, body: string, description = ''): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${Title} — Clew</title>
+  <meta name="description" content="${description}">
+  <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">
+  <link rel="icon" type="image/svg+xml" href="../assets/clew.svg">
+</head>
+<body>
+<header class="header">
+  <div class="header-inner">
+    <a href="../index.html" class="logo"><span class="logo-mark">C</span><span>Clew Code</span></a>
+    <nav class="header-nav">
+      <a href="../index.html">Home</a>
+      <a href="../commands.html">Commands</a>
+      <a href="../tools.html">Tools</a>
+      <a href="../providers.html">Providers</a>
+      <a href="../prompts-and-features.html">Reference</a>
+      <a href="../quick-start.html">Docs</a>
+    </nav>
+  </div>
+</header>
+<div class="app">
+  <aside class="sidebar" id="sidebar">
+    <div class="sidebar-section">
+      <div class="sidebar-label">Generated Docs</div>
+      <a href="providers.html" class="sidebar-link"><span class="link-icon"></span>Providers</a>
+      <a href="tools.html" class="sidebar-link"><span class="link-icon"></span>Tools</a>
+    </div>
+    <div class="sidebar-section">
+      <div class="sidebar-label">Static Docs</div>
+      <a href="../commands.html" class="sidebar-link"><span class="link-icon"></span>Commands</a>
+      <a href="../tools.html" class="sidebar-link"><span class="link-icon"></span>Tools</a>
+      <a href="../providers.html" class="sidebar-link"><span class="link-icon"></span>Providers</a>
+    </div>
+  </aside>
+  <div class="sidebar-overlay"></div>
+  <div class="content-wrap"><main class="content">
+    <div class="breadcrumbs"><a href="../index.html">Home</a><span class="sep">/</span><span>${Title}</span></div>
+    <h1>${Title}</h1>
+    <p class="section-subtitle"><em>Auto-generated from source code. Last updated: ${new Date().toISOString().slice(0, 10)}.</em></p>
+    ${body}
+  </main></div>
+</div>
+</body>
+</html>`;
+}
+
+function cap(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// 1. GENERATE PROVIDERS
+// ═══════════════════════════════════════════════════════════════════════
+
+function generateProviders(): void {
+  const providers = JSON.parse(
+    readFileSync(join(SRC, 'services/ai/providers.json'), 'utf8'),
+  ) as Record<string, any>;
+
+  const CAP_KEYS: Record<string, string> = {
+    chat: 'Chat',
+    streaming: 'Streaming',
+    toolCalling: 'Tools',
+    vision: 'Vision',
+    jsonSchema: 'JSON Schema',
+    reasoningEffort: 'Reasoning',
+  };
+
+  let rows = '';
+  let detailSections = '';
+
+  for (const [id, p] of Object.entries(providers)) {
+    const caps = Object.entries(p.capabilities ?? {})
+      .filter(([, v]) => v === true || v === 'full' || v === 'native')
+      .map(([k]) => CAP_KEYS[k] ?? cap(k))
+      .join(', ') || '—';
+
+    const models = (p.models ?? []).map((m: any) => m.id).join(', ') || '—';
+
+    rows += `<tr>
+      <td><strong>${p.label}</strong></td>
+      <td><code>${p.envKey}</code></td>
+      <td>${p.defaultModel || '—'}</td>
+      <td style="font-size:0.75rem">${caps}</td>
+    </tr>`;
+
+    detailSections += `<details>
+      <summary><strong>${p.label}</strong> <code>${id}</code></summary>
+      <p>${p.note || 'No description.'}</p>
+      <table>
+        <tr><th>Property</th><th>Value</th></tr>
+        <tr><td>Provider ID</td><td><code>${id}</code></td></tr>
+        <tr><td>Env Key</td><td><code>${p.envKey}</code></td></tr>
+        <tr><td>Default Model</td><td>${p.defaultModel || '—'}</td></tr>
+        <tr><td>Base URL</td><td><code>${p.defaultBaseUrl}</code></td></tr>
+        <tr><td>Models URL</td><td>${p.modelsUrl ? `<code>${p.modelsUrl}</code>` : '—'}</td></tr>
+        <tr><td>Local</td><td>${p.isLocal ? '✅' : '—'}</td></tr>
+        <tr><td>Capabilities</td><td>${caps || '—'}</td></tr>
+      </table>
+      <p><strong>Models (${(p.models ?? []).length}):</strong> ${models}</p>
+    </details>`;
+  }
+
+  const body = `
+    <h2>All Providers</h2>
+    <p>Clew supports <strong>${Object.keys(providers).length} AI providers</strong>. Switch between them at runtime with <code>/model</code> or <code>/provider-select</code>.</p>
+    <div class="table-wrap"><table>
+      <tr><th>Provider</th><th>Env Key</th><th>Default Model</th><th>Capabilities</th></tr>
+      ${rows}
+    </table></div>
+
+    <h2>Provider Details</h2>
+    <div class="provider-group">${detailSections}</div>
+
+    <style>
+      .provider-group details {
+        background: var(--bg-card);
+        border: 1px solid var(--border-subtle);
+        border-radius: 8px;
+        padding: 0.75rem 1rem;
+        margin: 0.4rem 0;
+      }
+      .provider-group summary { cursor: pointer; font-weight: 600; font-size: var(--text-sm); }
+      .provider-group details p { margin: 0.75rem 0; font-size: var(--text-sm); color: var(--text-secondary); }
+      .provider-group details table { margin: 0.5rem 0; }
+    </style>
+  `;
+
+  writeFileSync(join(OUT, 'providers.html'), html(
+    'Providers (Auto-generated)',
+    body,
+    `Auto-generated provider reference for ${Object.keys(providers).length} AI providers in Clew Code.`,
+  ));
+  console.log(`✅ Generated providers.html (${Object.keys(providers).length} providers)`);
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// 2. GENERATE TOOLS
+// ═══════════════════════════════════════════════════════════════════════
+
+function generateTools(): void {
+  const TOOLS_DIR = join(SRC, 'tools');
+  const entries = existsSync(TOOLS_DIR) ? readFileSystem(TOOLS_DIR, 1) : [];
+
+  const toolEntries: Array<{ name: string; prompt: string; description: string }> = [];
+
+  for (const dir of entries) {
+    const promptPath = join(TOOLS_DIR, dir, 'prompt.ts');
+    if (!existsSync(promptPath)) continue;
+
+    const content = readFileSync(promptPath, 'utf8');
+
+    // Extract DESCRIPTION export
+    const descMatch = content.match(/export\s+const\s+DESCRIPTION\s*=\s*([`'"])(.+?)\1/s);
+    const description = descMatch ? descMatch[2] : '';
+
+    // Extract PROMPT export (multiline template literals)
+    let prompt = '';
+    const promptMatch = content.match(/export\s+const\s+PROMPT\s*=\s*`([\s\S]*?)`/);
+    if (promptMatch) {
+      prompt = promptMatch[1].trim();
+    }
+
+    // If no template literal, try string literal
+    if (!prompt) {
+      const strMatch = content.match(/export\s+const\s+PROMPT\s*=\s*['"](.+?)['"]/s);
+      if (strMatch) prompt = strMatch[1].trim();
+    }
+
+    toolEntries.push({
+      name: dir.replace(/Tool$/, ''),
+      prompt,
+      description: description || prompt.slice(0, 120),
+    });
+  }
+
+  toolEntries.sort((a, b) => a.name.localeCompare(b.name));
+
+  let rows = '';
+  let promptSections = '';
+
+  for (const t of toolEntries) {
+    const desc = t.description || `Built-in tool "${t.name}". See system prompt for details.`;
+    rows += `<tr><td><code>${t.name}</code></td><td>${escapeHtml(desc)}</td></tr>\n`;
+
+    if (t.prompt) {
+      promptSections += `<details>
+        <summary><code>${t.name}</code> — System Prompt</summary>
+        <div class="prompt-box">${escapeHtml(t.prompt)}</div>
+      </details>\n`;
+    }
+  }
+
+  const body = `
+    <h2>All Tools with Prompts</h2>
+    <p>Clew provides <strong>${toolEntries.length} tools</strong> with system prompts. These prompts are injected into the AI model's context at session start to define the tool interface.</p>
+    <div class="table-wrap"><table>
+      <tr><th>Tool</th><th>Description</th></tr>
+      ${rows}
+    </table></div>
+
+    <h2>Tool Prompts</h2>
+    <p>Each tool's system prompt, as seen by the AI model:</p>
+    <div class="tool-prompts">${promptSections}</div>
+
+    <style>
+      .tool-prompts details {
+        background: var(--bg-card);
+        border: 1px solid var(--border-subtle);
+        border-radius: 8px;
+        margin: 0.5rem 0;
+        padding: 0.75rem 1rem;
+      }
+      .tool-prompts summary { cursor: pointer; font-weight: 600; font-size: var(--text-sm); }
+      .prompt-box {
+        background: var(--code-bg);
+        border: 1px solid var(--code-border);
+        border-radius: 6px;
+        padding: 1rem;
+        margin: 0.75rem 0;
+        font-family: var(--font-mono);
+        font-size: var(--text-xs);
+        line-height: 1.6;
+        color: var(--code-text);
+        white-space: pre-wrap;
+        overflow-x: auto;
+      }
+    </style>
+  `;
+
+  writeFileSync(join(OUT, 'tools.html'), html(
+    'Tools & Prompts (Auto-generated)',
+    body,
+    `Auto-generated tool reference with ${toolEntries.length} system prompts for Clew Code.`,
+  ));
+  console.log(`✅ Generated tools.html (${toolEntries.length} tools with prompts)`);
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// UTILITIES
+// ═══════════════════════════════════════════════════════════════════════
+
+function readFileSystem(dir: string, depth: number): string[] {
+  const results: string[] = [];
+  const entries = existsSync(dir) ? readdirSync(dir) : [];
+  for (const entry of entries) {
+    const fullPath = join(dir, entry);
+    if (statSync(fullPath).isDirectory()) {
+      if (depth > 0) {
+        results.push(entry);
+      }
+    }
+  }
+  return results;
+}
+
+import { readdirSync, statSync } from 'node:fs';
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// MAIN
+// ═══════════════════════════════════════════════════════════════════════
+
+console.log('📄 Generating docs from source...\n');
+generateProviders();
+generateTools();
+console.log('\n✨ Done — outputs in docs/generated/');