docbridge 0.7.0 → 0.9.0

package/dist/index.js

@@ -411,11 +411,11 @@ var require_codegen = __commonJS((exports) => {
       const rhs = this.rhs === undefined ? "" : ` = ${this.rhs}`;
       return `${varKind} ${this.name}${rhs};` + _n;
     }
-    optimizeNames(names, constants) {
+    optimizeNames(names, constants2) {
       if (!names[this.name.str])
         return;
       if (this.rhs)
-        this.rhs = optimizeExpr(this.rhs, names, constants);
+        this.rhs = optimizeExpr(this.rhs, names, constants2);
       return this;
     }
     get names() {
@@ -433,10 +433,10 @@ var require_codegen = __commonJS((exports) => {
     render({ _n }) {
       return `${this.lhs} = ${this.rhs};` + _n;
     }
-    optimizeNames(names, constants) {
+    optimizeNames(names, constants2) {
       if (this.lhs instanceof code_1.Name && !names[this.lhs.str] && !this.sideEffects)
         return;
-      this.rhs = optimizeExpr(this.rhs, names, constants);
+      this.rhs = optimizeExpr(this.rhs, names, constants2);
       return this;
     }
     get names() {
@@ -502,8 +502,8 @@ var require_codegen = __commonJS((exports) => {
     optimizeNodes() {
       return `${this.code}` ? this : undefined;
     }
-    optimizeNames(names, constants) {
-      this.code = optimizeExpr(this.code, names, constants);
+    optimizeNames(names, constants2) {
+      this.code = optimizeExpr(this.code, names, constants2);
       return this;
     }
     get names() {
@@ -533,12 +533,12 @@ var require_codegen = __commonJS((exports) => {
       }
       return nodes.length > 0 ? this : undefined;
     }
-    optimizeNames(names, constants) {
+    optimizeNames(names, constants2) {
       const { nodes } = this;
       let i = nodes.length;
       while (i--) {
         const n = nodes[i];
-        if (n.optimizeNames(names, constants))
+        if (n.optimizeNames(names, constants2))
           continue;
         subtractNames(names, n.names);
         nodes.splice(i, 1);
@@ -595,12 +595,12 @@ var require_codegen = __commonJS((exports) => {
         return;
       return this;
     }
-    optimizeNames(names, constants) {
+    optimizeNames(names, constants2) {
       var _a;
-      this.else = (_a = this.else) === null || _a === undefined ? undefined : _a.optimizeNames(names, constants);
-      if (!(super.optimizeNames(names, constants) || this.else))
+      this.else = (_a = this.else) === null || _a === undefined ? undefined : _a.optimizeNames(names, constants2);
+      if (!(super.optimizeNames(names, constants2) || this.else))
         return;
-      this.condition = optimizeExpr(this.condition, names, constants);
+      this.condition = optimizeExpr(this.condition, names, constants2);
       return this;
     }
     get names() {
@@ -625,10 +625,10 @@ var require_codegen = __commonJS((exports) => {
     render(opts) {
       return `for(${this.iteration})` + super.render(opts);
     }
-    optimizeNames(names, constants) {
-      if (!super.optimizeNames(names, constants))
+    optimizeNames(names, constants2) {
+      if (!super.optimizeNames(names, constants2))
         return;
-      this.iteration = optimizeExpr(this.iteration, names, constants);
+      this.iteration = optimizeExpr(this.iteration, names, constants2);
       return this;
     }
     get names() {
@@ -666,10 +666,10 @@ var require_codegen = __commonJS((exports) => {
     render(opts) {
       return `for(${this.varKind} ${this.name} ${this.loop} ${this.iterable})` + super.render(opts);
     }
-    optimizeNames(names, constants) {
-      if (!super.optimizeNames(names, constants))
+    optimizeNames(names, constants2) {
+      if (!super.optimizeNames(names, constants2))
         return;
-      this.iterable = optimizeExpr(this.iterable, names, constants);
+      this.iterable = optimizeExpr(this.iterable, names, constants2);
       return this;
     }
     get names() {
@@ -714,11 +714,11 @@ var require_codegen = __commonJS((exports) => {
       (_b = this.finally) === null || _b === undefined || _b.optimizeNodes();
       return this;
     }
-    optimizeNames(names, constants) {
+    optimizeNames(names, constants2) {
       var _a, _b;
-      super.optimizeNames(names, constants);
-      (_a = this.catch) === null || _a === undefined || _a.optimizeNames(names, constants);
-      (_b = this.finally) === null || _b === undefined || _b.optimizeNames(names, constants);
+      super.optimizeNames(names, constants2);
+      (_a = this.catch) === null || _a === undefined || _a.optimizeNames(names, constants2);
+      (_b = this.finally) === null || _b === undefined || _b.optimizeNames(names, constants2);
       return this;
     }
     get names() {
@@ -992,7 +992,7 @@ var require_codegen = __commonJS((exports) => {
   function addExprNames(names, from) {
     return from instanceof code_1._CodeOrName ? addNames(names, from.names) : names;
   }
-  function optimizeExpr(expr, names, constants) {
+  function optimizeExpr(expr, names, constants2) {
     if (expr instanceof code_1.Name)
       return replaceName(expr);
     if (!canOptimize(expr))
@@ -1007,14 +1007,14 @@ var require_codegen = __commonJS((exports) => {
       return items;
     }, []));
     function replaceName(n) {
-      const c = constants[n.str];
+      const c = constants2[n.str];
       if (c === undefined || names[n.str] !== 1)
         return n;
       delete names[n.str];
       return c;
     }
     function canOptimize(e) {
-      return e instanceof code_1._Code && e._items.some((c) => c instanceof code_1.Name && names[c.str] === 1 && constants[c.str] !== undefined);
+      return e instanceof code_1._Code && e._items.some((c) => c instanceof code_1.Name && names[c.str] === 1 && constants2[c.str] !== undefined);
     }
   }
   function subtractNames(names, from) {
@@ -2919,7 +2919,7 @@ var require_compile = __commonJS((exports) => {
     const schOrFunc = root.refs[ref];
     if (schOrFunc)
       return schOrFunc;
-    let _sch = resolve.call(this, root, ref);
+    let _sch = resolve2.call(this, root, ref);
     if (_sch === undefined) {
       const schema = (_a = root.localRefs) === null || _a === undefined ? undefined : _a[ref];
       const { schemaId } = this.opts;
@@ -2946,7 +2946,7 @@ var require_compile = __commonJS((exports) => {
   function sameSchemaEnv(s1, s2) {
     return s1.schema === s2.schema && s1.root === s2.root && s1.baseId === s2.baseId;
   }
-  function resolve(root, ref) {
+  function resolve2(root, ref) {
     let sch;
     while (typeof (sch = this.refs[ref]) == "string")
       ref = sch;
@@ -3532,7 +3532,7 @@ var require_fast_uri = __commonJS((exports, module) => {
     }
     return uri;
   }
-  function resolve(baseURI, relativeURI, options) {
+  function resolve2(baseURI, relativeURI, options) {
     const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
     const { parsed: baseParsed, malformedAuthorityOrPort: baseMalformed } = parseWithStatus(baseURI, schemelessOptions);
     const { parsed: relativeParsed, malformedAuthorityOrPort: relativeMalformed } = parseWithStatus(relativeURI, schemelessOptions);
@@ -3817,7 +3817,7 @@ var require_fast_uri = __commonJS((exports, module) => {
   var fastUri = {
     SCHEMES,
     normalize,
-    resolve,
+    resolve: resolve2,
     resolveComponent,
     equal,
     serialize,
@@ -7155,7 +7155,7 @@ var require_typescript = __commonJS((exports, module) => {
       compact: () => compact,
       compareBooleans: () => compareBooleans,
       compareDataObjects: () => compareDataObjects,
-      compareDiagnostics: () => compareDiagnostics,
+      compareDiagnostics: () => compareDiagnostics2,
       compareEmitHelpers: () => compareEmitHelpers,
       compareNumberOfDirectorySeparators: () => compareNumberOfDirectorySeparators,
       comparePaths: () => comparePaths2,
@@ -7474,7 +7474,7 @@ var require_typescript = __commonJS((exports, module) => {
       forEachUnique: () => forEachUnique,
       forEachYieldExpression: () => forEachYieldExpression,
       formatColorAndReset: () => formatColorAndReset,
-      formatDiagnostic: () => formatDiagnostic,
+      formatDiagnostic: () => formatDiagnostic2,
       formatDiagnostics: () => formatDiagnostics,
       formatDiagnosticsWithColorAndContext: () => formatDiagnosticsWithColorAndContext,
       formatGeneratedName: () => formatGeneratedName,
@@ -14966,7 +14966,7 @@ ${lanes.join(`
             return process.memoryUsage().heapUsed;
           },
           getFileSize(path) {
-            const stat = statSync(path);
+            const stat = statSync2(path);
             if (stat == null ? undefined : stat.isFile()) {
               return stat.size;
             }
@@ -15009,7 +15009,7 @@ ${lanes.join(`
           }
         };
         return nodeSystem;
-        function statSync(path) {
+        function statSync2(path) {
           try {
             return _fs.statSync(path, statSyncOptions);
           } catch {
@@ -15061,7 +15061,7 @@ ${lanes.join(`
             activeSession.post("Profiler.stop", (err, { profile }) => {
               var _a;
               if (!err) {
-                if ((_a = statSync(profilePath)) == null ? undefined : _a.isDirectory()) {
+                if ((_a = statSync2(profilePath)) == null ? undefined : _a.isDirectory()) {
                   profilePath = _path.join(profilePath, `${(/* @__PURE__ */ new Date()).toISOString().replace(/:/g, "-")}+P${process.pid}.cpuprofile`);
                 }
                 try {
@@ -15170,7 +15170,7 @@ ${lanes.join(`
               let stat;
               if (typeof dirent === "string" || dirent.isSymbolicLink()) {
                 const name = combinePaths(path, entry);
-                stat = statSync(name);
+                stat = statSync2(name);
                 if (!stat) {
                   continue;
                 }
@@ -15194,7 +15194,7 @@ ${lanes.join(`
           return matchFiles(path, extensions, excludes, includes, useCaseSensitiveFileNames2, process.cwd(), depth, getAccessibleFileSystemEntries, realpath);
         }
         function fileSystemEntryExists(path, entryKind) {
-          const stat = statSync(path);
+          const stat = statSync2(path);
           if (!stat) {
             return false;
           }
@@ -15228,7 +15228,7 @@ ${lanes.join(`
         }
         function getModifiedTime3(path) {
           var _a;
-          return (_a = statSync(path)) == null ? undefined : _a.mtime;
+          return (_a = statSync2(path)) == null ? undefined : _a.mtime;
         }
         function setModifiedTime(path, time) {
           try {
@@ -20956,7 +20956,7 @@ ${lanes.join(`
       return pathIsRelative(moduleName) || isRootedDiskPath(moduleName);
     }
     function sortAndDeduplicateDiagnostics(diagnostics) {
-      return sortAndDeduplicate(diagnostics, compareDiagnostics, diagnosticsEqualityComparer);
+      return sortAndDeduplicate(diagnostics, compareDiagnostics2, diagnosticsEqualityComparer);
     }
     var targetToLibMap = /* @__PURE__ */ new Map([
       [99, "lib.esnext.full.d.ts"],
@@ -27716,7 +27716,7 @@ ${lanes.join(`
     function getDiagnosticFilePath(diagnostic) {
       return diagnostic.file ? diagnostic.file.path : undefined;
     }
-    function compareDiagnostics(d1, d2) {
+    function compareDiagnostics2(d1, d2) {
       return compareDiagnosticsSkipRelatedInformation(d1, d2) || compareRelatedInformation(d1, d2) || 0;
     }
     function compareDiagnosticsSkipRelatedInformation(d1, d2) {
@@ -27731,7 +27731,7 @@ ${lanes.join(`
       if (d1.relatedInformation && d2.relatedInformation) {
         return compareValues(d2.relatedInformation.length, d1.relatedInformation.length) || forEach(d1.relatedInformation, (d1i, index) => {
           const d2i = d2.relatedInformation[index];
-          return compareDiagnostics(d1i, d2i);
+          return compareDiagnostics2(d1i, d2i);
         }) || 0;
       }
       return d1.relatedInformation ? -1 : 1;
@@ -54786,7 +54786,7 @@ ${lanes.join(`
           err.relatedInformation = err.relatedInformation || [];
           const leadingMessage = createDiagnosticForNode(adjustedNode, Diagnostics._0_was_also_declared_here, symbolName2);
           const followOnMessage = createDiagnosticForNode(adjustedNode, Diagnostics.and_here);
-          if (length(err.relatedInformation) >= 5 || some(err.relatedInformation, (r) => compareDiagnostics(r, followOnMessage) === 0 || compareDiagnostics(r, leadingMessage) === 0))
+          if (length(err.relatedInformation) >= 5 || some(err.relatedInformation, (r) => compareDiagnostics2(r, followOnMessage) === 0 || compareDiagnostics2(r, leadingMessage) === 0))
             continue;
           addRelatedInfo(err, !length(err.relatedInformation) ? leadingMessage : followOnMessage);
         }
@@ -87995,7 +87995,7 @@ ${lanes.join(`
           }
           const currentGlobalDiagnostics = diagnostics.getGlobalDiagnostics();
           if (currentGlobalDiagnostics !== previousGlobalDiagnostics) {
-            const deferredGlobalDiagnostics = relativeComplement(previousGlobalDiagnostics, currentGlobalDiagnostics, compareDiagnostics);
+            const deferredGlobalDiagnostics = relativeComplement(previousGlobalDiagnostics, currentGlobalDiagnostics, compareDiagnostics2);
             return concatenate(deferredGlobalDiagnostics, semanticDiagnostics);
           } else if (previousGlobalDiagnosticsSize === 0 && currentGlobalDiagnostics.length > 0) {
             return concatenate(currentGlobalDiagnostics, semanticDiagnostics);
@@ -105133,14 +105133,14 @@ ${lanes.join(`
         }
       }
       function createImportCallExpressionAMD(arg, containsLexicalThis) {
-        const resolve = factory2.createUniqueName("resolve");
+        const resolve2 = factory2.createUniqueName("resolve");
         const reject = factory2.createUniqueName("reject");
         const parameters = [
-          factory2.createParameterDeclaration(undefined, undefined, resolve),
+          factory2.createParameterDeclaration(undefined, undefined, resolve2),
           factory2.createParameterDeclaration(undefined, undefined, reject)
         ];
         const body = factory2.createBlock([
-          factory2.createExpressionStatement(factory2.createCallExpression(factory2.createIdentifier("require"), undefined, [factory2.createArrayLiteralExpression([arg || factory2.createOmittedExpression()]), resolve, reject]))
+          factory2.createExpressionStatement(factory2.createCallExpression(factory2.createIdentifier("require"), undefined, [factory2.createArrayLiteralExpression([arg || factory2.createOmittedExpression()]), resolve2, reject]))
         ]);
         let func;
         if (languageVersion >= 2) {
@@ -113910,11 +113910,11 @@ ${lanes.join(`
     function formatDiagnostics(diagnostics, host) {
       let output = "";
       for (const diagnostic of diagnostics) {
-        output += formatDiagnostic(diagnostic, host);
+        output += formatDiagnostic2(diagnostic, host);
       }
       return output;
     }
-    function formatDiagnostic(diagnostic, host) {
+    function formatDiagnostic2(diagnostic, host) {
       const errorMessage = `${diagnosticCategoryName(diagnostic)} TS${diagnostic.code}: ${flattenDiagnosticMessageText(diagnostic.messageText, host.getNewLine())}${host.getNewLine()}`;
       if (diagnostic.file) {
         const { line, character } = getLineAndCharacterOfPosition(diagnostic.file, diagnostic.start);
@@ -119897,7 +119897,7 @@ ${lanes.join(`
         getCanonicalFileName: createGetCanonicalFileName(system.useCaseSensitiveFileNames)
       };
       if (!pretty) {
-        return (diagnostic) => system.write(formatDiagnostic(diagnostic, host));
+        return (diagnostic) => system.write(formatDiagnostic2(diagnostic, host));
       }
       const diagnostics = new Array(1);
       return (diagnostic) => {
@@ -163155,7 +163155,7 @@ ${options.prefix}` : `
       compact: () => compact,
       compareBooleans: () => compareBooleans,
       compareDataObjects: () => compareDataObjects,
-      compareDiagnostics: () => compareDiagnostics,
+      compareDiagnostics: () => compareDiagnostics2,
       compareEmitHelpers: () => compareEmitHelpers,
       compareNumberOfDirectorySeparators: () => compareNumberOfDirectorySeparators,
       comparePaths: () => comparePaths2,
@@ -163474,7 +163474,7 @@ ${options.prefix}` : `
       forEachUnique: () => forEachUnique,
       forEachYieldExpression: () => forEachYieldExpression,
       formatColorAndReset: () => formatColorAndReset,
-      formatDiagnostic: () => formatDiagnostic,
+      formatDiagnostic: () => formatDiagnostic2,
       formatDiagnostics: () => formatDiagnostics,
       formatDiagnosticsWithColorAndContext: () => formatDiagnosticsWithColorAndContext,
       formatGeneratedName: () => formatGeneratedName,
@@ -175315,8 +175315,8 @@ Additional information: BADCLIENT: Bad error code, ${badCode} not found in range
       installPackage(options) {
         this.packageInstallId++;
         const request = { kind: "installPackage", ...options, id: this.packageInstallId };
-        const promise = new Promise((resolve, reject) => {
-          (this.packageInstalledPromise ?? (this.packageInstalledPromise = /* @__PURE__ */ new Map)).set(this.packageInstallId, { resolve, reject });
+        const promise = new Promise((resolve2, reject) => {
+          (this.packageInstalledPromise ?? (this.packageInstalledPromise = /* @__PURE__ */ new Map)).set(this.packageInstallId, { resolve: resolve2, reject });
         });
         this.installer.send(request);
         return promise;
@@ -175576,12 +175576,12 @@ Additional information: BADCLIENT: Bad error code, ${badCode} not found in range
 });
 
 // src/cli/index.ts
-import { existsSync as existsSync4, readFileSync as readFileSync6, statSync as statSync4 } from "node:fs";
-import { join as join9, resolve as resolve4 } from "node:path";
+import { existsSync as existsSync6, readFileSync as readFileSync9, statSync as statSync5 } from "node:fs";
+import { join as join14, resolve as resolve5 } from "node:path";
 // package.json
 var package_default = {
   name: "docbridge",
-  version: "0.7.0",
+  version: "0.9.0",
   description: "A CLI that links Markdown specifications and code declarations. Runs on Node.js and Bun.",
   keywords: [
     "bun",
@@ -175624,6 +175624,7 @@ var package_default = {
   devDependencies: {
     "@types/bun": "^1.3.14",
     ajv: "^8.20.0",
+    "markdown-it": "15.0.1",
     oxfmt: "0.57.0",
     oxlint: "1.73.0",
     typescript: "^5.9.0"
@@ -175636,20 +175637,7 @@ var package_default = {
 
 // src/core/config.ts
 import { readFileSync as readFileSync2 } from "node:fs";
-import { join as join4 } from "node:path";
-
-// src/core/code-language.ts
-import { accessSync, chmodSync, constants, existsSync, realpathSync, statSync } from "node:fs";
-import { dirname as dirname2, join as join3, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-// src/core/code-adapter-registry.ts
-var codeAdapters = {};
-
-// src/core/error.ts
-function reasonOf(error) {
-  return error instanceof Error ? error.message : String(error);
-}
+import { join as join2 } from "node:path";
 
 // src/core/glob.ts
 import { lstatSync, readFileSync, readdirSync } from "node:fs";
@@ -175802,12 +175790,562 @@ function escapeRegExpChar(char) {
   return /[.*+?^${}()|[\]\\]/.test(char) ? `\\${char}` : char;
 }
 
+// src/core/code-language.ts
+var KNOWN_CODE_LANGUAGES = [
+  "typescript",
+  "swift",
+  "dart",
+  "rust"
+];
+function isCodeLanguage(value) {
+  return KNOWN_CODE_LANGUAGES.includes(value);
+}
+function collectCodeFiles(projectRoot, codeInclude) {
+  const collected = [];
+  const seen = new Set;
+  for (const language of KNOWN_CODE_LANGUAGES) {
+    const entry = codeInclude[language];
+    if (entry === undefined) {
+      continue;
+    }
+    for (const relPath of collectFiles(projectRoot, entry.patterns)) {
+      if (seen.has(relPath)) {
+        continue;
+      }
+      seen.add(relPath);
+      collected.push({ language, relPath });
+    }
+  }
+  collected.sort((left, right) => comparePaths(left.relPath, right.relPath));
+  return collected;
+}
+function codeFileOwners(projectRoot, codeInclude) {
+  const owners = new Map;
+  for (const language of KNOWN_CODE_LANGUAGES) {
+    const entry = codeInclude[language];
+    if (entry === undefined) {
+      continue;
+    }
+    for (const relPath of collectFiles(projectRoot, entry.patterns)) {
+      const existing = owners.get(relPath);
+      if (existing === undefined) {
+        owners.set(relPath, [language]);
+      } else if (!existing.includes(language)) {
+        existing.push(language);
+      }
+    }
+  }
+  return owners;
+}
+
+// src/core/config.ts
+var CONFIG_FILE_NAME = "docbridge.config.json";
+var EMPTY_CONFIG = {
+  include: { code: {}, docs: [] }
+};
+var KNOWN_TOP_LEVEL_KEYS = new Set(["$schema", "include"]);
+var KNOWN_INCLUDE_KEYS = new Set(["code", "docs"]);
+var KNOWN_CODE_ENTRY_KEYS = new Set(["patterns", "visibility"]);
+var LANGUAGE_SUFFIX = {
+  typescript: ".ts",
+  swift: ".swift",
+  dart: ".dart",
+  rust: ".rs"
+};
+var LANGUAGE_VISIBILITY = {
+  typescript: ["public", "protected", "private"],
+  swift: ["public", "open", "internal"],
+  dart: ["public"],
+  rust: ["pub", "private"]
+};
+function loadConfig(projectRoot) {
+  let rawText;
+  try {
+    rawText = readFileSync2(join2(projectRoot, CONFIG_FILE_NAME), "utf8");
+  } catch {
+    rawText = undefined;
+  }
+  const resolved = resolveConfig(rawText);
+  if (!resolved.ok) {
+    return resolved;
+  }
+  const overlapDiagnostics = detectLanguageOverlap(projectRoot, resolved.config.include.code);
+  if (overlapDiagnostics.length === 0) {
+    return resolved;
+  }
+  return {
+    config: EMPTY_CONFIG,
+    diagnostics: [...resolved.diagnostics, ...overlapDiagnostics],
+    ok: false
+  };
+}
+function resolveConfig(rawText) {
+  if (rawText === undefined) {
+    return {
+      config: EMPTY_CONFIG,
+      ok: false,
+      diagnostics: [
+        configDiagnostic("config_file_invalid", CONFIG_FILE_NAME, `${CONFIG_FILE_NAME} was not found. DocBridge requires a configuration file.`)
+      ]
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(rawText);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return {
+      config: EMPTY_CONFIG,
+      ok: false,
+      diagnostics: [
+        configDiagnostic("config_file_invalid", CONFIG_FILE_NAME, `Failed to parse ${CONFIG_FILE_NAME}: ${reason}`)
+      ]
+    };
+  }
+  const diagnostics = [];
+  if (!isPlainObject(parsed)) {
+    diagnostics.push(configDiagnostic("config_invalid_value", CONFIG_FILE_NAME, "Configuration must be a JSON object."));
+    return { config: EMPTY_CONFIG, diagnostics, ok: false };
+  }
+  for (const key of Object.keys(parsed)) {
+    if (!KNOWN_TOP_LEVEL_KEYS.has(key)) {
+      diagnostics.push(configDiagnostic("config_unknown_key", key, `Unknown top-level configuration key: ${key}`));
+    }
+  }
+  if ("$schema" in parsed && typeof parsed.$schema !== "string") {
+    diagnostics.push(configDiagnostic("config_invalid_value", "$schema", "`$schema` must be a string."));
+  }
+  const include = parsed.include;
+  if (!isPlainObject(include)) {
+    diagnostics.push(configDiagnostic("config_invalid_value", "include", "`include` must be an object with `code` and `docs`."));
+    return { config: EMPTY_CONFIG, diagnostics, ok: false };
+  }
+  for (const key of Object.keys(include)) {
+    if (!KNOWN_INCLUDE_KEYS.has(key)) {
+      diagnostics.push(configDiagnostic("config_unknown_key", `include.${key}`, `Unknown configuration key under \`include\`: ${key}`));
+    }
+  }
+  const code = validateCodeInclude(include.code, diagnostics);
+  validatePatternArray(include.docs, "docs", ".md", false, diagnostics);
+  const ok = diagnostics.length === 0;
+  const config = ok ? { include: { code, docs: include.docs } } : EMPTY_CONFIG;
+  return { config, diagnostics, ok };
+}
+function validateCodeInclude(value, diagnostics) {
+  if (Array.isArray(value)) {
+    diagnostics.push(configDiagnostic("config_invalid_value", "include.code", '`include.code` must be a language-keyed object such as `{ "typescript": { "patterns": ["src/**/*.ts"] } }`, not an array.'));
+    return {};
+  }
+  if (!isPlainObject(value)) {
+    diagnostics.push(configDiagnostic("config_invalid_value", "include.code", "`include.code` must be a language-keyed object."));
+    return {};
+  }
+  const keys = Object.keys(value);
+  if (keys.length === 0) {
+    diagnostics.push(configDiagnostic("config_invalid_value", "include.code", "`include.code` must configure at least one language."));
+    return {};
+  }
+  const result = {};
+  for (const key of keys) {
+    if (!isCodeLanguage(key)) {
+      diagnostics.push(configDiagnostic("config_invalid_value", `include.code.${key}`, `Unknown code language: ${key}. Supported languages: ${KNOWN_CODE_LANGUAGES.join(", ")}.`));
+      continue;
+    }
+    const entry = validateCodeEntry(key, value[key], diagnostics);
+    if (entry !== undefined) {
+      result[key] = entry;
+    }
+  }
+  return result;
+}
+function validateCodeEntry(language, value, diagnostics) {
+  const target = `include.code.${language}`;
+  if (!isPlainObject(value)) {
+    diagnostics.push(configDiagnostic("config_invalid_value", target, `\`${target}\` must be an object with a \`patterns\` array. Shorthand arrays are not supported.`));
+    return;
+  }
+  for (const key of Object.keys(value)) {
+    if (!KNOWN_CODE_ENTRY_KEYS.has(key)) {
+      diagnostics.push(configDiagnostic("config_unknown_key", `${target}.${key}`, `Unknown configuration key under \`${target}\`: ${key}`));
+    }
+  }
+  const before = diagnostics.length;
+  validatePatternArray(value.patterns, `code.${language}.patterns`, LANGUAGE_SUFFIX[language], language === "typescript", diagnostics);
+  if ("visibility" in value) {
+    if (!isStringArray(value.visibility)) {
+      diagnostics.push(configDiagnostic("config_invalid_value", `${target}.visibility`, `\`${target}.visibility\` must be an array of strings.`));
+    } else {
+      validateVisibilityOptions(language, value.visibility, target, diagnostics);
+    }
+  }
+  if (diagnostics.length !== before) {
+    return;
+  }
+  const entry = { patterns: value.patterns };
+  if (isStringArray(value.visibility)) {
+    entry.visibility = value.visibility;
+  }
+  return entry;
+}
+function validateVisibilityOptions(language, values, target, diagnostics) {
+  const allowed = LANGUAGE_VISIBILITY[language];
+  if (allowed.length === 0) {
+    diagnostics.push(configDiagnostic("config_invalid_value", `${target}.visibility`, `\`${target}.visibility\` is not supported for ${language}.`));
+    return;
+  }
+  for (const value of values) {
+    if (!allowed.includes(value)) {
+      diagnostics.push(configDiagnostic("config_invalid_value", `${target}.visibility`, `Unsupported ${language} visibility: ${value}. Supported values: ${allowed.join(", ")}.`));
+    }
+  }
+}
+function validatePatternArray(value, field, requiredSuffix, excludeDeclarationFiles, diagnostics) {
+  const target = `include.${field}`;
+  if (!Array.isArray(value)) {
+    diagnostics.push(configDiagnostic("config_invalid_value", target, `\`${target}\` must be a non-empty array of strings.`));
+    return;
+  }
+  if (value.length === 0) {
+    diagnostics.push(configDiagnostic("config_invalid_value", target, `\`${target}\` must contain at least one pattern.`));
+    return;
+  }
+  for (const pattern of value) {
+    if (typeof pattern !== "string") {
+      diagnostics.push(configDiagnostic("config_invalid_value", target, `\`${target}\` patterns must be strings.`));
+      continue;
+    }
+    const globResult = validateGlobPattern(pattern);
+    if (!globResult.ok) {
+      diagnostics.push(configDiagnostic("config_invalid_value", pattern, `Invalid pattern in \`${target}\`: ${globResult.message}`));
+      continue;
+    }
+    const suffixError = checkSuffix(pattern, requiredSuffix, excludeDeclarationFiles);
+    if (suffixError !== undefined) {
+      diagnostics.push(configDiagnostic("config_invalid_value", pattern, suffixError));
+    }
+  }
+}
+function checkSuffix(pattern, requiredSuffix, excludeDeclarationFiles) {
+  if (!pattern.endsWith(requiredSuffix)) {
+    return `Pattern must end with \`${requiredSuffix}\`.`;
+  }
+  if (excludeDeclarationFiles && pattern.endsWith(".d.ts")) {
+    return "Pattern must not target `.d.ts` declaration files.";
+  }
+  return;
+}
+function detectLanguageOverlap(projectRoot, code) {
+  const diagnostics = [];
+  for (const [relPath, owners] of codeFileOwners(projectRoot, code)) {
+    if (owners.length > 1) {
+      diagnostics.push(configDiagnostic("config_invalid_value", relPath, `Code file ${relPath} matches multiple configured languages (${owners.join(", ")}). Each code file must belong to exactly one language.`));
+    }
+  }
+  return diagnostics;
+}
+function configDiagnostic(code, target, message) {
+  return { severity: "error", code, target, message };
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+// src/core/diagnostics.ts
+function sortDiagnostics(diagnostics) {
+  return [...diagnostics].toSorted(compareDiagnostics);
+}
+function summarizeDiagnostics(diagnostics) {
+  const summary = { errors: 0, warnings: 0 };
+  for (const diagnostic of diagnostics) {
+    if (diagnostic.severity === "error") {
+      summary.errors += 1;
+    } else {
+      summary.warnings += 1;
+    }
+  }
+  return summary;
+}
+function formatDiagnostic(diagnostic) {
+  const location = diagnostic.location;
+  if (location === undefined) {
+    return `${diagnostic.target} ${diagnostic.severity} ${diagnostic.code} - ${diagnostic.message}`;
+  }
+  const prefix = `${location.filePath}:${location.line}:${location.column}`;
+  return `${prefix} ${diagnostic.severity} ${diagnostic.code} ${diagnostic.target} - ${diagnostic.message}`;
+}
+function formatSummary(summary) {
+  return `Summary: ${summary.errors} ${pluralize("error", summary.errors)}, ${summary.warnings} ${pluralize("warning", summary.warnings)}`;
+}
+function collectErroredFiles(diagnostics) {
+  const errored = new Set;
+  for (const diagnostic of diagnostics) {
+    if (diagnostic.code === "file_read_error" || diagnostic.code === "code_parse_error" || isFileScopedScannerDiagnostic(diagnostic)) {
+      errored.add(diagnostic.target);
+    }
+  }
+  return errored;
+}
+function isFileScopedScannerDiagnostic(diagnostic) {
+  return (diagnostic.code === "code_scanner_unavailable" || diagnostic.code === "code_scanner_failed") && diagnostic.language !== undefined && diagnostic.target !== diagnostic.language;
+}
+function compareDiagnostics(left, right) {
+  const leftLocation = left.location;
+  const rightLocation = right.location;
+  if (leftLocation === undefined && rightLocation !== undefined) {
+    return -1;
+  }
+  if (leftLocation !== undefined && rightLocation === undefined) {
+    return 1;
+  }
+  if (leftLocation !== undefined && rightLocation !== undefined) {
+    return compareString(leftLocation.filePath, rightLocation.filePath) || compareNumber(leftLocation.line, rightLocation.line) || compareNumber(leftLocation.column, rightLocation.column) || compareString(left.code, right.code) || compareString(left.target, right.target);
+  }
+  return compareString(left.code, right.code) || compareString(left.target, right.target);
+}
+function compareString(left, right) {
+  return left.localeCompare(right);
+}
+function compareNumber(left, right) {
+  return left - right;
+}
+function pluralize(word, count) {
+  return count === 1 ? word : `${word}s`;
+}
+
+// src/core/endpoint.ts
+function filePathOf(endpoint) {
+  const hashIndex = endpoint.indexOf("#");
+  return hashIndex === -1 ? endpoint : endpoint.slice(0, hashIndex);
+}
+function fragmentOf(endpoint) {
+  const hashIndex = endpoint.indexOf("#");
+  return hashIndex === -1 ? endpoint : endpoint.slice(hashIndex + 1);
+}
+function compareEndpointOrder(left, right) {
+  return left.filePath.localeCompare(right.filePath) || left.line - right.line || left.column - right.column || left.endpoint.localeCompare(right.endpoint);
+}
+function endpointRange(element) {
+  const range = element.kind === "code" ? element.nameRange : element.headingTextRange;
+  if (range !== undefined) {
+    return range;
+  }
+  const { line, column } = element.location;
+  return { start: { line, column }, end: { line, column } };
+}
+
+// src/core/graph.ts
+function buildLinkGraph(codeFiles, docFiles) {
+  const codeByEndpoint = new Map;
+  for (const file of codeFiles) {
+    for (const symbol of file.symbols) {
+      if (!codeByEndpoint.has(symbol.endpoint)) {
+        codeByEndpoint.set(symbol.endpoint, symbol);
+      }
+    }
+  }
+  const docByEndpoint = new Map;
+  for (const file of docFiles) {
+    for (const anchor of file.anchors) {
+      if (!docByEndpoint.has(anchor.endpoint)) {
+        docByEndpoint.set(anchor.endpoint, anchor);
+      }
+    }
+  }
+  const counterparts = new Map;
+  const addEdge = (a, b) => {
+    addTo(counterparts, a, b);
+    addTo(counterparts, b, a);
+  };
+  for (const file of codeFiles) {
+    for (const link of file.links) {
+      if (codeByEndpoint.has(link.source) && docByEndpoint.has(link.target)) {
+        addEdge(link.source, link.target);
+      }
+    }
+  }
+  for (const file of docFiles) {
+    for (const link of file.links) {
+      if (docByEndpoint.has(link.source) && codeByEndpoint.has(link.target)) {
+        addEdge(link.source, link.target);
+      }
+    }
+  }
+  return { codeByEndpoint, docByEndpoint, counterparts };
+}
+function counterpartsOf(graph, endpoint) {
+  const targets = graph.counterparts.get(endpoint);
+  if (targets === undefined) {
+    return [];
+  }
+  const resolved = [];
+  for (const target of targets) {
+    const code = graph.codeByEndpoint.get(target);
+    if (code !== undefined) {
+      resolved.push(code);
+      continue;
+    }
+    const doc = graph.docByEndpoint.get(target);
+    if (doc !== undefined) {
+      resolved.push(doc);
+    }
+  }
+  return resolved.toSorted(compareEndpoints);
+}
+function addTo(map, key, value) {
+  const existing = map.get(key);
+  if (existing === undefined) {
+    map.set(key, new Set([value]));
+    return;
+  }
+  existing.add(value);
+}
+function compareEndpoints(left, right) {
+  return compareEndpointOrder({ ...left.location, endpoint: left.endpoint }, { ...right.location, endpoint: right.endpoint });
+}
+
+// src/core/code-adapter-registry.ts
+var codeAdapters = {};
+
+// src/core/scanner-executable.ts
+import { accessSync, chmodSync, constants, existsSync, realpathSync, statSync } from "node:fs";
+import { dirname, join as join3, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// src/core/error.ts
+function reasonOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/core/scanner-executable.ts
+var SUPPORTED_SCANNER_PLATFORM_KEYS = ["darwin-arm64", "linux-x64"];
+var SCANNER_EXECUTABLE_NAMES = {
+  swift: "docbridge-swift-scanner",
+  dart: "docbridge_dart_scanner",
+  rust: "docbridge-rust-scanner"
+};
+function scannerPlatformKey() {
+  return `${process.platform}-${process.arch}`;
+}
+function scannerExecutableName(language) {
+  return SCANNER_EXECUTABLE_NAMES[language];
+}
+function resolveScannerWorkerCommand(language, options = {}) {
+  const platformKey = options.platformKey ?? scannerPlatformKey();
+  const platformSupported = isSupportedScannerPlatformKey(platformKey);
+  const candidates = scannerExecutableCandidates(language, platformKey, platformSupported, options);
+  const found = candidates.find((candidate) => existsSync(candidate));
+  if (found !== undefined) {
+    const repair = ensureExecutable(found, options.chmod ?? chmodSync);
+    if (!repair.ok) {
+      return { ok: false, diagnostic: scannerUnavailableDiagnostic(language, repair.reason) };
+    }
+    return { ok: true, command: [found] };
+  }
+  if (!platformSupported) {
+    return {
+      ok: false,
+      diagnostic: scannerUnavailableDiagnostic(language, `platform ${platformKey} is unsupported; supported platforms: ${SUPPORTED_SCANNER_PLATFORM_KEYS.join(", ")}`)
+    };
+  }
+  return {
+    ok: false,
+    diagnostic: scannerUnavailableDiagnostic(language, `missing ${scannerExecutableName(language)} for platform ${platformKey}; supported platforms: ${SUPPORTED_SCANNER_PLATFORM_KEYS.join(", ")}`)
+  };
+}
+function scannerExecutableCandidates(language, platformKey, platformSupported, options) {
+  const sourceRoot = options.sourceRoot ?? sourceRootPath();
+  const distRoot = options.distRoot ?? distRootPath();
+  const executable = scannerExecutableName(language);
+  if (language === "swift") {
+    return [
+      join3(sourceRoot, "packages/swift-scanner/.build/release", executable),
+      join3(sourceRoot, "packages/swift-scanner/.build/debug", executable),
+      ...platformSupported ? [join3(distRoot, "bin", platformKey, executable)] : []
+    ];
+  }
+  if (language === "rust") {
+    return [
+      join3(sourceRoot, "packages/rust-scanner/target/release", executable),
+      join3(sourceRoot, "packages/rust-scanner/target/debug", executable),
+      ...platformSupported ? [join3(distRoot, "bin", platformKey, executable)] : []
+    ];
+  }
+  return [
+    join3(sourceRoot, "packages/dart-scanner/bin", executable),
+    ...platformSupported ? [join3(distRoot, "bin", platformKey, executable)] : []
+  ];
+}
+function ensureExecutable(path, chmod) {
+  let mode;
+  try {
+    mode = statSync(path).mode;
+  } catch (error) {
+    return { ok: false, reason: `cannot stat ${path}: ${reasonOf(error)}` };
+  }
+  if (isExecutableByThisProcess(path)) {
+    return { ok: true };
+  }
+  try {
+    chmod(path, mode | 73);
+  } catch (error) {
+    return {
+      ok: false,
+      reason: `${path} is not executable (mode ${formatMode(mode)}) and the executable ` + `bit could not be restored: ${reasonOf(error)}; run \`chmod +x ${path}\` ` + `or reinstall DocBridge into a writable location`
+    };
+  }
+  return { ok: true };
+}
+function isExecutableByThisProcess(path) {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function formatMode(mode) {
+  return `0${(mode & 4095).toString(8).padStart(3, "0")}`;
+}
+function isSupportedScannerPlatformKey(platformKey) {
+  return SUPPORTED_SCANNER_PLATFORM_KEYS.includes(platformKey);
+}
+function scannerRootsFromModuleUrl(moduleUrl) {
+  const modulePath = fileURLToPath(moduleUrl);
+  let resolved;
+  try {
+    resolved = realpathSync(modulePath);
+  } catch {
+    resolved = modulePath;
+  }
+  const moduleDir = dirname(resolved);
+  return { distRoot: moduleDir, sourceRoot: resolve(moduleDir, "..", "..") };
+}
+function sourceRootPath() {
+  return scannerRootsFromModuleUrl(import.meta.url).sourceRoot;
+}
+function distRootPath() {
+  return scannerRootsFromModuleUrl(import.meta.url).distRoot;
+}
+function scannerUnavailableDiagnostic(language, reason) {
+  const label = language.charAt(0).toUpperCase() + language.slice(1);
+  return {
+    severity: "error",
+    code: "code_scanner_unavailable",
+    language,
+    target: language,
+    message: `${label} scanner worker is unavailable: ${reason}`
+  };
+}
+
 // src/core/scanner-worker.ts
 var import__2020 = __toESM(require_2020(), 1);
 import { spawnSync } from "node:child_process";
 import { mkdirSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, join as join2 } from "node:path";
+import { dirname as dirname2, join as join4 } from "node:path";
 // schemas/common-output.schema.json
 var common_output_schema_default = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -175897,6 +176435,7 @@ var scanner_worker_schema_default = {
         canonicalId: { type: "string" },
         endpoint: { type: "string" },
         location: { $ref: "common-output.schema.json#/$defs/location" },
+        isMember: { type: "boolean" },
         nameRange: { $ref: "common-output.schema.json#/$defs/range" },
         declarationRange: { $ref: "common-output.schema.json#/$defs/range" },
         signatureRange: { $ref: "common-output.schema.json#/$defs/range" }
@@ -176015,7 +176554,7 @@ function invokeScannerWorker(request, command, run = runScannerWorkerProcess) {
   if (!processResult.ok) {
     return {
       ok: false,
-      diagnostic: scannerUnavailableDiagnostic(request.language, processResult.error, command[0]),
+      diagnostic: scannerUnavailableDiagnostic2(request.language, processResult.error, command[0]),
       stderr: processResult.stderr
     };
   }
@@ -176056,7 +176595,7 @@ function invokeScannerWorker(request, command, run = runScannerWorkerProcess) {
 }
 function clangModuleCachePath() {
   const owner = typeof process.getuid === "function" ? process.getuid() : "shared";
-  return join2(tmpdir(), `docbridge-clang-module-cache-${owner}`);
+  return join4(tmpdir(), `docbridge-clang-module-cache-${owner}`);
 }
 function runScannerWorkerProcess(input) {
   try {
@@ -176132,7 +176671,7 @@ function responseFilesMatchRequest(responseFiles, requestFiles) {
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function scannerUnavailableDiagnostic(language, error, executable) {
+function scannerUnavailableDiagnostic2(language, error, executable) {
   const label = languageLabel(language);
   return {
     severity: "error",
@@ -176147,7 +176686,7 @@ function spawnFailureReason(error, executable) {
   if (!isExecDenied(error) || executable === undefined) {
     return reason;
   }
-  return `${reason}; the scanner is executable but ${dirname(executable)} refuses to ` + `execute it, which a \`noexec\` mount does. Install DocBridge as a project ` + `dependency, or point the installer cache at an exec-capable directory, ` + `instead of running through \`bunx\``;
+  return `${reason}; the scanner is executable but ${dirname2(executable)} refuses to ` + `execute it, which a \`noexec\` mount does. Install DocBridge as a project ` + `dependency, or point the installer cache at an exec-capable directory, ` + `instead of running through \`bunx\``;
 }
 function isExecDenied(error) {
   if (!(error instanceof Error)) {
@@ -176283,7 +176822,7 @@ function scanTypeScript(filePath, content, options = {}) {
   for (const declaration of declarations) {
     const endpoint = `${filePath}#${declaration.canonicalId}`;
     if (!documentedEndpoints.has(endpoint)) {
-      if (!declaration.isMember && !undocumentedSeen.has(endpoint)) {
+      if (!undocumentedSeen.has(endpoint)) {
         undocumentedSeen.add(endpoint);
         undocumentedSymbols.push(makeCodeSymbol(filePath, endpoint, declaration));
       }
@@ -176609,6 +177148,9 @@ function makeCodeSymbol(filePath, endpoint, declaration) {
     endpoint,
     location: declaration.location
   };
+  if (declaration.isMember) {
+    symbol.isMember = true;
+  }
   if (declaration.nameRange !== undefined) {
     symbol.nameRange = declaration.nameRange;
   }
@@ -176693,54 +177235,13 @@ function duplicateLinkDiagnostic(source, target, location, range) {
   return diagnostic;
 }
 
-// src/core/code-language.ts
-var KNOWN_CODE_LANGUAGES = [
-  "typescript",
-  "swift",
-  "dart",
-  "rust"
-];
-function isCodeLanguage(value) {
-  return KNOWN_CODE_LANGUAGES.includes(value);
-}
+// src/core/code-scan.ts
 Object.assign(codeAdapters, {
   typescript: typeScriptAdapter,
   swift: createScannerWorkerAdapter("swift", (_projectRoot) => resolveScannerWorkerCommand("swift")),
   dart: createScannerWorkerAdapter("dart", (_projectRoot) => resolveScannerWorkerCommand("dart")),
   rust: createScannerWorkerAdapter("rust", (_projectRoot) => resolveScannerWorkerCommand("rust"))
 });
-var SUPPORTED_SCANNER_PLATFORM_KEYS = ["darwin-arm64", "linux-x64"];
-var SCANNER_EXECUTABLE_NAMES = {
-  swift: "docbridge-swift-scanner",
-  dart: "docbridge_dart_scanner",
-  rust: "docbridge-rust-scanner"
-};
-function scannerPlatformKey() {
-  return `${process.platform}-${process.arch}`;
-}
-function resolveScannerWorkerCommand(language, options = {}) {
-  const platformKey = options.platformKey ?? scannerPlatformKey();
-  const platformSupported = isSupportedScannerPlatformKey(platformKey);
-  const candidates = scannerExecutableCandidates(language, platformKey, platformSupported, options);
-  const found = candidates.find((candidate) => existsSync(candidate));
-  if (found !== undefined) {
-    const repair = ensureExecutable(found, options.chmod ?? chmodSync);
-    if (!repair.ok) {
-      return { ok: false, diagnostic: scannerUnavailableDiagnostic2(language, repair.reason) };
-    }
-    return { ok: true, command: [found] };
-  }
-  if (!platformSupported) {
-    return {
-      ok: false,
-      diagnostic: scannerUnavailableDiagnostic2(language, `platform ${platformKey} is unsupported; supported platforms: ${SUPPORTED_SCANNER_PLATFORM_KEYS.join(", ")}`)
-    };
-  }
-  return {
-    ok: false,
-    diagnostic: scannerUnavailableDiagnostic2(language, `missing ${scannerExecutableName(language)} for platform ${platformKey}; supported platforms: ${SUPPORTED_SCANNER_PLATFORM_KEYS.join(", ")}`)
-  };
-}
 function getCodeAdapter(language) {
   return codeAdapters[language];
 }
@@ -176774,25 +177275,6 @@ function createScannerWorkerAdapter(language, command, adapterOptions = {}) {
     }
   };
 }
-function collectCodeFiles(projectRoot, codeInclude) {
-  const collected = [];
-  const seen = new Set;
-  for (const language of KNOWN_CODE_LANGUAGES) {
-    const entry = codeInclude[language];
-    if (entry === undefined) {
-      continue;
-    }
-    for (const relPath of collectFiles(projectRoot, entry.patterns)) {
-      if (seen.has(relPath)) {
-        continue;
-      }
-      seen.add(relPath);
-      collected.push({ language, relPath });
-    }
-  }
-  collected.sort((left, right) => comparePaths(left.relPath, right.relPath));
-  return collected;
-}
 function scanCodeFiles(projectRoot, files, codeInclude, read, onContent) {
   const codeFiles = [];
   const diagnostics = [];
@@ -176817,24 +177299,6 @@ function scanCodeFiles(projectRoot, files, codeInclude, read, onContent) {
   }
   return { codeFiles, diagnostics };
 }
-function codeFileOwners(projectRoot, codeInclude) {
-  const owners = new Map;
-  for (const language of KNOWN_CODE_LANGUAGES) {
-    const entry = codeInclude[language];
-    if (entry === undefined) {
-      continue;
-    }
-    for (const relPath of collectFiles(projectRoot, entry.patterns)) {
-      const existing = owners.get(relPath);
-      if (existing === undefined) {
-        owners.set(relPath, [language]);
-      } else if (!existing.includes(language)) {
-        existing.push(language);
-      }
-    }
-  }
-  return owners;
-}
 function emptyScan(language, filePath) {
   return {
     language,
@@ -176851,448 +177315,717 @@ function fileScopedScannerDiagnostic(diagnostic, filePath) {
 function normalizeScannerCommand(value) {
   return Array.isArray(value) ? { ok: true, command: value } : value;
 }
-function scannerExecutableCandidates(language, platformKey, platformSupported, options) {
-  const sourceRoot = options.sourceRoot ?? sourceRootPath();
-  const distRoot = options.distRoot ?? distRootPath();
-  const executable = scannerExecutableName(language);
-  if (language === "swift") {
-    return [
-      join3(sourceRoot, "packages/swift-scanner/.build/release", executable),
-      join3(sourceRoot, "packages/swift-scanner/.build/debug", executable),
-      ...platformSupported ? [join3(distRoot, "bin", platformKey, executable)] : []
-    ];
-  }
-  if (language === "rust") {
-    return [
-      join3(sourceRoot, "packages/rust-scanner/target/release", executable),
-      join3(sourceRoot, "packages/rust-scanner/target/debug", executable),
-      ...platformSupported ? [join3(distRoot, "bin", platformKey, executable)] : []
-    ];
+
+// src/core/link-manifest.ts
+import { readFileSync as readFileSync3 } from "node:fs";
+import { join as join5 } from "node:path";
+
+// src/core/json-source.ts
+class JsonSyntaxError extends Error {
+  position;
+  constructor(message, position) {
+    super(message);
+    this.position = position;
   }
-  return [
-    join3(sourceRoot, "packages/dart-scanner/bin", executable),
-    ...platformSupported ? [join3(distRoot, "bin", platformKey, executable)] : []
-  ];
 }
-function ensureExecutable(path, chmod) {
-  let mode;
+var ESCAPE_VALUES = {
+  '"': '"',
+  "\\": "\\",
+  "/": "/",
+  b: "\b",
+  f: "\f",
+  n: `
+`,
+  r: "\r",
+  t: "\t"
+};
+function parseJsonSource(text) {
+  const reader = new JsonReader(text);
   try {
-    mode = statSync(path).mode;
+    reader.skipWhitespace();
+    const root = reader.readValue();
+    reader.skipWhitespace();
+    if (!reader.atEnd()) {
+      reader.fail("Unexpected trailing content after the JSON value.");
+    }
+    return { ok: true, root };
   } catch (error) {
-    return { ok: false, reason: `cannot stat ${path}: ${reasonOf(error)}` };
+    if (error instanceof JsonSyntaxError) {
+      return { ok: false, message: error.message, position: error.position };
+    }
+    throw error;
   }
-  if (isExecutableByThisProcess(path)) {
-    return { ok: true };
+}
+
+class JsonReader {
+  text;
+  index = 0;
+  line = 1;
+  column = 1;
+  constructor(text) {
+    this.text = text;
+  }
+  atEnd() {
+    return this.index >= this.text.length;
+  }
+  fail(message) {
+    throw new JsonSyntaxError(message, this.position());
+  }
+  position() {
+    return { line: this.line, column: this.column };
+  }
+  skipWhitespace() {
+    while (!this.atEnd()) {
+      const char = this.text[this.index] ?? "";
+      if (char !== " " && char !== "\t" && char !== `
+` && char !== "\r") {
+        return;
+      }
+      this.advance();
+    }
+  }
+  readValue() {
+    if (this.atEnd()) {
+      this.fail("Unexpected end of input where a JSON value was expected.");
+    }
+    const char = this.text[this.index] ?? "";
+    switch (char) {
+      case "{":
+        return this.readObject();
+      case "[":
+        return this.readArray();
+      case '"':
+        return this.readString();
+      case "t":
+        return this.readKeyword("true", true);
+      case "f":
+        return this.readKeyword("false", false);
+      case "n":
+        return this.readNull();
+      default:
+        return this.readNumber();
+    }
   }
-  try {
-    chmod(path, mode | 73);
-  } catch (error) {
-    return {
-      ok: false,
-      reason: `${path} is not executable (mode ${formatMode(mode)}) and the executable ` + `bit could not be restored: ${reasonOf(error)}; run \`chmod +x ${path}\` ` + `or reinstall DocBridge into a writable location`
-    };
+  readObject() {
+    const start = this.position();
+    this.expect("{");
+    const members = [];
+    this.skipWhitespace();
+    if (this.peek() === "}") {
+      this.advance();
+      return { kind: "object", members, range: { start, end: this.position() } };
+    }
+    for (;; ) {
+      this.skipWhitespace();
+      if (this.peek() !== '"') {
+        this.fail("Expected a quoted object key.");
+      }
+      const keyNode = this.readString();
+      this.skipWhitespace();
+      this.expect(":");
+      this.skipWhitespace();
+      const value = this.readValue();
+      members.push({ key: keyNode.value, keyRange: keyNode.range, value });
+      this.skipWhitespace();
+      const next = this.peek();
+      if (next === ",") {
+        this.advance();
+        continue;
+      }
+      if (next === "}") {
+        this.advance();
+        return { kind: "object", members, range: { start, end: this.position() } };
+      }
+      this.fail("Expected `,` or `}` in the object.");
+    }
   }
-  return { ok: true };
-}
-function isExecutableByThisProcess(path) {
-  try {
-    accessSync(path, constants.X_OK);
-    return true;
-  } catch {
-    return false;
+  readArray() {
+    const start = this.position();
+    this.expect("[");
+    const elements = [];
+    this.skipWhitespace();
+    if (this.peek() === "]") {
+      this.advance();
+      return { kind: "array", elements, range: { start, end: this.position() } };
+    }
+    for (;; ) {
+      this.skipWhitespace();
+      elements.push(this.readValue());
+      this.skipWhitespace();
+      const next = this.peek();
+      if (next === ",") {
+        this.advance();
+        continue;
+      }
+      if (next === "]") {
+        this.advance();
+        return { kind: "array", elements, range: { start, end: this.position() } };
+      }
+      this.fail("Expected `,` or `]` in the array.");
+    }
   }
-}
-function formatMode(mode) {
-  return `0${(mode & 4095).toString(8).padStart(3, "0")}`;
-}
-function isSupportedScannerPlatformKey(platformKey) {
-  return SUPPORTED_SCANNER_PLATFORM_KEYS.includes(platformKey);
-}
-function scannerRootsFromModuleUrl(moduleUrl) {
-  const modulePath = fileURLToPath(moduleUrl);
-  let resolved;
-  try {
-    resolved = realpathSync(modulePath);
-  } catch {
-    resolved = modulePath;
+  readString() {
+    const start = this.position();
+    this.expect('"');
+    const contentStart = this.position();
+    let value = "";
+    for (;; ) {
+      if (this.atEnd()) {
+        this.fail("Unterminated string.");
+      }
+      const char = this.text[this.index] ?? "";
+      if (char === '"') {
+        const contentEnd = this.position();
+        this.advance();
+        return {
+          kind: "string",
+          value,
+          contentRange: { start: contentStart, end: contentEnd },
+          range: { start, end: this.position() }
+        };
+      }
+      if (char === "\\") {
+        this.advance();
+        value += this.readEscape();
+        continue;
+      }
+      if (char < " ") {
+        this.fail("Unescaped control character in a string.");
+      }
+      this.advance();
+      value += char;
+    }
+  }
+  readEscape() {
+    if (this.atEnd()) {
+      this.fail("Unterminated escape sequence.");
+    }
+    const char = this.text[this.index] ?? "";
+    const simple = ESCAPE_VALUES[char];
+    if (simple !== undefined) {
+      this.advance();
+      return simple;
+    }
+    if (char !== "u") {
+      this.fail(`Unknown escape sequence \`\\${char}\`.`);
+    }
+    this.advance();
+    const digits = this.text.slice(this.index, this.index + 4);
+    if (!/^[0-9a-fA-F]{4}$/.test(digits)) {
+      this.fail("A `\\u` escape needs four hexadecimal digits.");
+    }
+    for (let offset = 0;offset < 4; offset += 1) {
+      this.advance();
+    }
+    return String.fromCharCode(Number.parseInt(digits, 16));
+  }
+  readNumber() {
+    const start = this.position();
+    const pattern = /-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/y;
+    pattern.lastIndex = this.index;
+    const match = pattern.exec(this.text);
+    if (match === null || match[0].length === 0) {
+      this.fail("Expected a JSON value.");
+    }
+    for (let offset = 0;offset < match[0].length; offset += 1) {
+      this.advance();
+    }
+    if (/[0-9a-zA-Z.+-]/.test(this.peek() ?? "")) {
+      this.fail("Malformed number.");
+    }
+    return { kind: "number", value: Number(match[0]), range: { start, end: this.position() } };
+  }
+  readNull() {
+    const start = this.position();
+    this.consumeWord("null");
+    return { kind: "null", value: null, range: { start, end: this.position() } };
+  }
+  readKeyword(word, value) {
+    const start = this.position();
+    this.consumeWord(word);
+    return { kind: "boolean", value, range: { start, end: this.position() } };
+  }
+  consumeWord(word) {
+    if (this.text.slice(this.index, this.index + word.length) !== word) {
+      this.fail(`Expected \`${word}\`.`);
+    }
+    for (let offset = 0;offset < word.length; offset += 1) {
+      this.advance();
+    }
+  }
+  peek() {
+    return this.text[this.index];
+  }
+  expect(char) {
+    if (this.peek() !== char) {
+      this.fail(`Expected \`${char}\`.`);
+    }
+    this.advance();
+  }
+  advance() {
+    const char = this.text[this.index] ?? "";
+    this.index += 1;
+    if (char === `
+`) {
+      this.line += 1;
+      this.column = 1;
+      return;
+    }
+    if (char === "\r") {
+      if (this.text[this.index] === `
+`) {
+        this.index += 1;
+      }
+      this.line += 1;
+      this.column = 1;
+      return;
+    }
+    this.column += 1;
   }
-  const moduleDir = dirname2(resolved);
-  return { distRoot: moduleDir, sourceRoot: resolve(moduleDir, "..", "..") };
-}
-function sourceRootPath() {
-  return scannerRootsFromModuleUrl(import.meta.url).sourceRoot;
-}
-function distRootPath() {
-  return scannerRootsFromModuleUrl(import.meta.url).distRoot;
-}
-function scannerExecutableName(language) {
-  return SCANNER_EXECUTABLE_NAMES[language];
-}
-function scannerUnavailableDiagnostic2(language, reason) {
-  const label = language.charAt(0).toUpperCase() + language.slice(1);
-  return {
-    severity: "error",
-    code: "code_scanner_unavailable",
-    language,
-    target: language,
-    message: `${label} scanner worker is unavailable: ${reason}`
-  };
 }
 
-// src/core/config.ts
-var CONFIG_FILE_NAME = "docbridge.config.json";
-var EMPTY_CONFIG = {
-  include: { code: {}, docs: [] }
-};
-var KNOWN_TOP_LEVEL_KEYS = new Set(["$schema", "include"]);
-var KNOWN_INCLUDE_KEYS = new Set(["code", "docs"]);
-var KNOWN_CODE_ENTRY_KEYS = new Set(["patterns", "visibility"]);
-var LANGUAGE_SUFFIX = {
-  typescript: ".ts",
-  swift: ".swift",
-  dart: ".dart",
-  rust: ".rs"
-};
-var LANGUAGE_VISIBILITY = {
-  typescript: ["public", "protected", "private"],
-  swift: ["public", "open", "internal"],
-  dart: ["public"],
-  rust: ["pub", "private"]
-};
-function loadConfig(projectRoot) {
+// src/core/link-manifest.ts
+var LINK_MANIFEST_FILE_NAME = "docbridge.links.json";
+var KNOWN_TOP_LEVEL_KEYS2 = new Set(["$schema", "links"]);
+var KNOWN_ENTRY_KEYS = new Set(["code", "doc", "note"]);
+var EMPTY_MANIFEST = { entries: [] };
+function loadLinkManifest(projectRoot) {
   let rawText;
   try {
-    rawText = readFileSync2(join4(projectRoot, CONFIG_FILE_NAME), "utf8");
-  } catch {
+    rawText = readFileSync3(join5(projectRoot, LINK_MANIFEST_FILE_NAME), "utf8");
+  } catch (error) {
+    if (!isMissingFileError(error)) {
+      const reason = error instanceof Error ? error.message : String(error);
+      return {
+        ok: false,
+        diagnostics: [
+          manifestDiagnostic("config_file_invalid", `Failed to read ${LINK_MANIFEST_FILE_NAME}: ${reason}`)
+        ]
+      };
+    }
     rawText = undefined;
   }
-  const resolved = resolveConfig(rawText);
-  if (!resolved.ok) {
-    return resolved;
-  }
-  const overlapDiagnostics = detectLanguageOverlap(projectRoot, resolved.config.include.code);
-  if (overlapDiagnostics.length === 0) {
-    return resolved;
-  }
-  return {
-    config: EMPTY_CONFIG,
-    diagnostics: [...resolved.diagnostics, ...overlapDiagnostics],
-    ok: false
-  };
+  return resolveLinkManifest(rawText);
 }
-function resolveConfig(rawText) {
+function isMissingFileError(error) {
+  return error instanceof Error && error.code === "ENOENT";
+}
+function resolveLinkManifest(rawText) {
   if (rawText === undefined) {
-    return {
-      config: EMPTY_CONFIG,
-      ok: false,
-      diagnostics: [
-        configDiagnostic("config_file_invalid", CONFIG_FILE_NAME, `${CONFIG_FILE_NAME} was not found. DocBridge requires a configuration file.`)
-      ]
-    };
+    return { ok: true, manifest: EMPTY_MANIFEST, diagnostics: [] };
   }
-  let parsed;
-  try {
-    parsed = JSON.parse(rawText);
-  } catch (error) {
-    const reason = error instanceof Error ? error.message : String(error);
+  const parsed = parseJsonSource(rawText);
+  if (!parsed.ok) {
     return {
-      config: EMPTY_CONFIG,
       ok: false,
       diagnostics: [
-        configDiagnostic("config_file_invalid", CONFIG_FILE_NAME, `Failed to parse ${CONFIG_FILE_NAME}: ${reason}`)
+        manifestDiagnostic("config_file_invalid", `Failed to parse ${LINK_MANIFEST_FILE_NAME}: ${parsed.message}`, parsed.position)
       ]
     };
   }
-  const diagnostics = [];
-  if (!isPlainObject(parsed)) {
-    diagnostics.push(configDiagnostic("config_invalid_value", CONFIG_FILE_NAME, "Configuration must be a JSON object."));
-    return { config: EMPTY_CONFIG, diagnostics, ok: false };
+  return validateManifest(parsed.root);
+}
+function validateManifest(root) {
+  if (root.kind !== "object") {
+    return { ok: false, diagnostics: [invalidValue("", "an object", root)] };
   }
-  for (const key of Object.keys(parsed)) {
-    if (!KNOWN_TOP_LEVEL_KEYS.has(key)) {
-      diagnostics.push(configDiagnostic("config_unknown_key", key, `Unknown top-level configuration key: ${key}`));
+  const diagnostics = [];
+  for (const member of root.members) {
+    if (!KNOWN_TOP_LEVEL_KEYS2.has(member.key)) {
+      diagnostics.push(unknownKey(member.key, member));
     }
   }
-  if ("$schema" in parsed && typeof parsed.$schema !== "string") {
-    diagnostics.push(configDiagnostic("config_invalid_value", "$schema", "`$schema` must be a string."));
+  reportDuplicateKeys(root, "", diagnostics);
+  const links = root.members.find((member) => member.key === "links");
+  if (links === undefined) {
+    return {
+      ok: false,
+      diagnostics: [...diagnostics, invalidValue("links", "present", root)]
+    };
   }
-  const include = parsed.include;
-  if (!isPlainObject(include)) {
-    diagnostics.push(configDiagnostic("config_invalid_value", "include", "`include` must be an object with `code` and `docs`."));
-    return { config: EMPTY_CONFIG, diagnostics, ok: false };
+  if (links.value.kind !== "array") {
+    return {
+      ok: false,
+      diagnostics: [...diagnostics, invalidValue("links", "an array", links.value)]
+    };
   }
-  for (const key of Object.keys(include)) {
-    if (!KNOWN_INCLUDE_KEYS.has(key)) {
-      diagnostics.push(configDiagnostic("config_unknown_key", `include.${key}`, `Unknown configuration key under \`include\`: ${key}`));
+  const entries = [];
+  for (const [index, element] of links.value.elements.entries()) {
+    const outcome = readEntry(element, index);
+    diagnostics.push(...outcome.diagnostics);
+    if (outcome.entry !== undefined) {
+      entries.push(outcome.entry);
     }
   }
-  const code = validateCodeInclude(include.code, diagnostics);
-  validatePatternArray(include.docs, "docs", ".md", false, diagnostics);
-  const ok = diagnostics.length === 0;
-  const config = ok ? { include: { code, docs: include.docs } } : EMPTY_CONFIG;
-  return { config, diagnostics, ok };
-}
-function validateCodeInclude(value, diagnostics) {
-  if (Array.isArray(value)) {
-    diagnostics.push(configDiagnostic("config_invalid_value", "include.code", '`include.code` must be a language-keyed object such as `{ "typescript": { "patterns": ["src/**/*.ts"] } }`, not an array.'));
-    return {};
-  }
-  if (!isPlainObject(value)) {
-    diagnostics.push(configDiagnostic("config_invalid_value", "include.code", "`include.code` must be a language-keyed object."));
-    return {};
-  }
-  const keys = Object.keys(value);
-  if (keys.length === 0) {
-    diagnostics.push(configDiagnostic("config_invalid_value", "include.code", "`include.code` must configure at least one language."));
-    return {};
+  if (diagnostics.some(isBlocking)) {
+    return { ok: false, diagnostics };
   }
-  const result = {};
-  for (const key of keys) {
-    if (!isCodeLanguage(key)) {
-      diagnostics.push(configDiagnostic("config_invalid_value", `include.code.${key}`, `Unknown code language: ${key}. Supported languages: ${KNOWN_CODE_LANGUAGES.join(", ")}.`));
-      continue;
-    }
-    const entry = validateCodeEntry(key, value[key], diagnostics);
-    if (entry !== undefined) {
-      result[key] = entry;
-    }
-  }
-  return result;
+  return { ok: true, manifest: { entries }, diagnostics };
 }
-function validateCodeEntry(language, value, diagnostics) {
-  const target = `include.code.${language}`;
-  if (!isPlainObject(value)) {
-    diagnostics.push(configDiagnostic("config_invalid_value", target, `\`${target}\` must be an object with a \`patterns\` array. Shorthand arrays are not supported.`));
-    return;
-  }
-  for (const key of Object.keys(value)) {
-    if (!KNOWN_CODE_ENTRY_KEYS.has(key)) {
-      diagnostics.push(configDiagnostic("config_unknown_key", `${target}.${key}`, `Unknown configuration key under \`${target}\`: ${key}`));
-    }
-  }
-  const before = diagnostics.length;
-  validatePatternArray(value.patterns, `code.${language}.patterns`, LANGUAGE_SUFFIX[language], language === "typescript", diagnostics);
-  if ("visibility" in value) {
-    if (!isStringArray(value.visibility)) {
-      diagnostics.push(configDiagnostic("config_invalid_value", `${target}.visibility`, `\`${target}.visibility\` must be an array of strings.`));
-    } else {
-      validateVisibilityOptions(language, value.visibility, target, diagnostics);
-    }
-  }
-  if (diagnostics.length !== before) {
-    return;
+function readEntry(element, index) {
+  const path = `links[${index}]`;
+  if (element.kind !== "object") {
+    return { diagnostics: [invalidValue(path, "an object", element)] };
   }
-  const entry = { patterns: value.patterns };
-  if (isStringArray(value.visibility)) {
-    entry.visibility = value.visibility;
+  const diagnostics = [];
+  for (const member of element.members) {
+    if (!KNOWN_ENTRY_KEYS.has(member.key)) {
+      diagnostics.push(unknownKey(`${path}.${member.key}`, member));
+    }
+  }
+  reportDuplicateKeys(element, `${path}.`, diagnostics);
+  const code = readString(element, "code", path, diagnostics);
+  const doc = readString(element, "doc", path, diagnostics);
+  const note = readOptionalNote(element, path, diagnostics);
+  if (code === undefined || doc === undefined || diagnostics.some(isBlocking)) {
+    return { diagnostics };
+  }
+  const codeTarget = parseTarget(code, diagnostics);
+  const docTarget = parseTarget(doc, diagnostics);
+  if (codeTarget === undefined || docTarget === undefined) {
+    return { diagnostics };
+  }
+  const entry = {
+    code: codeTarget,
+    doc: docTarget,
+    codeEndpoint: code.value,
+    docEndpoint: doc.value,
+    location: positionOf(element.range),
+    range: element.range,
+    codeRange: code.contentRange,
+    docRange: doc.contentRange
+  };
+  if (note !== undefined) {
+    entry.note = note;
   }
-  return entry;
+  return { entry, diagnostics };
 }
-function validateVisibilityOptions(language, values, target, diagnostics) {
-  const allowed = LANGUAGE_VISIBILITY[language];
-  if (allowed.length === 0) {
-    diagnostics.push(configDiagnostic("config_invalid_value", `${target}.visibility`, `\`${target}.visibility\` is not supported for ${language}.`));
+function readString(entry, key, path, diagnostics) {
+  const member = entry.members.find((candidate) => candidate.key === key);
+  if (member === undefined) {
+    diagnostics.push(invalidValue(`${path}.${key}`, "present", entry));
     return;
   }
-  for (const value of values) {
-    if (!allowed.includes(value)) {
-      diagnostics.push(configDiagnostic("config_invalid_value", `${target}.visibility`, `Unsupported ${language} visibility: ${value}. Supported values: ${allowed.join(", ")}.`));
-    }
+  if (member.value.kind !== "string") {
+    diagnostics.push(invalidValue(`${path}.${key}`, "a string", member.value));
+    return;
   }
+  return member.value;
 }
-function validatePatternArray(value, field, requiredSuffix, excludeDeclarationFiles, diagnostics) {
-  const target = `include.${field}`;
-  if (!Array.isArray(value)) {
-    diagnostics.push(configDiagnostic("config_invalid_value", target, `\`${target}\` must be a non-empty array of strings.`));
+function readOptionalNote(entry, path, diagnostics) {
+  const member = entry.members.find((candidate) => candidate.key === "note");
+  if (member === undefined) {
     return;
   }
-  if (value.length === 0) {
-    diagnostics.push(configDiagnostic("config_invalid_value", target, `\`${target}\` must contain at least one pattern.`));
+  if (member.value.kind !== "string") {
+    diagnostics.push(invalidValue(`${path}.note`, "a string", member.value));
     return;
   }
-  for (const pattern of value) {
-    if (typeof pattern !== "string") {
-      diagnostics.push(configDiagnostic("config_invalid_value", target, `\`${target}\` patterns must be strings.`));
-      continue;
-    }
-    const globResult = validateGlobPattern(pattern);
-    if (!globResult.ok) {
-      diagnostics.push(configDiagnostic("config_invalid_value", pattern, `Invalid pattern in \`${target}\`: ${globResult.message}`));
-      continue;
-    }
-    const suffixError = checkSuffix(pattern, requiredSuffix, excludeDeclarationFiles);
-    if (suffixError !== undefined) {
-      diagnostics.push(configDiagnostic("config_invalid_value", pattern, suffixError));
-    }
-  }
+  return member.value.value;
 }
-function checkSuffix(pattern, requiredSuffix, excludeDeclarationFiles) {
-  if (!pattern.endsWith(requiredSuffix)) {
-    return `Pattern must end with \`${requiredSuffix}\`.`;
-  }
-  if (excludeDeclarationFiles && pattern.endsWith(".d.ts")) {
-    return "Pattern must not target `.d.ts` declaration files.";
+function parseTarget(node, diagnostics) {
+  const result = parseLinkTarget(node.value, {
+    location: positionOf(node.contentRange),
+    targetRange: node.contentRange
+  });
+  if (result.ok) {
+    return result.target;
   }
+  diagnostics.push(result.diagnostic);
   return;
 }
-function detectLanguageOverlap(projectRoot, code) {
-  const diagnostics = [];
-  for (const [relPath, owners] of codeFileOwners(projectRoot, code)) {
-    if (owners.length > 1) {
-      diagnostics.push(configDiagnostic("config_invalid_value", relPath, `Code file ${relPath} matches multiple configured languages (${owners.join(", ")}). Each code file must belong to exactly one language.`));
+function reportDuplicateKeys(object, pathPrefix, diagnostics) {
+  const seen = new Set;
+  for (const member of object.members) {
+    if (seen.has(member.key)) {
+      diagnostics.push(manifestDiagnostic("config_invalid_value", `Duplicate key ${pathPrefix}${member.key} in ${LINK_MANIFEST_FILE_NAME}.`, positionOf(member.keyRange), member.keyRange));
     }
+    seen.add(member.key);
   }
-  return diagnostics;
 }
-function configDiagnostic(code, target, message) {
-  return { severity: "error", code, target, message };
-}
-function isPlainObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+function isBlocking(diagnostic) {
+  return diagnostic.code !== "invalid_link_target";
 }
-function isStringArray(value) {
-  return Array.isArray(value) && value.every((item) => typeof item === "string");
+function unknownKey(path, member) {
+  return manifestDiagnostic("config_unknown_key", `Unknown key ${path} in ${LINK_MANIFEST_FILE_NAME}.`, positionOf(member.keyRange), member.keyRange);
 }
-
-// src/core/diagnostics.ts
-function sortDiagnostics(diagnostics) {
-  return [...diagnostics].toSorted(compareDiagnostics);
+function invalidValue(path, expectation, node) {
+  const subject = path === "" ? LINK_MANIFEST_FILE_NAME : path;
+  return manifestDiagnostic("config_invalid_value", `${subject} must be ${expectation}.`, positionOf(node.range), node.range);
 }
-function summarizeDiagnostics(diagnostics) {
-  const summary = { errors: 0, warnings: 0 };
-  for (const diagnostic of diagnostics) {
-    if (diagnostic.severity === "error") {
-      summary.errors += 1;
-    } else {
-      summary.warnings += 1;
-    }
+function manifestDiagnostic(code, message, position, range) {
+  const diagnostic = {
+    severity: "error",
+    code,
+    target: LINK_MANIFEST_FILE_NAME,
+    message
+  };
+  if (position !== undefined) {
+    diagnostic.location = {
+      filePath: LINK_MANIFEST_FILE_NAME,
+      line: position.line,
+      column: position.column
+    };
   }
-  return summary;
-}
-function formatDiagnostic(diagnostic) {
-  const location = diagnostic.location;
-  if (location === undefined) {
-    return `${diagnostic.target} ${diagnostic.severity} ${diagnostic.code} - ${diagnostic.message}`;
+  if (range !== undefined) {
+    diagnostic.range = range;
   }
-  const prefix = `${location.filePath}:${location.line}:${location.column}`;
-  return `${prefix} ${diagnostic.severity} ${diagnostic.code} ${diagnostic.target} - ${diagnostic.message}`;
+  return diagnostic;
 }
-function formatSummary(summary) {
-  return `Summary: ${summary.errors} ${pluralize("error", summary.errors)}, ${summary.warnings} ${pluralize("warning", summary.warnings)}`;
+function positionOf(range) {
+  return {
+    filePath: LINK_MANIFEST_FILE_NAME,
+    line: range.start.line,
+    column: range.start.column
+  };
 }
-function compareDiagnostics(left, right) {
-  const leftLocation = left.location;
-  const rightLocation = right.location;
-  if (leftLocation === undefined && rightLocation !== undefined) {
-    return -1;
-  }
-  if (leftLocation !== undefined && rightLocation === undefined) {
-    return 1;
+
+// src/core/suggest.ts
+function nearestMatch(input, candidates) {
+  const ranked = candidates.map((candidate, index) => ({
+    candidate,
+    distance: editDistance(input, candidate),
+    index
+  })).toSorted((left, right) => left.distance - right.distance || left.index - right.index);
+  const abbreviation = ranked.find(({ candidate }) => isOrderedAbbreviation(input, candidate));
+  if (abbreviation !== undefined) {
+    return abbreviation.candidate;
   }
-  if (leftLocation !== undefined && rightLocation !== undefined) {
-    return compareString(leftLocation.filePath, rightLocation.filePath) || compareNumber(leftLocation.line, rightLocation.line) || compareNumber(leftLocation.column, rightLocation.column) || compareString(left.code, right.code) || compareString(left.target, right.target);
+  const best = ranked[0];
+  if (best === undefined) {
+    return;
   }
-  return compareString(left.code, right.code) || compareString(left.target, right.target);
-}
-function compareString(left, right) {
-  return left.localeCompare(right);
+  const closeEnough = best.distance <= Math.max(1, Math.floor(best.candidate.length / 2));
+  return closeEnough ? best.candidate : undefined;
 }
-function compareNumber(left, right) {
-  return left - right;
+function isOrderedAbbreviation(input, candidate) {
+  if (input.length < 3 || input.length >= candidate.length) {
+    return false;
+  }
+  let candidateIndex = 0;
+  for (const character of input) {
+    const matchIndex = candidate.indexOf(character, candidateIndex);
+    if (matchIndex === -1) {
+      return false;
+    }
+    candidateIndex = matchIndex + 1;
+  }
+  return true;
 }
-function pluralize(word, count) {
-  return count === 1 ? word : `${word}s`;
+function editDistance(left, right) {
+  let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+  for (let leftIndex = 1;leftIndex <= left.length; leftIndex += 1) {
+    const current = [leftIndex];
+    for (let rightIndex = 1;rightIndex <= right.length; rightIndex += 1) {
+      const substitutionCost = left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1;
+      current[rightIndex] = Math.min((current[rightIndex - 1] ?? Number.POSITIVE_INFINITY) + 1, (previous[rightIndex] ?? Number.POSITIVE_INFINITY) + 1, (previous[rightIndex - 1] ?? Number.POSITIVE_INFINITY) + substitutionCost);
+    }
+    previous = current;
+  }
+  return previous[right.length] ?? 0;
 }
 
-// src/core/endpoint.ts
-function filePathOf(endpoint) {
-  const hashIndex = endpoint.indexOf("#");
-  return hashIndex === -1 ? endpoint : endpoint.slice(0, hashIndex);
-}
-function fragmentOf(endpoint) {
-  const hashIndex = endpoint.indexOf("#");
-  return hashIndex === -1 ? endpoint : endpoint.slice(hashIndex + 1);
-}
-function compareEndpointOrder(left, right) {
-  return left.filePath.localeCompare(right.filePath) || left.line - right.line || left.column - right.column || left.endpoint.localeCompare(right.endpoint);
-}
-function endpointRange(element) {
-  const range = element.kind === "code" ? element.nameRange : element.headingTextRange;
-  if (range !== undefined) {
-    return range;
+// src/core/link-manifest-apply.ts
+function applyLinkManifest(input) {
+  if (input.manifest.entries.length === 0) {
+    return { codeFiles: input.codeFiles, docFiles: input.docFiles, diagnostics: [] };
   }
-  const { line, column } = element.location;
-  return { start: { line, column }, end: { line, column } };
+  const state = new ApplyState(input);
+  for (const entry of input.manifest.entries) {
+    state.applyEntry(entry);
+  }
+  return state.result();
 }
 
-// src/core/graph.ts
-function buildLinkGraph(codeFiles, docFiles) {
-  const codeByEndpoint = new Map;
-  for (const file of codeFiles) {
-    for (const symbol of file.symbols) {
-      if (!codeByEndpoint.has(symbol.endpoint)) {
-        codeByEndpoint.set(symbol.endpoint, symbol);
-      }
+class ApplyState {
+  erroredFiles;
+  codeStates = new Map;
+  docStates = new Map;
+  codeOrder;
+  docOrder;
+  diagnostics = [];
+  constructor(input) {
+    this.erroredFiles = collectErroredFiles(input.scanDiagnostics);
+    this.codeOrder = input.codeFiles;
+    this.docOrder = input.docFiles;
+    for (const file of input.codeFiles) {
+      const byEndpoint = new Map;
+      for (const symbol of [...file.symbols, ...file.undocumentedSymbols]) {
+        if (!byEndpoint.has(symbol.endpoint)) {
+          byEndpoint.set(symbol.endpoint, symbol);
+        }
+      }
+      this.codeStates.set(file.filePath, {
+        file,
+        symbols: file.symbols,
+        undocumentedSymbols: file.undocumentedSymbols,
+        links: file.links,
+        byEndpoint,
+        outgoing: new Set(file.links.map((annotation) => pairKey(annotation.source, annotation.target))),
+        changed: false
+      });
+    }
+    for (const file of input.docFiles) {
+      this.docStates.set(file.filePath, {
+        file,
+        headings: file.headings,
+        links: file.links,
+        anchors: new Set(file.anchors.map((anchor) => anchor.endpoint)),
+        outgoing: new Set(file.links.map((annotation) => pairKey(annotation.source, annotation.target))),
+        changed: false
+      });
     }
   }
-  const docByEndpoint = new Map;
-  for (const file of docFiles) {
-    for (const anchor of file.anchors) {
-      if (!docByEndpoint.has(anchor.endpoint)) {
-        docByEndpoint.set(anchor.endpoint, anchor);
-      }
+  applyEntry(entry) {
+    if (this.erroredFiles.has(entry.code.filePath) || this.erroredFiles.has(entry.doc.filePath)) {
+      return;
     }
+    const codeResolved = this.resolveCodeSide(entry);
+    const docResolved = this.resolveDocSide(entry);
+    if (!codeResolved || !docResolved) {
+      return;
+    }
+    this.addLinks(entry);
   }
-  const counterparts = new Map;
-  const addEdge = (a, b) => {
-    addTo(counterparts, a, b);
-    addTo(counterparts, b, a);
-  };
-  for (const file of codeFiles) {
-    for (const link of file.links) {
-      if (codeByEndpoint.has(link.source) && docByEndpoint.has(link.target)) {
-        addEdge(link.source, link.target);
-      }
+  resolveCodeSide(entry) {
+    const state = this.codeStates.get(entry.code.filePath);
+    if (state === undefined) {
+      this.report("code_file_not_found", entry.codeEndpoint, `Code file ${entry.code.filePath} declared in the link manifest is not in the managed code set.`, entry, "code");
+      return false;
     }
+    const symbol = state.byEndpoint.get(entry.codeEndpoint);
+    if (symbol === undefined) {
+      this.report("code_symbol_not_found", entry.codeEndpoint, this.symbolNotFoundMessage(entry, state), entry, "code", state.file.language);
+      return false;
+    }
+    this.markDocumented(state, symbol);
+    return true;
   }
-  for (const file of docFiles) {
-    for (const link of file.links) {
-      if (docByEndpoint.has(link.source) && codeByEndpoint.has(link.target)) {
-        addEdge(link.source, link.target);
-      }
+  resolveDocSide(entry) {
+    const state = this.docStates.get(entry.doc.filePath);
+    if (state === undefined) {
+      this.report("doc_file_not_found", entry.docEndpoint, `Doc file ${entry.doc.filePath} declared in the link manifest is not in the managed docs set.`, entry, "doc");
+      return false;
     }
+    if (!state.anchors.has(entry.docEndpoint)) {
+      this.report("doc_anchor_not_found", entry.docEndpoint, `Doc anchor ${entry.docEndpoint} declared in the link manifest does not exist.`, entry, "doc");
+      return false;
+    }
+    this.markAnnotated(state, entry.docEndpoint);
+    return true;
   }
-  return { codeByEndpoint, docByEndpoint, counterparts };
-}
-function counterpartsOf(graph, endpoint) {
-  const targets = graph.counterparts.get(endpoint);
-  if (targets === undefined) {
-    return [];
+  addLinks(entry) {
+    const codeState = this.codeStates.get(entry.code.filePath);
+    const docState = this.docStates.get(entry.doc.filePath);
+    if (codeState === undefined || docState === undefined) {
+      return;
+    }
+    const forward = pairKey(entry.codeEndpoint, entry.docEndpoint);
+    const backward = pairKey(entry.docEndpoint, entry.codeEndpoint);
+    const hasForward = codeState.outgoing.has(forward);
+    const hasBackward = docState.outgoing.has(backward);
+    if (hasForward || hasBackward) {
+      this.diagnostics.push({
+        severity: "warning",
+        code: "duplicate_link",
+        source: entry.codeEndpoint,
+        target: entry.docEndpoint,
+        message: `Link ${entry.codeEndpoint} to ${entry.docEndpoint} is already declared.`,
+        location: entry.location,
+        range: entry.range
+      });
+    }
+    if (!hasForward) {
+      codeState.links = [
+        ...codeState.links,
+        manifestLink(entry.codeEndpoint, entry.docEndpoint, entry, "doc")
+      ];
+      codeState.outgoing.add(forward);
+      codeState.changed = true;
+    }
+    if (!hasBackward) {
+      docState.links = [
+        ...docState.links,
+        manifestLink(entry.docEndpoint, entry.codeEndpoint, entry, "code")
+      ];
+      docState.outgoing.add(backward);
+      docState.changed = true;
+    }
   }
-  const resolved = [];
-  for (const target of targets) {
-    const code = graph.codeByEndpoint.get(target);
-    if (code !== undefined) {
-      resolved.push(code);
-      continue;
+  markDocumented(state, symbol) {
+    if (!state.undocumentedSymbols.includes(symbol)) {
+      return;
     }
-    const doc = graph.docByEndpoint.get(target);
-    if (doc !== undefined) {
-      resolved.push(doc);
+    state.undocumentedSymbols = state.undocumentedSymbols.filter((candidate) => candidate !== symbol);
+    state.symbols = [...state.symbols, symbol];
+    state.changed = true;
+  }
+  markAnnotated(state, endpoint) {
+    const index = state.headings.findIndex((heading2) => heading2.anchor?.endpoint === endpoint);
+    const heading = state.headings[index];
+    if (heading === undefined || heading.hasCodeAnnotation) {
+      return;
+    }
+    state.headings = state.headings.toSpliced(index, 1, {
+      ...heading,
+      hasCodeAnnotation: true
+    });
+    state.changed = true;
+  }
+  symbolNotFoundMessage(entry, state) {
+    const base = `Code symbol ${entry.codeEndpoint} declared in the link manifest does not exist.`;
+    const candidates = [...state.byEndpoint.values()].map((symbol) => symbol.canonicalId);
+    const suggestion = nearestMatch(entry.code.fragment, candidates);
+    return suggestion === undefined ? base : `${base} Did you mean \`${suggestion}\`?`;
+  }
+  report(code, target, message, entry, side, language) {
+    const range = side === "code" ? entry.codeRange : entry.docRange;
+    const diagnostic = {
+      severity: "error",
+      code,
+      target,
+      message,
+      location: { ...entry.location, line: range.start.line, column: range.start.column },
+      range
+    };
+    if (language !== undefined) {
+      diagnostic.language = language;
     }
+    this.diagnostics.push(diagnostic);
   }
-  return resolved.toSorted(compareEndpoints);
-}
-function addTo(map, key, value) {
-  const existing = map.get(key);
-  if (existing === undefined) {
-    map.set(key, new Set([value]));
-    return;
+  result() {
+    const codeFiles = this.codeOrder.map((file) => {
+      const state = this.codeStates.get(file.filePath);
+      if (state === undefined || !state.changed) {
+        return file;
+      }
+      return {
+        ...file,
+        symbols: state.symbols,
+        undocumentedSymbols: state.undocumentedSymbols,
+        links: state.links
+      };
+    });
+    const docFiles = this.docOrder.map((file) => {
+      const state = this.docStates.get(file.filePath);
+      if (state === undefined || !state.changed) {
+        return file;
+      }
+      return { ...file, headings: state.headings, links: state.links };
+    });
+    return { codeFiles, docFiles, diagnostics: this.diagnostics };
   }
-  existing.add(value);
 }
-function compareEndpoints(left, right) {
-  return compareEndpointOrder({ ...left.location, endpoint: left.endpoint }, { ...right.location, endpoint: right.endpoint });
+function pairKey(source, target) {
+  return `${source} -> ${target}`;
+}
+function manifestLink(source, target, entry, side) {
+  return {
+    source,
+    target,
+    location: entry.location,
+    targetRange: side === "code" ? entry.codeRange : entry.docRange
+  };
 }
 
 // src/core/markdown-syntax.ts
@@ -177565,10 +178298,17 @@ function scanProject(options) {
   if (!configResult.ok) {
     return { ok: false, diagnostics: configResult.diagnostics };
   }
+  const manifestResult = loadLinkManifest(options.projectRoot);
+  if (!manifestResult.ok) {
+    return { ok: false, diagnostics: [...configResult.diagnostics, ...manifestResult.diagnostics] };
+  }
   const collectCode = options.collectCode ?? collectCodeFiles;
   const collectDocs = options.collectDocs ?? collectFiles;
   const readFile = options.readFile ?? ((relPath) => readManagedFile(options.projectRoot, relPath));
-  const diagnostics = [...configResult.diagnostics];
+  const diagnostics = [
+    ...configResult.diagnostics,
+    ...manifestResult.diagnostics
+  ];
   const contentByFile = options.keepContent ? new Map : undefined;
   const codeScan = scanCodeFiles(options.projectRoot, collectCode(options.projectRoot, configResult.config.include.code), configResult.config.include.code, readFile, contentByFile === undefined ? undefined : (relPath, content) => contentByFile.set(relPath, content));
   diagnostics.push(...codeScan.diagnostics);
@@ -177584,17 +178324,24 @@ function scanProject(options) {
     diagnostics.push(...scan2.diagnostics);
     docFiles.push(scan2);
   }
-  const codeFiles = codeScan.codeFiles;
+  const applied = applyLinkManifest({
+    manifest: manifestResult.manifest,
+    codeFiles: codeScan.codeFiles,
+    docFiles,
+    scanDiagnostics: diagnostics
+  });
+  diagnostics.push(...applied.diagnostics);
+  const codeFiles = applied.codeFiles;
   const scan = {
     codeFiles,
-    docFiles,
+    docFiles: applied.docFiles,
     diagnostics
   };
   if (contentByFile !== undefined) {
     scan.contentByFile = contentByFile;
   }
   if (options.buildGraph === true) {
-    scan.graph = buildLinkGraph(codeFiles, docFiles);
+    scan.graph = buildLinkGraph(codeFiles, applied.docFiles);
   }
   return {
     ok: true,
@@ -177743,7 +178490,7 @@ function resolveLinks(input) {
       continue;
     }
     for (const link of file.links) {
-      docToCodePairs.add(pairKey(link.source, link.target));
+      docToCodePairs.add(pairKey2(link.source, link.target));
     }
   }
   const codeToDocPairs = new Set;
@@ -177752,7 +178499,7 @@ function resolveLinks(input) {
       continue;
     }
     for (const link of file.links) {
-      codeToDocPairs.add(pairKey(link.source, link.target));
+      codeToDocPairs.add(pairKey2(link.source, link.target));
     }
   }
   for (const file of input.codeFiles) {
@@ -177773,7 +178520,7 @@ function resolveLinks(input) {
         diagnostics.push(relationshipDiagnostic("doc_anchor_not_found", link.source, docEndpoint, `Doc anchor ${docEndpoint} referenced by ${link.source} does not exist.`, link));
         continue;
       }
-      if (!docToCodePairs.has(pairKey(docEndpoint, link.source))) {
+      if (!docToCodePairs.has(pairKey2(docEndpoint, link.source))) {
         diagnostics.push(relationshipDiagnostic("doc_backlink_not_found", link.source, docEndpoint, `Doc anchor ${docEndpoint} has no matching @code backlink to ${link.source}.`, link));
       }
     }
@@ -177792,7 +178539,7 @@ function resolveLinks(input) {
         diagnostics.push(relationshipDiagnostic("code_file_not_found", link.source, codeEndpoint, `Code file ${codeFilePath} referenced by ${link.source} is not in the managed code set.`, link));
         continue;
       }
-      if (!codeToDocPairs.has(pairKey(codeEndpoint, link.source))) {
+      if (!codeToDocPairs.has(pairKey2(codeEndpoint, link.source))) {
         diagnostics.push(relationshipDiagnostic("code_backlink_not_found", link.source, codeEndpoint, `Code endpoint ${codeEndpoint} has no matching @doc pair back to ${link.source}.`, link));
       }
     }
@@ -177827,6 +178574,9 @@ function auditUndocumentedSymbols(input, erroredFiles) {
       continue;
     }
     for (const symbol of file.undocumentedSymbols) {
+      if (symbol.isMember === true) {
+        continue;
+      }
       diagnostics.push({
         severity: "warning",
         code: "undocumented_symbol",
@@ -177898,19 +178648,7 @@ function unlinkedDocSectionDiagnostic(node, anchor) {
   }
   return diagnostic;
 }
-function collectErroredFiles(diagnostics) {
-  const errored = new Set;
-  for (const diagnostic of diagnostics) {
-    if (diagnostic.code === "file_read_error" || diagnostic.code === "code_parse_error" || isFileScopedScannerDiagnostic(diagnostic)) {
-      errored.add(diagnostic.target);
-    }
-  }
-  return errored;
-}
-function isFileScopedScannerDiagnostic(diagnostic) {
-  return (diagnostic.code === "code_scanner_unavailable" || diagnostic.code === "code_scanner_failed") && diagnostic.language !== undefined && diagnostic.target !== diagnostic.language;
-}
-function pairKey(source, target) {
+function pairKey2(source, target) {
   return `${source}->${target}`;
 }
 function relationshipDiagnostic(code, source, target, message, link) {
@@ -178498,8 +179236,33 @@ function comparePairs(left, right) {
   return left.docEndpoint.localeCompare(right.docEndpoint) || left.codeEndpoint.localeCompare(right.codeEndpoint);
 }
 
+// src/core/package-root.ts
+import { existsSync as existsSync2, realpathSync as realpathSync2 } from "node:fs";
+import { dirname as dirname3, join as join6 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+function resolvePackageRoot(moduleUrl = import.meta.url) {
+  const modulePath = fileURLToPath2(moduleUrl);
+  let resolved;
+  try {
+    resolved = realpathSync2(modulePath);
+  } catch {
+    resolved = modulePath;
+  }
+  let dir = dirname3(resolved);
+  for (;; ) {
+    if (existsSync2(join6(dir, "templates", "skills"))) {
+      return dir;
+    }
+    const parent = dirname3(dir);
+    if (parent === dir) {
+      return dir;
+    }
+    dir = parent;
+  }
+}
+
 // src/lsp/server.ts
-import { fileURLToPath as fileURLToPath3 } from "node:url";
+import { fileURLToPath as fileURLToPath4 } from "node:url";
 
 // src/lsp/position.ts
 function toLspPosition(position) {
@@ -178677,11 +179440,11 @@ function counterpartLocators(state, filePath, position) {
 
 // src/lsp/paths.ts
 import { isAbsolute as isAbsolute2, relative as relative2, resolve as resolve2, sep } from "node:path";
-import { fileURLToPath as fileURLToPath2, pathToFileURL } from "node:url";
+import { fileURLToPath as fileURLToPath3, pathToFileURL } from "node:url";
 function uriToRelativePath(projectRoot, uri) {
   let absolute;
   try {
-    absolute = fileURLToPath2(uri);
+    absolute = fileURLToPath3(uri);
   } catch {
     return;
   }
@@ -179104,7 +179867,7 @@ function runLspServer() {
 }
 function uriToPath(uri) {
   try {
-    return fileURLToPath3(uri);
+    return fileURLToPath4(uri);
   } catch {
     return;
   }
@@ -179138,363 +179901,264 @@ function fullChangeText(changes) {
   return typeof last.text === "string" ? last.text : undefined;
 }
 
-// src/cli/docs.ts
-import { readdirSync as readdirSync3, readFileSync as readFileSync4 } from "node:fs";
-import { join as join6 } from "node:path";
-
-// src/core/init-plan.ts
-import { existsSync as existsSync2, readdirSync as readdirSync2, readFileSync as readFileSync3, realpathSync as realpathSync2 } from "node:fs";
-import { dirname as dirname3, join as join5, relative as relative3 } from "node:path";
-import { fileURLToPath as fileURLToPath4 } from "node:url";
-var CONFIG_FILE_NAME2 = "docbridge.config.json";
-var INIT_SKILL_NAMES = [
-  "docbridge-adopt",
-  "docbridge-annotate",
-  "docbridge-link",
-  "docbridge-review",
-  "docbridge-sync"
-];
-var INIT_WITH_AGENT_SKILL_NAMES = ["docbridge-adopt"];
-function planInitCommand(input) {
-  const packageRoot = input.packageRoot ?? resolvePackageRoot();
-  const existingConfig = readExistingConfig(input.projectRoot);
-  const messages = [];
-  const nextSteps = [];
-  let exitCode = 0;
-  const agentResolution = input.command === "init" ? resolveInitAgentTarget(input.discovery, input.options) : resolveInitWithAgentTarget(input.discovery, input.options);
-  if (agentResolution.error !== undefined) {
-    return {
-      command: input.command,
-      configOps: [],
-      skillOps: [],
-      messages: [agentResolution.error],
-      nextSteps: [],
-      agentGuidance: [],
-      exitCode: 1
-    };
-  }
-  const agentTarget = agentResolution.target ?? "none";
-  const configOps = input.command === "init" ? planConfigOperations({
-    projectRoot: input.projectRoot,
-    options: input.options,
-    discovery: input.discovery,
-    confirmedScope: input.confirmedScope,
-    existingConfig,
-    messages
-  }) : [];
-  if (configOps.some((operation) => operation.action === "create" || operation.action === "would-create")) {
-    nextSteps.push("Review docbridge.config.json and adjust include.docs or include.code if needed.");
-    nextSteps.push("Add @doc and @code annotations to link code and documentation.");
-    nextSteps.push("Run docbridge check when links exist.");
-  } else if (existingConfig.ok) {
-    messages.push("Existing docbridge.config.json was left unchanged.");
-    summarizeExistingConfig(existingConfig.config, messages);
-  } else if (existingConfig.rawText !== undefined) {
-    messages.push("Existing docbridge.config.json is invalid and was not modified.");
-    for (const diagnostic of existingConfig.diagnostics) {
-      messages.push(diagnostic.message);
-    }
-    messages.push("Repair the config manually or delete it before re-running init.");
-    exitCode = 1;
-  }
-  const skillOps = planSkillOperations({
-    command: input.command,
-    projectRoot: input.projectRoot,
-    packageRoot,
-    agentTarget,
-    options: input.options
-  });
-  const agentGuidance = input.command === "init-with-agent" && agentTarget !== "none" ? buildAgentGuidance(input.projectRoot, agentTarget) : [];
-  if (input.command === "init-with-agent") {
-    nextSteps.push("Run the printed one-shot command or fallback prompt in your agent.");
-    nextSteps.push("Let docbridge-adopt confirm scope and create or improve docbridge.config.json.");
-  }
-  if (input.options.yes && input.command === "init" && configOps.length === 0 && existingConfig.rawText === undefined && (input.discovery.docs.ambiguous || input.discovery.code.ambiguous)) {
-    exitCode = 1;
-  }
-  return {
-    command: input.command,
-    configOps,
-    skillOps,
-    messages,
-    nextSteps,
-    agentGuidance,
-    exitCode
-  };
-}
-function buildConfigFromScope(scope) {
-  const code = {};
-  for (const language of scope.languages) {
-    code[language.language] = { patterns: [...language.patterns] };
-  }
-  return {
-    include: {
-      code,
-      docs: [scope.docsPattern]
-    }
-  };
+// src/setup/update-cache.ts
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync4, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname as dirname4, join as join7 } from "node:path";
+var UPDATE_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+var UPDATE_CACHE_SCHEMA_VERSION = 1;
+function resolveUpdateCachePath(env = process.env, home = homedir()) {
+  const explicit = env.DOCBRIDGE_UPDATE_CACHE;
+  if (explicit !== undefined && explicit.length > 0) {
+    return explicit;
+  }
+  const cacheRoot = env.XDG_CACHE_HOME !== undefined && env.XDG_CACHE_HOME.length > 0 ? env.XDG_CACHE_HOME : join7(home, ".cache");
+  return join7(cacheRoot, "docbridge", "update-check.json");
 }
-function resolvePackageRoot(moduleUrl = import.meta.url) {
-  const modulePath = fileURLToPath4(moduleUrl);
-  let resolved;
+function readUpdateCache(path) {
+  let rawText;
   try {
-    resolved = realpathSync2(modulePath);
+    rawText = readFileSync4(path, "utf8");
   } catch {
-    resolved = modulePath;
-  }
-  let dir = dirname3(resolved);
-  for (;; ) {
-    if (existsSync2(join5(dir, "templates", "skills"))) {
-      return dir;
-    }
-    const parent = dirname3(dir);
-    if (parent === dir) {
-      return dir;
-    }
-    dir = parent;
+    return;
   }
-}
-function listDistributableSkills(packageRoot) {
-  const skillsRoot = join5(packageRoot, "templates", "skills");
-  let entries;
+  let parsed;
   try {
-    entries = readdirSync2(skillsRoot);
+    parsed = JSON.parse(rawText);
   } catch {
-    return [];
+    return;
   }
-  return entries.filter((entry) => entry.startsWith("docbridge-")).filter((entry) => existsSync2(join5(skillsRoot, entry, "SKILL.md"))).toSorted();
+  return toUpdateCacheRecord(parsed);
 }
-function formatInitPlan(plan) {
-  const lines = [];
-  for (const message of plan.messages) {
-    lines.push(message);
-  }
-  if (plan.configOps.length > 0) {
-    lines.push("");
-    lines.push("Config:");
-    for (const operation of plan.configOps) {
-      lines.push(formatFileOp(operation));
-      if (operation.content !== undefined) {
-        lines.push(operation.content);
-      }
-    }
-  }
-  if (plan.skillOps.length > 0) {
-    lines.push("");
-    lines.push("Skills:");
-    for (const operation of plan.skillOps) {
-      lines.push(formatFileOp(operation));
-    }
-  }
-  if (plan.agentGuidance.length > 0) {
-    lines.push("");
-    lines.push("Agent setup:");
-    for (const guidance of plan.agentGuidance) {
-      lines.push("");
-      lines.push(`${capitalize(guidance.agent)} destination: ${guidance.destination}`);
-      lines.push(`One-shot command: ${guidance.oneShotCommand}`);
-      lines.push("Fallback prompt:");
-      lines.push(guidance.fallbackPrompt);
-    }
-  }
-  if (plan.nextSteps.length > 0) {
-    lines.push("");
-    lines.push("Next steps:");
-    for (const step of plan.nextSteps) {
-      lines.push(`- ${step}`);
-    }
-  }
-  return `${lines.join(`
-`)}
-`;
+function writeUpdateCache(path, record) {
+  try {
+    mkdirSync2(dirname4(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(record, null, 2)}
+`, "utf8");
+  } catch {}
 }
-function planConfigOperations(input) {
-  if (input.existingConfig.rawText !== undefined) {
-    return [];
-  }
-  const scope = input.confirmedScope ?? inferConfirmedScope(input.discovery, input.options);
-  if (scope === undefined) {
-    if (input.discovery.docs.message !== undefined) {
-      input.messages.push(input.discovery.docs.message);
-    }
-    if (input.discovery.code.message !== undefined) {
-      input.messages.push(input.discovery.code.message);
-    }
-    if (input.options.yes) {
-      input.messages.push("Automatic setup stopped because docs or code scope is ambiguous. Re-run interactively or confirm scope explicitly.");
-    }
-    return [];
-  }
-  const config = buildConfigFromScope(scope);
-  const content = `${JSON.stringify({ $schema: "./schemas/docbridge.schema.json", ...config }, null, 2)}
-`;
-  const action = input.options.dryRun ? "would-create" : "create";
-  input.messages.push(`Docs scope: ${scope.docsPattern}`);
-  input.messages.push(`Code scope: ${scope.languages.map((language) => `${language.language} (${language.patterns.join(", ")})`).join("; ")}`);
-  return [
-    {
-      action,
-      path: CONFIG_FILE_NAME2,
-      content,
-      reason: "Create docbridge.config.json from discovered scope."
-    }
-  ];
+function isUpdateCacheFresh(record, now, ttlMs = UPDATE_CACHE_TTL_MS) {
+  const age = now - record.checkedAt;
+  return age >= 0 && age < ttlMs;
 }
-function inferConfirmedScope(discovery, options) {
-  if (discovery.docs.ambiguous || discovery.code.ambiguous) {
+function toUpdateCacheRecord(value) {
+  if (typeof value !== "object" || value === null) {
     return;
   }
-  if (discovery.docs.recommended === undefined || discovery.code.languages.length === 0) {
+  const candidate = value;
+  if (candidate.schema !== UPDATE_CACHE_SCHEMA_VERSION) {
     return;
   }
-  if (!options.yes) {
+  if (typeof candidate.checkedAt !== "number" || !Number.isFinite(candidate.checkedAt)) {
+    return;
+  }
+  if (candidate.latest !== null && typeof candidate.latest !== "string") {
     return;
   }
   return {
-    docsPattern: discovery.docs.recommended.pattern,
-    languages: discovery.code.languages
+    schema: UPDATE_CACHE_SCHEMA_VERSION,
+    checkedAt: candidate.checkedAt,
+    latest: candidate.latest
   };
 }
-function planSkillOperations(input) {
-  if (input.agentTarget === "none") {
-    return [];
+
+// src/setup/version.ts
+var STABLE_VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+function parseStableVersion(value) {
+  const match = STABLE_VERSION_PATTERN.exec(value.trim());
+  if (match === null) {
+    return;
   }
-  const skillNames = input.command === "init" ? [...INIT_SKILL_NAMES] : [...INIT_WITH_AGENT_SKILL_NAMES];
-  const destinations = agentDestinations(input.agentTarget);
-  const availableSkills = new Set(listDistributableSkills(input.packageRoot));
-  const operations = [];
-  for (const destination of destinations) {
-    for (const skillName of skillNames) {
-      if (!availableSkills.has(skillName)) {
-        continue;
-      }
-      const destinationDir = join5(input.projectRoot, destination, skillName);
-      const exists = existsSync2(destinationDir);
-      let action;
-      let reason;
-      if (exists && input.options.force) {
-        action = input.options.dryRun ? "would-overwrite" : "overwrite";
-        reason = "Overwrite existing skill directory.";
-      } else if (exists) {
-        action = "skip";
-        reason = "Skill directory already exists.";
-      } else {
-        action = input.options.dryRun ? "would-create" : "create";
-        reason = "Install distributable skill template.";
-      }
-      operations.push({
-        action,
-        path: relative3(input.projectRoot, destinationDir),
-        reason
-      });
-    }
+  const [, major, minor, patch] = match;
+  if (major === undefined || minor === undefined || patch === undefined) {
+    return;
   }
-  return operations;
+  return {
+    major: Number.parseInt(major, 10),
+    minor: Number.parseInt(minor, 10),
+    patch: Number.parseInt(patch, 10)
+  };
 }
-function buildAgentGuidance(projectRoot, agentTarget) {
-  const guidance = [];
-  if (agentTarget === "codex" || agentTarget === "both") {
-    guidance.push({
-      agent: "codex",
-      destination: ".agents/skills/docbridge-adopt/",
-      oneShotCommand: `cd ${projectRoot} && $docbridge_adopt_prompt`,
-      fallbackPrompt: buildFallbackPrompt(projectRoot, "codex")
-    });
-  }
-  if (agentTarget === "claude" || agentTarget === "both") {
-    guidance.push({
-      agent: "claude",
-      destination: ".claude/skills/docbridge-adopt/",
-      oneShotCommand: `cd ${projectRoot} && /docbridge-adopt`,
-      fallbackPrompt: buildFallbackPrompt(projectRoot, "claude")
-    });
-  }
-  for (const entry of guidance) {
-    entry.oneShotCommand = entry.oneShotCommand.replace("$docbridge_adopt_prompt", 'codex --prompt "Use the docbridge-adopt skill to adopt DocBridge in this repository."');
-  }
-  return guidance;
+function compareStableVersions(left, right) {
+  return left.major - right.major || left.minor - right.minor || left.patch - right.patch;
 }
-function buildFallbackPrompt(projectRoot, agent) {
-  const invocation = agent === "claude" ? "Use the docbridge-adopt skill" : "Use the docbridge-adopt skill from .agents/skills/docbridge-adopt";
-  return `${invocation} to adopt DocBridge in ${projectRoot}. Confirm docs and code scope, create or improve docbridge.config.json, install the companion DocBridge skills, and suggest the next linking steps.`;
+function isNewerStableVersion(candidate, current) {
+  const parsedCandidate = parseStableVersion(candidate);
+  const parsedCurrent = parseStableVersion(current);
+  if (parsedCandidate === undefined || parsedCurrent === undefined) {
+    return false;
+  }
+  return compareStableVersions(parsedCandidate, parsedCurrent) > 0;
 }
-function resolveInitAgentTarget(discovery, options) {
-  if (options.agentTarget !== undefined) {
-    return { target: options.agentTarget, error: undefined };
+
+// src/setup/registry.ts
+var NPM_REGISTRY_LATEST_URL = "https://registry.npmjs.org/docbridge/latest";
+var REGISTRY_TIMEOUT_MS = 1500;
+function selectStableVersion(payload) {
+  if (typeof payload !== "object" || payload === null) {
+    return;
   }
-  if (options.yes) {
-    return { target: discovery.agent.defaultTarget, error: undefined };
+  const version = payload.version;
+  if (typeof version !== "string") {
+    return;
   }
-  return { target: discovery.agent.recommendedTarget, error: undefined };
+  return parseStableVersion(version) === undefined ? undefined : version.trim();
 }
-function resolveInitWithAgentTarget(discovery, options) {
-  if (options.agentTarget !== undefined) {
-    if (options.agentTarget === "none") {
-      return {
-        target: undefined,
-        error: "init-with-agent requires an agent target other than none."
-      };
+function resolveRegistryUrl(env = process.env) {
+  const override = env.DOCBRIDGE_REGISTRY_URL;
+  return override !== undefined && override.length > 0 ? override : NPM_REGISTRY_LATEST_URL;
+}
+async function fetchLatestStableVersion(options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const url = options.url ?? resolveRegistryUrl();
+  try {
+    const response = await fetchImpl(url, {
+      signal: AbortSignal.timeout(options.timeoutMs ?? REGISTRY_TIMEOUT_MS),
+      headers: { accept: "application/json" }
+    });
+    if (!response.ok) {
+      return;
     }
-    return { target: options.agentTarget, error: undefined };
+    return selectStableVersion(await response.json());
+  } catch {
+    return;
   }
-  if (discovery.agent.defaultTarget === "none") {
-    if (options.yes) {
-      return {
-        target: undefined,
-        error: "init-with-agent --yes requires an explicit agent target when no .agents/ or .claude/ directory exists. Pass --agent-target codex, claude, or both."
-      };
-    }
-    return { target: discovery.agent.recommendedTarget, error: undefined };
+}
+async function resolveLatestStableVersion(options = {}) {
+  const now = options.now ?? Date.now();
+  const cachePath = options.cachePath ?? resolveUpdateCachePath();
+  if (options.forceRefresh !== true) {
+    const cached = readUpdateCache(cachePath);
+    if (cached !== undefined && isUpdateCacheFresh(cached, now)) {
+      return cached.latest === null ? { status: "unavailable", source: "cache" } : { status: "ok", latest: cached.latest, source: "cache" };
+    }
+  }
+  const fetched = await fetchLatestStableVersion({
+    ...options.url !== undefined ? { url: options.url } : {},
+    ...options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {},
+    ...options.fetchImpl !== undefined ? { fetchImpl: options.fetchImpl } : {}
+  });
+  writeUpdateCache(cachePath, {
+    schema: UPDATE_CACHE_SCHEMA_VERSION,
+    checkedAt: now,
+    latest: fetched ?? null
+  });
+  return fetched === undefined ? { status: "unavailable", source: "network" } : { status: "ok", latest: fetched, source: "network" };
+}
+
+// src/setup/upgrade-guidance.ts
+import { sep as sep2 } from "node:path";
+var PACKAGE_MANAGERS = ["bun", "npm", "pnpm", "yarn"];
+var PROJECT_COMMANDS = {
+  bun: "bun add -d docbridge@latest",
+  npm: "npm install --save-dev docbridge@latest",
+  pnpm: "pnpm add -D docbridge@latest",
+  yarn: "yarn add -D docbridge@latest"
+};
+var GLOBAL_COMMANDS = {
+  bun: "bun add -g docbridge@latest",
+  npm: "npm install -g docbridge@latest",
+  pnpm: "pnpm add -g docbridge@latest",
+  yarn: "yarn global add docbridge@latest"
+};
+function detectPackageManager(env = process.env) {
+  const userAgent = env.npm_config_user_agent;
+  if (userAgent === undefined || userAgent.length === 0) {
+    return;
   }
-  return { target: discovery.agent.defaultTarget, error: undefined };
+  const name = userAgent.trim().split("/", 1)[0]?.toLowerCase();
+  return PACKAGE_MANAGERS.find((manager) => manager === name);
 }
-function readExistingConfig(projectRoot) {
-  const configPath = join5(projectRoot, CONFIG_FILE_NAME2);
-  let rawText;
-  try {
-    rawText = readFileSync3(configPath, "utf8");
-  } catch {
-    rawText = undefined;
+function detectInstallScope(packageRoot, candidateRoots) {
+  const installBase = resolveInstallBase(packageRoot);
+  if (installBase === undefined) {
+    return "unknown";
   }
-  const resolved = resolveConfig(rawText);
+  return candidateRoots.some((root) => isSameOrAncestor(installBase, root)) ? "project" : "global";
+}
+function detectUpgradeGuidance(input) {
+  const packageManager = detectPackageManager(input.env ?? process.env);
+  const scope = detectInstallScope(input.packageRoot, [
+    input.projectRoot,
+    input.currentDirectory ?? process.cwd()
+  ]);
+  const commands = scope === "global" ? GLOBAL_COMMANDS : PROJECT_COMMANDS;
+  const primaryManager = packageManager ?? "npm";
   return {
-    rawText,
-    ok: resolved.ok,
-    config: resolved.config,
-    diagnostics: resolved.diagnostics
+    packageManager,
+    scope,
+    primaryCommand: commands[primaryManager],
+    alternativeCommands: PACKAGE_MANAGERS.filter((manager) => manager !== primaryManager).map((manager) => commands[manager])
   };
 }
-function summarizeExistingConfig(config, messages) {
-  messages.push(`Docs scope: ${config.include.docs.join(", ")}`);
-  const codeSummary = Object.entries(config.include.code).map(([language, entry]) => `${language}: ${entry?.patterns.join(", ") ?? ""}`).join("; ");
-  messages.push(`Code scope: ${codeSummary}`);
+function formatUpgradeGuidance(guidance) {
+  const scopeLabel = guidance.scope === "unknown" ? "install scope not detected" : `${guidance.scope} install`;
+  return [
+    `Upgrade command (${scopeLabel}): ${guidance.primaryCommand}`,
+    `Other package managers: ${guidance.alternativeCommands.join(", ")}`
+  ];
 }
-function agentDestinations(agentTarget) {
-  switch (agentTarget) {
-    case "codex":
-      return [".agents/skills"];
-    case "claude":
-      return [".claude/skills"];
-    case "both":
-      return [".agents/skills", ".claude/skills"];
-    default:
-      return [];
+function resolveInstallBase(packageRoot) {
+  const marker = `${sep2}node_modules${sep2}`;
+  const markerIndex = withTrailingSeparator(packageRoot).indexOf(marker);
+  return markerIndex === -1 ? undefined : packageRoot.slice(0, markerIndex);
+}
+function isSameOrAncestor(candidate, descendant) {
+  return withTrailingSeparator(descendant).startsWith(withTrailingSeparator(candidate));
+}
+function withTrailingSeparator(path) {
+  return path.endsWith(sep2) ? path : `${path}${sep2}`;
+}
+
+// src/setup/update-notice.ts
+var SUPPRESSED_COMMANDS = new Set(["lsp", "upgrade"]);
+function isUpdateCheckOptedOut(env = process.env) {
+  return isEnabledFlag(env.DOCBRIDGE_NO_UPDATE_CHECK);
+}
+function decideUpdateCheck(input) {
+  const env = input.env ?? process.env;
+  if (isUpdateCheckOptedOut(env)) {
+    return { enabled: false, reason: "opt-out" };
+  }
+  if (isEnabledFlag(env.CI)) {
+    return { enabled: false, reason: "ci" };
   }
+  if (!input.isTty) {
+    return { enabled: false, reason: "non-tty" };
+  }
+  if (input.argv.includes("--json")) {
+    return { enabled: false, reason: "json-output" };
+  }
+  const command = input.argv[0];
+  if (command !== undefined && SUPPRESSED_COMMANDS.has(command)) {
+    return { enabled: false, reason: "machine-command" };
+  }
+  return { enabled: true };
 }
-function formatFileOp(operation) {
-  let label = operation.action;
-  if (operation.action === "would-create") {
-    label = "would create";
-  } else if (operation.action === "would-overwrite") {
-    label = "would overwrite";
+function formatUpdateNotice(input) {
+  if (!isNewerStableVersion(input.latest, input.current)) {
+    return;
   }
-  const reason = operation.reason ? ` (${operation.reason})` : "";
-  return `- ${label} ${operation.path}${reason}`;
+  return [
+    `Update available: docbridge ${input.current} -> ${input.latest}`,
+    formatUpgradeGuidance(input.guidance)[0] ?? "",
+    "Run `docbridge upgrade --check` for details, or set DOCBRIDGE_NO_UPDATE_CHECK=1 to silence this notice.",
+    ""
+  ].join(`
+`);
 }
-function capitalize(value) {
-  return value.charAt(0).toUpperCase() + value.slice(1);
+function isEnabledFlag(value) {
+  if (value === undefined) {
+    return false;
+  }
+  const normalized = value.trim().toLowerCase();
+  return normalized.length > 0 && normalized !== "0" && normalized !== "false";
 }
 
+// src/cli/docs.ts
+import { readdirSync as readdirSync2, readFileSync as readFileSync5 } from "node:fs";
+import { join as join8 } from "node:path";
+
 // src/cli/errors.ts
 class CliError extends Error {
   guidance;
@@ -179555,6 +180219,19 @@ function agentTargetGuidance(command) {
   ].join(`
 `);
 }
+function upgradeConfirmationGuidance() {
+  return [
+    "Confirm the migration explicitly:",
+    "",
+    "  docbridge upgrade --force --yes",
+    "",
+    "Or inspect it first:",
+    "",
+    "  docbridge upgrade --check",
+    "  docbridge upgrade --force --dry-run"
+  ].join(`
+`);
+}
 function includeContentGuidance() {
   return [
     "Use --include-content together with --json:",
@@ -179581,6 +180258,9 @@ function configSetupGuidance() {
 function configRepairGuidance() {
   return "Repair or delete docbridge.config.json, then re-run `docbridge check`.";
 }
+function manifestRepairGuidance() {
+  return "Repair or delete docbridge.links.json, then re-run `docbridge check`.";
+}
 function formatCliError(error) {
   if (!(error instanceof CliError)) {
     return error instanceof Error ? error.message : String(error);
@@ -179648,11 +180328,11 @@ function parseDocument(name, source) {
   };
 }
 function createFileDocumentationReader(packageRoot) {
-  const docsRoot = join6(packageRoot, "docs", "user");
+  const docsRoot = join8(packageRoot, "docs", "user");
   function documents() {
     let fileNames;
     try {
-      fileNames = readdirSync3(docsRoot).filter((fileName) => fileName.endsWith(".md")).toSorted();
+      fileNames = readdirSync2(docsRoot).filter((fileName) => fileName.endsWith(".md")).toSorted();
     } catch {
       throw documentationUnavailableError();
     }
@@ -179661,7 +180341,7 @@ function createFileDocumentationReader(packageRoot) {
     }
     return fileNames.map((fileName) => {
       const name = fileName.slice(0, -".md".length);
-      return parseDocument(name, readFileSync4(join6(docsRoot, fileName), "utf8"));
+      return parseDocument(name, readFileSync5(join8(docsRoot, fileName), "utf8"));
     });
   }
   return {
@@ -179732,6 +180412,7 @@ var SUBCOMMANDS = [
   "docs",
   "init",
   "init-with-agent",
+  "upgrade",
   "lsp"
 ];
 var ROOT_OPTION = {
@@ -179857,11 +180538,47 @@ var COMMAND_DOCS = {
 `),
     options: [JSON_OPTION]
   },
+  upgrade: {
+    usage: "[options]",
+    summary: "Use to check for a newer release and migrate managed skills.",
+    description: [
+      "Report DocBridge version drift and reconcile the managed agent skill.",
+      "Use it after a DocBridge release, or when a project still carries assets",
+      "from an older layout. `--check` is read-only. Applying changes touches",
+      "only the managed docbridge skill directory and the known legacy skill",
+      "directories; it never edits config, hooks, CI recipes, or user code, and",
+      "it never runs a package manager for you."
+    ].join(`
+`),
+    options: [
+      {
+        flag: "--root <path>",
+        description: "Project root to inspect. Defaults to current directory."
+      },
+      {
+        flag: "--check",
+        description: "Report version and managed asset state without writing files."
+      },
+      {
+        flag: "--dry-run",
+        description: "Print the operations that would be applied without writing files."
+      },
+      { flag: "--yes", description: "Confirm destructive operations without prompting." },
+      {
+        flag: "--force",
+        description: "Replace the managed skill and remove known legacy skill directories."
+      },
+      {
+        flag: "--agent-target <target>",
+        description: "Agent target: codex, claude, both, or none."
+      }
+    ]
+  },
   init: {
     usage: "[options]",
-    summary: "Use once per project to set up config and agent skills.",
+    summary: "Use once per project to set up config and the agent skill.",
     description: [
-      "Create docbridge.config.json and install the DocBridge agent skills.",
+      "Create docbridge.config.json and install the DocBridge agent skill.",
       "Use it once per project, when adopting DocBridge. Run it with --dry-run",
       "first to see what would be written."
     ].join(`
@@ -179878,7 +180595,7 @@ var COMMAND_DOCS = {
     usage: "[options]",
     summary: "Use to let a coding agent decide the setup instead of `init`.",
     description: [
-      "Install the docbridge-adopt skill and print the commands that let a coding",
+      "Install the docbridge skill and print the commands that let a coding",
       "agent finish the setup.",
       "Use it instead of `init` when an agent should decide the configuration",
       "rather than accepting the defaults."
@@ -179924,7 +180641,7 @@ function commandList() {
   return SUBCOMMANDS.map((command) => `  ${command.padEnd(width)}${COMMAND_DOCS[command].summary}`).join(`
 `);
 }
-var GLOBAL_OPTION_SECTIONS = ["check", "related", "context", "graph", "docs", "init"].map((command) => {
+var GLOBAL_OPTION_SECTIONS = ["check", "related", "context", "graph", "docs", "init", "upgrade"].map((command) => {
   const label = `${command.charAt(0).toUpperCase()}${command.slice(1)}`;
   return `${label} options:
 ${renderOptions(COMMAND_DOCS[command].options)}`;
@@ -180021,12 +180738,12 @@ function hasHelpFlag(args) {
 }
 
 // src/cli/init.ts
-import { cpSync, mkdirSync as mkdirSync2, readFileSync as readFileSync5, statSync as statSync3, writeFileSync } from "node:fs";
-import { join as join8, resolve as resolve3 } from "node:path";
+import { readFileSync as readFileSync8, statSync as statSync3, writeFileSync as writeFileSync2 } from "node:fs";
+import { join as join12, resolve as resolve3 } from "node:path";
 
-// src/core/init-discovery.ts
-import { existsSync as existsSync3, readdirSync as readdirSync4, statSync as statSync2 } from "node:fs";
-import { basename, dirname as dirname4, join as join7 } from "node:path";
+// src/setup/init-discovery.ts
+import { existsSync as existsSync3, readdirSync as readdirSync3, statSync as statSync2 } from "node:fs";
+import { basename, dirname as dirname5, join as join9 } from "node:path";
 var HIGH_CONFIDENCE_DIR_NAMES = new Set([
   "docs/specs",
   "specs",
@@ -180091,7 +180808,7 @@ function discoverDocsScope(projectRoot) {
   }
   const grouped = new Map;
   for (const filePath of eligible) {
-    const directory = dirname4(filePath);
+    const directory = dirname5(filePath);
     const existing = grouped.get(directory) ?? [];
     existing.push(filePath);
     grouped.set(directory, existing);
@@ -180153,8 +180870,8 @@ function discoverCodeScope(projectRoot) {
   };
 }
 function discoverAgentTarget(projectRoot) {
-  const hasAgentsDir = existsSync3(join7(projectRoot, ".agents"));
-  const hasClaudeDir = existsSync3(join7(projectRoot, ".claude"));
+  const hasAgentsDir = existsSync3(join9(projectRoot, ".agents"));
+  const hasClaudeDir = existsSync3(join9(projectRoot, ".claude"));
   let defaultTarget = "none";
   let recommendedTarget = "none";
   let message;
@@ -180181,10 +180898,10 @@ function discoverAgentTarget(projectRoot) {
   };
 }
 function collectMarkdownFiles(projectRoot, currentDir = ".") {
-  const absoluteDir = join7(projectRoot, currentDir);
+  const absoluteDir = join9(projectRoot, currentDir);
   let entries;
   try {
-    entries = readdirSync4(absoluteDir);
+    entries = readdirSync3(absoluteDir);
   } catch {
     return [];
   }
@@ -180195,7 +180912,7 @@ function collectMarkdownFiles(projectRoot, currentDir = ".") {
     if (segments.some((segment) => IGNORED_WALK_SEGMENTS.has(segment) || segment.startsWith("."))) {
       continue;
     }
-    const absolutePath = join7(projectRoot, relPath);
+    const absolutePath = join9(projectRoot, relPath);
     let stats;
     try {
       stats = statSync2(absolutePath);
@@ -180282,6 +180999,491 @@ function isExcludedCodeFile(filePath, language) {
   return lower.includes(".generated.");
 }
 
+// src/setup/init-plan.ts
+import { existsSync as existsSync4, readdirSync as readdirSync5, readFileSync as readFileSync7 } from "node:fs";
+import { join as join11, relative as relative3 } from "node:path";
+
+// src/setup/skill-assets.ts
+import { cpSync, lstatSync as lstatSync2, mkdirSync as mkdirSync3, readdirSync as readdirSync4, readFileSync as readFileSync6, rmSync } from "node:fs";
+import { join as join10 } from "node:path";
+function classifyManagedPath(projectRoot, relativePath) {
+  const segments = relativePath.split(/[/\\]/).filter((segment) => segment.length > 0);
+  let current = projectRoot;
+  for (const [index, segment] of segments.entries()) {
+    current = join10(current, segment);
+    const isLast = index === segments.length - 1;
+    let stats;
+    try {
+      stats = lstatSync2(current);
+    } catch {
+      return "absent";
+    }
+    if (stats.isSymbolicLink()) {
+      return isLast ? "symlink" : "symlinked-parent";
+    }
+    if (!stats.isDirectory()) {
+      return isLast ? "non-directory" : "blocked-parent";
+    }
+  }
+  return segments.length === 0 ? "blocked-parent" : "directory";
+}
+function unmanageablePathMessage(path, kind) {
+  switch (kind) {
+    case "symlink":
+      return `Skill directory ${path} is a symlink and was left in place.`;
+    case "symlinked-parent":
+      return `Skill directory ${path} sits under a symlinked directory and was left in place, because writing through it would leave the project root.`;
+    case "non-directory":
+      return `${path} exists but is not a directory, so it was left in place.`;
+    case "blocked-parent":
+      return `Skill directory ${path} cannot be reached because a parent path component is not a directory, so it was left in place.`;
+    default:
+      return `Skill directory ${path} was left in place.`;
+  }
+}
+function listSkillFiles(directory) {
+  const files = [];
+  collectSkillFiles(directory, "", files);
+  return files.toSorted();
+}
+function compareSkillTree(installedDir, templateDir) {
+  const installedFiles = new Set(listSkillFiles(installedDir));
+  const templateFiles = listSkillFiles(templateDir);
+  const modified = [];
+  const missing = [];
+  for (const file of templateFiles) {
+    if (!installedFiles.has(file)) {
+      missing.push(file);
+      continue;
+    }
+    installedFiles.delete(file);
+    if (readFileOrUndefined(join10(installedDir, file)) !== readFileOrUndefined(join10(templateDir, file))) {
+      modified.push(file);
+    }
+  }
+  return { modified, missing, extra: [...installedFiles].toSorted() };
+}
+function applySkillOperation(projectRoot, packageRoot, operation) {
+  if (operation.action !== "create" && operation.action !== "overwrite" && operation.action !== "remove") {
+    return;
+  }
+  const kind = classifyManagedPath(projectRoot, operation.path);
+  const destinationDir = join10(projectRoot, operation.path);
+  if (operation.action === "remove") {
+    if (kind === "directory") {
+      rmSync(destinationDir, { recursive: true, force: true });
+    }
+    return;
+  }
+  if (kind !== "absent" && kind !== "directory") {
+    return;
+  }
+  const skillName = operation.path.split(/[/\\]/).at(-1);
+  if (skillName === undefined || skillName.length === 0) {
+    return;
+  }
+  if (operation.action === "overwrite" && kind === "directory") {
+    rmSync(destinationDir, { recursive: true, force: true });
+  }
+  mkdirSync3(destinationDir, { recursive: true });
+  cpSync(join10(packageRoot, "templates", "skills", skillName), destinationDir, {
+    recursive: true,
+    force: true
+  });
+}
+function collectSkillFiles(root, prefix, files) {
+  let entries;
+  try {
+    entries = readdirSync4(join10(root, prefix), { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries.toSorted((left, right) => left.name < right.name ? -1 : 1)) {
+    const relativePath = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+    if (entry.isDirectory()) {
+      collectSkillFiles(root, relativePath, files);
+      continue;
+    }
+    files.push(relativePath);
+  }
+}
+function readFileOrUndefined(path) {
+  try {
+    return readFileSync6(path, "utf8");
+  } catch {
+    return;
+  }
+}
+
+// src/setup/init-plan.ts
+var CONFIG_FILE_NAME2 = "docbridge.config.json";
+var INIT_SKILL_NAMES = ["docbridge"];
+var LEGACY_SKILL_NAMES = [
+  "docbridge-adopt",
+  "docbridge-annotate",
+  "docbridge-link",
+  "docbridge-review",
+  "docbridge-sync"
+];
+function planInitCommand(input) {
+  const packageRoot = input.packageRoot ?? resolvePackageRoot();
+  const existingConfig = readExistingConfig(input.projectRoot);
+  const messages = [];
+  const nextSteps = [];
+  let exitCode = 0;
+  const agentResolution = input.command === "init" ? resolveInitAgentTarget(input.discovery, input.options) : resolveInitWithAgentTarget(input.discovery, input.options);
+  if (agentResolution.error !== undefined) {
+    return {
+      command: input.command,
+      configOps: [],
+      skillOps: [],
+      messages: [agentResolution.error],
+      nextSteps: [],
+      agentGuidance: [],
+      exitCode: 1
+    };
+  }
+  const agentTarget = agentResolution.target ?? "none";
+  const configOps = input.command === "init" ? planConfigOperations({
+    projectRoot: input.projectRoot,
+    options: input.options,
+    discovery: input.discovery,
+    confirmedScope: input.confirmedScope,
+    existingConfig,
+    messages
+  }) : [];
+  if (configOps.some((operation) => operation.action === "create" || operation.action === "would-create")) {
+    nextSteps.push("Review docbridge.config.json and adjust include.docs or include.code if needed.");
+    nextSteps.push("Add @doc and @code annotations to link code and documentation.");
+    nextSteps.push("Run docbridge check when links exist.");
+  } else if (existingConfig.ok) {
+    messages.push("Existing docbridge.config.json was left unchanged.");
+    summarizeExistingConfig(existingConfig.config, messages);
+  } else if (existingConfig.rawText !== undefined) {
+    messages.push("Existing docbridge.config.json is invalid and was not modified.");
+    for (const diagnostic of existingConfig.diagnostics) {
+      messages.push(diagnostic.message);
+    }
+    messages.push("Repair the config manually or delete it before re-running init.");
+    exitCode = 1;
+  }
+  const skillOps = planSkillOperations({
+    projectRoot: input.projectRoot,
+    packageRoot,
+    agentTarget,
+    options: input.options,
+    messages
+  });
+  const agentGuidance = input.command === "init-with-agent" && agentTarget !== "none" ? buildAgentGuidance(input.projectRoot, agentTarget) : [];
+  if (input.command === "init-with-agent") {
+    nextSteps.push("Run the printed one-shot command or fallback prompt in your agent.");
+    nextSteps.push("Let the docbridge skill confirm scope and create or improve docbridge.config.json.");
+  }
+  if (input.options.yes && input.command === "init" && configOps.length === 0 && existingConfig.rawText === undefined && (input.discovery.docs.ambiguous || input.discovery.code.ambiguous)) {
+    exitCode = 1;
+  }
+  return {
+    command: input.command,
+    configOps,
+    skillOps,
+    messages,
+    nextSteps,
+    agentGuidance,
+    exitCode
+  };
+}
+function buildConfigFromScope(scope) {
+  const code = {};
+  for (const language of scope.languages) {
+    code[language.language] = { patterns: [...language.patterns] };
+  }
+  return {
+    include: {
+      code,
+      docs: [scope.docsPattern]
+    }
+  };
+}
+function listDistributableSkills(packageRoot) {
+  const skillsRoot = join11(packageRoot, "templates", "skills");
+  let entries;
+  try {
+    entries = readdirSync5(skillsRoot);
+  } catch {
+    return [];
+  }
+  return entries.filter((entry) => entry.startsWith("docbridge")).filter((entry) => existsSync4(join11(skillsRoot, entry, "SKILL.md"))).toSorted();
+}
+function formatInitPlan(plan) {
+  const lines = [];
+  for (const message of plan.messages) {
+    lines.push(message);
+  }
+  if (plan.configOps.length > 0) {
+    lines.push("");
+    lines.push("Config:");
+    for (const operation of plan.configOps) {
+      lines.push(formatFileOp(operation));
+      if (operation.content !== undefined) {
+        lines.push(operation.content);
+      }
+    }
+  }
+  if (plan.skillOps.length > 0) {
+    lines.push("");
+    lines.push("Skills:");
+    for (const operation of plan.skillOps) {
+      lines.push(formatFileOp(operation));
+    }
+  }
+  if (plan.agentGuidance.length > 0) {
+    lines.push("");
+    lines.push("Agent setup:");
+    for (const guidance of plan.agentGuidance) {
+      lines.push("");
+      lines.push(`${capitalize(guidance.agent)} destination: ${guidance.destination}`);
+      lines.push(`One-shot command: ${guidance.oneShotCommand}`);
+      lines.push("Fallback prompt:");
+      lines.push(guidance.fallbackPrompt);
+    }
+  }
+  if (plan.nextSteps.length > 0) {
+    lines.push("");
+    lines.push("Next steps:");
+    for (const step of plan.nextSteps) {
+      lines.push(`- ${step}`);
+    }
+  }
+  return `${lines.join(`
+`)}
+`;
+}
+function planConfigOperations(input) {
+  if (input.existingConfig.rawText !== undefined) {
+    return [];
+  }
+  const scope = input.confirmedScope ?? inferConfirmedScope(input.discovery, input.options);
+  if (scope === undefined) {
+    if (input.discovery.docs.message !== undefined) {
+      input.messages.push(input.discovery.docs.message);
+    }
+    if (input.discovery.code.message !== undefined) {
+      input.messages.push(input.discovery.code.message);
+    }
+    if (input.options.yes) {
+      input.messages.push("Automatic setup stopped because docs or code scope is ambiguous. Re-run interactively or confirm scope explicitly.");
+    }
+    return [];
+  }
+  const config = buildConfigFromScope(scope);
+  const content = `${JSON.stringify({ $schema: "./schemas/docbridge.schema.json", ...config }, null, 2)}
+`;
+  const action = input.options.dryRun ? "would-create" : "create";
+  input.messages.push(`Docs scope: ${scope.docsPattern}`);
+  input.messages.push(`Code scope: ${scope.languages.map((language) => `${language.language} (${language.patterns.join(", ")})`).join("; ")}`);
+  return [
+    {
+      action,
+      path: CONFIG_FILE_NAME2,
+      content,
+      reason: "Create docbridge.config.json from discovered scope."
+    }
+  ];
+}
+function inferConfirmedScope(discovery, options) {
+  if (discovery.docs.ambiguous || discovery.code.ambiguous) {
+    return;
+  }
+  if (discovery.docs.recommended === undefined || discovery.code.languages.length === 0) {
+    return;
+  }
+  if (!options.yes) {
+    return;
+  }
+  return {
+    docsPattern: discovery.docs.recommended.pattern,
+    languages: discovery.code.languages
+  };
+}
+function planSkillOperations(input) {
+  if (input.agentTarget === "none") {
+    return [];
+  }
+  const destinations = agentDestinations(input.agentTarget);
+  const availableSkills = new Set(listDistributableSkills(input.packageRoot));
+  const operations = [];
+  for (const destination of destinations) {
+    for (const skillName of INIT_SKILL_NAMES) {
+      if (!availableSkills.has(skillName)) {
+        continue;
+      }
+      const destinationDir = join11(input.projectRoot, destination, skillName);
+      const path = relative3(input.projectRoot, destinationDir);
+      const kind = classifyManagedPath(input.projectRoot, path);
+      if (kind !== "absent" && kind !== "directory") {
+        input.messages.push(unmanageablePathMessage(path, kind));
+        continue;
+      }
+      const exists = kind === "directory";
+      let action;
+      let reason;
+      if (exists && input.options.force) {
+        action = input.options.dryRun ? "would-overwrite" : "overwrite";
+        reason = "Overwrite existing skill directory.";
+      } else if (exists) {
+        action = "skip";
+        reason = "Skill directory already exists.";
+      } else {
+        action = input.options.dryRun ? "would-create" : "create";
+        reason = "Install distributable skill template.";
+      }
+      operations.push({
+        action,
+        path,
+        reason
+      });
+    }
+    operations.push(...planLegacySkillOperations({
+      projectRoot: input.projectRoot,
+      destination,
+      options: input.options,
+      messages: input.messages
+    }));
+  }
+  return operations;
+}
+function planLegacySkillOperations(input) {
+  const operations = [];
+  const leftover = [];
+  for (const skillName of LEGACY_SKILL_NAMES) {
+    const destinationDir = join11(input.projectRoot, input.destination, skillName);
+    const path = relative3(input.projectRoot, destinationDir);
+    const kind = classifyManagedPath(input.projectRoot, path);
+    if (kind === "absent") {
+      continue;
+    }
+    if (kind !== "directory") {
+      input.messages.push(unmanageablePathMessage(path, kind));
+      continue;
+    }
+    if (input.options.force) {
+      operations.push({
+        action: input.options.dryRun ? "would-remove" : "remove",
+        path,
+        reason: "Remove leftover skill from the previous five-skill layout."
+      });
+    } else {
+      leftover.push(path);
+    }
+  }
+  if (leftover.length > 0) {
+    input.messages.push(`Legacy DocBridge skill directories were left in place (${leftover.join(", ")}). Re-run with --force to remove them after reviewing local edits.`);
+  }
+  return operations;
+}
+function buildAgentGuidance(projectRoot, agentTarget) {
+  const guidance = [];
+  if (agentTarget === "codex" || agentTarget === "both") {
+    guidance.push({
+      agent: "codex",
+      destination: ".agents/skills/docbridge/",
+      oneShotCommand: `cd ${projectRoot} && codex --prompt "Use the docbridge skill to adopt DocBridge in this repository."`,
+      fallbackPrompt: buildFallbackPrompt(projectRoot, "codex")
+    });
+  }
+  if (agentTarget === "claude" || agentTarget === "both") {
+    guidance.push({
+      agent: "claude",
+      destination: ".claude/skills/docbridge/",
+      oneShotCommand: `cd ${projectRoot} && /docbridge adopt DocBridge in this repository`,
+      fallbackPrompt: buildFallbackPrompt(projectRoot, "claude")
+    });
+  }
+  return guidance;
+}
+function buildFallbackPrompt(projectRoot, agent) {
+  const invocation = agent === "claude" ? "Use the docbridge skill" : "Use the docbridge skill from .agents/skills/docbridge";
+  return `${invocation} to adopt DocBridge in ${projectRoot}. Confirm docs and code scope, create or improve docbridge.config.json, and suggest the next linking steps.`;
+}
+function resolveInitAgentTarget(discovery, options) {
+  if (options.agentTarget !== undefined) {
+    return { target: options.agentTarget, error: undefined };
+  }
+  if (options.yes) {
+    return { target: discovery.agent.defaultTarget, error: undefined };
+  }
+  return { target: discovery.agent.recommendedTarget, error: undefined };
+}
+function resolveInitWithAgentTarget(discovery, options) {
+  if (options.agentTarget !== undefined) {
+    if (options.agentTarget === "none") {
+      return {
+        target: undefined,
+        error: "init-with-agent requires an agent target other than none."
+      };
+    }
+    return { target: options.agentTarget, error: undefined };
+  }
+  if (discovery.agent.defaultTarget === "none") {
+    if (options.yes) {
+      return {
+        target: undefined,
+        error: "init-with-agent --yes requires an explicit agent target when no .agents/ or .claude/ directory exists. Pass --agent-target codex, claude, or both."
+      };
+    }
+    return { target: discovery.agent.recommendedTarget, error: undefined };
+  }
+  return { target: discovery.agent.defaultTarget, error: undefined };
+}
+function readExistingConfig(projectRoot) {
+  const configPath = join11(projectRoot, CONFIG_FILE_NAME2);
+  let rawText;
+  try {
+    rawText = readFileSync7(configPath, "utf8");
+  } catch {
+    rawText = undefined;
+  }
+  const resolved = resolveConfig(rawText);
+  return {
+    rawText,
+    ok: resolved.ok,
+    config: resolved.config,
+    diagnostics: resolved.diagnostics
+  };
+}
+function summarizeExistingConfig(config, messages) {
+  messages.push(`Docs scope: ${config.include.docs.join(", ")}`);
+  const codeSummary = Object.entries(config.include.code).map(([language, entry]) => `${language}: ${entry?.patterns.join(", ") ?? ""}`).join("; ");
+  messages.push(`Code scope: ${codeSummary}`);
+}
+function agentDestinations(agentTarget) {
+  switch (agentTarget) {
+    case "codex":
+      return [".agents/skills"];
+    case "claude":
+      return [".claude/skills"];
+    case "both":
+      return [".agents/skills", ".claude/skills"];
+    default:
+      return [];
+  }
+}
+function formatFileOp(operation) {
+  let label = operation.action;
+  if (operation.action === "would-create") {
+    label = "would create";
+  } else if (operation.action === "would-overwrite") {
+    label = "would overwrite";
+  } else if (operation.action === "would-remove") {
+    label = "would remove";
+  }
+  const reason = operation.reason ? ` (${operation.reason})` : "";
+  return `- ${label} ${operation.path}${reason}`;
+}
+function capitalize(value) {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
 // src/cli/init.ts
 var AGENT_TARGETS = new Set(["codex", "claude", "both", "none"]);
 function parseInitOptions(args, command) {
@@ -180348,7 +181550,7 @@ function createDefaultPrompts(isInteractive = process.stdin.isTTY) {
         return defaultValue;
       }
       process.stdout.write(`${message} ${defaultValue ? "[Y/n]" : "[y/N]"} `);
-      const answer = readFileSync5(0, "utf8").trim().toLowerCase();
+      const answer = readFileSync8(0, "utf8").trim().toLowerCase();
       if (answer.length === 0) {
         return defaultValue;
       }
@@ -180365,7 +181567,7 @@ function createDefaultPrompts(isInteractive = process.stdin.isTTY) {
 `);
       }
       process.stdout.write(`Choice [${defaultChoice}]: `);
-      const answer = readFileSync5(0, "utf8").trim();
+      const answer = readFileSync8(0, "utf8").trim();
       if (answer.length === 0) {
         return defaultChoice;
       }
@@ -180481,30 +181683,17 @@ function executePlan(projectRoot, plan, packageRoot) {
     if (operation.action === "skip") {
       continue;
     }
-    executeSkillOperation(projectRoot, packageRoot, operation);
+    applySkillOperation(projectRoot, packageRoot, operation);
   }
 }
 function executeFileOperation(projectRoot, operation) {
-  const absolutePath = join8(projectRoot, operation.path);
+  const absolutePath = join12(projectRoot, operation.path);
   if (operation.action === "create" && operation.content !== undefined) {
-    writeFileSync(absolutePath, operation.content, "utf8");
+    writeFileSync2(absolutePath, operation.content, "utf8");
   }
   if (operation.action === "overwrite" && operation.content !== undefined) {
-    writeFileSync(absolutePath, operation.content, "utf8");
-  }
-}
-function executeSkillOperation(projectRoot, packageRoot, operation) {
-  if (operation.action !== "create" && operation.action !== "overwrite") {
-    return;
-  }
-  const skillName = operation.path.split("/").at(-1);
-  if (skillName === undefined) {
-    return;
+    writeFileSync2(absolutePath, operation.content, "utf8");
   }
-  const sourceDir = join8(packageRoot, "templates", "skills", skillName);
-  const destinationDir = join8(projectRoot, operation.path);
-  mkdirSync2(destinationDir, { recursive: true });
-  cpSync(sourceDir, destinationDir, { recursive: true, force: true });
 }
 function resolveProjectRoot(root, command) {
   const projectRoot = resolve3(root);
@@ -180520,6 +181709,343 @@ function resolveProjectRoot(root, command) {
   return projectRoot;
 }
 
+// src/cli/upgrade.ts
+import { statSync as statSync4 } from "node:fs";
+import { resolve as resolve4 } from "node:path";
+
+// src/setup/upgrade-plan.ts
+import { existsSync as existsSync5 } from "node:fs";
+import { join as join13, relative as relative4 } from "node:path";
+var MANAGED_SKILL_NAME = INIT_SKILL_NAMES[0];
+function reportCliVersion(currentVersion, latest) {
+  if (latest.status !== "ok") {
+    return { current: currentVersion, latest: undefined, status: "unknown" };
+  }
+  if (isNewerStableVersion(latest.latest, currentVersion)) {
+    return { current: currentVersion, latest: latest.latest, status: "outdated" };
+  }
+  if (isNewerStableVersion(currentVersion, latest.latest)) {
+    return { current: currentVersion, latest: latest.latest, status: "ahead" };
+  }
+  return { current: currentVersion, latest: latest.latest, status: "up-to-date" };
+}
+function resolveUpgradeAgentTarget(discovery, explicitTarget) {
+  return explicitTarget ?? discovery.agent.defaultTarget;
+}
+function inspectManagedSkill(input) {
+  const destinationDir = join13(input.projectRoot, input.destination, MANAGED_SKILL_NAME);
+  const path = toRootRelative(input.projectRoot, destinationDir);
+  const empty = {
+    destination: input.destination,
+    path,
+    modifiedFiles: [],
+    missingFiles: [],
+    extraFiles: []
+  };
+  const kind = classifyManagedPath(input.projectRoot, path);
+  if (kind !== "directory") {
+    return { ...empty, state: kind };
+  }
+  if (!input.templateAvailable) {
+    return { ...empty, state: "template-missing" };
+  }
+  const comparison = compareSkillTree(destinationDir, join13(input.packageRoot, "templates", "skills", MANAGED_SKILL_NAME));
+  const drifted = comparison.modified.length > 0 || comparison.missing.length > 0 || comparison.extra.length > 0;
+  return {
+    destination: input.destination,
+    path,
+    state: drifted ? "modified" : "up-to-date",
+    modifiedFiles: comparison.modified,
+    missingFiles: comparison.missing,
+    extraFiles: comparison.extra
+  };
+}
+function inspectLegacySkills(projectRoot, destination) {
+  const reports = [];
+  for (const skillName of LEGACY_SKILL_NAMES) {
+    const destinationDir = join13(projectRoot, destination, skillName);
+    const path = toRootRelative(projectRoot, destinationDir);
+    const kind = classifyManagedPath(projectRoot, path);
+    if (kind === "absent") {
+      continue;
+    }
+    if (kind === "symlinked-parent" && !existsSync5(destinationDir)) {
+      continue;
+    }
+    reports.push({ path, kind });
+  }
+  return reports;
+}
+function planUpgrade(input) {
+  const mode = input.options.check ? "check" : "apply";
+  const cli = reportCliVersion(input.currentVersion, input.latest);
+  const agentTarget = resolveUpgradeAgentTarget(input.discovery, input.options.agentTarget);
+  const templateAvailable = listDistributableSkills(input.packageRoot).includes(MANAGED_SKILL_NAME);
+  const messages = [];
+  const destinations = agentDestinations(agentTarget);
+  const managedSkills = destinations.map((destination) => inspectManagedSkill({
+    projectRoot: input.projectRoot,
+    packageRoot: input.packageRoot,
+    destination,
+    templateAvailable
+  }));
+  const legacySkills = destinations.flatMap((destination) => inspectLegacySkills(input.projectRoot, destination));
+  if (destinations.length === 0) {
+    messages.push("No agent skill directory was selected, so no managed assets were inspected. Pass --agent-target codex, claude, or both to reconcile them.");
+  }
+  if (!templateAvailable && destinations.length > 0) {
+    messages.push("The installed DocBridge package ships no docbridge skill template, so managed skills cannot be reconciled. Reinstall DocBridge.");
+  }
+  addVersionMessages(cli, input.guidance, messages);
+  const pending = [];
+  const operations = mode === "check" ? [] : planOperations({ managedSkills, legacySkills, options: input.options, pending });
+  for (const report of managedSkills) {
+    if (isUnmanageableState(report.state)) {
+      messages.push(unmanageablePathMessage(report.path, report.state));
+    }
+  }
+  for (const legacy of legacySkills) {
+    if (legacy.kind !== "directory") {
+      messages.push(unmanageablePathMessage(legacy.path, legacy.kind));
+    }
+  }
+  return {
+    mode,
+    cli,
+    guidance: input.guidance,
+    managedSkills,
+    legacySkills,
+    operations,
+    pending,
+    messages,
+    nextSteps: buildNextSteps({ mode, cli, options: input.options, pending }),
+    requiresConfirmation: mode === "apply" && !input.options.dryRun && !input.options.yes && operations.some((operation) => operation.action === "overwrite" || operation.action === "remove"),
+    exitCode: 0
+  };
+}
+function planOperations(input) {
+  const operations = [];
+  for (const report of input.managedSkills) {
+    if (report.state === "template-missing" || isUnmanageableState(report.state)) {
+      continue;
+    }
+    if (report.state === "absent") {
+      operations.push({
+        action: input.options.dryRun ? "would-create" : "create",
+        path: report.path,
+        reason: "Install the managed docbridge skill."
+      });
+      continue;
+    }
+    if (!input.options.force) {
+      input.pending.push(`${report.path} is ${report.state === "modified" ? "locally modified" : "already installed"} and was preserved. Re-run with --force to replace it with the packaged template.`);
+      continue;
+    }
+    operations.push({
+      action: input.options.dryRun ? "would-overwrite" : "overwrite",
+      path: report.path,
+      reason: "Replace the managed docbridge skill with the packaged template."
+    });
+  }
+  for (const legacy of input.legacySkills) {
+    if (legacy.kind !== "directory") {
+      continue;
+    }
+    if (!input.options.force) {
+      input.pending.push(`${legacy.path} is a leftover directory from the previous five-skill layout. Re-run with --force to remove it after reviewing local edits.`);
+      continue;
+    }
+    operations.push({
+      action: input.options.dryRun ? "would-remove" : "remove",
+      path: legacy.path,
+      reason: "Remove leftover skill from the previous five-skill layout."
+    });
+  }
+  return operations;
+}
+function isUnmanageableState(state) {
+  return state === "symlink" || state === "symlinked-parent" || state === "non-directory" || state === "blocked-parent";
+}
+function addVersionMessages(cli, guidance, messages) {
+  if (cli.status === "outdated") {
+    messages.push(`The running binary is older than the latest stable release. DocBridge does not upgrade itself: run \`${guidance.primaryCommand}\`, then re-run \`docbridge upgrade\` so managed assets are reconciled from the new binary.`);
+    return;
+  }
+  if (cli.status === "unknown") {
+    messages.push("The latest stable version could not be determined, so only local asset state is reported.");
+  }
+}
+function buildNextSteps(input) {
+  const nextSteps = [];
+  if (input.cli.status === "outdated") {
+    nextSteps.push("Upgrade the CLI with the command above, then re-run `docbridge upgrade`.");
+  }
+  if (input.mode === "check") {
+    nextSteps.push("Run `docbridge upgrade --dry-run` to see the operations that would be applied.");
+  }
+  if (input.pending.length > 0) {
+    nextSteps.push("Re-run with --force to apply the pending migrations listed above.");
+  }
+  if (input.mode === "apply" && input.options.dryRun) {
+    nextSteps.push("Re-run without --dry-run to apply the plan.");
+  }
+  return nextSteps;
+}
+function formatUpgradePlan(plan) {
+  const lines = [
+    `DocBridge ${plan.cli.current} (latest stable: ${plan.cli.latest ?? "unknown"})`,
+    `Status: ${plan.cli.status}`,
+    ...formatUpgradeGuidance(plan.guidance)
+  ];
+  if (plan.messages.length > 0) {
+    lines.push("", ...plan.messages);
+  }
+  appendSection(lines, "Managed skills:", plan.managedSkills.flatMap(formatManagedSkill));
+  appendSection(lines, "Legacy skills:", plan.legacySkills.map((legacy) => `- ${legacy.path} (${legacy.kind})`));
+  appendSection(lines, "Operations:", plan.operations.map((operation) => formatFileOp(operation)));
+  appendSection(lines, "Pending migration:", plan.pending.map((entry) => `- ${entry}`));
+  appendSection(lines, "Next steps:", plan.nextSteps.map((step) => `- ${step}`));
+  return `${lines.join(`
+`)}
+`;
+}
+function formatManagedSkill(report) {
+  const lines = [`- ${report.path}: ${report.state}`];
+  appendFileList(lines, "changed", report.modifiedFiles);
+  appendFileList(lines, "missing", report.missingFiles);
+  appendFileList(lines, "extra", report.extraFiles);
+  return lines;
+}
+function appendFileList(lines, label, files) {
+  if (files.length > 0) {
+    lines.push(`    ${label}: ${files.join(", ")}`);
+  }
+}
+function appendSection(lines, heading, entries) {
+  if (entries.length === 0) {
+    return;
+  }
+  lines.push("", heading, ...entries);
+}
+function toRootRelative(projectRoot, absolutePath) {
+  return relative4(projectRoot, absolutePath).split("\\").join("/");
+}
+
+// src/cli/upgrade.ts
+var AGENT_TARGETS2 = new Set(["codex", "claude", "both", "none"]);
+function parseUpgradeOptions(args) {
+  const options = {
+    root: ".",
+    agentTarget: undefined,
+    check: false,
+    dryRun: false,
+    yes: false,
+    force: false
+  };
+  for (let index = 0;index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === undefined) {
+      continue;
+    }
+    if (arg === "--check") {
+      options.check = true;
+      continue;
+    }
+    if (arg === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+    if (arg === "--yes") {
+      options.yes = true;
+      continue;
+    }
+    if (arg === "--force") {
+      options.force = true;
+      continue;
+    }
+    if (arg === "--root") {
+      const root = args[index + 1];
+      if (root === undefined) {
+        throw new CliError("--root requires a path.", rootPathGuidance("upgrade"));
+      }
+      options.root = root;
+      index += 1;
+      continue;
+    }
+    if (arg === "--agent-target") {
+      options.agentTarget = parseAgentTarget(args[index + 1]);
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      throw new CliError(`Unknown option: ${arg}`, commandHelpGuidance("upgrade"));
+    }
+    throw new CliError(`Unexpected argument: ${arg}`, commandHelpGuidance("upgrade"));
+  }
+  return options;
+}
+function runUpgrade(options, io, initRuntime, runtime) {
+  const projectRoot = resolveProjectRoot2(options.root);
+  const packageRoot = initRuntime.packageRoot ?? resolvePackageRoot();
+  const plan = planUpgrade({
+    projectRoot,
+    packageRoot,
+    currentVersion: runtime.currentVersion,
+    latest: runtime.latest,
+    guidance: detectUpgradeGuidance({
+      packageRoot,
+      projectRoot,
+      ...runtime.currentDirectory !== undefined ? { currentDirectory: runtime.currentDirectory } : {},
+      ...runtime.env !== undefined ? { env: runtime.env } : {}
+    }),
+    discovery: discoverRepository(projectRoot),
+    options
+  });
+  if (plan.mode === "check" || options.dryRun) {
+    io.stdout(formatUpgradePlan(plan));
+    return plan.exitCode;
+  }
+  return applyUpgrade(projectRoot, packageRoot, plan, io, initRuntime);
+}
+function applyUpgrade(projectRoot, packageRoot, plan, io, initRuntime) {
+  if (plan.requiresConfirmation && !initRuntime.prompts.isInteractive) {
+    throw new CliError("Replacing or removing managed skill directories requires confirmation.", upgradeConfirmationGuidance());
+  }
+  if (plan.requiresConfirmation && !initRuntime.prompts.confirm(`Apply ${plan.operations.length} operation(s) to managed skill directories?`, false)) {
+    io.stdout(formatUpgradePlan(plan));
+    io.stdout(`No changes were applied.
+`);
+    return 0;
+  }
+  for (const operation of plan.operations) {
+    applySkillOperation(projectRoot, packageRoot, operation);
+  }
+  io.stdout(formatUpgradePlan(plan));
+  return plan.exitCode;
+}
+function parseAgentTarget(value) {
+  if (value === undefined) {
+    throw new CliError("--agent-target requires a value.", agentTargetGuidance("upgrade"));
+  }
+  if (!AGENT_TARGETS2.has(value)) {
+    throw new CliError(`Unknown agent target: ${value}. Supported values: codex, claude, both, none.`, agentTargetGuidance("upgrade"));
+  }
+  return value;
+}
+function resolveProjectRoot2(root) {
+  const projectRoot = resolve4(root);
+  let stats;
+  try {
+    stats = statSync4(projectRoot);
+  } catch {
+    throw new CliError(`Root path does not exist: ${root}`, rootPathGuidance("upgrade"));
+  }
+  if (!stats.isDirectory()) {
+    throw new CliError(`Root path is not a directory: ${root}`, rootPathGuidance("upgrade"));
+  }
+  return projectRoot;
+}
+
 // src/cli/index.ts
 var VERSION = package_default.version;
 function parseCheckOptions(args) {
@@ -180534,11 +182060,11 @@ function parseContextOptions(args) {
 function parseGraphOptions(args) {
   return parseCommandOptions("graph", args);
 }
-function resolveProjectRoot2(root, command) {
-  const projectRoot = resolve4(root);
+function resolveProjectRoot3(root, command) {
+  const projectRoot = resolve5(root);
   let stats;
   try {
-    stats = statSync4(projectRoot);
+    stats = statSync5(projectRoot);
   } catch {
     throw new CliError(`Root path does not exist: ${root}`, rootPathGuidance(command));
   }
@@ -180548,7 +182074,7 @@ function resolveProjectRoot2(root, command) {
   return projectRoot;
 }
 function runCheck(options, io) {
-  const projectRoot = resolveProjectRoot2(options.root, "check");
+  const projectRoot = resolveProjectRoot3(options.root, "check");
   const result = check({ projectRoot, audit: options.audit });
   if (options.json) {
     io.stdout(`${JSON.stringify(result, null, 2)}
@@ -180560,9 +182086,10 @@ function runCheck(options, io) {
 
 ` : "";
     io.stdout(`${body}${formatSummary(result.summary)}
+See \`docbridge docs show troubleshooting\` for diagnostic codes and fixes.
 `);
-    if (result.diagnostics.some((diagnostic) => diagnostic.code === "config_file_invalid")) {
-      const guidance = existsSync4(join9(projectRoot, CONFIG_FILE_NAME)) ? configRepairGuidance() : configSetupGuidance();
+    const guidance = repairGuidanceFor(result.diagnostics, projectRoot);
+    if (guidance !== undefined) {
       io.stderr(`${guidance}
 `);
     }
@@ -180570,10 +182097,10 @@ function runCheck(options, io) {
   return result.summary.errors > 0 ? 1 : 0;
 }
 function runFileCommand(command, options, io, execute, render) {
-  const projectRoot = resolveProjectRoot2(options.root, command);
+  const projectRoot = resolveProjectRoot3(options.root, command);
   const inputFiles = [...options.files];
   if (options.stdin) {
-    const readStdin = io.stdin ?? (() => readFileSync6(0, "utf8"));
+    const readStdin = io.stdin ?? (() => readFileSync9(0, "utf8"));
     inputFiles.push(...readStdin().split(`
 `));
   }
@@ -180653,8 +182180,18 @@ function runGraph(options, io) {
     return 0;
   });
 }
+function repairGuidanceFor(diagnostics, projectRoot) {
+  const invalid = diagnostics.filter((diagnostic) => diagnostic.code === "config_file_invalid");
+  if (invalid.some((diagnostic) => diagnostic.target === LINK_MANIFEST_FILE_NAME)) {
+    return manifestRepairGuidance();
+  }
+  if (invalid.length === 0) {
+    return;
+  }
+  return existsSync6(join14(projectRoot, CONFIG_FILE_NAME)) ? configRepairGuidance() : configSetupGuidance();
+}
 function unknownCommandGuidance(command) {
-  const suggestion = nearestSubcommand(command);
+  const suggestion = nearestMatch(command, SUBCOMMANDS);
   const lines = ["Available commands:", `  ${SUBCOMMANDS.join(", ")}`];
   if (suggestion !== undefined) {
     lines.push("", `Did you mean \`${suggestion}\`?`);
@@ -180663,49 +182200,6 @@ function unknownCommandGuidance(command) {
   return lines.join(`
 `);
 }
-function nearestSubcommand(input) {
-  const ranked = SUBCOMMANDS.map((command, index) => ({
-    command,
-    distance: editDistance(input, command),
-    index
-  })).toSorted((left, right) => left.distance - right.distance || left.index - right.index);
-  const abbreviation = ranked.find(({ command }) => isOrderedAbbreviation(input, command));
-  if (abbreviation !== undefined) {
-    return abbreviation.command;
-  }
-  const best = ranked[0];
-  if (best === undefined) {
-    return;
-  }
-  const closeEnough = best.distance <= Math.max(1, Math.floor(best.command.length / 2));
-  return closeEnough ? best.command : undefined;
-}
-function isOrderedAbbreviation(input, command) {
-  if (input.length < 3 || input.length >= command.length) {
-    return false;
-  }
-  let commandIndex = 0;
-  for (const character of input) {
-    const matchIndex = command.indexOf(character, commandIndex);
-    if (matchIndex === -1) {
-      return false;
-    }
-    commandIndex = matchIndex + 1;
-  }
-  return true;
-}
-function editDistance(left, right) {
-  let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
-  for (let leftIndex = 1;leftIndex <= left.length; leftIndex += 1) {
-    const current = [leftIndex];
-    for (let rightIndex = 1;rightIndex <= right.length; rightIndex += 1) {
-      const substitutionCost = left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1;
-      current[rightIndex] = Math.min((current[rightIndex - 1] ?? Number.POSITIVE_INFINITY) + 1, (previous[rightIndex] ?? Number.POSITIVE_INFINITY) + 1, (previous[rightIndex - 1] ?? Number.POSITIVE_INFINITY) + substitutionCost);
-    }
-    previous = current;
-  }
-  return previous[right.length] ?? 0;
-}
 var COMMAND_HANDLERS = {
   check: (args, io) => runCheck(parseCheckOptions(args), io),
   related: (args, io) => runRelated(parseRelatedOptions(args), io),
@@ -180714,6 +182208,12 @@ var COMMAND_HANDLERS = {
   docs: (args, io) => runDocs(parseDocsCommand(args), io),
   init: (args, io, initRuntime) => runInit(parseInitOptions(args, "init"), io, initRuntime),
   "init-with-agent": (args, io, initRuntime) => runInitWithAgent(parseInitOptions(args, "init-with-agent"), io, initRuntime),
+  upgrade: (args, io, initRuntime, cliRuntime) => runUpgrade(parseUpgradeOptions(args), io, initRuntime, {
+    latest: cliRuntime.latest ?? { status: "unavailable", source: "network" },
+    currentVersion: VERSION,
+    ...cliRuntime.env !== undefined ? { env: cliRuntime.env } : {},
+    ...cliRuntime.currentDirectory !== undefined ? { currentDirectory: cliRuntime.currentDirectory } : {}
+  }),
   lsp: (args) => {
     if (args.length > 0) {
       throw new CliError("lsp takes no options.", commandHelpGuidance("lsp"));
@@ -180725,11 +182225,12 @@ var COMMAND_HANDLERS = {
 function run(argv, io = {
   stdout: (text) => process.stdout.write(text),
   stderr: (text) => process.stderr.write(text)
-}, initRuntime = { prompts: createDefaultPrompts() }) {
+}, initRuntime = { prompts: createDefaultPrompts() }, cliRuntime = {}) {
   const [command, ...rest] = argv;
   try {
     if (command === undefined || command === "--help" || command === "-h") {
       io.stdout(GLOBAL_HELP);
+      writeUpdateNotice(argv, io, initRuntime, cliRuntime);
       return 0;
     }
     if (isSubcommand(command) && hasHelpFlag(rest)) {
@@ -180739,10 +182240,13 @@ function run(argv, io = {
     if (command === "--version" || command === "-v") {
       io.stdout(`${VERSION}
 `);
+      writeUpdateNotice(argv, io, initRuntime, cliRuntime);
       return 0;
     }
     if (isSubcommand(command)) {
-      return COMMAND_HANDLERS[command](rest, io, initRuntime);
+      const exitCode = COMMAND_HANDLERS[command](rest, io, initRuntime, cliRuntime);
+      writeUpdateNotice(argv, io, initRuntime, cliRuntime);
+      return exitCode;
     }
     throw new CliError(`Unknown command: ${command}`, unknownCommandGuidance(command));
   } catch (error) {
@@ -180756,8 +182260,59 @@ function run(argv, io = {
     return 1;
   }
 }
+function rootOptionOf(argv, currentDirectory) {
+  const flagIndex = argv.indexOf("--root");
+  const value = flagIndex === -1 ? undefined : argv[flagIndex + 1];
+  return value === undefined ? currentDirectory : resolve5(currentDirectory, value);
+}
+function writeUpdateNotice(argv, io, initRuntime, cliRuntime) {
+  const latest = cliRuntime.latest;
+  if (latest === undefined || latest.status !== "ok") {
+    return;
+  }
+  if (!decideUpdateCheck({
+    argv,
+    ...cliRuntime.env !== undefined ? { env: cliRuntime.env } : {},
+    isTty: cliRuntime.isTty ?? false
+  }).enabled) {
+    return;
+  }
+  const packageRoot = initRuntime.packageRoot ?? resolvePackageRoot();
+  const currentDirectory = cliRuntime.currentDirectory ?? process.cwd();
+  const notice = formatUpdateNotice({
+    current: VERSION,
+    latest: latest.latest,
+    guidance: detectUpgradeGuidance({
+      packageRoot,
+      projectRoot: rootOptionOf(argv, currentDirectory),
+      currentDirectory,
+      ...cliRuntime.env !== undefined ? { env: cliRuntime.env } : {}
+    })
+  });
+  if (notice !== undefined) {
+    io.stderr(notice);
+  }
+}
+async function resolveLatestForInvocation(argv, env, isTty) {
+  if (isUpdateCheckOptedOut(env)) {
+    return;
+  }
+  if (argv[0] === "upgrade" && !hasHelpFlag(argv.slice(1))) {
+    return resolveLatestStableVersion({ forceRefresh: true });
+  }
+  if (!decideUpdateCheck({ argv, env, isTty }).enabled) {
+    return;
+  }
+  return resolveLatestStableVersion();
+}
 if (__require.main == __require.module) {
-  process.exitCode = run(process.argv.slice(2));
+  const argv = process.argv.slice(2);
+  const isTty = process.stderr.isTTY === true;
+  const latest = await resolveLatestForInvocation(argv, process.env, isTty);
+  process.exitCode = run(argv, {
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text)
+  }, { prompts: createDefaultPrompts() }, { ...latest !== undefined ? { latest } : {}, env: process.env, isTty });
 }
 export {
   run,