docbridge 0.11.0 → 0.13.0

package/docs/user/configuration.md

@@ -6,7 +6,9 @@ description: "Configure docbridge.config.json: roots, include patterns, language
 
 DocBridge loads `docbridge.config.json` from the project root supplied by
 `--root`, or from the current directory by default. Paths and glob patterns are
-interpreted relative to that root.
+interpreted relative to that root. The exact rules for every key, pattern, and
+value are in the
+[Configuration specification](https://github.com/salan70/docbridge/blob/main/docs/specs/configuration.md).
 
 <!-- @code src/config/config.ts#loadConfig -->
 
@@ -33,28 +35,110 @@ Declare documentation patterns and at least one supported code language:
 }
 ```
 
-Supported language keys are `typescript`, `swift`, `dart`, `rust`, and `go`. A
-project can enable more than one language, each with its own patterns.
+Other languages use the same shape under their own key. A Go project that
+documents its `internal` packages:
 
-Each language accepts an optional `visibility` array. Omitting it uses the
-scanner default: TypeScript `public` and `protected` members, Swift `public`
-and `open`, Dart `public` only, Rust unrestricted `pub`, Go `exported`. A
-declaration excluded by visibility is not an endpoint; an `@doc` on one is
-`unsupported_declaration`. See `docbridge docs show linking` for the
-per-language rules, including Dart's leading-underscore privacy and Go's
-exported-name rule for methods.
+```json
+{
+  "$schema": "./node_modules/docbridge/schemas/docbridge.schema.json",
+  "include": {
+    "code": {
+      "go": {
+        "patterns": ["internal/**/*.go"]
+      }
+    },
+    "docs": ["docs/**/*.md"]
+  }
+}
+```
 
-The configuration has no `exclude` list and no glob negation. Narrow the
-positive patterns instead; for Go, `cmd/**/*.go` and `internal/**/*.go` scan
-fewer files than `**/*.go`, but `_test.go` files under them are still scanned.
+A project can enable more than one language, each with its own patterns, but a
+source file may match only one language.
+
+## Languages
+
+| Key          | Files                                                | `visibility` values                         | Default               | Scanner                   |
+| ------------ | ---------------------------------------------------- | ------------------------------------------- | --------------------- | ------------------------- |
+| `typescript` | `.ts`, `.tsx`, `.mts`, `.cts`, not declaration files | `public`, `protected`, `private`            | `public`, `protected` | built in                  |
+| `javascript` | `.js`, `.jsx`, `.mjs`, `.cjs`                        | `public`, `protected`, `private`            | `public`, `protected` | built in                  |
+| `swift`      | `.swift`                                             | `public`, `open`, `internal`                | `public`, `open`      | `docbridge-swift-scanner` |
+| `dart`       | `.dart`                                              | `public`                                    | `public`              | `docbridge_dart_scanner`  |
+| `rust`       | `.rs`                                                | `pub`, `private`                            | `pub`                 | `docbridge-rust-scanner`  |
+| `go`         | `.go`                                                | `exported`, `unexported`                    | `exported`            | `docbridge-go-scanner`    |
+| `python`     | `.py`                                                | `public`, `private`                         | `public`              | CPython 3.10 or later     |
+| `ruby`       | `.rb`                                                | `public`, `protected`, `private`            | `public`              | CRuby 3.3 or later        |
+| `java`       | `.java`                                              | `public`, `protected`, `package`, `private` | `public`              | JDK 17 or later           |
+
+Patterns must end with one of the language's extensions. The npm package
+bundles the Swift, Dart, Rust, and Go scanners for `darwin-arm64` and
+`linux-x64`; TypeScript, JavaScript, and Markdown need no scanner binary.
+Python, Ruby, and Java are scanned by workers in the package that run on the
+interpreter or JDK installed on the machine, on any platform; see
+[Scanner runtimes](#scanner-runtimes).
+
+Each language accepts an optional `visibility` array; omitting it uses the
+default above. TypeScript and JavaScript `visibility` applies only to class and
+type members; top-level declarations must be exported, and every JavaScript
+member is `public`. Rust `pub` means unrestricted `pub`, and `private` covers
+every narrower visibility. A declaration excluded by visibility is not an
+endpoint. An `@doc` on an excluded TypeScript or JavaScript member, or on an
+excluded Python, Ruby, or Java declaration, is `unsupported_declaration`; the Swift,
+Dart, Rust, and Go scanners ignore an `@doc` on an excluded declaration
+without a diagnostic. See `docbridge docs show linking` for the per-language
+declaration rules, including Dart's and Python's leading-underscore privacy,
+Go's exported-name rule for methods, Ruby's `private` calls, and Java's
+implicitly public interface members. The
+[Scanning specification](https://github.com/salan70/docbridge/blob/main/docs/specs/scanning.md)
+owns the exact scanner behavior and platform keys.
+
+<!-- @code src/config/scanner-runtimes.ts#ScannerRuntimes -->
+
+## Scanner runtimes
+
+Python, Ruby, and Java files are scanned by workers that run on a runtime
+installed on the machine: CPython 3.10 or later; CRuby 3.3 or later, whose
+bundled Prism parses the source; and a JDK 17 or later, whose `jdk.compiler`
+module parses the source. A JRE lacks that module and cannot scan Java.
+DocBridge looks for `python3`, then `python` (`py -3`, then `python` on
+Windows), for `ruby`, and for `java` on `PATH`, and checks each candidate
+before using it. The workers never import, compile, or run project code.
+
+To use another runtime, name it under `scanners`:
+
+```json
+{
+  "include": {
+    "code": { "python": { "patterns": ["src/**/*.py"] } },
+    "docs": ["docs/**/*.md"]
+  },
+  "scanners": {
+    "python": { "command": ["/opt/python3.12/bin/python3"] }
+  }
+}
+```
+
+`command` is the runtime executable followed by its own arguments, as an
+array rather than a shell string; a relative path resolves against the project
+root. A Java entry names the JDK's `java`, such as
+`["/opt/jdk-21/bin/java"]`. Without a configured command, the environment
+variable `DOCBRIDGE_PYTHON_RUNTIME`, `DOCBRIDGE_RUBY_RUNTIME`, or
+`DOCBRIDGE_JAVA_RUNTIME` can name one runtime executable instead. A configured
+command or variable is the only runtime tried: when it is missing or unusable,
+the files report `code_scanner_unavailable` instead of falling back to
+`PATH`.
+
+A configured command runs with your permissions in the CLI and in the editor
+extension. Review `scanners` in a repository you do not trust before running
+DocBridge there.
 
 <!-- @code src/shared/glob.ts#collectFiles -->
+<!-- @code src/config/code-language.ts#collectCodeFiles -->
 
 ## Excluded files
 
-The configuration has no `exclude` property. Narrow the include patterns when
-tests, fixtures, generated files, or general documentation should stay outside
-the graph:
+The configuration has no `exclude` property and no glob negation. Narrow the
+positive include patterns when tests, fixtures, generated files, or general
+documentation should stay outside the graph:
 
 ```json
 {
@@ -69,8 +153,15 @@ the graph:
 }
 ```
 
+For Go, `cmd/**/*.go` and `internal/**/*.go` scan fewer files than
+`**/*.go`, but `_test.go` files under them are still scanned. For Python,
+Ruby, and Java, keep test directories such as `tests/`, `spec/`, and
+`src/test/` outside the patterns in the same way; in a Maven or Gradle layout,
+`src/main/java/**/*.java` does.
+
 DocBridge always ignores dependency directories, Git metadata, dot-prefixed
-path segments, symbolic links, and TypeScript declaration files (`.d.ts`).
+path segments, symbolic links, and TypeScript declaration files (`.d.ts`,
+`.d.mts`, and `.d.cts`).
 Keep patterns narrow enough that `docbridge check --audit` reports useful
 coverage gaps rather than every implementation detail or general prose file.
 
@@ -81,3 +172,6 @@ file, or invalid JSON, produces `config_file_invalid`. An unknown key produces
 `config_unknown_key`, and a rejected value produces `config_invalid_value`. Use
 `docbridge init --dry-run` to inspect a safe generated starting point without
 overwriting an existing file.
+
+Next, read `docbridge docs show linking` to add the first links, or
+`docbridge docs show commands` to choose how to check them.

package/docs/user/getting-started.md

@@ -1,5 +1,5 @@
 ---
-description: Set up DocBridge in an existing TypeScript, Swift, Dart, Rust, or Go project.
+description: Set up DocBridge in an existing TypeScript, JavaScript, Swift, Dart, Rust, Go, Python, Ruby, or Java project.
 ---
 
 # Getting Started

package/docs/user/linking.md

@@ -7,13 +7,22 @@ description: Choose, create, and semantically review @doc and @code links.
 DocBridge connects supported code declarations to Markdown headings. This
 guide covers the complete workflow: choose meaningful sections, create a
 reciprocal annotation pair, and review whether the relationship is still true.
+The exact contracts are in the
+[Annotations](https://github.com/salan70/docbridge/blob/main/docs/specs/annotations.md),
+[Link resolution](https://github.com/salan70/docbridge/blob/main/docs/specs/link-resolution.md),
+and [Link manifest](https://github.com/salan70/docbridge/blob/main/docs/specs/link-manifest.md)
+specifications.
 
 ## Choose what to link
 
 Prefer sections that define behavior, contracts, inputs and outputs,
-constraints, user-visible behavior, or design decisions. README files,
-changelogs, contribution guides, runbooks, and release notes are excluded by
-default unless a specific section acts as an enduring specification.
+constraints, user-visible behavior, or design decisions. Do not link README
+files, changelogs, contribution guides, runbooks, or release notes unless a
+specific section acts as an enduring specification. `docbridge init` skips
+conventional files such as `README.md`, `CHANGELOG.md`, and `CONTRIBUTING.md`
+when it chooses a documentation directory. DocBridge still scans every
+Markdown file that the configured `docs` patterns match, including a proposed
+`docs/**/*.md`, so narrow the patterns to keep these files out of the graph.
 
 Prefer supported public API declarations as code targets. Do not force a link
 when no declaration implements or represents the section, and do not use link
@@ -79,17 +88,44 @@ pub fn login(email: &str, password: &str) {}
 func Login(email, password string) error { return nil }
 ```
 
-Paths are relative to the configured root. An annotation on an unsupported or
-visibility-excluded declaration produces `unsupported_declaration`; the same
-declaration without an annotation is ignored.
+```js
+/** @doc docs/auth.md#login-flow */
+export function login(email, password) {}
+```
+
+```python
+def login(email: str, password: str) -> None:
+    """Start the login flow.
+
+    @doc docs/auth.md#login-flow
+    """
+```
+
+```ruby
+# @doc docs/auth.md#login-flow
+def login(email, password); end
+```
+
+```java
+/** @doc docs/auth.md#login-flow */
+public void login(String email, char[] password) {}
+```
+
+Paths are relative to the configured root. An annotation on an unsupported
+declaration, or on a TypeScript, JavaScript, Python, Ruby, or Java declaration
+excluded by visibility, produces `unsupported_declaration`; the same
+declaration without an annotation is ignored. Swift, Dart, Rust, and Go ignore
+an annotation on a declaration excluded by visibility without a diagnostic. To link such a declaration, add
+its tier to `visibility` where the language accepts one; Dart accepts only
+`public`, so a private Dart declaration cannot be linked.
 
 ### TypeScript declarations
 
 Supported top-level exported forms include functions, classes, interfaces,
-type aliases, enums, and single-declarator constants, including supported
-`declare` and named default forms. Supported members include class methods,
-properties, accessors, constructors, and static members; interface members;
-and members of object-literal type aliases.
+type aliases, enums, and single-declarator variables (`const`, `let`, or
+`var`), including supported `declare` and named default forms. Supported members
+include class methods, properties, accessors, constructors, and static members;
+interface members; and members of object-literal type aliases.
 
 Members use type-qualified IDs without parameter signatures, such as
 `AuthService.login` and `AuthService.constructor`. Visibility defaults to
@@ -140,6 +176,66 @@ clause, imports, `init`, and `_` are not endpoints. The scanner is syntactic:
 `_test.go` files and `//go:build`-constrained files are scanned whenever the
 patterns match them.
 
+### JavaScript declarations
+
+JavaScript follows the TypeScript rules for the forms an ES module can
+express: exported functions, classes, and single-declarator variables, named
+default exports, and the members of exported classes, with the same JSDoc
+comments and IDs such as `AuthService.login`. Every member is `public`;
+`#private` members are not endpoints. CommonJS assignments such as
+`module.exports = ...` and `exports.name = ...` are not endpoints, so an
+`@doc` on one is `unsupported_declaration`. JSX parses in every JavaScript
+file. TypeScript-only syntax, such as an `interface`, a `type` alias, or a type
+annotation, is a syntax error in a JavaScript file and is reported as
+`code_parse_error`; JSDoc types stay valid.
+
+### Python declarations
+
+Supported forms are module-level functions and classes, and the methods and
+nested classes of a class, including those under `if`, `try`, and `with`
+blocks; nothing inside a function body is an endpoint. Put `@doc` in the
+docstring or in the `#` comment block directly above the declaration or its
+first decorator. IDs are dot-qualified, such as `AuthService.login`. A
+property's getter, setter, and deleter share one endpoint, as do `@overload`
+stubs and their implementation. A name that starts with `_`, other than a
+`__dunder__` name, is `private`, and so is every member of a private class.
+Module docstrings, assignments, and nested functions are not endpoints.
+
+### Ruby declarations
+
+Supported forms are classes, modules, constants, instance methods, singleton
+methods (`def self.x` and `def x` inside `class << self`), and top-level
+methods. Put `@doc` in the `#` comment block directly above the declaration.
+IDs use `::` between constants and `.` before a method name, such as
+`Auth::Service`, `Auth::MAX_ATTEMPTS`, `Auth::Service.login`, and
+`Auth::Service.self.build` for a singleton method. A class reopened in the same
+file is one endpoint. Bare `private`, `protected`, and `public` calls,
+`private def x`, and `private_class_method` set method visibility; classes,
+modules, and constants are always `public`. `attr_reader` and its siblings,
+`alias`, and `define_method` are not endpoints.
+
+### Java declarations
+
+Supported forms are top-level and nested classes, interfaces, enums, records,
+and annotation types; methods and constructors; and fields and enum
+constants. Put `@doc` in the declaration's Javadoc comment (`/** */`); `//`
+and `/* */` comments are ignored. IDs are dot-qualified without the package,
+and methods and constructors add their parameter types: `AuthService`,
+`AuthService.MAX_ATTEMPTS`, `AuthService.login(String,char[])`, and
+`AuthService.AuthService(Authenticator)` for a constructor. Parameter types
+are written as in the source, without type arguments or annotations, and
+varargs become arrays (`String...` is `String[]`). Visibility defaults to
+`public`. Interface members without a modifier and enum constants are
+`public`, and a member is never more visible than its enclosing types. Local
+and anonymous classes, lambdas, and initializer blocks are not endpoints. An
+`@doc` above a field statement that declares several names (`int a, b;`) is
+`unsupported_declaration` because it cannot name one endpoint; link those
+fields from `docbridge.links.json` instead.
+
+`javadoc` reports `@doc` as an unknown tag when doclint runs with
+`-Xdoclint`. Register the tag with `-tag doc:a:"DocBridge:"` so the check
+accepts it.
+
 <!-- @code src/scan/markdown/markdown.ts#scanMarkdown -->
 
 ## Documentation to code

package/docs/user/troubleshooting.md

@@ -14,8 +14,8 @@ stderr. Use `docbridge <command> --help` for invocation errors and
 (for example, the path is a directory or lacks read permission), or is not
 valid JSON. The message says the file was not found in both of the first two
 cases. Run `docbridge init --dry-run` when the file is missing. When the path
-exists, make it a readable file with valid JSON, or remove it, before running
-`check` again.
+exists, make it a readable file with valid JSON, or remove it and create a new
+one with `docbridge init`, before running `check` again.
 
 `config_unknown_key` means a parsed file has a key DocBridge does not know,
 such as a misspelled property. `config_invalid_value` means a known key has a
@@ -36,14 +36,31 @@ lacks a binary for the current platform or the binary cannot execute.
 Reinstall the package first. If the platform is not supported, run DocBridge
 in a supported environment or build the scanner from the repository.
 
-`code_scanner_failed` diagnostics contain the worker failure rather than
-converting it into a broken link. Check that the source parses with the
-project's own toolchain, then reproduce with the smallest configured file
-set.
+Python, Ruby, and Java run on the runtime installed on the machine. For them,
+`code_scanner_unavailable` names the runtime DocBridge needs, the minimum
+version, and what it found for each candidate: no runtime on `PATH`, a
+version below CPython 3.10, CRuby 3.3, or JDK 17, a Ruby whose bundled Prism
+does not load, or a Java runtime without the `jdk.compiler` module, which is
+what a JRE or a trimmed `jlink` image reports. Install a supported version on
+`PATH`, or point `scanners.<language>.command` in the configuration, or
+`DOCBRIDGE_PYTHON_RUNTIME`, `DOCBRIDGE_RUBY_RUNTIME`, or
+`DOCBRIDGE_JAVA_RUNTIME` in the environment, at one; see
+[Configuration](configuration.md#scanner-runtimes). For Java, that is the
+`java` executable of a full JDK 17 or later, not a JRE. When the message names
+one of those overrides, DocBridge tried only that runtime, so fix or remove
+the override instead of installing another one.
 
-`code_parse_error` means a TypeScript, Swift, Dart, Rust, or Go source file has a
-syntax error. The diagnostic points at the first error the language's parser
-found and includes the parser's message. DocBridge extracts no links or symbols
+`code_scanner_failed` diagnostics contain the worker failure rather than
+converting it into a broken link. One worker run scans every file of its
+language, so a failed run reports the same message on each of those files.
+Check that the source parses with the project's own toolchain, then reproduce
+with the smallest configured file set.
+
+`code_parse_error` means a TypeScript, JavaScript, Swift, Dart, Rust, Go,
+Python, Ruby, or Java source file has a syntax error. The diagnostic points at
+the first error the language's parser found and includes the parser's message;
+for Python, Ruby, and Java, the wording comes from the installed runtime, and
+Java syntax newer than the installed JDK does not parse. DocBridge extracts no links or symbols
 from that file, so fix the syntax before judging link diagnostics that involve
 it. Unlike
 `code_scanner_failed`, the worker ran correctly; the source itself did not

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docbridge",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "A CLI that links Markdown specifications and code declarations. Runs on Node.js and Bun.",
   "keywords": [
     "bun",

package/schemas/common-output.schema.json

@@ -44,7 +44,17 @@
         "target": { "type": "string" },
         "language": {
           "type": "string",
-          "enum": ["typescript", "swift", "dart", "rust", "go"]
+          "enum": [
+            "typescript",
+            "swift",
+            "dart",
+            "rust",
+            "go",
+            "javascript",
+            "python",
+            "ruby",
+            "java"
+          ]
         },
         "source": { "type": "string" },
         "message": { "type": "string" },

package/schemas/context-output.schema.json

@@ -35,7 +35,17 @@
           },
           "language": {
             "type": "string",
-            "enum": ["typescript", "swift", "dart", "rust", "go"],
+            "enum": [
+              "typescript",
+              "swift",
+              "dart",
+              "rust",
+              "go",
+              "javascript",
+              "python",
+              "ruby",
+              "java"
+            ],
             "description": "Code language for code context blocks."
           },
           "startLine": {

package/schemas/docbridge.schema.json

@@ -22,7 +22,11 @@
             "swift": { "$ref": "#/$defs/swiftEntry" },
             "dart": { "$ref": "#/$defs/dartEntry" },
             "rust": { "$ref": "#/$defs/rustEntry" },
-            "go": { "$ref": "#/$defs/goEntry" }
+            "go": { "$ref": "#/$defs/goEntry" },
+            "javascript": { "$ref": "#/$defs/javascriptEntry" },
+            "python": { "$ref": "#/$defs/pythonEntry" },
+            "ruby": { "$ref": "#/$defs/rubyEntry" },
+            "java": { "$ref": "#/$defs/javaEntry" }
           }
         },
         "docs": {
@@ -34,9 +38,33 @@
           }
         }
       }
+    },
+    "scanners": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "python": { "$ref": "#/$defs/scannerRuntime" },
+        "ruby": { "$ref": "#/$defs/scannerRuntime" },
+        "java": { "$ref": "#/$defs/scannerRuntime" }
+      }
     }
   },
   "$defs": {
+    "scannerRuntime": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["command"],
+      "properties": {
+        "command": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
     "typescriptEntry": {
       "type": "object",
       "additionalProperties": false,
@@ -47,7 +75,7 @@
           "minItems": 1,
           "items": {
             "type": "string",
-            "pattern": "^(?!.*\\.d\\.ts$).*\\.ts$"
+            "pattern": "^(?!.*\\.d\\.[cm]?ts$).*\\.(ts|tsx|mts|cts)$"
           }
         },
         "visibility": {
@@ -146,6 +174,94 @@
           }
         }
       }
+    },
+    "javascriptEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["patterns"],
+      "properties": {
+        "patterns": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "pattern": "\\.(js|jsx|mjs|cjs)$"
+          }
+        },
+        "visibility": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["public", "protected", "private"]
+          }
+        }
+      }
+    },
+    "pythonEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["patterns"],
+      "properties": {
+        "patterns": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "pattern": "\\.py$"
+          }
+        },
+        "visibility": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["public", "private"]
+          }
+        }
+      }
+    },
+    "rubyEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["patterns"],
+      "properties": {
+        "patterns": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "pattern": "\\.rb$"
+          }
+        },
+        "visibility": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["public", "protected", "private"]
+          }
+        }
+      }
+    },
+    "javaEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["patterns"],
+      "properties": {
+        "patterns": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "pattern": "\\.java$"
+          }
+        },
+        "visibility": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["public", "protected", "package", "private"]
+          }
+        }
+      }
     }
   }
 }

package/schemas/graph-output.schema.json

@@ -31,7 +31,17 @@
           },
           "language": {
             "type": "string",
-            "enum": ["typescript", "swift", "dart", "rust", "go"],
+            "enum": [
+              "typescript",
+              "swift",
+              "dart",
+              "rust",
+              "go",
+              "javascript",
+              "python",
+              "ruby",
+              "java"
+            ],
             "description": "Code language for code nodes."
           },
           "location": { "$ref": "common-output.schema.json#/$defs/location" },

package/schemas/scanner-worker.schema.json

@@ -7,7 +7,7 @@
   "$defs": {
     "language": {
       "type": "string",
-      "enum": ["typescript", "swift", "dart", "rust", "go"]
+      "enum": ["typescript", "swift", "dart", "rust", "go", "javascript", "python", "ruby", "java"]
     },
     "codeSymbol": {
       "type": "object",

package/templates/skills/docbridge/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docbridge
-description: Adopt or introduce DocBridge, choose docs and code scope, create or improve docbridge.config.json, add @doc and @code annotations, fix link diagnostics, triage related --gate findings, and review existing links for stale docs or semantic validity.
+description: Adopt or introduce DocBridge, choose docs and code scope, create or improve docbridge.config.json, add @doc and @code annotations or docbridge.links.json entries, fix link diagnostics, triage related --gate findings, and review existing links for stale docs or semantic validity.
 ---
 
 # docbridge
@@ -22,7 +22,7 @@ Pick **one** job before editing. The first matching question wins:
 | ----------------- | ------------------------------------------------------------------------------ | --------------------------------------------- |
 | Adopt             | Introduce DocBridge, choose docs/code scope, or write `docbridge.config.json`? | Linking existing files                        |
 | Discover and link | Choose what to link in existing docs, docs-first?                              | A known pair already confirmed                |
-| Annotate          | Add or fix a `@doc` / `@code` pair, or clear link diagnostics?                 | Deciding _whether_ a section should be linked |
+| Annotate          | Add or fix a `@doc` / `@code` pair or a manifest entry, or clear diagnostics?  | Deciding _whether_ a section should be linked |
 | Review            | Check whether the docs still match the code, with no change set?               | Gate findings on a diff                       |
 | Sync              | A Git hook, CI comment, or `related --gate` flagged unchanged counterparts?    | Auditing the whole graph                      |
 
@@ -73,6 +73,16 @@ no diagnostic mentions either endpoint.
 Do not split or rename headings in this job. Preserve existing annotations
 unless the user asked to fix a wrong link.
 
+### Manifest links
+
+Use `docbridge.links.json` when the project already declares links there, or
+when the user does not accept markers in a file. Read
+`docbridge docs show linking` for its format. Add one entry per link with the
+same `code` and `doc` targets an annotation pair would use; never declare a
+link that an annotation pair already provides. Fix `code_symbol_not_found` with
+the printed suggestion only after confirming it names the intended symbol.
+Verify with `docbridge check`.
+
 ## Sync
 
 A `related --gate` violation means nobody has decided yet, not that the