@agentskit/doc-bridge 1.1.1 → 1.2.3

package/docs/DOGFOOD-ROUND2.md

@@ -1,3 +1,8 @@
+---
+title: Dogfood round 2
+description: Validation evidence from the second published Doc Bridge alpha.
+---
+
 # Dogfood round 2 — published `@agentskit/doc-bridge@0.1.0-alpha.2`
 
 **Date:** 2026-07-09  

package/docs/DOGFOOD-ROUND3.md

@@ -1,3 +1,8 @@
+---
+title: Dogfood round 3
+description: Validation evidence from the third published Doc Bridge alpha.
+---
+
 # Dogfood round 3 — `@agentskit/doc-bridge@0.1.0-alpha.3`
 
 **Date:** 2026-07-09  

package/docs/DOGFOOD-V1.md

@@ -1,3 +1,8 @@
+---
+title: Dogfood validation v1
+description: Release validation evidence for the first stable Doc Bridge package.
+---
+
 # Dogfood validation — `@agentskit/doc-bridge@1.0.0`
 
 **Date:** 2026-07-09  

package/docs/DOGFOOD.md

@@ -1,3 +1,8 @@
+---
+title: Ecosystem dogfood
+description: How AgentsKit repositories validate Doc Bridge against real documentation surfaces.
+---
+
 # Ecosystem dogfood — `@agentskit/doc-bridge`
 
 Validated **2026-07-09** against four consumers.

package/docs/MARKETPLACE-ECOSYSTEM-PLAN.md

@@ -0,0 +1,16 @@
+---
+title: Ecosystem and Marketplace acceptance plan
+description: Internal acceptance criteria for the Doc Bridge ecosystem and Marketplace slice.
+---
+
+# Doc Bridge ecosystem and Marketplace acceptance plan
+
+This slice is complete only when all conditions below are evidenced locally. Publication remains an owner-only follow-up.
+
+- Composite Action validates committed freshness, accepts shell inputs only through quoted environment variables, pins its runtime package, and pins third-party Actions by SHA.
+- Marketplace metadata, consumer example, release-owner checklist, and automated contract checks agree on the same version.
+- The public portal exposes seven ecosystem products, six Doc Bridge peers, and contextual routes for Chat, Code Review, and AKOS.
+- `/for-agents`, `llms.txt`, `llms-full.txt`, raw Markdown, and deterministic knowledge are public and cross-linked.
+- Human docs remain concise and navigable; source-heavy detail stays in raw/full machine surfaces.
+- Landing and documentation pages have no horizontal overflow at 375, 768, 1280, or 1440 pixels.
+- `ak-docs gate run`, documentation conformance, and `ak-docs doctor` finish at 100/A.

package/docs/MARKETPLACE.md

@@ -0,0 +1,45 @@
+---
+title: GitHub Marketplace
+description: Add the Doc Bridge freshness gate to pull requests with a reproducible composite Action.
+---
+
+# GitHub Marketplace
+
+Doc Bridge ships one root composite Action: `doc-bridge-gate`. It verifies the committed index and configured documentation gates without rebuilding artifacts first.
+
+## Use it in a repository
+
+```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
+```
+
+If the index is stale, run `ak-docs index`, review the generated diff, and commit it. The Action's default package version matches its immutable release tag.
+
+## Release-owner checklist
+
+1. Run `pnpm check:marketplace`, `pnpm test:marketplace`, and the repository release matrix.
+2. Confirm the public repository contains exactly one root `action.yml` and its name is available.
+3. Push the immutable semver tag. The release workflow publishes npm, uploads the artifact, and leaves a GitHub Release draft ready for review.
+4. Open that draft, select **Publish this Action to the GitHub Marketplace**, choose categories, and accept the GitHub Marketplace Developer Agreement if prompted.
+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

@@ -1,3 +1,8 @@
+---
+title: Doc Bridge positioning
+description: Product purpose, boundaries, maturity, and role inside the AgentsKit ecosystem.
+---
+
 # doc-bridge positioning
 
 Source of truth for README, issues, RFCs, and external posts.
@@ -49,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
@@ -78,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/RELEASE.md

@@ -1,3 +1,8 @@
+---
+title: Release checklist
+description: Reproducible package, documentation, and registry checks for a Doc Bridge release.
+---
+
 # Release checklist — `@agentskit/doc-bridge`
 
 ## Pre-flight (local)
@@ -27,37 +32,41 @@ pnpm changeset          # if new entry needed
 pnpm version-packages   # bumps package.json + CHANGELOG from .changeset/*
 ```
 
-Current track: **`1.1.1` stable** (alpha series ended at `0.1.0-alpha.5`).
+Current track: **`1.2.1` stable** (alpha series ended at `0.1.0-alpha.5`).
 
 ## Publish (npm + GitHub)
 
-Stable releases are published only by `.github/workflows/release.yml` from an immutable semver tag. The workflow re-runs the complete security, test, coverage, packaged-smoke, dogfood, and conformance matrix, publishes with npm provenance through the `npm` environment, verifies the registry result, uploads the tarball to GitHub Releases, and then marks the release latest.
+Stable packages are published only by `.github/workflows/release.yml` from an immutable semver tag. The workflow re-runs the complete security, test, coverage, packaged-smoke, dogfood, Marketplace-contract, and conformance matrix, publishes npm with provenance, verifies the registry result, uploads the tarball to a GitHub Release draft, and leaves final publication to the owner so the Marketplace fields can be completed first.
 
 ```bash
-git tag v1.1.1
-git push origin v1.1.1
+git tag v1.2.1
+git push origin v1.2.1
 ```
 
 For recovery of an existing immutable tag, use the guarded manual dispatch. Never move or recreate a release tag.
 
 ```bash
-gh workflow run release.yml --ref master -f tag=v1.1.1
+gh workflow run release.yml --ref master -f tag=v1.2.1
 ```
 
 Confirm:
 
 ```bash
-npm view @agentskit/doc-bridge@1.1.1 version dist.integrity
-npx ak-docs@1.1.1 --version
-gh release view v1.1.1
+npm view @agentskit/doc-bridge@1.2.1 version dist.integrity
+npx ak-docs@1.2.1 --version
+gh release view v1.2.1 --json isDraft
 ```
 
-GitHub Pages must remain configured for GitHub Actions; `.github/workflows/pages.yml` deploys the landing page from `docs/landing`.
+GitHub Pages must remain configured for GitHub Actions; `.github/workflows/pages.yml` builds and deploys the Fumadocs portal from `apps/docs`.
+
+## Publish the GitHub Action to Marketplace
+
+Run `pnpm check:marketplace && pnpm test:marketplace`, then follow [the Marketplace guide](./MARKETPLACE.md). In the generated release draft, select the Marketplace option and categories before publishing the GitHub Release. npm success alone does not publish the listing.
 
 ## Post-publish smoke (fresh machine)
 
 ```bash
-npm i -D @agentskit/doc-bridge@1.1.1
+npm i -D @agentskit/doc-bridge@1.2.1
 npx ak-docs init
 npx ak-docs index
 npx ak-docs query package example --agent

package/docs/agent-corpus/INDEX.md

@@ -0,0 +1,10 @@
+---
+type: package
+package: doc-bridge-index
+editRoot: src/index-builder
+humanDoc: /docs/recipes/index-pipeline
+---
+
+# Index builder
+
+Owns corpus scanning, handoffs, hashes, `llms.txt`, and watch mode. Generated output must remain deterministic.

package/docs/agent-corpus/OVERVIEW.md

@@ -0,0 +1,9 @@
+---
+type: index
+purpose: Route coding agents to Doc Bridge ownership sidecars.
+owner: maintainers
+---
+
+# Doc Bridge agent corpus
+
+Resolve the requested ownership ID with `ak-docs query ownership <id> --agent`. Read the returned sidecar and its linked human guide before editing.

package/docs/agent-corpus/chat.md

@@ -0,0 +1,10 @@
+---
+type: package
+package: doc-bridge-chat
+editRoot: src/intelligence
+humanDoc: /docs/chat-and-rag
+---
+
+# Chat and RAG
+
+Owns optional AgentsKit retrieval and chat after deterministic lookup. Conversational UI belongs to AgentsKit Chat; enterprise orchestration belongs to AKOS.

package/docs/agent-corpus/cli.md

@@ -0,0 +1,10 @@
+---
+type: package
+package: doc-bridge-cli
+editRoot: src/cli
+humanDoc: /docs/spec/cli
+---
+
+# CLI
+
+Owns public `ak-docs` commands and output modes. Keep JSON output versioned and text output readable.

package/docs/agent-corpus/conformance.md

@@ -0,0 +1,10 @@
+---
+type: package
+package: doc-bridge-conformance
+editRoot: src/conformance
+humanDoc: /docs/spec/documentation-standard-v1
+---
+
+# Conformance
+
+Owns versioned documentation-standard rules and evidence. Do not turn missing evidence into a passing score.

package/docs/agent-corpus/doc-bridge.md

@@ -0,0 +1,10 @@
+---
+type: package
+package: doc-bridge
+editRoot: src
+humanDoc: /docs/POSITIONING
+---
+
+# Doc Bridge core
+
+Owns the public CLI, index, MCP, gates, and doctor contracts. Preserve deterministic behavior and run `pnpm test && pnpm typecheck`.

package/docs/agent-corpus/doctor.md

@@ -0,0 +1,10 @@
+---
+type: package
+package: doc-bridge-doctor
+editRoot: src/doctor
+humanDoc: /docs/spec/documentation-standard-v1
+---
+
+# Doctor
+
+Owns health scoring and remediation guidance. Every point must trace to meaningful repository evidence.

package/docs/agent-corpus/gates.md

@@ -0,0 +1,10 @@
+---
+type: package
+package: doc-bridge-gates
+editRoot: src/gates
+humanDoc: /docs/spec/documentation-standard-v1
+---
+
+# Gates
+
+Owns freshness, coverage, and human-link checks. A gate must observe committed state before rewriting artifacts.

package/docs/agent-corpus/mcp.md

@@ -0,0 +1,10 @@
+---
+type: package
+package: doc-bridge-mcp
+editRoot: src/mcp
+humanDoc: /docs/mcp
+---
+
+# MCP
+
+Owns the stdio server and public tool contracts. Preserve runtime validation and stable response shapes.

package/docs/agent-corpus/memory.md

@@ -0,0 +1,10 @@
+---
+type: package
+package: doc-bridge-memory
+editRoot: src/memory
+humanDoc: /docs/schemas/memory-candidate-v1
+---
+
+# Memory
+
+Owns reviewable learning ingestion, classification, and promotion. Durable knowledge becomes a documented change, never silent state.

package/docs/agent-corpus/query.md

@@ -0,0 +1,10 @@
+---
+type: package
+package: doc-bridge-query
+editRoot: src/query
+humanDoc: /docs/query
+---
+
+# Query
+
+Owns deterministic package and document resolution. Prefer an explicit miss over an invented answer.

package/docs/chat-and-rag.md

@@ -1,3 +1,8 @@
+---
+title: Chat and RAG
+description: Add optional AgentsKit retrieval and chat after deterministic documentation resolution.
+---
+
 # Chat and RAG (Layer 1)
 
 Layer 0 (index, handoff, MCP, gates, memory pipeline) never requires an LLM.
@@ -12,6 +17,35 @@ Layer 1 is **opt-in** and dogfoods public AgentsKit packages:
 | `@agentskit/ink` | Terminal chat UI (`ak-docs chat`) |
 | `react` | Required by Ink |
 
+## 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.4.x
+surface. It does not recreate chat lifecycle or session state.
+
+At build time, `scripts/build-docs-artifacts.mjs` reads the fresh
+`.doc-bridge/index.json` and canonical `docs/**` corpus, then writes:
+
+- `deterministic/knowledge.json` — exact commands, documents, and real ownership handoffs;
+- `deterministic/site-config.json` — trusted artifact hash plus fallback policy;
+- `llms.txt`, `llms-full.txt`, and `raw/**` — model-friendly public sources.
+
+The browser verifies the SHA-256 content hash before using the artifact. A
+known exact question answers locally with provenance. Multiple exact matches
+return local choices. Only a genuine miss reaches the configured backend, and
+the UI reports a backend answer only after a successful completed stream.
+
+```mermaid
+flowchart LR
+  Q[Question] --> A{Verified exact match?}
+  A -->|one| L[Local answer + citation]
+  A -->|many| C[Local choices]
+  A -->|none| B[AgentsKit backend]
+  B --> S{Completed stream?}
+  S -->|yes| R[Backend answer + provenance]
+  S -->|no| E[Retryable error]
+```
+
 ## Trust model
 
 1. **`handoffFirst`** (default): if the question mentions a known package id, attach deterministic AgentHandoff context before the model answers.

package/docs/examples.md

@@ -1,3 +1,8 @@
+---
+title: Examples
+description: Ready-to-run Doc Bridge configurations and integration examples.
+---
+
 # Examples
 
 Config sketches under [`examples/`](../examples/):
@@ -43,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

@@ -0,0 +1,39 @@
+---
+title: For agents
+description: Resolve ownership, read compact context, and run the repository's own checks before editing.
+---
+
+# For agents
+
+Use Doc Bridge before changing a module. It returns versioned, runtime-validated data instead of asking a model to infer ownership from the entire repository.
+
+```bash
+ak-docs query ownership <id> --agent
+```
+
+The response supplies four things: `startHere`, `readBeforeEditing`, `editRoots`, and `checks`.
+
+```mermaid
+flowchart LR
+  Q["Resolve ownership"] --> R["Read startHere"]
+  R --> E["Edit only editRoots"]
+  E --> T["Run checks"]
+  T --> P["Promote durable learning"]
+```
+
+## Machine entry points
+
+- [`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

@@ -1,3 +1,8 @@
+---
+title: Getting started
+description: Install, index, query, and gate repository documentation in about 60 seconds.
+---
+
 # Getting started
 
 doc-bridge turns your existing docs into an **AgentHandoff** index:
@@ -147,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)