@agentskit/doc-bridge 0.1.0-alpha.3 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 1.0.0
+
+**Stable** — doctor, CI gate, MCP install, and agent skill are boring-reliable. Tier C polish ships.
+
+### Features
+- **Landing** — `docs/landing/index.html` deployed to GitHub Pages (`https://agentskit-io.github.io/doc-bridge/`)
+- **Playbook pattern** — published `docs/playbook/doc-bridge-pattern.md` + `ak-docs playbook pattern [--text]`
+- **Used by** — public AgentsKit surfaces cited on landing (for-agents, Registry, Playbook)
+
+### Stable criteria met
+- 60s demo path (`ak-docs demo`)
+- Doctor coverage score + badges
+- GitHub Action `doc-bridge-gate` + repo dogfood CI
+- Cursor skill + `mcp install --cursor`
+- Memory promote → draft PR, index `--watch`, Ollama smoke (optional)
+
+### Breaking changes from alpha
+- None intended for Layer 0 config/handoff schemas (still `schemaVersion: 1`)
+- Pin `@v1.0.0` for GitHub Action instead of alpha tags
+
+## 0.1.0-alpha.5
+
+Tier B — power-user workflows and production pipeline polish.
+
+### Features
+- **`ak-docs memory promote --pr`** — draft file + `gh pr create --draft` (with `--dry-run`, `--force`)
+- **`ak-docs index --watch`** — debounced rebuild on agent/human doc changes
+- **`ak-docs doctor --badge`** / **`--write-badge`** — shields.io markdown + `.doc-bridge/coverage-badge.json`
+- **Ollama demo** — `examples/ollama-chat.config.ts`, `docs/ollama-demo.md`, `pnpm smoke:ollama`
+- **Index pipeline recipes** — pre-commit, Turborepo, CI (`docs/recipes/index-pipeline.md`)
+- **`pnpm coverage:badge`** — CI-friendly badge updater script
+
+## 0.1.0-alpha.4
+
+Activation and agent-adoption polish — from "works" to "wow in 60s".
+
+### Features
+- **`ak-docs demo`** — bundled example/monorepo fixtures; before/after handoff, gate red→green, MCP snippet (no local config)
+- **`ak-docs doctor`** — coverage score 0–100, missing agentDoc/humanDoc, gate status, next actions
+- **`ak-docs mcp install --cursor | --claude`** — writes MCP server config
+- **Handoff `bridge`** — `linked` / `missing` / `external` humanDoc status with bootstrap action
+- **`ak-docs ask`** — handoff preview (start, edit, checks, bridge) when ownership matches
+- **GitHub Action** — `action.yml` (`doc-bridge-gate`) for PR gates + doctor annotation
+- **Agent skill** — `docs/skills/doc-bridge.md` for Cursor/Claude one-shot routing rules
+- **Demo fixtures** — `examples/demo-example`, `examples/demo-monorepo` (auth + billing)
+
 ## 0.1.0-alpha.3
 
 Dogfood round-2 fixes (search ranking, full-text body, peers, federation soft-fail).

package/README.md

@@ -1,12 +1,45 @@
 # doc-bridge
 
-**npm:** [`@agentskit/doc-bridge`](https://www.npmjs.com/package/@agentskit/doc-bridge) · **CLI:** `ak-docs`
+**npm:** [`@agentskit/doc-bridge`](https://www.npmjs.com/package/@agentskit/doc-bridge) · **CLI:** `ak-docs` · **Landing:** [agentskit-io.github.io/doc-bridge](https://agentskit-io.github.io/doc-bridge/)
 
-**Human↔agent documentation bridge** for any project — not a wiki, not a hosted RAG chat.
+**AgentHandoff for your monorepo** — deterministic routing so coding agents edit the right package, run the right checks, and stay linked to human docs.
 
-doc-bridge helps coding agents **find the right file, edit the right roots, run the right checks**, keeps **agent docs linked to human docs**, and turns **agent memory into project documentation** (with human approval). The core is deterministic and works **without any LLM or API key**.
+Not a wiki. Not a hosted RAG chat. Layer 0 works **without any LLM or API key**.
 
-Optional intelligence (RAG + terminal chat) uses public AgentsKit packages — install only when you want them.
+## 60-second wow path
+
+```bash
+npm i -D @agentskit/doc-bridge
+npx ak-docs demo --text
+```
+
+No config, no docs to read first. Output shows before/after, a real handoff, gate red→green, and the MCP snippet:
+
+```
+After (handoff.resolve / query --agent)
+  ✓ target:  auth (packages/auth)
+  ✓ start:   docs/for-agents/packages/auth.md
+  ✓ edit:    packages/auth
+  ✓ checks:  pnpm --filter @demo/auth test · pnpm --filter @demo/auth lint
+  ✓ human guide: /docs/guides/auth
+
+Gate: red → green
+```
+
+Monorepo fixture with auth + billing:
+
+```bash
+npx ak-docs demo --fixture monorepo --text
+```
+
+Full setup in your repo:
+
+```bash
+npx ak-docs init
+npx ak-docs index
+npx ak-docs query package example --agent
+ak-docs mcp install --cursor   # wires MCP into .cursor/mcp.json
+```
 
 ## Why this exists
 
@@ -21,41 +54,90 @@ doc-bridge ships **AgentHandoff** JSON:
 ```json
 {
   "type": "agent-handoff",
-  "startHere": "docs/for-agents/packages/example.md",
-  "editRoots": ["src"],
-  "checks": ["npm test"],
-  "humanDoc": "/docs/guides/example"
+  "startHere": "docs/for-agents/packages/auth.md",
+  "editRoots": ["packages/auth"],
+  "checks": ["pnpm --filter @demo/auth test"],
+  "humanDoc": "/docs/guides/auth",
+  "bridge": { "humanDoc": "linked" }
 }
 ```
 
-## Four loops
+When a human guide is missing, handoffs surface it as a feature:
 
-| Loop | What you get |
-|------|----------------|
-| **Act** | CLI + MCP handoffs (`query`, `handoff.resolve`) |
-| **Bridge** | Fumadocs / Docusaurus / plain-markdown ↔ agent corpus + gates |
-| **Learn** | `memory ingest → classify → promote` drafts (HITL) |
-| **Explain** | Optional `@agentskit/rag` + `@agentskit/ink` chat (`handoffFirst`) |
+```json
+{
+  "bridge": {
+    "humanDoc": "missing",
+    "action": "ak-docs bootstrap agent-docs"
+  },
+  "notes": ["Human guide missing for billing. Run: ak-docs bootstrap agent-docs"]
+}
+```
 
-## Quick start (< 2 minutes, no key)
+## Four loops (with real commands)
+
+| Loop | Command | What you see |
+|------|---------|--------------|
+| **Act** | `ak-docs query package auth --agent` | `editRoots`, `checks`, `startHere` |
+| **Bridge** | `ak-docs bootstrap agent-docs` | Draft agent docs from human site; `bridge.humanDoc` in handoff |
+| **Learn** | `ak-docs memory classify` → `promote` | HITL draft for agent corpus |
+| **Explain** | `ak-docs ask "auth is broken in staging"` | Ownership match + handoff preview + next commands |
 
 ```bash
-npm i -D @agentskit/doc-bridge
-npx ak-docs init
-npx ak-docs index
-npx ak-docs query package example --agent
+ak-docs ask "who owns schemas"
+# Best match: ownership os-core
+# Handoff preview
+#   start:  docs/for-agents/packages/os-core.md
+#   edit:   packages/os-core
+#   checks: pnpm --filter os-core lint · pnpm --filter os-core test
+```
+
+## Coverage your team checks daily
+
+```bash
+ak-docs doctor --text
+ak-docs doctor --badge          # shields.io markdown for README
+ak-docs index --watch           # keep index fresh while editing docs
+```
+
 ```
+Score: 82/100 (B)
+  Agent docs:      8/10 (80% handoff-ready)
+  Human guides:    6/10 (60% bridged)
+  Gates:           3/3 passing
+
+Next actions
+  → ak-docs bootstrap agent-docs
+  → ak-docs query package billing --agent
+```
+
+## Agent uses it alone
+
+1. **MCP auto-wire:** `ak-docs mcp install --cursor`
+2. **Skill/rule:** paste [docs/skills/doc-bridge.md](docs/skills/doc-bridge.md) into Cursor rules — agents call `handoff.resolve` before editing `packages/*`
+3. **Handoff is the next step:** `startHere`, `checks`, and `bridge` are in the JSON/MCP response
+
+## CI as first-class citizen
 
-`init` scaffolds config, a demo ownership target, and an `AGENTS.md` snippet.
+Reuse the bundled GitHub Action on every PR:
+
+```yaml
+- uses: AgentsKit-io/doc-bridge@v1.0.0
+  with:
+    config-path: doc-bridge.config.json
+```
+
+![handoff coverage](https://img.shields.io/badge/handoff_coverage-100%25-2ea44f?style=flat-square) ![human bridge](https://img.shields.io/badge/human_bridge-0%25-cb2431?style=flat-square)
+
+Run `ak-docs doctor --badge` locally to refresh — or `pnpm coverage:badge` in CI.
+
+Or locally:
 
 ```bash
-npx ak-docs list packages --text
-npx ak-docs ask "where do I change example?"
-npx ak-docs gate run
-npx ak-docs mcp
+ak-docs index && ak-docs gate run
 ```
 
-Full guide: **[docs/getting-started.md](docs/getting-started.md)**.
+Gate fails with `Index is stale. Run: ak-docs index` — same check in CI annotations.
 
 ## Surfaces
 
@@ -63,50 +145,38 @@ Full guide: **[docs/getting-started.md](docs/getting-started.md)**.
 
 | Surface | Purpose |
 |---------|---------|
+| **Demo** | `ak-docs demo` — bundled fixture, no setup |
+| **Doctor** | Coverage score, missing humanDoc/agent doc, next actions |
 | **Index** | `DocBridgeIndex` + `contentHash` + `llms.txt` + capabilities |
 | **CLI** | `query` / `search` / `list` / `ask` / `gate` / `memory` / `bootstrap` |
-| **MCP** | `handoff.resolve`, `doc.search`, `doc.get`, … |
+| **MCP** | `handoff.resolve`, `doc.search`, `doc.get`, `gate.status`, … |
 | **Gates** | Freshness, human-link validation, optional OKF style |
 | **Plugins** | `pnpm-monorepo`, `fumadocs`, `docusaurus`, `plain-markdown` |
 
-Ownership can come from **config**, **frontmatter** (`package` + `editRoot`), or **workspace discovery**.
-
 ### Layer 1 — optional AgentsKit peers
 
 ```bash
 npm i -D @agentskit/rag @agentskit/ink @agentskit/adapters @agentskit/memory react
-```
-
-```bash
-ak-docs rag ingest
-ak-docs chat
-ak-docs ask "how does auth work?" --chat
+ak-docs rag ingest && ak-docs chat
 ```
 
 See **[docs/chat-and-rag.md](docs/chat-and-rag.md)**.
 
-## Architecture
-
-```
-Your repo
-├── docs/for-agents/     agent corpus
-├── docs/ or content/    human site (plugin)
-├── AGENTS.md
-└── doc-bridge.config.*
-
-Layer 0 — Index · CLI · MCP · Gates · Memory pipeline
-Layer 1 — @agentskit/rag · adapters · ink chat   (opt-in)
-```
-
-**Trust model:** Layer 0 is merge-blocking truth. Layer 1 explains and drafts; humans and gates decide.
-
 ## Who uses it (public)
 
+[![npm](https://img.shields.io/npm/v/@agentskit/doc-bridge?style=flat-square)](https://www.npmjs.com/package/@agentskit/doc-bridge)
+[![CI](https://img.shields.io/github/actions/workflow/status/AgentsKit-io/doc-bridge/ci.yml?branch=master&style=flat-square)](https://github.com/AgentsKit-io/doc-bridge/actions)
+
 Designed for and dogfooded on open AgentsKit surfaces:
 
-- [for-agents docs](https://www.agentskit.io/docs/for-agents)
-- [Registry](https://registry.agentskit.io/)
-- [Playbook `llms.txt`](https://playbook.agentskit.io/llms.txt)
+| Surface | Link |
+|---------|------|
+| **for-agents** | [agentskit.io/docs/for-agents](https://www.agentskit.io/docs/for-agents) |
+| **Registry** | [registry.agentskit.io](https://registry.agentskit.io/) |
+| **Playbook** | [playbook.agentskit.io](https://playbook.agentskit.io/llms.txt) |
+| **This repo** | CI green · `ak-docs gate run` on every PR |
+
+**Playbook pattern:** [`docs/playbook/doc-bridge-pattern.md`](docs/playbook/doc-bridge-pattern.md) — export with `ak-docs playbook pattern --text`
 
 ## Configuration examples
 
@@ -114,19 +184,31 @@ Designed for and dogfooded on open AgentsKit surfaces:
 |---------|---------|
 | Solo markdown | [`examples/minimal-plain-markdown.config.ts`](examples/minimal-plain-markdown.config.ts) |
 | pnpm monorepo | [`examples/pnpm-monorepo.config.ts`](examples/pnpm-monorepo.config.ts) |
+| Demo monorepo | [`examples/demo-monorepo/`](examples/demo-monorepo/) |
 | Fumadocs + chat | [`examples/fumadocs-with-chat.config.ts`](examples/fumadocs-with-chat.config.ts) |
-| Docusaurus + memory | [`examples/docusaurus-with-memory.config.ts`](examples/docusaurus-with-memory.config.ts) |
 
-Contract: [`docs/spec/config-v1.md`](docs/spec/config-v1.md) · CLI: [`docs/spec/cli.md`](docs/spec/cli.md) · MCP: [`docs/mcp.md`](docs/mcp.md)
+Contract: [`docs/spec/config-v1.md`](docs/spec/config-v1.md) · CLI: [`docs/spec/cli.md`](docs/spec/cli.md) · MCP: [`docs/mcp.md`](docs/mcp.md) · Skill: [`docs/skills/doc-bridge.md`](docs/skills/doc-bridge.md) · Pattern: [`docs/playbook/doc-bridge-pattern.md`](docs/playbook/doc-bridge-pattern.md) · Recipes: [`docs/recipes/index-pipeline.md`](docs/recipes/index-pipeline.md)
+
+## Learn loop — memory → draft PR
+
+```bash
+ak-docs memory ingest
+ak-docs memory classify
+ak-docs memory promote --pr --dry-run   # preview gh commands
+ak-docs memory promote --pr              # opens draft PR via gh
+```
 
 ## Status
 
-**v0.1.0-alpha.3** — Dogfood polish (pnpm-aware checks, corpus ownership inference, playbook gate preset, git prepare build). Layer 1 RAG/chat via optional peers.
+**v1.0.0 stable** — doctor + CI + skill boring-reliable. Landing, Playbook pattern, full Tier A/B/C shipped.
 
 ```bash
 pnpm install && pnpm build && pnpm test
+pnpm smoke:ollama    # optional — skips if Ollama/peers unavailable
 ```
 
+**Landing:** https://agentskit-io.github.io/doc-bridge/
+
 ## Contributing
 
 - [CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](SECURITY.md) · [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) · [CHANGELOG.md](CHANGELOG.md)
@@ -134,4 +216,4 @@ pnpm install && pnpm build && pnpm test
 
 ## License
 
-MIT
+MIT

package/action.yml

@@ -0,0 +1,78 @@
+name: doc-bridge-gate
+description: Run doc-bridge index freshness and configured gates on pull requests
+branding:
+  icon: book
+  color: blue
+
+inputs:
+  config-path:
+    description: Path to doc-bridge.config.json (default discovers from repo root)
+    required: false
+    default: ''
+  gate:
+    description: Optional single gate id (default runs all configured gates)
+    required: false
+    default: ''
+  node-version:
+    description: Node.js version for ak-docs
+    required: false
+    default: '22'
+  package-version:
+    description: npm package version pin (e.g. 0.1.0-alpha.3)
+    required: false
+    default: ''
+
+runs:
+  using: composite
+  steps:
+    - name: Setup Node
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ inputs.node-version }}
+
+    - name: Install ak-docs
+      shell: bash
+      run: |
+        VERSION="${{ inputs.package-version }}"
+        if [ -n "$VERSION" ]; then
+          npm install -g "@agentskit/doc-bridge@${VERSION}"
+        else
+          npm install -g @agentskit/doc-bridge
+        fi
+
+    - name: Build index
+      shell: bash
+      run: |
+        if [ -n "${{ inputs.config-path }}" ]; then
+          ak-docs index --config "${{ inputs.config-path }}"
+        else
+          ak-docs index
+        fi
+
+    - name: Run gates
+      shell: bash
+      run: |
+        if [ -n "${{ inputs.gate }}" ] && [ -n "${{ inputs.config-path }}" ]; then
+          ak-docs gate run "${{ inputs.gate }}" --config "${{ inputs.config-path }}"
+        elif [ -n "${{ inputs.gate }}" ]; then
+          ak-docs gate run "${{ inputs.gate }}"
+        elif [ -n "${{ inputs.config-path }}" ]; then
+          ak-docs gate run --config "${{ inputs.config-path }}"
+        else
+          ak-docs gate run
+        fi
+
+    - name: Doctor coverage (annotation)
+      shell: bash
+      continue-on-error: true
+      run: |
+        if [ -n "${{ inputs.config-path }}" ]; then
+          REPORT="$(ak-docs doctor --text --config "${{ inputs.config-path }}" 2>&1 || true)"
+        else
+          REPORT="$(ak-docs doctor --text 2>&1 || true)"
+        fi
+        echo "$REPORT"
+        SCORE="$(echo "$REPORT" | sed -n 's/^Score: \([0-9]*\)\/.*/\1/p' | head -1)"
+        if [ -n "$SCORE" ]; then
+          echo "::notice title=doc-bridge coverage::Score ${SCORE}/100 — run ak-docs doctor locally for next actions"
+        fi