@agentskit/doc-bridge 1.11.1 → 1.12.0

package/docs/DOGFOOD-V1.md

@@ -1,89 +0,0 @@
----
-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  
-**Install:** `1.0.0` from npm (`alpha` dist-tag; `latest` still points at older alpha.1)
-
-## Scoreboard
-
-| Repo | Install | Ver | K/H | Gate | Doctor | Ranking | Ask handoff preview | MCP install |
-|------|---------|-----|-----|------|--------|---------|---------------------|-------------|
-| **agentskit** | pnpm -Dw ✅ | **1.0.0** | 25/24 | ✅ 24 human | **100/100 A** | core #1 | ✅ core + bridge | ✅ wrote `.cursor/mcp.json` |
-| **playbook** | pnpm -D ✅ | **1.0.0** | 127/81 | ✅ | **100/100 A** | OKF pattern #1 | ✅ | ✅ |
-| **registry** | npm --legacy-peer-deps ✅ | **1.0.0** | 36/36 | ✅ | **100/100 A** | docs-chat #1 | ✅ | ✅ |
-| **agentskit-os** | npx ✅ | **1.0.0** | 170/92 | ✅ | **81/100 B** | os-core #1 | ✅ + “human guide missing” | (not run write) |
-
-## 1.0.0 features exercised
-
-| Feature | Result |
-|---------|--------|
-| `doctor --text` | Score A on 3 repos; B on AKOS with **actionable missing humanDoc list** |
-| `doctor --badge` | Shields markdown for handoff/bridge/score |
-| `demo --text` | Before/after handoff + gate red→green + MCP snippet |
-| `mcp install --cursor` | Creates `.cursor/mcp.json` with nextSteps |
-| `ask` handoff preview | start / edit / checks / Bridge lines |
-| Ranking exact-id | core, os-core, docs-chat, open-knowledge-format-pattern all #1 |
-| Soft federation retrieve | exit 0, local chunks |
-
-## Highlights (impressive)
-
-### agentskit — perfect monorepo story
-
-```
-Score: 100/100 (A)
-Agent docs: 24/24 · Human guides: 24/24 · Badge: handoff 100% · bridge 100%
-```
-
-```
-ask "where do I change the core package?"
-Handoff preview
-  start:  .../for-agents/core.mdx
-  edit:   packages/core
-  checks: pnpm --filter @agentskit/core test · lint
-  Bridge: /docs/reference/packages/core
-```
-
-### playbook — OKF corpus
-
-```
-Score: 100/100 (A) · 81/81 handoff · 81/81 bridge
-checks: pnpm run check:okf-type
-```
-
-### registry — agent-id ownership
-
-```
-Score: 100/100 (A) · 36/36
-docs-chat → registry/docs-chat + npm run validate
-```
-
-### AKOS — honest B (bridge gap is the product)
-
-```
-Score: 81/100 (B)
-Agent docs: 86/92 (93%) · Human guides: 15/92 (16%)
-Missing humanDoc: admin, os-*, desktop-*, …
-notes: "Human guide missing for os-core. Run: ak-docs bootstrap agent-docs"
-ask Bridge: human guide missing → ak-docs bootstrap agent-docs
-```
-
-This is the right UX: **not fake 100%** when product docs are thin.
-
-## Remaining friction (not blockers for 1.0)
-
-1. **npm `latest` still 0.1.0-alpha.1** — users should install `@1.0.0` or `@alpha` until latest is retagged.
-2. **registry** still prefers `--legacy-peer-deps` on some npm versions.
-3. **AKOS** `pnpm add` store mismatch — `npx @agentskit/doc-bridge@1.0.0` works.
-4. **AKOS bridge 16%** — content/map work; doctor already drives it.
-5. **notes** may still show HTML entities (`<`) from source MDX.
-6. **mcp install** writes into repo (`.cursor/mcp.json`) — commit or gitignore intentionally.
-7. **CI** still not wired on all four consumers for `doctor`/`gate` on every PR.
-
-## Verdict
-
-**1.0.0 is validated on the four ecosystem repos.**  
-Doctor + ask handoff preview + mcp install + demo deliver the “wow” layer that alpha.3 still lacked in product surface. AKOS correctly surfaces bridge debt instead of hiding it.

package/docs/DOGFOOD.md

@@ -1,97 +0,0 @@
----
-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.
-
-- First pass: `0.1.0-alpha.1` (local `file:`)
-- Second pass after polish: **`0.1.0-alpha.2`** (`v0.1.0-alpha.2`)
-
-## Standard integration (all repos)
-
-| Artifact | Purpose |
-|----------|---------|
-| `doc-bridge.config.json` | Layer 0 config (schemaVersion 1) |
-| `docs:bridge:index` | `ak-docs index` |
-| `docs:bridge:gate` | `ak-docs gate run` |
-| `docs:bridge:query` | `ak-docs query` |
-| `.doc-bridge/` | Generated index (gitignored) |
-| `devDependency` | `@agentskit/doc-bridge` (`file:` or `0.1.0-alpha.1` / `@alpha` when npm resolves) |
-
-### MCP (optional, same in each repo)
-
-```json
-{
-  "mcpServers": {
-    "ak-docs": {
-      "command": "ak-docs",
-      "args": ["mcp"]
-    }
-  }
-}
-```
-
-## Results
-
-| Repo | Knowledge | Handoffs | Gate | Sample handoff |
-|------|-----------|----------|------|----------------|
-| **agentskit** | 25 | 24 | ✅ freshness + 24 humanDoc | `core` → `packages/core` + for-agents MDX |
-| **agentskit-os** | 170 | 82 | ✅ freshness + 2 humanDoc | `os-core` → for-agents package doc |
-| **agents-playbook** | 127 | 81 patterns | ✅ freshness + okf-type | `open-knowledge-format-pattern` |
-| **agentskit-registry** | 36 | 36 | ✅ freshness | `docs-chat` → `registry/docs-chat` |
-
-## Findings / improvements for doc-bridge
-
-### P0 product feedback
-1. **Default checks are npm-centric** (`npm test` / `npm run lint`) even in pnpm monorepos. Prefer detecting `packageManager` or `pnpm --filter <id> test`.
-2. **Git install lacks `dist/`** — `github:…#tag` installs source only; need `prepare`/`prepack` that builds, or document npm-only install.
-3. **`docs-style` gate is too strict** for playbook OKF (expects purpose/owner-source on every page). Make playbook profile softer or map to existing `check:okf-type`.
-4. **HumanDoc join rate low on AKOS** (2/82) — product Fumadocs tree is thin vs package atlas; support multi-human corpora (product + `docs/adr`) and/or ownership `humanDoc` from for-agents frontmatter.
-
-### P1 DX
-5. **Nested agent corpus inside human tree** (agentskit for-agents under `content/docs`) double-counts unless human meta exclude — works but humanDoc points at `/docs/for-agents/core` which is correct for that site.
-6. **Playbook is pattern-owned, not package-owned** — ownership generation from filenames works; first-class `routing.plugin: pattern-files` would help.
-7. **Registry human plain-markdown** + URL prefix `/agents/:id` works; committed `public/llms.txt` must stay owner of site discovery (`llmsTxt.enabled: false`).
-8. **AKOS pnpm store mismatch** can block `pnpm add` — dogfood via absolute `ak-docs` still validates; install needs store alignment.
-
-### P2 ecosystem
-9. Ship **npm package** publicly (`@agentskit/doc-bridge@alpha`) so consumers drop `file:`.
-10. Wire `docs:bridge:gate` into each CI (`check:quality-gates` / registry verify / new playbook workflow).
-11. Federation: registry `llms.txt` still 404 online — dogfood configs already list it; fix registry publish of Self-Describe artifact.
-
-## Per-repo config notes
-
-### agentskit
-- Agent: `apps/docs-next/content/docs/for-agents`
-- Human: Fumadocs same docs tree
-- Routing: `pnpm-monorepo` `packages/*`
-- Best fit: clean monorepo + for-agents coverage already exists
-
-### agentskit-os
-- Agent: `docs/for-agents` (canonical)
-- Human: product Fumadocs only (`apps/web/content/docs`) — dual human later
-- `llmsTxt.enabled: false` (keep `gen-self-describe`)
-- Dual-run with `docs:internal` — do not delete internal generators yet
-
-### agents-playbook
-- Agent = human = `content/docs` (OKF)
-- Ownership: generated per pattern file under pillars
-- Gates: `index-freshness` + `okf-type` only (not docs-style)
-
-### agentskit-registry
-- Agent root: `registry/**/README.md`
-- Ownership: one entry per agent id
-- npm package (not pnpm workspace)
-- `llmsTxt.enabled: false`
-
-## Commands used to validate
-
-```bash
-ak-docs index
-ak-docs gate run
-ak-docs query package <id> --agent
-ak-docs list packages --text
-```