@agentskit/doc-bridge 1.2.1 → 1.2.3

package/docs/index.md

@@ -1,23 +1,58 @@
 ---
 title: Documentation
-description: Choose the shortest Doc Bridge path for humans, agents, or pull-request enforcement.
+description: Practical Doc Bridge paths for humans, agents, PR gates, and MCP — one repository, two audiences.
 ---
 
 # Documentation
 
-Doc Bridge keeps one repository useful to both people and coding agents. Start with the outcome you need:
+Doc Bridge keeps **one repository** useful to people and coding agents. Pick the shortest path:
 
-- **Try it locally:** [Getting started](./getting-started.md)
-- **Route an agent:** [For agents](./for-agents.md)
-- **Block stale context in PRs:** [GitHub Marketplace](./MARKETPLACE.md)
-- **Connect an MCP client:** [MCP](./mcp.md)
+## Start
 
-```mermaid
-flowchart LR
-  D["Repository docs"] --> I["Deterministic index"]
-  I --> H["Human guide"]
-  I --> A["Agent handoff"]
-  I --> G["Pull-request gate"]
+| Goal | Page |
+| --- | --- |
+| Install + 60s proof | [Getting started](./getting-started.md) |
+| Guided install | [Install and run](./guides/install-and-run.md) |
+| Machine-first entry | [For agents](./for-agents.md) · site route `/for-agents` |
+| PR freshness gate | [Gate and CI](./guides/gate-ci.md) · [Marketplace](./MARKETPLACE.md) |
+
+## Build workflows
+
+| Goal | Page |
+| --- | --- |
+| Index + resolve ownership | [Index and query](./guides/index-and-query.md) · [Query](./query.md) |
+| MCP for Cursor / Claude | [MCP for agents](./guides/mcp-agents.md) · [MCP](./mcp.md) |
+| Memory digest → draft docs | [Memory pipeline](./guides/memory-pipeline.md) |
+| Every CLI command | [CLI map](./guides/cli-map.md) · [CLI reference](./spec/cli.md) |
+| Config sketches | [Examples](./examples.md) |
+| Optional chat / RAG | [Chat and RAG](./chat-and-rag.md) · [Ollama demo](./ollama-demo.md) |
+
+## How it works
+
+```text
+Repository docs
+      │
+      ▼
+ak-docs index  ──►  .doc-bridge/index.json + llms.txt
+      │
+      ├─► Human guides (Fumadocs / Docusaurus / md)
+      ├─► Agent handoff (CLI / MCP)
+      └─► PR gate (Marketplace Action)
 ```
 
-Long-form contracts remain available under **Specification** and as raw Markdown, without making the primary path read like a reference manual.
+1. **Index** — map ownership from corpus + config  
+2. **Resolve** — deterministic handoffs (`startHere`, `editRoots`, `checks`)  
+3. **Gate** — fail stale context before agents run  
+4. **Promote** — optional memory → draft docs loop  
+
+## Product vs reference
+
+- **Start / Guides** — get value in minutes  
+- **Product** — [Positioning](./POSITIONING.md), [Playbook pattern](./playbook/doc-bridge-pattern.md), [Recipes](./recipes/index-pipeline.md)  
+- **Reference** — [CLI](./spec/cli.md), [Config](./spec/config-v1.md), [Schemas](./schemas/agent-handoff-v1.md)  
+
+Machine surfaces: [llms.txt](/llms.txt) · [llms-full.txt](/llms-full.txt) · [raw Markdown](/raw/getting-started.md)
+
+## Ecosystem
+
+Part of AgentsKit — next to [AgentsKit](https://www.agentskit.io), [Registry](https://registry.agentskit.io), [Chat](https://chat.agentskit.io), [Playbook](https://playbook.agentskit.io), and [AKOS](https://akos.agentskit.io).

package/docs/mcp.md

@@ -62,3 +62,12 @@ Before editing a package:
 2. Open `startHere`  
 3. Stay inside `editRoots`  
 4. Run `checks` before claiming done  
+
+## Related
+
+- [MCP for agents guide](./guides/mcp-agents.md)  
+- [CLI map](./guides/cli-map.md)  
+- [Memory pipeline](./guides/memory-pipeline.md)  
+- [For agents](./for-agents.md)  
+- [Index and query](./guides/index-and-query.md)  
+- [Skill](./skills/doc-bridge.md) 

package/docs/meta.json

@@ -2,19 +2,25 @@
   "title": "Doc Bridge",
   "pages": [
     "index",
+    "---Start---",
     "getting-started",
+    "guides",
     "for-agents",
     "MARKETPLACE",
-    "POSITIONING",
+    "---Build---",
     "mcp",
     "query",
     "examples",
     "chat-and-rag",
     "ollama-demo",
+    "---Product---",
+    "POSITIONING",
     "playbook",
     "recipes",
+    "---Reference---",
     "schemas",
     "skills",
-    "spec"
+    "spec",
+    "RELEASE"
   ]
 }

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

@@ -113,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://doc-bridge.agentskit.io/

package/docs/query.md

@@ -1,34 +1,58 @@
 ---
-title: Deterministic query engine
-description: Ownership and documentation lookup rules for contributors changing Doc Bridge query behavior.
+title: Query
+description: Deterministic ownership and documentation lookup — no model, no re-scan of the repo.
 ---
 
-# Deterministic query engine
+# Query
 
-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.
+The query layer reads `.doc-bridge/index.json` only. It does **not** re-scan the repository and does **not** call a model.
 
-## Ownership
+## Commands
 
-- 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`
+```bash
+# Machine-readable handoff (for agents / MCP)
+ak-docs query package auth --agent
+ak-docs query ownership auth --agent
 
-## Before editing
+# Human-readable
+ak-docs query package auth --text
 
-Read [DocBridgeIndex v1](./schemas/doc-bridge-index-v1.md), [AgentHandoff v1](./schemas/agent-handoff-v1.md), and the [CLI reference](./spec/cli.md).
+# Discovery
+ak-docs list packages --text
+ak-docs ask "where do I change billing?"
+```
 
-## Checks
+## What you get
 
-```bash
-pnpm test
-pnpm typecheck
-node bin/ak-docs.js index
-node bin/ak-docs.js query package doc-bridge-query --agent
-```
+An **AgentHandoff** (v1) with stable fields:
+
+| Field | Use |
+| --- | --- |
+| `startHere` | First file the agent should open |
+| `editRoots` | Allowed write paths |
+| `checks` | Verification commands |
+| `humanDoc` | Parallel human documentation |
+
+Schema: [AgentHandoff v1](./schemas/agent-handoff-v1.md) · Index: [DocBridgeIndex v1](./schemas/doc-bridge-index-v1.md)
+
+## When to use which surface
+
+| Need | Surface |
+| --- | --- |
+| Agent about to edit a module | `query … --agent` or MCP `handoff.resolve` |
+| Human browsing ownership | `query … --text` / `list packages` |
+| Free-form question with known docs | `ask "…"` (local first) |
+| Unresolved semantic question | Optional [Chat and RAG](./chat-and-rag.md) backend |
+
+## Guarantees
+
+- Same inputs → same handoff JSON (deterministic)  
+- Breaking field meaning requires a **new schema version**, not silent reinterpretation of v1  
+- Gate/CI can require a fresh index so agents never see stale ownership  
+
+## Related
 
-Preserve stable JSON fields and text output. A breaking contract change requires
-a schema version rather than an implicit reinterpretation of v1.
+- [Guide: Index and query](./guides/index-and-query.md)  
+- [For agents](./for-agents.md)  
+- [CLI reference](./spec/cli.md)  
+- [MCP](./mcp.md)  

package/ecosystem-upstream.json

@@ -3,7 +3,7 @@
   "repository": "AgentsKit-io/agentskit",
   "ref": "main",
   "files": {
-    "ecosystem.json": "95adc3c083dd04885e52ff4cb9528b9d73d99d9c69e01408a484e1e862d0e797",
+    "ecosystem.json": "04995ca6863f744495b672d6e3a64162a415caf4cacb3ba8cdd3521bc90c4879",
     "ecosystem-claims.json": "0100f7fbc18a3381bb943aaf8151dd5d107f82c02c470e3c586b7d694c6be42e"
   }
 }

package/ecosystem.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 2,
-  "$comment": "Canonical registry of AgentsKit ecosystem products. Stable identity lives here; numeric values live in the generated ecosystem-claims ledger. The deprecated properties array temporarily preserves v1 sibling consumers.",
+  "$comment": "Canonical registry of AgentsKit ecosystem products. Stable identity lives in products[] (seven). Numeric values live in the generated ecosystem-claims ledger. The properties array is the full seven-product v1 projection of products[] (same order) for sibling consumers.",
   "parentBrand": {
     "id": "agentskit",
     "name": "AgentsKit"
@@ -27,7 +27,14 @@
       "navigation": {
         "showInBar": true,
         "order": 0,
-        "next": ["registry", "agentskit-chat", "playbook", "doc-bridge", "code-review", "akos"]
+        "next": [
+          "registry",
+          "agentskit-chat",
+          "playbook",
+          "doc-bridge",
+          "code-review",
+          "akos"
+        ]
       }
     },
     {
@@ -51,7 +58,14 @@
       "navigation": {
         "showInBar": true,
         "order": 1,
-        "next": ["agentskit", "agentskit-chat", "playbook", "doc-bridge", "code-review", "akos"]
+        "next": [
+          "agentskit",
+          "agentskit-chat",
+          "playbook",
+          "doc-bridge",
+          "code-review",
+          "akos"
+        ]
       }
     },
     {
@@ -74,7 +88,14 @@
       "navigation": {
         "showInBar": true,
         "order": 2,
-        "next": ["agentskit", "registry", "playbook", "doc-bridge", "code-review", "akos"]
+        "next": [
+          "agentskit",
+          "registry",
+          "playbook",
+          "doc-bridge",
+          "code-review",
+          "akos"
+        ]
       }
     },
     {
@@ -98,7 +119,14 @@
       "navigation": {
         "showInBar": true,
         "order": 3,
-        "next": ["agentskit", "registry", "agentskit-chat", "doc-bridge", "code-review", "akos"]
+        "next": [
+          "agentskit",
+          "registry",
+          "agentskit-chat",
+          "doc-bridge",
+          "code-review",
+          "akos"
+        ]
       }
     },
     {
@@ -121,7 +149,14 @@
       "navigation": {
         "showInBar": true,
         "order": 4,
-        "next": ["agentskit", "registry", "agentskit-chat", "playbook", "code-review", "akos"]
+        "next": [
+          "agentskit",
+          "registry",
+          "agentskit-chat",
+          "playbook",
+          "code-review",
+          "akos"
+        ]
       }
     },
     {
@@ -142,9 +177,16 @@
         "chat": "none"
       },
       "navigation": {
-        "showInBar": true,
+        "showInBar": false,
         "order": 5,
-        "next": ["agentskit", "registry", "agentskit-chat", "playbook", "doc-bridge", "akos"]
+        "next": [
+          "agentskit",
+          "registry",
+          "agentskit-chat",
+          "playbook",
+          "doc-bridge",
+          "akos"
+        ]
       }
     },
     {
@@ -187,17 +229,29 @@
       "stats": "https://www.agentskit.io/api/stats.json"
     },
     {
-      "id": "akos",
-      "name": "AgentsKit OS",
-      "barLabel": "AKOS",
-      "domain": "akos.agentskit.io",
-      "url": "https://akos.agentskit.io",
-      "repo": "AgentsKit-io/agentskit-os",
-      "tagline": "Run and govern agents in production.",
-      "kind": "product",
-      "accent": "#34D399",
-      "llms": "https://akos.agentskit.io/llms.txt",
-      "stats": "https://akos.agentskit.io/api/stats.json"
+      "id": "registry",
+      "name": "AgentsKit Registry",
+      "barLabel": "Registry",
+      "domain": "registry.agentskit.io",
+      "url": "https://registry.agentskit.io",
+      "repo": "AgentsKit-io/agentskit-registry",
+      "tagline": "Copy ready-made agents and own the source.",
+      "kind": "registry",
+      "accent": "#58A6FF",
+      "llms": "https://registry.agentskit.io/llms.txt",
+      "stats": "https://registry.agentskit.io/r/index.json"
+    },
+    {
+      "id": "agentskit-chat",
+      "name": "AgentsKit Chat",
+      "barLabel": "Chat",
+      "domain": "chat.agentskit.io",
+      "url": "https://chat.agentskit.io",
+      "repo": "AgentsKit-io/agentskit-chat",
+      "tagline": "Define one agent experience and deliver it across interfaces.",
+      "kind": "framework",
+      "accent": "#F59E0B",
+      "llms": "https://chat.agentskit.io/llms.txt"
     },
     {
       "id": "playbook",
@@ -213,17 +267,41 @@
       "stats": "https://playbook.agentskit.io/api/stats.json"
     },
     {
-      "id": "registry",
-      "name": "AgentsKit Registry",
-      "barLabel": "Registry",
-      "domain": "registry.agentskit.io",
-      "url": "https://registry.agentskit.io",
-      "repo": "AgentsKit-io/agentskit-registry",
-      "tagline": "Copy ready-made agents and own the source.",
-      "kind": "registry",
-      "accent": "#58A6FF",
-      "llms": "https://registry.agentskit.io/llms.txt",
-      "stats": "https://registry.agentskit.io/r/index.json"
+      "id": "doc-bridge",
+      "name": "Doc Bridge",
+      "barLabel": "Doc Bridge",
+      "domain": "agentskit-io.github.io",
+      "url": "https://agentskit-io.github.io/doc-bridge/",
+      "repo": "AgentsKit-io/doc-bridge",
+      "tagline": "Turn repository documentation into executable agent handoffs.",
+      "kind": "developer-tool",
+      "accent": "#06B6D4",
+      "llms": "https://agentskit-io.github.io/doc-bridge/llms.txt"
+    },
+    {
+      "id": "code-review",
+      "name": "AgentsKit Code Review",
+      "barLabel": "Code Review",
+      "domain": "github.com",
+      "url": "https://github.com/AgentsKit-io/code-review-cli",
+      "repo": "AgentsKit-io/code-review-cli",
+      "tagline": "Run deep, low-noise review with the model already in use.",
+      "kind": "developer-tool",
+      "accent": "#F97316",
+      "llms": "https://raw.githubusercontent.com/AgentsKit-io/code-review-cli/main/llms.txt"
+    },
+    {
+      "id": "akos",
+      "name": "AgentsKit OS",
+      "barLabel": "AKOS",
+      "domain": "akos.agentskit.io",
+      "url": "https://akos.agentskit.io",
+      "repo": "AgentsKit-io/agentskit-os",
+      "tagline": "Run and govern agents in production.",
+      "kind": "product",
+      "accent": "#34D399",
+      "llms": "https://akos.agentskit.io/llms.txt",
+      "stats": "https://akos.agentskit.io/api/stats.json"
     }
   ],
   "builder": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentskit/doc-bridge",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Human↔agent documentation bridge — deterministic handoffs, doc-site links, memory→docs, optional AgentsKit RAG/chat.",
   "type": "module",
   "bin": {
@@ -95,6 +95,7 @@
     "access": "public"
   },
   "dependencies": {
+    "mermaid": "^11.16.0",
     "zod": "^3.24.2"
   },
   "peerDependencies": {
@@ -126,16 +127,17 @@
     }
   },
   "devDependencies": {
-    "@agentskit/chat": "0.3.0",
+    "@agentskit/chat": "0.4.0",
     "@agentskit/core": "1.12.3",
+    "@agentskit/ink": "0.10.4",
     "@agentskit/react": "0.7.4",
     "@changesets/cli": "^2.31.0",
     "@lhci/cli": "^0.15.1",
     "@playwright/test": "1.61.1",
     "@tailwindcss/postcss": "4.3.2",
     "@types/node": "^22.15.3",
-    "@types/react": "19.0.0",
-    "@types/react-dom": "19.0.0",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
     "@vitest/coverage-v8": "4.1.10",
     "fumadocs-core": "15.6.5",
     "fumadocs-mdx": "11.6.4",
@@ -166,5 +168,5 @@
   "bugs": {
     "url": "https://github.com/AgentsKit-io/doc-bridge/issues"
   },
-  "homepage": "https://agentskit-io.github.io/doc-bridge/"
+  "homepage": "https://doc-bridge.agentskit.io/"
 }

package/src/conformance/ecosystem-contract.ts

@@ -50,7 +50,12 @@ const ManifestSchema = z.object({
   schemaVersion: z.literal(2),
   parentBrand: z.object({ id: NonEmptyStringSchema, name: NonEmptyStringSchema }).passthrough(),
   products: z.array(ProductSchema).min(1),
-  properties: z.array(LegacyPropertySchema).length(4),
+  // Historical four-product shim or full seven-product projection of products[].
+  properties: z
+    .array(LegacyPropertySchema)
+    .refine((value) => value.length === 4 || value.length === 7, {
+      message: 'must project either the legacy four products or the full seven-product catalog',
+    }),
   builder: z.object({ id: NonEmptyStringSchema, name: NonEmptyStringSchema, url: HttpsUrlSchema }).passthrough().optional(),
 }).passthrough()
 
@@ -88,7 +93,18 @@ const ClaimsSchema = z.object({
   products: z.array(ClaimProductSchema),
 }).passthrough()
 
-const LEGACY_PRODUCT_IDS = ['agentskit', 'akos', 'playbook', 'registry'] as const
+/** Historical four-product shim order. */
+const LEGACY_FOUR_PRODUCT_IDS = ['agentskit', 'akos', 'playbook', 'registry'] as const
+/** Full seven-product projection order (matches products[]). */
+const FULL_SEVEN_PRODUCT_IDS = [
+  'agentskit',
+  'registry',
+  'agentskit-chat',
+  'playbook',
+  'doc-bridge',
+  'code-review',
+  'akos',
+] as const
 
 export const parseCanonicalEcosystemContract = (
   manifestInput: unknown,
@@ -120,7 +136,10 @@ export const parseCanonicalEcosystemContract = (
     }
   }
 
-  for (const [index, id] of LEGACY_PRODUCT_IDS.entries()) {
+  const propertyIds =
+    manifest.properties.length === 7 ? FULL_SEVEN_PRODUCT_IDS : LEGACY_FOUR_PRODUCT_IDS
+
+  for (const [index, id] of propertyIds.entries()) {
     const legacy = manifest.properties[index]
     const product = products.get(id)
     if (!legacy || !product || legacy.id !== id || !product.surfaces.home) {

package/src/federation/ecosystem-llms.ts

@@ -0,0 +1,67 @@
+/**
+ * Canonical AgentsKit ecosystem section for llms.txt (and similar machine indexes).
+ *
+ * All products should render this block with the same heading and line shape so
+ * agents can parse the seven-product mesh without per-repo inventiveness.
+ */
+
+export type EcosystemLlmsProduct = {
+  readonly id: string
+  readonly name: string
+  readonly role?: string
+  readonly promise: string
+  readonly maturity?: string
+  readonly surfaces: {
+    readonly home?: string
+    readonly docs?: string
+    readonly llms?: string
+  }
+}
+
+export type FormatEcosystemLlmsBlockOptions = {
+  readonly products: readonly EcosystemLlmsProduct[]
+  /** When set, marks this product with **(current)**. */
+  readonly currentProductId?: string
+  /** Heading line without leading hashes — default `AgentsKit ecosystem`. */
+  readonly heading?: string
+  /**
+   * Prefer docs URL when available; otherwise home.
+   * Default: home, falling back to docs.
+   */
+  readonly prefer?: 'home' | 'docs'
+}
+
+/**
+ * Returns markdown lines for the shared ecosystem block, including a trailing blank line.
+ */
+export function formatEcosystemLlmsBlock(options: FormatEcosystemLlmsBlockOptions): string[] {
+  const heading = options.heading ?? 'AgentsKit ecosystem'
+  const prefer = options.prefer ?? 'home'
+  const lines: string[] = [`## ${heading}`, '']
+
+  for (const product of options.products) {
+    const primary =
+      prefer === 'docs'
+        ? product.surfaces.docs ?? product.surfaces.home
+        : product.surfaces.home ?? product.surfaces.docs
+    if (!primary) continue
+
+    const current = product.id === options.currentProductId ? ' **(current)**' : ''
+    const role = product.role ? ` Role: \`${product.role}\`.` : ''
+    const maturity = product.maturity ? ` Maturity: ${product.maturity}.` : ''
+    const machine = product.surfaces.llms ? ` Machine index: ${product.surfaces.llms}` : ''
+    const promise = product.promise.trim()
+    const promiseSentence = /[.!?]$/.test(promise) ? promise : `${promise}.`
+    lines.push(
+      `- [${product.name}](${primary})${current} — ${promiseSentence}${role}${maturity}${machine}`,
+    )
+  }
+
+  lines.push('')
+  return lines
+}
+
+/** Join the block into a single string ending with a newline. */
+export function formatEcosystemLlmsSection(options: FormatEcosystemLlmsBlockOptions): string {
+  return `${formatEcosystemLlmsBlock(options).join('\n')}\n`
+}

package/src/index.ts

@@ -65,6 +65,12 @@ export {
 } from './validate.js'
 
 export { buildDocBridgeIndex, type BuildIndexOptions, type BuildIndexResult } from './index-builder/build-index.js'
+export {
+  formatEcosystemLlmsBlock,
+  formatEcosystemLlmsSection,
+  type EcosystemLlmsProduct,
+  type FormatEcosystemLlmsBlockOptions,
+} from './federation/ecosystem-llms.js'
 export {
   scanHumanDocRecords,
   scanHumanDocs,

package/src/playbook/doc-bridge-pattern.ts

@@ -111,7 +111,7 @@ 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: https://github.com/AgentsKit-io/doc-bridge/blob/master/docs/skills/doc-bridge.md
-- landing: https://agentskit-io.github.io/doc-bridge/
+- landing: https://doc-bridge.agentskit.io/
 `
 
 export const docBridgePatternPayload = () => ({

package/src/version.ts

@@ -1 +1 @@
-export const PACKAGE_VERSION = '1.2.1'
+export const PACKAGE_VERSION = '1.2.3'