zelari-code 0.6.2 → 0.7.8

package/dist/cli/workspace/stubs.js

@@ -1,18 +1,19 @@
 /**
  * workspace/stubs.ts — CLI workspace tool stubs.
  *
- * Implements the 9 council workspace tools (`createPhase`, `createTask`,
- * `updateTask`, `addIdea`, `createMilestone`, `createDocument`,
- * `searchDocuments`, `linkDocuments`, `getDocumentBacklinks`) as
- * filesystem-backed stubs that persist to `.zelari/` at the project root.
+ * Implements the 10 council workspace tools (`createPlan`, `createPhase`,
+ * `createTask`, `updateTask`, `addIdea`, `createMilestone`,
+ * `createDocument`, `searchDocuments`, `linkDocuments`,
+ * `getDocumentBacklinks`) as filesystem-backed stubs that persist to
+ * `.zelari/` at the project root.
  *
  * Replaces the AnathemaBrain Electron-only ctx (e.g. `ctx.addIdea(...)`)
  * with a `WorkspaceContext` that writes Markdown + YAML frontmatter files.
  *
  * @see docs/plans/2026-07-01-council-workspace-cli-stubs.md
  */
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readdirSync, writeFileSync, readFileSync, mkdirSync, renameSync } from 'node:fs';
+import { join, basename, dirname, relative } from 'node:path';
 import { workspaceMutex } from './storage.js';
 import { resolveWorkspaceRoot, workspaceFile, workspaceArtifact, projectName as deriveProjectName, } from './paths.js';
 import { Storage } from './storage.js';
@@ -29,49 +30,64 @@ export function createWorkspaceContext(projectRoot = process.cwd()) {
         storage: new Storage(),
     };
 }
+/** Path of the machine-readable plan store (source of truth since v0.7.3). */
+function planJsonPath(ctx) {
+    return join(ctx.rootDir, 'plan.json');
+}
 function readPlan(ctx) {
+    // v0.7.3: the plan's source of truth is plan.json. The previous
+    // implementation round-tripped the whole summary through the handwritten
+    // YAML-subset frontmatter of plan.md; free-text names/descriptions with
+    // colons, commas, and apostrophes corrupted the flow-map parse, so a phase
+    // written by createPhase could be unreadable one call later ("Phase not
+    // found" right after "Phase created", live test 2026-07-02). plan.md is
+    // now only the human-readable rendering.
+    const jsonPath = planJsonPath(ctx);
+    if (existsSync(jsonPath)) {
+        try {
+            const parsed = JSON.parse(readFileSync(jsonPath, 'utf8'));
+            return {
+                phases: Array.isArray(parsed.phases) ? parsed.phases : [],
+                tasks: Array.isArray(parsed.tasks) ? parsed.tasks : [],
+                milestones: Array.isArray(parsed.milestones) ? parsed.milestones : [],
+            };
+        }
+        catch {
+            // Corrupt plan.json — fall through to the legacy migration read.
+        }
+    }
+    // Legacy migration: one best-effort parse of the old plan.md frontmatter
+    // (pre-v0.7.3 files). The next writePlan persists it as plan.json.
     const path = workspaceFile(ctx.rootDir, 'plan');
     const doc = ctx.storage.readIfExists(path);
     if (!doc)
         return { phases: [], tasks: [], milestones: [] };
-    // The plan.md body is markdown; the frontmatter is a single "summary" object.
-    // We treat the file as a single doc with `kind: plan` and a body listing items.
-    // For our needs we just persist individual items to disk separately.
-    // But for v1 we serialize the entire plan as one doc with a list of phases/tasks/milestones in the body.
-    // Simpler: we store ONE phase/task/milestone per file under `.zelari/plan/<id>.md`.
-    // TODO: refactor for v2 if plan gets large.
-    const items = [];
-    // For now, parse the doc.meta as the entire plan state (kind=plan, has children fields).
     const meta = doc.meta;
-    if (meta.phases)
-        items.push(...meta.phases);
-    return { phases: meta.phases ?? [], tasks: meta.tasks ?? [], milestones: meta.milestones ?? [] };
+    return {
+        phases: Array.isArray(meta.phases) ? meta.phases : [],
+        tasks: Array.isArray(meta.tasks) ? meta.tasks : [],
+        milestones: Array.isArray(meta.milestones) ? meta.milestones : [],
+    };
 }
 /**
- * Write the entire plan (phases + tasks + milestones) as one file.
- * Simpler than per-item files for v1.
+ * Write the entire plan (phases + tasks + milestones):
+ *   - plan.json — lossless machine-readable source of truth (atomic write).
+ *   - plan.md   — human-readable rendering only (no machine-parsed arrays in
+ *                 the frontmatter, so the fragile YAML round-trip is gone).
  */
 function writePlan(ctx, summary) {
-    const path = workspaceFile(ctx.rootDir, 'plan');
-    const meta = {
-        kind: 'phase',
-        id: '_plan_summary',
-        order: -1,
-        tags: ['plan-summary'],
-    };
-    // We pack phases/tasks/milestones in a synthetic frontmatter using flow-style.
-    // Easier: just store each item's key fields inline as comments? No — keep them
-    // parseable. We use a special frontmatter shape with arrays.
+    const jsonPath = planJsonPath(ctx);
+    mkdirSync(dirname(jsonPath), { recursive: true });
+    const tmp = jsonPath + '.tmp-' + process.pid;
+    writeFileSync(tmp, JSON.stringify(summary, null, 2), 'utf8');
+    renameSync(tmp, jsonPath);
+    const mdPath = workspaceFile(ctx.rootDir, 'plan');
     const summaryMeta = {
         kind: 'plan-summary',
         id: '_plan',
         updatedAt: new Date().toISOString(),
-        phases: summary.phases,
-        tasks: summary.tasks,
-        milestones: summary.milestones,
     };
-    const body = renderPlanBody(summary);
-    ctx.storage.write(path, summaryMeta, body);
+    ctx.storage.write(mdPath, summaryMeta, renderPlanBody(summary));
 }
 /** Render the plan.md body in human-readable Markdown. */
 function renderPlanBody(summary) {
@@ -149,6 +165,119 @@ function nextAdrId(ctx) {
 function slugify(s) {
     return s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 60);
 }
+/** Add a phase record. Returns the phase id and whether it was newly created. */
+function addPhaseRecord(summary, input) {
+    const id = slugify(input.name) || `phase-${input.order}`;
+    if (summary.phases.some((p) => p.id === id)) {
+        return { id, created: false };
+    }
+    summary.phases.push({
+        kind: 'phase',
+        id,
+        name: input.name,
+        description: input.description,
+        order: input.order,
+        color: input.color,
+    });
+    return { id, created: true };
+}
+/**
+ * Add a task record + its per-task file. With `dedupe: true` a task whose
+ * title already exists in the same phase is treated as the same task and
+ * NOT re-added (protects the createPlan batch path from duplicating tasks
+ * that a partial itemized run already persisted). The itemized createTask
+ * stub keeps `dedupe: false` for backward compatibility.
+ */
+function addTaskRecord(ctx, summary, phaseId, t, options) {
+    const slug = slugify(t.title);
+    if (options.dedupe) {
+        const existing = summary.tasks.find((k) => k.phaseId === phaseId && k.id.replace(/-\d+$/, '') === `${phaseId}-${slug}`);
+        if (existing)
+            return { id: existing.id, created: false };
+    }
+    const id = `${phaseId}-${slug}-${summary.tasks.filter((k) => k.phaseId === phaseId).length + 1}`;
+    summary.tasks.push({
+        kind: 'task',
+        id,
+        // v0.7.3: keep the human-readable title in plan.json so
+        // buildPlanSummary can render it in the system prompt.
+        name: t.title,
+        phaseId,
+        status: 'pending',
+        priority: t.priority,
+    });
+    const taskPath = join(ctx.rootDir, 'plan-tasks', `${id}.md`);
+    const meta = {
+        kind: 'task',
+        id,
+        phaseId,
+        status: 'pending',
+        priority: t.priority,
+        tags: t.fileRefs,
+    };
+    const body = [
+        `# ${t.title}`,
+        '',
+        t.description,
+        '',
+        `## File references`,
+        ...t.fileRefs.map((f) => `- \`${f}\``),
+        '',
+        `## Acceptance criteria`,
+        ...t.acceptance.map((a) => `- ${a}`),
+        '',
+        `## QA scenario`,
+        '',
+        t.qaScenario || '_(not specified)_',
+        '',
+    ].join('\n');
+    ctx.storage.write(taskPath, meta, body);
+    return { id, created: true };
+}
+/** Add a milestone record + its file. Returns id and whether newly created. */
+function addMilestoneRecord(ctx, summary, input) {
+    const id = `m-${slugify(input.title)}`;
+    if (summary.milestones.some((m) => m.id === id)) {
+        return { id, created: false };
+    }
+    const version = input.targetVersion ?? input.dueDate ?? 'TBD';
+    summary.milestones.push({
+        kind: 'milestone',
+        id,
+        name: input.title,
+        description: input.description,
+        dueDate: input.dueDate,
+        targetVersion: version,
+    });
+    const path = join(ctx.rootDir, 'milestones', `${id}.md`);
+    const meta = {
+        kind: 'milestone',
+        id,
+        name: input.title,
+        description: input.description,
+        dueDate: input.dueDate,
+        targetVersion: version,
+    };
+    const body = [
+        `# Milestone: ${input.title}`,
+        '',
+        input.description,
+        '',
+        `Target version: ${version}`,
+        '',
+    ].join('\n');
+    ctx.storage.write(path, meta, body);
+    return { id, created: true };
+}
+/**
+ * Read-only view of the current plan (phases + tasks + milestones).
+ * Exported for the built-in complete-design fallback (completeDesign.ts)
+ * so it can inspect per-phase task coverage without duplicating the
+ * plan.json / legacy plan.md read logic.
+ */
+export function readPlanSummary(ctx) {
+    return readPlan(ctx);
+}
 // ── Stub factory ─────────────────────────────────────────────────────
 /**
  * Create all 9 workspace stubs bound to the given context.
@@ -158,6 +287,7 @@ function slugify(s) {
  */
 export function createWorkspaceStubs(ctx) {
     return [
+        createPlanStub(ctx),
         createPhaseStub(ctx),
         createTaskStub(ctx),
         updateTaskStub(ctx),
@@ -170,6 +300,81 @@ export function createWorkspaceStubs(ctx) {
     ];
 }
 // ── Individual stubs ──────────────────────────────────────────────────
+/**
+ * v0.7.8 — Batch plan creation. One tool call persists the WHOLE plan:
+ * every phase, the tasks nested under each phase, and the milestone.
+ *
+ * Rationale: the itemized contract (4×createPhase + 12×createTask +
+ * 1×createMilestone = 17 sequential tool calls) exceeds what mid-tier
+ * council models reliably emit in one turn (composer-2.5 persisted ≤7 of
+ * 17 in the 2026-07-03 live tests, see HANDOFF.md). A single structured
+ * call collapses the whole contract into one emission, which the same
+ * models satisfy reliably (proven by the 1-call retry paths of Minosse
+ * and Lucifero).
+ */
+function createPlanStub(ctx) {
+    return {
+        name: 'createPlan',
+        description: 'Create the FULL project plan in one call: all phases, the tasks nested under each phase, and the target milestone. ' +
+            'Preferred over itemized createPhase/createTask/createMilestone calls — one createPlan call persists everything atomically.',
+        category: 'project',
+        parameters: [],
+        execute: async (args) => {
+            return workspaceMutex.run(`${ctx.rootDir}:plan`, () => {
+                const rawPhases = Array.isArray(args['phases'])
+                    ? args['phases']
+                    : [];
+                if (rawPhases.length === 0) {
+                    return 'createPlan requires a non-empty "phases" array (each phase: { name, description, order, color, tasks: [{ title, description, fileRefs, acceptance, qaScenario, priority }] }).';
+                }
+                const summary = readPlan(ctx);
+                let phasesCreated = 0;
+                let tasksCreated = 0;
+                const phaseIds = [];
+                rawPhases.forEach((rawPhase, idx) => {
+                    const { id: phaseId, created } = addPhaseRecord(summary, {
+                        name: rawPhase['name'] ?? `Phase ${idx + 1}`,
+                        description: rawPhase['description'] ?? '',
+                        order: rawPhase['order'] ?? idx + 1,
+                        color: rawPhase['color'] ?? '#3b82f6',
+                    });
+                    if (created)
+                        phasesCreated += 1;
+                    phaseIds.push(phaseId);
+                    const rawTasks = Array.isArray(rawPhase['tasks'])
+                        ? rawPhase['tasks']
+                        : [];
+                    for (const rawTask of rawTasks) {
+                        const { created: taskCreated } = addTaskRecord(ctx, summary, phaseId, {
+                            title: rawTask['title'] ?? 'New Task',
+                            description: rawTask['description'] ?? '',
+                            fileRefs: rawTask['fileRefs'] ?? rawTask['files'] ?? [],
+                            acceptance: rawTask['acceptance'] ?? [],
+                            qaScenario: rawTask['qaScenario'] ?? rawTask['qa'] ?? '',
+                            priority: (rawTask['priority'] ?? 'medium'),
+                        }, { dedupe: true });
+                        if (taskCreated)
+                            tasksCreated += 1;
+                    }
+                });
+                let milestonesCreated = 0;
+                const rawMilestone = args['milestone'];
+                if (rawMilestone && typeof rawMilestone === 'object') {
+                    const { created } = addMilestoneRecord(ctx, summary, {
+                        title: rawMilestone['title'] ?? 'v0.1.0 design-complete',
+                        description: rawMilestone['description'] ?? '',
+                        dueDate: rawMilestone['dueDate'],
+                        targetVersion: rawMilestone['targetVersion'],
+                    });
+                    if (created)
+                        milestonesCreated += 1;
+                }
+                writePlan(ctx, summary);
+                return `Plan created: ${phasesCreated} phases, ${tasksCreated} tasks, ${milestonesCreated} milestone(s). Phase ids: ${phaseIds.join(', ')}.`;
+            });
+        },
+    };
+}
 function createPhaseStub(ctx) {
     return {
         name: 'createPhase',
@@ -179,23 +384,17 @@ function createPhaseStub(ctx) {
         execute: async (args) => {
             return workspaceMutex.run(`${ctx.rootDir}:plan`, () => {
                 const name = args['name'] ?? 'New Phase';
-                const description = args['description'] ?? '';
                 const order = args['order'] ?? 0;
-                const color = args['color'] ?? '#3b82f6';
-                const id = slugify(name) || `phase-${order}`;
                 const summary = readPlan(ctx);
-                // Check uniqueness
-                if (summary.phases.some((p) => p.id === id)) {
-                    return `Phase "${id}" already exists.`;
-                }
-                summary.phases.push({
-                    kind: 'phase',
-                    id,
+                const { id, created } = addPhaseRecord(summary, {
                     name,
-                    description,
+                    description: args['description'] ?? '',
                     order,
-                    color,
+                    color: args['color'] ?? '#3b82f6',
                 });
+                if (!created) {
+                    return `Phase "${id}" already exists.`;
+                }
                 writePlan(ctx, summary);
                 return `Phase "${name}" created (id: ${id}, order: ${order}).`;
             });
@@ -212,53 +411,21 @@ function createTaskStub(ctx) {
             return workspaceMutex.run(`${ctx.rootDir}:plan`, () => {
                 const phaseId = args['phaseId'] ?? args['phase'];
                 const title = args['title'] ?? 'New Task';
-                const description = args['description'] ?? '';
-                const fileRefs = args['fileRefs'] ?? args['files'] ?? [];
-                const acceptance = args['acceptance'] ?? [];
-                const qaScenario = args['qaScenario'] ?? args['qa'] ?? '';
-                const priority = args['priority'] ?? 'medium';
                 if (!phaseId)
                     return 'Task requires a phaseId.';
                 const summary = readPlan(ctx);
                 if (!summary.phases.some((p) => p.id === phaseId)) {
                     return `Phase "${phaseId}" not found. Create it first via /createPhase.`;
                 }
-                const id = `${phaseId}-${slugify(title)}-${summary.tasks.filter((t) => t.phaseId === phaseId).length + 1}`;
-                summary.tasks.push({
-                    kind: 'task',
-                    id,
-                    phaseId,
-                    status: 'pending',
-                    priority: priority,
-                });
+                const { id } = addTaskRecord(ctx, summary, phaseId, {
+                    title,
+                    description: args['description'] ?? '',
+                    fileRefs: args['fileRefs'] ?? args['files'] ?? [],
+                    acceptance: args['acceptance'] ?? [],
+                    qaScenario: args['qaScenario'] ?? args['qa'] ?? '',
+                    priority: (args['priority'] ?? 'medium'),
+                }, { dedupe: false });
                 writePlan(ctx, summary);
-                // Also write the task body to a per-task file so it doesn't get lost
-                const taskPath = join(ctx.rootDir, 'plan-tasks', `${id}.md`);
-                const meta = {
-                    kind: 'task',
-                    id,
-                    phaseId,
-                    status: 'pending',
-                    priority: priority,
-                    tags: fileRefs,
-                };
-                const body = [
-                    `# ${title}`,
-                    '',
-                    description,
-                    '',
-                    `## File references`,
-                    ...fileRefs.map((f) => `- \`${f}\``),
-                    '',
-                    `## Acceptance criteria`,
-                    ...acceptance.map((a) => `- ${a}`),
-                    '',
-                    `## QA scenario`,
-                    '',
-                    qaScenario || '_(not specified)_',
-                    '',
-                ].join('\n');
-                ctx.storage.write(taskPath, meta, body);
                 return `Task "${title}" created (id: ${id}) under phase "${phaseId}".`;
             });
         },
@@ -273,12 +440,21 @@ function updateTaskStub(ctx) {
         execute: async (args) => {
             return workspaceMutex.run(`${ctx.rootDir}:plan`, () => {
                 const taskId = args['taskId'];
-                const status = args['status'];
-                if (!taskId || !status)
+                const rawStatus = args['status'];
+                if (!taskId || !rawStatus)
                     return 'updateTask requires taskId and status.';
                 const valid = ['pending', 'in_progress', 'done', 'blocked'];
-                if (!valid.includes(status))
-                    return `Invalid status: ${status}. Must be one of: ${valid.join(', ')}.`;
+                // v0.7.3: models routinely use kanban vocabulary ("todo", "completed")
+                // — map the common synonyms instead of erroring on each attempt.
+                const aliases = {
+                    'todo': 'pending', 'to-do': 'pending', 'open': 'pending', 'backlog': 'pending',
+                    'in-progress': 'in_progress', 'in progress': 'in_progress', 'doing': 'in_progress', 'started': 'in_progress', 'active': 'in_progress',
+                    'complete': 'done', 'completed': 'done', 'finished': 'done', 'closed': 'done', 'resolved': 'done',
+                    'stuck': 'blocked', 'waiting': 'blocked', 'on-hold': 'blocked', 'on hold': 'blocked',
+                };
+                const status = valid.includes(rawStatus) ? rawStatus : aliases[rawStatus.toLowerCase()];
+                if (!status)
+                    return `Invalid status: ${rawStatus}. Must be one of: ${valid.join(', ')}.`;
                 const summary = readPlan(ctx);
                 const task = summary.tasks.find((t) => t.id === taskId);
                 if (!task)
@@ -346,41 +522,17 @@ function createMilestoneStub(ctx) {
         execute: async (args) => {
             return workspaceMutex.run(`${ctx.rootDir}:plan`, () => {
                 const title = args['title'] ?? 'New Milestone';
-                const description = args['description'] ?? '';
-                const dueDate = args['dueDate'];
-                const id = `m-${slugify(title)}`;
                 const summary = readPlan(ctx);
-                if (summary.milestones.some((m) => m.id === id))
-                    return `Milestone "${id}" already exists.`;
-                const version = args['targetVersion'] ?? dueDate ?? 'TBD';
-                summary.milestones.push({
-                    kind: 'milestone',
-                    id,
-                    name: title,
-                    description,
-                    dueDate,
-                    targetVersion: version,
+                const { id, created } = addMilestoneRecord(ctx, summary, {
+                    title,
+                    description: args['description'] ?? '',
+                    dueDate: args['dueDate'],
+                    targetVersion: args['targetVersion'],
                 });
+                if (!created)
+                    return `Milestone "${id}" already exists.`;
                 writePlan(ctx, summary);
-                // Also write the body
-                const path = join(ctx.rootDir, 'milestones', `${id}.md`);
-                const meta = {
-                    kind: 'milestone',
-                    id,
-                    name: title,
-                    description,
-                    dueDate,
-                    targetVersion: version,
-                };
-                const body = [
-                    `# Milestone: ${title}`,
-                    '',
-                    description,
-                    '',
-                    `Target version: ${version}`,
-                    '',
-                ].join('\n');
-                ctx.storage.write(path, meta, body);
+                const version = summary.milestones.find((m) => m.id === id)?.targetVersion ?? 'TBD';
                 return `Milestone "${title}" created (id: ${id}, version: ${version}).`;
             });
         },
@@ -397,7 +549,12 @@ function createDocumentStub(ctx) {
                 const title = args['title'] ?? 'New Document';
                 const content = args['content'] ?? '';
                 const tags = args['tags'] ?? [];
-                const id = slugify(title) || `doc-${Date.now()}`;
+                // v0.7.8: models routinely pass the FILENAME as title ("risks.md",
+                // "synthesis.md"), which slugified to "risks-md"/"synthesis-md" and
+                // produced duplicated artifacts (docs/risks-md.md next to risks.md,
+                // HANDOFF 2026-07-03 §5.1). Strip the extension before slugifying.
+                const normalizedTitle = title.replace(/\.(md|markdown)\s*$/i, '');
+                const id = slugify(normalizedTitle) || `doc-${Date.now()}`;
                 const path = workspaceArtifact(ctx.rootDir, 'docs', id);
                 const meta = {
                     kind: 'doc',
@@ -411,21 +568,52 @@ function createDocumentStub(ctx) {
         },
     };
 }
+/**
+ * After this many searchDocuments calls in one council run, every further
+ * result carries a nudge to stop searching and act. Live test 2026-07-02:
+ * one member burned ~25 near-identical searches (each phrased slightly
+ * differently, so the duplicate-call cache never tripped) before doing any
+ * actual work.
+ */
+const SEARCH_NUDGE_THRESHOLD = 5;
 function searchDocumentsStub(ctx) {
+    let callCount = 0;
     return {
         name: 'searchDocuments',
-        description: 'Search all workspace documents (`.zelari/**`) for a keyword. Returns matching files with snippets.',
+        description: 'Search all workspace documents (`.zelari/**`) for a keyword. Returns matching files with snippets. ' +
+            'Search AT MOST 2-3 times, then act on the results: read the matched files with read_file instead of rephrasing the same search.',
         category: 'analysis',
         parameters: [],
         execute: async (args) => {
-            const query = (args['query'] ?? '').toLowerCase();
+            callCount++;
+            const nudge = callCount > SEARCH_NUDGE_THRESHOLD
+                ? `[note] This is searchDocuments call #${callCount} in this run — STOP searching. Read the files you already found with read_file and act on them.\n\n`
+                : '';
+            const rawQuery = (args['query'] ?? '').trim();
             const limit = args['limit'] ?? 5;
-            if (!query)
+            if (!rawQuery)
                 return 'searchDocuments requires a query.';
+            // v0.7.3: models routinely write boolean-ish queries ("plan OR phase OR
+            // milestone"). The previous implementation substring-matched the WHOLE
+            // query string, so every OR query — and any multi-word query that didn't
+            // appear verbatim — returned "No matches" even for documents created
+            // seconds earlier. Match any OR-phrase first, then fall back to
+            // any-word matching per file.
+            const phrases = rawQuery
+                .toLowerCase()
+                .split(/\s+or\s+/i)
+                .map((p) => p.trim())
+                .filter((p) => p.length > 0);
+            const words = rawQuery
+                .toLowerCase()
+                .split(/[^a-z0-9_-]+/)
+                .filter((w) => w.length >= 3 && w !== 'or' && w !== 'and' && w !== 'the');
             const files = [
                 ...ctx.storage.listMarkdown(join(ctx.rootDir, 'decisions')),
                 ...ctx.storage.listMarkdown(join(ctx.rootDir, 'docs')),
                 ...ctx.storage.listMarkdown(join(ctx.rootDir, 'reviews')),
+                ...ctx.storage.listMarkdown(join(ctx.rootDir, 'plan-tasks')),
+                ...ctx.storage.listMarkdown(join(ctx.rootDir, 'milestones')),
                 workspaceFile(ctx.rootDir, 'plan'),
                 workspaceFile(ctx.rootDir, 'risks'),
             ];
@@ -433,20 +621,40 @@ function searchDocumentsStub(ctx) {
             for (const file of files) {
                 if (!existsSync(file))
                     continue;
-                const content = readFileSync(file, 'utf8').toLowerCase();
-                const idx = content.indexOf(query);
+                const raw = readFileSync(file, 'utf8');
+                const content = raw.toLowerCase();
+                let idx = -1;
+                let matchLen = 0;
+                for (const p of phrases) {
+                    const i = content.indexOf(p);
+                    if (i >= 0) {
+                        idx = i;
+                        matchLen = p.length;
+                        break;
+                    }
+                }
+                if (idx < 0) {
+                    for (const w of words) {
+                        const i = content.indexOf(w);
+                        if (i >= 0) {
+                            idx = i;
+                            matchLen = w.length;
+                            break;
+                        }
+                    }
+                }
                 if (idx < 0)
                     continue;
                 const start = Math.max(0, idx - 40);
-                const end = Math.min(content.length, idx + query.length + 40);
-                const snippet = '…' + readFileSync(file, 'utf8').slice(start, end).replace(/\n/g, ' ').trim() + '…';
-                results.push({ path: file, snippet });
+                const end = Math.min(raw.length, idx + matchLen + 40);
+                const snippet = '…' + raw.slice(start, end).replace(/\n/g, ' ').trim() + '…';
+                results.push({ path: relative(ctx.rootDir, file) || basename(file), snippet });
                 if (results.length >= limit)
                     break;
             }
             if (results.length === 0)
-                return `No matches for "${query}" in workspace.`;
-            return results.map((r) => `[${r.path}]\n${r.snippet}`).join('\n\n');
+                return `${nudge}No matches for "${rawQuery}" in workspace.`;
+            return nudge + results.map((r) => `[${r.path}]\n${r.snippet}`).join('\n\n');
         },
     };
 }
@@ -458,8 +666,13 @@ function linkDocumentsStub(ctx) {
         parameters: [],
         execute: async (args) => {
             return workspaceMutex.run(`${ctx.rootDir}:link`, () => {
-                const fromId = args['fromId'];
-                const toId = args['toId'];
+                // v0.7.8: the provider-facing JSON schema (toolSchemas.ts) advertises
+                // sourceId/targetPathOrTitle — accept those aliases too, otherwise
+                // every schema-conformant call fails with "requires fromId and toId".
+                const fromId = args['fromId'] ?? args['sourceId'];
+                const toId = args['toId']
+                    ?? args['targetId']
+                    ?? args['targetPathOrTitle'];
                 if (!fromId || !toId)
                     return 'linkDocuments requires fromId and toId.';
                 // Find the source file by id
@@ -497,7 +710,8 @@ function getDocumentBacklinksStub(ctx) {
         category: 'analysis',
         parameters: [],
         execute: async (args) => {
-            const targetId = args['targetId'];
+            // v0.7.8: the provider-facing JSON schema advertises `id` — accept it.
+            const targetId = args['targetId'] ?? args['id'];
             if (!targetId)
                 return 'getDocumentBacklinks requires targetId.';
             const allFiles = [