devsmind-mcp 2.4.0 → 4.0.0

package/dist/cli/extract-agent.d.ts

@@ -0,0 +1,66 @@
+import { ExtractionCandidate } from '../utils/ast';
+import { LlmCredentials } from './llm-client';
+/**
+ * Agentic node-extraction curation — the judgment half of Phase D. `enumerateFileCandidates`
+ * (deterministic, no LLM) already found every candidate and split them by whether their EXISTENCE
+ * is unambiguous (`isExported`). This module handles only what's left: for candidates whose
+ * significance genuinely requires judgment (an unexported helper, an anonymous default, a tiny
+ * inline callback), a multi-turn tool-calling agent decides keep/drop/merge/rename. Existence is
+ * never delegated to the model — only significance is, which is the whole reason this is more
+ * reliable than the old "dump the whole file to an LLM and hope it finds everything" extraction.
+ */
+export type CurationDecisionKind = 'keep' | 'drop' | 'merge' | 'rename';
+export interface CurationDecision {
+    qualified: string;
+    decision: CurationDecisionKind;
+    /** Present when `decision === 'merge'` — the candidate this one conceptually belongs to. */
+    mergeInto?: string;
+    /** Present when `decision === 'rename'` — the better name for this candidate. */
+    renameTo?: string;
+    reason?: string;
+}
+export interface CurationResult {
+    decisions: CurationDecision[];
+    /** True when the turn budget ran out before the model called `submit_decisions` — every
+     * candidate defaulted to "keep" (see {@link curateAmbiguousCandidates}'s doc for why). */
+    timedOut: boolean;
+}
+/**
+ * Runs the agentic curation loop over one file's AMBIGUOUS candidates only (the `isExported:false`
+ * subset of `enumerateFileCandidates` — the caller is responsible for that split, see
+ * {@link extractFileWithCuration}). Multi-turn: the model may call `get_file_imports` any number
+ * of times before it must call `submit_decisions` to finish. `opts.onTurn` receives one line per
+ * model turn — nothing about this loop happens silently.
+ *
+ * If the turn budget is exhausted without a `submit_decisions` call, every candidate defaults to
+ * "keep" — silently dropping a real candidate is a worse failure than over-including one, and
+ * everything reaching this function already passed the deterministic auto-accept gate, so "keep,
+ * unreviewed" is the safe fallback, not a crash or a lost node.
+ */
+export declare function curateAmbiguousCandidates(creds: LlmCredentials, filePath: string, candidates: ExtractionCandidate[], opts?: {
+    maxTurns?: number;
+    rpm?: number;
+    onTurn?: (line: string) => void;
+}): Promise<CurationResult>;
+/** The shape `runBackgroundIndexing`/`runBackgroundReindexing` already consume from the old
+ * `extractNodesFromCode` — matched exactly so wiring this in is a drop-in call-site swap. */
+export interface CuratedExtractionResult {
+    nodes: {
+        node_id: string;
+        name: string;
+        type: string;
+        signature?: string;
+        code_snapshot: string;
+    }[];
+}
+/**
+ * The full Phase D per-file extraction: deterministic enumeration + auto-accept for exported
+ * candidates (zero LLM turns), agentic curation only for the ambiguous remainder. This is the
+ * cost control the whole design rests on — on a typical file most candidates ARE exported, so most
+ * files touch the LLM only for a handful of borderline cases, or not at all.
+ */
+export declare function extractFileWithCuration(creds: LlmCredentials, filePath: string, opts?: {
+    maxTurns?: number;
+    rpm?: number;
+    onLog?: (line: string) => void;
+}): Promise<CuratedExtractionResult>;

package/dist/cli/extract-agent.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.curateAmbiguousCandidates = curateAmbiguousCandidates;
+exports.extractFileWithCuration = extractFileWithCuration;
+const ast_1 = require("../utils/ast");
+const llm_client_1 = require("./llm-client");
+const runner_1 = require("./runner");
+const SUBMIT_TOOL_NAME = 'submit_decisions';
+const GET_IMPORTS_TOOL_NAME = 'get_file_imports';
+function buildTools() {
+    return [
+        {
+            name: GET_IMPORTS_TOOL_NAME,
+            description: "Returns this file's own import statements (module specifier + imported name). Useful to judge whether an ambiguous candidate is a real, independently meaningful entity or just a trivial local detail — e.g. whether it mirrors something worth tracking alongside a specific imported dependency, versus pure local plumbing.",
+            parameters: { type: 'object', properties: {}, additionalProperties: false }
+        },
+        {
+            name: SUBMIT_TOOL_NAME,
+            description: 'REQUIRED — call this exactly once, when you have a decision for every candidate, to finish the task. This is the ONLY way to finish; do not stop without calling it.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    decisions: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                qualified: { type: 'string', description: 'The candidate\'s "qualified" name, copied exactly as given.' },
+                                decision: { type: 'string', enum: ['keep', 'drop', 'merge', 'rename'] },
+                                merge_into: { type: 'string', description: 'Required when decision is "merge" — the qualified name of the candidate this one belongs to.' },
+                                rename_to: { type: 'string', description: 'Required when decision is "rename" — the better name for this candidate.' },
+                                reason: { type: 'string', description: 'One short sentence: why.' }
+                            },
+                            required: ['qualified', 'decision']
+                        }
+                    }
+                },
+                required: ['decisions']
+            }
+        }
+    ];
+}
+function buildSystemPrompt() {
+    return [
+        'You are curating a list of code-graph node CANDIDATES for one source file.',
+        "These candidates were found deterministically by parsing the file's AST — every one of them genuinely exists in the code, at the exact line numbers given. Nothing about their EXISTENCE is in question here.",
+        '',
+        'Your ONLY job is judgment. For EACH candidate, decide:',
+        '- "keep" — a real, independently meaningful entity worth its own node.',
+        '- "drop" — trivial noise (e.g. a tiny inline callback, a throwaway local) not worth tracking on its own.',
+        '- "merge" — this is really part of another candidate\'s concept, not a distinct entity (give merge_into).',
+        "- \"rename\" — the extractor's name is wrong, unclear, or anonymous and you have a genuinely better one (give rename_to).",
+        '',
+        `Call ${GET_IMPORTS_TOOL_NAME} if the file's imports would help you judge significance — as many times as you like, though it never changes between calls.`,
+        `When you have a decision for EVERY candidate, call ${SUBMIT_TOOL_NAME} exactly once with the full list. Keep any "reason" to one short sentence. Do not respond with plain text instead of a tool call.`
+    ].join('\n');
+}
+function buildInitialUserMessage(filePath, candidates) {
+    const blocks = candidates.map(c => `- qualified: "${c.qualified}"\n  type: ${c.type}\n  lines: ${c.startLine}-${c.endLine}\n  code:\n${c.codeSnapshot.split('\n').map(l => '    ' + l).join('\n')}`);
+    return `File: ${filePath}\n\n${candidates.length} candidate(s) to curate:\n\n${blocks.join('\n\n')}`;
+}
+function parseDecisions(args, candidates) {
+    const raw = Array.isArray(args.decisions) ? args.decisions : [];
+    const validQualified = new Set(candidates.map(c => c.qualified));
+    const decisions = [];
+    const seen = new Set();
+    for (const entry of raw) {
+        const d = entry;
+        if (!d || typeof d.qualified !== 'string' || !validQualified.has(d.qualified))
+            continue;
+        if (seen.has(d.qualified))
+            continue; // one decision per candidate — a duplicate is ignored
+        seen.add(d.qualified);
+        const decisionKind = d.decision === 'drop' || d.decision === 'merge' || d.decision === 'rename' ? d.decision : 'keep';
+        decisions.push({
+            qualified: d.qualified,
+            decision: decisionKind,
+            mergeInto: typeof d.merge_into === 'string' ? d.merge_into : undefined,
+            renameTo: typeof d.rename_to === 'string' ? d.rename_to : undefined,
+            reason: typeof d.reason === 'string' ? d.reason : undefined
+        });
+    }
+    // Any candidate the model never mentioned still needs a decision — same conservative default
+    // as a turn-budget timeout (see curateAmbiguousCandidates): keep, not silently drop.
+    for (const c of candidates) {
+        if (!seen.has(c.qualified)) {
+            decisions.push({ qualified: c.qualified, decision: 'keep', reason: 'not mentioned by the model — conservative default' });
+        }
+    }
+    return decisions;
+}
+/**
+ * Runs the agentic curation loop over one file's AMBIGUOUS candidates only (the `isExported:false`
+ * subset of `enumerateFileCandidates` — the caller is responsible for that split, see
+ * {@link extractFileWithCuration}). Multi-turn: the model may call `get_file_imports` any number
+ * of times before it must call `submit_decisions` to finish. `opts.onTurn` receives one line per
+ * model turn — nothing about this loop happens silently.
+ *
+ * If the turn budget is exhausted without a `submit_decisions` call, every candidate defaults to
+ * "keep" — silently dropping a real candidate is a worse failure than over-including one, and
+ * everything reaching this function already passed the deterministic auto-accept gate, so "keep,
+ * unreviewed" is the safe fallback, not a crash or a lost node.
+ */
+async function curateAmbiguousCandidates(creds, filePath, candidates, opts = {}) {
+    if (candidates.length === 0)
+        return { decisions: [], timedOut: false };
+    const maxTurns = opts.maxTurns ?? 4;
+    const tools = buildTools();
+    const systemPrompt = buildSystemPrompt();
+    const messages = [{ role: 'user', content: buildInitialUserMessage(filePath, candidates) }];
+    const log = opts.onTurn ?? (() => { });
+    for (let turn = 1; turn <= maxTurns; turn++) {
+        await (0, runner_1.throttleRpm)(opts.rpm);
+        const result = await (0, llm_client_1.sendConversationTurnWithRetry)(creds, systemPrompt, messages, tools, {
+            onRetry: (m) => log(`  ⚠ ${m}`)
+        });
+        const submitCall = result.toolCalls.find(tc => tc.name === SUBMIT_TOOL_NAME);
+        if (submitCall) {
+            const decisions = parseDecisions(submitCall.args, candidates);
+            log(`  ✓ turn ${turn}: ${SUBMIT_TOOL_NAME} — ${decisions.length} decision(s)`);
+            return { decisions, timedOut: false };
+        }
+        const importsCall = result.toolCalls.find(tc => tc.name === GET_IMPORTS_TOOL_NAME);
+        if (importsCall) {
+            log(`  → turn ${turn}: ${GET_IMPORTS_TOOL_NAME}`);
+            messages.push({ role: 'assistant', content: result.text, toolCalls: result.toolCalls });
+            messages.push({
+                role: 'tool',
+                toolCallId: importsCall.id,
+                toolName: GET_IMPORTS_TOOL_NAME,
+                content: JSON.stringify((0, ast_1.listFileImports)(filePath))
+            });
+            continue;
+        }
+        // No recognized tool call this turn — nudge once rather than loop silently on a model that
+        // isn't cooperating; if it still won't call a tool, the turn budget above ends this cleanly.
+        log(`  ? turn ${turn}: no tool call — nudging`);
+        messages.push({ role: 'assistant', content: result.text, toolCalls: [] });
+        messages.push({
+            role: 'user',
+            content: `You must call ${SUBMIT_TOOL_NAME} to finish (or ${GET_IMPORTS_TOOL_NAME} first if you need it). Do not respond with plain text.`
+        });
+    }
+    log(`  ⚠ turn budget (${maxTurns}) exhausted — defaulting all ${candidates.length} candidate(s) to "keep"`);
+    return {
+        decisions: candidates.map(c => ({ qualified: c.qualified, decision: 'keep', reason: 'curation turn budget exhausted — conservative default' })),
+        timedOut: true
+    };
+}
+/**
+ * The full Phase D per-file extraction: deterministic enumeration + auto-accept for exported
+ * candidates (zero LLM turns), agentic curation only for the ambiguous remainder. This is the
+ * cost control the whole design rests on — on a typical file most candidates ARE exported, so most
+ * files touch the LLM only for a handful of borderline cases, or not at all.
+ */
+async function extractFileWithCuration(creds, filePath, opts = {}) {
+    const log = opts.onLog ?? (() => { });
+    const candidates = (0, ast_1.enumerateFileCandidates)(filePath);
+    const exported = candidates.filter(c => c.isExported);
+    const ambiguous = candidates.filter(c => !c.isExported);
+    log(`  ${exported.length} exported (auto-accepted, 0 LLM turns), ${ambiguous.length} ambiguous`);
+    const nodes = exported.map(c => ({
+        node_id: c.qualified,
+        name: c.name,
+        type: c.type,
+        signature: c.signature ?? undefined,
+        code_snapshot: c.codeSnapshot
+    }));
+    if (ambiguous.length === 0)
+        return { nodes };
+    const result = await curateAmbiguousCandidates(creds, filePath, ambiguous, {
+        maxTurns: opts.maxTurns,
+        rpm: opts.rpm,
+        onTurn: log
+    });
+    const byQualified = new Map(ambiguous.map(c => [c.qualified, c]));
+    for (const d of result.decisions) {
+        const c = byQualified.get(d.qualified);
+        if (!c)
+            continue;
+        // "merge" folds this candidate's SIGNIFICANCE into its target conceptually — it does not
+        // become a separate node. The merge target (if it's also a real candidate) is handled by its
+        // own decision entry; this candidate's code simply isn't extracted as its own node.
+        if (d.decision === 'drop' || d.decision === 'merge')
+            continue;
+        const name = d.decision === 'rename' && d.renameTo ? d.renameTo : c.name;
+        const nodeId = d.decision === 'rename' && d.renameTo ? d.renameTo : c.qualified;
+        nodes.push({ node_id: nodeId, name, type: c.type, signature: c.signature ?? undefined, code_snapshot: c.codeSnapshot });
+    }
+    return { nodes };
+}
+//# sourceMappingURL=extract-agent.js.map

package/dist/cli/extract-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-agent.js","sourceRoot":"","sources":["../../src/cli/extract-agent.ts"],"names":[],"mappings":"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"}

package/dist/cli/feedback.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `devsmind feedback` — the human-facing read of the local, gitignored feedback log that
+ * `commit_changes`' `feedback` param writes to (see db/feedback.ts). Read-only, same store
+ * `read_graph_feedback` (an agent's own batch graph-fix session) and the AI-only product log
+ * draw from — this is the first surface a person has ever had to actually see any of it.
+ */
+export declare function handleFeedback(opts: {
+    path?: string;
+    since?: string;
+    all?: boolean;
+}): Promise<void>;

package/dist/cli/feedback.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleFeedback = handleFeedback;
+const config_1 = require("../utils/config");
+const feedback_1 = require("../db/feedback");
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RESET = '\x1b[0m';
+function sinceCutoff(sinceDays) {
+    const n = sinceDays ? parseInt(sinceDays, 10) : undefined;
+    return n !== undefined && !Number.isNaN(n) ? Date.now() - n * 24 * 60 * 60 * 1000 : null;
+}
+function printGraphCluster(c) {
+    const confidenceTag = c.confidence === 'confirmed' ? `${GREEN}confirmed${RESET}` : `${YELLOW}suspected${RESET}`;
+    console.log(`  ${BOLD}${c.count}x${RESET}  ${c.category}  ${DIM}${c.node_id}${RESET}  (${confidenceTag})`);
+    // One representative line of text per cluster keeps this readable even when the same report
+    // repeated 30 times — the individual entries (with evidence) are what read_graph_feedback
+    // exposes to the AI's own batch graph-fix session, not what a human skim needs here.
+    console.log(`      ${c.entries[0].text}`);
+    if (c.entries[0].evidence) {
+        const e = c.entries[0].evidence;
+        console.log(`      ${DIM}evidence: ${e.file}${e.line ? ':' + e.line : ''}${RESET}`);
+    }
+}
+function printProductEntries(entries, category) {
+    const filtered = entries.filter(e => e.category === category);
+    if (!filtered.length)
+        return;
+    const label = { tools_used: 'What helped', dropped_and_why: 'What got dropped', devsmind_better: 'How to improve' }[category];
+    console.log(`  ${BOLD}${label}${RESET}`);
+    for (const e of filtered) {
+        console.log(`    ${DIM}${new Date(e.ts).toLocaleDateString()}${RESET}  ${e.text}`);
+    }
+}
+/**
+ * `devsmind feedback` — the human-facing read of the local, gitignored feedback log that
+ * `commit_changes`' `feedback` param writes to (see db/feedback.ts). Read-only, same store
+ * `read_graph_feedback` (an agent's own batch graph-fix session) and the AI-only product log
+ * draw from — this is the first surface a person has ever had to actually see any of it.
+ */
+async function handleFeedback(opts) {
+    const devmindDir = (0, config_1.resolveDevmindDir)(opts.path);
+    if (!devmindDir) {
+        console.error(`❌ No .devmind directory found.\n` +
+            `   Run from inside a DevsMind brain folder, or pass --path <devmind_path>.`);
+        process.exit(1);
+    }
+    const cutoff = sinceCutoff(opts.since);
+    const inWindow = (ts) => cutoff === null || new Date(ts).getTime() >= cutoff;
+    const graphEntries = (0, feedback_1.readGraphFeedback)(devmindDir, { includeProcessed: !!opts.all }).filter(e => inWindow(e.ts));
+    const productEntries = (0, feedback_1.readProductFeedback)(devmindDir).filter(e => inWindow(e.ts));
+    const ruleCandidates = (0, feedback_1.readIndexerRuleCandidates)(devmindDir).filter(e => inWindow(e.ts));
+    if (!graphEntries.length && !productEntries.length && !ruleCandidates.length) {
+        console.log(`\n📭  No feedback recorded${cutoff !== null ? ` in the last ${opts.since} day(s)` : ''}.\n` +
+            `   commit_changes asks for feedback on every commit — "none" is a valid answer and writes\n` +
+            `   nothing here, so an empty log usually just means every recent commit answered "none".\n`);
+        return;
+    }
+    console.log('');
+    if (graphEntries.length) {
+        const clusters = (0, feedback_1.clusterGraphFeedback)(graphEntries);
+        console.log(`${BOLD}Graph feedback${RESET}  ${DIM}${graphEntries.length} report(s) in ${clusters.length} cluster(s)${opts.all ? '' : ' — unprocessed only, pass --all to include processed'}${RESET}`);
+        for (const c of clusters)
+            printGraphCluster(c);
+        console.log('');
+    }
+    if (productEntries.length) {
+        console.log(`${BOLD}Product feedback${RESET}  ${DIM}${productEntries.length} entries — never read by an agent, for you to act on${RESET}`);
+        printProductEntries(productEntries, 'devsmind_better');
+        printProductEntries(productEntries, 'dropped_and_why');
+        printProductEntries(productEntries, 'tools_used');
+        console.log('');
+    }
+    if (ruleCandidates.length) {
+        console.log(`${BOLD}Indexer rule candidates${RESET}  ${DIM}recurring patterns worth a permanent detector${RESET}`);
+        for (const r of ruleCandidates) {
+            console.log(`  ${BOLD}${r.evidence_count}x${RESET}  ${r.pattern}`);
+            for (const ex of r.examples.slice(0, 3))
+                console.log(`      ${DIM}${ex}${RESET}`);
+        }
+        console.log('');
+    }
+    if (graphEntries.length) {
+        console.log(`${DIM}Graph feedback is meant to be resolved by an AI agent's own batch graph-fix session`);
+        console.log(`(ask it to "run a graph-fix session" — it calls read_graph_feedback / mark_graph_feedback_processed).${RESET}\n`);
+    }
+}
+//# sourceMappingURL=feedback.js.map

package/dist/cli/feedback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback.js","sourceRoot":"","sources":["../../src/cli/feedback.ts"],"names":[],"mappings":"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"}

package/dist/cli/index.js

@@ -8,16 +8,22 @@ const view_1 = require("./view");
 const prune_1 = require("./prune");
 const sync_1 = require("./sync");
 const analyze_1 = require("./analyze");
+const diff_1 = require("./diff");
+const activity_1 = require("./activity");
+const feedback_1 = require("./feedback");
 const workflow_1 = require("./workflow");
 const mcp_1 = require("./integrations/mcp");
 const memory_1 = require("./integrations/memory");
 const runner_1 = require("./runner");
+const describe_1 = require("./describe");
+const embed_1 = require("./embed");
 const server_1 = require("../mcp/server");
+const version_1 = require("../utils/version");
 const program = new commander_1.Command();
 program
     .name('devsmind')
     .description('DevsMind — Team AI Brain CLI')
-    .version('1.0.0', '-v, --version');
+    .version(version_1.DEVSMIND_VERSION, '-v, --version');
 program
     .command('init')
     .description('Initialize a new DevsMind brain or update repository paths')
@@ -37,7 +43,7 @@ program
     `  IDEs connect via: http://localhost:${server_1.DEVSMIND_PORT}/mcp`)
     .option('--stdio', 'Use stdio transport instead of HTTP (for direct IDE process injection)')
     .option('-p, --port <number>', `HTTP port to listen on (default: ${server_1.DEVSMIND_PORT})`, String(server_1.DEVSMIND_PORT))
-    .option('--path <devmind_path>', 'Explicit path to the .devmind directory (auto-detected from cwd by default) — used only for --sync/--analyze below')
+    .option('--path <devmind_path>', 'Explicit path to the .devmind directory the server binds to (auto-detected from cwd by default). The server serves this one project, so callers never pass a path.')
     .option('--sync', 'Run devsmind sync before starting the server')
     .option('--analyze', 'Run devsmind analyze before starting the server')
     .option('--fix', 'With --analyze, also apply safe automatic fixes')
@@ -55,8 +61,16 @@ program
         }
     }
     if (opts.stdio) {
-        // Stdio mode: IDE manages the process directly
-        (0, server_1.runStdioMcpServer)();
+        // Stdio mode: IDE manages the process directly. Errors here (e.g. a bad --path) must not
+        // be an unhandled throw — same clean-exit treatment as the HTTP branch below, just via
+        // stderr since stdout is the JSON-RPC pipe.
+        try {
+            (0, server_1.runStdioMcpServer)(opts.path);
+        }
+        catch (err) {
+            console.error(`❌ MCP Server failed to start: ${err.message}`);
+            process.exit(1);
+        }
     }
     else {
         // HTTP mode: IDE connects over the network
@@ -66,7 +80,7 @@ program
             process.exit(1);
         }
         try {
-            await (0, server_1.runHttpMcpServer)(port);
+            await (0, server_1.runHttpMcpServer)(port, opts.path);
         }
         catch (err) {
             const msg = err.message;
@@ -85,6 +99,7 @@ program
     .description('Get the AI workspace rule and place it in your tool (guided), or print it')
     .option('-p, --path <devmind_path>', 'Explicit path to the .devmind directory (auto-detected from cwd by default)')
     .option('--print', 'Just print the rule to stdout (no interactive placement)')
+    .option('--manual', 'Manual workflow style: AI searches/reads freely but only stages or commits when explicitly asked (default is automatic — stages and commits without being asked). Only needed with --print/non-interactive; the interactive flow asks.')
     .action(async (opts) => {
     try {
         await (0, rule_1.handleRule)(opts);
@@ -109,8 +124,9 @@ program
 });
 program
     .command('memory')
-    .description('Seed a tool\'s own persistent agent-memory/skills store (guided, per-tool)')
-    .option('-p, --path <devmind_path>', 'Explicit path to the .devmind directory (auto-detected from cwd by default)')
+    .description('Print one paste-able prompt asking your AI to remember the DevsMind workflow — writes nothing to disk')
+    .option('--print', 'Skip the interactive tool picker and print immediately (non-interactive use)')
+    .option('--tool <id>', 'Which tool\'s framing line to print (claude-code, cursor, antigravity, ...). The prompt itself is the same either way. Only used with --print/non-interactive; the interactive flow asks.')
     .action(async (opts) => {
     try {
         await (0, memory_1.handleMemory)(opts);
@@ -151,6 +167,112 @@ program
         process.exit(1);
     }
 });
+program
+    .command('describe')
+    .description('Backfill natural-language descriptions for existing nodes that predate the description requirement — what search_nodes needs to find code by natural language. Always safe to re-run (work queue is just "nodes with no description yet"); new nodes going forward get described via commit_changes\' gate + add_description instead, not this command.')
+    .option('-p, --path <devmind_path>', 'Explicit path to the .devmind directory (auto-detected from cwd by default)')
+    .option('--provider <provider>', 'LLM provider: "gemini", "vertex", or "ollama"', 'gemini')
+    .option('--model <name>', 'Model identifier (default: "gemini-2.0-flash", "gemini-1.5-flash", or "qwen2.5-coder")')
+    .option('--key <api_key>', 'API Key or Service Account file path (overrides GEMINI_API_KEY / GOOGLE_APPLICATION_CREDENTIALS)')
+    .option('--url <url>', 'Ollama server endpoint (default: "http://localhost:11434")')
+    .option('--rpm <number>', 'Max LLM requests per minute, proactively paced (default: unthrottled)')
+    .option('--batch-size <number>', 'Nodes described per LLM call (default: 25)')
+    .option('--dry-run', 'List pending nodes without calling the LLM or writing anything')
+    .action(async (opts) => {
+    try {
+        await (0, describe_1.handleDescribe)({
+            path: opts.path,
+            provider: opts.provider,
+            model: opts.model,
+            key: opts.key,
+            url: opts.url,
+            rpm: opts.rpm ? parseInt(opts.rpm, 10) : undefined,
+            batchSize: opts.batchSize ? parseInt(opts.batchSize, 10) : undefined,
+            dryRun: !!opts.dryRun
+        });
+    }
+    catch (err) {
+        console.error(`❌ Describe failed: ${err.message}`);
+        process.exit(1);
+    }
+});
+program
+    .command('embed')
+    .description('Compute semantic (vector) search embeddings for every described node that lacks a current one. Fully local/offline — no LLM credentials needed, inference runs on-device. Always safe to re-run (work queue is "needs a vector"); new/edited descriptions going forward get auto-embedded via commit_changes/add_description/describe instead, not this command — it\'s only for clearing an existing backlog or a model upgrade (--force).')
+    .option('-p, --path <devmind_path>', 'Explicit path to the .devmind directory (auto-detected from cwd by default)')
+    .option('--batch-size <number>', 'Nodes embedded per inference call (default: 32)')
+    .option('--dry-run', 'List pending nodes without running inference or writing anything')
+    .option('--force', 'Re-embed every described node regardless of current vector state (use after a model upgrade)')
+    .action(async (opts) => {
+    try {
+        await (0, embed_1.handleEmbed)({
+            path: opts.path,
+            batchSize: opts.batchSize ? parseInt(opts.batchSize, 10) : undefined,
+            dryRun: !!opts.dryRun,
+            force: !!opts.force
+        });
+    }
+    catch (err) {
+        console.error(`❌ Embed failed: ${err.message}`);
+        process.exit(1);
+    }
+});
+program
+    .command('diff <node_id>')
+    .description('Show what changed in an entity, red/green, with the reasoning recorded for it')
+    .option('-p, --path <devmind_path>', 'Explicit path to the .devmind directory (auto-detected from cwd by default)')
+    .action(async (nodeId, opts) => {
+    try {
+        await (0, diff_1.handleDiff)(nodeId, opts);
+    }
+    catch (err) {
+        console.error(`❌ Diff failed: ${err.message}`);
+        process.exit(1);
+    }
+});
+program
+    .command('revert <node_id>')
+    .description('Undo an entity\'s most recent recorded edit and erase it from history')
+    .option('-p, --path <devmind_path>', 'Explicit path to the .devmind directory (auto-detected from cwd by default)')
+    .option('-y, --yes', 'Skip the confirmation prompt')
+    .action(async (nodeId, opts) => {
+    try {
+        await (0, diff_1.handleRevert)(nodeId, opts);
+    }
+    catch (err) {
+        console.error(`❌ Revert failed: ${err.message}`);
+        process.exit(1);
+    }
+});
+program
+    .command('activity')
+    .description('Show your local activity timeline — sessions and messages by day (local only, never pushed)')
+    .option('-p, --path <devmind_path>', 'Explicit path to the .devmind directory (auto-detected from cwd by default)')
+    .option('--since <days>', 'Only show messages from the last N days')
+    .action(async (opts) => {
+    try {
+        await (0, activity_1.handleActivity)(opts);
+    }
+    catch (err) {
+        console.error(`❌ Activity failed: ${err.message}`);
+        process.exit(1);
+    }
+});
+program
+    .command('feedback')
+    .description('Show feedback recorded from commit_changes — graph problems, product feedback, and indexer rule candidates (local only, never pushed)')
+    .option('-p, --path <devmind_path>', 'Explicit path to the .devmind directory (auto-detected from cwd by default)')
+    .option('--since <days>', 'Only show entries from the last N days')
+    .option('--all', 'Include graph-feedback entries already marked processed (default: unprocessed only)')
+    .action(async (opts) => {
+    try {
+        await (0, feedback_1.handleFeedback)(opts);
+    }
+    catch (err) {
+        console.error(`❌ Feedback failed: ${err.message}`);
+        process.exit(1);
+    }
+});
 program
     .command('workflow')
     .description('List, view, pause, and resume persistent feature workflows (interactive)')
@@ -200,6 +322,8 @@ program
     .option('--from-scratch', 'Wipe ALL nodes, connections, history, and graph/history folders, then reindex from zero. Asks for confirmation unless --yes is passed.')
     .option('--nodes-only', 'Only run Phase 1 (node/code extraction). No connections are built or touched.')
     .option('--edges-only', 'Only run Phase 2 (connection resolution). Wipes existing connections and rebuilds them fresh across all current nodes. Requires nodes to already exist.')
+    .option('--describe', 'Only meaningful with --nodes-only: also run Phase 3 (description backfill) right after that structure-only extraction, using the SAME credentials — an optional extension when you want a --nodes-only run to be searchable immediately instead of running `devsmind describe` separately later. On a FULL run (neither --nodes-only nor --edges-only), Phase 3 always runs regardless of this flag — descriptions are mandatory there, since Phase 1/2 never write one and an undescribed "finished" index is not actually searchable by search_nodes\' description/vector layers. Not allowed with --edges-only (which never extracts nodes or resolves credentials).')
+    .option('--describe-batch-size <number>', 'Nodes described per LLM call during Phase 3 (default: 25)')
     .option('--repos <names>', 'Comma-separated repo names to restrict this run to (standalone mode only). Composes with --nodes-only / --edges-only, or full. Not allowed with --from-scratch.')
     .option('--rpm <number>', 'Max LLM requests per minute, paced proactively to avoid 429s (default: unthrottled — fires as fast as possible)')
     .option('--yes', 'Skip the confirmation prompt for --from-scratch')
@@ -215,6 +339,10 @@ program
             console.error('❌ Error: --from-scratch and --edges-only cannot be used together — --from-scratch wipes nodes, so there would be nothing to build edges from. Use --from-scratch alone, or --from-scratch --nodes-only, then --edges-only separately.');
             process.exit(1);
         }
+        if (opts.describe && opts.edgesOnly) {
+            console.error('❌ Error: --describe and --edges-only cannot be used together — --edges-only never extracts nodes or resolves LLM credentials, so there is nothing new to describe. Run `devsmind describe` separately if you need to backfill descriptions after an --edges-only run.');
+            process.exit(1);
+        }
         try {
             await (0, runner_1.runBackgroundIndexing)({
                 devmindPath,
@@ -228,6 +356,8 @@ program
                 fromScratch: !!opts.fromScratch,
                 nodesOnly: !!opts.nodesOnly,
                 edgesOnly: !!opts.edgesOnly,
+                describe: !!opts.describe,
+                describeBatchSize: opts.describeBatchSize ? parseInt(opts.describeBatchSize, 10) : undefined,
                 repos: opts.repos ? opts.repos.split(',').map(s => s.trim()).filter(Boolean) : undefined,
                 rpm: opts.rpm ? parseInt(opts.rpm, 10) : undefined,
                 yes: !!opts.yes
@@ -243,8 +373,8 @@ program
         console.log(`   Brain : ${resolved}`);
         console.log(`\n📋 To index your codebase, tell your AI assistant:\n`);
         console.log(`   "Call devsmind.index_start with devmind_path = ${resolved}"`);
-        console.log(`   "Then read every file it returns and call stage_change for each entity, then commit_changes."`);
-        console.log(`   "Checkpoint every 10 files. Call index_complete when done."`);
+        console.log(`   "It already parses the code itself — describe each node it hands you with add_description, then call index_continue."`);
+        console.log(`   "Repeat index_continue until every file is extracted and described, then call index_complete."`);
         console.log(`   "NEVER use or write external scripts (like Python) to index files."\n`);
         console.log(`   Or run it locally in the background using:\n`);
         console.log(`   devsmind index --run --provider gemini --key YOUR_GEMINI_KEY`);