docbridge 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -7,11 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.4.0] - 2026-06-18
+## [0.4.1] - 2026-06-21
 
 ### Added
 
-- npm distribution support for the Bun-only `speclink` package, including
+- `docbridge init` for CLI-driven first-time setup: repository scope discovery,
+  safe `docbridge.config.json` creation, and DocBridge agent skill installation.
+- `docbridge init-with-agent` for agent-guided adoption: installs
+  `docbridge-adopt` and prints one-shot setup commands without launching an
+  agent process.
+- `docbridge-adopt` now installs the companion DocBridge skills after adoption
+  scope is confirmed.
+
+## [0.4.0] - 2026-06-20
+
+### Added
+
+- npm distribution support for the Bun-only `docbridge` package, including
   `dist/index.js` as the package binary, a runtime package allowlist, dist
   verification, packed-package smoke testing, and release workflow publishing.
 - Platform-staged Swift and Dart scanner binary layout under
@@ -28,21 +40,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Worker-backed scanner protocol foundation for Swift and Dart adapters,
   including stdin/stdout JSON invocation and scanner availability/failure
   diagnostics.
-- `speclink graph`: prints the resolved link graph as human-readable output or
+- `docbridge graph`: prints the resolved link graph as human-readable output or
   as JSON following `schemas/graph-output.schema.json`, including resolvable
   one-way links, pair completeness, optional lightweight node content, and
   diagnostics that do not prevent graph construction.
-- Distributable adoption skills under `templates/skills/`: `speclink-adopt`
-  for existing-project setup, `speclink-link` for docs-first annotation
-  candidate confirmation, and `speclink-review` for whole-graph semantic
-  review using `speclink graph --json --include-content`.
+- Distributable adoption skills under `templates/skills/`: `docbridge-adopt`
+  for existing-project setup, `docbridge-link` for docs-first annotation
+  candidate confirmation, and `docbridge-review` for whole-graph semantic
+  review using `docbridge graph --json --include-content`.
 
 ### Changed
 
-- `speclink context` and `speclink graph --json` now carry code language
+- The project, package, command, configuration file, templates, and repository
+  URLs were renamed from SpecLink/`speclink` to DocBridge/`docbridge`.
+- `docbridge context` and `docbridge graph --json` now carry code language
   metadata for code blocks/nodes so Swift endpoints render and serialize as
   Swift.
-- SpecLink's distributable skills are now dogfooded from `.agents/skills/` and
+- DocBridge's distributable skills are now dogfooded from `.agents/skills/` and
   `.claude/skills/` as symlinks to the canonical `templates/skills/` entries.
 - TypeScript scanner endpoints now include `signatureRange` in addition to the
   existing full `declarationRange`, allowing graph consumers to read the
@@ -135,7 +149,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.4.0...HEAD
+[Unreleased]: https://github.com/salan70/docbridge/compare/v0.4.1...HEAD
+[0.4.1]: https://github.com/salan70/docbridge/releases/tag/v0.4.1
 [0.4.0]: https://github.com/salan70/docbridge/releases/tag/v0.4.0
 [0.3.0]: https://github.com/salan70/docbridge/releases/tag/v0.3.0
 [0.2.0]: https://github.com/salan70/docbridge/releases/tag/v0.2.0

package/README.md

@@ -1,5 +1,6 @@
 # DocBridge
 
+[![npm version](https://img.shields.io/npm/v/docbridge.svg)](https://www.npmjs.com/package/docbridge)
 [![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)
 
@@ -10,99 +11,49 @@ and Markdown documentation, enabling LSP-like experiences such as Hover,
 Definition, References, and Diagnostics across implementation and specification
 files.
 
-## Motivation
-
-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
+## Installation
 
-Traditional documentation tools often focus on one direction:
+DocBridge is distributed as the `docbridge` npm package and is intended to run
+with Bun:
 
-```text
-Code -> Documentation
+```sh
+bunx docbridge check
 ```
 
-DocBridge focuses on both directions:
-
-```text
-Code <-> Documentation
-```
+The current release is
+[v0.4.0](https://github.com/salan70/docbridge/releases/tag/v0.4.0), published
+as `docbridge@0.4.0` on npm.
 
-DocBridge links supported code declarations to Markdown sections. TypeScript is
-scanned in-process; Swift and Dart are scanned through bundled first-party
-worker packages.
+The npm package is Bun-only; Node.js runtime compatibility is not part of the
+initial distribution. The package includes prebuilt Swift and Dart scanner
+binaries for `darwin-arm64` and `linux-x64`. TypeScript and Markdown checks run
+without scanner binaries. Configured Swift or Dart projects on unsupported
+platforms report `code_scanner_unavailable` and name the supported platform
+keys.
 
-## Example
+## Quick Start
 
-TypeScript:
+Run first-time setup in the project root:
 
-```ts
-/**
- * @doc docs/auth.md#login-spec
- */
-export async function login() {
-  // ...
-}
+```sh
+bunx docbridge init
 ```
 
-Markdown:
-
-```md
-<!-- @code src/auth/login.ts#login -->
-## Login Spec
+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:
 
-Login flow specification.
+```sh
+bunx docbridge init-with-agent
 ```
 
-Swift and Dart use the same `@doc` and `@code` model. Their code fragments are
-the scanner-produced canonical IDs, so members are type-qualified:
-
-```swift
-/// @doc docs/auth.md#login-spec
-public struct AuthService {
-  public func login(email: String, password: String) {}
-}
-```
+Preview planned file operations without writing:
 
-```md
-<!-- @code Sources/AuthService.swift#AuthService.login(email:password:) -->
-## Login Spec
+```sh
+bunx docbridge init --dry-run
 ```
 
-## Scope
-
-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
-- 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
-
-Supported Markdown elements:
-
-- ATX headings
-- HTML comments
-- `@code` annotations attached to the next heading
-
-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:
+You can also create `docbridge.config.json` manually:
 
 ```json
 {
@@ -117,66 +68,56 @@ Minimal TypeScript configuration:
 }
 ```
 
-Multilanguage configuration is language-keyed. The old `include.code` array
-shape is intentionally invalid; migrate it to a `typescript` entry:
+Link an exported TypeScript declaration to a Markdown section:
 
-```json
-{
-  "include": {
-    "code": {
-      "typescript": { "patterns": ["src/**/*.ts"] },
-      "swift": { "patterns": ["Sources/**/*.swift"] },
-      "dart": { "patterns": ["lib/**/*.dart"] }
-    },
-    "docs": ["docs/**/*.md"]
-  }
+```ts
+/**
+ * @doc docs/auth.md#login-spec
+ */
+export async function login() {
+  // ...
 }
 ```
 
-Swift and Dart projects must build their scanner workers in source checkouts
-before checking those languages. Run `just build-swift-scanner` for Swift and
-`just build-dart-scanner` for Dart, or use the native test recipes below.
+Add the backlink in the Markdown file:
 
-## Installation
+```md
+<!-- @code src/auth/login.ts#login -->
+## Login Spec
 
-DocBridge is distributed as the `docbridge` npm package and is intended to run
-with Bun:
+Login flow specification.
+```
+
+Check the project:
 
 ```sh
 bunx docbridge check
 ```
 
-The npm package is Bun-only; Node.js runtime compatibility is not part of the
-initial distribution. The package includes prebuilt Swift and Dart scanner
-binaries for `darwin-arm64` and `linux-x64`. TypeScript and Markdown checks run
-without scanner binaries. Configured Swift or Dart projects on unsupported
-platforms report `code_scanner_unavailable` and name the supported platform
-keys.
-
-## CLI
+## Usage
 
 Check links:
 
 ```sh
-just check
+bunx docbridge check
 ```
 
-Check another root:
+Check another project root:
 
 ```sh
-just check-example
+bunx docbridge check --root examples/typescript
 ```
 
 Emit JSON:
 
 ```sh
-just check-example-json
+bunx docbridge check --json
 ```
 
 Run audit diagnostics:
 
 ```sh
-just audit
+bunx docbridge check --audit
 ```
 
 Audit diagnostics include:
@@ -186,21 +127,20 @@ Audit diagnostics include:
 List the linked counterparts of changed files:
 
 ```sh
-git diff --name-only | docbridge related --stdin
+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; `just related-gate` runs this over uncommitted changes. Both modes
-support `--root` and `--json`. See [docs/specs/cli.md](docs/specs/cli.md) for
-details.
+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 | docbridge context --stdin
+git diff --name-only | bunx docbridge context --stdin
 ```
 
 `docbridge context` answers "what do the linked counterparts say": full
@@ -214,14 +154,121 @@ tree has broken links. See [docs/specs/cli.md](docs/specs/cli.md) for details.
 Inspect the resolved link graph:
 
 ```sh
-docbridge graph
-docbridge graph --json --include-content
+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 and Dart 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
+- 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
+
+Supported Markdown elements:
+
+- ATX headings
+- HTML comments
+- `@code` annotations attached to the next heading
+
+Swift and Dart use the same `@doc` and `@code` model. Their code fragments are
+the scanner-produced canonical IDs, so members are type-qualified:
+
+```swift
+/// @doc docs/auth.md#login-spec
+public struct AuthService {
+  public func login(email: String, password: String) {}
+}
+```
+
+```md
+<!-- @code Sources/AuthService.swift#AuthService.login(email:password:) -->
+## Login Spec
+```
+
+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 and Dart projects must build their scanner workers in source checkouts
+before checking those languages. Run `just build-swift-scanner` for Swift and
+`just build-dart-scanner` for Dart, or use the native test recipes below.
+
 ## AI agent integration
 
 DocBridge's link graph is built to be consumed by AI coding agents:
@@ -231,7 +278,9 @@ DocBridge's link graph is built to be consumed by AI coding agents:
   with `docbridge related --gate`, and PR reporting.
 - [examples/hooks](examples/hooks) — copyable agent hook scripts implementing
   those recipes.
-- [templates/skills](templates/skills) — distributable agent skills:
+- [templates/skills](templates/skills) — distributable agent skills installed by
+  `docbridge init`; `docbridge init-with-agent` installs `docbridge-adopt`
+  first, then `docbridge-adopt` installs the companion skills:
   `docbridge-annotate`, `docbridge-sync`, `docbridge-adopt`, `docbridge-link`,
   and `docbridge-review`.
 
@@ -404,7 +453,7 @@ inside their worker packages.
 
 ## Roadmap
 
-Completed v0.1–v0.3 capabilities are documented above and in
+Completed v0.1–v0.4 capabilities are documented above and in
 [CHANGELOG.md](CHANGELOG.md). The current roadmap tracks upcoming work only.
 
 v0.5:

package/dist/bin/darwin-arm64/SHA256SUMS

@@ -1,2 +1,2 @@
-4e8638f664e3cb08e36146dd03097d1dfe1c35be39b79219c6d633ea07e7742f  speclink-swift-scanner
-ef5e2d41194493de9f3cea22bc8f268c35bbd0f69ff63e275e303b6476b658a1  speclink_dart_scanner
+a2ec141fe5b365958bf3d7cceb5938b4b0e0acf0227791dce08a627a1b17e541  speclink-swift-scanner
+459d9e21cd1479c3604c9567ba38c1a59959e70578d52e853f7a591e666428a6  speclink_dart_scanner

package/dist/bin/linux-x64/SHA256SUMS

@@ -1,2 +1,2 @@
-4100cc8c861a24821fca240c758ba188a42f677a403fe40a76bac4271a918bfe  speclink-swift-scanner
+14b5284afd5387b0734832b35585f6b72945b6eef0642075bb68e1343fb1965d  speclink-swift-scanner
 2145eac2afd09696ced849e0196a2557d6f7041224f13da1d5ef21c552ecf7bc  speclink_dart_scanner