@agentskit/doc-bridge 0.1.0-alpha.1

package/docs/RELEASE.md

@@ -0,0 +1,75 @@
+# Release checklist — `@agentskit/doc-bridge`
+
+## Pre-flight (local)
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm smoke:packaged
+```
+
+Expect: packaged smoke prints `packaged smoke passed` and includes demo `query package example --agent`.
+
+## Version
+
+Alpha versions use Changesets:
+
+```bash
+pnpm changeset          # if new entry needed
+pnpm version-packages   # bumps package.json + CHANGELOG from .changeset/*
+```
+
+Current track: `0.1.0-alpha.x`.
+
+## Publish (npm)
+
+Requires npm auth for the `@agentskit` org (`npm whoami` / `NPM_TOKEN`).
+
+```bash
+pnpm release
+# equivalent:
+# pnpm build && pnpm test && changeset publish
+```
+
+Or one-shot after version bump:
+
+```bash
+npm publish --access public
+```
+
+Confirm:
+
+```bash
+npm view @agentskit/doc-bridge version
+npx ak-docs@0.1.0-alpha.x --version
+```
+
+## GitHub
+
+```bash
+git tag v0.1.0-alpha.x
+git push origin master --tags
+gh release create v0.1.0-alpha.x --title "v0.1.0-alpha.x" --notes-file CHANGELOG.md
+```
+
+## Post-publish smoke (fresh machine)
+
+```bash
+npm i -D @agentskit/doc-bridge@0.1.0-alpha.x
+npx ak-docs init
+npx ak-docs index
+npx ak-docs query package example --agent
+```
+
+## Ecosystem dogfood (after npm is live)
+
+1. **for-agents** — https://www.agentskit.io/docs/for-agents — add `doc-bridge.config` + CI gate in AgentsKit docs monorepo  
+2. **Playbook** — https://playbook.agentskit.io/llms.txt — federation source already used in smoke  
+3. **Registry** — https://registry.agentskit.io/ — ship `llms.txt` + link doc-bridge as onboarding companion  
+
+## Do not claim
+
+- Chat/RAG works without installing Layer 1 peers  
+- Private monorepos as the public proof of scale  

package/docs/chat-and-rag.md

@@ -0,0 +1,48 @@
+# Chat and RAG (Layer 1)
+
+Layer 0 (index, handoff, MCP, gates, memory pipeline) never requires an LLM.
+
+Layer 1 is **opt-in** and dogfoods public AgentsKit packages:
+
+| Peer | Role |
+|------|------|
+| `@agentskit/rag` | Chunk, embed, ingest, search |
+| `@agentskit/memory` | `fileVectorMemory` under `.doc-bridge/vectors` |
+| `@agentskit/adapters` | Chat model + embedder (ollama, openai, …) |
+| `@agentskit/ink` | Terminal chat UI (`ak-docs chat`) |
+| `react` | Required by Ink |
+
+## Trust model
+
+1. **`handoffFirst`** (default): if the question mentions a known package id, attach deterministic AgentHandoff context before the model answers.
+2. RAG retrieves from the indexed agent corpus (and configured sources).
+3. CI gates still decide merge truth — chat never auto-writes docs.
+
+## Commands
+
+```bash
+ak-docs rag ingest
+ak-docs rag search "<query>"
+ak-docs chat
+ak-docs ask "<question>" --chat
+```
+
+Missing peers produce an install hint instead of a silent no-op.
+
+## Providers
+
+| provider | Notes |
+|----------|--------|
+| `ollama` | Best zero-cloud path; uses `ollamaEmbedder` (e.g. `nomic-embed-text`) |
+| `openai` | Chat + `text-embedding-3-small` |
+| `openrouter` | Chat via OpenRouter |
+| `anthropic` | Chat; embeddings currently need `OPENAI_API_KEY` or use ollama |
+
+## Config sketch
+
+See `examples/fumadocs-with-chat.config.ts`.
+
+## When not to use Layer 1
+
+- You only need routing for coding agents → Layer 0 is enough.
+- You already have another RAG stack → keep Layer 0 handoffs; skip peers.

package/docs/examples.md

@@ -0,0 +1,50 @@
+# Examples
+
+Config sketches under [`examples/`](../examples/):
+
+| File | Profile |
+|------|---------|
+| `minimal-plain-markdown.config.ts` | Solo markdown, Layer 0 only |
+| `pnpm-monorepo.config.ts` | Workspace discovery + ownership |
+| `fumadocs-only.config.ts` | Human bridge via Fumadocs |
+| `docusaurus-only.config.ts` | Human bridge via Docusaurus |
+| `fumadocs-with-chat.config.ts` | Standard + intelligence (AgentsKit peers) |
+| `docusaurus-with-memory.config.ts` | Assisted memory promotion path |
+
+## Ownership without monorepo
+
+```json
+{
+  "schemaVersion": 1,
+  "corpus": { "agent": { "root": "docs/for-agents" } },
+  "routing": {
+    "options": {
+      "ownership": {
+        "auth": {
+          "path": "src/auth",
+          "purpose": "Authentication",
+          "checks": ["npm test -- auth"]
+        }
+      }
+    }
+  }
+}
+```
+
+Or frontmatter on an agent doc:
+
+```md
+---
+package: auth
+editRoot: src/auth
+checks: [npm test -- auth]
+---
+```
+
+## Public ecosystem surfaces
+
+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

package/docs/getting-started.md

@@ -0,0 +1,111 @@
+# Getting started
+
+## Install
+
+```bash
+npm i -D @agentskit/doc-bridge
+# or
+pnpm add -D @agentskit/doc-bridge
+```
+
+CLI binary: **`ak-docs`**.
+
+## Two-minute path (no API key)
+
+```bash
+ak-docs init          # config + demo ownership + AGENTS.md snippet
+ak-docs index
+ak-docs query package example --agent
+```
+
+You should see an **AgentHandoff** with `startHere`, `editRoots`, and `checks`.
+
+Useful follow-ups:
+
+```bash
+ak-docs list packages --text
+ak-docs ask "where do I change example?"
+ak-docs gate run
+ak-docs mcp
+```
+
+`init --no-demo` skips the starter module if you want an empty corpus.
+
+## Configuration
+
+Default: `doc-bridge.config.json` (also `.ts` / `.js` / `package.json#docBridge`).
+
+**Required:** `schemaVersion: 1` + `corpus.agent.root`.
+
+Ownership (any one of these):
+
+1. `routing.options.ownership`
+2. Frontmatter on agent docs: `package` + `editRoot`
+3. Monorepo plugin (`pnpm-monorepo` + workspace discovery)
+
+Project root for `--config path/to/doc-bridge.config.json` is the **directory of that file**.
+
+See [config-v1](./spec/config-v1.md) and [examples](./examples.md).
+
+## MCP (Cursor / Claude)
+
+```json
+{
+  "mcpServers": {
+    "ak-docs": {
+      "command": "ak-docs",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Tools: `handoff.resolve`, `doc.search`, `doc.get`, `gate.status`, …
+
+## Human ↔ agent bridge
+
+```bash
+# After configuring corpus.human (fumadocs | docusaurus | plain-markdown)
+ak-docs index
+ak-docs query package <id> --agent   # includes humanDoc when linked
+ak-docs gate run human-guide-links
+ak-docs bootstrap agent-docs         # draft agent docs from human site
+```
+
+## Memory → project docs
+
+```bash
+ak-docs memory ingest
+ak-docs memory classify
+ak-docs memory promote   # draft only — never auto-merges
+```
+
+Sources include `.agent-memory/**` and `.cursor/rules/*.mdc`.
+
+## Optional chat + RAG (AgentsKit)
+
+```bash
+npm i -D @agentskit/rag @agentskit/ink @agentskit/adapters @agentskit/memory react
+```
+
+Enable in config:
+
+```json
+{
+  "intelligence": {
+    "enabled": true,
+    "adapter": { "provider": "ollama", "model": "llama3.2" },
+    "chat": { "enabled": true, "handoffFirst": true, "sources": ["agent", "human"] }
+  }
+}
+```
+
+```bash
+ak-docs index
+ak-docs rag ingest
+ak-docs rag search "authentication boundaries"
+ak-docs chat
+ak-docs ask "how does auth work?" --chat
+```
+
+Details: [chat-and-rag.md](./chat-and-rag.md).

package/docs/mcp.md

@@ -0,0 +1,50 @@
+# MCP setup
+
+## Cursor / Claude Desktop / Codex-style
+
+```json
+{
+  "mcpServers": {
+    "ak-docs": {
+      "command": "npx",
+      "args": ["ak-docs", "mcp"],
+      "cwd": "/absolute/path/to/your/repo"
+    }
+  }
+}
+```
+
+Or with a global/local bin:
+
+```json
+{
+  "mcpServers": {
+    "ak-docs": {
+      "command": "ak-docs",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Run from the repo root (or pass config discovery that resolves to it). Always `ak-docs index` after doc changes (or gate in CI).
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `handoff.resolve` | Package/ownership → AgentHandoff |
+| `doc.search` | Deterministic index search |
+| `doc.get` | Read an indexed agent doc |
+| `gate.status` | Freshness / configured gates |
+| `retriever.query` | Local retriever chunks |
+| `memory.classify` / `memory.promoteDraft` | Memory pipeline |
+
+## Agent guidance (paste into AGENTS.md)
+
+Before editing a package:
+
+1. Call `handoff.resolve` with the package id  
+2. Open `startHere`  
+3. Stay inside `editRoots`  
+4. Run `checks` before claiming done  

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

@@ -0,0 +1,32 @@
+# AgentHandoff v1
+
+Zod schema: `AgentHandoffV1Schema` in `@agentskit/doc-bridge`.
+
+Portable JSON Schema export: `AgentHandoffV1JsonSchema`.
+
+## Shape
+
+```json
+{
+  "type": "agent-handoff",
+  "schemaVersion": 1,
+  "source": ".doc-bridge/index.json",
+  "target": { "type": "package", "id": "auth" },
+  "startHere": "docs/for-agents/modules/auth.md",
+  "readBeforeEditing": ["docs/for-agents/modules/auth.md", "AGENTS.md"],
+  "editRoots": ["src/auth/"],
+  "checks": ["npm test -- auth"],
+  "humanDoc": "/docs/guides/authentication",
+  "notes": ["Authentication module"]
+}
+```
+
+## Legacy compatibility
+
+Legacy `--agent` payloads may omit `schemaVersion`. Use `normalizeAgentHandoff()` or `safeParseAgentHandoff()` to upgrade.
+
+## CLI validation
+
+```bash
+ak-docs validate-handoff ./handoff.json
+```

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

@@ -0,0 +1,71 @@
+# DocBridgeIndex v1
+
+Zod schema: `DocBridgeIndexV1Schema` in `@agentskit/doc-bridge`.
+
+Portable JSON Schema export: `DocBridgeIndexV1JsonSchema`.
+
+## Shape
+
+```json
+{
+  "schemaVersion": 1,
+  "contentHash": "df701207f5f3663d3e0a5d0e257c7ce1b8f2898ef8e1ea1fe91d5289ec74bb3c",
+  "contentHashAlgo": "sha256-normalized-v1",
+  "generatedAt": "2026-07-09T00:00:00.000Z",
+  "project": { "name": "my-project", "root": "." },
+  "knowledge": [
+    {
+      "id": "auth",
+      "type": "agent-doc",
+      "title": "Authentication",
+      "path": "docs/for-agents/auth.md",
+      "description": "Auth ownership and edit workflow."
+    }
+  ],
+  "handoffs": {
+    "auth": {
+      "type": "agent-handoff",
+      "schemaVersion": 1,
+      "source": ".doc-bridge/index.json",
+      "target": { "type": "package", "id": "auth", "path": "packages/auth" },
+      "startHere": "docs/for-agents/auth.md",
+      "readBeforeEditing": ["docs/for-agents/auth.md", "AGENTS.md"],
+      "editRoots": ["packages/auth"],
+      "checks": ["npm test -- auth"],
+      "notes": ["Authentication package"]
+    }
+  },
+  "lookup": {
+    "packages": ["auth"],
+    "ownership": {
+      "auth": {
+        "id": "auth",
+        "path": "packages/auth",
+        "checks": ["npm test -- auth"],
+        "agentDoc": "docs/for-agents/auth.md"
+      }
+    }
+  }
+}
+```
+
+## Content Hash
+
+`contentHashAlgo` is `sha256-normalized-v1`.
+
+The hash input is deterministic JSON containing only:
+
+- `schemaVersion`
+- `knowledge`
+- `handoffs`
+- `lookup`
+
+`generatedAt` is not part of the hash input. When the hash is unchanged, `ak-docs index` preserves the existing `generatedAt` so regenerated `index.json` bytes stay stable.
+
+## Validation
+
+```ts
+import { parseDocBridgeIndex } from '@agentskit/doc-bridge'
+
+const index = parseDocBridgeIndex(JSON.parse(raw))
+```

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

@@ -0,0 +1,32 @@
+# 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.
+
+## Shape
+
+```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"]
+}
+```
+
+## Validation
+
+```ts
+import { parseMemoryCandidate } from '@agentskit/doc-bridge'
+
+const candidate = parseMemoryCandidate(JSON.parse(raw))
+```

package/docs/spec/cli.md

@@ -0,0 +1,137 @@
+# ak-docs CLI
+
+Command-line interface for **`@agentskit/doc-bridge`**. The npm package is scoped; the **only published binary** is `ak-docs`.
+
+## Naming
+
+| What | Name |
+|------|------|
+| npm package | `@agentskit/doc-bridge` |
+| CLI binary | `ak-docs` |
+| Config file | `doc-bridge.config.ts` |
+| GitHub repo | `AgentsKit-io/doc-bridge` |
+
+Install the package, run `ak-docs` — not `doc-bridge` on the shell.
+
+## Why a separate binary
+
+| Choice | Rationale |
+|--------|-----------|
+| **`ak-docs`**, not `agentskit docs` | Dedicated tool; no need for full `@agentskit/cli` |
+| **`ak-docs`**, not an OS subcommand | OS CLIs imply sidecar / runs / pipelines |
+| **`@agentskit/doc-bridge` package** | Part of AgentsKit npm scope; engine + first consumer alignment |
+| **`ak-docs` bin name** | Short, memorable CLI; avoids colliding with package import path |
+
+## Install
+
+```bash
+npm install @agentskit/doc-bridge
+# or
+pnpm add -D @agentskit/doc-bridge
+```
+
+```json
+{
+  "name": "@agentskit/doc-bridge",
+  "bin": {
+    "ak-docs": "./bin/ak-docs.js"
+  }
+}
+```
+
+## Commands (v1)
+
+### Layer 0 — no API key
+
+| Command | Description |
+|---------|-------------|
+| `ak-docs init` | Scaffold `doc-bridge.config.json` + agent INDEX stub |
+| `ak-docs init --scaffold-workspaces` | Also create draft `docs/for-agents/packages/*.md` from discovered pnpm workspaces; never overwrites existing docs |
+| `ak-docs bootstrap agent-docs` | Create draft `docs/for-agents/human/*.md` from configured human-doc adapters; never overwrites existing docs |
+| `ak-docs validate-config` | Zod-validate config file |
+| `ak-docs index` | Build `DocBridgeIndex` + optional `llms.txt` |
+| `ak-docs query <target> [--agent] [--text]` | Resolve package/module/intent/change → handoff JSON or text |
+| `ak-docs search <term> [--agent] [--text]` | Full-text search over index |
+| `ak-docs ask <question>` | Human-readable local consult mode: search + best match + next handoff commands; no LLM |
+| `ak-docs ask` | Interactive local REPL in a TTY; commands: `search <term>`, `read <id-or-path>`, `open <id-or-path>`, `resolve <id>`, `gate [id]`, `exit` |
+| `ak-docs retrieve <query>` | Hybrid local/federated retriever chunks; deterministic local first |
+| `ak-docs init --demo` / default | Scaffold demo ownership (`example`) + `AGENTS.md` snippet so `query --agent` works immediately |
+| `ak-docs init --no-demo` | Config + empty INDEX only |
+| `ak-docs memory ingest` | Normalize local memory files (`.agent-memory/**/*.md`, `.cursor/rules/*.mdc`) into `MemoryCandidate[]` |
+| `ak-docs memory classify` | Deterministically route candidates to agent/human/playbook/discard |
+| `ak-docs memory promote` | Build draft-only promotion body with safety scan; never auto-merges |
+| `ak-docs registry topology` | Print the `doc-curator` topology for AgentsKit/Registry composition |
+| `ak-docs playbook draft` | Build a draft Playbook feedback payload from local memory candidates |
+| `ak-docs list <kind> [--text]` | List packages, apps, intents, … |
+| `ak-docs gate run [index-freshness]` | Check generated index freshness |
+| `ak-docs mcp` | Start MCP server (stdio default) |
+
+### Layer 1 — optional AgentsKit peers (`intelligence.enabled`)
+
+| Command | Description |
+|---------|-------------|
+| `ak-docs rag ingest` | Ingest agent corpus into `@agentskit/rag` + file vector store |
+| `ak-docs rag search <query>` | Semantic search over ingested vectors |
+| `ak-docs chat` | Interactive terminal chat (`@agentskit/ink` + retriever + adapter) |
+| `ak-docs ask <question> --chat` | One-shot grounded answer (`handoffFirst` when possible) |
+
+Peers: `@agentskit/rag`, `@agentskit/ink`, `@agentskit/adapters`, `@agentskit/memory`, `react`.
+
+## Global flags
+
+| Flag | Description |
+|------|-------------|
+| `--config <path>` | Config file (default: auto-discover) |
+| `--json` / `--text` | Output format for non-agent commands (default: json); `--agent` always emits agent JSON |
+| `--chat` | Request planned intelligence-backed ask mode; errors clearly until `intelligence.adapter` and RAG/chat support are configured |
+| `--help` | Command help |
+
+## Examples
+
+```bash
+ak-docs index
+ak-docs query ownership auth --agent
+ak-docs query ownership auth --text
+ak-docs search "sidecar transport" --agent
+ak-docs list packages --text
+ak-docs gate run
+ak-docs mcp
+```
+
+## MCP server config (Cursor)
+
+```json
+{
+  "mcpServers": {
+    "ak-docs": {
+      "command": "ak-docs",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+## Programmatic API
+
+```ts
+import { buildIndex, query, defineConfig } from '@agentskit/doc-bridge'
+
+export default defineConfig({ schemaVersion: 1, corpus: { agent: { root: 'docs' } } })
+```
+
+CLI is a thin wrapper over the same exports.
+
+`MCP_TOOLS` exports the static tool descriptors used by `tools/list`.
+
+## Private Dogfood Alias
+
+```bash
+pnpm docs:internal:query …   # private dogfood wrapper → ak-docs query …
+```
+
+Private repo wrappers stay private. `ak-docs` is the only public binary.
+
+## See also
+
+- [config-v1.md](./config-v1.md)
+- [POSITIONING.md](../POSITIONING.md)