docbridge 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -7,6 +7,114 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-09-23
+
+### Added
+
+- An optional root file `docbridge.links.json` declares links without any
+  annotation in code or Markdown, for projects that do not accept
+  tool-specific markers in their source files. One entry declares both
+  directions, so DocBridge checks only that both targets exist and reports no
+  missing backlink. `check`, `related`, `context`, `graph`, `--audit`, and
+  editor navigation treat a declared link like an annotated one, and both
+  styles can be used in one project. A `code` target can name a type member in
+  all four supported languages. Annotation linking remains the recommended
+  style, and a declared link is invisible to a reader of either file, so
+  `related --gate` in continuous integration is the remaining safety net.
+- `code_symbol_not_found` reports a manifest `code` target whose file is in
+  scope but whose canonical ID does not exist, located at the manifest entry
+  and carrying a `Did you mean` suggestion.
+- `docbridge upgrade` reports version drift and reconciles managed agent
+  assets. `--check` is a read-only diagnostic covering the installed version,
+  the latest stable release, package-manager upgrade guidance, the managed
+  `docbridge` skill state, leftover legacy skill directories, symlinks, and
+  locally modified files. `--dry-run` prints the full plan, and `--force`
+  replaces the managed skill and removes only the five known legacy skill
+  directories when they are ordinary directories reached through ordinary
+  directories. Every path component below the project root is checked, so a
+  symlinked `.agents/skills` or `.claude/skills` can never route a write or a
+  removal outside the selected project. Symlinks and regular files carrying a
+  legacy name are reported and preserved, replacing the managed skill reproduces
+  the packaged template exactly, destructive operations require `--yes` or an
+  interactive confirmation, and configuration, hooks, CI recipes, and user files
+  are never touched.
+- Human-readable terminal invocations print one stderr notice when a newer
+  stable release is published on npm. The lookup uses a bounded timeout and a
+  daily per-user cache, fails silently offline, and is suppressed in CI, for
+  `--json` output, for `lsp` and `upgrade`, for non-TTY output, and when
+  `DOCBRIDGE_NO_UPDATE_CHECK=1` is set. That variable also stops `upgrade` from
+  contacting the registry. Command stdout and exit codes are unchanged. Upgrade
+  guidance is derived from the project the command acted on (`--root`) and the
+  current directory, so a project dependency invoked from elsewhere is not
+  mistaken for a global install.
+- A documentation hub, matching Japanese task guides, and the read-only
+  `just check-docs` structural gate provide a maintained path through user,
+  integration, specification, and contributor documentation.
+
+### Changed
+
+- `docbridge docs show` no longer accepts the 0.8.0 names `linking-workflow`
+  and `link-review`, or the older names `annotations` and `agent-integration`.
+  Use `linking` for the first three and `automation` for `agent-integration`.
+  Projects with a 0.8.0 `docbridge` skill should refresh it with
+  `docbridge upgrade --force` because that skill calls the removed names.
+- Packaged user documentation is consolidated into six task-oriented names:
+  `getting-started`, `configuration`, `linking`, `commands`, `automation`, and
+  `troubleshooting`.
+- `just vscode-lsp` and `just cursor-lsp` build their VSIX with the same
+  implementation release packaging uses, in a local mode that requires only the
+  host platform's staged scanner binaries. Release packaging still requires
+  every supported platform.
+
+### Fixed
+
+- The locally installed editor extension shipped a raw `src/` tree without
+  `ajv` or `schemas/`, which the bundled server's imports need, so its language
+  server could not start. Both installation helpers and release packaging now
+  ship the same bundled server. `just verify-vsix` additionally initializes the
+  packaged language server outside the checkout, exercises a linked
+  TypeScript/Markdown fixture, and rejects an artifact carrying a source tree or
+  test files.
+- A type error in the editor client now fails required CI. `just verify` and the
+  CI gate run `just typecheck-extension`, which covers the separate TypeScript
+  project the root `tsconfig.json` excludes.
+
+## [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 +423,9 @@ 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.9.0...HEAD
+[0.9.0]: https://github.com/salan70/docbridge/releases/tag/v0.9.0
+[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

@@ -4,60 +4,48 @@
 [![Japanese README](https://img.shields.io/badge/README-%E6%97%A5%E6%9C%AC%E8%AA%9E-blue)](docs/ja/README.md)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/salan70/docbridge)
 
-Bring Markdown into the LSP world.
+DocBridge keeps Markdown documentation and the code that implements it linked
+in both directions. It validates `@doc` annotations on supported TypeScript,
+Swift, Dart, and Rust declarations against `@code` annotations on Markdown
+headings, so humans and coding agents can find the right counterpart before a
+change drifts.
 
-DocBridge creates bidirectional links between TypeScript, Swift, Dart, or Rust code
-and Markdown documentation, enabling LSP-like experiences such as Hover,
-Definition, References, and Diagnostics across implementation and specification
-files.
+## Requirements
 
-## Installation
+- Node.js 22 or later, or Bun 1.1.31 or later
+- A project containing Markdown and supported source files
 
-DocBridge is distributed as the `docbridge` npm package and runs on Node.js
-(>= 22) and Bun:
+Prebuilt Swift, Dart, and Rust scanners are included for supported macOS and
+Linux platforms. See [Releases](https://github.com/salan70/docbridge/releases)
+for packaged-platform details.
 
-```sh
-npx docbridge check
-# or
-bunx docbridge check
-```
-
-See the npm badge above or
-[Releases](https://github.com/salan70/docbridge/releases) for the current
-version.
-
-The package includes prebuilt Swift, Dart, and Rust scanner
-binaries for `darwin-arm64` and `linux-x64`. TypeScript and Markdown checks run
-without scanner binaries. Configured Swift, Dart, or Rust projects on unsupported
-platforms report `code_scanner_unavailable` and name the supported platform
-keys.
+## Install
 
-## Quick Start
-
-Run first-time setup in the project root:
+Add DocBridge to the project that owns the documentation:
 
 ```sh
-bunx docbridge init
+npm install --save-dev docbridge
 ```
 
-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:
+With Bun:
 
 ```sh
-bunx docbridge init-with-agent
+bun add --dev docbridge
 ```
 
-Preview planned file operations without writing:
+## Run the first check
+
+Create a starting configuration interactively:
 
 ```sh
-bunx docbridge init --dry-run
+npx docbridge init
 ```
 
-You can also create `docbridge.config.json` manually:
+Or write the minimal TypeScript configuration yourself:
 
 ```json
 {
+  "$schema": "./node_modules/docbridge/schemas/docbridge.schema.json",
   "include": {
     "code": {
       "typescript": {
@@ -69,361 +57,56 @@ You can also create `docbridge.config.json` manually:
 }
 ```
 
-Link an exported TypeScript declaration to a Markdown section:
-
-```ts
-/**
- * @doc docs/auth.md#login-spec
- */
-export async function login() {
-  // ...
-}
-```
-
-Add the backlink in the Markdown file:
-
-```md
-<!-- @code src/auth/login.ts#login -->
-
-## Login Spec
-
-Login flow specification.
-```
-
-Check the project:
-
-```sh
-bunx docbridge check
-```
-
-## Usage
-
-Discover a command:
-
-```sh
-bunx docbridge --help
-bunx docbridge context --help
-```
-
-Every command accepts `--help` (alias `-h`) and prints its usage, when to use
-it, and its options on stdout.
-
-Check links:
-
-```sh
-bunx docbridge check
-```
-
-Check another project root:
-
-```sh
-bunx docbridge check --root examples/typescript
-```
-
-Emit JSON:
-
-```sh
-bunx docbridge check --json
-```
-
-Run audit diagnostics:
-
-```sh
-bunx docbridge check --audit
-```
-
-Audit diagnostics include:
-
-- `undocumented_symbol` — in-scope code endpoints with no `@doc`
-- `unlinked_doc_section` — in-scope documentation sections with no `@code`
-
-List the linked counterparts of changed files:
-
-```sh
-git diff --name-only | bunx docbridge related --stdin
-```
-
-`docbridge related` is informational: it reports each counterpart and whether it
-is itself in the change set, and always exits `0` on success. Changed files can
-also be passed as positional arguments. Add `--gate` to report only the
-counterparts that are not themselves in the change set and exit `1` when any
-exist. Both modes support `--root` and `--json`. See
-[docs/specs/cli.md](docs/specs/cli.md) for details.
-
-Print the content of the linked counterparts of changed files:
-
-```sh
-git diff --name-only | bunx docbridge context --stdin
-```
-
-`docbridge context` answers "what do the linked counterparts say": full
-Markdown sections for doc counterparts, full declarations including JSDoc for
-code counterparts. The default output is Markdown suitable for direct
-injection into an agent prompt; `--json` follows
-[schemas/context-output.schema.json](schemas/context-output.schema.json).
-Extraction is best-effort and the command exits `0` on success even when the
-tree has broken links. See [docs/specs/cli.md](docs/specs/cli.md) for details.
-
-Inspect the resolved link graph:
-
-```sh
-bunx docbridge graph
-bunx docbridge graph --json --include-content
-```
-
-`docbridge graph` prints the resolved endpoint graph, including resolvable
-one-way links. JSON output follows
-[schemas/graph-output.schema.json](schemas/graph-output.schema.json).
-
-## Why DocBridge
-
-Modern software projects often suffer from a gap between implementation and
-documentation:
-
-- Code changes without documentation updates
-- Documentation changes without implementation updates
-- Difficulty finding which specifications relate to a given implementation
-- Difficulty finding which implementation relates to a given specification
-- AI coding agents missing relevant context during code modifications
-
-DocBridge makes relationships between code and documentation explicit,
-navigable, and machine-readable.
-
-## Concept
-
-Traditional documentation tools often focus on one direction:
-
-```text
-Code -> Documentation
-```
-
-DocBridge focuses on both directions:
-
-```text
-Code <-> Documentation
-```
-
-DocBridge links supported code declarations to Markdown sections. TypeScript is
-scanned in-process; Swift, Dart, and Rust are scanned through bundled first-party
-worker packages.
-
-## Supported Inputs
-
-DocBridge recognizes the following elements.
-
-Supported code declarations:
-
-- TypeScript top-level exported declarations: `function`, `class`,
-  `abstract class`, `interface`, `type`, `const`, `enum`, and supported
-  `declare` / named default forms
-- TypeScript type members: class methods, properties, accessors, constructors,
-  and static members, plus interface and object-type-alias signatures
-- Swift public/open declarations and configured internal declarations:
-  top-level and member types, functions, variables, constants, initializers,
-  and extension members
-- Dart public declarations: top-level functions/variables, classes, enums,
-  mixins, constructors, fields, accessors, methods, and extension members
-- Rust `pub` declarations (and configured non-`pub` with `visibility`):
-  modules, structs, enums, free functions, and inherent `impl` methods
-
-Supported Markdown elements:
-
-- ATX headings
-- HTML comments
-- `@code` annotations attached to the next heading
-
-All four languages use the same `@doc` and `@code` model. Code fragments are
-the scanner-produced canonical IDs, so members are type-qualified.
-
-TypeScript member IDs carry no parameter signature; overload signatures and a
-getter/setter pair each collapse to one endpoint, and the constructor is
-`<Type>.constructor`. By default `public` and `protected` members are scanned;
-`private` members require `include.code.typescript.visibility`. Members are
-linkable but are never reported by `check --audit`.
+Add a documentation target to a supported declaration:
 
 ```ts
-export class AuthService {
-  /** @doc docs/auth.md#login-spec */
-  login(email: string, password: string): void {}
-}
+/** @doc docs/auth.md#login-flow */
+export function login(): void {}
 ```
 
-```md
-<!-- @code src/auth/service.ts#AuthService.login -->
-
-## Login Spec
-```
-
-Swift, Dart, and Rust canonical IDs follow their own conventions:
-
-```swift
-/// @doc docs/auth.md#login-spec
-public struct AuthService {
-  public func login(email: String, password: String) {}
-}
-```
+Add the reciprocal code target immediately before the Markdown heading:
 
 ```md
-<!-- @code Sources/AuthService.swift#AuthService.login(email:password:) -->
+<!-- @code src/auth.ts#login -->
 
-## Login Spec
+## Login Flow
 ```
 
-Projects must define scan targets in `docbridge.config.json`. There is no
-implicit default configuration; when the config file is missing, DocBridge
-reports `config_file_invalid` and does not scan project files.
-
-Minimal TypeScript configuration:
-
-```json
-{
-  "include": {
-    "code": {
-      "typescript": {
-        "patterns": ["src/**/*.ts"]
-      }
-    },
-    "docs": ["docs/**/*.md"]
-  }
-}
-```
-
-Multilanguage configuration is language-keyed. The old `include.code` array
-shape is intentionally invalid; migrate it to a `typescript` entry:
-
-```json
-{
-  "include": {
-    "code": {
-      "typescript": { "patterns": ["src/**/*.ts"] },
-      "swift": { "patterns": ["Sources/**/*.swift"] },
-      "dart": { "patterns": ["lib/**/*.dart"] }
-    },
-    "docs": ["docs/**/*.md"]
-  }
-}
-```
-
-Swift, Dart, and Rust projects must build their scanner workers in source checkouts
-before checking those languages. Run `just build-swift-scanner` for Swift,
-`just build-dart-scanner` for Dart, and `just build-rust-scanner` for Rust, or
-use the native test recipes below.
-
-## AI agent integration
-
-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`.
-
-This repository dogfoods the skills under `.claude/` and `.agents/`, and keeps
-its guardrail in the Git `pre-commit` hook under `.githooks/` rather than in
-any agent's configuration.
-
-## Editor support
-
-DocBridge ships a language server that exposes the same link graph to editors:
-
-```sh
-docbridge lsp
-```
-
-`docbridge lsp` speaks LSP over stdio and provides Diagnostics, Hover,
-Definition, and References across linked code and Markdown. It takes no
-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:
+Then validate the pair:
 
 ```sh
-just package-vsix
-just verify-vsix
+npx docbridge check
 ```
 
-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).
-
-## Diagnostics
-
-Errors:
-
-- `config_file_invalid`
-- `config_unknown_key`
-- `config_invalid_value`
-- `invalid_link_target`
-- `doc_file_not_found`
-- `doc_anchor_not_found`
-- `code_file_not_found`
-- `code_backlink_not_found`
-- `doc_backlink_not_found`
-- `duplicate_doc_anchor`
-- `duplicate_code_symbol`
-- `code_parse_error`
-- `code_scanner_unavailable`
-- `code_scanner_failed`
-- `file_read_error`
-
-Warnings:
+A valid graph exits `0`. Invalid configuration, unresolved targets, and missing
+backlinks produce diagnostics and exit `1`.
 
-- `duplicate_link`
-- `dangling_code_annotation`
-- `unsupported_declaration`
-- `undocumented_symbol` when `--audit` is enabled
-- `unlinked_doc_section` when `--audit` is enabled
+## Choose the next guide
 
-Exit code policy:
+- [Documentation hub](docs/README.md) — user guides, integration recipes,
+  specifications, and contributor references
+- [Getting started](docs/user/getting-started.md) — installation and project
+  setup
+- [Configuration](docs/user/configuration.md) — roots, include patterns,
+  languages, and visibility
+- [Linking](docs/user/linking.md) — choose, create, and semantically review
+  links
+- [Commands](docs/user/commands.md) — check, related, context, graph, docs, and
+  upgrade
+- [Automation](docs/user/automation.md) — coding agents, Git hooks, and CI
+- [Troubleshooting](docs/user/troubleshooting.md) — diagnose configuration,
+  scanning, and link failures
+- [日本語ドキュメント](docs/ja/README.md)
 
-- `1` when any error exists
-- `0` when there are only warnings or no diagnostics
+The CLI ships the English task guides with its own version. Run
+`npx docbridge docs list` and `npx docbridge docs show <name>` to read them
+without a repository checkout.
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the pinned development environment,
-repository setup, testing matrix, commit convention, and pull request workflow.
-
-## Documentation
-
-- Contributor guide: [CONTRIBUTING.md](CONTRIBUTING.md)
-- Japanese documentation: [docs/ja/README.md](docs/ja/README.md)
-- Specifications: [docs/specs](docs/specs)
-- v0.1 decisions: [docs/decisions/v0.1.md](docs/decisions/v0.1.md)
-- v0.2 decisions: [docs/decisions/v0.2.md](docs/decisions/v0.2.md)
-- v0.3 decisions: [docs/decisions/v0.3.md](docs/decisions/v0.3.md)
-- AI agent integration recipes: [docs/integrations](docs/integrations)
-- Commit message convention: [docs/contributing/commits.md](docs/contributing/commits.md)
-- Pull request convention: [docs/contributing/pull-requests.md](docs/contributing/pull-requests.md)
-- Testing convention: [docs/contributing/testing.md](docs/contributing/testing.md)
-
-## Roadmap
-
-Completed v0.1–v0.6 capabilities are documented above and in
-[CHANGELOG.md](CHANGELOG.md).
-
-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
-
-## Vision
-
-DocBridge is not a documentation generator.
+Repository setup, tests, and pull-request policy are in
+[CONTRIBUTING.md](CONTRIBUTING.md). Documentation ownership and writing rules
+are in [Documentation Guidelines](docs/contributing/documentation.md).
 
-Its purpose is to make relationships between code and documentation visible, navigable, and machine-readable so humans and AI agents can reach relevant context with minimal effort.
+DocBridge is not a documentation generator. It makes the relationship between
+maintained prose and implementation explicit, navigable, and machine-readable.

package/dist/bin/darwin-arm64/SHA256SUMS

@@ -1,3 +1,3 @@
-bc9e7548f993e48d280c3a487be4cc90a3e6549491c6f93f0e518ccc4239d991  docbridge-swift-scanner
-ceb237b7e5b2047d091f961c0a43ba436b8c624c741cc7f864e5783d9248a4eb  docbridge_dart_scanner
+0f653f4418743c05283edd61b6562104a5f8b8bdd1a8bb04e78734b3e44ee49c  docbridge-swift-scanner
+18909a2c5779381a6a6975d12b69b00e407068a60e522a189d9f1f9eaad9a424  docbridge_dart_scanner
 a1b129d980c981a2d24f0c9682e614a9695d4e9f9b8174d61b0dacb3fc9e3c79  docbridge-rust-scanner

package/dist/bin/linux-x64/SHA256SUMS

@@ -1,3 +1,3 @@
-114f780cebfb8834f200ef60f3a828ca7dc4668b23f6e646971e3e56c377b37a  docbridge-swift-scanner
-095c4c172da615be155bee15dcce7b99faaf2a8bb26f3cad3e0b17881495ddf2  docbridge_dart_scanner
+71ffeb93cb22a6fed305652a450d3f8559e9520b0beb837888e512c9534f8037  docbridge-swift-scanner
+1784df5ebc370c785a3728e2d8cccb8da27593265ed6a1cac27019787c9ea666  docbridge_dart_scanner
 d89a1146ed10dcb01151ef5351a746862c3955286431c47f3cf91cf6639866ba  docbridge-rust-scanner

package/dist/bin/linux-x64/docbridge-swift-scanner

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/dist/bin/linux-x64/docbridge-swift-scanner
 size: 38122456 bytes
-sha256: 114f780cebfb8834f200ef60f3a828ca7dc4668b23f6e646971e3e56c377b37a
+sha256: 71ffeb93cb22a6fed305652a450d3f8559e9520b0beb837888e512c9534f8037