@stravica-ai/digital-operator-pa 0.1.8 → 0.1.10

package/dist/engineering-pa-cli/src/knowledge/cli.mjs

@@ -63,6 +63,10 @@ Graph location: <repo-root>/operator/knowledge/.graph.json.
 Repo-root resolution: \$DAVE_REPO_ROOT / \$PA_REPO_ROOT, else walk upward
 from cwd looking for a .git entry.
 
+The graph is a per-device artefact: untracked, and rebuilt locally by
+library-sync-cycle's graph-rebuild leg. If it is absent, the first query
+rebuilds it on demand (one stderr line, then the answer) rather than failing.
+
 JSON output shape (stable-by-convention — consumed by dispatch-briefer):
   { "verb": "<name>", ...verb-specific fields }
 

package/dist/engineering-pa-cli/src/knowledge/graph.mjs

@@ -31,12 +31,65 @@ const GRAPH_RELATIVE_PATH = 'operator/knowledge/.graph.json';
 
 // --- loader ---------------------------------------------------------------
 
-export async function loadGraph({ repoRoot, graphPath } = {}) {
+// SELF-HEAL ON A MISSING GRAPH (w-2026-07-29-007)
+//
+// Since the estate moved to per-device retrieval artefacts (w-2026-07-29-002),
+// `.graph.json` is untracked and rebuilt locally by `library-sync-cycle`'s
+// graph-rebuild leg. Any host that pulls the untracking commit before it runs a
+// sync cycle -- an unmigrated laptop, a host that has been off during a move --
+// therefore has a knowledge tree on disk and no graph over it, and every
+// `pa knowledge` verb used to exit 3. Refusing to answer when the source data
+// is right there is the wrong default for a retrieval tool.
+//
+// So a missing artefact triggers an on-demand build (same two builders, same
+// order, same root as the scheduled leg) and the query is served. The artefact
+// is a pure function of the tree, so this cannot produce a graph the scheduled
+// leg would not have produced -- only a less well-stamped one, which the
+// `coverage.builtBy` marker makes visible.
+//
+// GATE. Self-heal fires only when the caller passed a `repoRoot` and did NOT
+// pass an explicit `graphPath`. An explicit `graphPath` means the caller is
+// pointing at a specific artefact (a fixture, a snapshot, an inspection copy);
+// the builders write to `<root>/operator/knowledge/.graph.json` and nowhere
+// else, so building would silently answer a different question than the one
+// asked. Those callers keep the exit-3 refusal.
+//
+// Set `autoBuild: false` to opt out entirely.
+export async function loadGraph({ repoRoot, graphPath, autoBuild = true, stderr = process.stderr } = {}) {
   const path = graphPath ?? join(repoRoot, GRAPH_RELATIVE_PATH);
   if (!existsSync(path)) {
-    const err = new Error(`knowledge graph not found at ${path}`);
-    err.exitCode = 3;
-    throw err;
+    const canBuild = autoBuild && Boolean(repoRoot) && graphPath == null;
+    if (!canBuild) {
+      const err = new Error(`knowledge graph not found at ${path}`);
+      err.exitCode = 3;
+      throw err;
+    }
+    try {
+      const { rebuildRetrievalArtefacts } = await import('./rebuild.mjs');
+      const built = await rebuildRetrievalArtefacts({ root: repoRoot });
+      stderr.write(
+        `[pa knowledge] no graph at ${path} -- built on demand ` +
+        `(${built.nodeCount} nodes, ${built.edgeCount} edges, ${built.durationMs}ms); ` +
+        'retrieval artefacts are per-device and normally rebuilt by library-sync-cycle\n',
+      );
+    } catch (e) {
+      // Both errors, in one message: "graph missing" alone sends the reader
+      // looking for the artefact, when what they need to fix is why it could
+      // not be built.
+      const err = new Error(
+        `knowledge graph not found at ${path}, and the on-demand rebuild failed: ${e.message}`,
+      );
+      err.exitCode = 3;
+      err.cause = e;
+      throw err;
+    }
+    if (!existsSync(path)) {
+      const err = new Error(
+        `knowledge graph not found at ${path}, and the on-demand rebuild did not produce it`,
+      );
+      err.exitCode = 3;
+      throw err;
+    }
   }
   let raw;
   try {

package/dist/engineering-pa-cli/src/knowledge/rebuild.mjs

@@ -0,0 +1,118 @@
+// rebuild.mjs — in-process rebuild of the retrieval artefacts.
+//
+// WHY THIS EXISTS
+// ---------------
+// As of 2026-07-29 (estate ruling w-2026-07-29-002) `operator/knowledge/.graph.json`
+// and `.backlinks.json` are PER-DEVICE artefacts: untracked by the library
+// repos, and rebuilt locally by `library-sync-cycle`'s `graph-rebuild` leg
+// immediately after the down-path materialises the tree they describe. Each
+// device's graph then describes exactly the tree that device can see, instead
+// of one build host's partial view being shipped to everyone.
+//
+// The migration has a gap. A host that pulls the untracking commit but has not
+// yet run a sync cycle -- or whose cycle is not installed at all -- ends up with
+// no artefact on disk, and every `pa knowledge` verb hard-failed with exit 3
+// ("knowledge graph not found"). The retrieval tool going dark is a bad failure
+// for a host whose whole job is to answer questions from the library, and the
+// data needed to fix it is sitting right there on disk.
+//
+// So `loadGraph` self-heals: on a missing artefact it calls this module, which
+// runs the same two builders the graph-rebuild leg runs, in the same order,
+// against the same workspace root -- then serves the query. The artefact is a
+// pure function of the tree, so building it on demand cannot produce anything
+// the scheduled leg would not have produced.
+//
+// IN-PROCESS, NOT SPAWNED
+// -----------------------
+// The builders ship in the same package as this module, so we import and call
+// them rather than spawning `node <script> --root <root>`. That removes a
+// process launch (~50 ms of the total) and, more importantly, removes the
+// `--root`-resolution hazard entirely: a spawned builder without `--root`
+// resolves its default four levels up from its own script path, which for a
+// package install lands inside the versioned `dist/` tree rather than the
+// workspace (the "versioned-dist-path trap"). An imported function takes the
+// root as an argument and cannot get this wrong.
+//
+// PROVENANCE
+// ----------
+// Both artefacts carry a `coverage` stamp naming which path built them. The
+// scheduled leg writes `builtBy: 'library-sync-cycle:graph-rebuild'` plus the
+// device's entitlement picture; this path writes `builtBy: 'loadGraph:on-demand'`
+// and honestly reports `complete: null`, because a CLI invocation has no
+// registry context and therefore cannot know which knowledge mounts this device
+// is not entitled to. An on-demand graph is a fallback, not a substitute for
+// the stamped one -- and it says so in its own output.
+
+import { buildBacklinkIndex } from '../../../engineering-pa-core/src/knowledge/retrieval/backlink-indexer.mjs';
+import { buildKnowledgeGraph } from '../../../engineering-pa-core/src/knowledge/retrieval/graph-builder.mjs';
+
+/** Marks artefacts produced by the self-heal path rather than the scheduled leg. */
+export const ON_DEMAND_BUILT_BY = 'loadGraph:on-demand';
+
+/**
+ * The coverage stamp this path writes.
+ *
+ * Shape-compatible with the one `library-sync-cycle:graph-rebuild` writes so a
+ * reader can branch on the same fields, but honest about what it does not know:
+ * `complete: null` means "this build could not determine its own coverage",
+ * which is different from `false` ("it has a named hole"). `registryError`
+ * carries the reason in the same slot the scheduled leg uses, so the estate's
+ * `formatCoverageSummary` renders a truthful "coverage UNKNOWN (...)" line
+ * without special-casing.
+ *
+ * `rebuildDurationMs` stays null on this path: the stamp has to exist before the
+ * artefacts are serialised, so the elapsed time is not known yet. The caller
+ * gets it as a return value for its stderr line instead of the artefact
+ * carrying a number it would have to be rewritten to hold.
+ *
+ * @param {{workspace:string, builtOn?:string}} args
+ * @returns {object}
+ */
+export function buildOnDemandCoverage({
+  workspace,
+  builtOn = new Date().toISOString(),
+}) {
+  return {
+    builtOn,
+    deviceId: null,
+    builtBy: ON_DEMAND_BUILT_BY,
+    workspace,
+    sourceMarkdownCount: null,
+    rebuildDurationMs: null,
+    registryDir: null,
+    entitledRepos: [],
+    unentitledRepos: [],
+    unentitledKnowledgeMountTargets: [],
+    complete: null,
+    registryError: 'built on demand by pa knowledge -- no registry context, coverage not determined',
+  };
+}
+
+/**
+ * Rebuild `.backlinks.json` then `.graph.json` over `root`.
+ *
+ * Order is a correctness property, not a preference: `graph-builder` reads the
+ * file `backlink-indexer` writes, so running them the other way round builds a
+ * graph from the previous run's backlinks.
+ *
+ * Throws whatever the builders throw (a missing `operator/knowledge/` yields
+ * ENOENT on the first write) -- the caller decides how loud to be.
+ *
+ * @param {{root:string, coverage?:object|null}} args
+ * @returns {Promise<{nodeCount:number, edgeCount:number, targetCount:number, durationMs:number, graphPath:string, backlinksPath:string}>}
+ */
+export async function rebuildRetrievalArtefacts({ root, coverage }) {
+  const started = Date.now();
+  const stamp = coverage ?? buildOnDemandCoverage({ workspace: root });
+  const backlinks = await buildBacklinkIndex({ root, coverage: stamp });
+  const graph = await buildKnowledgeGraph({ root, coverage: stamp });
+  const durationMs = Date.now() - started;
+  return {
+    nodeCount: graph.nodeCount,
+    edgeCount: graph.edgeCount,
+    targetCount: backlinks.targetCount,
+    durationMs,
+    graphPath: graph.outPath,
+    backlinksPath: backlinks.outPath,
+  };
+}

package/dist/engineering-pa-core/docs/knowledge-scaffold.md

@@ -56,7 +56,13 @@ Use double-bracket syntax to link to other documents:
 See [[fermentation]] for details on lacto-fermentation.
 ```
 
-Wiki-links are resolved by searching for a file matching the target name (case-insensitive) across all knowledge domains. If multiple matches exist, the link resolves to the most recently updated one.
+Wiki-links are resolved against the real file set, in this order:
+
+1. A target containing a `/` (`[[../wespa/spi-no-staging]]`, `[[engineering/standards/secrets]]`) is tried relative to the linking document first, then repo-root-relative, then relative to each knowledge root. An over-deep `../` chain is salvaged when exactly one file can be meant.
+2. A bare target (`[[fermentation]]`) matches on filename across all knowledge domains -- exact case first, case-insensitive second.
+3. If several files share the name, the one in the linking document's own directory wins, then the one in its own domain. If neither disambiguates, the link is reported as ambiguous and produces no edge -- the builder does not guess, because a guess silently changes what `related`, `path` and `orphans` answer.
+
+A wiki-link that resolves to nothing is reported as dangling and produces no edge. It is never turned into a node: a graph that invents a document for every broken reference inflates itself and corrupts its own orphan statistics.
 
 ### Standard markdown links
 
@@ -66,6 +72,26 @@ Use standard markdown links for explicit paths:
 See [fermentation](techniques/fermentation.md) for details.
 ```
 
+Markdown links resolve relative to the linking document. Unlike wiki-links, a markdown link to a file that is not present still produces a node -- that is deliberate, and is how a document the build host is not entitled to stays visible in the graph.
+
+### Machine-readable hubs (`index.json`)
+
+A directory can carry an `index.json` listing its documents with curated descriptions:
+
+```json
+{
+  "version": "1.0",
+  "patterns": [
+    { "id": "some-pattern", "path": "knowledge/engineering/patterns/some-pattern.md",
+      "description": "What it is and when it bites" }
+  ]
+}
+```
+
+Every `.md` path in such a file becomes an edge from the hub to the document, so a document listed in its domain's index is indexed for retrieval without also needing a prose link. Entry paths may be canonical-repo-relative (`knowledge/...`), repo-root-relative, or relative to the index file. A `path` naming a directory resolves to that directory's `README.md`. Hubs nest: each `index.json` is linked from the nearest `index.json` above it.
+
+`index.json` files are hand-maintained source, not build output -- no builder writes them.
+
 
 ## Backlink indexing
 
@@ -89,7 +115,8 @@ The retrieval system builds a graph of document relationships based on links. Th
 
 The retrieval tools at `core/knowledge/retrieval/` provide:
 
-- **index-builder.mjs** -- Rebuilds all indexes (domain registry, backlinks, adjacency graph)
+- **index-builder.mjs** -- Rebuilds the domain registry (`operator/knowledge/domains.json`)
+- **backlink-indexer.mjs** / **graph-builder.mjs** -- Rebuild the per-device retrieval artefacts (`.backlinks.json`, `.graph.json`). These two are untracked and device-local: each host builds its own over the tree it can actually see, and `pa knowledge` rebuilds them on demand if they are missing. Do not commit them.
 - **search.mjs** -- Full-text search across all knowledge
 - **graph.mjs** -- Graph queries (neighbours, paths, clusters)
 

package/dist/engineering-pa-core/src/distill/prompt.mjs

@@ -14,6 +14,11 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 // Absolute paths to the bundled retrieval tools. From this module
 // (`packages/core/src/distill/prompt.mjs`) the retrieval tools live at
 // `../knowledge/retrieval/`.
+//
+// Only the index builder is named in the prompt. The backlink indexer and the
+// graph builder are still exported here -- they are part of this module's
+// public surface and callers outside the sweep use them -- but a distillation
+// sweep must NOT run them; see step 4 for why.
 export const RETRIEVAL_INDEX_BUILDER = resolve(__dirname, '..', 'knowledge', 'retrieval', 'index-builder.mjs');
 export const RETRIEVAL_BACKLINK_INDEXER = resolve(__dirname, '..', 'knowledge', 'retrieval', 'backlink-indexer.mjs');
 export const RETRIEVAL_GRAPH_BUILDER = resolve(__dirname, '..', 'knowledge', 'retrieval', 'graph-builder.mjs');
@@ -22,11 +27,19 @@ export const RETRIEVAL_GRAPH_BUILDER = resolve(__dirname, '..', 'knowledge', 're
  * Build the distillation prompt text. Absolute paths are interpolated for the
  * retrieval-tool invocations so Claude doesn't have to guess at install
  * locations.
+ *
+ * `workspaceRoot` is interpolated as the builder's `--root`, and it is
+ * load-bearing. Without `--root` the builder falls back to `$DAVE_ROOT`, then to
+ * a path resolved four levels up from its own script -- which for a
+ * package-installed platform lands inside the versioned `dist/` tree, so the
+ * sweep writes its index INTO THE PACKAGE instead of the workspace (the
+ * "versioned-dist-path trap"). `runDistill` passes the repo root it has already
+ * resolved from prereqs; the default is this process's cwd, which is correct for
+ * the cron/bin invocations that construct the prompt with no arguments.
  */
 export function buildDistillPrompt({
   indexBuilder = RETRIEVAL_INDEX_BUILDER,
-  backlinkIndexer = RETRIEVAL_BACKLINK_INDEXER,
-  graphBuilder = RETRIEVAL_GRAPH_BUILDER,
+  workspaceRoot = process.cwd(),
 } = {}) {
   return `You are operating as the Librarian. Run a full distillation sweep now.
 
@@ -41,10 +54,12 @@ export function buildDistillPrompt({
 
 3. **Synthesise the operator profile narrative.** After updating operator/profile/operator.json, regenerate operator/profile/profile.md as a human-readable markdown narrative derived from the JSON plus the body of accumulated observations. This is the file the workspace and PA read first; it must always exist and reflect current state. Replace it in full each run — it is a derived artefact, not an append log.
 
-4. **Rebuild indexes.** After all content changes, run these in order:
-   - node ${indexBuilder}
-   - node ${backlinkIndexer}
-   - node ${graphBuilder}
+4. **Rebuild the domain index.** After all content changes, run exactly this one command:
+   - node ${indexBuilder} --root ${workspaceRoot}
+
+   The \`--root\` argument is required: without it the builder resolves a default root inside the installed package and writes the index there instead of into the workspace.
+
+   Do NOT rebuild, and do NOT commit, \`operator/knowledge/.backlinks.json\` or \`operator/knowledge/.graph.json\`. Since w-2026-07-29-002 those two artefacts are per-device and untracked -- every host rebuilds its own from the tree it can actually see, via library-sync-cycle's graph-rebuild leg -- so a sweep that rebuilds them commits one host's partial view of the library over everybody else's.
 
 5. **Library hygiene check.** Per your role definition — verify JSON camelCase, cross-reference integrity, index completeness, and lastUpdated freshness. Fix violations in place.
 
@@ -54,9 +69,11 @@ export function buildDistillPrompt({
 }
 
 /**
- * Back-compat constant: the prompt assembled with default (bundled) paths.
- * Existing consumers that import DISTILL_PROMPT keep working; new callers
- * should use buildDistillPrompt() with explicit overrides where needed.
+ * Back-compat constant: the prompt assembled with default (bundled) paths and
+ * this process's cwd as the workspace root. Existing consumers that import
+ * DISTILL_PROMPT keep working; new callers should use buildDistillPrompt() with
+ * an explicit `workspaceRoot`, as `runDistill` does -- the resolved repo root is
+ * more trustworthy than cwd at module-load time.
  */
 export const DISTILL_PROMPT = buildDistillPrompt();
 

package/dist/engineering-pa-core/src/distill/run.mjs

@@ -37,7 +37,7 @@ import { basename, join } from 'node:path';
 
 import { resolvePrereqs } from './prereqs.mjs';
 import { countStagedObservations } from './staging.mjs';
-import { DISTILL_PROMPT, claudeArgs } from './prompt.mjs';
+import { buildDistillPrompt, claudeArgs } from './prompt.mjs';
 
 function log(line, { stderr = process.stderr } = {}) {
   stderr.write(`[distill] ${line}\n`);
@@ -116,6 +116,12 @@ export async function runDistill({
   }
   log(`found ${stagingCount} staged observation(s)`, { stderr });
 
+  // Assemble the sweep prompt against THIS host's resolved repo root. The
+  // index-builder invocation in step 4 carries it as `--root`; the module-level
+  // DISTILL_PROMPT default (cwd) is a fallback for callers that have not
+  // resolved a root, and a cron sweep always has.
+  const prompt = buildDistillPrompt({ workspaceRoot: repoRoot });
+
   // Step 3 — assemble & invoke.
   //
   // Two timestamp shapes for two jobs:
@@ -165,7 +171,7 @@ export async function runDistill({
     log(`  appended system:      ${librarianDef} (${librarianBase.length} bytes)`, { stderr });
     log(`  operator supplement:  ${supplementPlanLine}`, { stderr });
     log(`  composed total:       ${librarianIdentity.length} bytes`, { stderr });
-    log(`  prompt:               <inline> (${DISTILL_PROMPT.length} bytes)`, { stderr });
+    log(`  prompt:               <inline> (${prompt.length} bytes, --root ${repoRoot})`, { stderr });
     log('  command:              claude --print --permission-mode bypassPermissions \\', { stderr });
     log(`                          --no-session-persistence --name ${sessionName} \\`, { stderr });
     log('                          --append-system-prompt <librarian definition> \\', { stderr });
@@ -177,7 +183,7 @@ export async function runDistill({
   log(`starting distillation sweep — log: ${runLogPath}`, { stderr });
   const start = Date.now();
 
-  const claudeArgv = claudeArgs({ sessionName, librarianDef: librarianIdentity });
+  const claudeArgv = claudeArgs({ sessionName, librarianDef: librarianIdentity, prompt });
   const claudeResult = await runner.spawn('claude', claudeArgv, { cwd: repoRoot });
 
   // Persist claude stdout/stderr to the per-run log file.

package/dist/engineering-pa-core/src/knowledge/retrieval/backlink-indexer.mjs

@@ -7,10 +7,28 @@
 // Output: operator/knowledge/.backlinks.json
 //
 // CLI: node backlink-indexer.mjs [--root /path/to/repo]
-
-import { readdir, readFile, writeFile, stat } from 'node:fs/promises';
-import { join, resolve, dirname, relative, normalize } from 'node:path';
+//
+// Extraction and resolution live in ./links.mjs, shared with graph-builder.mjs
+// — graph-builder reverses every entry in this file into a graph edge, so the
+// two must agree on what a link points at. See that file for the contract.
+//
+// index.json hub references are deliberately NOT indexed here: this file's
+// contract is "which markdown documents link to this target". Hub ingestion is
+// graph-builder's job.
+//
+// LIBRARY + CLI. The work lives in the exported `buildBacklinkIndex()` so an
+// in-process caller can rebuild the artefact without paying for a child
+// process -- `pa knowledge`'s on-demand self-heal is the live consumer. The
+// script keeps its CLI face unchanged (argv parsing, console reporting,
+// `process.exit`), now behind a directly-invoked guard so importing the module
+// does not run a sweep and exit the host process.
+
+import { readFile } from 'node:fs/promises';
+import { realpathSync } from 'node:fs';
+import { join, resolve, dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { buildFileIndex, extractLinks, scanDirsFor, toPosix, walkFiles } from './links.mjs';
+import { writeJsonAtomic } from './write-atomic.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_ROOT = resolve(__dirname, '../../../..');
@@ -23,77 +41,79 @@ Usage:
 
 Options:
   --root <path>    Repository root (default: 4 levels up from this script)
+  --quiet          Suppress the unresolved-link report
   --help, -h       Show this help
 
 Scans all .md files under operator/knowledge/ and core/knowledge/.
 Finds:
-  - Wiki-style links: [[target]]
+  - Wiki-style links: [[target]]      (resolved against the real file set)
   - Markdown links:   [text](relative/path.md)
 
 Output: operator/knowledge/.backlinks.json
 `.trim();
 
-// ── Helpers ─────────────────────────────────────────────────────────
-
-async function walkDir(dir) {
-  const results = [];
-  let entries;
-  try {
-    entries = await readdir(dir, { withFileTypes: true });
-  } catch (err) {
-    if (err.code === 'ENOENT') return results;
-    throw err;
+/**
+ * Build the backlink index over `root` and write
+ * `operator/knowledge/.backlinks.json`.
+ *
+ * @param {object} args
+ * @param {string} args.root  workspace root the knowledge tree hangs off
+ * @param {object|null} [args.coverage]  optional provenance stamp merged into
+ *   the artefact as `coverage`. The estate's `library-sync-cycle:graph-rebuild`
+ *   leg writes a device/entitlement stamp; `pa knowledge`'s on-demand build
+ *   writes a minimal one. Readers treat it as optional either way.
+ * @returns {Promise<{outPath:string, targetCount:number, unresolved:object[]}>}
+ */
+export async function buildBacklinkIndex({ root, coverage = null }) {
+  // Pass 1 — enumerate. `[[slug]]` cannot be resolved without knowing which
+  // files exist, so the whole tree is collected before any link is read.
+  const allFiles = [];
+  for (const dir of scanDirsFor(root)) {
+    allFiles.push(...await walkFiles(dir));
   }
-  for (const entry of entries) {
-    const full = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      if (entry.name.startsWith('.')) continue;
-      results.push(...await walkDir(full));
-    } else if (entry.isFile() && entry.name.endsWith('.md')) {
-      results.push(full);
+  const fileIds = allFiles.map((f) => toPosix(relative(root, f)));
+  const fileIndex = buildFileIndex(fileIds);
+
+  // Pass 2 — build backlinks map: target -> [sources]
+  const backlinks = {};
+  const unresolved = [];
+
+  for (let i = 0; i < allFiles.length; i++) {
+    const content = await readFile(allFiles[i], 'utf8');
+    const relSource = fileIds[i];
+    const result = extractLinks(content, relSource, fileIndex);
+    unresolved.push(...result.unresolved);
+
+    for (const target of result.links) {
+      if (!backlinks[target]) backlinks[target] = [];
+      if (!backlinks[target].includes(relSource)) {
+        backlinks[target].push(relSource);
+      }
     }
   }
-  return results;
-}
 
-function extractLinks(content, sourcePath, repoRoot) {
-  const links = [];
-  const sourceDir = dirname(sourcePath);
-
-  // Wiki-style: [[target]]
-  const wikiRe = /\[\[([^\]]+)\]\]/g;
-  let m;
-  while ((m = wikiRe.exec(content)) !== null) {
-    let target = m[1].trim();
-    // Resolve as relative to repo root
-    if (!target.endsWith('.md')) target += '.md';
-    const resolved = normalize(target);
-    links.push(resolved);
+  // Sort keys and source arrays for deterministic output.
+  const sortedBacklinks = {};
+  for (const target of Object.keys(backlinks).sort()) {
+    sortedBacklinks[target] = backlinks[target].sort();
   }
 
-  // Markdown-style: [text](relative/path.md)
-  // Exclude external URLs and anchors
-  const mdRe = /\[([^\]]*)\]\(([^)]+)\)/g;
-  while ((m = mdRe.exec(content)) !== null) {
-    const href = m[2].trim();
-    if (href.startsWith('http://') || href.startsWith('https://') || href.startsWith('#') || href.startsWith('mailto:')) continue;
-    // Strip anchor fragment
-    const path = href.split('#')[0];
-    if (!path) continue;
-    if (!path.endsWith('.md')) continue;
-    // Resolve relative to source file's directory
-    const abs = resolve(sourceDir, path);
-    const rel = relative(repoRoot, abs);
-    links.push(normalize(rel));
-  }
+  const output = {
+    version: '1.0',
+    generatedAt: new Date().toISOString(),
+    unresolvedLinkCount: unresolved.length,
+    backlinks: sortedBacklinks,
+  };
+  if (coverage) output.coverage = coverage;
 
-  return links;
+  const outPath = join(root, 'operator', 'knowledge', '.backlinks.json');
+  await writeJsonAtomic(outPath, output);
+  return { outPath, targetCount: Object.keys(sortedBacklinks).length, unresolved };
 }
 
-// ── Main ────────────────────────────────────────────────────────────
-
 async function main(args) {
   let root = DEFAULT_ROOT;
+  let quiet = false;
 
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
@@ -101,54 +121,43 @@ async function main(args) {
       console.log(USAGE);
       return 0;
     }
+    if (a === '--quiet') quiet = true;
     if (a === '--root') {
       root = resolve(args[++i]);
     }
   }
 
-  const scanDirs = [
-    join(root, 'operator', 'knowledge'),
-    join(root, 'core', 'knowledge'),
-  ];
-
-  // Collect all markdown files
-  const allFiles = [];
-  for (const dir of scanDirs) {
-    allFiles.push(...await walkDir(dir));
-  }
-
-  // Build backlinks map: target -> [sources]
-  const backlinks = {};
-
-  for (const filePath of allFiles) {
-    const content = await readFile(filePath, 'utf8');
-    const relSource = relative(root, filePath);
-    const links = extractLinks(content, filePath, root);
-
-    for (const target of links) {
-      if (!backlinks[target]) backlinks[target] = [];
-      if (!backlinks[target].includes(relSource)) {
-        backlinks[target].push(relSource);
+  const { outPath, targetCount, unresolved } = await buildBacklinkIndex({ root });
+
+  console.log(`Wrote ${outPath} (${targetCount} targets indexed)`);
+  if (unresolved.length > 0) {
+    const byReason = new Map();
+    for (const e of unresolved) byReason.set(e.reason, (byReason.get(e.reason) ?? 0) + 1);
+    const summary = [...byReason.entries()].map(([r, n]) => `${r}=${n}`).join(' ');
+    console.warn(`${unresolved.length} wiki links unresolved (${summary})`);
+    if (!quiet) {
+      for (const e of unresolved) {
+        const extra = e.candidates ? ` [candidates: ${e.candidates.join(', ')}]` : '';
+        console.warn(`  ${e.reason}: ${e.source} -> ${e.target}${extra}`);
       }
     }
   }
+  return 0;
+}
 
-  // Sort source arrays for deterministic output
-  for (const target of Object.keys(backlinks)) {
-    backlinks[target].sort();
+// Realpath both sides: under pnpm, argv[1] is frequently a symlink into a
+// store path, and a raw string comparison silently no-ops. Same shape as
+// core/src/scheduler/*.mjs.
+function isDirectlyInvoked() {
+  if (!process.argv[1]) return false;
+  try {
+    return fileURLToPath(import.meta.url) === realpathSync(resolve(process.argv[1]));
+  } catch {
+    return false;
   }
-
-  const output = {
-    version: '1.0',
-    generatedAt: new Date().toISOString(),
-    backlinks,
-  };
-
-  const outPath = join(root, 'operator', 'knowledge', '.backlinks.json');
-  await writeFile(outPath, JSON.stringify(output, null, 2) + '\n', 'utf8');
-  console.log(`Wrote ${outPath} (${Object.keys(backlinks).length} targets indexed)`);
-  return 0;
 }
 
-const exitCode = await main(process.argv.slice(2));
-process.exit(exitCode ?? 0);
+if (isDirectlyInvoked()) {
+  const exitCode = await main(process.argv.slice(2));
+  process.exit(exitCode ?? 0);
+}