@agentskit/doc-bridge 1.0.1 → 1.1.1

package/docs/RELEASE.md

@@ -4,13 +4,19 @@
 
 ```bash
 pnpm install
+pnpm audit --audit-level low
 pnpm typecheck
+pnpm check:ecosystem-upstream
 pnpm test
+pnpm coverage
 pnpm build
 pnpm smoke:packaged
+node bin/ak-docs.js index
+node bin/ak-docs.js gate run
+node bin/ak-docs.js conformance run documentation-standard-v1 --text
 ```
 
-Expect: packaged smoke prints `packaged smoke passed` and includes demo `query package example --agent`.
+Expect: zero known vulnerabilities, coverage above the repository threshold, packaged smoke prints `packaged smoke passed`, and every required and recommended documentation rule passes without exceptions.
 
 ## Version
 
@@ -21,45 +27,37 @@ pnpm changeset          # if new entry needed
 pnpm version-packages   # bumps package.json + CHANGELOG from .changeset/*
 ```
 
-Current track: **`1.0.0` stable** (alpha series ended at `0.1.0-alpha.5`).
+Current track: **`1.1.1` stable** (alpha series ended at `0.1.0-alpha.5`).
 
-## Publish (npm)
+## Publish (npm + GitHub)
 
-Requires npm auth for the `@agentskit` org (`npm whoami` / `NPM_TOKEN`).
+Stable releases are published only by `.github/workflows/release.yml` from an immutable semver tag. The workflow re-runs the complete security, test, coverage, packaged-smoke, dogfood, and conformance matrix, publishes with npm provenance through the `npm` environment, verifies the registry result, uploads the tarball to GitHub Releases, and then marks the release latest.
 
 ```bash
-pnpm release
-# equivalent:
-# pnpm build && pnpm test && changeset publish
+git tag v1.1.1
+git push origin v1.1.1
 ```
 
-Or one-shot after version bump:
+For recovery of an existing immutable tag, use the guarded manual dispatch. Never move or recreate a release tag.
 
 ```bash
-npm publish --access public
+gh workflow run release.yml --ref master -f tag=v1.1.1
 ```
 
 Confirm:
 
 ```bash
-npm view @agentskit/doc-bridge version
-npx ak-docs@0.1.0-alpha.x --version
+npm view @agentskit/doc-bridge@1.1.1 version dist.integrity
+npx ak-docs@1.1.1 --version
+gh release view v1.1.1
 ```
 
-## GitHub
-
-```bash
-git tag v1.0.0
-git push origin master --tags
-gh release create v1.0.0 --title "v1.0.0 — AgentHandoff stable" --notes-file CHANGELOG.md
-```
-
-Enable GitHub Pages (Settings → Pages → GitHub Actions) for landing deploy from `.github/workflows/pages.yml`.
+GitHub Pages must remain configured for GitHub Actions; `.github/workflows/pages.yml` deploys the landing page from `docs/landing`.
 
 ## Post-publish smoke (fresh machine)
 
 ```bash
-npm i -D @agentskit/doc-bridge@0.1.0-alpha.x
+npm i -D @agentskit/doc-bridge@1.1.1
 npx ak-docs init
 npx ak-docs index
 npx ak-docs query package example --agent

package/docs/getting-started.md

@@ -1,5 +1,16 @@
 # Getting started
 
+doc-bridge turns your existing docs into an **AgentHandoff** index:
+
+- `startHere` — what the agent reads first
+- `editRoots` — where the agent is allowed to work
+- `checks` — what proves the edit
+- `humanDoc` — the human-facing guide for the same area
+
+It also runs the inverse loop: local agent memory becomes a classified,
+reviewable documentation draft. Start with CLI. Add MCP when agents should call
+it automatically. Add CI when the bridge becomes part of review.
+
 ## Install
 
 ```bash
@@ -60,6 +71,17 @@ Project root for `--config path/to/doc-bridge.config.json` is the **directory of
 
 See [config-v1](./spec/config-v1.md) and [examples](./examples.md).
 
+## Use surfaces
+
+| Surface | When to use | Command |
+|---------|-------------|---------|
+| CLI | You want to inspect or debug the bridge yourself | `ak-docs query package <id> --agent` |
+| MCP | You want coding agents to resolve handoffs before editing | `ak-docs mcp install --cursor` |
+| CI | You want stale indexes and broken links to fail PRs | `ak-docs index && ak-docs gate run` |
+| Adapters | You already have Fumadocs, Docusaurus, or markdown docs | configure `corpus.human` |
+| Memory pipeline | You want agent notes turned into reviewable docs | `ak-docs memory promote --pr --dry-run` |
+| Optional RAG/chat | You want a terminal assistant grounded in the same index | `ak-docs rag ingest && ak-docs chat` |
+
 ## MCP (Cursor / Claude)
 
 ```json
@@ -90,10 +112,13 @@ ak-docs bootstrap agent-docs         # draft agent docs from human site
 ```bash
 ak-docs memory ingest
 ak-docs memory classify
-ak-docs memory promote   # draft only — never auto-merges
+ak-docs memory promote              # prints a safe draft body
+ak-docs memory promote --pr --dry-run
+ak-docs memory promote --pr         # opens a GitHub draft PR via gh
 ```
 
-Sources include `.agent-memory/**` and `.cursor/rules/*.mdc`.
+Sources include `.agent-memory/**` and `.cursor/rules/*.mdc`. Promotion is
+draft-only and never auto-merges.
 
 ## Optional chat + RAG (AgentsKit)
 

package/docs/landing/index.html

@@ -3,8 +3,8 @@
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>doc-bridge — AgentHandoff for your monorepo</title>
-  <meta name="description" content="Deterministic routing for coding agents: edit the right package, run the right checks, bridge to human docs. No API key required." />
+  <title>doc-bridge — docs your agents can act on</title>
+  <meta name="description" content="Turn human docs into executable handoffs for agents, and turn agent memory into reviewable documentation drafts. MCP, CLI, CI. No API key required." />
   <link rel="preconnect" href="https://fonts.googleapis.com" />
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
   <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600;700&display=swap" rel="stylesheet" />
@@ -105,6 +105,22 @@
     .dot-y { background: var(--amber); }
     .dot-g { background: var(--green); }
     .terminal-body { padding: 1.25rem 1.5rem; overflow-x: auto; }
+    .hero-image {
+      display: block;
+      width: 100%;
+      margin: 0 0 2rem;
+      border: 1px solid var(--border);
+      border-radius: var(--radius);
+      box-shadow: 0 24px 70px rgba(0, 0, 0, 0.35);
+    }
+    .section-image {
+      display: block;
+      width: 100%;
+      margin: 0 0 1.5rem;
+      border: 1px solid var(--border);
+      border-radius: var(--radius);
+      box-shadow: 0 18px 50px rgba(0, 0, 0, 0.28);
+    }
     .t-dim { color: var(--muted); }
     .t-ok { color: var(--green); }
     .t-bad { color: var(--red); }
@@ -145,6 +161,25 @@
       text-decoration: none;
     }
     .used-by a:hover { border-color: var(--accent-dim); }
+    .surface-table {
+      width: 100%;
+      border-collapse: collapse;
+      overflow: hidden;
+      border: 1px solid var(--border);
+      border-radius: var(--radius);
+      background: var(--surface);
+    }
+    .surface-table th,
+    .surface-table td {
+      padding: 0.9rem 1rem;
+      border-bottom: 1px solid var(--border);
+      text-align: left;
+      vertical-align: top;
+      font-size: 0.92rem;
+    }
+    .surface-table th { color: var(--text); font-weight: 600; }
+    .surface-table td { color: var(--muted); }
+    .surface-table tr:last-child td { border-bottom: 0; }
     .badge-row { display: flex; flex-wrap: wrap; gap: 0.5rem; margin-top: 1.5rem; }
     .badge-row img { height: 22px; }
     footer {
@@ -173,16 +208,19 @@
   <main>
     <section class="hero">
       <div class="wrap">
-        <div class="eyebrow">AgentHandoff for your monorepo</div>
-        <h1>Your agent never edits the wrong package again.</h1>
+        <div class="eyebrow">Docs your agents can act on</div>
+        <h1>Turn repo docs into executable handoffs.</h1>
         <p class="lead">
-          Deterministic handoffs: <strong>startHere</strong>, <strong>editRoots</strong>, <strong>checks</strong>, and a bridge to human docs.
-          Layer 0 works without any LLM or API key.
+          doc-bridge gives every coding agent the same contract: <strong>startHere</strong>,
+          <strong>editRoots</strong>, <strong>checks</strong>, and <strong>humanDoc</strong>.
+          Then it turns agent memory back into reviewable documentation drafts.
+          Use it from CLI, MCP, and CI. No LLM or API key required.
         </p>
         <div class="cta-row">
           <a class="btn btn-primary" href="#demo">See 60s demo</a>
           <a class="btn btn-ghost" href="https://github.com/AgentsKit-io/doc-bridge#readme">Read README</a>
         </div>
+        <img class="hero-image" src="assets/doc-bridge-hero.webp" alt="doc-bridge maps human docs into structured agent handoffs for CLI, MCP, and CI" />
         <div class="grid-2" id="demo">
           <div class="terminal">
             <div class="terminal-bar"><span class="dot dot-r"></span><span class="dot dot-y"></span><span class="dot dot-g"></span></div>
@@ -221,10 +259,32 @@
       </div>
     </section>
 
+    <section>
+      <div class="wrap">
+        <h2>Use it where agents already work</h2>
+        <p class="section-lead">One index, multiple surfaces. Start with the CLI; wire MCP and CI when the first handoff is useful.</p>
+        <img class="section-image" src="assets/doc-bridge-surfaces.webp" alt="doc-bridge index used through CLI, MCP, CI, and documentation adapters" />
+        <table class="surface-table">
+          <thead>
+            <tr><th>Surface</th><th>What it does</th><th>How you use it</th></tr>
+          </thead>
+          <tbody>
+            <tr><td>CLI</td><td>Query ownership, inspect handoffs, run doctor, search docs.</td><td><code>ak-docs query package auth --agent</code></td></tr>
+            <tr><td>MCP</td><td>Lets Cursor, Claude Code, and Codex-style agents resolve before editing.</td><td><code>ak-docs mcp install --cursor</code></td></tr>
+            <tr><td>CI</td><td>Blocks stale indexes and broken human-doc bridges.</td><td><code>ak-docs index && ak-docs gate run</code></td></tr>
+            <tr><td>Adapters</td><td>Connect Fumadocs, Docusaurus, plain markdown, and pnpm workspaces.</td><td><code>fumadocs</code> · <code>docusaurus</code> · <code>plain-markdown</code></td></tr>
+            <tr><td>Memory pipeline</td><td>Classifies local agent memory and drafts documentation updates.</td><td><code>ak-docs memory promote --pr</code></td></tr>
+            <tr><td>Optional RAG/chat</td><td>Adds handoff-first chat when you install AgentsKit peers.</td><td><code>ak-docs rag ingest && ak-docs chat</code></td></tr>
+          </tbody>
+        </table>
+      </div>
+    </section>
+
     <section id="loops">
       <div class="wrap">
         <h2>Four loops, one bridge</h2>
         <p class="section-lead">Act, bridge, learn, explain — each loop has a CLI command and real output, not a concept table.</p>
+        <img class="section-image" src="assets/doc-bridge-two-way.webp" alt="doc-bridge connects human docs to coding agents and agent memory back to draft docs" />
         <div class="loops">
           <div class="card">
             <div class="loop-tag">Act</div>
@@ -238,8 +298,8 @@
           </div>
           <div class="card">
             <div class="loop-tag">Learn</div>
-            <h3>Memory → docs</h3>
-            <p><code>memory promote --pr</code> · HITL draft PR</p>
+            <h3>Agent memory → docs</h3>
+            <p><code>memory classify</code> · <code>promote --pr</code></p>
           </div>
           <div class="card">
             <div class="loop-tag">Explain</div>
@@ -277,7 +337,7 @@
           <div class="terminal-bar"><span class="dot dot-r"></span><span class="dot dot-y"></span><span class="dot dot-g"></span></div>
           <div class="terminal-body">
             <div class="t-dim"># .github/workflows/pr.yml</div>
-            <div>- uses: <span class="t-hi">AgentsKit-io/doc-bridge@v1.0.0</span></div>
+            <div>- uses: <span class="t-hi">AgentsKit-io/doc-bridge@v1.1.1</span></div>
             <div>&nbsp;&nbsp;with:</div>
             <div>&nbsp;&nbsp;&nbsp;&nbsp;config-path: doc-bridge.config.json</div>
           </div>
@@ -296,4 +356,4 @@
     </div>
   </footer>
 </body>
-</html>
+</html>

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

@@ -75,7 +75,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.1.1
 ```
 
 Or: `ak-docs index && ak-docs gate run` — stale index fails the PR.
@@ -111,4 +111,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/recipes/index-pipeline.md

@@ -66,7 +66,7 @@ Root `package.json`:
 ## CI (GitHub Action)
 
 ```yaml
-- uses: AgentsKit-io/doc-bridge@v1.0.0
+- uses: AgentsKit-io/doc-bridge@v1.1.1
 ```
 
 Or manual:
@@ -86,4 +86,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/memory-candidate-v1.md

@@ -4,7 +4,16 @@ 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/spec/cli.md

@@ -69,6 +69,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

@@ -63,6 +63,9 @@ export default {
 
   /** Optional: Playbook / Registry / remote OKF bundles */
   federation?: FederationConfig
+
+  /** Optional deterministic documentation conformance profiles */
+  conformance?: ConformanceConfig
 } satisfies DocBridgeConfigV1
 ```
 
@@ -248,7 +251,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 +272,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 +292,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 +309,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 +633,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,131 @@
+# 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.