@agentskit/doc-bridge 0.1.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 0.1.0-alpha.1
+
+Initial alpha — human↔agent documentation bridge.
+
+### Layer 0 (no API key)
+
+- Versioned Zod schemas for AgentHandoff, AgentSearch, DocBridgeIndex, config, and MemoryCandidate.
+- `ak-docs init` (demo ownership by default, `--no-demo` available), `index`, `query`, `search`, `list`, `gate run`, `mcp`, `ask`.
+- Ownership handoffs from **config**, **agent-doc frontmatter** (`package` + `editRoot`), or monorepo discovery.
+- `--config` resolves project root from the config file directory.
+- MCP: `handoff.resolve`, `doc.search`, `doc.get`, `gate.status`, memory + retriever tools.
+- Human adapters: plain markdown, Fumadocs, Docusaurus; gates for freshness, human links, OKF style.
+- Memory pipeline: ingest → classify → promote drafts (HITL).
+- Progressive CLI help (Core / Intelligence / Advanced).
+
+### Layer 1 (optional AgentsKit peers)
+
+- `ak-docs rag ingest|search` via `@agentskit/rag` + `@agentskit/memory`.
+- `ak-docs chat` and `ask --chat` via `@agentskit/ink` + adapters (`handoffFirst`).
+- Optional peerDependencies — Layer 0 install stays lean.
+
+### Docs / packaging
+
+- Positioning as human↔agent bridge; public consumers: for-agents, Registry, Playbook.
+- Getting started, MCP, examples, chat-and-rag guides.
+- Fixed package `main`/`types` exports for publish.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,7 @@
+# Code of Conduct
+
+Be respectful, direct, and constructive.
+
+We do not accept harassment, threats, discriminatory language, or bad-faith disruption in issues, pull requests, discussions, or release channels.
+
+Maintainers may hide, edit, or remove comments and may restrict participation when needed to keep the project usable for contributors.

package/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing
+
+Thanks for helping improve `@agentskit/doc-bridge`.
+
+## Setup
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+## Development rules
+
+- Keep Layer 0 deterministic: no LLM/API key required for `init`, `index`, `query`, `list`, gates, or MCP handoff tools.
+- Do not add private-repo assumptions to public docs, examples, defaults, or tests.
+- Prefer existing helpers and Node APIs before adding dependencies.
+- Add or update the smallest test that would fail if the behavior regresses.
+- Public contract changes must update the relevant docs under `docs/spec/` or `docs/schemas/`.
+
+## Releases
+
+Use Changesets for versioned changes:
+
+```bash
+pnpm changeset
+pnpm version-packages
+pnpm release
+```
+
+Do not publish from a dirty worktree.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentsKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# doc-bridge
+
+**npm:** [`@agentskit/doc-bridge`](https://www.npmjs.com/package/@agentskit/doc-bridge) · **CLI:** `ak-docs`
+
+**Human↔agent documentation bridge** for any project — not a wiki, not a hosted RAG chat.
+
+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**.
+
+Optional intelligence (RAG + terminal chat) uses public AgentsKit packages — install only when you want them.
+
+## Why this exists
+
+| Pattern | Gap |
+|---------|-----|
+| Wiki + RAG | Explains; weak on *where to act* and proof docs match code |
+| AGENTS.md alone | Great static rules; no ownership index, gates, or human bridge |
+| Context7-class tools | Library docs for the model; not *your* monorepo routing |
+
+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"
+}
+```
+
+## Four loops
+
+| 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`) |
+
+## Quick start (< 2 minutes, no key)
+
+```bash
+npm i -D @agentskit/doc-bridge
+npx ak-docs init
+npx ak-docs index
+npx ak-docs query package example --agent
+```
+
+`init` scaffolds config, a demo ownership target, and an `AGENTS.md` snippet.
+
+```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
+```
+
+Full guide: **[docs/getting-started.md](docs/getting-started.md)**.
+
+## Surfaces
+
+### Layer 0 — always (no LLM)
+
+| Surface | Purpose |
+|---------|---------|
+| **Index** | `DocBridgeIndex` + `contentHash` + `llms.txt` + capabilities |
+| **CLI** | `query` / `search` / `list` / `ask` / `gate` / `memory` / `bootstrap` |
+| **MCP** | `handoff.resolve`, `doc.search`, `doc.get`, … |
+| **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
+```
+
+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)
+
+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)
+
+## Configuration examples
+
+| Profile | Example |
+|---------|---------|
+| 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) |
+| 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)
+
+## Status
+
+**v0.1.0-alpha.1** — Layer 0 complete for daily use; Layer 1 RAG/chat wired via optional peers; not yet a guarantee of semver stability.
+
+```bash
+pnpm install && pnpm build && pnpm test
+```
+
+## Contributing
+
+- [CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](SECURITY.md) · [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) · [CHANGELOG.md](CHANGELOG.md)
+- Positioning: [`docs/POSITIONING.md`](docs/POSITIONING.md)
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,24 @@
+# Security Policy
+
+## Supported versions
+
+`@agentskit/doc-bridge` is currently in alpha. Security fixes target the latest published alpha.
+
+## Reporting a vulnerability
+
+Please do not open a public issue for security reports.
+
+Email security reports to `security@agentskit.io` with:
+
+- affected version or commit
+- reproduction steps
+- impact
+- any suggested fix
+
+We will acknowledge reports as soon as practical and coordinate disclosure before publishing details.
+
+## Security expectations
+
+- Core commands must work without sending repository content to a network service.
+- MCP `doc.get` must only read indexed docs inside the project root.
+- Optional intelligence features must stay opt-in and provider-controlled by the user.

package/bin/ak-docs.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runCli } from '../dist/cli/program.js'
+
+const code = runCli(process.argv.slice(2))
+if (typeof code === 'number') process.exit(code)
+if (code) process.exit(await code)

package/dist/cli/program.d.ts

@@ -0,0 +1,3 @@
+declare const runCli: (argv: readonly string[]) => number | undefined | Promise<number>;
+
+export { runCli };