docbridge 0.7.0 → 0.9.0

package/schemas/docbridge.links.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "DocBridge Link Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["links"],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "links": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/link" }
+    }
+  },
+  "$defs": {
+    "link": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "doc"],
+      "properties": {
+        "code": {
+          "description": "Code endpoint as file#canonicalId, relative to the project root.",
+          "type": "string",
+          "pattern": "^[^/\\\\#\\s][^\\\\#\\s]*#[^#\\s]+$"
+        },
+        "doc": {
+          "description": "Documentation endpoint as file#anchor, relative to the project root.",
+          "type": "string",
+          "pattern": "^[^/\\\\#\\s][^\\\\#\\s]*\\.md#[^#\\s]+$"
+        },
+        "note": {
+          "description": "Free-form text for human readers. It reaches no command output.",
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/schemas/scanner-worker.schema.json

@@ -29,6 +29,7 @@
         "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" }

package/templates/skills/README.md

@@ -1,34 +1,27 @@
 # DocBridge skill templates
 
-Distributable agent skills for projects that use DocBridge. Prefer
+Distributable agent skill for projects that use DocBridge. Prefer
 `docbridge init` for CLI-driven setup or `docbridge init-with-agent` for
-agent-guided adoption. `init-with-agent` installs `docbridge-adopt` first;
-`docbridge-adopt` installs the companion skills after scope is confirmed.
-Manual copy-based installation remains available: copy a
-skill directory into your repository's skill location (`.claude/skills/` for
-Claude Code or `.agents/skills/` for Codex-style project skills) and adjust
-nothing unless your DocBridge invocation differs from the examples inside.
+agent-guided adoption. Both commands install the same `docbridge` skill.
+Manual copy-based installation remains available: copy the skill directory
+into your repository's skill location (`.claude/skills/` for Claude Code or
+`.agents/skills/` for Codex-style project skills).
 
-- [`docbridge-annotate`](docbridge-annotate/SKILL.md) — create correct
-  `@doc`/`@code` link pairs and verify them with `docbridge check`.
-- [`docbridge-sync`](docbridge-sync/SKILL.md) — triage `related --gate`
-  findings: fetch the flagged counterpart content with `docbridge context`,
-  then update the counterpart or justify leaving it unchanged.
-- [`docbridge-adopt`](docbridge-adopt/SKILL.md) — adopt DocBridge in an existing
-  TypeScript, Swift, Dart, or Rust project by confirming docs/code scope, creating
-  or improving config, installing companion skills, and handling simple CI or
-  Git-hook setup.
-- [`docbridge-link`](docbridge-link/SKILL.md) — link existing docs sections to
-  existing supported code declarations through docs-first candidate discovery
-  and section-level confirmation.
-- [`docbridge-review`](docbridge-review/SKILL.md) — review the whole DocBridge
-  graph for semantic validity using `docbridge graph --json --include-content`.
+- [`docbridge`](docbridge/SKILL.md) — route adopt, discover-and-link, annotate,
+  review, and sync work. Facts about the binary live in
+  `docbridge docs show`, not in this file.
 
-This repository dogfoods the distributable DocBridge skills from both
+This repository dogfoods the distributable DocBridge skill from both
 `.claude/skills/` and `.agents/skills/` as skill-level symlinks to this
 directory. The template is the source of truth; do not edit the symlinked
 copies in place. In-repository dogfood links require symlink-capable checkouts;
 external projects should use the copy-based installation above.
 
-The Git-hook and CI integration that complements these skills is described
+Existing installs may still have the five legacy skill directories
+(`docbridge-adopt`, `docbridge-annotate`, `docbridge-link`,
+`docbridge-review`, `docbridge-sync`). `docbridge init --force` removes those
+copied directories after you review local edits. Symlinked skill directories
+are reported and left untouched.
+
+The Git-hook and CI integration that complements this skill is described
 under [`docs/integrations/`](../../docs/integrations/).

package/templates/skills/docbridge/SKILL.md

@@ -0,0 +1,125 @@
+---
+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.
+---
+
+# docbridge
+
+Route DocBridge work, then apply the matching judgment. Facts about the binary
+— annotation syntax, supported declarations, the anchor algorithm, diagnostic
+codes — live in packaged docs, not in this skill. Read them with
+`docbridge docs show`. Invocation is documented in
+`docbridge docs show automation`.
+
+An agent with no DocBridge skill can still finish the job from
+`docbridge --help` plus `docbridge docs list` / `docbridge docs show`.
+
+## Task router
+
+Pick **one** job before editing. The first matching question wins:
+
+| Job               | Ask this                                                                       | Not this                                      |
+| ----------------- | ------------------------------------------------------------------------------ | --------------------------------------------- |
+| 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 |
+| 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                      |
+
+**Review versus sync.** Whole graph, no change set → **review**. A change set's
+flagged counterparts → **sync**. "Check whether the docs still match the code"
+is review. "These counterparts were not updated in this diff" is sync.
+
+## Adopt
+
+Survey the repo: existing config, likely specification directories, public API
+locations, existing annotations, scripts, CI, and Git hooks.
+
+Recommend docs scope, code scope, and whether to wire simple CI or hooks now.
+Show the tradeoff, then wait for confirmation. Create or improve
+`docbridge.config.json` only after that. Use the language-keyed `include.code`
+object, never the old array form. Never replace a user-authored config blindly.
+
+Handle CI and Git hooks conservatively: implement a simple confirmed setup;
+otherwise provide a patch plan. Prefer a non-blocking gate early in adoption.
+
+Verify with `docbridge check`. A clean zero-link result is acceptable. Then
+continue into discover-and-link.
+
+Read `docbridge docs show getting-started` and `configuration`.
+
+## Discover and link
+
+Work docs-first. Confirm docs scope, then follow
+`docbridge docs show linking`: prioritize unlinked specification
+sections, propose at most three symbols per section with why/uncertain, present
+5–10 sections per round, collect adopt/exclude/hold, and classify no-matches
+instead of forcing a link.
+
+Add annotations only after section-level confirmation. Then follow Annotate.
+
+## Annotate
+
+Create both sides of a pair, or add the missing backlink. Read
+`docbridge docs show linking` for syntax, supported declarations, anchors,
+and target grammar. Read `docbridge docs show troubleshooting` for diagnostic
+codes and fixes.
+
+Procedure: identify the declaration and the heading; add `@doc` on the
+declaration (create a minimal doc comment if missing); add `@code` directly
+above the heading; verify with `docbridge check`. The pair is correct only when
+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.
+
+## Sync
+
+A `related --gate` violation means nobody has decided yet, not that the
+counterpart must change. Read `docbridge docs show automation` for the
+three-way judgment.
+
+1. Collect violations from the hook, CI comment, or, for uncommitted work
+   including new files,
+   `{ git diff --name-only HEAD; git ls-files --others --exclude-standard; } | docbridge related --stdin --gate`.
+2. Fetch counterpart content with `docbridge context` over the changed files.
+3. Per counterpart: update it when the documented contract diverged; leave it
+   unchanged with a written justification that cites the counterpart content;
+   or fix the annotation pair when the link itself is wrong.
+4. Re-run the gate. Report every decision.
+
+Never detach a link to silence the gate. Do not rubber-stamp: unread
+counterpart content is not a judgment. When a code change contradicts an
+explicit documented promise, surface that instead of quietly rewriting the
+promise.
+
+## Review
+
+Audit meaning across the whole graph, not a diff. Follow the semantic review
+procedure in `docbridge docs show linking`.
+
+Requires `docbridge graph --json --include-content`. Read `diagnostics` first.
+Batch by docs file. Read both sides. Classify High / Medium / Low. Report
+severity, endpoints, evidence, and a recommended fix. Do not edit annotations
+automatically.
+
+`check` proves mechanics; this job reviews meaning. Do not rubber-stamp a
+resolving link. Prefer fewer, clearer links. Do not delete annotations to
+silence uncertainty.
+
+## Shared guardrails
+
+- Confirm scope and section-level decisions with the user before writing links.
+- Do not decide branch or pull-request policy.
+- Prefer public API declarations as link targets.
+- After edits, re-run `docbridge check` (and `related --gate` for sync).
+
+## Read more
+
+- `docbridge docs list` — the full menu
+- `docbridge docs show linking` — discovery, annotations, and semantic review
+- `docbridge docs show automation` — invocation, gate judgment, hooks, and CI
+- `docbridge docs show troubleshooting` — diagnostic codes and fixes
+- `docbridge docs show getting-started` — first-time setup
+- `docbridge docs show configuration` — `docbridge.config.json`
+- `docbridge docs show commands` — check, related, context, graph, docs, upgrade

package/docs/user/agent-integration.md

@@ -1,70 +0,0 @@
----
-description: Wire DocBridge into coding agents, Git hooks, and CI.
----
-
-# Agent Integration
-
-DocBridge gives coding agents deterministic link data instead of asking them
-to infer documentation relationships from filenames.
-
-<!-- @code src/cli/init.ts#runInitWithAgent -->
-
-## Install agent skills
-
-`docbridge init` can install the distributable skills while creating project
-configuration. To let an agent decide the scope, run:
-
-```sh
-docbridge init-with-agent --agent-target codex
-```
-
-Use `claude` or `both` for other supported targets. The command installs the
-adoption skill and prints the next command or prompt; it does not launch an
-agent process.
-
-## Editing workflow
-
-Before changing a linked file, provide its counterpart content:
-
-```sh
-docbridge context path/to/changed-file
-```
-
-After editing, inspect the change set:
-
-```sh
-git diff --name-only | docbridge related --stdin --gate
-```
-
-For every reported counterpart, update it when behavior diverged or record why
-no documentation or code change is necessary.
-
-## Hooks
-
-Put the automation in Git hooks rather than in one agent's configuration, so
-it covers every contributor and every tool. A `pre-commit` hook can run
-`docbridge check` as a hard gate, then report `related --gate` over the staged
-files:
-
-```sh
-git diff --cached --name-only | docbridge related --stdin --gate
-```
-
-When an agent runs `git commit` through a shell, the hook's output lands in the
-tool result and therefore in the agent's context, so the counterpart findings
-reach it without any agent-specific wiring. Attach the counterparts' content
-with `docbridge context --stdin` to make the finding actionable in place.
-
-Keep the gate stage non-blocking while the link graph is still sparse: a
-blocking gate on a staged subset mostly trains `--no-verify`. Hooks must not
-silently rewrite files or replace the repository's mandatory checks.
-
-Git hooks cannot signal before an edit, and they are skipped by `--no-verify`
-and by some GUI clients, so the pull request stays the enforcement point.
-
-## CI
-
-Run `docbridge check` over the whole project as the hard link-validity gate. A
-pull-request workflow can additionally pass the base-to-head changed file list
-to `related --stdin --gate` and attach `context` output for reviewers. Ensure
-the checkout includes both commits needed for the diff.

package/docs/user/annotations.md

@@ -1,52 +0,0 @@
----
-description: Write @doc and @code annotations and valid link targets.
----
-
-# Annotations
-
-DocBridge links supported code declarations to Markdown headings. A complete
-pair has `@doc` on the declaration and `@code` immediately before the heading.
-
-## Code to documentation
-
-Use a documentation path and heading anchor in a declaration's documentation
-comment:
-
-```ts
-/**
- * @doc docs/auth.md#login-flow
- */
-export function login(): void {}
-```
-
-Swift, Dart, and Rust use their normal documentation comment syntax with the same
-target format. Paths are relative to the configured project root.
-
-<!-- @code src/core/markdown.ts#scanMarkdown -->
-
-## Documentation to code
-
-Place an HTML comment immediately before the linked heading:
-
-```md
-<!-- @code src/auth.ts#login -->
-
-## Login Flow
-```
-
-The code fragment is the canonical symbol ID emitted by the language scanner.
-Top-level functions and types normally use their declaration name. Members use
-their type-qualified identity. TypeScript member IDs omit parameter signatures,
-Swift member IDs include argument labels, Dart member IDs omit parameter
-signatures, and Rust member IDs use `::` path qualification.
-
-## Anchors and reciprocity
-
-Markdown anchors use the normalized heading text, such as `# Login Flow`
-becoming `#login-flow`. Duplicate headings receive the same numeric suffixes
-used by GitHub-style Markdown anchors.
-
-Each direction is validated independently. A target can resolve while still
-reporting a missing reciprocal annotation. Run `docbridge check` to validate
-targets and pair completeness, and `docbridge graph --json` when you need the
-resolved endpoints and edges.

package/templates/skills/docbridge-adopt/SKILL.md

@@ -1,96 +0,0 @@
----
-name: docbridge-adopt
-description: Adopt DocBridge in an existing TypeScript, Swift, Dart, or Rust project. Use when asked to introduce DocBridge into a repository, choose docs/code scope, create or improve docbridge.config.json, and optionally wire simple CI or Git hooks.
----
-
-# docbridge-adopt
-
-Adopt DocBridge in an existing project. This skill assumes it is already
-installed in the agent environment through `docbridge init-with-agent`,
-`docbridge init`, or a manual copy into `.agents/skills/` or
-`.claude/skills/`.
-
-The goal is to make the repository ready for DocBridge links, then continue
-into an initial docs-first link-candidate pass. Do not assume a pull request.
-
-Run DocBridge with the project's native invocation: `docbridge` on `PATH`, a
-repo recipe such as `just check`, or
-`bun run /path/to/docbridge/src/cli/index.ts`.
-
-## Procedure
-
-1. **Survey the repository.** Inspect:
-   - existing `docbridge.config.json`
-   - Markdown docs structure and likely specification directories
-   - TypeScript, Swift, Dart, or Rust source structure and public API locations
-   - existing `@doc` / `@code` annotations
-   - package scripts, CI files, and Git hooks
-
-2. **Recommend scope, then ask for confirmation.** Present concise options and
-   your recommendation for:
-   - docs scope: directories/files whose sections are likely specifications,
-     contracts, behavior, constraints, or design decisions
-   - code scope: language-keyed TypeScript, Swift, Dart, or Rust directories/files
-     whose supported declarations should be linkable
-   - CI/Git-hook mode: if any integration should be added now
-
-   Do not ask the user to rediscover obvious facts from the repository. Show
-   your recommendation and the tradeoff, then wait for confirmation.
-
-3. **Create or improve config.**
-   - If no config exists, create `docbridge.config.json` with the confirmed
-     `include.code` and `include.docs` globs.
-   - Use the language-keyed `include.code` object. Do not write the old
-     array form; for example, use `{ "typescript": { "patterns": [...] } }`,
-     `{ "swift": { "patterns": [...] } }`, `{ "dart": { "patterns": [...] } }`,
-     or `{ "rust": { "patterns": [...] } }`.
-   - If config exists, read it, explain the current scope, propose any
-     improvement, and edit only after confirmation.
-   - Never replace a user-authored config blindly.
-
-4. **Install companion DocBridge skills.**
-   - After scope is confirmed and `docbridge.config.json` exists or has been
-     intentionally left unchanged, install the rest of the distributable
-     DocBridge skills for the same agent target.
-   - Prefer the project-native DocBridge invocation. From the project root, run
-     `docbridge init --yes --agent-target codex` for Codex,
-     `docbridge init --yes --agent-target claude` for Claude Code, or
-     `docbridge init --yes --agent-target both` for both. Use the target that
-     matches the existing `.agents/` and/or `.claude/` setup.
-   - This command should leave an existing `docbridge.config.json` unchanged
-     and copy any missing `docbridge-annotate`, `docbridge-link`,
-     `docbridge-review`, and `docbridge-sync` skill directories. Do not use
-     `--force` unless the user explicitly asks to overwrite installed skills.
-   - If the command is unavailable, explain the blocker and provide the manual
-     copy target paths from `templates/skills/docbridge-*` instead of silently
-     skipping this step.
-
-5. **Handle CI and Git hooks conservatively.**
-   - If the existing setup is simple and the user confirmed the mode, implement
-     it.
-   - If the setup is complex or ambiguous, provide a concrete patch plan or
-     snippet instead of editing.
-   - Prefer non-blocking awareness early in adoption unless the user requests a
-     hard gate.
-
-6. **Verify the setup.** Run `docbridge check` or the repository's equivalent.
-   If the project intentionally has no links yet, a clean zero-link result is
-   acceptable. Surface config or scanning diagnostics before proceeding.
-
-7. **Continue into initial candidate discovery.** After setup, inspect the
-   confirmed docs scope and present 5-10 high-value section candidates using
-   the `docbridge-link` rules. Candidate discovery may continue in the same
-   turn, but annotation edits still require section-level user confirmation.
-
-## Scope Rules
-
-- Prefer docs sections that state behavior, contracts, inputs/outputs,
-  constraints, user-visible behavior, or design decisions.
-- Treat README, changelogs, contribution docs, runbooks, logs, and release
-  notes as exclusions by default unless the user identifies specific sections
-  as specifications.
-- Prefer supported public API declarations as link targets. TypeScript starts
-  with top-level exported declarations; Swift, Dart, and Rust also support member
-  endpoints with scanner-produced canonical IDs.
-- Do not decide project workflow policy such as branch or PR strategy. Mention
-  only what affects DocBridge adoption.

package/templates/skills/docbridge-annotate/SKILL.md

@@ -1,99 +0,0 @@
----
-name: docbridge-annotate
-description: Create bidirectional DocBridge links between supported code declarations and Markdown sections. Use when asked to link code to its specification, add @doc or @code annotations, annotate new code with docs, or fix DocBridge link diagnostics.
----
-
-# docbridge-annotate
-
-Create a DocBridge link pair: a `@doc` tag in the code documentation comment
-and a `@code` comment above the Markdown heading. A link is valid only when
-both directions exist and point at each other.
-
-Run DocBridge with the project's native invocation: `docbridge` on `PATH`, a
-repo recipe such as `just check`, or
-`bun run /path/to/docbridge/src/cli/index.ts`.
-
-## Link anatomy
-
-Code side — a `@doc` tag in the documentation comment of a supported
-declaration:
-
-```ts
-/**
- * @doc docs/auth.md#login-spec
- */
-export async function login() {}
-```
-
-```swift
-/// @doc docs/auth.md#login-spec
-public struct AuthService {
-  public func login(email: String, password: String) {}
-}
-```
-
-Markdown side — a standalone HTML comment directly above the heading of the
-section:
-
-```md
-<!-- @code src/auth/login.ts#login -->
-
-## Login Spec
-```
-
-Both targets are `file#fragment`: the file path is project-root-relative with
-`/` separators (no `./`, `../`, or absolute paths), and the fragment is
-required. Optional text after the target is allowed and ignored
-(`@doc docs/auth.md#login-spec human note`).
-
-## Rules that decide whether the link resolves
-
-- `@doc` works only on top-level exported declarations: `function`, `class`,
-  `abstract class`, `interface`, `type`, `enum`, `const enum`, `const` with a
-  single declarator, named default `function`/`class`, and their `declare`
-  forms. Anything else (anonymous default exports, multi-declarator `const`,
-  namespaces, re-exports, non-exported declarations) produces
-  `unsupported_declaration`.
-- Swift `@doc` works on supported public/open declarations and configured
-  internal declarations. Member endpoints are type-qualified and include
-  argument labels, for example `AuthService.login(email:password:)`.
-- Dart `@doc` works on supported public declarations. Member endpoints are
-  type-qualified without parameter signatures, for example
-  `AuthService.login`; setters carry a trailing `=`.
-- The code-side fragment is the scanner-produced canonical ID.
-- The doc-side fragment is the anchor generated from the ATX heading
-  (`#`–`######`): lowercase via JavaScript `toLowerCase()`, Unicode letters
-  and numbers preserved, whitespace and punctuation runs collapsed to `-`,
-  leading/trailing `-` removed. Example: `## Login Spec (v2)` →
-  `#login-spec-v2`. Setext headings have no anchors.
-- The `@code` comment must be standalone, indented at most 3 spaces, with the
-  body starting with `@code`. Blank lines between the comment and its heading
-  are fine; any other text in between makes it `dangling_code_annotation`.
-- One declaration may carry multiple `@doc` tags and one heading multiple
-  `@code` comments; each pair is an independent link.
-- Anchors must be unique within one Markdown file; symbols must be unique
-  among annotated declarations in one TypeScript file.
-
-## Procedure
-
-1. Identify the two endpoints: the exported declaration and the Markdown
-   section. If the section does not exist yet, write it first — the heading
-   text fixes the anchor.
-2. Add the `@doc` tag to the declaration's documentation comment (create the
-   documentation comment if missing), pointing at the doc file and the
-   generated heading anchor.
-3. Add the `@code` comment directly above the heading, pointing back at the
-   code file and the scanner-produced canonical ID.
-4. Verify with `docbridge check`. The link is correct only when no diagnostic
-   mentions either endpoint.
-
-## Diagnosing check failures
-
-| Diagnostic                                           | Meaning                              | Usual fix                                             |
-| ---------------------------------------------------- | ------------------------------------ | ----------------------------------------------------- |
-| `doc_file_not_found` / `code_file_not_found`         | target file not in the managed set   | fix the path, or extend `docbridge.config.json` globs |
-| `doc_anchor_not_found`                               | file found, anchor wrong             | regenerate the anchor from the exact heading text     |
-| `doc_backlink_not_found` / `code_backlink_not_found` | one direction missing                | add the missing `@code` or `@doc` side                |
-| `unsupported_declaration`                            | `@doc` on an unsupported declaration | move the tag to a supported declaration               |
-| `dangling_code_annotation`                           | text between `@code` and the heading | move the comment directly above the heading           |
-| `invalid_link_target`                                | malformed `file#fragment`            | rewrite the target per the rules above                |

package/templates/skills/docbridge-link/SKILL.md

@@ -1,80 +0,0 @@
----
-name: docbridge-link
-description: Link existing Markdown specification sections to existing supported code declarations. Use for docs-first candidate discovery, section-level confirmation, and adding @doc/@code annotations to existing projects.
----
-
-# docbridge-link
-
-Create DocBridge annotations for existing docs and code. Work docs-first: choose
-Markdown sections that look like specifications, then propose supported
-TypeScript, Swift, Dart, or Rust declarations that implement or represent each
-section.
-
-Run DocBridge with the project's native invocation: `docbridge` on `PATH`, a
-repo recipe such as `just check`, or
-`bun run /path/to/docbridge/src/cli/index.ts`.
-
-## Procedure
-
-1. **Determine docs scope.** Use the scope confirmed by `docbridge-adopt` when
-   available. Otherwise, inspect the repository and ask the user to confirm the
-   docs directories/files before proposing links.
-
-2. **Find section candidates.**
-   - Prioritize unlinked sections.
-   - Include already linked sections at lower priority when an additional link
-     may be justified.
-   - Ignore sections that are clearly prose-only, changelog entries, runbook
-     steps, or project process unless the user says they are specifications.
-
-3. **For each candidate section, propose up to three code symbols.** Base the
-   ranking on:
-   - heading text and section body
-   - exported symbol names
-   - existing JSDoc and nearby comments
-   - file paths and directory names
-   - implementation body only when the surrounding information is insufficient
-
-   Include both:
-   - why the symbol may match
-   - what remains uncertain
-
-4. **Ask for section-level decisions.** Present 5-10 section candidates at a
-   time. For each section the user can choose:
-   - adopt: select one or more code symbols to link
-   - exclude: do not link this section
-   - hold: keep undecided for later
-
-   The user may also name a symbol not in the proposed top three.
-
-5. **Classify no-match sections.** If no reasonable exported symbol exists,
-   report the likely reason instead of forcing a link:
-   - not implemented yet
-   - spans multiple symbols without a clear public representative
-   - likely stale docs
-   - not a specification section
-   - target appears internal or not exported
-
-6. **Add annotations only after confirmation.**
-   - Add `@code` directly above the Markdown heading, as the nearest comment
-     to the heading.
-   - Add `@doc` to the code declaration's documentation comment.
-   - If the declaration has no documentation comment, create a minimal one
-     containing only `@doc`, using the language's documentation comment form.
-   - If the pair already exists on one side, show it and, after confirmation,
-     add the missing backlink.
-   - Preserve existing annotations; do not replace or clean up suspicious links
-     in this skill.
-
-7. **Verify.** Run `docbridge check`, then inspect the affected links with
-   `docbridge context` or `docbridge graph --json --include-content` for the
-   changed files. Report any remaining diagnostics or semantic uncertainty.
-
-## Boundaries
-
-- Do not split Markdown sections or rename headings. If a section is too broad
-  or ambiguous, classify it as held or no-match.
-- Multiple code symbols may link to one docs section when each role is clear.
-- One code symbol may link to multiple docs sections when each section covers a
-  distinct specification aspect.
-- Do not link solely because names are similar.