@agentskit/doc-bridge 1.7.45 → 1.10.0

package/docs/spec/cli.md

@@ -5,7 +5,7 @@ description: Complete command reference for indexing, querying, gates, doctor, m
 
 # ak-docs CLI
 
-Command-line interface for **`@agentskit/doc-bridge`**. The npm package is scoped; the **only published binary** is `ak-docs`.
+Command-line interface for **`@agentskit/doc-bridge`**. The package publishes two executables: `ak-docs` is the product CLI and `ak-verify` is the verification-harness wrapper.
 
 ## Naming
 
@@ -13,11 +13,17 @@ Command-line interface for **`@agentskit/doc-bridge`**. The npm package is scope
 |------|------|
 | npm package | `@agentskit/doc-bridge` |
 | CLI binary | `ak-docs` |
-| Config file | `doc-bridge.config.ts` |
+| Verification binary | `ak-verify` |
+| Primary config filename | `doc-bridge.config.ts` |
 | GitHub repo | `AgentsKit-io/doc-bridge` |
 
 Install the package, run `ak-docs` — not `doc-bridge` on the shell.
 
+The primary filename is shown for readability. Discovery also accepts
+`doc-bridge.config.mts`, `.js`, `.mjs`, `.json`, and the `docBridge` field in
+`package.json`; see the [configuration contract](./config-v1.md#discovery-order)
+for the authoritative order.
+
 ## Why a separate binary
 
 | Choice | Rationale |
@@ -39,7 +45,8 @@ pnpm add -D @agentskit/doc-bridge
 {
   "name": "@agentskit/doc-bridge",
   "bin": {
-    "ak-docs": "./bin/ak-docs.js"
+    "ak-docs": "./bin/ak-docs.js",
+    "ak-verify": "./bin/ak-verify.js"
   }
 }
 ```
@@ -58,8 +65,8 @@ pnpm add -D @agentskit/doc-bridge
 | `ak-docs doctor [--text] [--badge] [--write-badge]` | Coverage score, gaps, gates, shields.io badge |
 | `ak-docs index` | Build `DocBridgeIndex` + optional `llms.txt` |
 | `ak-docs index --watch` | Debounced rebuild on agent/human doc changes |
-| `ak-docs query <target> [--agent] [--text]` | Resolve package/module/intent/change → handoff JSON or text |
-| `ak-docs search <term> [--agent] [--text]` | Full-text search over index |
+| `ak-docs query <target> [--agent] [--text]` | Resolve package/area/module/document/intent/change → handoff JSON or text |
+| `ak-docs search <term> [--agent] [--explain] [--mode=<mode>] [--context-budget=<tokens>] [--text]` | Ranked search over the retrieval projection; `--explain` names every scoring component and the matched terms, and agent mode bounds the context it returns to a task-specific budget |
 | `ak-docs ask <question>` | Human-readable local consult mode: search + best match + next handoff commands; no LLM |
 | `ak-docs ask` | Interactive local REPL in a TTY; commands: `search <term>`, `read <id-or-path>`, `open <id-or-path>`, `resolve <id>`, `gate [id]`, `exit` |
 | `ak-docs retrieve <query>` | Hybrid local/federated retriever chunks; deterministic local first |
@@ -68,13 +75,26 @@ pnpm add -D @agentskit/doc-bridge
 | `ak-docs memory ingest` | Normalize local memory files (`.agent-memory/**/*.md`, `.cursor/rules/*.mdc`) into `MemoryCandidate[]` |
 | `ak-docs memory classify` | Deterministically route candidates to agent/human/playbook/discard |
 | `ak-docs memory promote` | Build draft-only promotion body with safety scan; never auto-merges |
-| `ak-docs memory promote --pr [--dry-run] [--force]` | Write draft + open GitHub draft PR via `gh` |
+| `ak-docs memory promote --pr --dry-run [--force]` | Write a local draft and print the `git`/`gh` commands; does not execute them |
+| `ak-docs memory promote --pr [--force]` | Write the draft, commit/push it, and open a GitHub draft PR via `gh` |
 | `ak-docs registry topology` | Print the `doc-curator` topology for AgentsKit/Registry composition |
+| `ak-docs suggest [--documentation] --json` | Run the configured Registry agent module or CLI and persist its typed proposal; optionally include the bounded documentation-audit context |
+| `ak-docs enrich [--json\|--text]` | Run the enrichment stage: context packs to the configured Registry roles, deterministic validators, the overlay at `.doc-bridge/enrich/overlay.json`. Zero agent calls over an unchanged repository |
+| `ak-docs enrich list \| approve <proposalId> --by <name> \| reject <proposalId> --by <name> [--reason <text>]` | Review pending enrichment proposals; a decision is recorded through the ecosystem approval gate under `.doc-bridge/approvals/`, bound to the proposal id and the target content hash |
+| `ak-docs check --enrich` | `check` with the `enrich` stage between `reconcile` and `evaluate`; a failed enrichment is reported in `enrichment` and never changes the check result |
+| `ak-docs enrich --retrieval-delta [--json\|--text]` | `enrich`, then the golden suite with and without the accepted overlay on the same snapshot. Exits 1 when the overlay lowers hit@3 |
+| `ak-docs bench retrieval <suite.json> --overlay [--json\|--text]` | The overlay on disk measured against a suite: both indexes projected from one snapshot, no index on disk required. Exits 1 on a hit@3 regression |
+| `ak-docs study expectations <task-suite.json> --expectations <local.json> [--index <index.json>] [--repository <id>]` | Check a study round's mechanical retrieval expectations through the benchmark. Exits 1 when a reference does not resolve or a case misses |
 | `ak-docs playbook draft` | Build a draft Playbook feedback payload from local memory candidates |
 | `ak-docs playbook pattern [--text]` | Export published Doc Bridge Playbook pattern (OKF markdown / JSON) |
 | `ak-docs list <kind> [--text]` | List packages, apps, intents, … |
-| `ak-docs gate run [index-freshness]` | Check generated index freshness |
+| `ak-docs gate run [gate-id]` | Run resolved configured documentation gates; an optional id narrows the run to one gate |
 | `ak-docs conformance run documentation-standard-v1 [--text\|--json]` | Run the stable ecosystem documentation profile with evidence and remediation |
+| `ak-docs audit documentation [--text\|--json]` | Measure documentation quality and compare documentation claims with the observed project graph |
+| `ak-docs parity [--claims <file>] [--json\|--text]` | Check the public claim registry against what the repository can prove: stale, missing, contradictory and not-analyzed claims, each with an owner, an exact source and a remediation. Exits 1 on a blocking finding |
+| `ak-docs render <llms.txt\|area\|ownership\|change-digest\|overlay-review> [--data <artifact>] [--output <path>] [--print-template] [--json]` | Render the canonical artifacts as Markdown from bundled or project templates (`render.templates`); deterministic, no agent. See [Render v1](./render-v1.md) |
+| `ak-docs bench retrieval <suite.json> [--index <file>] [--baseline <file>] [--limit <n>] [--text\|--json]` | Measure retrieval quality against a golden query suite: hit@1, hit@3, mean reciprocal rank, context bytes and approximate tokens. Exits non-zero on a hit@3 regression against the baseline. No model, no network |
+| `ak-docs bench retrieval <suite.json> --baseline <file> --update-baseline --by <name> [--reason <text>]` | Record the measured figures as the approved baseline. A normal run never writes one |
 | `ak-docs mcp` | Start MCP server (stdio default) |
 | `ak-docs mcp install --cursor \| --claude` | Write MCP server config for Cursor or Claude Desktop |
 
@@ -94,7 +114,7 @@ Peers: `@agentskit/rag`, `@agentskit/ink`, `@agentskit/adapters`, `@agentskit/me
 | Flag | Description |
 |------|-------------|
 | `--config <path>` | Config file (default: auto-discover) |
-| `--json` / `--text` | Output format for non-agent commands (default: json); `--agent` always emits agent JSON |
+| `--json` / `--text` | Output format for non-agent commands (default: formatted json); `--agent` emits compact machine-readable JSON, while `--text` remains human-readable |
 | `--chat` | Request planned intelligence-backed ask mode; errors clearly until `intelligence.adapter` and RAG/chat support are configured |
 | `--help` | Command help |
 
@@ -104,7 +124,7 @@ Peers: `@agentskit/rag`, `@agentskit/ink`, `@agentskit/adapters`, `@agentskit/me
 ak-docs index
 ak-docs query ownership auth --agent
 ak-docs query ownership auth --text
-ak-docs search "sidecar transport" --agent
+ak-docs search "sidecar transport" --agent --mode=discovery --context-budget=256
 ak-docs list packages --text
 ak-docs gate run
 ak-docs mcp
@@ -141,7 +161,7 @@ CLI is a thin wrapper over the same exports.
 pnpm docs:internal:query …   # private dogfood wrapper → ak-docs query …
 ```
 
-Private repo wrappers stay private. `ak-docs` is the only public binary.
+`ak-docs` is the primary product CLI. `ak-verify` is the portable verification-harness entry point used to prove repository work against a declared contract.
 
 ## See also
 

package/docs/spec/config-v1.md

@@ -5,7 +5,7 @@ description: Configure documentation corpora, ownership routing, conformance, an
 
 # doc-bridge config contract v1
 
-`doc-bridge.config.ts` (or `.js`, `.mjs`, `.json`, or `package.json` → `docBridge`) is the alpha integration point for any project. Layer 0 fields are sufficient to run `index`, `query`, and MCP without an LLM.
+`doc-bridge.config.ts` (or `.js`, `.mjs`, `.json`, or `package.json` → `docBridge`) is the v1 integration point for any project. Layer 0 fields are sufficient to run `index`, `query`, and MCP without an LLM.
 
 Reconciliation summaries also expose deterministic `diagnosticsByCode` and
 `diagnosticsByStatus` maps. They are additive rollups for agents and dashboards;
@@ -36,7 +36,7 @@ doc-bridge.config.json
 package.json → "docBridge" field (subset, JSON only)
 ```
 
-TypeScript/JavaScript configs are static in v0.1 alpha: `defineConfig` imports are supported, but arbitrary imports are not. YAML config files are planned.
+TypeScript/JavaScript configs are static in v1: `defineConfig` imports are supported, but arbitrary imports are not. YAML config files are planned.
 
 Dynamic-loading coverage is evidence-backed. Literal strings, constant aliases,
 parenthesized strings, and string concatenations are resolved without executing
@@ -88,9 +88,15 @@ export default {
   /** Optional reconciliation scope and orphan-document policy */
   reconciliation?: ReconciliationConfig
 
+  /** Optional retrieval tuning: corpus projection, field weights, BM25 parameters */
+  retrieval?: RetrievalConfig
+
   /** Optional resumable workflow state */
   workflow?: WorkflowConfig
 
+  /** Optional project templates for `ak-docs render`, by template name */
+  render?: RenderConfig
+
   /** Optional report publication privacy; private is the default */
   report?: { privacy?: 'private' | 'anonymized' }
 } satisfies DocBridgeConfigV1
@@ -301,7 +307,9 @@ by Nx plugins are intentionally not inferred by this read-only adapter.
 | Screen / feature | `id` in `screens/` or `features/` | MDX slug |
 | Flow / recipe | `id` in `flows/` | docs slug |
 
-Plugins document their join convention; gates fail on orphan links.
+Plugins document their join convention. The orphan-link gate only runs when the
+corresponding gate is enabled (for example, `human-guide-links`); the `minimal`
+preset does not enable that gate.
 
 ---
 
@@ -347,14 +355,14 @@ type GateId =
 | Preset | Gates |
 |--------|-------|
 | `minimal` | `index-freshness` |
-| `standard` | + `human-guide-links` in v0.1 alpha |
-| `strict` | + `okf-type` in v0.1 alpha |
+| `standard` | + `human-guide-links` in v1 |
+| `strict` | + `okf-type` in v1 |
 
 Implemented gates include `index-freshness`, `human-guide-links`, `okf-type`, `docs-style`, and the opt-in `documentation-standard-v1`. For v1 compatibility, `link-rot`, `routing-currency`, and `bootstrap-size` remain accepted as reserved IDs; including one emits `AK_DOCS_RESERVED_GATE` and does not claim that the gate ran. Unknown IDs are rejected.
 
 ### Structural vs style validation
 
-Alpha gates are deterministic lint checks, not editorial grading:
+These gates are deterministic lint checks, not editorial grading:
 
 | Gate | Kind | What it proves |
 |------|------|----------------|
@@ -363,7 +371,7 @@ Alpha gates are deterministic lint checks, not editorial grading:
 | `okf-type` | OKF lint | Agent docs have required `type:` frontmatter when strict/required |
 | `docs-style` | style lint | Opt-in deterministic profile checks for title, purpose, audience, examples, owner/source, task orientation, and stale wording |
 
-`docs-style` supports `google-dev-docs`, `playbook-okf`, and `custom` profiles. It is not part of the default alpha path and does not grade prose quality; it checks for explicit structural signals. LLM critique remains planned optional behavior.
+`docs-style` supports `google-dev-docs`, `playbook-okf`, and `custom` profiles. It is not part of the default path and does not grade prose quality; it checks for explicit structural signals. LLM critique remains planned optional behavior.
 
 ---
 
@@ -413,7 +421,7 @@ report status, commands, and the recorded stable-publication HITL decision.
 ```ts
 type ReconciliationConfig = {
   /** Semantic comparison level; discovery still preserves raw file relations. */
-  scope?: 'file' | 'module' | 'package'
+  scope?: 'file' | 'module' | 'area' | 'package'
   /** Observed relation kinds that require documentation declarations. */
   requiredRelationKinds?: string[]
   /** Limit missing-declaration findings to relations between internal project entities. */
@@ -425,6 +433,12 @@ type ReconciliationConfig = {
 
 Use `scope: 'package'` for monorepos where file imports should be compared as package-level architecture evidence. Omit `requiredRelationKinds` to require all observed kinds; an empty array intentionally disables undocumented-relation findings and must be treated as an explicit exemption.
 
+Use `scope: 'area'` for a single-package repository. At package scope such a repository aggregates
+every internal relation into one self-loop, which the comparison skips — a thousand observed
+relations and nothing to report. At area scope the same relations become edges between
+directories, which a declaration can confirm or fail to. On this repository that is the difference
+between zero diagnostics and 177.
+
 Use `requiredRelationTargets: 'internal'` when the repository wants package or module architecture declarations without requiring Markdown to enumerate every external library import. External relations remain in the raw snapshot and report as evidence; they simply do not generate missing-declaration findings.
 
 The reconciliation documentation summary reports package health separately from
@@ -456,6 +470,117 @@ report?: {
 
 `private` is the default and keeps local evidence useful for debugging. `anonymized` is intended for reports shared outside the repository: it preserves counts, relation kinds, topology, and coverage status while removing project-specific identity and evidence content. The generated HTML and every lazy chunk use the same mode.
 
+## `analysis.areas` (optional)
+
+```ts
+areas?: {
+  /** Directory levels below a source root that form an area. Default 1. */
+  depth?: number
+  /** Directories that contain areas rather than being one. */
+  roots?: string[]
+  /** Glob patterns for directories that hold code without being a unit of architecture. */
+  exclude?: string[]
+}
+```
+
+An **area** is the unit of architecture between a package and a file: a directory that groups
+modules. `src` is not an area in any useful sense; `src/query` is. So `roots` names the
+directories that hold areas — by default `src`, `lib`, `app`, `source`, `server`, `client`,
+`packages`, `apps` — and `depth` says how many levels below such a root an area sits.
+
+`exclude` names what the convention gets wrong in the other direction. A monorepo where every
+package keeps `tests/` and `fixtures/` beside `src/` derives an area per directory, and
+connectivity then asks for a document about a folder of test data — on one 26-package monorepo,
+43 of 81 undocumented areas were exactly that. A candidate matching an exclude pattern is not
+derived, and its modules fall to the most specific area that still encloses them, or to none,
+which is the honest answer for a folder of fixtures.
+
+Areas are derived, never declared, with one exception that matters: **any path an ownership record
+names becomes an area**, whatever the convention says — including a path `exclude` matches, because
+a person saying a directory is a unit outranks a pattern saying it is not. A configuration that reads
+`path: "src/mcp"` is a human stating that the directory is a unit, and the graph should have an
+entity for it. Such an area carries `metadata.ownershipId`, which is what lets an agent document
+declaring `id` plus `editRoot` resolve to the thing it owns.
+
+Each module belongs to exactly one area — the most specific one containing it — so containment
+stays a tree and an aggregation at area scope has one answer per module. Nested areas keep their
+shape: `area:src` holds what sits directly in `src`, with `area:src/query` recorded as its child.
+
+An ownership path that no observed module or document lives under is reported as
+`OWNERSHIP_PATH_UNOBSERVED` with status `stale-or-unverified`. A renamed directory is otherwise
+invisible: the handoff still resolves, it just points an agent somewhere that no longer holds what
+it claims.
+
+## `retrieval` (optional)
+
+```ts
+type RetrievalConfig = {
+  corpus?: {
+    /** Project repository documents and modules into `index.knowledge`. Default: true. */
+    enabled?: boolean
+  }
+  /** Per-field BM25 multipliers. Unknown field names are ignored. */
+  weights?: {
+    id?: number
+    symbols?: number
+    title?: number
+    path?: number
+    tags?: number
+    description?: number
+    body?: number
+  }
+  /** BM25 parameters: `k1` term-frequency saturation, `b` length-normalization strength (0–1). */
+  params?: { k1?: number; b?: number }
+}
+```
+
+Search ranks records with field-weighted BM25 plus boosts for exact identity, so an agent that
+types an exported symbol, a file path or a package name lands on that thing rather than on
+whatever mentions it most. The defaults are:
+
+| Field | Weight | Why |
+| --- | --- | --- |
+| `id` | 8 | The query names the record |
+| `symbols` | 7 | An agent that types an exported name wants the module that defines it |
+| `title` | 6 | A heading is what a document is about |
+| `path` | 4 | Location is identity for a module |
+| `tags` | 3 | Audience and kind |
+| `description` | 2 | A summary a human wrote |
+| `body` | 1 | A passing mention is the weakest evidence |
+
+Tuning is configuration, not code: the resolved weights, parameters and stopword-lexicon version
+are recorded in `index.retrieval`, so a retuned ranking is a different artifact with a different
+content hash rather than a silent behaviour change. Re-run `ak-docs index` after changing them,
+and re-approve the [retrieval benchmark](../bench/README.md) baseline if you gate on it.
+
+`corpus.enabled: false` keeps the index to the curated agent corpus only. The index is then
+smaller and builds faster, at the cost of the retrieval it exists for: an exported-symbol or
+file-path query has nothing to resolve against. Turn it off only for a repository whose source is
+not the thing agents ask about.
+
+## `render` (optional)
+
+```ts
+type RenderConfig = {
+  /** Project templates that replace the bundled ones, by name, as paths relative to the project root. */
+  templates?: Partial<Record<'llms.txt' | 'area' | 'ownership' | 'change-digest' | 'overlay-review', string>>
+}
+```
+
+`ak-docs render <name>` renders the canonical artifacts as Markdown from a bundled template; a
+path under `templates` replaces that template entirely, without a code change. Templates use
+knap syntax and see only the variables Doc Bridge computes — see [Render v1](./render-v1.md) for
+each template's variables and `ak-docs render <name> --print-template` for the bundled source.
+The `llms.txt` override is also what `ak-docs index` writes.
+
+```json
+{
+  "render": {
+    "templates": { "area": "templates/area.md" }
+  }
+}
+```
+
 ## `safety` (optional)
 
 ```ts
@@ -610,14 +735,38 @@ type IntelligenceConfig = {
     agentId?: string
     agentRoot?: string
     runnerModule?: string
+    cli?: {
+      /** Executable name or absolute path; arguments are passed without a shell. */
+      command: string
+      args?: string[]
+    }
     deterministic?: boolean
+    maxInputBytes?: number
     timeoutMs?: number
     maxTokens?: number
     maxResponseBytes?: number
     maxConcurrency?: number
+    /** Byte budget of one enrichment context pack. Default 65536 (4096..4000000). */
+    maxPackBytes?: number
+    /**
+     * Which installed agent plays which enrichment role (see Enrichment overlay v1).
+     * Default: the configured agent as curator only. The adjudicator must be a
+     * different identity from the curator and the reviewer.
+     */
+    roles?: {
+      curator?: EnrichmentRole
+      reviewer?: EnrichmentRole
+      adjudicator?: EnrichmentRole
+    }
   }
 }
 
+type EnrichmentRole = {
+  enabled?: boolean               // default: true when the role is declared; curator on by default
+  agentId?: string                // default: intelligence.registry.agentId
+  promptVersion?: string          // default: '1'; part of every proposal id and cache key
+}
+
 type MemoryAdapterId =
   | 'playbook-memory'              // .agent-memory/MEMORY.md layout
   | 'cursor-rules'                 // .cursor/rules/*.mdc

package/docs/spec/documentation-audit-v1.md

@@ -0,0 +1,61 @@
+---
+title: Documentation audit v1
+description: Configurable deterministic checks for documentation quality and agreement with repository structure.
+---
+
+# Documentation audit v1
+
+Run the repository audit after discovery and reconciliation:
+
+```bash
+ak-docs audit documentation --json
+ak-docs audit documentation --text
+```
+
+The JSON report is versioned and content-hashed. It includes criterion-level evidence, metrics, blocking findings, generated-document freshness boundaries, and limitations.
+
+## Configuration
+
+Configure the optional `audit.documentation` block in `doc-bridge.config.json`:
+
+```json
+{
+  "audit": {
+    "documentation": {
+      "criticalPaths": ["src/cli/**", "src/mcp/**"],
+      "generatedPaths": ["docs/generated/**"],
+      "minWords": 20,
+      "requiredSections": ["Usage", "Examples"],
+      "requireExamples": true,
+      "exactDuplicates": true,
+      "defaultTier": "tier-2",
+      "tierRules": [
+        { "pattern": "docs/agent-corpus/**", "tier": "tier-0", "critical": true },
+        { "pattern": "docs/adr/**", "tier": "tier-1" }
+      ],
+      "requiredCriticalMetadata": ["owner", "lifecycle", "sourceOfTruth", "validationPath"]
+    }
+  }
+}
+```
+
+- `criticalPaths` makes high-confidence contradictions and missing structure documentation blocking.
+- `generatedPaths` excludes generated documents from manual quality checks and reports freshness as `not-analyzed`; configure the generator's real check separately.
+- `requiredSections`, `minWords`, and `requireExamples` are opt-in to avoid false positives for indexes and short reference files.
+- `exactDuplicates` detects identical normalized bodies. It does not claim that similar prose is redundant.
+- `defaultTier` and ordered `tierRules` classify every included document as `tier-0`, `tier-1`, or `tier-2`. A document may override the configured tier with `tier` frontmatter; `critical: true` frontmatter or a rule marks it critical.
+- Critical documents are checked for `owner`, `lifecycle`, `sourceOfTruth`, and `validationPath` metadata. `requiredCriticalMetadata` can reduce this list for a declared project profile.
+
+The audit reuses the canonical discovery snapshot and reconciliation report. A finding is not proof that prose is wrong unless its evidence and confidence say so. `not-analyzed` is intentional and includes semantic contradiction, unnecessary content, and agent-review boundaries. A document title is satisfied by a Markdown level-one heading, a `title` frontmatter field, or a visible HTML `<h1>` used by README-style documents.
+
+## Independent quality dimensions
+
+Each document receives an assessment instead of one opaque quality score. The machine-readable report exposes `documentAssessments` and independent status counts for:
+
+- correctness: deterministic reconciliation can expose evidence, but semantic correctness remains `not-analyzed` until code, configuration, tests, and applicable runtime behavior are reviewed;
+- completeness: structural signals such as title and configured required sections are reported as `partial`, never as semantic completeness;
+- clarity: title and basic structure are measurable, while human readability remains `not-analyzed`;
+- agent efficiency: title and example presence are signals only; retrieval usefulness and task success require the controlled study;
+- maintainability: owner, lifecycle, source-of-truth, and validation-path metadata are directly measurable.
+
+Example presence and example correctness are separate. The audit reports `example.present`; `example.validation` remains `not-analyzed` unless a real validation flow supplies evidence. Similar prose, unnecessary content, and document/document semantic contradictions are intentionally deferred to the Registry-agent and human-adjudication path.