@3fn/core 14.1.0 → 15.0.0

package/dist/cli/sync/RegionGrain.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * Region grain — extraction and splicing of a DesignerPunk-managed marker
+ * region inside a consumer-owned text file (Spec 123 Task 16.4; design.md
+ * § "C7. `sync` — managed set, grains, classification, pruning, migration",
+ * row `CLAUDE.md` / `.gitignore` — "marker region"; § "THE NAMESPACE RULE,
+ * uniform across all three grains" — "prefix for keys and files, markers
+ * for text").
+ *
+ * Pure functions over strings — no filesystem access. A caller (`attach`,
+ * `sync`) reads the file, calls `spliceRegion`, and only writes when the
+ * result is `ok: true`. This module never throws and never performs I/O:
+ * a missing or unmatched marker pair is a normal (non-exceptional) result
+ * carrying the loud-failure catalog string (`errorCatalog.ts`,
+ * `managedRegionMarkersMissingMessage`).
+ *
+ * **Grain, defined**:
+ *  - The region is the text strictly between the END of the begin-marker's
+ *    own line and the START of the end-marker's own line. The region's
+ *    surrounding marker lines are themselves part of "outside" bytes that
+ *    round-trip unchanged on a successful splice (only the inner content
+ *    is replaced).
+ *  - **First pair wins** (defined nested/duplicate-marker behavior, per
+ *    Task 16.4's brief): extraction matches the FIRST `begin` marker and
+ *    the FIRST `end` marker that follows it. A second `begin`/`end` pair
+ *    appearing later in the file is left untouched, inside the returned
+ *    `after` bytes — it is never read as a second region. A `begin`
+ *    appearing again INSIDE the matched region (before the matched `end`)
+ *    is treated as ordinary region content, not as a nested marker.
+ *  - An absent `begin`, an absent `end`, or an `end` with no preceding
+ *    `begin` are all the same outcome: "missing markers".
+ *  - **CRLF/LF**: the end-of-line style used for the two newlines the
+ *    splice introduces (after `begin`, before `end`) is detected from the
+ *    file's OUTSIDE bytes (the text before the matched `begin` plus the
+ *    text from the matched `end` onward) — never from the region being
+ *    replaced — so re-splicing is idempotent and never flips a CRLF file
+ *    to LF (or vice versa) by way of its own prior contents.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GITIGNORE_COMMENT = exports.CLAUDE_MD_COMMENT = void 0;
+exports.regionMarkers = regionMarkers;
+exports.extractRegion = extractRegion;
+exports.spliceRegion = spliceRegion;
+exports.normalizeRegionContent = normalizeRegionContent;
+exports.wrapRegion = wrapRegion;
+exports.appendRegion = appendRegion;
+const errorCatalog_1 = require("../shared/errorCatalog");
+/** `CLAUDE.md`'s comment syntax (HTML-style wrapping comment). */
+exports.CLAUDE_MD_COMMENT = { open: '<!--', close: '-->' };
+/** `.gitignore`'s comment syntax (line comment, no closer). */
+exports.GITIGNORE_COMMENT = { open: '#' };
+/**
+ * Build the begin/end marker pair for a given comment syntax and region
+ * label (default `managed`, the one DesignerPunk region today — C7 names
+ * `CLAUDE.md` and `.gitignore` as the two text-grain managed surfaces; a
+ * second label is available for a future second region in the same file).
+ */
+function regionMarkers(syntax, label = 'managed') {
+    const begin = `designerpunk:${label}:begin`;
+    const end = `designerpunk:${label}:end`;
+    return syntax.close
+        ? { begin: `${syntax.open} ${begin} ${syntax.close}`, end: `${syntax.open} ${end} ${syntax.close}` }
+        : { begin: `${syntax.open} ${begin}`, end: `${syntax.open} ${end}` };
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Non-greedy: the FIRST `begin`, then the FIRST `(eol)end` that follows it. */
+function buildRegionRegex(markers) {
+    return new RegExp(`${escapeRegExp(markers.begin)}(\\r\\n|\\n)([\\s\\S]*?)(\\r\\n|\\n)${escapeRegExp(markers.end)}`);
+}
+/** CRLF if the sample contains any `\r\n`, else LF. Scope the sample to OUTSIDE bytes for idempotency. */
+function detectEol(sample) {
+    return sample.includes('\r\n') ? '\r\n' : '\n';
+}
+/** Strip a single trailing EOL (of either style) from `value`, if present. */
+function stripTrailingEol(value) {
+    return value.replace(/\r\n$|\n$/, '');
+}
+/** Normalize every line ending in `value` to `eol` (the new region content is ours to control). */
+function normalizeEol(value, eol) {
+    return value.replace(/\r\n|\n/g, eol);
+}
+/**
+ * Extract the managed region from `text`. Returns `{ found: false }` on a
+ * missing or unmatched marker pair — never throws.
+ *
+ * **Invariant**: on a match, `before + region + after === text` exactly —
+ * `region` carries the content between the begin-marker's line and the
+ * end-marker's line, INCLUDING the eol that terminates it (so the split
+ * reassembles byte-for-byte with no extra bookkeeping by the caller).
+ */
+function extractRegion(text, markers) {
+    const match = buildRegionRegex(markers).exec(text);
+    if (!match) {
+        return { found: false };
+    }
+    const innerStart = match.index + markers.begin.length + match[1].length;
+    const endMarkerStart = match.index + match[0].length - markers.end.length;
+    return {
+        found: true,
+        before: text.slice(0, innerStart),
+        region: text.slice(innerStart, endMarkerStart),
+        after: text.slice(endMarkerStart),
+    };
+}
+/**
+ * Replace the managed region's contents with `newContents`. Bytes outside
+ * the matched marker pair are byte-identical to `text` on success.
+ *
+ * On a missing or unmatched marker pair, returns `{ ok: false, message }`
+ * carrying the exact loud-failure catalog string for `file` — the caller
+ * must not write in that case (this function never does I/O itself).
+ */
+function spliceRegion(text, markers, newContents, file) {
+    const match = buildRegionRegex(markers).exec(text);
+    if (!match) {
+        return { ok: false, message: (0, errorCatalog_1.managedRegionMarkersMissingMessage)(file) };
+    }
+    const beginMarkerEnd = match.index + markers.begin.length;
+    const endMarkerStart = match.index + match[0].length - markers.end.length;
+    const before = text.slice(0, beginMarkerEnd); // … up to and including `begin`
+    const after = text.slice(endMarkerStart); // `end` through EOF
+    const eol = detectEol(before + after);
+    const body = stripTrailingEol(normalizeEol(newContents, eol));
+    const inner = body.length > 0 ? `${eol}${body}${eol}` : `${eol}${eol}`;
+    return { ok: true, text: `${before}${inner}${after}` };
+}
+// ---------------------------------------------------------------------------
+// Task 16.5 — the region's comparand, and the first write into a file that has
+// no region yet. Still pure: no I/O, no throws.
+// ---------------------------------------------------------------------------
+/**
+ * The region content in the ONE form `attach` records and `sync` compares (the
+ * manifest's region-entry hash is the sha256 of this string): line endings
+ * normalized to LF, then ONE trailing line ending stripped — exactly the body
+ * `spliceRegion` writes between the markers. So a region extracted from disk
+ * (`extractRegion(…).region`, which carries its own trailing eol, in the file's
+ * eol style) and the package's emitted contents normalize to the same string
+ * when they hold the same lines, on a CRLF file as on an LF one.
+ */
+function normalizeRegionContent(contents) {
+    return stripTrailingEol(normalizeEol(contents, '\n'));
+}
+/** The full text of a file that holds only the managed region (the create case). */
+function wrapRegion(markers, newContents) {
+    const body = normalizeRegionContent(newContents);
+    return body.length > 0 ? `${markers.begin}\n${body}\n${markers.end}\n` : `${markers.begin}\n\n${markers.end}\n`;
+}
+/**
+ * Append a managed region to a file that has NONE yet (the first `attach` into a
+ * consumer's existing `CLAUDE.md`). Every existing byte is kept, in place, as the
+ * prefix of the result; the region goes after it, separated by one blank line, in
+ * the file's own line-ending style. Callers use this only when the manifest
+ * records no region for the file — a recorded region whose markers are gone is
+ * the catalog's "markers missing" case, never re-appended.
+ */
+function appendRegion(text, markers, newContents) {
+    if (text.length === 0)
+        return wrapRegion(markers, newContents);
+    const eol = detectEol(text);
+    const body = normalizeEol(normalizeRegionContent(newContents), eol);
+    const sep = text.endsWith(eol) ? eol : `${eol}${eol}`;
+    const inner = body.length > 0 ? `${eol}${body}${eol}` : `${eol}${eol}`;
+    return `${text}${sep}${markers.begin}${inner}${markers.end}${eol}`;
+}
+//# sourceMappingURL=RegionGrain.js.map

package/dist/cli/sync/Reporter.d.ts

@@ -1,11 +1,40 @@
 /**
- * Format grouped sync output for terminal display.
+ * `sync`'s report — and `sync`'s slice of the loud-failure catalog.
  *
- * @see Spec 111 — Requirement 9
+ * Spec 123 Task 5.4 (design.md § "C7"; § "Error Handling — the loud-failure
+ * catalog"). The report is ALWAYS printed before anything applies ("no class
+ * applies without the report printing first"). Catalog rows are exact strings;
+ * `sync.catalog.test.ts` pins each to its design row, string-equal.
+ *
+ * @see Spec 111 — Requirement 9; Spec 123 design.md § "C7"
  */
 import type { ClassificationResult } from './Classifier';
-export interface ReportOptions {
+import type { SurfaceKeyResult } from './KeyGrain';
+/** Row `deleted-by-you`. */
+export declare function deletedByYouMessage(p: string): string;
+/** Row `untracked-new`. */
+export declare function untrackedNewMessage(p: string, target: string): string;
+/** Row "consumer key under our prefix" (Leonardo A-R1) — info, once per key. */
+export declare function yoursUnderPrefixMessage(key: string): string;
+/** The steward exemption (found-not-fixed item 5): sync never runs against the package's own tree. */
+export declare const STEWARD_REPO_MESSAGE = "this is DesignerPunk's own source tree (the package root) \u2014 sync reconciles a consumer repo against its installed package, so there is nothing to sync here. Nothing was read or written.";
+export declare const OFF_TTY_REPORT_ONLY_MESSAGE = "not a terminal and --apply was not given \u2014 reported only; nothing was changed. Re-run with --apply to apply the updates above.";
+export declare const RETIRED_FORCE_MESSAGE = "--force / --accept-all are retired: updates apply with --apply (or one confirmation on a terminal); a conflict applies only with --overwrite <path>, and a file you deleted only with --restore <path>.";
+export declare function corruptManifestMessage(error: string): string;
+export declare function invalidSurfaceMessage(file: string, error: string): string;
+export declare function packageKeysUnavailableMessage(reason: string): string;
+export interface ReportModel {
     dryRun: boolean;
+    /** Lines describing manifest relocation / pruning (Manifest.ts). */
+    manifestLines: string[];
+    files: ClassificationResult;
+    keys: SurfaceKeyResult[];
+    /** Additional sections (migration, repairs), already rendered. */
+    sections: Array<{
+        title: string;
+        lines: string[];
+    }>;
 }
-export declare function displayReport(classified: ClassificationResult, options: ReportOptions): void;
+export declare function buildReport(model: ReportModel): string[];
+export declare function displayReport(lines: string[]): void;
 //# sourceMappingURL=Reporter.d.ts.map

package/dist/cli/sync/Reporter.js

@@ -1,66 +1,125 @@
 "use strict";
 /**
- * Format grouped sync output for terminal display.
+ * `sync`'s report — and `sync`'s slice of the loud-failure catalog.
  *
- * @see Spec 111 — Requirement 9
+ * Spec 123 Task 5.4 (design.md § "C7"; § "Error Handling — the loud-failure
+ * catalog"). The report is ALWAYS printed before anything applies ("no class
+ * applies without the report printing first"). Catalog rows are exact strings;
+ * `sync.catalog.test.ts` pins each to its design row, string-equal.
+ *
+ * @see Spec 111 — Requirement 9; Spec 123 design.md § "C7"
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.RETIRED_FORCE_MESSAGE = exports.OFF_TTY_REPORT_ONLY_MESSAGE = exports.STEWARD_REPO_MESSAGE = void 0;
+exports.deletedByYouMessage = deletedByYouMessage;
+exports.untrackedNewMessage = untrackedNewMessage;
+exports.yoursUnderPrefixMessage = yoursUnderPrefixMessage;
+exports.corruptManifestMessage = corruptManifestMessage;
+exports.invalidSurfaceMessage = invalidSurfaceMessage;
+exports.packageKeysUnavailableMessage = packageKeysUnavailableMessage;
+exports.buildReport = buildReport;
 exports.displayReport = displayReport;
-function displayReport(classified, options) {
-    const { new: newFiles, updatedSafe, conflicts, removed, unchanged } = classified;
-    const governanceUpdates = [...newFiles, ...updatedSafe].filter(f => f.tier === 'governance');
-    const sourceUpdates = [...newFiles, ...updatedSafe].filter(f => f.tier === 'source');
-    if (options.dryRun) {
-        console.log('🔍 Dry-run mode — no changes will be applied.\n');
-    }
-    // New files
-    if (newFiles.length > 0) {
-        console.log(`📥 New files (${newFiles.length}):`);
-        for (const f of newFiles) {
-            console.log(`   ${f.relativePath} [${f.tier}]`);
-        }
-        console.log('');
-    }
-    // Updated (auto-applying governance)
-    if (governanceUpdates.length > 0) {
-        console.log(`🔄 Governance updates — auto-applying (${governanceUpdates.length}):`);
-        for (const f of governanceUpdates) {
-            console.log(`   ${f.relativePath}`);
-        }
-        console.log('');
-    }
-    // Source updates (require confirmation)
-    if (sourceUpdates.length > 0) {
-        console.log(`📋 Source updates — confirm required (${sourceUpdates.length}):`);
-        for (const f of sourceUpdates) {
-            const note = f.reason ? ` (${f.reason})` : '';
-            console.log(`   ${f.relativePath}${note}`);
-        }
-        console.log('');
+// ---------------------------------------------------------------------------
+// Catalog rows (design.md § "Error Handling") — exact strings
+// ---------------------------------------------------------------------------
+/** Row `deleted-by-you`. */
+function deletedByYouMessage(p) {
+    return `${p} was generated earlier and you deleted it — not re-adding. To restore: npx designerpunk sync --restore ${p}`;
+}
+/** Row `untracked-new`. */
+function untrackedNewMessage(p, target) {
+    return `${p} would be generated but was never recorded — not adding it on first sync. To add it: npx designerpunk attach --target=${target}`;
+}
+/** Row "consumer key under our prefix" (Leonardo A-R1) — info, once per key. */
+function yoursUnderPrefixMessage(key) {
+    return `${key} is under DesignerPunk's prefix but was not generated by DesignerPunk — it is yours; sync will not manage or remove it`;
+}
+// ---------------------------------------------------------------------------
+// Strings authored at Task 5 (no catalog row exists) — pinned by the same test
+// ---------------------------------------------------------------------------
+/** The steward exemption (found-not-fixed item 5): sync never runs against the package's own tree. */
+exports.STEWARD_REPO_MESSAGE = "this is DesignerPunk's own source tree (the package root) — sync reconciles a consumer repo against its installed package, so there is nothing to sync here. Nothing was read or written.";
+exports.OFF_TTY_REPORT_ONLY_MESSAGE = 'not a terminal and --apply was not given — reported only; nothing was changed. Re-run with --apply to apply the updates above.';
+exports.RETIRED_FORCE_MESSAGE = '--force / --accept-all are retired: updates apply with --apply (or one confirmation on a terminal); a conflict applies only with --overwrite <path>, and a file you deleted only with --restore <path>.';
+function corruptManifestMessage(error) {
+    return `designerpunk.manifest.json could not be read (${error}) — refusing to guess its baseline. Restore it from version control; nothing was changed.`;
+}
+function invalidSurfaceMessage(file, error) {
+    return `${file} is not valid JSON (${error}) — not reading or rewriting it; DesignerPunk's keys in it were not checked.`;
+}
+function packageKeysUnavailableMessage(reason) {
+    return `could not compute DesignerPunk's MCP keys from the installed package — ${reason}. Your MCP config files were not checked.`;
+}
+function buildReport(model) {
+    const out = [];
+    const { files } = model;
+    if (model.dryRun)
+        out.push('🔍 Dry-run mode — no changes will be applied.', '');
+    if (model.manifestLines.length > 0) {
+        out.push('📋 Manifest:');
+        for (const l of model.manifestLines)
+            out.push(`   ${l}`);
+        out.push('');
     }
-    // Conflicts
-    if (conflicts.length > 0) {
-        console.log(`⚠️  Conflicts (${conflicts.length}):`);
-        for (const f of conflicts) {
-            console.log(`   ${f.relativePath} — ${f.reason}`);
-        }
-        console.log('');
+    const keyItems = (cls) => model.keys.flatMap((s) => s.classified.filter((c) => c.classification === cls).map((c) => `${s.surface.file}#${c.key}`));
+    const newItems = [...files.new.map((f) => f.relativePath), ...keyItems('new')];
+    const updated = [...files.updatedSafe.map((f) => f.relativePath), ...keyItems('updated-safe')];
+    const conflicts = [
+        ...files.conflicts.map((f) => `${f.relativePath} — ${f.reason}`),
+        ...keyItems('conflict').map((k) => `${k} — you edited DesignerPunk's key`),
+    ];
+    const removed = [...files.removed.map((f) => f.relativePath), ...keyItems('removed')];
+    const deleted = [...files.deletedByYou.map((f) => f.relativePath), ...keyItems('deleted-by-you')];
+    const untracked = model.keys.flatMap((s) => s.classified.filter((c) => c.classification === 'untracked-new').map((c) => ({ p: `${s.surface.file}#${c.key}`, t: s.surface.target })));
+    const group = (title, items) => {
+        if (items.length === 0)
+            return;
+        out.push(`${title} (${items.length}):`);
+        for (const i of items)
+            out.push(`   ${i}`);
+        out.push('');
+    };
+    group('📥 New from the package — applies after confirmation or --apply', newItems);
+    group('🔄 Updated in the package, unchanged by you — applies after confirmation or --apply', updated);
+    group('⚠️  Conflicts — never overwritten (per path: --overwrite <path>)', conflicts);
+    group('⚠️  Removed from package (left in place)', removed);
+    if (deleted.length > 0) {
+        out.push(`🗑  Deleted by you (${deleted.length}):`);
+        for (const p of deleted)
+            out.push(`   ${deletedByYouMessage(p)}`);
+        out.push('');
     }
-    // Removed
-    if (removed.length > 0) {
-        console.log(`⚠️  Removed from package:`);
-        for (const f of removed) {
-            console.log(`   ${f.relativePath}`);
-        }
-        console.log('');
+    if (untracked.length > 0) {
+        out.push(`➕ Never recorded (${untracked.length}):`);
+        for (const u of untracked)
+            out.push(`   ${untrackedNewMessage(u.p, u.t)}`);
+        out.push('');
     }
-    // Unchanged summary
-    if (unchanged.length > 0) {
-        console.log(`✓ ${unchanged.length} file${unchanged.length === 1 ? '' : 's'} unchanged`);
+    for (const s of model.keys) {
+        if (s.invalid)
+            out.push(`⚠️  ${invalidSurfaceMessage(s.surface.file, s.invalid)}`, '');
+        for (const k of s.yoursUnderPrefix)
+            out.push(`ℹ️  ${yoursUnderPrefixMessage(k)}`);
     }
-    // Total summary
-    if (newFiles.length === 0 && updatedSafe.length === 0 && conflicts.length === 0) {
-        console.log('\n✅ Everything is up to date.');
+    if (model.keys.some((s) => s.yoursUnderPrefix.length > 0))
+        out.push('');
+    for (const section of model.sections) {
+        if (section.lines.length === 0)
+            continue;
+        out.push(section.title);
+        for (const l of section.lines)
+            out.push(`   ${l}`);
+        out.push('');
     }
+    const unchangedCount = files.unchanged.length + model.keys.reduce((n, s) => n + s.classified.filter((c) => c.classification === 'unchanged').length, 0);
+    if (unchangedCount > 0)
+        out.push(`✓ ${unchangedCount} managed item${unchangedCount === 1 ? '' : 's'} unchanged`);
+    if (newItems.length === 0 && updated.length === 0 && conflicts.length === 0)
+        out.push('✅ Everything DesignerPunk manages is up to date.');
+    return out;
+}
+function displayReport(lines) {
+    for (const l of lines)
+        console.log(l);
 }
 //# sourceMappingURL=Reporter.js.map

package/dist/cli/sync/SteeringDirCheck.d.ts

@@ -34,12 +34,32 @@ export interface StaleSteeringDirFinding {
  * that have no `MCP_STEERING_DIR`) produce no finding.
  */
 export declare function detectStaleSteeringDir(projectRoot: string): StaleSteeringDirFinding[];
+/** The package's MCP-config template, relative to the package root — the value a fresh `init`/`attach` writes. */
+export declare const MCP_TEMPLATE_REL = "src/cli/templates/mcp-config.json.template";
 /**
- * Compute the recommended value for a stale entry by swapping the
- * `.kiro/steering` segment for `governance` while preserving any prefix
- * (e.g. `./node_modules/@3fn/core/.kiro/steering` → `./node_modules/@3fn/core/governance`).
+ * The `MCP_STEERING_DIR` value the package's MCP template carries for the docs
+ * server — read from the template itself, never a second hard-coded copy. `null`
+ * when the template cannot be read (a damaged install): the caller then makes no
+ * recommendation rather than guessing one.
+ *
+ * This module sits at `src/cli/sync/` (`dist/cli/sync/` packed) — THREE levels below
+ * the package root — so it hands `resolvePackageRoot` its parent directory, which
+ * satisfies that util's two-levels-down contract.
+ */
+export declare function templateSteeringDir(pkgRoot?: string): string | null;
+/**
+ * Compute the recommended value for a stale entry.
+ *
+ * - **Package-prefixed** (the value reaches into `node_modules/`, e.g.
+ *   `./node_modules/@3fn/core/.kiro/steering`): swap the `.kiro/steering` segment for
+ *   `governance`, keeping the prefix → `./node_modules/@3fn/core/governance`.
+ * - **No package prefix** (the pre-123 `init` wrote the bare `./.kiro/steering`,
+ *   pointing at the consumer's OWN copies): the swap would give `./governance`, a
+ *   directory no consumer repo has — the docs MCP then indexes nothing. Recommend the
+ *   template's value instead (`.kiro/issues/2026-10-02-sync-steering-dir-suggestion-writes-broken-path.md`).
+ *   `null` when the template cannot be read.
  */
-export declare function recommendedSteeringDir(currentValue: string): string;
+export declare function recommendedSteeringDir(currentValue: string, templateValue?: string | null): string | null;
 /**
  * Report stale findings to the consumer and (interactively) offer to update them.
  * In dry-run / non-TTY mode this only reports. Returns the number of configs updated.
@@ -47,4 +67,12 @@ export declare function recommendedSteeringDir(currentValue: string): string;
 export declare function reportAndMaybeFixStaleSteeringDir(projectRoot: string, options: {
     dryRun: boolean;
 }, rl?: readline.Interface): Promise<number>;
+/**
+ * Rewrite a single stale entry in place, preserving formatting as best we can
+ * by parsing and re-serializing with 2-space indent. Writes nothing (returns
+ * `false`) when there is no recommendation for the entry.
+ *
+ * @internal Exported for testing.
+ */
+export declare function applySteeringDirFix(projectRoot: string, finding: StaleSteeringDirFinding, templateValue?: string | null): boolean;
 //# sourceMappingURL=SteeringDirCheck.d.ts.map

package/dist/cli/sync/SteeringDirCheck.js

@@ -49,13 +49,16 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EXPECTED_STEERING_DIR_SEGMENT = void 0;
+exports.MCP_TEMPLATE_REL = exports.EXPECTED_STEERING_DIR_SEGMENT = void 0;
 exports.detectStaleSteeringDir = detectStaleSteeringDir;
+exports.templateSteeringDir = templateSteeringDir;
 exports.recommendedSteeringDir = recommendedSteeringDir;
 exports.reportAndMaybeFixStaleSteeringDir = reportAndMaybeFixStaleSteeringDir;
+exports.applySteeringDirFix = applySteeringDirFix;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const readline = __importStar(require("readline"));
+const resolvePackageRoot_1 = require("../shared/resolvePackageRoot");
 /** The post-119-A served corpus directory the docs MCP should index. */
 exports.EXPECTED_STEERING_DIR_SEGMENT = 'governance';
 /** The pre-119-A location — a value still pointing here is stale. */
@@ -104,13 +107,45 @@ function detectStaleSteeringDir(projectRoot) {
     }
     return findings;
 }
+/** The package's MCP-config template, relative to the package root — the value a fresh `init`/`attach` writes. */
+exports.MCP_TEMPLATE_REL = 'src/cli/templates/mcp-config.json.template';
 /**
- * Compute the recommended value for a stale entry by swapping the
- * `.kiro/steering` segment for `governance` while preserving any prefix
- * (e.g. `./node_modules/@3fn/core/.kiro/steering` → `./node_modules/@3fn/core/governance`).
+ * The `MCP_STEERING_DIR` value the package's MCP template carries for the docs
+ * server — read from the template itself, never a second hard-coded copy. `null`
+ * when the template cannot be read (a damaged install): the caller then makes no
+ * recommendation rather than guessing one.
+ *
+ * This module sits at `src/cli/sync/` (`dist/cli/sync/` packed) — THREE levels below
+ * the package root — so it hands `resolvePackageRoot` its parent directory, which
+ * satisfies that util's two-levels-down contract.
+ */
+function templateSteeringDir(pkgRoot = (0, resolvePackageRoot_1.resolvePackageRoot)(path.join(__dirname, '..'))) {
+    try {
+        const template = JSON.parse(fs.readFileSync(path.join(pkgRoot, exports.MCP_TEMPLATE_REL), 'utf-8'));
+        const value = template.mcpServers?.['designerpunk-docs']?.env?.MCP_STEERING_DIR;
+        return typeof value === 'string' && value.length > 0 ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compute the recommended value for a stale entry.
+ *
+ * - **Package-prefixed** (the value reaches into `node_modules/`, e.g.
+ *   `./node_modules/@3fn/core/.kiro/steering`): swap the `.kiro/steering` segment for
+ *   `governance`, keeping the prefix → `./node_modules/@3fn/core/governance`.
+ * - **No package prefix** (the pre-123 `init` wrote the bare `./.kiro/steering`,
+ *   pointing at the consumer's OWN copies): the swap would give `./governance`, a
+ *   directory no consumer repo has — the docs MCP then indexes nothing. Recommend the
+ *   template's value instead (`.kiro/issues/2026-10-02-sync-steering-dir-suggestion-writes-broken-path.md`).
+ *   `null` when the template cannot be read.
  */
-function recommendedSteeringDir(currentValue) {
-    return currentValue.replace(/\.kiro\/steering\/?$/, exports.EXPECTED_STEERING_DIR_SEGMENT);
+function recommendedSteeringDir(currentValue, templateValue = templateSteeringDir()) {
+    if (currentValue.includes('node_modules/')) {
+        return currentValue.replace(/\.kiro\/steering\/?$/, exports.EXPECTED_STEERING_DIR_SEGMENT);
+    }
+    return templateValue;
 }
 /**
  * Report stale findings to the consumer and (interactively) offer to update them.
@@ -123,12 +158,19 @@ async function reportAndMaybeFixStaleSteeringDir(projectRoot, options, rl) {
     console.log(`\n⚠ MCP_STEERING_DIR points at the pre-119-A '.kiro/steering' location in ` +
         `${findings.length} config${findings.length === 1 ? '' : 's'}. ` +
         `The docs MCP now serves the relocated corpus from 'governance/'.`);
+    const templateValue = templateSteeringDir();
+    let recommendable = 0;
     for (const f of findings) {
+        const recommended = recommendedSteeringDir(f.currentValue, templateValue);
+        if (recommended !== null)
+            recommendable++;
         console.log(`    ${f.configPath} → ${f.serverKey}: "${f.currentValue}" ` +
-            `(recommended: "${recommendedSteeringDir(f.currentValue)}")`);
+            (recommended !== null
+                ? `(recommended: "${recommended}")`
+                : `(no recommendation: the installed @3fn/core's ${exports.MCP_TEMPLATE_REL} could not be read)`));
     }
-    // Dry-run / non-interactive: advisory only.
-    if (options.dryRun || !process.stdin.isTTY) {
+    // Dry-run / non-interactive: advisory only. Nothing to offer when no entry has a recommendation.
+    if (options.dryRun || !process.stdin.isTTY || recommendable === 0) {
         console.log('    Update MCP_STEERING_DIR to the recommended value so the docs MCP indexes the relocated docs.');
         return 0;
     }
@@ -137,10 +179,10 @@ async function reportAndMaybeFixStaleSteeringDir(projectRoot, options, rl) {
         rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     }
     let updated = 0;
-    const answer = await new Promise(resolve => rl.question(`\n  Update MCP_STEERING_DIR to 'governance/' in the above config(s)? [Y/n]: `, resolve));
+    const answer = await new Promise(resolve => rl.question(`\n  Update MCP_STEERING_DIR to the recommended value in the above config(s)? [Y/n]: `, resolve));
     if (answer.toLowerCase().trim() !== 'n') {
         for (const f of findings) {
-            if (applySteeringDirFix(projectRoot, f))
+            if (applySteeringDirFix(projectRoot, f, templateValue))
                 updated++;
         }
         console.log(`  ✓ Updated MCP_STEERING_DIR in ${updated} config${updated === 1 ? '' : 's'}.`);
@@ -154,16 +196,22 @@ async function reportAndMaybeFixStaleSteeringDir(projectRoot, options, rl) {
 }
 /**
  * Rewrite a single stale entry in place, preserving formatting as best we can
- * by parsing and re-serializing with 2-space indent.
+ * by parsing and re-serializing with 2-space indent. Writes nothing (returns
+ * `false`) when there is no recommendation for the entry.
+ *
+ * @internal Exported for testing.
  */
-function applySteeringDirFix(projectRoot, finding) {
+function applySteeringDirFix(projectRoot, finding, templateValue = templateSteeringDir()) {
     const abs = path.join(projectRoot, finding.configPath);
     try {
         const parsed = JSON.parse(fs.readFileSync(abs, 'utf-8'));
         const env = parsed?.mcpServers?.[finding.serverKey]?.env;
         if (!env || typeof env.MCP_STEERING_DIR !== 'string')
             return false;
-        env.MCP_STEERING_DIR = recommendedSteeringDir(env.MCP_STEERING_DIR);
+        const recommended = recommendedSteeringDir(env.MCP_STEERING_DIR, templateValue);
+        if (recommended === null)
+            return false;
+        env.MCP_STEERING_DIR = recommended;
         fs.writeFileSync(abs, JSON.stringify(parsed, null, 2) + '\n', 'utf-8');
         return true;
     }