@agentskit/doc-bridge 1.0.2 → 1.2.1

package/CHANGELOG.md

@@ -1,8 +1,50 @@
 # Changelog
 
+## 1.2.1
+
+### Fixes
+
+- Restore the stable release audit with pnpm's bulk advisory client and pin patched transitive versions of PostCSS, tmp, and uuid.
+
+## 1.2.0
+
+### Minor Changes
+
+- d4260b9: Add the production documentation portal, deterministic AgentsKit Chat knowledge surface, generated LLM and raw Markdown artifacts, and README Standard v1 quality gates.
+
+## Unreleased
+
+### Features
+
+- Migrate the documentation portal dogfood from AgentsKit Chat 0.2 packages (`@agentskit/chat-protocol`, `@agentskit/chat-react`) to the consolidated 0.3.x surface (`@agentskit/chat/protocol`, `@agentskit/chat/react`) while keeping `@agentskit/chat` as the root package.
+- Replace the legacy Pages landing with a statically exported Fumadocs portal backed directly by the canonical `docs/**` corpus.
+- Generate `llms.txt`, `llms-full.txt`, raw Markdown, and a hash-verified deterministic AgentsKit Chat artifact from the repository's own Doc Bridge index.
+- Add dynamic AgentsKit Chat dogfood with local exact answers, ambiguity choices, session-aware backend fallback, and explicit provenance.
+- Adopt README Standard v1 for repository, package, and public-app profiles with synchronized executable examples and freshness evidence.
+
+### Quality
+
+- Add `pnpm check:no-legacy-chat-imports` to reject any reintroduction of `@agentskit/chat-protocol` or `@agentskit/chat-react`.
+- Add desktop/mobile Playwright coverage for the landing, Fumadocs, local chat, ambiguity, and completed backend stream.
+- Expand self-ownership handoffs across CLI, indexing, query, MCP, quality, memory, and intelligence modules.
+
+## 1.1.1
+
+### Fixes
+
+- Publish stable packages only from immutable tags after security, test, coverage, packaged-smoke, dogfood, and Documentation Standard v1 gates pass.
+- Sync the canonical ecosystem snapshot before release so conformance and cross-product navigation remain current.
+
+## 1.1.0
+
+### Minor Changes
+
+- Add the stable, HITL-approved Documentation Standard v1 deterministic conformance profile, CLI command, reports, remediation, explicit approved exceptions, generated llms.txt freshness checks, and canonical ecosystem manifest/claims validation.
+
 ## 1.0.2
 
 ### Fixes
+
 - Sync `ak-docs --version`, MCP `serverInfo.version`, and capabilities version from `package.json` during build/release.
 - Allow `ak-docs query <id> --agent` as a shortcut for package/ownership handoff lookup.
 - Packaged smoke now verifies installed CLI version.
@@ -10,6 +52,7 @@
 ## 1.0.1
 
 ### Fixes
+
 - Hardened release validation with coverage for Layer 1 CLI, RAG/chat wrappers, MCP install, package-manager checks, watcher, markdown/glob helpers, and packaged/docsite smoke paths.
 - Fixed provider API-key defaults for optional AgentsKit intelligence adapters.
 - Replaced publish-time `pnpm build` hooks with `npm run build` for npm-friendly packing.
@@ -19,11 +62,13 @@
 **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
@@ -31,6 +76,7 @@
 - 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
 
@@ -39,6 +85,7 @@
 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`
@@ -51,6 +98,7 @@ Tier B — power-user workflows and production pipeline polish.
 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
@@ -65,6 +113,7 @@ Activation and agent-adoption polish — from "works" to "wow in 60s".
 Dogfood round-2 fixes (search ranking, full-text body, peers, federation soft-fail).
 
 ### Fixes
+
 - **Search ranking:** exact id / basename boost; ownership preferred for routing questions; path dedupe
 - **Full-text search:** knowledge entries store `body` excerpt; descriptions prefer frontmatter `purpose` and complete sentences
 - **ask:** next command prefers ownership match over knowledge-only
@@ -78,6 +127,7 @@ Dogfood round-2 fixes (search ranking, full-text body, peers, federation soft-fa
 Dogfood-driven polish after ecosystem install on agentskit, agentskit-os, playbook, and registry.
 
 ### Fixes / features
+
 - **Package-manager-aware checks** — pnpm/yarn/npm/bun; `pnpm --filter <pkg>` in workspaces
 - **Corpus ownership inference** — `packages/<id>.md`, pillars patterns, registry READMEs (toggle `routing.options.ownershipFromCorpus`)
 - **Richer `guessAgentDocForPackage`** — packages/id, index.md, mdx, for-agents top-level

package/CONTRIBUTING.md

@@ -18,6 +18,14 @@ pnpm build
 - 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/`.
+- Dogfood AgentsKit Chat 0.3.x only: `@agentskit/chat`, `@agentskit/chat/protocol`, and `@agentskit/chat/react`. Never reintroduce `@agentskit/chat-protocol` or `@agentskit/chat-react` (`pnpm check:no-legacy-chat-imports`).
+
+## Pull request checklist
+
+- Run `pnpm typecheck && pnpm test && pnpm build`.
+- Run `npm pack --dry-run` for package or README changes.
+- Update docs and `CHANGELOG.md` when behavior changes.
+- Keep examples public and reproducible.
 
 ## Releases
 

package/README.md

@@ -1,12 +1,58 @@
 # doc-bridge
 
+[![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/workflows/ci.yml)
+[![Pages](https://img.shields.io/github/actions/workflow/status/AgentsKit-io/doc-bridge/pages.yml?branch=master&label=pages&style=flat-square)](https://agentskit-io.github.io/doc-bridge/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D22-339933?style=flat-square)](package.json)
+[![TypeScript](https://img.shields.io/badge/types-TypeScript-3178c6?style=flat-square)](dist/index.d.ts)
+
 **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/)
 
-**AgentHandoff for your monorepo** — deterministic routing so coding agents edit the right package, run the right checks, and stay linked to human docs.
+**Topics:** `ai-agents` · `documentation` · `developer-experience` · `mcp` · `llms-txt` · `typescript`
+
+**Compatibility:** node >=22 · TypeScript 5.8+ · pnpm, npm, or yarn consumers
+
+**Turn your docs into executable handoffs for coding agents.**
+
+doc-bridge reads your repo docs, ownership map, and human documentation site, then gives every agent the same answer:
+
+- where to start reading
+- which files/packages it may edit
+- which checks prove the change
+- which human docs explain the feature
+
+It is not a wiki or hosted RAG. The core works **without any LLM or API key**; the documentation portal dogfoods AgentsKit Chat as an optional surface over that deterministic layer.
+
+![doc-bridge maps human docs into structured agent handoffs](docs/landing/assets/doc-bridge-hero.webp)
+
+## Why teams use it
+
+Agents are powerful, but most repo docs are written for humans. The result is familiar: the agent guesses ownership, edits the sibling package, runs the wrong test, or ignores the human guide that already explained the rule.
 
-Not a wiki. Not a hosted RAG chat. Layer 0 works **without any LLM or API key**.
+doc-bridge works in both directions:
 
-## 60-second wow path
+![doc-bridge connects human docs to coding agents and agent memory back to draft docs](docs/landing/assets/doc-bridge-two-way.webp)
+
+| Direction | What it does | Command |
+|-----------|--------------|---------|
+| **Human docs → agents** | Turns Fumadocs, Docusaurus, markdown, and ownership docs into `AgentHandoff` | `ak-docs index` · `ak-docs query --agent` |
+| **Agent memory → docs** | Reads `.agent-memory/**` and `.cursor/rules/*.mdc`, classifies what should become project docs, and drafts a human-reviewed promotion | `ak-docs memory ingest` · `classify` · `promote --pr` |
+
+The handoff is a routing contract:
+
+```json
+{
+  "startHere": "docs/for-agents/packages/auth.md",
+  "editRoots": ["packages/auth"],
+  "checks": ["pnpm --filter @demo/auth test"],
+  "humanDoc": "/docs/guides/auth"
+}
+```
+
+That contract works from the terminal, MCP, CI, and optional RAG/chat.
+
+## 60-second proof
 
 ```bash
 npm i -D @agentskit/doc-bridge
@@ -32,6 +78,24 @@ Monorepo fixture with auth + billing:
 npx ak-docs demo --fixture monorepo --text
 ```
 
+### Verify the real handoff path
+
+This checked example runs the bundled demo through the public CLI. The README gate compares this block byte-for-byte with the executable fixture and runs it on every PR.
+
+<!-- readme-command:verify-handoff -->
+<!-- readme-example:verify-handoff -->
+```js
+import { execFileSync } from 'node:child_process'
+
+execFileSync(process.execPath, ['bin/ak-docs.js', 'demo', '--text'], {
+  stdio: 'inherit',
+})
+```
+
+```bash
+node examples/verify-handoff.mjs
+```
+
 Full setup in your repo:
 
 ```bash
@@ -41,6 +105,23 @@ npx ak-docs query package example --agent
 ak-docs mcp install --cursor   # wires MCP into .cursor/mcp.json
 ```
 
+## What ships
+
+![doc-bridge index used through CLI, MCP, CI, and documentation adapters](docs/landing/assets/doc-bridge-surfaces.webp)
+
+| Surface | Use it for | Command / artifact |
+|---------|------------|--------------------|
+| **CLI** | Inspect ownership, search docs, run gates, ask local questions | `ak-docs query`, `search`, `ask`, `doctor`, `gate` |
+| **MCP server** | Let Cursor, Claude Code, Codex-style agents resolve handoffs before editing | `ak-docs mcp`, `handoff.resolve` |
+| **GitHub Action / CI** | Fail stale indexes and broken human-doc links on PRs | `AgentsKit-io/doc-bridge@v1.2.1` |
+| **Documentation conformance** | Check the stable ecosystem standard with auditable evidence | `ak-docs conformance run documentation-standard-v1 --text` |
+| **Doc adapters** | Link human docs to agent docs | `fumadocs`, `docusaurus`, `plain-markdown` |
+| **Monorepo routing** | Discover workspaces and checks | `pnpm-monorepo` |
+| **Memory pipeline** | Turn agent notes into reviewable documentation drafts | `memory ingest`, `classify`, `promote --pr` |
+| **Optional RAG/chat** | Ground chat in the same handoff-first index | `@agentskit/rag`, `@agentskit/ink`, `ak-docs chat` |
+
+See [docs/getting-started.md](docs/getting-started.md), [docs/mcp.md](docs/mcp.md), and [docs/examples.md](docs/examples.md).
+
 ## Why this exists
 
 | Pattern | Gap |
@@ -122,11 +203,18 @@ Next actions
 Reuse the bundled GitHub Action on every PR:
 
 ```yaml
-- uses: AgentsKit-io/doc-bridge@v1.0.0
-  with:
-    config-path: doc-bridge.config.json
+permissions:
+  contents: read
+
+steps:
+  - uses: actions/checkout@v4
+  - uses: AgentsKit-io/doc-bridge@v1.2.1
+    with:
+      config-path: doc-bridge.config.json
 ```
 
+The Action checks the committed index before changing anything, pins the matching npm package, and rejects non-exact package versions. See the [Marketplace guide](docs/MARKETPLACE.md).
+
 ![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.
@@ -139,9 +227,9 @@ ak-docs index && ak-docs gate run
 
 Gate fails with `Index is stale. Run: ak-docs index` — same check in CI annotations.
 
-## Surfaces
+## Product surface
 
-### Layer 0 — always (no LLM)
+### Core — always (no LLM)
 
 | Surface | Purpose |
 |---------|---------|
@@ -151,9 +239,9 @@ Gate fails with `Index is stale. Run: ak-docs index` — same check in CI annota
 | **CLI** | `query` / `search` / `list` / `ask` / `gate` / `memory` / `bootstrap` |
 | **MCP** | `handoff.resolve`, `doc.search`, `doc.get`, `gate.status`, … |
 | **Gates** | Freshness, human-link validation, optional OKF style |
-| **Plugins** | `pnpm-monorepo`, `fumadocs`, `docusaurus`, `plain-markdown` |
+| **Adapters** | `pnpm-monorepo`, `fumadocs`, `docusaurus`, `plain-markdown` |
 
-### Layer 1 — optional AgentsKit peers
+### Optional AgentsKit peers
 
 ```bash
 npm i -D @agentskit/rag @agentskit/ink @agentskit/adapters @agentskit/memory react
@@ -162,10 +250,9 @@ ak-docs rag ingest && ak-docs chat
 
 See **[docs/chat-and-rag.md](docs/chat-and-rag.md)**.
 
-## Who uses it (public)
+## AgentsKit ecosystem
 
-[![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)
+### Who uses it (public)
 
 Designed for and dogfooded on open AgentsKit surfaces:
 
@@ -174,6 +261,9 @@ Designed for and dogfooded on open AgentsKit surfaces:
 | **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) |
+| **AgentsKit Chat** | [documentation](https://chat.agentskit.io) · [source](https://github.com/AgentsKit-io/agentskit-chat) |
+| **AgentsKit OS** | [akos.agentskit.io](https://akos.agentskit.io) |
+| **Code Review** | [repository-native CLI](https://github.com/AgentsKit-io/code-review-cli) |
 | **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`
@@ -200,7 +290,7 @@ ak-docs memory promote --pr              # opens draft PR via gh
 
 ## Status
 
-**v1.0.0 stable** — doctor + CI + skill boring-reliable. Landing, Playbook pattern, full Tier A/B/C shipped.
+**v1.2.1 stable** — deterministic Documentation Standard v1 conformance, verified release provenance, Fumadocs portal, Marketplace Action, doctor + CI + skill, and full Tier A/B/C.
 
 ```bash
 pnpm install && pnpm build && pnpm test
@@ -211,9 +301,16 @@ pnpm smoke:ollama    # optional — skips if Ollama/peers unavailable
 
 ## 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)
+Issues and PRs are welcome. Start here:
+
+| Need | Doc |
+|------|-----|
+| Local setup, tests, release flow | [CONTRIBUTING.md](CONTRIBUTING.md) |
+| Vulnerability reports | [SECURITY.md](SECURITY.md) |
+| Community standards | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) |
+| Release history | [CHANGELOG.md](CHANGELOG.md) |
+| Product positioning | [docs/POSITIONING.md](docs/POSITIONING.md) |
 
 ## License
 
-MIT
+[MIT](LICENSE)

package/SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Supported versions
 
-`@agentskit/doc-bridge` is currently in alpha. Security fixes target the latest published alpha.
+Security fixes target the latest stable `@agentskit/doc-bridge` release on npm.
 
 ## Reporting a vulnerability
 

package/action.yml

@@ -18,46 +18,41 @@ inputs:
     required: false
     default: '22'
   package-version:
-    description: npm package version pin (e.g. 0.1.0-alpha.3)
+    description: Exact @agentskit/doc-bridge npm version (kept in sync with this Action release)
     required: false
-    default: ''
+    default: '1.2.1'
 
 runs:
   using: composite
   steps:
     - name: Setup Node
-      uses: actions/setup-node@v4
+      uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v4
       with:
         node-version: ${{ inputs.node-version }}
 
     - name: Install ak-docs
       shell: bash
+      env:
+        DOC_BRIDGE_PACKAGE_VERSION: ${{ inputs.package-version }}
       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
+        if [[ ! "$DOC_BRIDGE_PACKAGE_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
+          echo "::error title=Invalid package-version::Use an exact semver version such as 1.2.1"
+          exit 2
         fi
+        npm install -g "@agentskit/doc-bridge@${DOC_BRIDGE_PACKAGE_VERSION}"
 
     - name: Run gates
       shell: bash
+      env:
+        DOC_BRIDGE_CONFIG_PATH: ${{ inputs.config-path }}
+        DOC_BRIDGE_GATE_ID: ${{ inputs.gate }}
       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 }}"
+        if [ -n "$DOC_BRIDGE_GATE_ID" ] && [ -n "$DOC_BRIDGE_CONFIG_PATH" ]; then
+          ak-docs gate run "$DOC_BRIDGE_GATE_ID" --config "$DOC_BRIDGE_CONFIG_PATH"
+        elif [ -n "$DOC_BRIDGE_GATE_ID" ]; then
+          ak-docs gate run "$DOC_BRIDGE_GATE_ID"
+        elif [ -n "$DOC_BRIDGE_CONFIG_PATH" ]; then
+          ak-docs gate run --config "$DOC_BRIDGE_CONFIG_PATH"
         else
           ak-docs gate run
         fi
@@ -65,9 +60,11 @@ runs:
     - name: Doctor coverage (annotation)
       shell: bash
       continue-on-error: true
+      env:
+        DOC_BRIDGE_CONFIG_PATH: ${{ inputs.config-path }}
       run: |
-        if [ -n "${{ inputs.config-path }}" ]; then
-          REPORT="$(ak-docs doctor --text --config "${{ inputs.config-path }}" 2>&1 || true)"
+        if [ -n "$DOC_BRIDGE_CONFIG_PATH" ]; then
+          REPORT="$(ak-docs doctor --text --config "$DOC_BRIDGE_CONFIG_PATH" 2>&1 || true)"
         else
           REPORT="$(ak-docs doctor --text 2>&1 || true)"
         fi
@@ -75,4 +72,4 @@ runs:
         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
+        fi