docbridge 0.7.0 → 0.8.0

package/docs/user/commands.md

@@ -13,6 +13,8 @@ Use the narrowest command for the question you need to answer.
 The first argument selects a command. Global `--help` and `--version` are
 handled before project scanning, while each command validates its own options.
 
+<!-- @code src/core/resolver.ts#check -->
+
 ### `check`: validate the project
 
 Run `docbridge check` before committing and in CI. It validates configuration,
@@ -20,6 +22,8 @@ annotations, targets, and reciprocal links. Add `--audit` to include warnings
 for undocumented code declarations and unlinked Markdown sections. Add
 `--json` for machine-readable diagnostics.
 
+<!-- @code src/core/related.ts#related -->
+
 ### `related`: find counterpart files
 
 Pass changed paths to learn which linked files may also need attention:
@@ -32,6 +36,8 @@ git diff --name-only | docbridge related --stdin
 set. It identifies review obligations; it does not decide whether the
 counterpart actually needs an edit.
 
+<!-- @code src/core/context.ts#context -->
+
 ### `context`: read counterpart content
 
 Use `context` when a human or agent needs the linked sections themselves:
@@ -43,6 +49,8 @@ docbridge context src/auth.ts
 The default Markdown output is suitable for an agent prompt. `--json` returns
 structured contexts, diagnostics, and a summary.
 
+<!-- @code src/core/graph-output.ts#graph -->
+
 ### `graph`: inspect link structure
 
 Use `graph` for endpoints, edges, reciprocal pairs, and unresolved links across

package/docs/user/configuration.md

@@ -36,6 +36,15 @@ Declare documentation patterns and at least one supported code language:
 Supported language keys are `typescript`, `swift`, `dart`, and `rust`. A project can
 enable more than one language, each with its own patterns.
 
+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`. A declaration
+excluded by visibility is not an endpoint; an `@doc` on one is
+`unsupported_declaration`. See `docbridge docs show annotations` for the
+per-language rules, including Dart's leading-underscore privacy.
+
+<!-- @code src/core/glob.ts#collectFiles -->
+
 ## Excluded files
 
 The configuration has no `exclude` property. Narrow the include patterns when

package/docs/user/getting-started.md

@@ -30,7 +30,7 @@ npx docbridge init --dry-run
 
 Then run `npx docbridge init` interactively, or use `--yes` when the detected
 scope is unambiguous. The command can create `docbridge.config.json` and install
-the distributable DocBridge skills for Codex, Claude Code, or both. It never
+the distributable `docbridge` skill for Codex, Claude Code, or both. It never
 overwrites an existing configuration.
 
 If a coding agent should choose the documentation and code scope, use:
@@ -67,5 +67,9 @@ A clean graph exits `0`. Broken links and invalid configuration exit `1`.
 
 - Read `docbridge docs show configuration` before narrowing scan scope.
 - Read `docbridge docs show annotations` for link target rules.
+- Read `docbridge docs show linking-workflow` to choose sections and propose
+  candidates.
+- Read `docbridge docs show link-review` to audit existing links for meaning.
 - Read `docbridge docs show commands` to choose an inspection command.
+- Read `docbridge docs show troubleshooting` when `check` reports a diagnostic.
 - Add `docbridge check` to CI after the local graph passes.

package/docs/user/link-review.md

@@ -0,0 +1,53 @@
+---
+description: Audit existing links for semantic correctness, not just resolution.
+---
+
+# Link Review
+
+Audit the semantic validity of the entire DocBridge graph. This is not a
+change-set or pull-request review, and it is not `related --gate` triage. It
+checks whether valid links actually connect a docs section to the code symbol
+that implements or represents that specification.
+
+`docbridge check` proves link mechanics. This review judges meaning. Do not
+rubber-stamp a link because the target resolves.
+
+## Procedure
+
+1. Build the graph:
+
+   ```sh
+   docbridge graph --json --include-content
+   ```
+
+   Read `diagnostics` first. Mechanical failures from `docbridge check`
+   should be fixed or acknowledged before relying on semantic findings.
+
+2. Batch by docs file. Review all links, but process them in batches:
+   - the docs file is the default batch boundary
+   - split a batch further when it contains too many sections or links
+   - keep notes so repeated patterns are applied consistently across batches
+
+3. Read both sides.
+   - For docs nodes, use the graph range to read the full Markdown section.
+   - For code nodes, start with graph content: documentation comment plus
+     signature. Read the implementation only when necessary to judge the
+     relationship.
+   - Compare behavior, contract, input/output, constraints, and design
+     intent.
+
+4. Classify findings.
+   - High: clearly wrong link, stale docs fixed in place by a link, or a
+     link to a section that is not a specification.
+   - Medium: partial overlap, unclear representative symbol, overly broad
+     section, or multiple linked symbols with ambiguous roles.
+   - Low: cleanup opportunity, duplicate docs, excessive links, or missing
+     explanation of why multiple links are needed.
+
+5. Report findings. For each finding include severity, the doc endpoint, the
+   code endpoint, evidence from both sides, and a recommended fix.
+
+Do not edit annotations automatically. Prefer fewer, clearer links over
+broad many-to-many links without explicit roles. Do not delete annotations
+merely to silence uncertainty; explain the uncertainty and ask for a
+decision.

package/docs/user/linking-workflow.md

@@ -0,0 +1,70 @@
+---
+description: Choose what to link and propose candidates docs-first.
+---
+
+# Linking Workflow
+
+Choose Markdown sections that look like specifications, then propose supported
+code declarations that implement or represent each section. Add annotations
+only after a section-level decision.
+
+## What to link
+
+Prefer sections that state behavior, contracts, inputs/outputs, constraints,
+user-visible behavior, or design decisions.
+
+Treat README files, changelogs, contribution docs, runbooks, logs, and
+release notes as exclusions by default unless a specific section is identified
+as a specification.
+
+Prefer supported public API declarations as link targets. TypeScript starts
+with top-level exported declarations; Swift, Dart, and Rust also support
+member endpoints. Use the scanner-produced canonical ID exactly; see
+`docbridge docs show annotations`.
+
+Do not decide project workflow policy such as branch or pull-request
+strategy.
+
+## Propose candidates
+
+1. Confirm docs scope first. Inspect the repository and agree the
+   documentation directories 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 prose-only sections, changelog entries, runbook steps, and project
+   process unless they are specifications.
+3. For each candidate section, propose at most three code symbols. Rank them
+   from heading text and section body, exported symbol names, existing
+   documentation comments, file paths, and the implementation body only when
+   that surrounding information is insufficient. For each symbol, state why it
+   may match and what remains uncertain.
+4. Present 5–10 section candidates per round. For each section, choose:
+   - adopt: select one or more code symbols to link
+   - exclude: do not link this section
+   - hold: keep undecided for later
+
+   A symbol that is not in the proposed top three may still be named.
+
+5. Classify no-match sections 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
+
+## After confirmation
+
+Add `@code` directly above the Markdown heading and `@doc` on the chosen
+declaration. If the declaration has no documentation comment, create a
+minimal one containing only `@doc`. If one side already exists, show it and
+add the missing backlink after confirmation. Preserve existing annotations;
+do not replace or clean up suspicious links in this pass.
+
+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.
+
+Verify with `docbridge check`, then inspect the affected links with
+`docbridge context` or `docbridge graph --json --include-content`.

package/docs/user/troubleshooting.md

@@ -14,31 +14,39 @@ stderr. Use `docbridge <command> --help` for invocation errors and
 does not match the schema. Run `docbridge init --dry-run` when the file is
 missing. When it exists, repair or remove it before running `check` again.
 
-Confirm that include patterns match real files relative to the selected
-`--root`, language keys are supported, and excludes do not remove an intended
-link target.
+`config_unknown_key` and `config_invalid_value` mean a present file has a key
+or value the schema rejects. Confirm that include patterns match real files
+relative to the selected `--root`, language keys are supported, and excludes
+do not remove an intended link target.
 
 ## Scanner errors
 
-Swift, Dart, and Rust use packaged scanner workers. A `scanner_unavailable` diagnostic
-usually means the installed package 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.
-
-`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.
-
-## Parsing and target errors
-
-- A missing documentation file or anchor means the `@doc` path or normalized
-  heading anchor does not resolve.
-- A missing code file or symbol means the `@code` path or canonical symbol ID
-  does not resolve.
-- A missing backlink means one direction resolves but the counterpart lacks
-  the reciprocal annotation.
-- A malformed annotation means the comment syntax or target shape is invalid.
+Swift, Dart, and Rust use packaged scanner workers. A
+`code_scanner_unavailable` diagnostic usually means the installed package
+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.
+
+## Link-authoring errors
+
+These codes appear while writing `@doc` / `@code` pairs:
+
+| 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; see `docs show annotations`       |
+| `duplicate_doc_anchor`                               | two headings share an anchor in one file | rename one heading so anchors stay unique             |
+| `duplicate_code_symbol`                              | two annotated declarations share an ID   | keep one `@doc` per canonical ID in that file         |
+| `duplicate_link`                                     | the same source repeats the same target  | remove the extra annotation                           |
 
 Use `docbridge graph --json` to inspect resolved and one-way edges. Use
 `docbridge context <file>` to confirm which counterpart content DocBridge can

package/package.json

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

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,126 @@
+---
+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 agent-integration`.
+
+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-workflow`: 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 annotations` 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 agent-integration` for the
+three-way judgment.
+
+1. Collect violations from the hook, CI comment, or
+   `git diff --name-only HEAD | 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
+`docbridge docs show link-review`.
+
+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 agent-integration` — invocation, gate judgment, hooks, CI
+- `docbridge docs show annotations` — `@doc` / `@code` rules
+- `docbridge docs show linking-workflow` — docs-first candidate discovery
+- `docbridge docs show link-review` — semantic audit
+- `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

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                |