@doquflow/cli 1.6.0 → 2.0.0

package/dist/commands/doctor.js

@@ -0,0 +1,270 @@
+"use strict";
+/**
+ * docuflow doctor
+ *
+ * Diagnostic command that reports installed DocuFlow packages, MCP server
+ * registrations, detected workflow, and actionable recommendations.
+ *
+ * Usage:
+ *   docuflow doctor            # human-readable report
+ *   docuflow doctor --json     # machine-readable JSON
+ *   docuflow doctor --quiet    # recommendations only
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+// ── Package version resolution ────────────────────────────────────────────────
+function resolvePackageVersion(pkgName) {
+    const candidates = [
+        () => require.resolve(`${pkgName}/package.json`),
+        () => node_path_1.default.resolve(__dirname, "../../../", pkgName.replace("@doquflow/", ""), "package.json"),
+        () => node_path_1.default.resolve(__dirname, "../../", pkgName.replace("@doquflow/", ""), "package.json"),
+    ];
+    for (const c of candidates) {
+        try {
+            const pkgPath = c();
+            const raw = node_fs_1.default.readFileSync(pkgPath, "utf8");
+            return JSON.parse(raw).version;
+        }
+        catch { /* try next */ }
+    }
+    return null;
+}
+function getInstalledPackages() {
+    const packages = ["@doquflow/cli", "@doquflow/core", "@doquflow/studio", "@doquflow/server"];
+    return packages.map(name => ({ name, version: resolvePackageVersion(name) }));
+}
+function getClaudeDesktopConfigPath() {
+    const p = process.platform;
+    if (p === "darwin")
+        return node_path_1.default.join(node_os_1.default.homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    if (p === "win32")
+        return node_path_1.default.join(node_os_1.default.homedir(), "AppData", "Roaming", "Claude", "claude_desktop_config.json");
+    return node_path_1.default.join(node_os_1.default.homedir(), ".config", "Claude", "claude_desktop_config.json");
+}
+function getMcpRegistrations(projectPath) {
+    const results = [];
+    // Project-level .mcp.json
+    const projectMcp = node_path_1.default.join(projectPath, ".mcp.json");
+    try {
+        const cfg = JSON.parse(node_fs_1.default.readFileSync(projectMcp, "utf8"));
+        const entry = cfg.mcpServers?.docuflow;
+        results.push({ source: ".mcp.json", registered: !!entry, command: entry?.command, args: entry?.args });
+    }
+    catch {
+        results.push({ source: ".mcp.json", registered: false });
+    }
+    // Claude Desktop
+    try {
+        const cfg = JSON.parse(node_fs_1.default.readFileSync(getClaudeDesktopConfigPath(), "utf8"));
+        const entry = cfg.mcpServers?.docuflow;
+        results.push({ source: "Claude Desktop", registered: !!entry, command: entry?.command, args: entry?.args });
+    }
+    catch {
+        results.push({ source: "Claude Desktop", registered: false });
+    }
+    // VS Code user MCP
+    const vscodePath = process.platform === "darwin"
+        ? node_path_1.default.join(node_os_1.default.homedir(), "Library", "Application Support", "Code", "User", "mcp.json")
+        : process.platform === "win32"
+            ? node_path_1.default.join(node_os_1.default.homedir(), "AppData", "Roaming", "Code", "User", "mcp.json")
+            : node_path_1.default.join(node_os_1.default.homedir(), ".config", "Code", "User", "mcp.json");
+    try {
+        const cfg = JSON.parse(node_fs_1.default.readFileSync(vscodePath, "utf8"));
+        const entry = cfg.servers?.docuflow;
+        results.push({ source: "VS Code (user)", registered: !!entry, command: entry?.command, args: entry?.args });
+    }
+    catch {
+        results.push({ source: "VS Code (user)", registered: false });
+    }
+    // Copilot CLI
+    const copilotPath = node_path_1.default.join(node_os_1.default.homedir(), ".copilot", "mcp-config.json");
+    try {
+        const cfg = JSON.parse(node_fs_1.default.readFileSync(copilotPath, "utf8"));
+        const entry = cfg.mcpServers?.docuflow;
+        results.push({ source: "Copilot CLI", registered: !!entry, command: entry?.command, args: entry?.args });
+    }
+    catch {
+        results.push({ source: "Copilot CLI", registered: false });
+    }
+    return results;
+}
+function detectWorkflow(projectPath) {
+    const docuDir = node_path_1.default.join(projectPath, ".docuflow");
+    const hasDocuflow = node_fs_1.default.existsSync(docuDir);
+    let hasSources = false;
+    let hasSpecs = false;
+    let hasQueryUsage = false;
+    let watchRunning = false;
+    if (hasDocuflow) {
+        try {
+            hasSources = node_fs_1.default.readdirSync(node_path_1.default.join(docuDir, "sources")).some(f => f.endsWith(".md"));
+        }
+        catch { /* */ }
+        try {
+            hasSpecs = node_fs_1.default.readdirSync(node_path_1.default.join(docuDir, "specs")).some(f => f.endsWith(".md"));
+        }
+        catch { /* */ }
+        try {
+            const log = node_fs_1.default.readFileSync(node_path_1.default.join(docuDir, "log.md"), "utf8");
+            hasQueryUsage = /query-wiki|queryWiki/i.test(log);
+        }
+        catch { /* */ }
+        // Check watch daemon PID file
+        const pidFile = node_path_1.default.join(docuDir, "watch.pid.json");
+        try {
+            const data = JSON.parse(node_fs_1.default.readFileSync(pidFile, "utf8"));
+            try {
+                process.kill(data.pid, 0);
+                watchRunning = true;
+            }
+            catch { /* not running */ }
+        }
+        catch { /* no pid file */ }
+    }
+    return { hasDocuflow, hasSources, hasSpecs, hasQueryUsage, watchRunning };
+}
+function getHealthSummary(projectPath) {
+    const docuDir = node_path_1.default.join(projectPath, ".docuflow");
+    const byCategory = { entities: 0, concepts: 0, timelines: 0, syntheses: 0 };
+    for (const cat of Object.keys(byCategory)) {
+        try {
+            const files = node_fs_1.default.readdirSync(node_path_1.default.join(docuDir, "wiki", cat));
+            byCategory[cat] = files.filter(f => f.endsWith(".md")).length;
+        }
+        catch { /* dir may not exist */ }
+    }
+    const totalPages = Object.values(byCategory).reduce((a, b) => a + b, 0);
+    let lastUpdate = "never";
+    try {
+        const log = node_fs_1.default.readFileSync(node_path_1.default.join(docuDir, "log.md"), "utf8");
+        const match = log.match(/\[(\d{4}-\d{2}-\d{2}[^\]]*)\]/);
+        if (match) {
+            const d = new Date(match[1]);
+            if (!isNaN(d.getTime())) {
+                const diffH = Math.floor((Date.now() - d.getTime()) / 3_600_000);
+                lastUpdate = diffH < 1 ? "just now" : diffH < 24 ? `${diffH}h ago` : `${Math.floor(diffH / 24)}d ago`;
+            }
+        }
+    }
+    catch { /* */ }
+    return { totalPages, byCategory, lastUpdate, healthScore: null };
+}
+function buildRecommendations(packages, registrations, workflow, health) {
+    const recs = [];
+    const pkgMap = Object.fromEntries(packages.map(p => [p.name, p.version]));
+    // Core/Studio installed?
+    if (!pkgMap["@doquflow/core"] && !pkgMap["@doquflow/studio"]) {
+        if (pkgMap["@doquflow/cli"]) {
+            // CLI installs core+studio transitively — this just means they weren't directly required
+        }
+        else {
+            recs.push({ severity: "error", message: "No DocuFlow packages detected", action: 'Run: npm i -g @doquflow/cli' });
+        }
+    }
+    // Suggest minimal install if only using query/ingest
+    const hasCli = !!pkgMap["@doquflow/cli"];
+    const hasCore = !!pkgMap["@doquflow/core"];
+    const hasStudio = !!pkgMap["@doquflow/studio"];
+    if (hasCli && !workflow.watchRunning && !workflow.hasQueryUsage && hasCore && !hasStudio) {
+        recs.push({ severity: "info", message: "You only use core tools (query/ingest)", action: "Consider: npm i -g @doquflow/core for a smaller install" });
+    }
+    // Not initialised
+    if (!workflow.hasDocuflow) {
+        recs.push({ severity: "error", message: ".docuflow/ not found in this directory", action: "Run: docuflow init" });
+        return recs; // no point checking further
+    }
+    // No MCP registration anywhere
+    const anyRegistered = registrations.some(r => r.registered);
+    if (!anyRegistered) {
+        recs.push({ severity: "error", message: "DocuFlow is not registered with any MCP host", action: "Run: docuflow init (re-run is safe)" });
+    }
+    // No sources
+    if (!workflow.hasSources) {
+        recs.push({ severity: "warn", message: "No source documents in .docuflow/sources/", action: "Drop a markdown file there, then run: docuflow ingest" });
+    }
+    // Empty wiki
+    if (health.totalPages === 0 && workflow.hasSources) {
+        recs.push({ severity: "warn", message: "Wiki is empty but sources exist", action: "Run: docuflow rewiki" });
+    }
+    // Old @doquflow/server pointing at dist/index.js instead of dist/mcp/index.js
+    for (const reg of registrations.filter(r => r.registered)) {
+        const argStr = reg.args?.join(" ") ?? "";
+        if (argStr.includes("@doquflow/server") && argStr.includes("dist/index.js")) {
+            recs.push({ severity: "info", message: `${reg.source}: MCP registration uses old server path`, action: "Run: docuflow init to refresh to @doquflow/studio/dist/mcp/index.js" });
+        }
+    }
+    if (recs.length === 0) {
+        recs.push({ severity: "info", message: "Everything looks good", action: "No action needed" });
+    }
+    return recs;
+}
+// ── Output formatters ─────────────────────────────────────────────────────────
+function icon(severity) {
+    return severity === "error" ? "🔴" : severity === "warn" ? "🟡" : "🟢";
+}
+function printHuman(packages, registrations, workflow, health, recs, quiet) {
+    if (!quiet) {
+        // 1. Installed packages
+        console.log("\n── 1. Installed packages ────────────────────────────────");
+        for (const pkg of packages) {
+            const mark = pkg.version ? "✓" : "✗";
+            const ver = pkg.version ?? "not found";
+            console.log(`  ${mark}  ${pkg.name.padEnd(22)} ${ver}`);
+        }
+        // 2. MCP registrations
+        console.log("\n── 2. MCP server registrations ──────────────────────────");
+        for (const reg of registrations) {
+            const mark = reg.registered ? "✓" : "·";
+            const detail = reg.registered && reg.command
+                ? `  ${reg.command} ${(reg.args ?? []).slice(-1)[0] ?? ""}`
+                : "";
+            console.log(`  ${mark}  ${reg.source.padEnd(18)}${reg.registered ? "registered" : "not registered"}${detail}`);
+        }
+        // 3. Workflow detection
+        console.log("\n── 3. Workflow detection ─────────────────────────────────");
+        console.log(`  ${workflow.hasDocuflow ? "✓" : "✗"}  .docuflow/ initialised`);
+        console.log(`  ${workflow.hasSources ? "✓" : "·"}  source documents present`);
+        console.log(`  ${workflow.hasSpecs ? "✓" : "·"}  specs written`);
+        console.log(`  ${workflow.hasQueryUsage ? "✓" : "·"}  query_wiki usage in logs`);
+        console.log(`  ${workflow.watchRunning ? "✓" : "·"}  watch daemon running`);
+        // 4. Health summary
+        console.log("\n── 5. Wiki health summary ───────────────────────────────");
+        console.log(`  Pages total:    ${health.totalPages}`);
+        if (health.totalPages > 0) {
+            for (const [cat, n] of Object.entries(health.byCategory)) {
+                if (n > 0)
+                    console.log(`    ${cat.padEnd(14)} ${n}`);
+            }
+        }
+        console.log(`  Last updated:   ${health.lastUpdate}`);
+        console.log("");
+    }
+    // 4. Recommendations (always shown)
+    if (!quiet)
+        console.log("── 4. Recommendations ───────────────────────────────────");
+    for (const rec of recs) {
+        console.log(`  ${icon(rec.severity)}  ${rec.message}`);
+        console.log(`     → ${rec.action}`);
+    }
+    console.log("");
+}
+// ── Entry point ───────────────────────────────────────────────────────────────
+async function run(opts = {}) {
+    const projectPath = process.cwd();
+    const packages = getInstalledPackages();
+    const registrations = getMcpRegistrations(projectPath);
+    const workflow = detectWorkflow(projectPath);
+    const health = getHealthSummary(projectPath);
+    const recs = buildRecommendations(packages, registrations, workflow, health);
+    if (opts.json) {
+        console.log(JSON.stringify({ packages, registrations, workflow, health, recommendations: recs }, null, 2));
+        return;
+    }
+    printHuman(packages, registrations, workflow, health, recs, opts.quiet ?? false);
+}

package/dist/commands/help.js

@@ -0,0 +1,38 @@
+"use strict";
+// Help text for `docuflow --help` and `docuflow advanced --help`.
+// No external help library — plain console.log for zero-dependency output.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printCoreHelp = printCoreHelp;
+exports.printAdvancedHelp = printAdvancedHelp;
+function printCoreHelp() {
+    console.log('DocuFlow — preserve decision context for AI agents.');
+    console.log('');
+    console.log('CORE');
+    console.log('  docuflow init                         Initialise .docuflow/ in this project');
+    console.log('  docuflow ingest <file>                Add a source document to the wiki');
+    console.log('  docuflow query "<question>"           Ask the wiki — answer with citations');
+    console.log('  docuflow status                       Show wiki health and counts');
+    console.log('  docuflow rewiki                       Migrate / re-ingest with current rules');
+    console.log('  docuflow doctor                       Diagnose install, MCP registration, and wiki health');
+    console.log('');
+    console.log('ADVANCED');
+    console.log('  docuflow advanced --help              See watch / sync / ui / review / recent / suggest / update');
+    console.log('');
+    console.log('  docuflow --version                    Print version');
+    console.log('  docuflow --help                       Show this help');
+}
+function printAdvancedHelp() {
+    console.log('DocuFlow — advanced surface (sync daemons, UI, audit commands).');
+    console.log('');
+    console.log('  docuflow advanced watch [stop|status|restart]    Auto-sync daemon');
+    console.log('  docuflow advanced sync [--ai]                    One-shot sync for CI / git hooks');
+    console.log('  docuflow advanced ui [--port N]                  Launch web UI dashboard');
+    console.log('  docuflow advanced start                          Alias for ui');
+    console.log('  docuflow advanced review                         Review uncommitted changes');
+    console.log('  docuflow advanced recent                         Recent work dashboard');
+    console.log('  docuflow advanced suggest                        First-steps guidance');
+    console.log('  docuflow advanced update                         Self-upgrade DocuFlow');
+    console.log('');
+    console.log('Note: every "advanced" command also works at its old top-level path');
+    console.log('(e.g. `docuflow watch` is still valid). The "advanced" prefix is optional.');
+}

package/dist/commands/ingest.js

@@ -0,0 +1,118 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const c = {
+    green: (s) => `\x1b[32m${s}\x1b[0m`,
+    yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+    red: (s) => `\x1b[31m${s}\x1b[0m`,
+    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+    dim: (s) => `\x1b[2m${s}\x1b[0m`,
+    bold: (s) => `\x1b[1m${s}\x1b[0m`,
+};
+function loadServerTool(toolFile) {
+    const candidates = [
+        () => require(`@doquflow/core/dist/tools/${toolFile}`),
+        () => require(node_path_1.default.resolve(__dirname, "../../../core/dist/tools", toolFile)),
+        () => require(node_path_1.default.resolve(__dirname, "../../core/dist/tools", toolFile)),
+        () => require(`@doquflow/studio/dist/tools/${toolFile}`),
+        () => require(node_path_1.default.resolve(__dirname, "../../../studio/dist/tools", toolFile)),
+        () => require(node_path_1.default.resolve(__dirname, "../../studio/dist/tools", toolFile)),
+    ];
+    for (const attempt of candidates) {
+        try {
+            return attempt();
+        }
+        catch { }
+    }
+    throw new Error(`Cannot load server tool "${toolFile}". Run "npm run build" first.`);
+}
+async function run(options) {
+    const { sourceFile, all = false, dryRun = false, quiet = false } = options;
+    const projectPath = node_path_1.default.resolve(process.cwd());
+    const docuDir = node_path_1.default.join(projectPath, ".docuflow");
+    const sourcesDir = node_path_1.default.join(docuDir, "sources");
+    function info(msg) { if (!quiet)
+        process.stdout.write(msg + "\n"); }
+    if (!all && !sourceFile) {
+        console.error(c.red("  ✗ Provide a source filename or pass --all."));
+        console.error(`    Usage: docuflow ingest <source.md>`);
+        console.error(`           docuflow ingest --all`);
+        process.exit(2);
+    }
+    if (!node_fs_1.default.existsSync(docuDir)) {
+        console.error(c.red(`  ✗ .docuflow/ not found at ${projectPath}`));
+        console.error(`    Run "docuflow init" first.`);
+        process.exit(2);
+    }
+    if (dryRun) {
+        info(c.yellow("  dry-run not supported for ingest_source; use `docuflow rewiki --dry-run` for a full simulation"));
+        process.exit(0);
+    }
+    let ingestSource;
+    try {
+        ({ ingestSource } = loadServerTool("ingest-source"));
+    }
+    catch (e) {
+        console.error(c.red(`  ✗ ${e.message}`));
+        process.exit(2);
+    }
+    // Collect files to ingest
+    let files;
+    if (all) {
+        if (!node_fs_1.default.existsSync(sourcesDir)) {
+            console.error(c.yellow("  No .docuflow/sources/ directory found — nothing to ingest."));
+            process.exit(0);
+        }
+        files = node_fs_1.default.readdirSync(sourcesDir).filter(f => f.endsWith(".md"));
+        if (files.length === 0) {
+            info(c.yellow("  No source files found in .docuflow/sources/"));
+            process.exit(0);
+        }
+    }
+    else {
+        // Single file — verify it exists
+        const filename = sourceFile;
+        const fullPath = node_path_1.default.join(sourcesDir, filename);
+        if (!node_fs_1.default.existsSync(fullPath)) {
+            console.error(c.red(`  ✗ Source file not found: .docuflow/sources/${filename}`));
+            process.exit(3);
+        }
+        files = [filename];
+    }
+    info(c.bold(`DocuFlow ingest`));
+    info(`  Project : ${projectPath}`);
+    info(`  Files   : ${files.length}`);
+    info("");
+    let totalCreated = 0;
+    let totalUpdated = 0;
+    let errored = 0;
+    for (const filename of files) {
+        info(c.dim(`  Ingesting ${filename}…`));
+        try {
+            const result = await ingestSource({ project_path: projectPath, source_filename: filename });
+            totalCreated += result.pages_created ?? 0;
+            totalUpdated += result.pages_updated ?? 0;
+            info(`  ${c.green("✓")} ${filename}` +
+                `  ${c.dim(`+${result.pages_created ?? 0} created, ~${result.pages_updated ?? 0} updated`)}`);
+        }
+        catch (e) {
+            errored++;
+            console.error(c.red(`  ✗ ${filename}: ${e.message}`));
+        }
+    }
+    info("");
+    if (errored === 0) {
+        info(c.green("  ✓ Done.") +
+            `  Pages created: ${totalCreated}  updated: ${totalUpdated}`);
+    }
+    else {
+        info(c.yellow(`  Done with ${errored} error(s).`) +
+            `  Pages created: ${totalCreated}  updated: ${totalUpdated}`);
+        process.exit(2);
+    }
+}

package/dist/commands/init.js

@@ -62,13 +62,13 @@ function getCodexConfigPath() {
     return node_path_1.default.join(node_os_1.default.homedir(), ".codex", "config.toml");
 }
 function resolveServerBin() {
-    // Try npm-installed package first
+    // Try npm-installed studio MCP binary first
     try {
-        return require.resolve("@doquflow/server/dist/index.js");
+        return require.resolve("@doquflow/studio/dist/mcp/index.js");
     }
     catch {
         // Fallback: monorepo sibling path (dev environment)
-        return node_path_1.default.resolve(__dirname, "..", "..", "server", "dist", "index.js");
+        return node_path_1.default.resolve(__dirname, "..", "..", "studio", "dist", "mcp", "index.js");
     }
 }
 async function copyTemplateFile(templateName, destPath) {
@@ -101,64 +101,55 @@ async function copyTemplateFile(templateName, destPath) {
     }
 }
 function buildClaudeMd(projectDir) {
-    return `# DocuFlow — AI Documentation Assistant
-
-DocuFlow is an MCP server that gives you structured access to this codebase and maintains a living wiki.
-It is registered in your Claude Desktop config and available as MCP tools in every session.
-
-## Codebase Scanner Tools
+    return `<!-- BEGIN DOCUFLOW -->
+# DocuFlow — AI Documentation Assistant
 
-- **read_module** — Analyse a single source file. Returns language, classes, functions, dependencies, DB tables, endpoints, config refs, and raw content (first 8 KB).
-  - Example: \`read_module({ path: "src/UserService.cs" })\`
-- **list_modules** — Walk a directory and extract facts for every non-binary file. Use this to understand the full project in one call.
-  - Example: \`list_modules({ path: "${projectDir}" })\`
-- **write_spec** — Persist a markdown spec to \`.docuflow/specs/<filename>.md\` and update the index.
-  - Example: \`write_spec({ project_path: "${projectDir}", filename: "UserService", content: "# UserService\\n..." })\`
-- **read_specs** — Read previously written specs, optionally filtered by name.
-  - Example: \`read_specs({ project_path: "${projectDir}" })\`
+DocuFlow preserves decision context for AI agents. Intent in, value out.
 
-## Wiki Pipeline Tools
-
-- **ingest_source** — Ingest a markdown file from \`.docuflow/sources/\` and generate wiki pages (entities, concepts).
-- **update_index** — Rebuild \`.docuflow/index.md\` from all wiki pages.
-- **list_wiki** — List all wiki pages, optionally filtered by category (entity/concept/timeline/synthesis).
-- **wiki_search** — BM25 search across all wiki pages. Returns ranked results with previews.
-- **query_wiki** — One-stop Q&A: searches wiki, synthesises an answer, returns source citations.
-- **synthesize_answer** — Generate a markdown synthesis from a list of specific wiki page IDs.
-- **save_answer_as_page** — Persist a synthesised answer back into the wiki (knowledge compounding).
+## Core tools (use these first)
 
-## Health & Guidance Tools
+- **query_wiki({ project_path, question })** — Ask the wiki. Returns an answer with citations.
+- **ingest_source({ project_path, source_filename })** — Fold a markdown source into the wiki.
+- **wiki_search({ project_path, query })** — BM25 search across all pages.
+- **read_module({ path })** — Read and extract facts from a single source file.
 
-- **lint_wiki** — Health check: orphan pages, broken refs, stale content, metadata gaps. Returns a 0–100 health score.
-- **get_schema_guidance** — Analyse what wiki pages should exist based on the schema and current state.
-- **preview_generation** — Preview what a tool will do before running it.
+## CLI — Core Commands
 
-## Common Workflows
-
-### First time — understand the codebase
 \`\`\`
-list_modules({ path: "${projectDir}" })
-→ read the language breakdown and dependency map
-→ write_spec each important module
+docuflow query "<question>"         # ask the wiki from the shell
+docuflow ingest <source.md>         # add a source doc to the wiki
+docuflow status                     # wiki health and counts
+docuflow rewiki                     # re-ingest with current rules
+docuflow init                       # initialise .docuflow/ in this project
 \`\`\`
 
-### Ongoing — answer a question
+## Workflows
+
+### Answer a question
 \`\`\`
 query_wiki({ project_path: "${projectDir}", question: "How does authentication work?" })
-→ save_answer_as_page if the answer is worth keeping
 \`\`\`
 
-### Maintenance — check wiki health
+### Add new context
 \`\`\`
-lint_wiki({ project_path: "${projectDir}" })
-→ fix orphans and broken refs
+# drop a markdown file in .docuflow/sources/
+ingest_source({ project_path: "${projectDir}", source_filename: "auth-design.md" })
 \`\`\`
 
-### Maintenance — re-ingest with updated rules
-\`\`\`
-docuflow rewiki --dry-run   # preview cleanup
-docuflow rewiki             # apply (backs up wiki first)
-\`\`\`
+## Advanced tools
+
+Use when the core tools don't cover the workflow. Each has more parameters and side effects.
+
+- **list_modules** — Walk a directory tree and extract facts in bulk
+- **list_wiki** — Inventory pages by category, with staleness flags
+- **write_spec / read_specs** — Persistent agent-written specs
+- **save_answer_as_page** — Promote a synthesised answer into the wiki
+- **synthesize_answer** — Combine multiple pages into a markdown synthesis
+- **update_index** — Rebuild \`.docuflow/index.md\`
+- **lint_wiki** — Health checks: orphans, broken refs, stale content
+- **get_schema_guidance** — Recommend what pages should exist
+- **preview_generation** — Show what a tool will do before running
+- **generate_dependency_graph** — Build the import/shared-table graph
 
 ## Storage Layout
 
@@ -175,20 +166,25 @@ docuflow rewiki             # apply (backs up wiki first)
 ├── index.md         Auto-maintained catalog
 └── log.md           Operation log
 \`\`\`
-`;
+<!-- END DOCUFLOW -->`;
 }
 async function writeClaudeMd(projectDir) {
     const claudeMdPath = node_path_1.default.join(projectDir, "CLAUDE.md");
     const newSection = buildClaudeMd(projectDir);
     if (node_fs_1.default.existsSync(claudeMdPath)) {
         const existing = await promises_1.default.readFile(claudeMdPath, "utf8");
-        if (existing.includes("DocuFlow")) {
-            // Already has DocuFlow section — replace it
+        if (existing.includes("<!-- BEGIN DOCUFLOW -->") && existing.includes("<!-- END DOCUFLOW -->")) {
+            // Marker-based replacement — idempotent re-runs preserve surrounding content
+            const replaced = existing.replace(/<!-- BEGIN DOCUFLOW -->[\s\S]*?<!-- END DOCUFLOW -->/, newSection.trimEnd());
+            await promises_1.default.writeFile(claudeMdPath, replaced, "utf8");
+        }
+        else if (existing.includes("DocuFlow")) {
+            // Old format without markers — replace old DocuFlow section, add markers this time
             const withoutDocuflow = existing.replace(/\n?# DocuFlow[\s\S]*/, "").trimEnd();
             await promises_1.default.writeFile(claudeMdPath, withoutDocuflow + "\n\n" + newSection, "utf8");
         }
         else {
-            // Append to existing CLAUDE.md
+            // No DocuFlow section yet — append
             await promises_1.default.appendFile(claudeMdPath, "\n\n" + newSection, "utf8");
         }
     }