---
owner: doc-bridge-maintainers
lifecycle: active
sourceOfTruth: src
validationPath: pnpm test && pnpm typecheck
---

# Knowledge Engine Runbook

Doc Bridge is deterministic by default. It turns repository structure and Markdown declarations into versioned snapshot, reconciliation, rule, report, and workflow artifacts. Optional Registry assistance is explicit and never changes deterministic results.

## First run

```bash
pnpm install
pnpm build
ak-docs discover --json
ak-docs scan --json
ak-docs reconcile --json
ak-docs check --json
ak-docs map --html --output .doc-bridge/report.html
```

Expected artifacts are under `.doc-bridge/workflow/`: `manifest.json`, immutable stage artifacts, `transitions.jsonl`, and `last-known-good.json`. The HTML report is standalone and can be opened directly without a server or network.

The safe repository walk excludes common generated trees, including `dist`, `build`, `.next`, `out`, `.turbo`, `.svelte-kit`, `.mcpb-build`, and `.mcpb-output`, so generated output is reported as a coverage boundary rather than mistaken for source architecture. Add a project-specific `safety.exclude` pattern when another tool generates code outside these conventions.

## Safe fixes

```bash
ak-docs fix propose links --output .doc-bridge/proposal.json
ak-docs fix approve .doc-bridge/proposal.json --by human
ak-docs fix apply .doc-bridge/proposal.json
```

Proposal generation never changes project files. Approval is bound to the exact proposal and affected-file hashes; apply rejects drift and rolls back on failure.

## Optional Registry assistance

Install the configured local Registry agent, then configure a local runner module:

```bash
npx agentskit add ecosystem-doc-bridge-corpus-scanner
ak-docs suggest --documentation --json
```

Set `intelligence.registry.enabled: true` and either `runnerModule` or the generic `cli` adapter in `doc-bridge.config.json`. The runner receives redacted immutable snapshot/report/evidence context and must return `AgentProposalV1`. Network, shell, direct file mutation, and automatic approval are not available to a module runner. A CLI receives the same context as a JSON envelope on stdin and must write exactly one `AgentProposalV1` JSON object to stdout; configure the executable and argument array without shell syntax:

```json
{
  "intelligence": {
    "registry": {
      "enabled": true,
      "agentId": "ecosystem-doc-bridge-corpus-scanner",
      "cli": {
        "command": "codex",
        "args": ["exec", "--json"]
      },
      "timeoutMs": 120000,
      "maxInputBytes": 8000000,
      "maxResponseBytes": 262144
    }
  }
}
```

The child runs with the project root as its working directory, never through a shell, and inherits the parent environment so the CLI can use its own login. Doc Bridge enforces timeout, output and proposal-schema limits, rejects non-zero exits, non-JSON output, mismatched hashes, and invalid origins. The CLI is an explicit trust boundary: its own network and filesystem permissions are controlled by the operator, not by Doc Bridge.

## Recovery and CI

Rerunning an unchanged command reuses valid stage artifacts. A changed source revision, configuration hash, or tool version creates a stale/superseding run. CI can use `ak-docs check --json`; non-zero rule findings fail the command while unsupported analysis is reported as explicit coverage.

The first implementation analyzes JavaScript/TypeScript and Markdown. Other languages should add analyzers that emit the same canonical entity, relation, evidence, coverage, and hash contracts.

## What the Markdown analyzer reads

Documentation is parsed with remark (CommonMark plus GFM), so a document's own prose becomes
evidence: links between documents, paths and package names in inline code, and exported names all
become `observed` relations carrying the line they were claimed on. The contract — relation kinds,
the ambiguity and near-miss rules, generated regions, the document fields and the `docbridge`
schema — is [Markdown analyzer v1](./spec/markdown-analyzer-v1.md).

## Relation coverage policy

Agent documents under the configured `corpus.agent.root` may use the conventional
`packages/<name>.md` or `apps/<name>.md` path to declare package coverage without a
`humanDoc` field. This is intentionally separate from the human bridge: `humanDoc`
still reports whether an agent has a resolvable human-facing guide.

Missing declarations are configurable because not every implementation import is useful documentation. In the root configuration, `reconciliation.scope` selects the semantic comparison level while `reconciliation.requiredRelationKinds` selects the observed relation kinds that must be declared in Markdown. A single-package repository wants `scope: "area"`: at package scope its internal relations aggregate into one self-loop the comparison skips, so nothing is reported. See [areas](./spec/config-v1.md#analysisareas-optional). Raw file relations remain available in the snapshot and report for evidence and exploration:

```json
{
  "reconciliation": {
    "scope": "package",
    "requiredRelationKinds": ["imports", "re-exports", "depends-on"],
    "requiredRelationTargets": "internal"
  }
}
```

Omit the option to preserve the original all-relation behavior. Use an empty list for low-friction adoption when package/app coverage and explicitly declared claims matter more than documenting every module, test, or external-library import. Existing declarations are still checked for stale, conflicting, and unresolved references.

With `requiredRelationTargets: "internal"`, external-library relations remain in the canonical graph and evidence trail but do not require a Markdown declaration. Internal project relations still require declarations and remain subject to stale, conflicting, and unresolved checks.

Package health is not inferred from coverage presence alone. A covered package
is `fresh` only when its relevant relations are verified; undocumented or
not-analyzed relations make it `unverified`, while conflicting declarations
make it `stale`. This prevents a high-level coverage document from hiding a
large architecture/documentation gap.

The reconciliation summary also includes deterministic `diagnosticsByCode` and
`diagnosticsByStatus` rollups. Use them for triage and dashboards, but keep the
canonical diagnostics and their evidence as the source of truth.

Document counts are intentionally split by classification. The total document
inventory includes human, agent, project, archive, and unclassified Markdown;
it is not the denominator for agent-corpus coverage. Compare
`documentClassificationCounts.agent` with
`documentedDocumentClassificationCounts.agent` for the configured agent-doc
surface, and inspect the remaining classifications separately.