docbridge 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-08-18
+
+### Added
+
+- The VS Code-compatible extension `salan70.docbridge` is published on Visual
+  Studio Marketplace.
+- Packaged user docs now cover linking workflow and semantic link review
+  (`docbridge docs show linking-workflow`, `docbridge docs show link-review`),
+  plus supported and unsupported `@doc` declaration forms, the heading-anchor
+  algorithm, and named link-authoring diagnostic codes.
+- Human-readable `docbridge check` output ends with a pointer to
+  `docbridge docs show troubleshooting`. `check --json` is unchanged.
+
+### Changed
+
+- `docbridge init` and `docbridge init-with-agent` install one skill,
+  `docbridge`, instead of the five companion skills. The skill routes adopt,
+  discover-and-link, annotate, review, and sync work; facts about the binary
+  come from `docbridge docs show`.
+
+### Fixed
+
+- `just package-vsix` bundles `vscode-languageclient` into the editor client.
+  Packaging with `--no-dependencies` previously omitted the module, so the
+  installed VSIX failed to activate.
+- `docs/user/annotations.md` no longer claims GitHub-style numeric suffixes for
+  duplicate headings. Duplicate anchors in one file are `duplicate_doc_anchor`.
+
+### Upgrading
+
+- Existing installs keep the five legacy skill directories
+  (`docbridge-adopt`, `docbridge-annotate`, `docbridge-link`,
+  `docbridge-review`, `docbridge-sync`) until `docbridge init --force` is run.
+  Review locally edited copies first. Symlinked skill directories are reported
+  and left untouched.
+
 ## [0.7.0] - 2026-08-16
 
 ### Added
@@ -315,7 +351,8 @@ Initial release of the SpecLink CLI.
 - `speclink check` command with `--root`, `--json`, and `--audit` options.
 - `speclink --version` (alias `-v`) and `speclink --help` (alias `-h`).
 
-[Unreleased]: https://github.com/salan70/docbridge/compare/v0.7.0...HEAD
+[Unreleased]: https://github.com/salan70/docbridge/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/salan70/docbridge/releases/tag/v0.8.0
 [0.7.0]: https://github.com/salan70/docbridge/releases/tag/v0.7.0
 [0.6.1]: https://github.com/salan70/docbridge/releases/tag/v0.6.1
 [0.6.0]: https://github.com/salan70/docbridge/releases/tag/v0.6.0

package/README.md

@@ -40,9 +40,8 @@ Run first-time setup in the project root:
 bunx docbridge init
 ```
 
-For agent-guided adoption, install `docbridge-adopt` and print setup commands.
-The `docbridge-adopt` skill finishes adoption and installs the remaining
-DocBridge skills after scope is confirmed:
+For agent-guided adoption, install the `docbridge` skill and print setup
+commands. The skill routes adopt, link, review, and sync work:
 
 ```sh
 bunx docbridge init-with-agent
@@ -316,11 +315,10 @@ DocBridge's link graph is built to be consumed by AI coding agents:
 - [docs/integrations](docs/integrations) — recipes for Claude Code, Codex,
   and CI: gate triage with `docbridge related --gate`, counterpart content with
   `docbridge context`, and PR reporting.
-- [templates/skills](templates/skills) — distributable agent skills installed by
-  `docbridge init`; `docbridge init-with-agent` installs `docbridge-adopt`
-  alone, then `docbridge-adopt` installs the companion skills:
-  `docbridge-annotate`, `docbridge-link`, `docbridge-review`, and
-  `docbridge-sync`.
+- [templates/skills](templates/skills) — the distributable `docbridge` skill
+  installed by `docbridge init` and `docbridge init-with-agent`. Facts about
+  the binary live in `docbridge docs show`. Existing five-skill installs remain
+  until `docbridge init --force`.
 
 This repository dogfoods the skills under `.claude/` and `.agents/`, and keeps
 its guardrail in the Git `pre-commit` hook under `.githooks/` rather than in
@@ -340,24 +338,24 @@ options; the project root comes from the editor's `initialize` request.
 `docbridge check` is unchanged.
 
 A VS Code-compatible extension lives in [editors/vscode](editors/vscode). It
-packages the language server into a VSIX for VS Code and Cursor. The extension
-has not yet been published to VS Code Marketplace. Until the first Marketplace
-publication, stage the supported `dist/bin/darwin-arm64` and
-`dist/bin/linux-x64` scanner artifacts, then build and install the VSIX
-locally:
+packages the language server into a VSIX for VS Code and Cursor. Install
+[`salan70.docbridge`](https://marketplace.visualstudio.com/items?itemName=salan70.docbridge)
+from VS Code Marketplace. Bun must be available to the editor; set
+`docbridge.bunPath` if the GUI cannot find `bun` on `PATH`.
+
+Contributors can still stage the supported `dist/bin/darwin-arm64` and
+`dist/bin/linux-x64` scanner artifacts and build a local VSIX:
 
 ```sh
 just package-vsix
 just verify-vsix
 ```
 
-Install the generated file from `editors/vscode/.tmp/out/` with **Extensions:
-Install from VSIX...** in VS Code or Cursor. The first Marketplace publication
-is intentionally manual; the repository provides a publish command for that
-release process. Open VSX delivery is out of scope. Zed integration is tracked
-separately and is not yet implemented. MCP delivery is out of scope until a
-concrete consumer requires a long-lived tool server. Full LSP behavior is specified in
-[docs/specs/lsp.md](docs/specs/lsp.md).
+Registry publication remains manual (`VSCE_PAT=<token> just
+publish-vscode-extension`). Open VSX delivery is out of scope. Zed integration
+is tracked separately and is not yet implemented. MCP delivery is out of scope
+until a concrete consumer requires a long-lived tool server. Full LSP behavior
+is specified in [docs/specs/lsp.md](docs/specs/lsp.md).
 
 ## Diagnostics
 
@@ -417,7 +415,6 @@ Completed v0.1–v0.6 capabilities are documented above and in
 
 Remaining editor delivery work:
 
-- Publish the first verified VSIX to VS Code Marketplace
 - Follow-up automation for GitHub Release VSIX attachment and registry
   publishing after the manual flow is proven
 - Add a separate Zed integration path

package/dist/bin/darwin-arm64/SHA256SUMS

@@ -1,3 +1,3 @@
-bc9e7548f993e48d280c3a487be4cc90a3e6549491c6f93f0e518ccc4239d991  docbridge-swift-scanner
-ceb237b7e5b2047d091f961c0a43ba436b8c624c741cc7f864e5783d9248a4eb  docbridge_dart_scanner
+4b0ab3efbe865e9fb0cc48a6a0d37146c72a4255479e1c78c27b6c20e7e62604  docbridge-swift-scanner
+c764c46477f522c8a82b62e629ff69907c0511fbc58b005ee6eba04d0e08dbef  docbridge_dart_scanner
 a1b129d980c981a2d24f0c9682e614a9695d4e9f9b8174d61b0dacb3fc9e3c79  docbridge-rust-scanner

package/dist/bin/linux-x64/SHA256SUMS

@@ -1,3 +1,3 @@
-114f780cebfb8834f200ef60f3a828ca7dc4668b23f6e646971e3e56c377b37a  docbridge-swift-scanner
+9b7f3eea8df6ec2a07bd243a46b149fe3468240c6e0293390dc58594140519de  docbridge-swift-scanner
 095c4c172da615be155bee15dcce7b99faaf2a8bb26f3cad3e0b17881495ddf2  docbridge_dart_scanner
 d89a1146ed10dcb01151ef5351a746862c3955286431c47f3cf91cf6639866ba  docbridge-rust-scanner

package/dist/index.js

@@ -175581,7 +175581,7 @@ import { join as join9, resolve as resolve4 } from "node:path";
 // package.json
 var package_default = {
   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",
@@ -179143,18 +179143,18 @@ import { readdirSync as readdirSync3, readFileSync as readFileSync4 } from "node
 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 { existsSync as existsSync2, lstatSync as lstatSync2, 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 = [
+var INIT_SKILL_NAMES = ["docbridge"];
+var LEGACY_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);
@@ -179198,16 +179198,16 @@ function planInitCommand(input) {
     exitCode = 1;
   }
   const skillOps = planSkillOperations({
-    command: input.command,
     projectRoot: input.projectRoot,
     packageRoot,
     agentTarget,
-    options: input.options
+    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 docbridge-adopt confirm scope and create or improve docbridge.config.json.");
+    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;
@@ -179262,7 +179262,7 @@ function listDistributableSkills(packageRoot) {
   } catch {
     return [];
   }
-  return entries.filter((entry) => entry.startsWith("docbridge-")).filter((entry) => existsSync2(join5(skillsRoot, entry, "SKILL.md"))).toSorted();
+  return entries.filter((entry) => entry.startsWith("docbridge")).filter((entry) => existsSync2(join5(skillsRoot, entry, "SKILL.md"))).toSorted();
 }
 function formatInitPlan(plan) {
   const lines = [];
@@ -179359,16 +179359,20 @@ function planSkillOperations(input) {
   if (input.agentTarget === "none") {
     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) {
+    for (const skillName of INIT_SKILL_NAMES) {
       if (!availableSkills.has(skillName)) {
         continue;
       }
       const destinationDir = join5(input.projectRoot, destination, skillName);
+      const path = relative3(input.projectRoot, destinationDir);
+      if (isSymlink(destinationDir)) {
+        input.messages.push(`Skill directory ${path} is a symlink and was left in place.`);
+        continue;
+      }
       const exists = existsSync2(destinationDir);
       let action;
       let reason;
@@ -179384,10 +179388,44 @@ function planSkillOperations(input) {
       }
       operations.push({
         action,
-        path: relative3(input.projectRoot, destinationDir),
+        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 = join5(input.projectRoot, input.destination, skillName);
+    const path = relative3(input.projectRoot, destinationDir);
+    if (isSymlink(destinationDir)) {
+      input.messages.push(`Skill directory ${path} is a symlink and was left in place.`);
+      continue;
+    }
+    if (!existsSync2(destinationDir)) {
+      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;
 }
@@ -179396,27 +179434,24 @@ function buildAgentGuidance(projectRoot, agentTarget) {
   if (agentTarget === "codex" || agentTarget === "both") {
     guidance.push({
       agent: "codex",
-      destination: ".agents/skills/docbridge-adopt/",
-      oneShotCommand: `cd ${projectRoot} && $docbridge_adopt_prompt`,
+      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-adopt/",
-      oneShotCommand: `cd ${projectRoot} && /docbridge-adopt`,
+      destination: ".claude/skills/docbridge/",
+      oneShotCommand: `cd ${projectRoot} && /docbridge adopt DocBridge in this repository`,
       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 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.`;
+  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) {
@@ -179481,12 +179516,21 @@ function agentDestinations(agentTarget) {
       return [];
   }
 }
+function isSymlink(path) {
+  try {
+    return lstatSync2(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
 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}`;
@@ -179859,9 +179903,9 @@ var COMMAND_DOCS = {
   },
   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 +179922,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."
@@ -180021,7 +180065,15 @@ function hasHelpFlag(args) {
 }
 
 // src/cli/init.ts
-import { cpSync, mkdirSync as mkdirSync2, readFileSync as readFileSync5, statSync as statSync3, writeFileSync } from "node:fs";
+import {
+  cpSync,
+  lstatSync as lstatSync3,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync5,
+  rmSync,
+  statSync as statSync3,
+  writeFileSync
+} from "node:fs";
 import { join as join8, resolve as resolve3 } from "node:path";
 
 // src/core/init-discovery.ts
@@ -180494,15 +180546,31 @@ function executeFileOperation(projectRoot, operation) {
   }
 }
 function executeSkillOperation(projectRoot, packageRoot, operation) {
+  const destinationDir = join8(projectRoot, operation.path);
+  if (operation.action === "remove") {
+    try {
+      if (lstatSync3(destinationDir).isSymbolicLink()) {
+        return;
+      }
+    } catch {
+      return;
+    }
+    rmSync(destinationDir, { recursive: true, force: true });
+    return;
+  }
   if (operation.action !== "create" && operation.action !== "overwrite") {
     return;
   }
+  try {
+    if (lstatSync3(destinationDir).isSymbolicLink()) {
+      return;
+    }
+  } catch {}
   const skillName = operation.path.split("/").at(-1);
   if (skillName === undefined) {
     return;
   }
   const sourceDir = join8(packageRoot, "templates", "skills", skillName);
-  const destinationDir = join8(projectRoot, operation.path);
   mkdirSync2(destinationDir, { recursive: true });
   cpSync(sourceDir, destinationDir, { recursive: true, force: true });
 }
@@ -180560,6 +180628,7 @@ 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();

package/docs/user/agent-integration.md

@@ -5,22 +5,32 @@ 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.
+to infer documentation relationships from filenames. An agent can do the whole
+job from `docbridge --help` plus `docbridge docs list` / `docbridge docs show`.
+A project skill is an accelerator, not a prerequisite.
 
 <!-- @code src/cli/init.ts#runInitWithAgent -->
 
-## Install agent skills
+## Invoking DocBridge
 
-`docbridge init` can install the distributable skills while creating project
-configuration. To let an agent decide the scope, run:
+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`.
+
+`docbridge init` can create `docbridge.config.json` and copy the distributable
+`docbridge` skill for Codex, Claude Code, or both. 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.
+skill and prints the next command or prompt; it does not launch an agent
+process.
+
+<!-- @code src/core/context.ts#context -->
+<!-- @code src/core/related.ts#related -->
 
 ## Editing workflow
 
@@ -36,8 +46,17 @@ After editing, inspect the change set:
 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.
+For every reported counterpart, choose one of three judgments:
+
+- Update the counterpart when behavior, contract, format, or constraint
+  diverged.
+- Leave it unchanged, with a written justification that cites the counterpart
+  content, when the change is internal and every documented statement still
+  holds.
+- Fix the link itself when the annotation pair points at the wrong section or
+  symbol.
+
+Do not detach a link only to silence the gate.
 
 ## Hooks
 
@@ -68,3 +87,10 @@ 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.
+
+## Read more
+
+Run `docbridge docs list` for the full menu of packaged guides, then
+`docbridge docs show <name>` for a page. Start with `getting-started`,
+`annotations`, `linking-workflow`, `link-review`, `troubleshooting`, and
+`commands`.

package/docs/user/annotations.md

@@ -7,6 +7,23 @@ description: Write @doc and @code annotations and valid link targets.
 DocBridge links supported code declarations to Markdown headings. A complete
 pair has `@doc` on the declaration and `@code` immediately before the heading.
 
+<!-- @code src/core/links.ts#parseLinkTarget -->
+
+## Target grammar
+
+Both `@doc` and `@code` take a `file#fragment` target:
+
+- The file path is project-root-relative and uses `/` separators.
+- `./`, `../`, and absolute paths are invalid.
+- The fragment is required. File-only, fragment-only, and same-file targets
+  are invalid.
+- Optional text after the target is allowed and ignored
+  (`@doc docs/auth.md#login-spec human note`).
+
+One declaration may carry multiple `@doc` tags, and one heading may carry
+multiple `@code` comments. Each pair is an independent link. Duplicate
+annotations from the same source to the same target produce `duplicate_link`.
+
 ## Code to documentation
 
 Use a documentation path and heading anchor in a declaration's documentation
@@ -19,14 +36,106 @@ comment:
 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.
+```swift
+/// @doc docs/auth.md#login-flow
+public func login(email: String, password: String) {}
+```
+
+```dart
+/// @doc docs/auth.md#login-flow
+void login(String email, String password) {}
+```
+
+```rust
+/// @doc docs/auth.md#login-flow
+pub fn login(email: &str, password: &str) {}
+```
+
+Swift, Dart, and Rust use their normal documentation comment syntax. Paths are
+relative to the configured project root.
+
+An `@doc` on an unsupported declaration produces `unsupported_declaration`. The
+same declaration without `@doc` is ignored.
+
+### TypeScript
+
+Supported top-level exported forms: `function`, `class`, `abstract class`,
+`interface`, `type`, `enum`, `const enum`, `const` with a single declarator,
+named default `function`/`class`, and their `declare` forms in `.ts` files.
+Type members are also supported: class methods, properties, getters, setters,
+constructors, and static members; interface property and method signatures;
+and property and method signatures of a type alias written as an object type
+literal.
+
+By default, `public` and `protected` members are included; `private` members
+are included only when `include.code.typescript.visibility` lists `private`.
+TypeScript `visibility` applies only to type members. Top-level declarations
+are scoped by `export`. Members excluded by visibility are not endpoints; an
+`@doc` on one is `unsupported_declaration`.
+
+Unsupported examples include anonymous default exports, multi-declarator
+`const`, namespaces, re-exports, non-exported declarations, members whose name
+is not a plain identifier, enum members, index signatures, call and construct
+signatures, and constructor parameter properties.
+
+Canonical IDs omit parameter signatures (`AuthService.login`,
+`AuthService.constructor`).
+
+### Swift
+
+Supported forms include top-level and member `class`, `struct`, `enum`,
+`protocol`, and `actor`; top-level and member `func`, `var`, `let`, and
+`init`; and members declared in extensions, canonicalized as members of the
+extended type.
+
+By default only `public` and `open` declarations are included. `internal`
+declarations are included when `include.code.swift.visibility` lists
+`internal`. An `@doc` on a visibility-excluded declaration is
+`unsupported_declaration`.
+
+Member IDs are type-qualified and include argument labels, for example
+`AuthService.login(email:password:)`, `AuthService.refresh(_:)`, and
+`AuthService.init(email:password:)`.
+
+### Dart
+
+Supported forms include top-level functions, getters, setters, and variables;
+`class`, `enum`, `mixin`, and their members; and members declared in
+extensions, canonicalized as members of the extended type.
+
+Only public declarations are scanned. Dart marks library-private names with a
+leading `_`, so an endpoint is excluded when any segment of its canonical ID
+starts with `_`, including a public member of a `_Private` type.
+`include.code.dart.visibility` accepts only `public`. An `@doc` on a
+visibility-excluded declaration is `unsupported_declaration`.
+
+Member IDs omit parameter signatures (`AuthService.login`). Setters carry a
+trailing `=` (`AuthService.token=`). The unnamed constructor is
+`AuthService.new`; named constructors keep their name (`AuthService.guest`).
+
+### Rust
+
+Supported forms are `mod` (including nested modules), `struct`, `enum`, free
+`fn`, and inherent `impl` methods. Trait definitions, trait-impl methods,
+macros, const/static items, unions, and extern blocks are unsupported.
+
+By default only unrestricted `pub` declarations are included. A plain `fn` or
+`struct` without `pub` is not an endpoint. Non-`pub` items are included when
+`include.code.rust.visibility` lists `private`. An `@doc` on a
+visibility-excluded declaration is `unsupported_declaration`.
+
+Canonical IDs use `::` path qualification, for example `normalize`,
+`TypingEngine`, `TypingEngine::advance`, and `domain::typing`.
 
 <!-- @code src/core/markdown.ts#scanMarkdown -->
 
 ## Documentation to code
 
-Place an HTML comment immediately before the linked heading:
+Place a standalone HTML comment immediately before the linked heading. The
+comment may be indented by 0 to 3 spaces; 4 or more spaces are ignored. The
+trimmed comment body must start with `@code`. Blank lines between the comment
+and the heading are allowed. Any other text in between produces
+`dangling_code_annotation`.
 
 ```md
 <!-- @code src/auth.ts#login -->
@@ -35,16 +144,28 @@ Place an HTML comment immediately before the linked heading:
 ```
 
 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.
+Use that ID exactly in the `@code` target.
 
 ## 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.
+Anchors come from ATX headings (`#` through `######`) only. Setext headings
+have no anchors. Empty headings do not create linkable anchors; a `@code`
+attached to an empty heading is `dangling_code_annotation`.
+
+The algorithm:
+
+1. Take the heading text after the `#` markers.
+2. Lowercase with JavaScript `toLowerCase()`.
+3. Collapse runs of whitespace and punctuation to `-`. Unicode letters and
+   numbers are preserved.
+4. Strip leading and trailing `-`.
+
+Example: `## Login Spec (v2)` becomes `#login-spec-v2`. `# Login Flow`
+becomes `#login-flow`.
+
+Duplicate non-empty anchors in the same Markdown file produce
+`duplicate_doc_anchor`. The same anchor in different files is allowed.
+DocBridge does not add GitHub-style numeric suffixes.
 
 Each direction is validated independently. A target can resolve while still
 reporting a missing reciprocal annotation. Run `docbridge check` to validate