@doquflow/cli 0.4.5 → 0.5.1

package/dist/commands/init.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildClaudeMd = buildClaudeMd;
+exports.buildAgentsMd = buildAgentsMd;
 exports.run = run;
 const node_fs_1 = __importDefault(require("node:fs"));
 const promises_1 = __importDefault(require("node:fs/promises"));
@@ -32,6 +33,9 @@ function getVSCodeMcpConfigPath() {
 function getCopilotCliMcpConfigPath() {
     return node_path_1.default.join(node_os_1.default.homedir(), ".copilot", "mcp-config.json");
 }
+function getCodexConfigPath() {
+    return node_path_1.default.join(node_os_1.default.homedir(), ".codex", "config.toml");
+}
 function resolveServerBin() {
     // Try npm-installed package first
     try {
@@ -161,10 +165,98 @@ async function writeClaudeMd(projectDir) {
         await promises_1.default.writeFile(claudeMdPath, newSection, "utf8");
     }
 }
+function buildAgentsMd(projectDir) {
+    return `# DocuFlow — AI Documentation Assistant
+
+DocuFlow is an MCP server that provides structured access to this codebase and maintains a living wiki.
+It is registered via \`.codex/config.toml\` and available as MCP tools in every Codex session.
+
+## Available MCP Tools
+
+### Codebase Scanner
+- **read_module** — Analyse a single file: language, classes, functions, dependencies, DB tables, endpoints, config refs, raw content.
+  - \`read_module({ path: "src/UserService.cs" })\`
+- **list_modules** — Walk a directory, extract facts for every file. One call to understand the whole project.
+  - \`list_modules({ path: "${projectDir}" })\`
+- **write_spec** — Save a markdown spec to \`.docuflow/specs/<name>.md\`.
+  - \`write_spec({ project_path: "${projectDir}", filename: "UserService", content: "..." })\`
+- **read_specs** — Read saved specs, optionally filtered by name.
+  - \`read_specs({ project_path: "${projectDir}" })\`
+
+### Wiki Pipeline
+- **ingest_source** — Ingest a markdown file from \`.docuflow/sources/\` into the wiki (entities, concepts).
+- **update_index** — Rebuild \`.docuflow/index.md\` from all wiki pages.
+- **list_wiki** — List all wiki pages by category (entity/concept/timeline/synthesis).
+- **wiki_search** — BM25 search across all wiki pages.
+- **query_wiki** — Q&A: searches wiki, synthesises an answer, returns citations.
+  - \`query_wiki({ project_path: "${projectDir}", question: "How does auth work?" })\`
+- **synthesize_answer** — Generate a markdown synthesis from a list of page IDs.
+- **save_answer_as_page** — Persist a synthesis as a wiki page.
+
+### Health & Guidance
+- **lint_wiki** — Health check: orphan pages, broken refs, stale content. Returns a 0–100 health score.
+- **get_schema_guidance** — Recommend what wiki pages should exist based on schema + current state.
+- **preview_generation** — Preview what a tool will generate before running it.
+
+## Common Workflows
+
+Start here — understand the codebase:
+\`\`\`
+list_modules({ path: "${projectDir}" })
+→ write_spec for important modules
+\`\`\`
+
+Answer a question:
+\`\`\`
+query_wiki({ project_path: "${projectDir}", question: "..." })
+\`\`\`
+
+Maintain wiki health:
+\`\`\`
+lint_wiki({ project_path: "${projectDir}" })
+\`\`\`
+
+## Storage Layout
+
+\`\`\`
+.docuflow/
+├── specs/        Code specs written by write_spec
+├── wiki/         LLM-generated wiki pages
+│   ├── entities/
+│   ├── concepts/
+│   ├── timelines/
+│   └── syntheses/
+├── sources/      Raw markdown docs to ingest
+├── schema.md     Wiki configuration (edit to customise)
+├── index.md      Auto-maintained catalog
+└── log.md        Operation log
+\`\`\`
+`;
+}
+async function writeAgentsMd(projectDir) {
+    const agentsMdPath = node_path_1.default.join(projectDir, "AGENTS.md");
+    const newSection = buildAgentsMd(projectDir);
+    if (node_fs_1.default.existsSync(agentsMdPath)) {
+        const existing = await promises_1.default.readFile(agentsMdPath, "utf8");
+        if (existing.includes("DocuFlow")) {
+            // Replace existing DocuFlow section
+            const withoutDocuflow = existing.replace(/\n?# DocuFlow[\s\S]*/, "").trimEnd();
+            await promises_1.default.writeFile(agentsMdPath, withoutDocuflow + "\n\n" + newSection, "utf8");
+        }
+        else {
+            // Append to existing AGENTS.md
+            await promises_1.default.appendFile(agentsMdPath, "\n\n" + newSection, "utf8");
+        }
+    }
+    else {
+        await promises_1.default.writeFile(agentsMdPath, newSection, "utf8");
+    }
+}
 async function run() {
     const configPath = getClaudeDesktopConfigPath();
     const vscodeConfigPath = getVSCodeMcpConfigPath();
     const copilotCliConfigPath = getCopilotCliMcpConfigPath();
+    const codexConfigPath = getCodexConfigPath();
     const serverBin = resolveServerBin();
     const nodeBin = process.execPath;
     // Register in Claude Desktop config
@@ -223,6 +315,24 @@ async function run() {
     catch {
         // Copilot CLI not installed — skip silently
     }
+    // Register in OpenAI Codex CLI (~/.codex/config.toml in TOML format)
+    let codexCliRegistered = false;
+    try {
+        await promises_1.default.mkdir(node_path_1.default.dirname(codexConfigPath), { recursive: true });
+        let tomlContent = "";
+        try {
+            tomlContent = await promises_1.default.readFile(codexConfigPath, "utf8");
+        }
+        catch { /* new file */ }
+        if (!tomlContent.includes("[mcp_servers.docuflow]")) {
+            const entry = `\n[mcp_servers.docuflow]\ncommand = "${nodeBin}"\nargs = [${JSON.stringify(serverBin)}]\n`;
+            await promises_1.default.writeFile(codexConfigPath, tomlContent + entry, "utf8");
+        }
+        codexCliRegistered = true;
+    }
+    catch {
+        // Codex CLI not installed — skip silently
+    }
     // Create .docuflow/ directory structure
     const projectDir = process.cwd();
     const docuflowDir = node_path_1.default.join(projectDir, ".docuflow");
@@ -245,6 +355,8 @@ async function run() {
     await copyTemplateFile("log.md", node_path_1.default.join(docuflowDir, "log.md"));
     // Generate CLAUDE.md so Claude Code picks up DocuFlow automatically
     await writeClaudeMd(projectDir);
+    // Generate AGENTS.md so OpenAI Codex picks up DocuFlow automatically
+    await writeAgentsMd(projectDir);
     // Write .vscode/mcp.json for project-level workspace MCP config (shareable via git)
     // Uses npx so it works on any machine — safe to commit
     const vscodeDirPath = node_path_1.default.join(projectDir, ".vscode");
@@ -274,6 +386,8 @@ async function run() {
             await promises_1.default.appendFile(gitignorePath, "\n# Docuflow\n.docuflow/\n");
         }
     }
+    // Install git post-commit hook (auto-sync on every commit)
+    await installGitHook(projectDir);
     console.log("\u2713 DocuFlow initialised successfully.");
     console.log("");
     console.log("\ud83d\udcc1 Structure created:");
@@ -289,18 +403,75 @@ async function run() {
     console.log(`  \u251c\u2500\u2500 index.md            (auto-maintained catalog)`);
     console.log(`  \u2514\u2500\u2500 log.md              (operation log)`);
     console.log("");
-    console.log("\ud83d\udcdd CLAUDE.md:");
-    console.log(`  Generated at: ${node_path_1.default.join(projectDir, "CLAUDE.md")}`);
-    console.log(`  Claude Code reads DocuFlow tool instructions automatically.`);
+    console.log("\ud83d\udcdd Instruction files:");
+    console.log(`  CLAUDE.md  ✓ ${node_path_1.default.join(projectDir, "CLAUDE.md")}`);
+    console.log(`  AGENTS.md  ✓ ${node_path_1.default.join(projectDir, "AGENTS.md")}`);
     console.log("");
     console.log("\ud83d\udd27 MCP Registration:");
     console.log(`  Claude Desktop:  \u2713 registered`);
     console.log(`  VS Code Copilot: ${vscodeRegistered ? "\u2713 registered (user-level)" : "\u2014 not detected"}`);
     console.log(`  Copilot CLI:     ${copilotCliRegistered ? "\u2713 registered (~/.copilot/mcp-config.json)" : "\u2014 not detected"}`);
+    console.log(`  Codex CLI:       ${codexCliRegistered ? "\u2713 registered (~/.codex/config.toml)" : "\u2014 not detected"}`);
     console.log(`  Workspace:       \u2713 .vscode/mcp.json written (commit to share with team)`);
     console.log("");
     console.log("\ud83d\udcd6 Next steps:");
     console.log("  1. Edit .docuflow/schema.md to customize your wiki domain");
     console.log("  2. Add markdown docs to .docuflow/sources/ then ingest them");
     console.log("  3. Restart Claude Desktop / reload VS Code / restart Copilot CLI");
+    console.log("");
+    console.log("\u26a1 Auto-sync options:");
+    console.log("  docuflow watch           # background daemon (watches for file changes)");
+    console.log("  docuflow watch --ai      # + Claude/Codex documents code changes automatically");
+    console.log("  docuflow sync            # one-shot sync (good for CI/CD)");
+    console.log("  docuflow sync --ai       # + AI generates docs from last git commit");
+    console.log("");
+    console.log("  A git post-commit hook was installed at .git/hooks/post-commit");
+    console.log("  It runs \"docuflow sync --ai --quiet\" after every commit automatically.");
+}
+/**
+ * Install a git post-commit hook that runs `docuflow sync` automatically.
+ * Idempotent — does not overwrite a hook that already has DocuFlow content.
+ */
+async function installGitHook(projectDir) {
+    const gitDir = node_path_1.default.join(projectDir, ".git");
+    if (!node_fs_1.default.existsSync(gitDir))
+        return; // not a git repo
+    const hooksDir = node_path_1.default.join(gitDir, "hooks");
+    await promises_1.default.mkdir(hooksDir, { recursive: true });
+    const hookPath = node_path_1.default.join(hooksDir, "post-commit");
+    const hookMarker = "# docuflow-auto-sync";
+    // Don't overwrite if already installed
+    if (node_fs_1.default.existsSync(hookPath)) {
+        const existing = await promises_1.default.readFile(hookPath, "utf8");
+        if (existing.includes(hookMarker))
+            return;
+        // Append to existing hook
+        const appendContent = [
+            "",
+            hookMarker,
+            `# Auto-generated by docuflow init — runs wiki sync after every commit`,
+            `# Requires Claude CLI, Codex CLI, or ANTHROPIC_API_KEY for AI-powered doc generation`,
+            `# Remove the lines below to disable auto-sync`,
+            `if command -v docuflow &> /dev/null; then`,
+            `  docuflow sync --ai --quiet &`,
+            `fi`,
+        ].join("\n");
+        await promises_1.default.appendFile(hookPath, appendContent + "\n");
+        return;
+    }
+    // Create new hook file
+    const hookContent = [
+        `#!/bin/sh`,
+        hookMarker,
+        `# Auto-generated by docuflow init`,
+        `# Syncs the DocuFlow wiki after every commit using Claude / Codex / Anthropic API`,
+        `# AI bridge priority: Claude CLI > Codex CLI > ANTHROPIC_API_KEY`,
+        `# Run in background (&) so it never delays your git workflow`,
+        `if command -v docuflow &> /dev/null; then`,
+        `  docuflow sync --ai --quiet &`,
+        `fi`,
+    ].join("\n");
+    await promises_1.default.writeFile(hookPath, hookContent + "\n", "utf8");
+    // Make executable
+    node_fs_1.default.chmodSync(hookPath, 0o755);
 }

package/dist/commands/sync.js

@@ -0,0 +1,361 @@
+"use strict";
+/**
+ * docuflow sync
+ *
+ * One-shot synchronisation — re-ingests all sources, rebuilds the index,
+ * and runs a lint health check. Designed for CI/CD pipelines and git hooks.
+ *
+ * Usage:
+ *   docuflow sync                        # sync all sources, rebuild index, lint
+ *   docuflow sync --ai                   # also call Claude/Codex for changed code
+ *   docuflow sync --since-commit HEAD~1  # only process files changed in last commit
+ *   docuflow sync --source myfile.md     # sync a single source file
+ *   docuflow sync --no-lint              # skip health check (faster for CI)
+ *
+ * Exit codes:
+ *   0 — success, wiki is healthy (score ≥ 70)
+ *   1 — wiki has issues (score < 70) — use to fail CI
+ *   2 — fatal error (server tools not found, .docuflow missing)
+ */
+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 promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const watch_1 = require("./watch");
+// ─── Colour helpers ────────────────────────────────────────────────────────────
+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`,
+};
+// ─── Dynamic server tool loader ────────────────────────────────────────────────
+function loadServerTool(toolFile) {
+    const candidates = [
+        () => require(`@doquflow/server/dist/tools/${toolFile}`),
+        () => require(node_path_1.default.resolve(__dirname, "../../../server/dist/tools", toolFile)),
+        () => require(node_path_1.default.resolve(__dirname, "../../server/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.`);
+}
+// ─── Git helpers ───────────────────────────────────────────────────────────────
+/**
+ * Get list of source files changed since a given git ref.
+ * Returns paths relative to projectPath.
+ */
+function getGitChangedFiles(projectPath, sinceRef) {
+    try {
+        const output = (0, node_child_process_1.execSync)(`git diff --name-only ${sinceRef} HEAD`, {
+            cwd: projectPath,
+            encoding: "utf8",
+        }).trim();
+        return output ? output.split("\n").filter(Boolean) : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Get files staged in the current commit (for post-commit hook use).
+ */
+function getLastCommitFiles(projectPath) {
+    try {
+        const output = (0, node_child_process_1.execSync)("git diff-tree --no-commit-id -r --name-only HEAD", {
+            cwd: projectPath,
+            encoding: "utf8",
+        }).trim();
+        return output ? output.split("\n").filter(Boolean) : [];
+    }
+    catch {
+        return [];
+    }
+}
+// ─── AI bridge for sync (uses watch.ts bridges) ───────────────────────────────
+function buildSyncPrompt(projectPath, changedFiles) {
+    const fileList = changedFiles.length > 0
+        ? changedFiles.slice(0, 10).map(f => `- ${f}`).join("\n")
+        : "(full sync — no specific changed files)";
+    return [
+        `You are the DocuFlow wiki maintainer for: ${projectPath}`,
+        ``,
+        `Files recently committed/changed:`,
+        fileList,
+        ``,
+        `Use docuflow MCP tools in order:`,
+        `1. list_wiki({ project_path: "${projectPath}" }) — note page count`,
+        `2. ingest_source for each .docuflow/sources/ file relevant to the changes`,
+        `   (if unsure, ingest all source files)`,
+        `3. update_index({ project_path: "${projectPath}" })`,
+        `4. lint_wiki({ project_path: "${projectPath}", check_type: "all" })`,
+        `5. Report: pages before/after, health score, high-severity issues.`,
+        ``,
+        `Be concise. Just execute and report.`,
+    ].join("\n");
+}
+/**
+ * Run Copilot CLI — directly calls DocuFlow MCP tools.
+ * Returns the assistant's text response or null.
+ */
+function runCopilotSync(prompt) {
+    const result = (0, node_child_process_1.spawnSync)("copilot", ["--prompt", prompt, "--allow-all-tools", "--allow-all-paths", "--no-ask-user", "--output-format", "json"], { encoding: "utf8", timeout: 180_000 });
+    if (result.error || result.status !== 0)
+        return null;
+    let lastMessage = null;
+    for (const line of (result.stdout ?? "").split("\n")) {
+        try {
+            const obj = JSON.parse(line.trim());
+            if (obj.type === "assistant.message" && obj.data?.content)
+                lastMessage = obj.data.content;
+        }
+        catch { }
+    }
+    return lastMessage;
+}
+/**
+ * Run Claude CLI — directly calls DocuFlow MCP tools.
+ * Pass allowDangerousPermissions=true (via --allow-dangerous-permissions CLI flag)
+ * to skip interactive permission prompts for non-interactive use.
+ * Without it Claude CLI may prompt for tool access and time out in a daemon context.
+ * Injects docuflow MCP config explicitly via --mcp-config.
+ */
+function runClaudeSync(prompt, projectPath, allowDangerousPermissions = false) {
+    // Build the MCP config pointing to the local server binary
+    let serverBin;
+    try {
+        serverBin = require.resolve("@doquflow/server/dist/index.js");
+    }
+    catch {
+        serverBin = node_path_1.default.resolve(__dirname, "../../server/dist/index.js");
+    }
+    const mcpConfig = JSON.stringify({
+        mcpServers: {
+            docuflow: { type: "stdio", command: process.execPath, args: [serverBin] }
+        }
+    });
+    const env = { ...process.env };
+    const claudeArgs = ["--print", "--mcp-config", mcpConfig];
+    if (allowDangerousPermissions) {
+        claudeArgs.splice(1, 0, "--dangerously-skip-permissions");
+    }
+    const result = (0, node_child_process_1.spawnSync)("claude", claudeArgs, { input: prompt, encoding: "utf8", timeout: 180_000, env });
+    const stdout = result.stdout?.trim() ?? "";
+    // Filter out Claude auth errors
+    if (!stdout || stdout.includes("Invalid API key") || stdout.includes("authentication"))
+        return null;
+    return stdout || null;
+}
+/**
+ * Fallback for codex/api: generate markdown doc from changed files, then ingest.
+ */
+async function generateAndIngest(projectPath, changedFiles, bridge, info) {
+    const fileList = changedFiles.map(f => `- ${f}`).join("\n");
+    const prompt = [
+        `You are maintaining documentation for a software project.`,
+        `These files changed:\n${fileList}`,
+        ``,
+        `Write a concise markdown document (200-500 words) capturing what changed.`,
+        `Markdown only. Start with # heading. No preamble.`,
+    ].join("\n");
+    let docContent = null;
+    if (bridge === "codex") {
+        const r = (0, node_child_process_1.spawnSync)("codex", [prompt], { encoding: "utf8", timeout: 90_000 });
+        docContent = r.status === 0 ? r.stdout?.trim() ?? null : null;
+    }
+    else if (bridge === "api" && process.env.ANTHROPIC_API_KEY) {
+        const https = require("https");
+        const body = JSON.stringify({ model: "claude-3-5-haiku-20241022", max_tokens: 1024, messages: [{ role: "user", content: prompt }] });
+        docContent = await new Promise((resolve) => {
+            const req = https.request({ hostname: "api.anthropic.com", path: "/v1/messages", method: "POST",
+                headers: { "Content-Type": "application/json", "x-api-key": process.env.ANTHROPIC_API_KEY, "anthropic-version": "2023-06-01", "Content-Length": Buffer.byteLength(body) } }, (res) => { let d = ""; res.on("data", (ch) => d += ch); res.on("end", () => { try {
+                resolve(JSON.parse(d)?.content?.[0]?.text ?? null);
+            }
+            catch {
+                resolve(null);
+            } }); });
+            req.on("error", () => resolve(null));
+            req.setTimeout(90_000, () => { req.destroy(); resolve(null); });
+            req.write(body);
+            req.end();
+        });
+    }
+    if (!docContent) {
+        info("  ⚠  AI returned no content — skipping AI doc generation");
+        return;
+    }
+    const sourcesDir = node_path_1.default.join(projectPath, ".docuflow", "sources");
+    await promises_1.default.mkdir(sourcesDir, { recursive: true });
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    const autoFilename = `auto_sync_${timestamp}.md`;
+    await promises_1.default.writeFile(node_path_1.default.join(sourcesDir, autoFilename), docContent, "utf8");
+    info(`  ✅ AI doc saved → ${autoFilename}`);
+}
+async function run(options = {}) {
+    const projectPath = node_path_1.default.resolve(options.projectPath ?? process.cwd());
+    const docuDir = node_path_1.default.join(projectPath, ".docuflow");
+    const sourcesDir = node_path_1.default.join(docuDir, "sources");
+    const quiet = options.quiet ?? false;
+    const failThreshold = options.failOnScore ?? 70;
+    function info(msg) {
+        if (!quiet)
+            console.log(msg);
+    }
+    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);
+    }
+    info(c.bold("\n  🔄 DocuFlow Sync\n"));
+    const startTime = Date.now();
+    let skipManualSync = false; // set true when Copilot/Claude handle everything
+    // ── Step 1: Determine which source files to process ─────────────────────────
+    let sourceFilesToProcess = [];
+    if (options.sourceFile) {
+        // Single file mode
+        sourceFilesToProcess = [options.sourceFile];
+        info(`  📄 Single file mode: ${c.cyan(options.sourceFile)}`);
+    }
+    else {
+        // Scan all .md files in sources/
+        try {
+            const all = await promises_1.default.readdir(sourcesDir);
+            sourceFilesToProcess = all.filter((f) => f.endsWith(".md"));
+        }
+        catch {
+            info(c.yellow(`  ⚠  No sources/ directory found — nothing to ingest`));
+            sourceFilesToProcess = [];
+        }
+        info(`  📚 Found ${sourceFilesToProcess.length} source file(s) to ingest`);
+    }
+    // ── Step 2: AI-powered sync for code changes ─────────────────────────────
+    if (options.ai) {
+        const codeExts = /\.(ts|tsx|js|jsx|mjs|py|go|rb|java|cs|php|rs|kt|swift)$/;
+        const changedCodeFiles = options.sinceCommit
+            ? getGitChangedFiles(projectPath, options.sinceCommit).filter(f => !f.startsWith(".docuflow") && codeExts.test(f))
+            : getLastCommitFiles(projectPath).filter(f => !f.startsWith(".docuflow") && codeExts.test(f));
+        const bridge = (0, watch_1.detectBridge)({ useAI: true, forceCopilot: options.forceCopilot, forceClaude: options.forceClaude, forceCodex: options.forceCodex });
+        const sinceLabel = options.sinceCommit ?? "last commit";
+        if (changedCodeFiles.length > 0) {
+            info(`\n  🤖 ${changedCodeFiles.length} code file(s) changed (${sinceLabel})`);
+            for (const f of changedCodeFiles.slice(0, 5))
+                info(c.dim(`     ${f}`));
+            if (bridge === "copilot") {
+                info(`  ⚡ Copilot will directly call DocuFlow MCP tools (ingest + index + lint)...`);
+                const prompt = buildSyncPrompt(projectPath, changedCodeFiles);
+                const result = runCopilotSync(prompt);
+                if (result) {
+                    info(c.green(`  ✅ Copilot completed wiki sync via MCP tools`));
+                    info(c.dim(`     ${result.replace(/\n/g, "\n     ")}`));
+                    // Copilot handled everything — skip manual steps below
+                    skipManualSync = true;
+                }
+                else {
+                    info(c.yellow(`  ⚠  Copilot returned no result — continuing with direct sync`));
+                }
+            }
+            else if (bridge === "claude") {
+                info(`  ⚡ Claude will directly call DocuFlow MCP tools (ingest + index + lint)...`);
+                const prompt = buildSyncPrompt(projectPath, changedCodeFiles);
+                const result = runClaudeSync(prompt, projectPath, options.allowDangerousPermissions);
+                if (result) {
+                    info(c.green(`  ✅ Claude completed wiki sync via MCP tools`));
+                    info(c.dim(`     ${result.replace(/\n/g, "\n     ")}`));
+                    skipManualSync = true;
+                }
+                else {
+                    info(c.yellow(`  ⚠  Claude returned no result — continuing with direct sync`));
+                }
+            }
+            else if (bridge !== "none") {
+                // codex or api: generate doc → add to sources
+                await generateAndIngest(projectPath, changedCodeFiles, bridge, info);
+                const sourcesAgain = await promises_1.default.readdir(sourcesDir).catch(() => []);
+                sourceFilesToProcess = sourcesAgain.filter(f => f.endsWith(".md"));
+            }
+        }
+        else {
+            info(c.dim(`  No code files changed since ${sinceLabel}`));
+        }
+    }
+    // ── Step 3: Ingest + Step 4: Rebuild (skip if Copilot/Claude handled via MCP) ──
+    let totalPagesCreated = 0;
+    let ingestErrors = 0;
+    if (!skipManualSync) {
+        const { ingestSource } = loadServerTool("ingest-source");
+        const { updateIndex } = loadServerTool("update-index");
+        if (sourceFilesToProcess.length > 0) {
+            info(`\n  📥 Ingesting sources...`);
+        }
+        for (const filename of sourceFilesToProcess) {
+            try {
+                const result = await ingestSource({ project_path: projectPath, source_filename: filename });
+                const created = result.pages_created?.length ?? 0;
+                totalPagesCreated += created;
+                info(`     ${created > 0 ? c.green("✓") : c.yellow("~")} ${filename} → ${created} page(s)`);
+            }
+            catch (e) {
+                info(c.red(`     ✗ ${filename}: ${e.message}`));
+                ingestErrors++;
+            }
+        }
+        info(`\n  📋 Rebuilding index...`);
+        const indexResult = await updateIndex({ project_path: projectPath });
+        info(c.green(`  ✅ Index rebuilt — ${indexResult.entries_indexed} entries`));
+    }
+    else {
+        info(c.dim(`  ℹ️  Ingest/index handled by Copilot/Claude via MCP tools directly`));
+    }
+    // ── Step 5: Lint ─────────────────────────────────────────────────────────────
+    let healthScore = 100;
+    if (!options.noLint) {
+        info(`\n  🔍 Running wiki health check...`);
+        const { lintWiki } = loadServerTool("lint-wiki");
+        const lintResult = await lintWiki({ project_path: projectPath, check_type: "all" });
+        healthScore = lintResult.health_score ?? 100;
+        const scoreLabel = healthScore >= 90
+            ? c.green(`${healthScore}/100`)
+            : healthScore >= 70
+                ? c.yellow(`${healthScore}/100`)
+                : c.red(`${healthScore}/100`);
+        info(`  📊 Wiki health: ${scoreLabel}`);
+        if (lintResult.issues_found?.length > 0) {
+            const high = lintResult.issues_found.filter((i) => i.severity === "high").length;
+            const med = lintResult.issues_found.filter((i) => i.severity === "medium").length;
+            const low = lintResult.issues_found.filter((i) => i.severity === "low").length;
+            info(`     🔴 High: ${high}  🟡 Medium: ${med}  🟢 Low: ${low}`);
+        }
+        for (const rec of lintResult.recommendations?.slice(0, 3) ?? []) {
+            info(c.dim(`     → ${rec}`));
+        }
+    }
+    // ── Summary ──────────────────────────────────────────────────────────────────
+    const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+    info(`\n  ─────────────────────────────────────────────`);
+    info(`  Sources processed:  ${sourceFilesToProcess.length}`);
+    info(`  Pages created:      ${totalPagesCreated}`);
+    info(`  Ingest errors:      ${ingestErrors > 0 ? c.red(String(ingestErrors)) : "0"}`);
+    if (!options.noLint) {
+        info(`  Health score:       ${healthScore}/100`);
+    }
+    info(`  Duration:           ${elapsed}s`);
+    info(`  ─────────────────────────────────────────────\n`);
+    // Exit with code 1 if health is below threshold (useful for CI)
+    if (!options.noLint && healthScore < failThreshold) {
+        process.exit(1);
+    }
+    if (ingestErrors > 0) {
+        process.exit(1);
+    }
+}