docbridge 0.8.0 → 0.9.0

package/templates/skills/docbridge/SKILL.md

@@ -9,7 +9,7 @@ Route DocBridge work, then apply the matching judgment. Facts about the binary
 — annotation syntax, supported declarations, the anchor algorithm, diagnostic
 codes — live in packaged docs, not in this skill. Read them with
 `docbridge docs show`. Invocation is documented in
-`docbridge docs show agent-integration`.
+`docbridge docs show automation`.
 
 An agent with no DocBridge skill can still finish the job from
 `docbridge --help` plus `docbridge docs list` / `docbridge docs show`.
@@ -51,7 +51,7 @@ Read `docbridge docs show getting-started` and `configuration`.
 ## Discover and link
 
 Work docs-first. Confirm docs scope, then follow
-`docbridge docs show linking-workflow`: prioritize unlinked specification
+`docbridge docs show linking`: prioritize unlinked specification
 sections, propose at most three symbols per section with why/uncertain, present
 5–10 sections per round, collect adopt/exclude/hold, and classify no-matches
 instead of forcing a link.
@@ -61,7 +61,7 @@ Add annotations only after section-level confirmation. Then follow Annotate.
 ## Annotate
 
 Create both sides of a pair, or add the missing backlink. Read
-`docbridge docs show annotations` for syntax, supported declarations, anchors,
+`docbridge docs show linking` for syntax, supported declarations, anchors,
 and target grammar. Read `docbridge docs show troubleshooting` for diagnostic
 codes and fixes.
 
@@ -76,11 +76,12 @@ unless the user asked to fix a wrong link.
 ## Sync
 
 A `related --gate` violation means nobody has decided yet, not that the
-counterpart must change. Read `docbridge docs show agent-integration` for the
+counterpart must change. Read `docbridge docs show automation` for the
 three-way judgment.
 
-1. Collect violations from the hook, CI comment, or
-   `git diff --name-only HEAD | docbridge related --stdin --gate`.
+1. Collect violations from the hook, CI comment, or, for uncommitted work
+   including new files,
+   `{ git diff --name-only HEAD; git ls-files --others --exclude-standard; } | docbridge related --stdin --gate`.
 2. Fetch counterpart content with `docbridge context` over the changed files.
 3. Per counterpart: update it when the documented contract diverged; leave it
    unchanged with a written justification that cites the counterpart content;
@@ -94,8 +95,8 @@ promise.
 
 ## Review
 
-Audit meaning across the whole graph, not a diff. Follow
-`docbridge docs show link-review`.
+Audit meaning across the whole graph, not a diff. Follow the semantic review
+procedure in `docbridge docs show linking`.
 
 Requires `docbridge graph --json --include-content`. Read `diagnostics` first.
 Batch by docs file. Read both sides. Classify High / Medium / Low. Report
@@ -116,11 +117,9 @@ silence uncertainty.
 ## Read more
 
 - `docbridge docs list` — the full menu
-- `docbridge docs show agent-integration` — invocation, gate judgment, hooks, CI
-- `docbridge docs show annotations` — `@doc` / `@code` rules
-- `docbridge docs show linking-workflow` — docs-first candidate discovery
-- `docbridge docs show link-review` — semantic audit
+- `docbridge docs show linking` — discovery, annotations, and semantic review
+- `docbridge docs show automation` — invocation, gate judgment, hooks, and CI
 - `docbridge docs show troubleshooting` — diagnostic codes and fixes
 - `docbridge docs show getting-started` — first-time setup
 - `docbridge docs show configuration` — `docbridge.config.json`
-- `docbridge docs show commands` — check, related, context, graph
+- `docbridge docs show commands` — check, related, context, graph, docs, upgrade

package/docs/user/agent-integration.md

@@ -1,96 +0,0 @@
----
-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. 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 -->
-
-## Invoking DocBridge
-
-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
-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
-
-Before changing a linked file, provide its counterpart content:
-
-```sh
-docbridge context path/to/changed-file
-```
-
-After editing, inspect the change set:
-
-```sh
-git diff --name-only | docbridge related --stdin --gate
-```
-
-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
-
-Put the automation in Git hooks rather than in one agent's configuration, so
-it covers every contributor and every tool. A `pre-commit` hook can run
-`docbridge check` as a hard gate, then report `related --gate` over the staged
-files:
-
-```sh
-git diff --cached --name-only | docbridge related --stdin --gate
-```
-
-When an agent runs `git commit` through a shell, the hook's output lands in the
-tool result and therefore in the agent's context, so the counterpart findings
-reach it without any agent-specific wiring. Attach the counterparts' content
-with `docbridge context --stdin` to make the finding actionable in place.
-
-Keep the gate stage non-blocking while the link graph is still sparse: a
-blocking gate on a staged subset mostly trains `--no-verify`. Hooks must not
-silently rewrite files or replace the repository's mandatory checks.
-
-Git hooks cannot signal before an edit, and they are skipped by `--no-verify`
-and by some GUI clients, so the pull request stays the enforcement point.
-
-## CI
-
-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

@@ -1,173 +0,0 @@
----
-description: Write @doc and @code annotations and valid link targets.
----
-
-# Annotations
-
-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
-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) {}
-```
-
-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 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 -->
-
-## Login Flow
-```
-
-The code fragment is the canonical symbol ID emitted by the language scanner.
-Use that ID exactly in the `@code` target.
-
-## Anchors and reciprocity
-
-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
-targets and pair completeness, and `docbridge graph --json` when you need the
-resolved endpoints and edges.

package/docs/user/link-review.md

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

package/docs/user/linking-workflow.md

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