@agentskit/doc-bridge 1.2.1 → 1.2.4

package/docs/MARKETPLACE.md

@@ -37,3 +37,9 @@ If the index is stale, run `ak-docs index`, review the generated diff, and commi
 5. Publish the release, then verify the listing and execute the exact consumer workflow above in a clean fixture repository.
 
 Marketplace publication is a deliberate owner action; the workflow never moves tags and does not publish the GitHub Release before the Marketplace fields are complete.
+
+## Related
+
+- [Gate and CI guide](./guides/gate-ci.md)  
+- [Getting started](./getting-started.md)  
+- [CLI](./spec/cli.md)

package/docs/POSITIONING.md

@@ -54,7 +54,7 @@ Engineering teams with real ownership (monorepos first). Secondary: solo libs, i
 - [AgentsKit for-agents](https://www.agentskit.io/docs/for-agents) — agent-first package corpus
 - [Registry](https://registry.agentskit.io/) — agent discovery / onboarding companion
 - [Playbook llms.txt](https://playbook.agentskit.io/llms.txt) — patterns + federation source
-- [doc-bridge landing](https://agentskit-io.github.io/doc-bridge/) — conversion page + used-by
+- [doc-bridge landing](https://doc-bridge.agentskit.io/) — conversion page + used-by
 - [Doc Bridge Playbook pattern](../playbook/doc-bridge-pattern.md) — `ak-docs playbook pattern`
 
 ## Comparison
@@ -83,3 +83,14 @@ optional:  Playbook / Registry federation
 - Human guide links gate green on fixture adapters
 - Chat/RAG path documented with optional peers
 - Public consumers cited (for-agents, Registry, Playbook)
+
+## Canonical ecosystem role
+
+| Field | Value |
+|-------|--------|
+| **Product id** | `doc-bridge` |
+| **Role** | `understanding` |
+| **Kind** | developer-tool |
+| **Promise** | Human↔agent documentation bridge — deterministic handoffs for any repo |
+
+AgentsKit is the **foundation library** (not a “JavaScript framework” in marketing cards). Chat is the **experience** layer. Doc Bridge stays the **understanding** product.

package/docs/chat-and-rag.md

@@ -20,7 +20,7 @@ Layer 1 is **opt-in** and dogfoods public AgentsKit packages:
 ## Public docs chat: deterministic before backend
 
 The documentation portal uses `@agentskit/chat` (root), `@agentskit/chat/react`,
-and `@agentskit/chat/protocol` directly — the consolidated AgentsKit Chat 0.3.x
+and `@agentskit/chat/protocol` directly — the consolidated AgentsKit Chat 0.4.x
 surface. It does not recreate chat lifecycle or session state.
 
 At build time, `scripts/build-docs-artifacts.mjs` reads the fresh

package/docs/examples.md

@@ -48,8 +48,16 @@ checks: [npm test -- auth]
 
 ## Public ecosystem surfaces
 
-doc-bridge is designed to be consumed by:
+Doc Bridge is designed to be consumed by:
 
 - https://www.agentskit.io/docs/for-agents
 - https://registry.agentskit.io/
 - https://playbook.agentskit.io/llms.txt
+- https://chat.agentskit.io/docs
+- https://doc-bridge.agentskit.io/
+
+## Related
+
+- [Install and run](./guides/install-and-run.md)
+- [Config reference](./spec/config-v1.md)
+- [Getting started](./getting-started.md)

package/docs/for-agents.md

@@ -23,9 +23,17 @@ flowchart LR
 
 ## Machine entry points
 
-- [`llms.txt`](https://agentskit-io.github.io/doc-bridge/llms.txt) — concise discovery and canonical routes
-- [`llms-full.txt`](https://agentskit-io.github.io/doc-bridge/llms-full.txt) — complete source corpus
-- [`deterministic/knowledge.json`](https://agentskit-io.github.io/doc-bridge/deterministic/knowledge.json) — local chat/discovery artifact
-- [`raw/for-agents.md`](https://agentskit-io.github.io/doc-bridge/raw/for-agents.md) — this guide as raw Markdown
+- [`llms.txt`](https://doc-bridge.agentskit.io/llms.txt) — concise discovery and canonical routes
+- [`llms-full.txt`](https://doc-bridge.agentskit.io/llms-full.txt) — complete source corpus
+- [`deterministic/knowledge.json`](https://doc-bridge.agentskit.io/deterministic/knowledge.json) — local chat/discovery artifact
+- [`raw/for-agents.md`](https://doc-bridge.agentskit.io/raw/for-agents.md) — this guide as raw Markdown
+- Site route: [`/for-agents`](https://doc-bridge.agentskit.io/for-agents/) — human-readable agent entry
+
+## Related
+
+- [MCP for agents](./guides/mcp-agents.md)
+- [Index and query](./guides/index-and-query.md)
+- [AgentHandoff schema](./schemas/agent-handoff-v1.md)
+- [Skill text](./skills/doc-bridge.md)
 
 If the task is conversational UI, continue with [AgentsKit Chat](https://chat.agentskit.io). For verification before merge, use [AgentsKit Code Review](https://github.com/AgentsKit-io/code-review-cli). For enterprise orchestration, governance, and audit, continue with [AKOS](https://akos.agentskit.io).

package/docs/getting-started.md

@@ -152,3 +152,13 @@ ak-docs ask "how does auth work?" --chat
 ```
 
 Details: [chat-and-rag.md](./chat-and-rag.md).
+
+## Related
+
+- [Install and run](./guides/install-and-run.md) — guided path with tables  
+- [CLI map](./guides/cli-map.md) — every command with copy-paste examples  
+- [Memory pipeline](./guides/memory-pipeline.md) — digest · classify · promote  
+- [Index and query](./guides/index-and-query.md) · [MCP for agents](./guides/mcp-agents.md)  
+- [Gate and CI](./guides/gate-ci.md) · [Marketplace](./MARKETPLACE.md)  
+- [CLI reference](./spec/cli.md) · [Config](./spec/config-v1.md)  
+- [Positioning](./POSITIONING.md)

package/docs/guides/cli-map.md

@@ -0,0 +1,153 @@
+---
+title: CLI map
+description: Every ak-docs command with copy-paste examples — Layer 0 core and optional Layer 1 intelligence.
+---
+
+# CLI map
+
+Binary: **`ak-docs`** · Package: **`@agentskit/doc-bridge`**
+
+Full flags: [CLI reference](../spec/cli.md)
+
+## Global flags
+
+```bash
+ak-docs --help
+ak-docs --version
+ak-docs --config path/to/doc-bridge.config.json <command>
+ak-docs <command> --agent    # machine JSON (handoffs)
+ak-docs <command> --text     # human text
+ak-docs <command> --json     # JSON where supported
+```
+
+---
+
+## Layer 0 — no API key
+
+### Bootstrap
+
+```bash
+ak-docs init
+ak-docs init --demo
+ak-docs init --no-demo
+ak-docs init --scaffold-workspaces
+ak-docs bootstrap agent-docs
+ak-docs validate-config
+ak-docs validate-handoff path/to/handoff.json
+ak-docs demo --text
+ak-docs demo --fixture monorepo --text
+```
+
+### Index & doctor
+
+```bash
+ak-docs index
+ak-docs index --watch
+ak-docs doctor --text
+ak-docs doctor --badge
+ak-docs doctor --write-badge
+ak-docs gate run
+ak-docs gate run index-freshness
+ak-docs conformance run documentation-standard-v1 --text
+```
+
+### Query & search
+
+```bash
+ak-docs query package auth --agent
+ak-docs query ownership auth --text
+ak-docs query intent onboard --agent
+ak-docs search "abort signal" --agent
+ak-docs list packages --text
+ak-docs list intents --text
+ak-docs ask "where do I change billing?"
+ak-docs retrieve "authentication boundaries"
+```
+
+### MCP
+
+```bash
+ak-docs mcp
+ak-docs mcp install --cursor
+ak-docs mcp install --claude
+```
+
+### Memory pipeline
+
+```bash
+ak-docs memory ingest
+ak-docs memory classify
+ak-docs memory promote
+ak-docs memory promote --pr --dry-run
+ak-docs memory promote --pr
+```
+
+Deep dive: [Memory pipeline](./memory-pipeline.md)
+
+### Ecosystem / playbook
+
+```bash
+ak-docs registry topology
+ak-docs playbook draft
+ak-docs playbook pattern --text
+```
+
+---
+
+## Layer 1 — optional AgentsKit peers
+
+Requires `intelligence.enabled` + peers (`@agentskit/rag`, `@agentskit/ink`, …).
+
+```bash
+ak-docs rag ingest
+ak-docs rag search "how does auth work?"
+ak-docs chat
+ak-docs ask "how does auth work?" --chat
+```
+
+Walkthrough: [Chat and RAG](../chat-and-rag.md) · [Ollama demo](../ollama-demo.md)
+
+---
+
+## Suggested sequences
+
+### New repo in 2 minutes
+
+```bash
+pnpm add -D @agentskit/doc-bridge
+ak-docs init
+ak-docs index
+ak-docs query package example --agent
+ak-docs doctor --text
+```
+
+### Agent about to edit
+
+```bash
+ak-docs query ownership <id> --agent
+# read startHere → edit editRoots → run checks
+```
+
+### Turn session notes into docs
+
+```bash
+ak-docs memory ingest
+ak-docs memory classify
+ak-docs memory promote --pr --dry-run
+```
+
+### PR gate
+
+```bash
+ak-docs index
+ak-docs gate run
+# commit generated index if your repo treats it as source-of-truth
+```
+
+## Related
+
+- [Install and run](./install-and-run.md)  
+- [Index and query](./index-and-query.md)  
+- [MCP for agents](./mcp-agents.md)  
+- [Memory pipeline](./memory-pipeline.md)  
+- [CLI reference](../spec/cli.md)  

package/docs/guides/gate-ci.md

@@ -0,0 +1,64 @@
+---
+title: Gate and CI
+description: Fail stale documentation context in pull requests with Doc Bridge gates and the Marketplace Action.
+---
+
+# Gate and CI
+
+Gates keep incomplete or stale documentation context from reaching coding agents.
+
+## Local gate
+
+```bash
+ak-docs index
+ak-docs gate run
+ak-docs doctor --text
+ak-docs doctor --badge
+```
+
+Typical failures:
+
+| Symptom | Fix |
+| --- | --- |
+| Stale index | `ak-docs index`, review + commit generated files |
+| Missing ownership | Add config ownership, frontmatter, or monorepo plugin |
+| Documentation Standard gaps | Follow doctor remediations / evidence paths |
+
+## Pull request workflow
+
+```yaml
+name: Documentation gate
+on: [pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: AgentsKit-io/doc-bridge@v1.2.1
+        with:
+          config-path: doc-bridge.config.json
+```
+
+The composite Action verifies the **committed** index and configured gates — it does **not** silently rebuild and hide drift.
+
+If the Action fails:
+
+1. Run `ak-docs index` locally  
+2. Review the diff under `.doc-bridge/` / `llms.txt`  
+3. Commit intentional updates  
+4. Re-run the PR check  
+
+## What to commit
+
+Commit generated index artifacts your repo treats as source-of-truth (common: `.doc-bridge/index.json`, root `llms.txt`). Keep CI fail-closed when those drift from the docs corpus.
+
+## Related
+
+- [Marketplace details](../MARKETPLACE.md)  
+- [Install and run](./install-and-run.md)  
+- [Documentation Standard](../spec/documentation-standard-v1.md)  
+- [Doctor / CLI](../spec/cli.md)  

package/docs/guides/index-and-query.md

@@ -0,0 +1,75 @@
+---
+title: Index and query
+description: Build a deterministic index and resolve ownership handoffs without calling a model.
+---
+
+# Index and query
+
+Layer 0 is **offline and deterministic**. Indexing scans your corpus; querying never re-scans and never calls a model.
+
+## Index
+
+```bash
+ak-docs index
+ak-docs index --watch   # rebuild on doc changes
+```
+
+Outputs (defaults):
+
+| Path | Role |
+| --- | --- |
+| `.doc-bridge/index.json` | Machine index (DocBridgeIndex v1) |
+| `llms.txt` | Concise agent discovery surface |
+| `.doc-bridge/capabilities.json` | Capability map for MCP / tools |
+
+After ownership or corpus changes, **always re-index** (or gate in CI will fail).
+
+## Query ownership
+
+```bash
+ak-docs query package <id> --agent
+ak-docs query ownership <id> --agent
+ak-docs query package <id> --text      # human-readable
+```
+
+`--agent` returns validated **AgentHandoff** JSON:
+
+```json
+{
+  "startHere": "docs/for-agents/packages/auth.md",
+  "editRoots": ["packages/auth"],
+  "checks": ["pnpm test --filter auth"],
+  "humanDoc": "docs/guides/auth.md"
+}
+```
+
+Use this **before** an agent edits code. The model should not invent ownership from the full monorepo dump.
+
+## Search and ask (local)
+
+```bash
+ak-docs list packages --text
+ak-docs ask "where is authentication?"
+```
+
+`ask` stays on the deterministic plane when a known match exists. Only unresolved questions should escalate to optional backend/RAG (see [Chat and RAG](../chat-and-rag.md)).
+
+## Agent workflow
+
+```text
+resolve ownership  →  read startHere  →  edit only editRoots  →  run checks
+```
+
+1. `ak-docs query ownership <module> --agent`  
+2. Open `startHere` / `readBeforeEditing`  
+3. Edit paths under `editRoots` only  
+4. Run every command in `checks`  
+5. Promote durable learnings via memory pipeline when ready  
+
+## Related
+
+- [Install and run](./install-and-run.md)  
+- [For agents](../for-agents.md)  
+- [MCP](./mcp-agents.md)  
+- [AgentHandoff schema](../schemas/agent-handoff-v1.md)  
+- [CLI reference](../spec/cli.md)  

package/docs/guides/install-and-run.md

@@ -0,0 +1,84 @@
+---
+title: Install and run
+description: Install Doc Bridge, run the demo, and index your repository in minutes.
+---
+
+# Install and run
+
+Get a deterministic AgentHandoff from your own docs — no API key required for Layer 0.
+
+## Install
+
+```bash
+pnpm add -D @agentskit/doc-bridge
+# or
+npm i -D @agentskit/doc-bridge
+```
+
+CLI binary: **`ak-docs`**.
+
+## Prove it in 60 seconds (no project setup)
+
+```bash
+npx ak-docs demo --text
+npx ak-docs demo --fixture monorepo --text
+```
+
+You should see handoffs, a gate red→green path, and an MCP install snippet.
+
+## Two-minute path on your repo
+
+```bash
+cd your-repo
+ak-docs init                 # config + optional demo ownership + AGENTS.md tip
+ak-docs index                # build .doc-bridge/index.json
+ak-docs query package example --agent
+ak-docs doctor --text
+ak-docs gate run
+```
+
+Expected handoff fields:
+
+| Field | Meaning |
+| --- | --- |
+| `startHere` | What the agent reads first |
+| `editRoots` | Where edits are allowed |
+| `checks` | Commands that prove the change |
+| `humanDoc` | Human guide for the same ownership |
+
+## Minimal config
+
+`doc-bridge.config.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "corpus": {
+    "agent": { "root": "docs/for-agents" }
+  }
+}
+```
+
+**Required:** `schemaVersion: 1` and `corpus.agent.root`.
+
+Ownership comes from (first match wins):
+
+1. `routing.options.ownership` in config  
+2. Frontmatter on agent docs (`package`, `editRoot`, `checks`)  
+3. Monorepo plugin discovery (`pnpm-monorepo`)
+
+## Dev loop
+
+```bash
+ak-docs index --watch
+ak-docs list packages --text
+ak-docs ask "where do I change auth?"
+```
+
+## Related
+
+- [Index and query](./index-and-query.md) — resolve ownership deterministically  
+- [Gate and CI](./gate-ci.md) — fail stale context in PRs  
+- [MCP for agents](./mcp-agents.md) — wire Cursor / Claude / Codex  
+- [Config reference](../spec/config-v1.md)  
+- [Examples](../examples.md)  

package/docs/guides/mcp-agents.md

@@ -0,0 +1,63 @@
+---
+title: MCP for agents
+description: Expose Doc Bridge handoffs to Cursor, Claude Desktop, and other MCP clients.
+---
+
+# MCP for agents
+
+Doc Bridge MCP tools return the **same deterministic handoffs** as the CLI — ownership, start files, edit roots, and checks.
+
+## One-command install
+
+```bash
+ak-docs mcp install --cursor    # writes .cursor/mcp.json
+ak-docs mcp install --claude    # merges Claude Desktop config (macOS)
+```
+
+Then index your repo:
+
+```bash
+ak-docs index
+```
+
+Optional skill text: [skills/doc-bridge.md](../skills/doc-bridge.md)
+
+## Manual config
+
+```json
+{
+  "mcpServers": {
+    "ak-docs": {
+      "command": "npx",
+      "args": ["ak-docs", "mcp"],
+      "cwd": "/absolute/path/to/your/repo"
+    }
+  }
+}
+```
+
+Run MCP from the **repository root** (or ensure config discovery resolves there).
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `handoff.resolve` | Package / ownership → AgentHandoff |
+| Search / list tools | Discover modules and docs without dumping the tree |
+
+Prefer `handoff.resolve` **before** any multi-file edit.
+
+## Agent loop
+
+1. Resolve ownership via MCP or `ak-docs query … --agent`  
+2. Read `startHere`  
+3. Edit only `editRoots`  
+4. Run `checks`  
+5. Re-index when docs change  
+
+## Related
+
+- [For agents](../for-agents.md)  
+- [Index and query](./index-and-query.md)  
+- [MCP deep dive](../mcp.md)  
+- [Chat and RAG](../chat-and-rag.md) — optional intelligence plane  

package/docs/guides/memory-pipeline.md

@@ -0,0 +1,105 @@
+---
+title: Memory pipeline
+description: Digest agent notes, classify them, and promote reviewable documentation drafts — never silent auto-merge.
+---
+
+# Memory pipeline
+
+Agent sessions leave durable learnings in local files. Doc Bridge **ingests**, **classifies**, and **promotes** them into draft documentation that humans review. Nothing lands in the corpus without a PR.
+
+## Sources (Layer 0)
+
+| Source | Path pattern |
+| --- | --- |
+| Agent memory notes | `.agent-memory/**/*.md` |
+| Cursor rules | `.cursor/rules/*.mdc` |
+
+No API key. Classification is deterministic.
+
+## End-to-end commands
+
+```bash
+# 1) Normalize raw notes → MemoryCandidate[]
+ak-docs memory ingest
+
+# 2) Route each candidate: agent | human | playbook | discard
+ak-docs memory classify
+
+# 3) Build a safe draft body (safety scan; never auto-merges)
+ak-docs memory promote
+
+# 4) Optional: open a GitHub draft PR via `gh`
+ak-docs memory promote --pr --dry-run
+ak-docs memory promote --pr
+```
+
+## What a candidate looks like
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "auth-abort-signal",
+  "source": "agent-memory",
+  "rawPath": ".agent-memory/auth.md",
+  "fact": "Auth handlers must forward AbortSignal.",
+  "why": "Run cancellation must stop network work.",
+  "howToApply": "Use AbortSignal.any([caller, AbortSignal.timeout(ms)]).",
+  "suggestedType": "project",
+  "confidence": 0.8,
+  "references": ["docs/for-agents/auth.md"]
+}
+```
+
+Schema: [MemoryCandidate v1](../schemas/memory-candidate-v1.md)
+
+## Digest mental model
+
+```text
+.agent-memory / .cursor/rules
+        │
+        ▼
+  memory ingest     →  normalized candidates
+        │
+        ▼
+  memory classify   →  agent | human | playbook | discard
+        │
+        ▼
+  memory promote    →  draft markdown (+ optional draft PR)
+        │
+        ▼
+  Human review / merge   (never silent)
+```
+
+## Safety guarantees
+
+| Guarantee | Behavior |
+| --- | --- |
+| Draft-only | Promotion never writes the canonical corpus directly |
+| Safety scan | Risky content is flagged before draft output |
+| HITL | `--pr` opens a **draft** GitHub PR via `gh` |
+| Deterministic | Same inputs → same classify/promote routing |
+
+## MCP tools
+
+When MCP is running (`ak-docs mcp`):
+
+| Tool | Role |
+| --- | --- |
+| `memory.classify` | Classify candidates |
+| `memory.promoteDraft` | Produce a draft promotion body |
+
+See [MCP for agents](./mcp-agents.md).
+
+## Playbook feedback
+
+```bash
+ak-docs playbook draft      # payload from classified memory
+ak-docs playbook pattern    # published Doc Bridge pattern (OKF)
+```
+
+## Related
+
+- [CLI map](./cli-map.md) — every command  
+- [MemoryCandidate schema](../schemas/memory-candidate-v1.md)  
+- [Chat and RAG](../chat-and-rag.md) — optional Layer 1 after handoffs  
+- [Getting started](../getting-started.md)  

package/docs/guides/meta.json

@@ -0,0 +1,11 @@
+{
+  "title": "Guides",
+  "pages": [
+    "install-and-run",
+    "index-and-query",
+    "gate-ci",
+    "mcp-agents",
+    "memory-pipeline",
+    "cli-map"
+  ]
+}