docbridge 0.8.0 → 0.10.0

package/docs/README.md

@@ -0,0 +1,67 @@
+# DocBridge Documentation
+
+Choose the shortest path for the task. User guides explain how to achieve an
+outcome; specifications define exhaustive behavior; integration recipes adapt
+the general workflow to a particular tool.
+
+[日本語の入口](ja/README.md)
+
+## Use DocBridge
+
+These English guides are also installed with the npm package and available
+through `docbridge docs show <name>`:
+
+- [Getting started](user/getting-started.md) — install, configure, and validate
+  the first reciprocal link
+- [Configuration](user/configuration.md) — choose roots, patterns, languages,
+  and visibility
+- [Linking](user/linking.md) — select sections, author annotation pairs, and
+  review their meaning
+- [Commands](user/commands.md) — choose between check, related, context, graph,
+  docs, and upgrade
+- [Automation](user/automation.md) — connect agents, Git hooks, and CI
+- [Troubleshooting](user/troubleshooting.md) — recover from configuration,
+  scanner, parsing, and link diagnostics
+
+## Automate and integrate
+
+- [Claude Code](integrations/claude-code.md)
+- [Codex](integrations/codex.md)
+- [Continuous integration](integrations/ci.md)
+- [VS Code-compatible extension](../editors/vscode/README.md)
+
+These pages contain client-specific setup and runnable recipes. The general
+editing and gate policy stays in [Automation](user/automation.md).
+
+## Understand the contracts
+
+Normative command, configuration, diagnostic, scanning, link-resolution, and
+language-server behavior lives under [Specifications](specs/cli.md). Start
+with the specification for the interface whose exact contract you need:
+
+- [CLI](specs/cli.md)
+- [Configuration](specs/configuration.md)
+- [Annotations](specs/annotations.md)
+- [Scanning](specs/scanning.md)
+- [Link resolution](specs/link-resolution.md)
+- [Link manifest](specs/link-manifest.md)
+- [Diagnostics](specs/diagnostics.md)
+- [Language server](specs/lsp.md)
+
+## Contribute to DocBridge
+
+- [Contributor guide](../CONTRIBUTING.md)
+- [Module architecture](contributing/architecture.md)
+- [Writing guidelines](contributing/writing.md)
+- [Documentation guidelines](contributing/documentation.md)
+- [Testing](contributing/testing.md)
+- [Commit messages](contributing/commits.md)
+- [Pull requests](contributing/pull-requests.md)
+- [Releasing](contributing/releasing.md)
+- [Self-audit baseline](contributing/self-audit.md)
+- [Dogfooding review, September 2026](reports/2026-09-dogfooding-review.md)
+
+Architectural choices are recorded in [Decisions](decisions/README.md).
+Completed delivery records are archived under
+[Completed plans](plans/done/README.md). They are historical context, not
+current user instructions.

package/docs/user/automation.md

@@ -0,0 +1,104 @@
+---
+description: Automate DocBridge with coding agents, Git hooks, and CI.
+---
+
+# Automation
+
+Use automation after `docbridge check` passes locally. Keep link validity as a
+hard gate, and treat unchanged linked counterparts as review obligations rather
+than automatic failures.
+
+<!-- @code src/cli/init.ts#runInitWithAgent -->
+
+## Invoking DocBridge
+
+Run DocBridge through the project's normal command: `docbridge` on `PATH`, a
+package-manager script, or a repository recipe such as `just check`. An agent
+can discover the interface from `docbridge --help` and the packaged guides from
+`docbridge docs list`.
+
+Keep the DocBridge version in one place, such as the package manifest's
+development dependency or a single version file that hooks and CI read. When
+the same pin is copied into several scripts, the copies drift apart. After
+changing the version, run `docbridge upgrade --check` to confirm that the CLI
+and the installed skill match; see `docbridge docs show commands`.
+
+`docbridge init` can create `docbridge.config.json` and install the
+distributable `docbridge` skill for Codex, Claude Code, or both. To have an
+agent choose the initial documentation and code scope, run:
+
+```sh
+docbridge init-with-agent --agent-target codex
+```
+
+Use `claude` or `both` for the other supported targets. The command installs
+the skill and prints the next command or prompt; it does not launch an agent.
+
+<!-- @code src/core/context.ts#context -->
+<!-- @code src/core/related.ts#related -->
+
+## Editing workflow
+
+Before editing a linked file, read its counterpart:
+
+```sh
+docbridge context path/to/file
+```
+
+After editing, inspect the change set:
+
+```sh
+git diff --name-only | docbridge related --stdin --gate
+```
+
+For every reported counterpart, make one explicit judgment:
+
+- update it when behavior, contract, format, or constraints changed;
+- leave it unchanged with a written, content-based justification when every
+  documented statement still holds; or
+- fix the annotation pair when the link points to the wrong section or symbol.
+
+Never remove a valid link just to silence the gate.
+
+## Git hooks
+
+Put shared checks in repository hooks rather than one agent's configuration.
+A pre-commit hook can run `docbridge check` as a blocking validity gate and
+then report related files from the staged set:
+
+```sh
+git diff --cached --name-only | docbridge related --stdin --gate
+```
+
+Add `docbridge context --stdin` when the report should include counterpart
+content. Keep the related-file stage informational while the graph is sparse;
+hooks must not rewrite files or replace the repository's normal quality gates.
+Hooks can be bypassed, so pull-request CI remains the enforcement point.
+
+## Continuous integration
+
+Run `docbridge check` over the whole project as the hard link-validity gate. A
+pull-request workflow can also pass the base-to-head file list to
+`related --stdin --gate` and attach `context` output for reviewers. Fetch enough
+Git history for the comparison and calculate the changed paths from the PR's
+base and head commits.
+
+The general contract belongs here. Copyable GitHub Actions steps and sticky PR
+comment behavior belong in the [CI integration recipe](https://github.com/salan70/docbridge/blob/main/docs/integrations/ci.md).
+
+## Agent-specific recipes
+
+The distributable skill is under
+[`templates/skills/docbridge`](https://github.com/salan70/docbridge/tree/main/templates/skills/docbridge).
+The recipes below live in the repository, not in the installed package. For
+client setup and prompt examples, use the specialized recipes:
+
+- [Claude Code](https://github.com/salan70/docbridge/blob/main/docs/integrations/claude-code.md)
+- [Codex](https://github.com/salan70/docbridge/blob/main/docs/integrations/codex.md)
+- [CI](https://github.com/salan70/docbridge/blob/main/docs/integrations/ci.md)
+
+## Next steps
+
+- Read `docbridge docs show commands` for command output and exit behavior.
+- Read `docbridge docs show linking` before adding or reviewing links.
+- Read `docbridge docs show troubleshooting` when an automated check fails.

package/docs/user/commands.md

@@ -1,5 +1,5 @@
 ---
-description: Choose between check, related, context, and graph.
+description: Choose between check, related, context, graph, docs, and upgrade.
 ---
 
 # Commands
@@ -18,9 +18,9 @@ handled before project scanning, while each command validates its own options.
 ### `check`: validate the project
 
 Run `docbridge check` before committing and in CI. It validates configuration,
-annotations, targets, and reciprocal links. Add `--audit` to include warnings
-for undocumented code declarations and unlinked Markdown sections. Add
-`--json` for machine-readable diagnostics.
+annotations, targets, reciprocal links, and the optional link manifest. 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 -->
 
@@ -57,8 +57,71 @@ Use `graph` for endpoints, edges, reciprocal pairs, and unresolved links across
 the project. Passing file paths scopes the result to those files and their
 direct counterparts. `--include-content` is available only with `--json`.
 
+<!-- @code src/cli/upgrade.ts#runUpgrade -->
+
+### `upgrade`: keep the CLI and skills in step
+
+Run `docbridge upgrade --check` after a DocBridge release, or whenever a
+project still carries agent assets from an older layout:
+
+```sh
+docbridge upgrade --check
+```
+
+It is read-only. It reports the installed version, the latest stable release on
+npm, the command to upgrade the CLI with your package manager, the state of the
+managed `docbridge` skill, any leftover legacy skill directories, symlinks, and
+files you have edited locally.
+
+DocBridge never upgrades itself and never runs a package manager for you.
+Upgrade the CLI with the printed command, then re-run `docbridge upgrade` so the
+managed skill is reconciled from the new binary:
+
+```sh
+docbridge upgrade --dry-run
+docbridge upgrade --force --yes
+```
+
+`--dry-run` prints the full plan without writing files. Without `--force`, an
+existing skill directory is preserved and the migration is reported as pending.
+`--force` replaces the managed `docbridge` skill and removes only the five known
+legacy skill directories, and only when they are ordinary directories reached
+through ordinary directories. A symlink, a regular file carrying a legacy name,
+and anything under a symlinked `.agents/skills` or `.claude/skills` are reported
+and left alone. Replacing the skill reproduces the packaged template exactly, so
+a file you added inside it does not survive `--force`; keep local notes outside
+the managed directory, or make it a symlink to a copy you own. Destructive operations ask for confirmation unless `--yes` is
+passed, and a non-interactive run without `--yes` fails instead of replacing
+local edits. Configuration, hooks, CI recipes, and your own files are never
+touched.
+
+## Update notification
+
+On an interactive terminal, DocBridge prints one line to stderr when a newer
+stable release is available. The check uses a short timeout and a daily
+per-user cache, fails silently when offline, and never changes a command's
+stdout or exit code. It is suppressed in CI, for `--json` output, for the
+language server, when output is redirected, and when
+`DOCBRIDGE_NO_UPDATE_CHECK=1` is set. That variable also stops `upgrade` from
+contacting the registry, so it reports the latest version as unknown and only
+describes local asset state.
+
 ## Common options
 
 The project commands accept `--root <path>` when invoked outside the project
 root. Run `docbridge <command> --help` for the exact options and exit behavior
 of a command.
+
+## Documentation commands
+
+Use `docbridge docs list` to see the version-matched guides installed with the
+CLI and `docbridge docs show <name>` to print one. The canonical names are
+`getting-started`, `configuration`, `linking`, `commands`, `automation`, and
+`troubleshooting`.
+
+## Next steps
+
+- Read `docbridge docs show linking` before creating or reviewing a pair.
+- Read `docbridge docs show automation` before adding repository automation.
+- Read `docbridge docs show troubleshooting` when a command reports a failure.
+- Run `docbridge upgrade --check` after upgrading the CLI.

package/docs/user/configuration.md

@@ -1,5 +1,5 @@
 ---
-description: "Configure docbridge.config.json: roots, includes, excludes, languages."
+description: "Configure docbridge.config.json: roots, include patterns, languages, visibility."
 ---
 
 # Configuration
@@ -40,7 +40,7 @@ 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
+`unsupported_declaration`. See `docbridge docs show linking` for the
 per-language rules, including Dart's leading-underscore privacy.
 
 <!-- @code src/core/glob.ts#collectFiles -->
@@ -71,7 +71,8 @@ coverage gaps rather than every implementation detail or general prose file.
 
 ## Validate changes
 
-Run `docbridge check` after editing configuration. A missing, malformed, or
-schema-invalid configuration produces `config_file_invalid`. Use
+Run `docbridge check` after editing configuration. A missing or unreadable
+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.

package/docs/user/getting-started.md

@@ -66,10 +66,10 @@ A clean graph exits `0`. Broken links and invalid configuration exit `1`.
 ## Next steps
 
 - 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 linking` to choose sections, write annotations, and
+  review links for meaning.
 - Read `docbridge docs show commands` to choose an inspection command.
+- Read `docbridge docs show automation` before adding hooks, CI, or an agent
+  workflow.
 - Read `docbridge docs show troubleshooting` when `check` reports a diagnostic.
 - Add `docbridge check` to CI after the local graph passes.

package/docs/user/linking.md

@@ -0,0 +1,202 @@
+---
+description: Choose, create, and semantically review @doc and @code links.
+---
+
+# Linking
+
+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.
+
+## 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.
+
+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
+annotations to encode branch, review, or release policy.
+
+## Propose candidates docs-first
+
+1. Confirm which documentation directories are in scope.
+2. Prioritize unlinked specification sections.
+3. Propose no more than three code symbols per section, with a short reason and
+   any uncertainty.
+4. Classify each section as adopt, exclude, or hold.
+5. Add annotations only after the section-level decision is clear.
+
+Use `docbridge check --audit` to find unlinked sections and undocumented public
+symbols. Audit diagnostics are candidates for judgment, not instructions to
+link every item.
+
+<!-- @code src/core/links.ts#parseLinkTarget -->
+
+## Target grammar
+
+Both annotations take a project-root-relative `file#fragment` target:
+
+- use `/` path separators;
+- include both file and fragment;
+- do not target the file that contains the annotation (same-file targets are invalid);
+- do not use `./`, `../`, absolute paths, or whitespace inside the target; and
+- optionally add human-readable text after the target.
+
+One declaration may have multiple `@doc` tags, and one heading may have
+multiple `@code` comments. Each pair is independent. Repeating the same target
+from the same source produces `duplicate_link`.
+
+## Code to documentation
+
+Put `@doc` in the declaration's documentation comment:
+
+```ts
+/** @doc docs/auth.md#login-flow */
+export function login(): void {}
+```
+
+```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) {}
+```
+
+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.
+
+### 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.
+
+Members use type-qualified IDs without parameter signatures, such as
+`AuthService.login` and `AuthService.constructor`. Visibility defaults to
+`public` and `protected`; configure `private` explicitly. Anonymous default
+exports, namespaces, re-exports, multi-declarator constants, computed member
+names, enum members, and call/index/construct signatures are not endpoints.
+
+### Swift declarations
+
+Supported forms include top-level and member types, functions, variables,
+constants, initializers, actors, protocols, and extension members. Visibility
+defaults to `public` and `open`; configure `internal` explicitly. Member IDs
+include argument labels, for example
+`AuthService.login(email:password:)`.
+
+### Dart declarations
+
+Supported forms include top-level functions, accessors, and variables; classes,
+enums, mixins, constructors, fields, and methods; and extension members. Dart
+supports public endpoints only. Any canonical-ID segment beginning with `_` is
+private. Member IDs omit parameter signatures; setters end in `=`, the unnamed
+constructor ends in `.new`, and named constructors retain their name.
+
+### Rust declarations
+
+Supported forms are modules, structs, enums, free functions, and inherent
+`impl` methods. Visibility defaults to unrestricted `pub`; configure `private`
+to include non-`pub` items. Trait definitions and implementations, macros,
+constants, statics, unions, and extern blocks are not endpoints. IDs use `::`
+qualification, such as `TypingEngine::advance`.
+
+<!-- @code src/core/markdown.ts#scanMarkdown -->
+
+## Documentation to code
+
+Place a standalone HTML comment immediately before the linked ATX heading.
+Zero to three leading spaces and blank lines before the heading are allowed;
+other intervening content produces `dangling_code_annotation`.
+
+```md
+<!-- @code src/auth.ts#login -->
+
+## Login Flow
+```
+
+Use the scanner-produced canonical symbol ID exactly.
+
+## Heading anchors and reciprocity
+
+DocBridge creates anchors from ATX headings only. It lowercases the heading,
+collapses runs of whitespace and punctuation to `-`, preserves Unicode letters
+and numbers, and removes leading and trailing hyphens. `## Login Spec (v2)` is
+`#login-spec-v2`.
+
+Empty headings have no anchor; a `@code` annotation attached to an empty
+heading produces `dangling_code_annotation`. Duplicate non-empty anchors in
+one file produce `duplicate_doc_anchor`; DocBridge does not add GitHub-style
+numeric suffixes.
+Each direction is validated independently, so a resolving target can still
+report a missing backlink. Run `docbridge check` after every edit.
+
+<!-- @code src/core/link-manifest.ts#loadLinkManifest -->
+
+## Declare links in a manifest
+
+Some teams do not accept tool-specific markers in their source files. Those
+projects can declare every link in an optional root file
+`docbridge.links.json` and write no annotation at all. Annotation linking
+stays the recommended style, and the two styles work together in one project.
+
+```json
+{
+  "$schema": "./node_modules/docbridge/schemas/docbridge.links.schema.json",
+  "links": [
+    {
+      "code": "src/auth.ts#AuthService.login",
+      "doc": "docs/auth.md#login-flow",
+      "note": "optional, for human readers only"
+    }
+  ]
+}
+```
+
+One entry declares both directions, so a manifest link never reports a missing
+backlink. DocBridge checks only that both targets exist. `check`, `related`,
+`context`, `graph`, and editor navigation treat the result exactly like an
+annotation pair.
+
+A `code` target whose file is in scope but whose symbol does not exist reports
+`code_symbol_not_found` with a `Did you mean` suggestion; this diagnostic is
+specific to the manifest. An entry that repeats an existing link, whether from
+another entry or from an annotation, reports `duplicate_link`.
+
+The cost is that a declared link is invisible to someone reading the code or
+the document. Run `related --gate` in continuous integration so a change to
+one side still surfaces the other.
+
+## Semantic link review
+
+`docbridge check` proves mechanics. A semantic review asks whether each linked
+section and symbol still describe the same behavior or contract.
+
+1. Run `docbridge graph --json --include-content` and read diagnostics first.
+2. Review one documentation file at a time and read both endpoints.
+3. Compare behavior, inputs, outputs, constraints, and design intent.
+4. Report High findings for wrong or stale links, Medium for partial or
+   ambiguous relationships, and Low for cleanup or excessive linkage.
+5. Include both endpoints, evidence, and a recommended fix for each finding.
+
+Do not edit or remove annotations merely because the relationship is uncertain.
+Prefer fewer precise links over broad many-to-many relationships.
+
+## Next steps
+
+- Run `docbridge docs show commands` to inspect the graph or related content.
+- Run `docbridge docs show automation` before wiring hooks or CI.
+- Run `docbridge docs show troubleshooting` for named diagnostics.

package/docs/user/troubleshooting.md

@@ -10,14 +10,23 @@ stderr. Use `docbridge <command> --help` for invocation errors and
 
 ## Configuration errors
 
-`config_file_invalid` means `docbridge.config.json` is missing, malformed, or
-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.
+`config_file_invalid` means `docbridge.config.json` is missing, cannot be read
+(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.
 
-`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.
+`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
+value DocBridge rejects, such as an unsupported language, an empty pattern
+list, or a pattern with the wrong file suffix. Compare the file with
+[Configuration](configuration.md), and confirm that include patterns match
+real files relative to the selected `--root`.
+
+The same three codes apply to an optional `docbridge.links.json` link manifest.
+When that file cannot be read or parsed, the CLI prints guidance to repair or
+delete it. See [Linking](linking.md) for its format.
 
 ## Scanner errors
 
@@ -32,21 +41,36 @@ 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.
 
+`code_parse_error` means a TypeScript, Swift, Dart, or Rust source file has a
+syntax error. 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
+parse.
+
+`file_read_error` means a file matched by the configuration could not be read,
+for example because of permissions or a broken symbolic link. The message
+contains the operating-system reason.
+
 ## 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                           |
+| 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         |
+| `code_symbol_not_found`                              | manifest names a symbol that is not there | rename the entry, or follow the `Did you mean` suggestion |
+| `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 linking`               |
+| `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                               |
+
+`undocumented_symbol` and `unlinked_doc_section` appear only with
+`docbridge check --audit`. They are warnings that list unlinked endpoints, not
+authoring errors.
 
 Use `docbridge graph --json` to inspect resolved and one-way edges. Use
 `docbridge context <file>` to confirm which counterpart content DocBridge can
@@ -59,3 +83,11 @@ currently resolve.
 Unknown commands, unknown options, missing values, invalid roots, and missing
 required inputs exit `1`, write to stderr, and leave stdout empty. These are not
 included in diagnostic JSON because the project scan did not run.
+
+`docbridge upgrade --force` is one of these when it would replace or remove a
+managed skill directory without a terminal to confirm on. Re-run it with
+`--yes`, or inspect the plan first with `docbridge upgrade --check` or
+`docbridge upgrade --force --dry-run`.
+
+When `docbridge docs show <name>` rejects a name, use a name printed by
+`docbridge docs list`. Former guide names are no longer accepted.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docbridge",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "A CLI that links Markdown specifications and code declarations. Runs on Node.js and Bun.",
   "keywords": [
     "bun",
@@ -33,13 +33,6 @@
     "LICENSE"
   ],
   "type": "module",
-  "scripts": {
-    "docbridge": "bun run src/cli/index.ts",
-    "check": "bun run src/cli/index.ts check",
-    "check:example": "bun run src/cli/index.ts check --root examples/typescript",
-    "test": "bun test",
-    "build": "bun build src/cli/index.ts --outdir dist --target node"
-  },
   "devDependencies": {
     "@types/bun": "^1.3.14",
     "ajv": "^8.20.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"
+        }
+      }
+    }
+  }
+}