@agentskit/doc-bridge 1.0.2 → 1.2.1

package/docs/meta.json

@@ -0,0 +1,20 @@
+{
+  "title": "Doc Bridge",
+  "pages": [
+    "index",
+    "getting-started",
+    "for-agents",
+    "MARKETPLACE",
+    "POSITIONING",
+    "mcp",
+    "query",
+    "examples",
+    "chat-and-rag",
+    "ollama-demo",
+    "playbook",
+    "recipes",
+    "schemas",
+    "skills",
+    "spec"
+  ]
+}

package/docs/ollama-demo.md

@@ -1,3 +1,8 @@
+---
+title: Ollama chat demo
+description: Run the optional local chat layer with Ollama after deterministic routing.
+---
+
 # Ollama chat demo (Layer 1)
 
 Zero-cloud path for grounded `ak-docs chat` and `ak-docs ask --chat`.
@@ -61,4 +66,4 @@ Skips gracefully if Ollama is down or peers are missing (safe for CI as optional
 | `Intelligence provider request failed` | `ollama serve` not running |
 | `Optional peer "@agentskit/rag" is not installed` | Install Layer 1 peers (see above) |
 | Empty chat response | Pull models: `ollama pull llama3.2` |
-| Slow first `rag ingest` | Normal — embeds entire corpus locally |
+| Slow first `rag ingest` | Normal — embeds entire corpus locally |

package/docs/playbook/doc-bridge-pattern.md

@@ -1,6 +1,8 @@
 ---
 type: pattern
 id: doc-bridge-pattern
+title: Doc Bridge pattern
+description: A reusable pattern for making documentation useful to humans and agents.
 purpose: Route coding agents to the correct package, checks, and human docs in any monorepo.
 owner: AgentsKit
 license: CC-BY-4.0
@@ -75,7 +77,7 @@ Agents call `handoff.resolve` before editing `packages/*`:
 ## CI gate
 
 ```yaml
-- uses: AgentsKit-io/doc-bridge@v1.0.0
+- uses: AgentsKit-io/doc-bridge@v1.2.1
 ```
 
 Or: `ak-docs index && ak-docs gate run` — stale index fails the PR.
@@ -111,4 +113,4 @@ Teams track handoff % and human-bridge % daily.
 - npm: https://www.npmjs.com/package/@agentskit/doc-bridge
 - repo: https://github.com/AgentsKit-io/doc-bridge
 - skill: [doc-bridge skill](../skills/doc-bridge.md)
-- landing: https://agentskit-io.github.io/doc-bridge/
+- landing: https://agentskit-io.github.io/doc-bridge/

package/docs/query.md

@@ -0,0 +1,34 @@
+---
+title: Deterministic query engine
+description: Ownership and documentation lookup rules for contributors changing Doc Bridge query behavior.
+---
+
+# Deterministic query engine
+
+The query layer reads the generated `.doc-bridge/index.json`; it does not scan
+the repository again and does not call a model. Keep exact ownership resolution,
+ranked document search, and handoff output deterministic.
+
+## Ownership
+
+- Source: `src/query/**`
+- Index contract: `src/schemas/doc-bridge-index.ts`
+- Handoff contract: `src/schemas/agent-handoff.ts`
+- CLI consumers: `src/cli/program.ts`
+- MCP consumers: `src/mcp/server.ts`
+
+## Before editing
+
+Read [DocBridgeIndex v1](./schemas/doc-bridge-index-v1.md), [AgentHandoff v1](./schemas/agent-handoff-v1.md), and the [CLI reference](./spec/cli.md).
+
+## Checks
+
+```bash
+pnpm test
+pnpm typecheck
+node bin/ak-docs.js index
+node bin/ak-docs.js query package doc-bridge-query --agent
+```
+
+Preserve stable JSON fields and text output. A breaking contract change requires
+a schema version rather than an implicit reinterpretation of v1.

package/docs/recipes/index-pipeline.md

@@ -1,3 +1,8 @@
+---
+title: Index pipeline recipes
+description: Compose indexing, querying, gating, and CI into repeatable documentation workflows.
+---
+
 # Index pipeline recipes
 
 Keep `.doc-bridge/index.json` fresh during development and in CI.
@@ -66,7 +71,7 @@ Root `package.json`:
 ## CI (GitHub Action)
 
 ```yaml
-- uses: AgentsKit-io/doc-bridge@v1.0.0
+- uses: AgentsKit-io/doc-bridge@v1.2.1
 ```
 
 Or manual:
@@ -86,4 +91,4 @@ ak-docs doctor --write-badge
 pnpm coverage:badge
 ```
 
-Paste the shields.io line from `.doc-bridge/coverage-badge.json` → `markdown` field.
+Paste the shields.io line from `.doc-bridge/coverage-badge.json` → `markdown` field.

package/docs/schemas/agent-handoff-v1.md

@@ -1,3 +1,8 @@
+---
+title: AgentHandoff v1
+description: Machine-readable contract for a compact, actionable coding-agent handoff.
+---
+
 # AgentHandoff v1
 
 Zod schema: `AgentHandoffV1Schema` in `@agentskit/doc-bridge`.

package/docs/schemas/doc-bridge-index-v1.md

@@ -1,3 +1,8 @@
+---
+title: DocBridgeIndex v1
+description: Schema reference for the deterministic Doc Bridge repository index.
+---
+
 # DocBridgeIndex v1
 
 Zod schema: `DocBridgeIndexV1Schema` in `@agentskit/doc-bridge`.

package/docs/schemas/memory-candidate-v1.md

@@ -1,10 +1,24 @@
+---
+title: MemoryCandidate v1
+description: Contract for reviewing and promoting durable agent memory into canonical documentation.
+---
+
 # MemoryCandidate v1
 
 Zod schema: `MemoryCandidateV1Schema` in `@agentskit/doc-bridge`.
 
 Portable JSON Schema export: `MemoryCandidateV1JsonSchema`.
 
-This is the normalized draft shape for memory ingestion. Layer 0 ships deterministic local ingest for Cursor rules and `.agent-memory/**/*.md`; classification and promotion are planned.
+This is the normalized shape for memory ingestion. The core ships deterministic
+local ingest for Cursor rules and `.agent-memory/**/*.md`, classification into
+`agent | human | playbook | discard`, safety scanning, draft generation, and an
+optional GitHub draft PR flow.
+
+```bash
+ak-docs memory ingest
+ak-docs memory classify
+ak-docs memory promote --pr --dry-run
+```
 
 ## Shape
 

package/docs/skills/doc-bridge.md

@@ -1,3 +1,8 @@
+---
+title: Agent routing skill
+description: Give coding agents a deterministic recipe for finding ownership and checks.
+---
+
 # Doc Bridge — agent routing skill
 
 Use this skill in Cursor, Claude Code, or Codex so agents resolve ownership **before** editing packages.
@@ -61,4 +66,4 @@ Before editing any file under packages/ or apps/:
 ```bash
 ak-docs ask "auth is broken in staging"
 ak-docs doctor --text
-```
+```

package/docs/spec/cli.md

@@ -1,3 +1,8 @@
+---
+title: ak-docs CLI
+description: Complete command reference for indexing, querying, gates, doctor, memory, and MCP.
+---
+
 # ak-docs CLI
 
 Command-line interface for **`@agentskit/doc-bridge`**. The npm package is scoped; the **only published binary** is `ak-docs`.
@@ -69,6 +74,7 @@ pnpm add -D @agentskit/doc-bridge
 | `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 conformance run documentation-standard-v1 [--text\|--json]` | Run the stable ecosystem documentation profile with evidence and remediation |
 | `ak-docs mcp` | Start MCP server (stdio default) |
 | `ak-docs mcp install --cursor \| --claude` | Write MCP server config for Cursor or Claude Desktop |
 

package/docs/spec/config-v1.md

@@ -1,3 +1,8 @@
+---
+title: Configuration contract v1
+description: Configure documentation corpora, ownership routing, conformance, and gates.
+---
+
 # 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.
@@ -63,6 +68,9 @@ export default {
 
   /** Optional: Playbook / Registry / remote OKF bundles */
   federation?: FederationConfig
+
+  /** Optional deterministic documentation conformance profiles */
+  conformance?: ConformanceConfig
 } satisfies DocBridgeConfigV1
 ```
 
@@ -248,7 +256,7 @@ Plugins document their join convention; gates fail on orphan links.
 
 ```ts
 type GatesConfig = {
-  preset?: 'minimal' | 'standard' | 'strict'
+  preset?: 'minimal' | 'standard' | 'strict' | 'playbook'
   /** Enabled gate ids; merged with preset */
   include?: GateId[]
   exclude?: GateId[]
@@ -269,18 +277,18 @@ type GatesConfig = {
         | 'no-stale-wording'
       >
     }
-    'link-rot'?: { scanDirs?: string[] }
   }
 }
 
 type GateId =
   | 'index-freshness'
   | 'human-guide-links'
-  | 'link-rot'
+  | 'link-rot'                    // reserved; emits a diagnostic and is not executed
   | 'okf-type'
   | 'docs-style'
-  | 'routing-currency'             // every workspace package appears in routing
-  | 'bootstrap-size'               // AGENTS.md / CLAUDE.md line budgets
+  | 'routing-currency'            // reserved; emits a diagnostic and is not executed
+  | 'bootstrap-size'              // reserved; emits a diagnostic and is not executed
+  | 'documentation-standard-v1'    // opt-in ecosystem documentation profile
 ```
 
 | Preset | Gates |
@@ -289,7 +297,7 @@ type GateId =
 | `standard` | + `human-guide-links` in v0.1 alpha |
 | `strict` | + `okf-type` in v0.1 alpha |
 
-Implemented alpha gates: `index-freshness`, `human-guide-links`, `okf-type`, `docs-style`. `include` / `exclude` are applied to implemented gates only.
+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
 
@@ -306,6 +314,47 @@ Alpha gates are deterministic lint checks, not editorial grading:
 
 ---
 
+## `conformance` (optional)
+
+Documentation Standard v1 is an opt-in, deterministic ecosystem profile. It validates
+repository evidence without executing configured commands or making network/model calls.
+
+```ts
+type ConformanceConfig = {
+  documentationStandardV1?: {
+    rawSources?: string[]
+    contributionPaths?: string[]
+    metadata?: Array<{ path: string; contains: string[] }>
+    links?: Array<{ url: string; paths: string[] }>
+    quickstarts?: Array<{
+      id: string
+      doc: string
+      test: string
+      command: string
+      testContains: string[]
+    }>
+    visuals?: string[]
+    diagrams?: Array<{ path: string; contains: string[] }>
+    ecosystemContract?: {
+      manifest: string
+      claims: string
+      productId: string
+    }
+    exceptions?: Array<{
+      ruleId: DocumentationStandardRuleId
+      reason: string
+      approvedBy: string
+      trackingUrl: string
+    }>
+  }
+}
+```
+
+See [Documentation Standard v1](documentation-standard-v1.md) for rule semantics,
+report status, commands, and the recorded stable-publication HITL decision.
+
+---
+
 ## `surfaces` (optional)
 
 ```ts
@@ -589,6 +638,7 @@ export default defineConfig({
 | `ak-docs search <q>` | `index` |
 | `ak-docs retrieve <q>` | `index` + `federation` |
 | `ak-docs gate run` | `gates` |
+| `ak-docs conformance run documentation-standard-v1` | `corpus`, `routing`, `index`, `conformance` |
 | `ak-docs mcp` | `surfaces.mcp` |
 | `ak-docs chat` | planned; `intelligence.*` |
 | `ak-docs memory ingest` | deterministic local ingest; `MemoryCandidate[]` |

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

@@ -0,0 +1,136 @@
+---
+title: Documentation Standard v1
+description: Shared quality contract for AgentsKit documentation, metadata, examples, links, and visuals.
+---
+
+# Documentation Standard v1
+
+Status: **stable — HITL-approved on 2026-07-13**
+
+Profile ID: `documentation-standard-v1`
+
+Schema version: `1`
+
+Documentation Standard v1 is a deterministic Doc Bridge conformance profile for
+documentation properties in the AgentsKit ecosystem. It turns the shared quality
+expectations into local evidence that humans, CI, and agents can inspect without a model,
+API key, or network request.
+
+```mermaid
+flowchart LR
+  A[Human docs] --> P[Documentation Standard v1]
+  L[llms.txt and raw sources] --> P
+  H[AgentHandoff index] --> P
+  C[Contribution and metadata] --> P
+  Q[Quickstart test evidence] --> P
+  P --> R[Versioned conformance report]
+  R --> CI[CI exit code]
+  R --> HITL[Human approval]
+```
+
+## Rule set
+
+| Rule | Level | Passing evidence |
+|---|---|---|
+| `human-docs` | Required | A configured human adapter discovers at least one non-agent document |
+| `llms-and-raw-source` | Required | `llms.txt` exactly matches the current deterministic Doc Bridge output and every declared raw source is non-empty |
+| `agent-handoffs` | Required | Every emitted handoff has `startHere`, edit roots, checks, and a linked/external human bridge |
+| `contribution` | Required | At least one declared contribution guide exists and is non-empty |
+| `metadata` | Required | Declared metadata files exist and contain every configured marker |
+| `cross-links` | Required | Vendored canonical manifest/claims snapshots agree, include this product, and every declared URL is canonical and occurs in source |
+| `tested-quickstarts` | Required | Each quickstart maps a doc to a test file, identifying test markers, and a CI command |
+| `visual-explanations` | Recommended | Every declared image or animation asset exists |
+| `structured-diagrams` | Recommended | Declared diagram source exists and contains its configured marker |
+
+Recommended failures remain visible but do not fail the command. Required failures return
+exit code 1 unless an approved exception applies.
+
+## Approved exceptions
+
+Exceptions are explicit audit records, not hidden exclusions. A valid exception requires
+the rule ID, a substantive reason, the approver, and a tracking URL:
+
+```json
+{
+  "ruleId": "structured-diagrams",
+  "reason": "The interactive visual already expresses this relationship more clearly.",
+  "approvedBy": "Documentation Working Group",
+  "trackingUrl": "https://github.com/AgentsKit-io/example/issues/123"
+}
+```
+
+The report uses status `excepted`; it never rewrites an exception as an ordinary pass.
+
+## Configuration
+
+```json
+{
+  "conformance": {
+    "documentationStandardV1": {
+      "rawSources": ["README.md", "docs/getting-started.md"],
+      "contributionPaths": ["CONTRIBUTING.md"],
+      "metadata": [
+        { "path": "docs/index.html", "contains": ["<title>", "name=\"description\""] }
+      ],
+      "links": [
+        { "url": "https://www.agentskit.io", "paths": ["README.md"] }
+      ],
+      "ecosystemContract": {
+        "manifest": "ecosystem.json",
+        "claims": "ecosystem-claims.json",
+        "productId": "example"
+      },
+      "quickstarts": [
+        {
+          "id": "demo",
+          "doc": "README.md",
+          "test": "tests/demo.test.ts",
+          "command": "pnpm vitest run tests/demo.test.ts",
+          "testContains": ["runs the demo"]
+        }
+      ],
+      "visuals": ["docs/assets/overview.webp"],
+      "diagrams": [
+        { "path": "docs/architecture.md", "contains": ["```mermaid"] }
+      ],
+      "exceptions": []
+    }
+  }
+}
+```
+
+The profile does not execute the declared quickstart command. The test-evidence file and
+identifying markers prove that the quickstart has a repository test; the normal CI suite
+executes that test. This avoids turning documentation configuration into an arbitrary
+command-execution surface.
+
+The ecosystem contract files are committed, network-free consumer snapshots of the canonical
+AgentsKit `ecosystem.json` v2 manifest and `ecosystem-claims.json` ledger. The gate verifies
+their schema relationship, product identity parity, the adopting product ID, and that declared
+cross-links occur both in the manifest's public surfaces and in repository documentation.
+Doc Bridge also records the upstream ref and SHA-256 digests in `ecosystem-upstream.json`;
+`pnpm check:ecosystem-upstream` compares the local snapshots with AgentsKit `main` in CI.
+This network parity check is deliberately separate from the runtime conformance profile, which
+remains deterministic and offline.
+
+## Run the profile
+
+```bash
+ak-docs conformance run documentation-standard-v1 --text
+ak-docs conformance run documentation-standard-v1 --json
+ak-docs gate run documentation-standard-v1
+```
+
+JSON output is the stable automation surface. Text output sends the same evidence in a
+human-scannable form. Both return 0 when required rules pass or are explicitly excepted,
+and 1 when a required rule fails.
+
+## Adoption and stability
+
+The Doc Bridge repository is the first real fixture and dogfoods the profile in its normal
+`ak-docs gate run`. Other ecosystem repositories adopt it in their documentation slices.
+The required/recommended rule split received product-owner HITL approval in
+[issue #27](https://github.com/AgentsKit-io/doc-bridge/issues/27), and the canonical ecosystem
+contract was delivered by
+[AgentsKit #1208](https://github.com/AgentsKit-io/agentskit/pull/1208). The profile is stable;
+future breaking rule changes require a new version.

package/docs/spec/playbook-feedback.md

@@ -1,3 +1,8 @@
+---
+title: Playbook feedback promotion
+description: Promote durable implementation lessons into reviewed AgentsKit Playbook contributions.
+---
+
 # Playbook Feedback Promotion
 
 doc-bridge can feed durable documentation learnings back into public patterns, but promotion must be explicit and reviewable.

package/docs/spec/registry-agents.md

@@ -1,3 +1,8 @@
+---
+title: Registry agent topology
+description: Connect registry agent definitions to Doc Bridge ownership and documentation handoffs.
+---
+
 # Registry Agent Topology
 
 doc-bridge exposes deterministic tools; Registry agents can compose them into maintenance flows.

package/ecosystem-claims.json

@@ -0,0 +1,187 @@
+{
+  "schemaVersion": 1,
+  "manifestSchemaVersion": 2,
+  "products": [
+    {
+      "productId": "agentskit",
+      "source": {
+        "type": "endpoint",
+        "url": "https://www.agentskit.io/api/stats.json"
+      },
+      "verification": "verified",
+      "claims": [
+        {
+          "id": "packages",
+          "value": 22,
+          "noun": "packages",
+          "conservativeFloor": 22,
+          "evidence": {
+            "type": "repository-derivation",
+            "repo": "AgentsKit-io/agentskit",
+            "path": "scripts/compute-stats.mjs",
+            "summary": "Published non-private @agentskit/* package directories."
+          }
+        },
+        {
+          "id": "framework-bindings",
+          "value": 7,
+          "noun": "framework bindings",
+          "evidence": {
+            "type": "repository-derivation",
+            "repo": "AgentsKit-io/agentskit",
+            "path": "scripts/compute-stats.mjs",
+            "summary": "Published framework bindings from the supported binding list."
+          }
+        },
+        {
+          "id": "native-adapters",
+          "value": 25,
+          "noun": "native adapters",
+          "conservativeFloor": 25,
+          "evidence": {
+            "type": "repository-derivation",
+            "repo": "AgentsKit-io/agentskit",
+            "path": "scripts/compute-stats.mjs",
+            "summary": "Provider exports in the adapters package excluding composition helpers."
+          }
+        },
+        {
+          "id": "integrations",
+          "value": 50,
+          "noun": "integrations",
+          "conservativeFloor": 50,
+          "evidence": {
+            "type": "repository-derivation",
+            "repo": "AgentsKit-io/agentskit",
+            "path": "scripts/compute-stats.mjs",
+            "summary": "Service directories in the integrations catalog."
+          }
+        },
+        {
+          "id": "catalog-providers",
+          "value": 140,
+          "noun": "providers",
+          "conservativeFloor": 140,
+          "evidence": {
+            "type": "repository-derivation",
+            "repo": "AgentsKit-io/agentskit",
+            "path": "scripts/compute-stats.mjs",
+            "summary": "Providers in the committed model catalog snapshot."
+          }
+        },
+        {
+          "id": "catalog-models",
+          "value": 5162,
+          "noun": "models",
+          "conservativeFloor": 5000,
+          "evidence": {
+            "type": "repository-derivation",
+            "repo": "AgentsKit-io/agentskit",
+            "path": "scripts/compute-stats.mjs",
+            "summary": "Models in the committed provider catalog snapshot."
+          }
+        },
+        {
+          "id": "skills",
+          "value": 21,
+          "noun": "ready-made skills",
+          "conservativeFloor": 21,
+          "evidence": {
+            "type": "repository-derivation",
+            "repo": "AgentsKit-io/agentskit",
+            "path": "scripts/compute-stats.mjs",
+            "summary": "Concrete skill modules excluding registry and composition helpers."
+          }
+        },
+        {
+          "id": "memory-backends",
+          "value": 17,
+          "noun": "memory backends",
+          "evidence": {
+            "type": "repository-derivation",
+            "repo": "AgentsKit-io/agentskit",
+            "path": "scripts/compute-stats.mjs",
+            "summary": "Concrete memory modules excluding contracts and helpers."
+          }
+        },
+        {
+          "id": "recipes",
+          "value": 69,
+          "noun": "recipes",
+          "conservativeFloor": 69,
+          "evidence": {
+            "type": "repository-derivation",
+            "repo": "AgentsKit-io/agentskit",
+            "path": "scripts/compute-stats.mjs",
+            "summary": "Published recipe MDX pages excluding indexes and metadata."
+          }
+        },
+        {
+          "id": "core-size-kb-gzip",
+          "value": 10,
+          "noun": "KB gzipped core budget",
+          "evidence": {
+            "type": "repository-derivation",
+            "repo": "AgentsKit-io/agentskit",
+            "path": "scripts/compute-stats.mjs",
+            "summary": "Configured ESM gzip size budget for @agentskit/core."
+          }
+        }
+      ]
+    },
+    {
+      "productId": "registry",
+      "source": {
+        "type": "endpoint",
+        "url": "https://registry.agentskit.io/r/index.json"
+      },
+      "verification": "declared",
+      "claims": []
+    },
+    {
+      "productId": "agentskit-chat",
+      "source": {
+        "type": "repository",
+        "repo": "AgentsKit-io/agentskit-chat"
+      },
+      "verification": "declared",
+      "claims": []
+    },
+    {
+      "productId": "playbook",
+      "source": {
+        "type": "endpoint",
+        "url": "https://playbook.agentskit.io/api/stats.json"
+      },
+      "verification": "declared",
+      "claims": []
+    },
+    {
+      "productId": "doc-bridge",
+      "source": {
+        "type": "repository",
+        "repo": "AgentsKit-io/doc-bridge"
+      },
+      "verification": "declared",
+      "claims": []
+    },
+    {
+      "productId": "code-review",
+      "source": {
+        "type": "repository",
+        "repo": "AgentsKit-io/code-review-cli"
+      },
+      "verification": "declared",
+      "claims": []
+    },
+    {
+      "productId": "akos",
+      "source": {
+        "type": "endpoint",
+        "url": "https://akos.agentskit.io/api/stats.json"
+      },
+      "verification": "declared",
+      "claims": []
+    }
+  ]
+}

package/ecosystem-upstream.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "repository": "AgentsKit-io/agentskit",
+  "ref": "main",
+  "files": {
+    "ecosystem.json": "95adc3c083dd04885e52ff4cb9528b9d73d99d9c69e01408a484e1e862d0e797",
+    "ecosystem-claims.json": "0100f7fbc18a3381bb943aaf8151dd5d107f82c02c470e3c586b7d694c6be42e"
+  }
+}