@pathmode/mcp-server 1.8.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}`);
@@ -34104,14 +34137,18 @@ function decisionLines(decisions, heading) {
 /**
  * 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)
@@ -34544,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).
  */
@@ -34575,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.
  */
@@ -34584,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',
         };
@@ -34622,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;
@@ -34668,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)
@@ -34697,39 +34814,104 @@ 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);
+}
 
 
 /***/ }),
@@ -34784,6 +34966,64 @@ function mergePathmodeSection(existing, section) {
 }
 
 
+/***/ }),
+
+/***/ 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,
+    };
+}
+
+
 /***/ }),
 
 /***/ 8294:
@@ -34858,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'],
@@ -34918,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) {
@@ -35011,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 ──────────────────────────────────────
@@ -35031,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}`);
@@ -35042,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('');
 }
 
 
@@ -64623,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.8.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"}}');
 
 /***/ })
 
@@ -64676,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:
  *   {
@@ -64717,6 +64990,7 @@ 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);
@@ -64746,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
@@ -64779,6 +65056,9 @@ 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();
     }
@@ -64946,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') },
@@ -65005,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: {
@@ -65211,7 +65491,7 @@ function startMcpServer() {
             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), "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: {
@@ -65286,7 +65566,7 @@ function startMcpServer() {
             return { content: [{ type: 'text', text: `Sync failed: ${e.message}` }] };
         }
     });
-    server.registerTool('get_agent_prompt', {
+    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: {
@@ -65306,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,
@@ -65322,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,
@@ -65341,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: {
@@ -65370,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: {
@@ -65390,7 +65670,7 @@ function startMcpServer() {
                 }]
         };
     });
-    server.registerTool('record_implementation_finding', {
+    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: {
@@ -65415,7 +65695,7 @@ function startMcpServer() {
                 }]
         };
     });
-    server.registerTool('create_intent', {
+    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: {
@@ -65455,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: {
@@ -65496,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: {
@@ -65520,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: {
@@ -65547,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: {
@@ -65573,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: {
@@ -65655,6 +65935,7 @@ 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'),
@@ -65696,17 +65977,41 @@ 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 the project root. Must stay inside the project (absolute paths and ".." are rejected). Defaults to intent.md'),
-    }, async ({ spec, path }) => {
+        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 content = (0, intent_compiler_1.formatIntentMd)({ ...spec, id: `intent_${Date.now()}` });
+        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`,
                 }],
         };
     });
@@ -65873,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) => {