@agentskit/doc-bridge 1.0.1 → 1.1.1

package/CHANGELOG.md

@@ -1,15 +1,46 @@
 # Changelog
 
+## 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.
+
+## 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.
+
 ## 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
@@ -17,6 +48,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
 
@@ -25,6 +57,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`
@@ -37,6 +70,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
@@ -51,6 +85,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
@@ -64,6 +99,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

@@ -19,6 +19,13 @@ pnpm build
 - 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/`.
 
+## 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
 
 Use Changesets for versioned changes:

package/README.md

@@ -1,12 +1,54 @@
 # 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.
+**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, not hosted RAG, and not another chat UI. The core works **without any LLM or API key**.
+
+![doc-bridge maps human docs into structured agent handoffs](docs/landing/assets/doc-bridge-hero.webp)
+
+## Why teams use it
 
-Not a wiki. Not a hosted RAG chat. Layer 0 works **without any LLM or API key**.
+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.
 
-## 60-second wow path
+doc-bridge works in both directions:
+
+![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
@@ -41,6 +83,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.1.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,7 +181,7 @@ Next actions
 Reuse the bundled GitHub Action on every PR:
 
 ```yaml
-- uses: AgentsKit-io/doc-bridge@v1.0.0
+- uses: AgentsKit-io/doc-bridge@v1.1.1
   with:
     config-path: doc-bridge.config.json
 ```
@@ -139,9 +198,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 +210,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
@@ -164,9 +223,6 @@ See **[docs/chat-and-rag.md](docs/chat-and-rag.md)**.
 
 ## 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:
 
 | Surface | Link |
@@ -174,6 +230,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** | [chat framework](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 +259,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.1.1 stable** — deterministic Documentation Standard v1 conformance, verified release provenance, doctor + CI + skill, landing, Playbook pattern, and full Tier A/B/C.
 
 ```bash
 pnpm install && pnpm build && pnpm test
@@ -211,9 +270,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,7 +18,7 @@ inputs:
     required: false
     default: '22'
   package-version:
-    description: npm package version pin (e.g. 0.1.0-alpha.3)
+    description: npm package version pin (e.g. 1.1.1)
     required: false
     default: ''
 
@@ -75,4 +75,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