@pathmode/mcp-server 1.7.0 → 1.9.0

package/dist/index.js

@@ -33598,6 +33598,39 @@ class PathmodeClient {
         }
         return response;
     }
+    /**
+     * Announce this client to the server once at launch.
+     *
+     * The server otherwise hears nothing until a tool fires, so a user who installs
+     * the connector and never invokes anything is indistinguishable from one who
+     * never installed it at all. That ambiguity hid the shape of the biggest drop-off
+     * in the funnel: 73% of people who created a key had no successful call, and we
+     * could not tell whether they were stuck on setup or simply idle.
+     *
+     * Silent by contract. Never throws, never writes to stdout (stdout belongs to
+     * JSON-RPC), and never blocks startup — a failed handshake must not cost the user
+     * a working server. Deliberately does NOT go through `fetch()` above, which logs
+     * to stderr and throws on non-2xx.
+     */
+    async handshake(clientInfo = {}) {
+        try {
+            const res = await fetch(`${this.apiUrl}/api/v1/connection/handshake`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(clientInfo),
+                signal: AbortSignal.timeout(5000),
+            });
+            if (isDebug)
+                console.error(`[pathmode-mcp] handshake: ${res.status}`);
+        }
+        catch (e) {
+            if (isDebug)
+                console.error(`[pathmode-mcp] handshake failed (ignored): ${e}`);
+        }
+    }
     async listIntents(status) {
         const params = status ? `?status=${status}` : '';
         const res = await this.fetch(`/intents${params}`);
@@ -33626,6 +33659,13 @@ class PathmodeClient {
         });
         return res.json();
     }
+    async recordFinding(intentId, input) {
+        const res = await this.fetch(`/intents/${intentId}/findings`, {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+        return res.json();
+    }
     async getWorkspace() {
         const res = await this.fetch('/workspace');
         return res.json();
@@ -33912,6 +33952,57 @@ exports.formatIntentMd = formatIntentMd;
 exports.formatCursorRules = formatCursorRules;
 exports.formatClaudeMdSection = formatClaudeMdSection;
 exports.formatOutcomeRubric = formatOutcomeRubric;
+const VERIFICATION_KIND_LABELS = {
+    fastest: 'Fastest check',
+    'shipped-signal': 'Shipped signal',
+    'regression-guard': 'Regression guard',
+    manual: 'Manual check',
+    test: 'Automated test',
+};
+const VERIFICATION_KIND_ORDER = ['fastest', 'shipped-signal', 'regression-guard', 'manual', 'test'];
+const VERIFICATION_KIND_SET = new Set(VERIFICATION_KIND_ORDER);
+/** Read verification uniformly as a check collection: canonical checks[] + adapted legacy buckets. */
+function toVerificationChecks(v) {
+    if (!v || typeof v !== 'object')
+        return [];
+    const out = [];
+    for (const c of Array.isArray(v.checks) ? v.checks : []) {
+        const description = typeof c?.description === 'string' ? c.description.trim() : '';
+        if (!description)
+            continue;
+        out.push({
+            kind: VERIFICATION_KIND_SET.has(c.kind) ? c.kind : 'test',
+            description,
+            status: c.status,
+            verifies: typeof c.verifies === 'string' && c.verifies.trim()
+                ? c.verifies.trim()
+                : undefined,
+        });
+    }
+    const legacy = [
+        [v.e2eTests, 'test'], [v.unitTests, 'test'], [v.manualChecks, 'manual'],
+    ];
+    for (const [arr, kind] of legacy) {
+        for (const s of arr ?? []) {
+            if (typeof s === 'string' && s.trim())
+                out.push({ kind, description: s.trim() });
+        }
+    }
+    return out;
+}
+/** Group verification into ordered, non-empty kind groups for rendering. */
+function groupVerificationChecks(v) {
+    const checks = toVerificationChecks(v);
+    return VERIFICATION_KIND_ORDER
+        .map((kind) => ({ kind, label: VERIFICATION_KIND_LABELS[kind], checks: checks.filter((c) => c.kind === kind) }))
+        .filter((g) => g.checks.length > 0);
+}
+/** A single check rendered as agent-facing text, annotated with its verdict and verifies target. */
+function renderCheckLine(c) {
+    const verifies = c.verifies ? ` (verifies: ${c.verifies})` : '';
+    const status = c.status && c.status !== 'unknown' ? ` [${c.status}]` : '';
+    return `${c.description}${verifies}${status}`;
+}
 /** Extract text from a string or structured outcome. */
 function getOutcomeText(o) {
     return typeof o === 'string' ? o : o.text;
@@ -34023,24 +34114,41 @@ IMPORTANT:
   - edgeCases: { scenario: string, expectedBehavior: string }[] (optional)
   - healthMetrics: string[] (optional)
   - scope: { inScope?: string[], outOfScope?: string[] } (optional)
-  - verification: { manualChecks?: string[], unitTests?: string[], e2eTests?: string[] } (optional)
+  - verification: { checks?: { kind: 'fastest'|'shipped-signal'|'regression-guard'|'manual'|'test', description: string }[] } (optional) — verification is a feedback loop, not just tests: a fastest check (quickest signal it works), a shipped-signal (observable production signal it landed), a regression-guard (what must not break), plus manual/test as needed. Legacy { manualChecks?, unitTests?, e2eTests? } string arrays are still accepted.
 
 Now, start the conversation. If they haven't provided one yet, ask for the concrete evidence (quote, metric, or ticket) driving this work.`;
 }
 // ============================================================
 // Format: intent.md
 // ============================================================
+/** Text-only decisions lines for the local file formatters (local mode has no evidence store).
+ *  Defensive: skips entries missing a string choice/reason. Returns [] when none (incl. a leading
+ *  blank line for section spacing when present). */
+function decisionLines(decisions, heading) {
+    const valid = (decisions || []).filter(d => d && typeof d.choice === 'string' && d.choice.length > 0 && typeof d.reason === 'string');
+    if (valid.length === 0)
+        return [];
+    const lines = ['', heading];
+    for (const d of valid) {
+        lines.push(`- **${d.choice}**${d.ruledOut ? ` (instead of: ${d.ruledOut})` : ''} — ${d.reason}`);
+    }
+    return lines;
+}
 /**
  * Generate intent.md content with YAML frontmatter.
  * Adapted from lib/agentPromptGenerator.ts generateIntentMd().
+ *
+ * `spec.id`, `opts.version`, and `opts.status` are preserved rather than reset — an intent that
+ * is saved twice must keep its identity and its lifecycle state. Only a genuinely new intent
+ * (no id) gets a minted id, version 1, and status 'draft'.
  */
-function formatIntentMd(spec) {
+function formatIntentMd(spec, opts = {}) {
     const now = new Date().toISOString();
     const frontmatter = {
         id: spec.id || `intent_${Date.now()}`,
-        version: 1,
-        status: 'draft',
-        created: now,
+        version: opts.version && opts.version >= 1 ? opts.version : 1,
+        status: opts.status || 'draft',
+        created: opts.created || now,
         updated: now,
     };
     const yamlLines = Object.entries(frontmatter)
@@ -34057,6 +34165,7 @@ function formatIntentMd(spec) {
         sections.push('## Objective');
         sections.push(spec.objective);
     }
+    sections.push(...decisionLines(spec.decisions, '## Decisions & Ruled-Out Alternatives'));
     if (spec.outcomes?.length) {
         sections.push('');
         sections.push('## Outcomes');
@@ -34099,27 +34208,15 @@ function formatIntentMd(spec) {
             sections.push(`- ${metric}`);
         }
     }
-    if (spec.verification) {
-        const { e2eTests, unitTests, manualChecks } = spec.verification;
-        const hasContent = e2eTests?.length || unitTests?.length || manualChecks?.length;
-        if (hasContent) {
-            sections.push('');
-            sections.push('## Verification');
-            if (e2eTests?.length) {
-                sections.push('**E2E Tests**:');
-                for (const t of e2eTests)
-                    sections.push(`- [ ] ${t}`);
-            }
-            if (unitTests?.length) {
-                sections.push('**Unit Tests**:');
-                for (const t of unitTests)
-                    sections.push(`- [ ] ${t}`);
-            }
-            if (manualChecks?.length) {
-                sections.push('**Manual Checks**:');
-                for (const t of manualChecks)
-                    sections.push(`- [ ] ${t}`);
-            }
+    const intentMdChecks = groupVerificationChecks(spec.verification);
+    if (intentMdChecks.length) {
+        sections.push('');
+        sections.push('## Verification');
+        sections.push('_A feedback loop, not just a test list._');
+        for (const g of intentMdChecks) {
+            sections.push(`**${g.label}**:`);
+            for (const c of g.checks)
+                sections.push(`- [ ] ${renderCheckLine(c)}`);
         }
     }
     sections.push('');
@@ -34146,6 +34243,7 @@ function formatCursorRules(spec) {
         sections.push('# WHY');
         sections.push(spec.objective);
     }
+    sections.push(...decisionLines(spec.decisions, '# DECISIONS (already settled — do not relitigate)'));
     if (spec.outcomes?.length) {
         sections.push('');
         sections.push('# SUCCESS OUTCOMES');
@@ -34192,25 +34290,15 @@ function formatCursorRules(spec) {
             sections.push(`- ${metric}`);
         }
     }
-    if (spec.verification) {
-        const { e2eTests, unitTests, manualChecks } = spec.verification;
-        const hasContent = e2eTests?.length || unitTests?.length || manualChecks?.length;
-        if (hasContent) {
-            sections.push('');
-            sections.push('# VERIFICATION');
-            sections.push('After implementation, verify:');
-            if (e2eTests?.length) {
-                for (const t of e2eTests)
-                    sections.push(`- [e2e] ${t}`);
-            }
-            if (unitTests?.length) {
-                for (const t of unitTests)
-                    sections.push(`- [unit] ${t}`);
-            }
-            if (manualChecks?.length) {
-                for (const t of manualChecks)
-                    sections.push(`- [manual] ${t}`);
-            }
+    const cursorChecks = groupVerificationChecks(spec.verification);
+    if (cursorChecks.length) {
+        sections.push('');
+        sections.push('# VERIFICATION');
+        sections.push('After implementation, verify (a feedback loop, not just tests):');
+        for (const g of cursorChecks) {
+            sections.push(`**${g.label}**:`);
+            for (const c of g.checks)
+                sections.push(`- ${renderCheckLine(c)}`);
         }
     }
     sections.push('');
@@ -34236,6 +34324,7 @@ function formatClaudeMdSection(spec) {
     if (spec.objective) {
         sections.push(`**Objective**: ${spec.objective}`);
     }
+    sections.push(...decisionLines(spec.decisions, '**Decisions**:'));
     if (spec.outcomes?.length) {
         sections.push('**Outcomes**:');
         sections.push(spec.outcomes.map(o => `- [ ] ${getPriorityLabel(o)}${getOutcomeText(o)}`).join('\n'));
@@ -34315,6 +34404,13 @@ function buildWriterDescription(spec) {
         sections.push('');
         sections.push(`Why this matters: ${spec.objective}`);
     }
+    const decisions = (spec.decisions || []).filter(d => d && typeof d.choice === 'string' && d.choice.length > 0 && typeof d.reason === 'string');
+    if (decisions.length > 0) {
+        sections.push('');
+        sections.push('Decisions already made (do not relitigate):');
+        for (const d of decisions)
+            sections.push(`- ${d.choice}${d.ruledOut ? ` (instead of: ${d.ruledOut})` : ''} — ${d.reason}`);
+    }
     if (spec.scope?.inScope?.length) {
         sections.push('');
         sections.push('In scope:');
@@ -34399,17 +34495,9 @@ function buildGraderRubric(spec, opts = {}) {
             sections.push(`- ${c}`);
     }
     // Verification → procedures the grader must run to produce evidence
-    const v = spec.verification;
     const checks = [];
-    for (const t of v?.e2eTests ?? [])
-        if (t?.trim())
-            checks.push(`[e2e] ${t}`);
-    for (const t of v?.unitTests ?? [])
-        if (t?.trim())
-            checks.push(`[unit] ${t}`);
-    for (const t of v?.manualChecks ?? [])
-        if (t?.trim())
-            checks.push(`[manual] ${t}`);
+    for (const c of toVerificationChecks(spec.verification))
+        checks.push(`[${c.kind}] ${renderCheckLine(c)}`);
     for (const t of spec.implementationContext?.verificationSuggestions ?? [])
         if (t?.trim())
             checks.push(`[suggested] ${t}`);
@@ -34451,11 +34539,7 @@ function formatOutcomeRubric(spec, opts = {}) {
     const maxIterations = opts.maxIterations ?? 5;
     const description = buildWriterDescription(spec);
     const rubric = buildGraderRubric(spec, opts);
-    const hasVerification = [
-        ...(spec.verification?.e2eTests ?? []),
-        ...(spec.verification?.unitTests ?? []),
-        ...(spec.verification?.manualChecks ?? []),
-    ].some((t) => t?.trim());
+    const hasVerification = toVerificationChecks(spec.verification).length > 0;
     const doc = [];
     doc.push('<!-- Pathmode → Claude Managed Agents: Outcomes rubric -->');
     doc.push(`<!-- Generated ${new Date().toISOString()} | pathmode.io -->`);
@@ -34497,15 +34581,24 @@ function formatOutcomeRubric(spec, opts = {}) {
 /**
  * Local Intent Reader
  * Reads intent.md files from the current working directory for offline/local mode.
+ *
+ * Parsing is line-based on purpose. The previous implementation extracted sections with
+ * `/^##\s+Heading\s*\n([\s\S]*?)(?=^##\s|$)/m` — but under the `m` flag `$` matches at EVERY
+ * line end, so the lazy quantifier stopped after the FIRST line. Every section round-tripped
+ * as a single item: three outcomes read back as one, `## Scope` vanished entirely, and
+ * `## Verification` produced `{}`. See round-trip.test.ts for the regression guard.
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.readLocalIntents = readLocalIntents;
+exports.readIntentMeta = readIntentMeta;
+exports.readIntentFile = readIntentFile;
 const fs_1 = __importDefault(__nccwpck_require__(9896));
 const path_1 = __importDefault(__nccwpck_require__(6928));
 const gray_matter_1 = __importDefault(__nccwpck_require__(9599));
+const DECISIONS_HEADING = 'Decisions & Ruled-Out Alternatives';
 /**
  * Read all intent.md files from the current directory and subdirectories (1 level deep).
  */
@@ -34528,6 +34621,28 @@ function readLocalIntents() {
     }
     return intents;
 }
+/**
+ * Read only the frontmatter identity of an intent.md. Used by `intent_save` to decide whether a
+ * write is an update (same id → bump version, keep status) or a collision (different id → refuse
+ * rather than clobber someone else's spec).
+ */
+function readIntentMeta(filePath) {
+    if (!fs_1.default.existsSync(filePath))
+        return null;
+    try {
+        const { data } = (0, gray_matter_1.default)(fs_1.default.readFileSync(filePath, 'utf-8'));
+        const version = Number(data.version);
+        return {
+            id: typeof data.id === 'string' && data.id.trim() ? data.id.trim() : null,
+            version: Number.isFinite(version) && version >= 1 ? version : 1,
+            status: typeof data.status === 'string' && data.status.trim() ? data.status.trim() : 'draft',
+            created: typeof data.created === 'string' ? data.created : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Parse a single intent.md file with YAML frontmatter.
  */
@@ -34537,32 +34652,29 @@ function readIntentFile(filePath) {
     try {
         const content = fs_1.default.readFileSync(filePath, 'utf-8');
         const { data, content: body } = (0, gray_matter_1.default)(content);
-        // Extract sections from markdown body
-        const outcomes = extractListSection(body, 'Outcomes');
-        const constraints = extractListSection(body, 'Constraints');
-        const healthMetrics = extractListSection(body, 'Health Metrics');
-        const edgeCases = extractEdgeCases(body);
-        const scope = extractScope(body);
-        const parsedVerification = extractVerification(body);
+        const sections = splitSections(body);
+        const parsedVerification = extractVerification(sections);
         const frontmatterVerification = data.verification && typeof data.verification === 'object'
             ? data.verification
             : null;
-        const verification = Object.keys(parsedVerification).length > 0
+        const verification = hasVerificationContent(parsedVerification)
             ? parsedVerification
             : (frontmatterVerification || {});
+        const version = Number(data.version);
         return {
             id: data.id || path_1.default.basename(filePath, '.md'),
             status: data.status || 'draft',
-            version: data.version || 1,
-            objective: data.objective || extractSection(body, 'Objective') || '',
+            version: Number.isFinite(version) && version >= 1 ? version : 1,
+            objective: data.objective || extractSection(sections, 'Objective') || '',
             title: data.title || data.userGoal || extractTitle(body) || 'Untitled Intent',
             stageName: data.stage || undefined,
             severity: data.severity || undefined,
-            outcomes,
-            constraints,
-            edgeCases,
-            healthMetrics,
-            scope: scope || undefined,
+            outcomes: extractListSection(sections, 'Outcomes'),
+            decisions: extractDecisions(sections),
+            constraints: extractListSection(sections, 'Constraints'),
+            edgeCases: extractEdgeCases(sections),
+            healthMetrics: extractListSection(sections, 'Health Metrics'),
+            scope: extractScope(sections) || undefined,
             verification,
             source: 'local',
         };
@@ -34575,44 +34687,93 @@ function readIntentFile(filePath) {
 // ============================================================
 // Markdown Parsing Helpers
 // ============================================================
+/**
+ * Split the markdown body into `## Heading` → body lines. On a duplicate heading the last one
+ * wins. `###` is not a section boundary (`^##\s+` cannot match `### `), so sub-headings stay
+ * inside their parent section.
+ */
+function splitSections(body) {
+    const sections = new Map();
+    let current = null;
+    for (const line of body.split('\n')) {
+        const heading = line.match(/^##\s+(.+?)\s*$/);
+        if (heading) {
+            current = [];
+            sections.set(heading[1], current);
+            continue;
+        }
+        // An H1 ends the preceding section without opening a new one (it is the intent title).
+        if (/^#\s+/.test(line)) {
+            current = null;
+            continue;
+        }
+        if (current)
+            current.push(line);
+    }
+    return sections;
+}
 function extractTitle(body) {
     const match = body.match(/^#\s+(.+)$/m);
     return match ? match[1].trim() : '';
 }
-function extractSection(body, heading) {
-    const regex = new RegExp(`^##\\s+${heading}\\s*\\n([\\s\\S]*?)(?=^##\\s|$)`, 'm');
-    const match = body.match(regex);
-    return match ? match[1].trim() : '';
+function sectionLines(sections, heading) {
+    return sections.get(heading) ?? [];
 }
-function extractListSection(body, heading) {
-    const section = extractSection(body, heading);
-    if (!section)
-        return [];
-    return section
-        .split('\n')
-        .filter(line => line.match(/^[-*]\s/))
-        .map(line => line.replace(/^[-*]\s+(\[.\]\s+)?/, '').trim())
+function extractSection(sections, heading) {
+    return sectionLines(sections, heading).join('\n').trim();
+}
+/** Strip a list marker and an optional `[ ]` / `[x]` checkbox from a line. */
+function stripListMarker(line) {
+    return line.replace(/^\s*[-*]\s+(\[.\]\s+)?/, '').trim();
+}
+function isListItem(line) {
+    return /^\s*[-*]\s/.test(line);
+}
+function extractListSection(sections, heading) {
+    return sectionLines(sections, heading)
+        .filter(isListItem)
+        .map(stripListMarker)
         .filter(Boolean);
 }
-function extractEdgeCases(body) {
-    const section = extractSection(body, 'Edge Cases');
-    if (!section)
-        return [];
+/**
+ * Parse `## Decisions & Ruled-Out Alternatives` entries written by `decisionLines()`:
+ *   - **choice** (instead of: ruledOut) — reason
+ * The separator is an em dash when written by us; a plain hyphen is accepted for hand-edited files.
+ */
+function extractDecisions(sections) {
+    const out = [];
+    for (const line of sectionLines(sections, DECISIONS_HEADING)) {
+        if (!isListItem(line))
+            continue;
+        const clean = stripListMarker(line);
+        const match = clean.match(/^\*\*(.+?)\*\*\s*(?:\(instead of:\s*([^)]*)\)\s*)?[—–-]\s*(.+)$/);
+        if (!match)
+            continue;
+        const choice = match[1].trim();
+        const ruledOut = match[2]?.trim();
+        const reason = match[3].trim();
+        if (!choice || !reason)
+            continue;
+        out.push(ruledOut ? { choice, ruledOut, reason } : { choice, reason });
+    }
+    return out;
+}
+function extractEdgeCases(sections) {
     const cases = [];
-    const lines = section.split('\n').filter(line => line.match(/^[-*]\s/));
-    for (const line of lines) {
-        const clean = line.replace(/^[-*]\s+/, '');
+    for (const line of sectionLines(sections, 'Edge Cases')) {
+        if (!isListItem(line))
+            continue;
+        const clean = stripListMarker(line);
         // Pattern: **scenario**: expected behavior
         const match = clean.match(/^\*\*(.+?)\*\*:\s*(.+)$/);
         if (match) {
             cases.push({ scenario: match[1], expectedBehavior: match[2] });
+            continue;
         }
-        else {
-            // Pattern: scenario → expected behavior
-            const arrowMatch = clean.match(/^(.+?)\s*[→:]\s*(.+)$/);
-            if (arrowMatch) {
-                cases.push({ scenario: arrowMatch[1].trim(), expectedBehavior: arrowMatch[2].trim() });
-            }
+        // Pattern: scenario → expected behavior
+        const arrowMatch = clean.match(/^(.+?)\s*[→:]\s*(.+)$/);
+        if (arrowMatch) {
+            cases.push({ scenario: arrowMatch[1].trim(), expectedBehavior: arrowMatch[2].trim() });
         }
     }
     return cases;
@@ -34621,24 +34782,27 @@ function extractEdgeCases(body) {
  * Extract Scope section with **In scope:** and **Out of scope:** sub-lists.
  * Matches the format emitted by formatIntentMd().
  */
-function extractScope(body) {
-    const section = extractSection(body, 'Scope');
-    if (!section)
+function extractScope(sections) {
+    const lines = sectionLines(sections, 'Scope');
+    if (lines.length === 0)
         return null;
     const inScope = [];
     const outOfScope = [];
     let target = null;
-    for (const line of section.split('\n')) {
-        if (/^\*\*In scope[:\*]*/.test(line.trim())) {
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (/^\*\*In scope[:*]*/i.test(trimmed)) {
             target = inScope;
             continue;
         }
-        if (/^\*\*Out of scope[:\*]*/.test(line.trim())) {
+        if (/^\*\*Out of scope[:*]*/i.test(trimmed)) {
             target = outOfScope;
             continue;
         }
-        if (target && line.match(/^[-*]\s/)) {
-            target.push(line.replace(/^[-*]\s+/, '').trim());
+        if (target && isListItem(line)) {
+            const item = stripListMarker(line);
+            if (item)
+                target.push(item);
         }
     }
     if (inScope.length === 0 && outOfScope.length === 0)
@@ -34650,39 +34814,214 @@ function extractScope(body) {
         result.outOfScope = outOfScope;
     return result;
 }
+/** Canonical kind labels written by `VERIFICATION_KIND_LABELS` in intent-compiler.ts. */
+const VERIFICATION_LABEL_TO_KIND = {
+    'fastest check': 'fastest',
+    'shipped signal': 'shipped-signal',
+    'regression guard': 'regression-guard',
+    'manual check': 'manual',
+    'automated test': 'test',
+};
+/** Legacy bucket labels from older intent.md files. Checked after the canonical labels. */
+const LEGACY_VERIFICATION_LABELS = [
+    [/^e2e tests?$/i, 'e2eTests'],
+    [/^unit tests?$/i, 'unitTests'],
+    [/^manual checks$/i, 'manualChecks'],
+];
+/** Inverse of `renderCheckLine()`: `description (verifies: X) [passing]`. */
+function parseCheckLine(text) {
+    let rest = text.trim();
+    let status;
+    let verifies;
+    const statusMatch = rest.match(/\s*\[(unknown|passing|failing)\]$/i);
+    if (statusMatch) {
+        status = statusMatch[1].toLowerCase();
+        rest = rest.slice(0, statusMatch.index).trim();
+    }
+    const verifiesMatch = rest.match(/\s*\(verifies:\s*([^)]*)\)$/i);
+    if (verifiesMatch) {
+        const value = verifiesMatch[1].trim();
+        if (value)
+            verifies = value;
+        rest = rest.slice(0, verifiesMatch.index).trim();
+    }
+    return { description: rest, status, verifies };
+}
+/** Read a `**Label**:` heading inside the Verification section. */
+function parseVerificationLabel(line) {
+    const match = line.trim().match(/^\*\*(.+?)\*\*\s*:?\s*$/);
+    return match ? match[1].trim() : null;
+}
 /**
- * Extract Verification section with **E2E Tests**, **Unit Tests**, **Manual Checks** sub-lists.
- * Matches the format emitted by formatIntentMd().
+ * Extract the Verification section. Canonical kind labels ("Fastest check", "Shipped signal",
+ * "Regression guard", "Manual check", "Automated test") become `checks[]`; legacy labels
+ * ("E2E Tests", "Unit Tests", "Manual Checks") keep their string-array buckets, which
+ * `toVerificationChecks()` in intent-compiler.ts adapts on read.
  */
-function extractVerification(body) {
-    const section = extractSection(body, 'Verification');
-    if (!section)
+function extractVerification(sections) {
+    const lines = sectionLines(sections, 'Verification');
+    if (lines.length === 0)
         return {};
     const result = {};
-    let currentKey = null;
-    for (const line of section.split('\n')) {
-        const trimmed = line.trim();
-        if (/^\*\*E2E Tests?\*?\*?:?/.test(trimmed)) {
-            currentKey = 'e2eTests';
-            result[currentKey] = [];
+    let currentKind = null;
+    let currentLegacy = null;
+    for (const line of lines) {
+        const label = parseVerificationLabel(line);
+        if (label) {
+            const kind = VERIFICATION_LABEL_TO_KIND[label.toLowerCase()];
+            if (kind) {
+                currentKind = kind;
+                currentLegacy = null;
+                continue;
+            }
+            const legacy = LEGACY_VERIFICATION_LABELS.find(([re]) => re.test(label));
+            if (legacy) {
+                currentKind = null;
+                currentLegacy = legacy[1];
+                if (!result[currentLegacy])
+                    result[currentLegacy] = [];
+                continue;
+            }
+            // Unknown bold label — stop attributing lines to the previous bucket.
+            currentKind = null;
+            currentLegacy = null;
             continue;
         }
-        if (/^\*\*Unit Tests?\*?\*?:?/.test(trimmed)) {
-            currentKey = 'unitTests';
-            result[currentKey] = [];
+        if (!isListItem(line))
             continue;
-        }
-        if (/^\*\*Manual Checks?\*?\*?:?/.test(trimmed)) {
-            currentKey = 'manualChecks';
-            result[currentKey] = [];
+        const text = stripListMarker(line);
+        if (!text)
             continue;
+        if (currentKind) {
+            const { description, status, verifies } = parseCheckLine(text);
+            if (!description)
+                continue;
+            const check = { kind: currentKind, description };
+            if (status)
+                check.status = status;
+            if (verifies)
+                check.verifies = verifies;
+            (result.checks ||= []).push(check);
         }
-        if (currentKey && trimmed.match(/^[-*]\s/)) {
-            result[currentKey].push(trimmed.replace(/^[-*]\s+(\[.\]\s+)?/, '').trim());
+        else if (currentLegacy) {
+            result[currentLegacy].push(text);
         }
     }
     return result;
 }
+function hasVerificationContent(v) {
+    return !!(v.checks?.length || v.e2eTests?.length || v.unitTests?.length || v.manualChecks?.length);
+}
+
+
+/***/ }),
+
+/***/ 4681:
+/***/ ((__unused_webpack_module, exports) => {
+
+"use strict";
+
+/**
+ * Idempotent merge of a Pathmode-generated section into an existing agent-instructions file
+ * (CLAUDE.md / AGENTS.md). The section is wrapped in <!-- PATHMODE:START ... --> / <!-- PATHMODE:END -->
+ * markers (both the local formatClaudeMdSection and the cloud generateClaudeMdContent emit them),
+ * so re-running replaces the marked block in place instead of appending a duplicate. This is the
+ * no-drift guarantee of the round-trip: the repo's Pathmode context is regenerated from the
+ * canonical source, never hand-maintained.
+ */
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.mergePathmodeSection = mergePathmodeSection;
+/** Matches the whole PATHMODE block, tolerant of the suffixed start marker
+ *  (`<!-- PATHMODE:START - Do not edit... -->`). Not global — there is one block per file. */
+const PATHMODE_SECTION_RE = /<!-- PATHMODE:START[\s\S]*?-->[\s\S]*?<!-- PATHMODE:END -->/;
+/** The section embeds a volatile `_Generated at <timestamp>_` line. Strip it so a re-generated
+ *  section that differs ONLY by a fresher timestamp still compares equal (reports 'unchanged' →
+ *  caller skips the write → no noisy timestamp-only diff that would mask real drift). */
+const GENERATED_AT_RE = /^_Generated at .*$/m;
+const withoutTimestamp = (s) => s.replace(GENERATED_AT_RE, '');
+/**
+ * Merge `section` (a marker-wrapped Pathmode block) into `existing` file content.
+ * - empty file        -> the section becomes the whole file ('created')
+ * - has a PATHMODE block, byte-identical to `section` -> no change ('unchanged' — proven no drift)
+ * - has a PATHMODE block, different -> replace it in place ('replaced')
+ * - no PATHMODE block  -> append it after the existing content ('appended')
+ * Pure; callers decide whether to actually write (skip the write when 'unchanged').
+ */
+function mergePathmodeSection(existing, section) {
+    if (!existing)
+        return { content: section, action: 'created' };
+    const match = existing.match(PATHMODE_SECTION_RE);
+    if (match) {
+        if (withoutTimestamp(match[0]) === withoutTimestamp(section)) {
+            return { content: existing, action: 'unchanged' };
+        }
+        // Replacer FUNCTION, not a string: `section` may contain `$&`, `$$`, `` $` ``, `$'`, `$1`
+        // (a user's spec text), which String.replace would otherwise interpret as special patterns
+        // and corrupt the merged file. The function form substitutes `section` verbatim.
+        return { content: existing.replace(PATHMODE_SECTION_RE, () => section), action: 'replaced' };
+    }
+    // No existing block: append, separated by a blank line, normalizing trailing whitespace so
+    // re-runs stay stable (the next run finds the marker and replaces in place).
+    return { content: `${existing.replace(/\s*$/, '')}\n\n${section}\n`, action: 'appended' };
+}
+
+
+/***/ }),
+
+/***/ 6137:
+/***/ ((__unused_webpack_module, exports) => {
+
+"use strict";
+
+/**
+ * Save policy for intent.md.
+ *
+ * Extracted from the `intent_save` handler so the decision is testable: the handler itself lives
+ * inside startMcpServer() and cannot be imported. The rules exist because the original handler
+ * stamped a fresh `intent_${Date.now()}` id on every save and wrote unconditionally — a second
+ * save in one conversation destroyed the first spec and reset its version and status.
+ */
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.unquoteId = unquoteId;
+exports.decideSave = decideSave;
+/** Strip one layer of matching surrounding quotes, as picked up from raw YAML frontmatter text. */
+function unquoteId(value) {
+    const trimmed = (value || '').trim();
+    const m = trimmed.match(/^(['"])([\s\S]*)\1$/);
+    return m ? m[2].trim() : trimmed;
+}
+/**
+ * Decide how a save against an existing intent.md should be applied.
+ *
+ * - No existing file → create at version 1, status 'draft'.
+ * - Existing file, same intent → update: bump version, preserve status and created.
+ *   "Same intent" means a matching id, OR no incoming id at all: the common conversational flow is
+ *   save → refine → save, where the agent holds a spec object it never gave an id.
+ * - Existing file, different id → refuse, unless overwrite was explicitly requested. Refusing is
+ *   the safe default because the alternative silently destroys an unrelated spec.
+ *
+ * The incoming id is unquoted first: frontmatter serializes `id: "intent_123"`, and an agent that
+ * reads intent.md as text rather than parsed YAML hands those quotes straight back. Comparing raw
+ * would refuse a legitimate update and print two identical-looking ids in the error.
+ */
+function decideSave(params) {
+    const { existing, overwrite, mintId } = params;
+    const incomingId = unquoteId(params.incomingId);
+    const isSameIntent = !!existing && (!incomingId || incomingId === existing.id);
+    if (existing && !isSameIntent && !overwrite) {
+        return { action: 'refuse', id: incomingId, version: existing.version, status: existing.status };
+    }
+    // An explicit overwrite of a different intent is a create: the previous spec's version and
+    // status belonged to a different intent and must not carry over onto this one.
+    const previous = isSameIntent ? existing : null;
+    return {
+        action: previous ? 'update' : 'create',
+        id: incomingId || previous?.id || mintId(),
+        version: previous ? previous.version + 1 : 1,
+        status: previous ? previous.status : 'draft',
+        created: previous?.created,
+    };
+}
 
 
 /***/ }),
@@ -34759,7 +35098,9 @@ function success(msg) { console.log(`  ${GREEN}✓${RESET} ${msg}`); }
 function warn(msg) { console.log(`  ${YELLOW}!${RESET} ${msg}`); }
 function fail(msg) { console.log(`  ${RED}✗${RESET} ${msg}`); }
 function getMcpServerBlock(apiKey, omitApiKey) {
-    if (omitApiKey) {
+    // No key, or a config that may be committed to a repo: emit a bare block. The server infers
+    // local mode when it finds no key, so this is a complete keyless setup, not a partial one.
+    if (!apiKey || omitApiKey) {
         return {
             command: 'npx',
             args: ['@pathmode/mcp-server'],
@@ -34819,57 +35160,62 @@ async function runSetup() {
     log(`${BOLD}Pathmode MCP Setup${RESET}`);
     log(`${DIM}──────────────────${RESET}`);
     log('');
-    if (!apiKey) {
-        log(`Usage: npx @pathmode/mcp-server setup ${DIM}<api-key>${RESET}`);
-        log('');
-        log(`Get your API key from ${CYAN}https://pathmode.io${RESET} → Settings → API Keys`);
-        log('');
-        process.exit(1);
-    }
-    // ─── Step 1: Validate key ─────────────────────────────────
-    process.stdout.write(`  Validating API key...`);
+    // ─── Step 1: Validate key (cloud mode) ────────────────────
+    //
+    // No key is NOT an error. The skill pack's documented first command is `setup`, and this used
+    // to exit(1) on every keyless user — the first command in the onboarding path was a wall.
+    // Keyless setup configures local mode, which is a complete, working configuration.
     let workspaceName = '';
     let workspaceId = '';
     const apiUrl = args.includes('--staging')
         ? 'https://staging.pathmode.io'
         : 'https://pathmode.io';
-    try {
-        const res = await fetch(`${apiUrl}/api/v1/workspace`, {
-            headers: {
-                'Authorization': `Bearer ${apiKey}`,
-                'Content-Type': 'application/json',
-            },
-        });
-        if (!res.ok) {
-            if (res.status === 401 || res.status === 403) {
-                log(` ${RED}✗${RESET}`);
-                log('');
-                fail('Invalid or expired API key.');
-                log(`  Get a new key from ${CYAN}${apiUrl}${RESET} → Settings → API Keys`);
-                log('');
-                process.exit(1);
-            }
-            throw new Error(`HTTP ${res.status}`);
-        }
-        const workspace = await res.json();
-        workspaceName = workspace.name;
-        workspaceId = workspace.id;
-        log(` ${GREEN}✓${RESET}`);
-        success(`Connected to "${BOLD}${workspaceName}${RESET}"`);
-    }
-    catch (err) {
-        log(` ${RED}✗${RESET}`);
+    if (!apiKey) {
+        success(`Configuring ${BOLD}local mode${RESET} (no API key given)`);
+        log(`  ${DIM}Specs are written to intent.md in your project. Nothing leaves your machine.${RESET}`);
+        log(`  ${DIM}To connect a workspace later: npx @pathmode/mcp-server setup pm_live_xxx${RESET}`);
         log('');
-        if (err.cause?.code === 'ENOTFOUND' || err.cause?.code === 'ECONNREFUSED') {
-            fail('Could not reach pathmode.io. Check your internet connection.');
+    }
+    else {
+        process.stdout.write(`  Validating API key...`);
+        try {
+            const res = await fetch(`${apiUrl}/api/v1/workspace`, {
+                headers: {
+                    'Authorization': `Bearer ${apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+            });
+            if (!res.ok) {
+                if (res.status === 401 || res.status === 403) {
+                    log(` ${RED}✗${RESET}`);
+                    log('');
+                    fail('Invalid or expired API key.');
+                    log(`  Get a new key from ${CYAN}${apiUrl}${RESET} → Settings → API Keys`);
+                    log('');
+                    process.exit(1);
+                }
+                throw new Error(`HTTP ${res.status}`);
+            }
+            const workspace = await res.json();
+            workspaceName = workspace.name;
+            workspaceId = workspace.id;
+            log(` ${GREEN}✓${RESET}`);
+            success(`Connected to "${BOLD}${workspaceName}${RESET}"`);
         }
-        else {
-            fail(`Connection failed: ${err.message}`);
+        catch (err) {
+            log(` ${RED}✗${RESET}`);
+            log('');
+            if (err.cause?.code === 'ENOTFOUND' || err.cause?.code === 'ECONNREFUSED') {
+                fail('Could not reach pathmode.io. Check your internet connection.');
+            }
+            else {
+                fail(`Connection failed: ${err.message}`);
+            }
+            log('');
+            process.exit(1);
         }
         log('');
-        process.exit(1);
     }
-    log('');
     // ─── Step 2: Detect & configure tools ─────────────────────
     let configured = 0;
     for (const tool of TOOLS) {
@@ -34912,15 +35258,20 @@ async function runSetup() {
         }
     }
     // ─── Step 3: Save ~/.pathmode/config.json ─────────────────
-    const pathmodeConfigDir = path_1.default.join(os_1.default.homedir(), '.pathmode');
-    const pathmodeConfigFile = path_1.default.join(pathmodeConfigDir, 'config.json');
-    const pathmodeConfig = {
-        apiKey,
-        apiUrl,
-        workspaceId,
-    };
-    if (writeJsonSafe(pathmodeConfigFile, pathmodeConfig)) {
-        success(`Config saved → ${DIM}${shortenPath(pathmodeConfigFile)}${RESET}`);
+    //
+    // Only when we have a key. A keyless run must not touch this file: writing a keyless config
+    // would silently disconnect a workspace the user set up earlier.
+    if (apiKey) {
+        const pathmodeConfigDir = path_1.default.join(os_1.default.homedir(), '.pathmode');
+        const pathmodeConfigFile = path_1.default.join(pathmodeConfigDir, 'config.json');
+        const pathmodeConfig = {
+            apiKey,
+            apiUrl,
+            workspaceId,
+        };
+        if (writeJsonSafe(pathmodeConfigFile, pathmodeConfig)) {
+            success(`Config saved → ${DIM}${shortenPath(pathmodeConfigFile)}${RESET}`);
+        }
     }
     log('');
     // ─── Step 4: Summary ──────────────────────────────────────
@@ -34932,8 +35283,10 @@ async function runSetup() {
         log(`  ${CYAN}  "mcpServers": {${RESET}`);
         log(`  ${CYAN}    "pathmode": {${RESET}`);
         log(`  ${CYAN}      "command": "npx",${RESET}`);
-        log(`  ${CYAN}      "args": ["@pathmode/mcp-server"],${RESET}`);
-        log(`  ${CYAN}      "env": { "PATHMODE_API_KEY": "${apiKey}" }${RESET}`);
+        log(`  ${CYAN}      "args": ["@pathmode/mcp-server"]${apiKey ? ',' : ''}${RESET}`);
+        if (apiKey) {
+            log(`  ${CYAN}      "env": { "PATHMODE_API_KEY": "${apiKey}" }${RESET}`);
+        }
         log(`  ${CYAN}    }${RESET}`);
         log(`  ${CYAN}  }${RESET}`);
         log(`  ${CYAN}}${RESET}`);
@@ -34943,6 +35296,23 @@ async function runSetup() {
         log(`${GREEN}Done!${RESET} Restart your tools to activate Pathmode.`);
         log('');
     }
+    // ─── Step 5: The exact next step ──────────────────────────
+    //
+    // Setup that ends at "Done!" leaves the user to guess how to reach the product. Name the
+    // phrase, because the skills auto-trigger on plain English rather than slash commands.
+    log(`${BOLD}Next${RESET}`);
+    log(`  1. Install the skill pack:  ${CYAN}npx @pathmode/mcp-server install-skills${RESET}`);
+    log(`  2. Restart Claude Code, then say:`);
+    log('');
+    log(`     ${CYAN}"Help me write an intent spec for [the thing you're about to build]"${RESET}`);
+    log('');
+    if (apiKey) {
+        log(`  ${DIM}Specs sync to "${workspaceName}" and are visible to your team and other agents.${RESET}`);
+    }
+    else {
+        log(`  ${DIM}The spec is written to intent.md in your project root.${RESET}`);
+    }
+    log('');
 }
 
 
@@ -64524,7 +64894,7 @@ module.exports = /*#__PURE__*/JSON.parse('{"$schema":"http://json-schema.org/dra
 /***/ ((module) => {
 
 "use strict";
-module.exports = /*#__PURE__*/JSON.parse('{"name":"@pathmode/mcp-server","version":"1.7.0","publishConfig":{"access":"public"},"mcpName":"io.github.pathmodeio/mcp-server","description":"Pathmode MCP Server — Build structured intent specs through Socratic AI conversation (zero-config), or connect to your Intent Layer for strategic context, dependency graphs, and implementation prompts.","main":"dist/index.js","bin":{"pathmode-mcp":"dist/index.js"},"files":["dist/","manifest.json","icon.svg","README.md","skills/"],"scripts":{"build":"ncc build src/index.ts -o dist","dev":"ts-node src/index.ts","prepublishOnly":"npm run build"},"keywords":["pathmode","mcp","model-context-protocol","claude-code","claude-code-skills","agent-skills","cursor","windsurf","intent-engineering","intent-compiler","ai-agents","product-development","dependency-graph","strategic-planning"],"author":"Pathmode","license":"MIT","type":"commonjs","engines":{"node":">=18.0.0"},"repository":{"type":"git","url":"git+https://github.com/pathmodeio/mcp-server.git","directory":"packages/mcp-server"},"homepage":"https://pathmode.io","dependencies":{"@modelcontextprotocol/sdk":"^1.12.1","gray-matter":"^4.0.3","zod":"^3.24.0"},"devDependencies":{"@types/node":"^25.1.0","@vercel/ncc":"^0.38.4","ts-node":"^10.9.2","typescript":"^5.9.3"}}');
+module.exports = /*#__PURE__*/JSON.parse('{"name":"@pathmode/mcp-server","version":"1.9.0","publishConfig":{"access":"public"},"mcpName":"io.github.pathmodeio/mcp-server","description":"Pathmode MCP Server — Build structured intent specs through Socratic AI conversation (zero-config), or connect to your Intent Layer for strategic context, dependency graphs, and implementation prompts.","main":"dist/index.js","bin":{"pathmode-mcp":"dist/index.js"},"files":["dist/","manifest.json","icon.svg","README.md","skills/"],"scripts":{"build":"rm -rf dist && ncc build src/index.ts -o dist","dev":"ts-node src/index.ts","prepublishOnly":"npm run build"},"keywords":["pathmode","mcp","model-context-protocol","claude-code","claude-code-skills","agent-skills","cursor","windsurf","intent-engineering","intent-compiler","ai-agents","product-development","dependency-graph","strategic-planning"],"author":"Pathmode","license":"MIT","type":"commonjs","engines":{"node":">=18.0.0"},"repository":{"type":"git","url":"git+https://github.com/pathmodeio/mcp-server.git","directory":"packages/mcp-server"},"homepage":"https://pathmode.io","dependencies":{"@modelcontextprotocol/sdk":"^1.12.1","gray-matter":"^4.0.3","zod":"^3.24.0"},"devDependencies":{"@types/node":"^25.1.0","@vercel/ncc":"^0.38.4","ts-node":"^10.9.2","typescript":"^5.9.3"}}');
 
 /***/ })
 
@@ -64577,14 +64947,16 @@ var exports = __webpack_exports__;
  * Connects Claude Code, Cursor, and other AI agents to your Intent Layer.
  *
  * Usage:
- *   npx @pathmode/mcp-server                       # Cloud mode (uses ~/.pathmode/config.json)
- *   npx @pathmode/mcp-server --local                # Local mode (reads intent.md from cwd)
- *   npx @pathmode/mcp-server setup pm_live_xxx      # Auto-configure your tools
+ *   npx @pathmode/mcp-server                       # Cloud mode with a key, local mode without one
+ *   npx @pathmode/mcp-server --local                # Force local mode (reads intent.md from cwd)
+ *   npx @pathmode/mcp-server setup                  # Configure your tools for keyless local mode
+ *   npx @pathmode/mcp-server setup pm_live_xxx      # Configure your tools for cloud mode
  *   npx @pathmode/mcp-server install-skills         # Copy the skill pack into .claude/skills/
  *   npx @pathmode/mcp-server install-skills --global  # Install into ~/.claude/skills/ instead
  *
- * The Intent Compiler (compile-intent prompt, intent_save, intent_export tools)
- * works without an API key — zero-config intent spec building in Claude Code.
+ * Mode is inferred: with no API key configured (PATHMODE_API_KEY or ~/.pathmode/config.json)
+ * the server runs in local mode and reads/writes intent.md in the project root. The Intent
+ * Compiler (compile-intent prompt, intent_save, intent_export tools) needs no API key.
  *
  * Add to .mcp.json in the project root:
  *   {
@@ -64618,7 +64990,9 @@ const path_1 = __nccwpck_require__(6928);
 const fs_1 = __nccwpck_require__(9896);
 const api_client_1 = __nccwpck_require__(7475);
 const local_reader_1 = __nccwpck_require__(3518);
+const save_policy_1 = __nccwpck_require__(6137);
 const intent_compiler_1 = __nccwpck_require__(6488);
+const pathmode_section_1 = __nccwpck_require__(4681);
 const setup_1 = __nccwpck_require__(8294);
 const install_skills_1 = __nccwpck_require__(3783);
 // Server version is sourced from package.json so the version reported to MCP
@@ -64646,18 +65020,21 @@ else {
 }
 function startMcpServer() {
     // ─── MCP Server ───────────────────────────────────────────────
-    const isLocalMode = process.argv.includes('--local');
-    let client = null;
     const isDebug = process.env.PATHMODE_MCP_DEBUG === '1';
-    if (!isLocalMode) {
-        const config = (0, api_client_1.loadConfig)();
-        if (isDebug) {
-            console.error(`[pathmode-mcp] API key present: ${!!config?.apiKey}, url: ${config?.apiUrl || 'none'}`);
-        }
-        if (config) {
-            client = new api_client_1.PathmodeClient(config);
-        }
-        // No exit — Intent Compiler tools work without an API key
+    // Local mode is the DEFAULT when no API key is configured. `--local` forces it even when a key
+    // exists. Previously local mode required the flag, so the keyless install documented on
+    // pathmode.io (no key, no flag) fell through to the cloud path with a null client: every tool
+    // failed, including the four that can read intent.md. Keyless users could write a spec and never
+    // read it back.
+    const cloudConfig = (0, api_client_1.loadConfig)();
+    const hasApiKey = !!cloudConfig?.apiKey;
+    const isLocalMode = process.argv.includes('--local') || !hasApiKey;
+    let client = null;
+    if (isDebug) {
+        console.error(`[pathmode-mcp] mode: ${isLocalMode ? 'local' : 'cloud'}, API key present: ${hasApiKey}, url: ${cloudConfig?.apiUrl || 'none'}`);
+    }
+    if (!isLocalMode && cloudConfig) {
+        client = new api_client_1.PathmodeClient(cloudConfig);
     }
     // ============================================================
     // Server Setup
@@ -64679,9 +65056,28 @@ function startMcpServer() {
     class CloudClientError extends Error {
         constructor() { super(CLOUD_REQUIRED_MSG); this.name = 'CloudClientError'; }
     }
+    const cloudOnly = isLocalMode
+        ? { registerTool: (() => undefined) }
+        : server;
     function normalizeText(value) {
         return (value || '').trim();
     }
+    // Clamp a caller-supplied write path to the project root (process.cwd()).
+    // The optional `path` argument on intent_save / intent_export is influenced by
+    // the MCP client, so an absolute path or `..` segments could otherwise land a
+    // file outside the intended project folder. Reject those before any fs write.
+    function resolveWithinProject(requestedPath) {
+        const root = process.cwd();
+        if ((0, path_1.isAbsolute)(requestedPath)) {
+            throw new Error(`Refusing to write outside the project: "${requestedPath}" is an absolute path. Pass a path relative to the project root.`);
+        }
+        const resolved = (0, path_1.resolve)(root, requestedPath);
+        const rel = (0, path_1.relative)(root, resolved);
+        if (rel === '' || rel.startsWith('..') || (0, path_1.isAbsolute)(rel)) {
+            throw new Error(`Refusing to write outside the project: "${requestedPath}" resolves outside the project root.`);
+        }
+        return resolved;
+    }
     // Keep this selection heuristic aligned with the canonical readiness rules in
     // /Users/jannelammi/code/Pathmode/lib/intentReadiness.ts. The MCP package cannot
     // import app/lib code directly, so this mirrors only the minimum logic needed
@@ -64701,6 +65097,24 @@ function startMcpServer() {
             return anyReady;
         return intents[0];
     }
+    /** The union of evidence IDs an intent cites: directly linked + section anchors + decision-cited.
+     *  Mirrors lib/intentSpecHelpers.collectSpecEvidenceIds (the MCP package can't import app/lib). */
+    function collectCitedEvidenceIds(intent) {
+        const anchorIds = Object.values((intent?.evidenceAnchors || {})).flat();
+        const decisionIds = (intent?.decisions || []).flatMap((d) => d?.evidenceIds || []);
+        const all = [...(intent?.evidenceIds || []), ...anchorIds, ...decisionIds];
+        return Array.from(new Set(all.filter((id) => typeof id === 'string' && id.length > 0)));
+    }
+    /** Cheap, fetch-free coverage summary from the intent's own fields. Tells an agent how much
+     *  evidence backs the intent and where to get the full text, without bloating the default call. */
+    function summarizeCitedEvidence(intent) {
+        return {
+            citedCount: collectCitedEvidenceIds(intent).length,
+            linkedCount: (intent?.evidenceIds || []).length,
+            anchoredSections: Object.keys(intent?.evidenceAnchors || {}).length,
+            note: 'Evidence is referenced by ID. Call get_agent_prompt for the full evidence-backed execution prompt, or re-call get_current_intent with include_evidence=true to inline the evidence content.',
+        };
+    }
     // Note: The MCP SDK catches errors thrown in tool handlers and returns them as
     // error text results. CloudClientError thrown by requireCloudClient() will
     // surface its message to the client without crashing the server.
@@ -64709,10 +65123,13 @@ function startMcpServer() {
     // ============================================================
     server.registerTool('get_current_intent', {
         title: 'Get Current Intent',
-        description: 'Get the currently active intent, preferring approved intents with real objective/outcome content over empty stubs. Returns the full IntentSpec with objective, outcomes, constraints, and edge cases.',
-        inputSchema: { status: zod_1.z.string().optional().describe('Filter by status: draft, validated, approved, shipped, verified') },
+        description: 'Get the currently active intent, preferring approved intents with real objective/outcome content over empty stubs. Returns the full IntentSpec plus an evidenceSummary (how much user evidence backs it). Evidence is referenced by ID; pass include_evidence=true to inline the evidence content, or call get_agent_prompt for the full evidence-backed execution prompt.',
+        inputSchema: {
+            status: zod_1.z.string().optional().describe('Filter by status: draft, validated, approved, shipped, verified'),
+            include_evidence: zod_1.z.boolean().optional().describe('Inline the actual evidence items (truncated) this intent cites. Default false — the default response carries only a fetch-free evidenceSummary to keep casual calls cheap.'),
+        },
         annotations: READ_ONLY,
-    }, async ({ status }) => {
+    }, async ({ status, include_evidence }) => {
         if (isLocalMode) {
             const intents = (0, local_reader_1.readLocalIntents)();
             const filtered = status ? intents.filter(i => i.status === status) : intents;
@@ -64720,18 +65137,47 @@ function startMcpServer() {
             if (!current) {
                 return { content: [{ type: 'text', text: 'No intents found locally.' }] };
             }
+            // Local mode has no cloud evidence store — return the intent as-is.
             return { content: [{ type: 'text', text: JSON.stringify(current, null, 2) }] };
         }
         const cloud = requireCloudClient();
-        const intents = await cloud.listIntents(status || 'approved');
+        let intents = await cloud.listIntents(status || 'approved');
         if (intents.length === 0) {
-            const allIntents = await cloud.listIntents();
-            if (allIntents.length === 0) {
+            intents = await cloud.listIntents();
+            if (intents.length === 0) {
                 return { content: [{ type: 'text', text: 'No intents found in workspace.' }] };
             }
-            return { content: [{ type: 'text', text: JSON.stringify(pickCurrentIntent(allIntents), null, 2) }] };
         }
-        return { content: [{ type: 'text', text: JSON.stringify(pickCurrentIntent(intents), null, 2) }] };
+        const current = pickCurrentIntent(intents);
+        // Default: a fetch-free coverage summary (no extra API call). On request: the cited
+        // evidence content, fetched once for the product and filtered to this intent's citations.
+        const evidenceSummary = summarizeCitedEvidence(current);
+        let evidence;
+        let unresolvedEvidenceIds;
+        if (include_evidence && current?.productId) {
+            const cited = collectCitedEvidenceIds(current);
+            if (cited.length > 0) {
+                // Pull up to the API max (200) and filter to this intent's citations. A cited item
+                // older than that page won't resolve — surface it as unresolvedEvidenceIds rather
+                // than silently returning an incomplete evidence block.
+                const { evidence: pool } = await cloud.queryEvidence({ productId: current.productId, limit: 200 });
+                const found = new Map(pool.map(e => [e.id, e]));
+                evidence = cited
+                    .map(id => found.get(id))
+                    .filter((e) => !!e)
+                    .map(e => ({
+                    id: e.id,
+                    type: e.type,
+                    content: e.content.length > 200 ? `${e.content.slice(0, 200)}…` : e.content,
+                    source: e.source,
+                    severity: e.severity,
+                }));
+                const missing = cited.filter(id => !found.has(id));
+                if (missing.length > 0)
+                    unresolvedEvidenceIds = missing;
+            }
+        }
+        return { content: [{ type: 'text', text: JSON.stringify({ ...current, evidenceSummary, ...(evidence ? { evidence } : {}), ...(unresolvedEvidenceIds ? { unresolvedEvidenceIds } : {}) }, null, 2) }] };
     });
     server.registerTool('list_intents', {
         title: 'List Intents',
@@ -64760,7 +65206,7 @@ function startMcpServer() {
     });
     server.registerTool('get_intent', {
         title: 'Get Intent',
-        description: 'Get a single intent by ID with full details including objective, outcomes, constraints, edge cases, and relations.',
+        description: 'Get a single intent by ID with full details including objective, outcomes, constraints, edge cases, and relations. Evidence is referenced by ID; call get_agent_prompt for the full evidence-backed execution prompt.',
         inputSchema: { intentId: zod_1.z.string().describe('The intent ID to fetch') },
         annotations: READ_ONLY,
     }, async ({ intentId }) => {
@@ -64780,7 +65226,7 @@ function startMcpServer() {
             return { content: [{ type: 'text', text: `Failed to fetch intent: ${e.message}` }] };
         }
     });
-    server.registerTool('get_intent_relations', {
+    cloudOnly.registerTool('get_intent_relations', {
         title: 'Get Intent Relations',
         description: 'Get the dependency graph for a specific intent. Shows what it depends on, enables, or blocks.',
         inputSchema: { intentId: zod_1.z.string().describe('The intent ID to get relations for') },
@@ -64839,7 +65285,7 @@ function startMcpServer() {
             return { content: [{ type: 'text', text: `Search failed: ${e.message}` }] };
         }
     });
-    server.registerTool('analyze_intent_graph', {
+    cloudOnly.registerTool('analyze_intent_graph', {
         title: 'Analyze Intent Graph',
         description: 'Analyze the intent dependency graph for risks and strategic insights. Returns critical path, cycles, bottlenecks, orphans, status mismatches, and stalled intents.',
         inputSchema: {
@@ -65029,27 +65475,29 @@ function startMcpServer() {
     });
     /** Map a cloud ApiIntent into the IntentFields shape the formatters consume. */
     function apiIntentToFields(intent) {
-        const v = (intent.verification || {});
         return {
             id: intent.id,
             title: intent.title,
             objective: intent.objective,
             outcomes: intent.outcomes ?? [],
+            decisions: intent.decisions,
             constraints: intent.constraints,
             edgeCases: (intent.edgeCases ?? []).map((e) => ({ scenario: e.scenario, expectedBehavior: e.expectedBehavior })),
             healthMetrics: intent.healthMetrics,
             scope: intent.scope,
-            verification: { manualChecks: v.manualChecks, unitTests: v.unitTests, e2eTests: v.e2eTests },
+            // Pass the whole verification through (checks[] + legacy buckets) so feedback-loop checks
+            // survive the cloud→local bridge; the formatters adapt both shapes uniformly.
+            verification: (intent.verification || undefined),
             implementationContext: intent.implementationContext ?? undefined,
         };
     }
-    server.registerTool('export_context', {
+    cloudOnly.registerTool('export_context', {
         title: 'Export Context',
-        description: 'Export workspace context as a formatted file. Use "claude-md" for CLAUDE.md (full workspace context), "cursorrules" for Cursor AI rules, "intent-md" for a single intent specification file, or "outcome-rubric" for a Claude Managed Agents Outcomes rubric (writer description + evidence-forcing grader rubric) derived from the resolved intent, its implementation context, and the workspace constitution. For cursorrules/intent-md/outcome-rubric, product context is always derived from the resolved intent. For claude-md, pass productId to select a specific product, otherwise the first active product is used.',
+        description: 'Export workspace context as a formatted file. Use "claude-md" for CLAUDE.md (full workspace context), "agents-md" for the same workspace context written for AGENTS.md (the native instruction file for OpenAI Codex and modern Cursor), "cursorrules" for Cursor AI rules, "intent-md" for a single intent specification file, or "outcome-rubric" for a Claude Managed Agents Outcomes rubric (writer description + evidence-forcing grader rubric) derived from the resolved intent, its implementation context, and the workspace constitution. claude-md and agents-md produce identical, agent-agnostic content (the difference is only the target filename). For cursorrules/intent-md/outcome-rubric, product context is always derived from the resolved intent. For claude-md/agents-md, pass productId to select a specific product, otherwise the first active product is used.',
         inputSchema: {
-            format: zod_1.z.enum(['claude-md', 'cursorrules', 'intent-md', 'outcome-rubric']).describe('Export format'),
+            format: zod_1.z.enum(['claude-md', 'agents-md', 'cursorrules', 'intent-md', 'outcome-rubric']).describe('Export format'),
             intentId: zod_1.z.string().optional().describe('Intent ID (optional, for cursorrules and intent-md)'),
-            productId: zod_1.z.string().optional().describe('Product ID (optional, only used for claude-md format to select a specific product)'),
+            productId: zod_1.z.string().optional().describe('Product ID (optional, only used for claude-md/agents-md format to select a specific product)'),
         },
         annotations: READ_ONLY,
     }, async ({ format, intentId, productId }) => {
@@ -65083,7 +65531,42 @@ function startMcpServer() {
             return { content: [{ type: 'text', text: `Export failed: ${e.message}` }] };
         }
     });
-    server.registerTool('get_agent_prompt', {
+    server.tool('sync_context', 'Write this workspace\'s canonical Pathmode context into the repo\'s CLAUDE.md (or AGENTS.md), idempotently — the round-trip. Pulls the latest from Pathmode and replaces the PATHMODE-marked section in place, so the repo\'s agent instructions never drift from the source of truth. Unlike export_context (which returns the text for you to read), this writes the file; re-running when nothing changed reports "no drift". Run it after the canonical context changes in Pathmode.', {
+        format: zod_1.z.enum(['claude-md', 'agents-md']).optional().describe('Target file: claude-md → CLAUDE.md (default), agents-md → AGENTS.md (Codex and other AGENTS.md-aware agents).'),
+        productId: zod_1.z.string().optional().describe('Product ID (optional; defaults to the first active product).'),
+        path: zod_1.z.string().optional().describe('Output file path relative to the project root. Must stay inside the project (absolute paths and ".." are rejected). Defaults to CLAUDE.md / AGENTS.md.'),
+    }, async ({ format, productId, path }) => {
+        if (isLocalMode) {
+            return { content: [{ type: 'text', text: 'Sync requires cloud mode. Use PATHMODE_API_KEY to connect.' }] };
+        }
+        const fmt = format || 'claude-md';
+        try {
+            // Pull the canonical, marker-wrapped section from the cloud (generateClaudeMdContent emits
+            // the same <!-- PATHMODE:START/END --> markers the merge keys on).
+            const section = await requireCloudClient().exportContext(fmt, undefined, productId);
+            const defaultFile = fmt === 'agents-md' ? 'AGENTS.md' : 'CLAUDE.md';
+            const filePath = resolveWithinProject(path || defaultFile);
+            let existing = '';
+            try {
+                existing = (0, fs_1.readFileSync)(filePath, 'utf-8');
+            }
+            catch { /* file doesn't exist yet */ }
+            const merged = (0, pathmode_section_1.mergePathmodeSection)(existing, section);
+            if (merged.action !== 'unchanged')
+                (0, fs_1.writeFileSync)(filePath, merged.content, 'utf-8');
+            const msg = {
+                unchanged: `✓ ${filePath} is already in sync with Pathmode — no drift.`,
+                created: `✓ Created ${filePath} from your Pathmode context.`,
+                appended: `✓ Added the Pathmode context section to ${filePath}.`,
+                replaced: `✓ Synced ${filePath} — refreshed the Pathmode context section from canonical.`,
+            };
+            return { content: [{ type: 'text', text: msg[merged.action] }] };
+        }
+        catch (e) {
+            return { content: [{ type: 'text', text: `Sync failed: ${e.message}` }] };
+        }
+    });
+    cloudOnly.registerTool('get_agent_prompt', {
         title: 'Get Agent Prompt',
         description: 'Get a formatted execution prompt for a specific intent. This is the full structured prompt including objective, outcomes, constraints, edge cases, and verification steps.',
         inputSchema: {
@@ -65103,7 +65586,7 @@ function startMcpServer() {
                 }]
         };
     });
-    server.registerTool('get_workspace', {
+    cloudOnly.registerTool('get_workspace', {
         title: 'Get Workspace',
         description: 'Get workspace details including strategy (vision, non-negotiables, architecture principles), active products, and constitution rules.',
         annotations: READ_ONLY,
@@ -65119,7 +65602,7 @@ function startMcpServer() {
                 }]
         };
     });
-    server.registerTool('get_constitution', {
+    cloudOnly.registerTool('get_constitution', {
         title: 'Get Constitution',
         description: 'Get the workspace constitution rules. These are mandatory constraints that all implementations must respect.',
         annotations: READ_ONLY,
@@ -65138,7 +65621,7 @@ function startMcpServer() {
     // ============================================================
     // Tools — Write Operations
     // ============================================================
-    server.registerTool('update_intent_status', {
+    cloudOnly.registerTool('update_intent_status', {
         title: 'Update Intent Status',
         description: 'Update the status of an intent. Use this to mark an intent as shipped after implementation, or verified after testing. For shipped/verified transitions, the response includes a verification checklist of outcomes, constitution rules, and health metrics that should be confirmed.',
         inputSchema: {
@@ -65167,7 +65650,7 @@ function startMcpServer() {
                 }]
         };
     });
-    server.registerTool('log_implementation_note', {
+    cloudOnly.registerTool('log_implementation_note', {
         title: 'Log Implementation Note',
         description: 'Record a technical decision or implementation note for an intent. Use this to document why you chose a specific approach.',
         inputSchema: {
@@ -65187,7 +65670,32 @@ function startMcpServer() {
                 }]
         };
     });
-    server.registerTool('create_intent', {
+    cloudOnly.registerTool('record_implementation_finding', {
+        title: 'Record Implementation Finding',
+        description: 'Write a correction back to an intent when BUILDING it revealed the spec was wrong. Use this the moment you discover the spec assumed something the implementation contradicts — instead of only fixing it in your head or this chat, record it so the NEXT agent or person inherits the correction. This is the inverse of a decision: it closes the refinement loop so the same stale premise is not rebuilt. Open findings ride into future agent prompts until a human reconciles them into the spec.',
+        inputSchema: {
+            intentId: zod_1.z.string().describe('The intent ID whose spec the finding is about'),
+            assumption: zod_1.z.string().describe('What the spec assumed or said before you built it'),
+            finding: zod_1.z.string().describe('What building it actually revealed — the fact that contradicts the assumption'),
+            target: zod_1.z.string().optional().describe('Which part of the spec this contradicts: "objective", "outcome:<id>", "constraint:<index>", "edgeCase:<id>", "check:<id>" (a verification check — recording this flips that check to failing), or plain prose'),
+            correction: zod_1.z.string().optional().describe('Your proposed correction to the intent, if you have one'),
+            source: zod_1.z.string().optional().describe('Where this came from, e.g. "claude-code @ owner/repo" — provenance for the audit trail'),
+        },
+        annotations: WRITE_OP,
+    }, async ({ intentId, assumption, finding, target, correction, source }) => {
+        if (isLocalMode) {
+            return { content: [{ type: 'text', text: 'Recording findings requires cloud mode. Use PATHMODE_API_KEY to connect.' }] };
+        }
+        const result = await requireCloudClient().recordFinding(intentId, { assumption, finding, target, correction, source });
+        const openCount = result?.openCount;
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Finding recorded for intent ${intentId}. The next agent that pulls this intent will see it flagged as unreconciled until a human folds it into the spec.${typeof openCount === 'number' ? ` Open findings now: ${openCount}.` : ''}`
+                }]
+        };
+    });
+    cloudOnly.registerTool('create_intent', {
         title: 'Create Intent',
         description: 'Create a new intent spec in the workspace. Requires at minimum a title, objective, and productId. Returns the created intent with its ID. Use list_intents first to see existing intents and avoid duplicates.',
         inputSchema: {
@@ -65202,6 +65710,12 @@ function startMcpServer() {
                 expectedBehavior: zod_1.z.string(),
             })).optional().describe('Failure modes and boundary conditions'),
             verification: zod_1.z.object({
+                checks: zod_1.z.array(zod_1.z.object({
+                    kind: zod_1.z.enum(['fastest', 'manual', 'shipped-signal', 'regression-guard', 'test']),
+                    description: zod_1.z.string(),
+                    status: zod_1.z.enum(['unknown', 'passing', 'failing']).optional(),
+                    verifies: zod_1.z.string().optional(),
+                })).optional().describe('Feedback-loop checks (preferred over the legacy test buckets)'),
                 manualChecks: zod_1.z.array(zod_1.z.string()).optional(),
                 unitTests: zod_1.z.array(zod_1.z.string()).optional(),
                 e2eTests: zod_1.z.array(zod_1.z.string()).optional(),
@@ -65221,7 +65735,7 @@ function startMcpServer() {
                 }]
         };
     });
-    server.registerTool('update_intent', {
+    cloudOnly.registerTool('update_intent', {
         title: 'Update Intent',
         description: "Update an existing intent's content. Provide only the fields you want to change. Does NOT change intent status (use update_intent_status for that).",
         inputSchema: {
@@ -65236,6 +65750,12 @@ function startMcpServer() {
                 expectedBehavior: zod_1.z.string(),
             })).optional().describe('Replace all edge cases'),
             verification: zod_1.z.object({
+                checks: zod_1.z.array(zod_1.z.object({
+                    kind: zod_1.z.enum(['fastest', 'manual', 'shipped-signal', 'regression-guard', 'test']),
+                    description: zod_1.z.string(),
+                    status: zod_1.z.enum(['unknown', 'passing', 'failing']).optional(),
+                    verifies: zod_1.z.string().optional(),
+                })).optional().describe('Feedback-loop checks (preferred over the legacy test buckets)'),
                 manualChecks: zod_1.z.array(zod_1.z.string()).optional(),
                 unitTests: zod_1.z.array(zod_1.z.string()).optional(),
                 e2eTests: zod_1.z.array(zod_1.z.string()).optional(),
@@ -65256,7 +65776,7 @@ function startMcpServer() {
                 }]
         };
     });
-    server.registerTool('query_evidence', {
+    cloudOnly.registerTool('query_evidence', {
         title: 'Query Evidence',
         description: 'Search evidence items (friction points, user quotes, observations, metrics, feature requests) by product, type, severity, or text. Returns matching evidence with IDs that can be linked to intents.',
         inputSchema: {
@@ -65280,7 +65800,7 @@ function startMcpServer() {
                 }]
         };
     });
-    server.registerTool('create_evidence', {
+    cloudOnly.registerTool('create_evidence', {
         title: 'Create Evidence',
         description: 'Create a new evidence item (e.g., a discovered bug, user feedback quote, behavioral observation, or feature request). Evidence can later be linked to intents to support prioritization.',
         inputSchema: {
@@ -65307,7 +65827,7 @@ function startMcpServer() {
                 }]
         };
     });
-    server.registerTool('link_evidence', {
+    cloudOnly.registerTool('link_evidence', {
         title: 'Link Evidence to Intent',
         description: 'Link or unlink evidence items to/from an intent. Linking evidence to intents establishes traceability between user problems and planned solutions.',
         inputSchema: {
@@ -65333,7 +65853,7 @@ function startMcpServer() {
                 }]
         };
     });
-    server.registerTool('verify_implementation', {
+    cloudOnly.registerTool('verify_implementation', {
         title: 'Verify Implementation',
         description: 'AI-grade your implementation against the intent spec. Checks each outcome, constraint, constitution rule, and edge case. Returns pass/fail per item with reasoning and an overall score. Also logs the result as an implementation note.',
         inputSchema: {
@@ -65415,9 +65935,15 @@ function startMcpServer() {
     // Intent Compiler — Zero-config tools (no API key needed)
     // ============================================================
     const intentSpecSchema = {
+        id: zod_1.z.string().optional().describe('Existing intent id. Pass it back when re-saving an intent you already saved so the file is updated (version bumped, status preserved) instead of replaced. Omit for a new intent.'),
         title: zod_1.z.string().describe('Short name for the intent'),
         objective: zod_1.z.string().describe('Why this matters — the problem and who has it'),
         outcomes: zod_1.z.array(zod_1.z.string()).describe('Observable, testable state changes'),
+        decisions: zod_1.z.array(zod_1.z.object({
+            choice: zod_1.z.string(),
+            ruledOut: zod_1.z.string().optional(),
+            reason: zod_1.z.string(),
+        })).optional().describe('Decisions settled during design + the alternatives ruled out, so the agent does not relitigate them'),
         constraints: zod_1.z.array(zod_1.z.string()).optional().describe('Hard limits the implementation must respect'),
         edgeCases: zod_1.z.array(zod_1.z.object({
             scenario: zod_1.z.string(),
@@ -65429,6 +65955,12 @@ function startMcpServer() {
             outOfScope: zod_1.z.array(zod_1.z.string()).optional().describe('What is explicitly out of scope'),
         }).optional().describe('Scope boundaries — what to build and what to avoid'),
         verification: zod_1.z.object({
+            checks: zod_1.z.array(zod_1.z.object({
+                kind: zod_1.z.enum(['fastest', 'manual', 'shipped-signal', 'regression-guard', 'test']),
+                description: zod_1.z.string(),
+                status: zod_1.z.enum(['unknown', 'passing', 'failing']).optional(),
+                verifies: zod_1.z.string().optional(),
+            })).optional().describe('Feedback-loop checks (preferred over the legacy test buckets)'),
             manualChecks: zod_1.z.array(zod_1.z.string()).optional(),
             unitTests: zod_1.z.array(zod_1.z.string()).optional(),
             e2eTests: zod_1.z.array(zod_1.z.string()).optional(),
@@ -65445,28 +65977,52 @@ function startMcpServer() {
                 }],
         };
     });
-    server.tool('intent_save', 'Save an intent spec to intent.md in the project root. Called after building a spec through conversation.', {
+    server.tool('intent_save', 'Save an intent spec to intent.md in the project root. Called after building a spec through conversation. Re-saving the same intent bumps its version and preserves its status; it never silently replaces a different intent.', {
         spec: zod_1.z.object(intentSpecSchema),
-        path: zod_1.z.string().optional().describe('File path relative to cwd. Defaults to intent.md'),
-    }, async ({ spec, path }) => {
-        const filePath = (0, path_1.resolve)(process.cwd(), path || 'intent.md');
-        const content = (0, intent_compiler_1.formatIntentMd)({ ...spec, id: `intent_${Date.now()}` });
+        path: zod_1.z.string().optional().describe('File path relative to the project root. Must stay inside the project (absolute paths and ".." are rejected). Defaults to intent.md'),
+        overwrite: zod_1.z.boolean().optional().describe('Replace the file even when it already holds a DIFFERENT intent. Default false — the save is refused instead, so an unrelated spec is never clobbered.'),
+    }, async ({ spec, path, overwrite }) => {
+        const filePath = resolveWithinProject(path || 'intent.md');
+        const existing = (0, local_reader_1.readIntentMeta)(filePath);
+        const decision = (0, save_policy_1.decideSave)({
+            existing,
+            incomingId: spec.id,
+            overwrite,
+            mintId: () => `intent_${Date.now()}`,
+        });
+        if (decision.action === 'refuse') {
+            return {
+                content: [{
+                        type: 'text',
+                        text: [
+                            `✗ Refusing to overwrite ${filePath}`,
+                            '',
+                            `It already holds a different intent (id: ${existing.id ?? 'unknown'}, status: ${existing.status}, version: ${existing.version}), and this spec is "${decision.id}".`,
+                            '',
+                            'Save to another path (pass `path`), or pass overwrite=true to replace it deliberately.',
+                        ].join('\n'),
+                    }],
+            };
+        }
+        const { id, version, status, created } = decision;
+        const content = (0, intent_compiler_1.formatIntentMd)({ ...spec, id }, { version, status, created });
         (0, fs_1.writeFileSync)(filePath, content, 'utf-8');
+        const action = decision.action === 'update' ? `Updated intent spec (v${version})` : 'Saved intent spec';
         return {
             content: [{
                     type: 'text',
-                    text: `✓ Saved intent spec to ${filePath}\n\nTo connect this to Pathmode for dependency tracking and team collaboration, visit pathmode.io`,
+                    text: `✓ ${action} at ${filePath}\n  id: ${id} · status: ${status}\n\nTo connect this to Pathmode for dependency tracking and team collaboration, visit pathmode.io`,
                 }],
         };
     });
     server.tool('intent_export', 'Export an intent spec as .cursorrules, a CLAUDE.md or AGENTS.md section, or a Claude Managed Agents Outcomes rubric for AI agent consumption. Use agents-md for Codex, Cursor, and other AGENTS.md-aware agents.', {
         format: zod_1.z.enum(['cursorrules', 'claude-md', 'agents-md', 'outcome-rubric']).describe('Export format'),
         spec: zod_1.z.object(intentSpecSchema),
-        path: zod_1.z.string().optional().describe('Output file path. Defaults to .cursorrules, CLAUDE.md, or AGENTS.md'),
+        path: zod_1.z.string().optional().describe('Output file path relative to the project root. Must stay inside the project (absolute paths and ".." are rejected). Defaults to .cursorrules, CLAUDE.md, or AGENTS.md'),
     }, async ({ format, spec, path }) => {
         if (format === 'cursorrules') {
             const content = (0, intent_compiler_1.formatCursorRules)(spec);
-            const filePath = (0, path_1.resolve)(process.cwd(), path || '.cursorrules');
+            const filePath = resolveWithinProject(path || '.cursorrules');
             (0, fs_1.writeFileSync)(filePath, content, 'utf-8');
             return {
                 content: [{
@@ -65477,7 +66033,7 @@ function startMcpServer() {
         }
         else if (format === 'outcome-rubric') {
             const content = (0, intent_compiler_1.formatOutcomeRubric)(spec);
-            const filePath = (0, path_1.resolve)(process.cwd(), path || 'outcome-rubric.md');
+            const filePath = resolveWithinProject(path || 'outcome-rubric.md');
             (0, fs_1.writeFileSync)(filePath, content, 'utf-8');
             return {
                 content: [{
@@ -65489,28 +66045,24 @@ function startMcpServer() {
         else {
             const section = (0, intent_compiler_1.formatClaudeMdSection)(spec);
             const defaultFile = format === 'agents-md' ? 'AGENTS.md' : 'CLAUDE.md';
-            const filePath = (0, path_1.resolve)(process.cwd(), path || defaultFile);
-            // Append or replace PATHMODE section in existing file
+            const filePath = resolveWithinProject(path || defaultFile);
             let existing = '';
             try {
                 existing = (0, fs_1.readFileSync)(filePath, 'utf-8');
             }
             catch { /* file doesn't exist yet */ }
-            // Tolerant of the suffixed start marker emitted by formatClaudeMdSection
-            // (`<!-- PATHMODE:START - Do not edit... -->`), so re-exports replace
-            // the block instead of appending a duplicate.
-            const marker = /<!-- PATHMODE:START[\s\S]*?-->[\s\S]*?<!-- PATHMODE:END -->/;
-            const updated = marker.test(existing)
-                ? existing.replace(marker, section)
-                : existing ? existing + '\n\n' + section : section;
-            (0, fs_1.writeFileSync)(filePath, updated, 'utf-8');
+            const merged = (0, pathmode_section_1.mergePathmodeSection)(existing, section);
+            if (merged.action !== 'unchanged')
+                (0, fs_1.writeFileSync)(filePath, merged.content, 'utf-8');
             const audience = format === 'agents-md'
                 ? 'Codex, Cursor, and other AGENTS.md-aware agents'
                 : 'Claude Code';
             return {
                 content: [{
                         type: 'text',
-                        text: `✓ Exported ${defaultFile} section to ${filePath}\n\n${audience} will now see this intent as context in every conversation.`,
+                        text: merged.action === 'unchanged'
+                            ? `✓ ${filePath} already has this intent's context — no change.`
+                            : `✓ Exported ${defaultFile} section to ${filePath}\n\n${audience} will now see this intent as context in every conversation.`,
                     }],
             };
         }
@@ -65626,6 +66178,22 @@ function startMcpServer() {
     // ============================================================
     async function main() {
         const transport = new stdio_js_1.StdioServerTransport();
+        // Tell Pathmode we launched. Hooked to oninitialized rather than placed after
+        // connect() because the client's identity only exists once the MCP handshake has
+        // completed — read it any earlier and getClientVersion() is undefined. Registered
+        // before connect() so we cannot miss the callback. Fire-and-forget: this is the
+        // only signal separating "installed but idle" from "never installed", but it must
+        // never cost the user a working server. See PathmodeClient.handshake.
+        server.server.oninitialized = () => {
+            if (!client)
+                return;
+            const info = server.server.getClientVersion();
+            void client.handshake({
+                client: info?.name,
+                clientVersion: info?.version,
+                serverVersion: SERVER_VERSION,
+            });
+        };
         await server.connect(transport);
     }
     main().catch((error) => {