@agentskit/doc-bridge 0.1.0-alpha.1 → 0.1.0-alpha.3

package/docs/DOGFOOD-ROUND2.md

@@ -0,0 +1,142 @@
+# Dogfood round 2 — published `@agentskit/doc-bridge@0.1.0-alpha.2`
+
+**Date:** 2026-07-09  
+**Install:** npm registry tag `alpha` → `0.1.0-alpha.2`  
+**Consumers:** agentskit · agentskit-os · agents-playbook · agentskit-registry  
+
+## Scoreboard
+
+| Repo | Install | Version | Knowledge | Handoffs | Gate | Sample handoff quality |
+|------|---------|---------|-----------|----------|------|------------------------|
+| **agentskit** | `pnpm add -Dw @0.1.0-alpha.2` ✅ | 0.1.0-alpha.2 | 25 | 24 | ✅ freshness + 23 humanDoc | Excellent: pnpm filter checks + humanDoc `/docs/reference/packages/core` |
+| **agentskit-os** | pnpm store conflict; used **`npx`** ✅ | 0.1.0-alpha.2 | 170 | 92 | ✅ freshness + 9 humanDoc | Good act path; weak human bridge (9/92) |
+| **agents-playbook** | `pnpm add -D` ✅ | 0.1.0-alpha.2 | 127 | 81 | ✅ freshness + okf-type | Pattern ownership + `check:okf-type` ✅ |
+| **agentskit-registry** | needs `--legacy-peer-deps` ⚠️ | 0.1.0-alpha.2 | 36 | 36 | ✅ freshness | Full agent ownership + humanDoc ✅ |
+
+### npm dist-tags (observed)
+
+| Tag | Version |
+|-----|---------|
+| `latest` | `0.1.0-alpha.1` |
+| `alpha` | `0.1.0-alpha.2` |
+
+**Recommendation:** keep prereleases only on `alpha` until stable; document `npm i -D @agentskit/doc-bridge@alpha`.
+
+---
+
+## What works well (validated)
+
+1. **Published binary works** — `ak-docs 0.1.0-alpha.2` from registry / npx.
+2. **Monorepo handoffs** — `editRoots` + `pnpm --filter @agentskit/<pkg> test|lint` on agentskit and AKOS.
+3. **Playbook preset** — gates green without crushing large OKF corpus.
+4. **Registry ownership** — all 36 agents resolve; checks use `npm run validate`.
+5. **Fumadocs humanDoc** on agentskit points at **reference** docs, not nested for-agents.
+6. **Pattern checks** — playbook patterns emit `pnpm run check:okf-type`.
+
+---
+
+## Issues found (prioritized)
+
+### P0 — correctness / ranking (agents will take wrong action)
+
+| ID | Issue | Evidence | Suggested fix |
+|----|--------|----------|----------------|
+| **R2-1** | **Search/ask ranking ignores exact package id** | `search core --agent` bestMatch = **angular** (score 8) tied with **core** (score 8) because summary contains `@agentskit/core` | Boost exact `id` / path segment matches; prefer ownership id === term before body mentions |
+| **R2-2** | **`ask` suggests wrong handoff** | “where do I change the **core** package?” → best match **angular**, next `query ownership angular` | Same ranking fix; optional: prefer ownership over knowledge for “package/module” language |
+| **R2-3** | **Purpose/notes truncated mid-sentence** | core notes: `"Stable TypeScript contracts (Adapter, Tool, Memory, Retriever, Skill,"` | Raise firstParagraph budget; strip trailing incomplete commas; prefer frontmatter `purpose` full line |
+
+### P1 — install / peer DX
+
+| ID | Issue | Evidence | Suggested fix |
+|----|--------|----------|----------------|
+| **R2-4** | **Optional peers still break npm install** | registry: `ERESOLVE` with optional peers vs `@agentskit/adapters@0.12.x` | Peer ranges more permissive (`>=0.12` / `>=1.0`); document `--legacy-peer-deps`; ensure optional peers never hard-fail Layer 0 |
+| **R2-5** | **Peer `@agentskit/core@^1.10.0` vs monorepo 1.9.0** | pnpm warning on agentskit install | Align peer to `^1.9.0 \|\| ^1.10.0` or `>=1.9.0 <2` for dogfood until monorepo bumps |
+| **R2-6** | **`latest` still points at alpha.1** | `npm view` latest=alpha.1, alpha=alpha.2 | Publish hygiene: don’t put prereleases on `latest`, or retag after publish |
+| **R2-7** | **AKOS cannot `pnpm add` (store v10 vs v11)** | `ERR_PNPM_UNEXPECTED_STORE` | Docs: use npx / align store; not a doc-bridge bug but dogfood friction |
+
+### P2 — search / retrieval quality
+
+| ID | Issue | Evidence | Suggested fix |
+|----|--------|----------|----------------|
+| **R2-8** | **Search miss on common English** | agentskit `search documentation` → **0 matches** | Index more body text / titles; lower threshold; BM25 over full file not only description |
+| **R2-9** | **Playbook `search handoff` → 0** | term may only appear deep in body | Same as R2-8; chunk full markdown into search corpus |
+| **R2-10** | **Federation hard-fail noise** | `retrieve` → `Failed to fetch https://registry.agentskit.io/llms.txt: 404` | Soft-fail federation sources; warn once; don’t fail command |
+| **R2-11** | **Text search UX** | tab-separated dense lines | Columnar/TTY formatting (`type  id  path  summary`) |
+
+### P3 — bridge coverage & product polish
+
+| ID | Issue | Evidence | Suggested fix |
+|----|--------|----------|----------------|
+| **R2-12** | **AKOS humanDoc still sparse** | 9/92 handoffs with humanDoc | Map for-agents frontmatter `humanDoc`; product Fumadocs catalog; optional plain-markdown `docs/errors` etc. |
+| **R2-13** | **Duplicate knowledge+ownership rows in search** | same path appears as ownership + knowledge | Deduplicate by path; show ownership preferred |
+| **R2-14** | **Default checks for patterns without okf script** | N/A playbook ok | Fine; document convention |
+| **R2-15** | **MCP not re-smoked this round** | — | Keep in CI smoke; optional round 3 |
+
+---
+
+## Sample outputs (good)
+
+### agentskit — `query package core --agent`
+
+```json
+{
+  "startHere": "apps/docs-next/content/docs/for-agents/core.mdx",
+  "editRoots": ["packages/core"],
+  "checks": [
+    "pnpm --filter @agentskit/core test",
+    "pnpm --filter @agentskit/core lint"
+  ],
+  "humanDoc": "/docs/reference/packages/core"
+}
+```
+
+### playbook — pattern handoff
+
+```json
+{
+  "startHere": "content/docs/pillars/ai-collaboration/open-knowledge-format-pattern.md",
+  "checks": ["pnpm run check:okf-type"],
+  "humanDoc": "/docs/pillars/ai-collaboration/open-knowledge-format-pattern"
+}
+```
+
+### registry — `docs-chat`
+
+```json
+{
+  "startHere": "registry/docs-chat/README.md",
+  "editRoots": ["registry/docs-chat"],
+  "checks": ["npm run validate", "npm test"],
+  "humanDoc": "/agents/docs-chat"
+}
+```
+
+---
+
+## Recommended next alpha (0.1.0-alpha.3) scope
+
+1. **Ranking:** exact id / basename boost; package-intent heuristics for `ask`
+2. **Search corpus:** full-text over body (not only description); dedupe paths
+3. **Descriptions:** full purpose from frontmatter or first complete paragraph
+4. **Peers:** widen optional peer ranges; Layer 0 install never requires AgentsKit packages
+5. **Federation:** soft-fail missing `llms.txt` sources
+6. **Publish:** keep `latest` free of broken prereleases; doc install as `@alpha`
+
+---
+
+## Consumer follow-ups (not doc-bridge code)
+
+| Repo | Action |
+|------|--------|
+| agentskit | Bump `@agentskit/core` to 1.10+ or live with peer warning |
+| agentskit-os | Align pnpm store / commit lock with published dep; add CI `docs:bridge:gate` |
+| agents-playbook | Optional CI workflow for gate |
+| agentskit-registry | Publish `public/llms.txt` at site root (404 today); use `--legacy-peer-deps` until peer ranges loosen |
+| all | After alpha.3: switch dep to `@agentskit/doc-bridge@alpha` only |
+
+---
+
+## Conclusion
+
+**Round 2 proves Layer 0 is useful on real monorepos and OKF/registry corpora with the published package.**  
+The biggest remaining gap for “agents do the right thing” is **discovery ranking (R2-1/R2-2)** and **search body coverage (R2-8/R2-9)** — not indexing or handoff structure.

package/docs/DOGFOOD.md

@@ -0,0 +1,92 @@
+# 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
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentskit/doc-bridge",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.3",
   "description": "Human↔agent documentation bridge — deterministic handoffs, doc-site links, memory→docs, optional AgentsKit RAG/chat.",
   "type": "module",
   "bin": {
@@ -21,6 +21,7 @@
   "files": [
     "dist",
     "bin",
+    "scripts/prepare.mjs",
     "docs",
     "examples",
     "README.md",
@@ -28,7 +29,10 @@
     "SECURITY.md",
     "CODE_OF_CONDUCT.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "tsup.config.ts",
+    "tsconfig.json",
+    "src"
   ],
   "scripts": {
     "build": "tsup",
@@ -42,7 +46,9 @@
     "changeset": "changeset",
     "version-packages": "changeset version",
     "release": "pnpm build && pnpm test && changeset publish",
-    "prepublishOnly": "pnpm build && pnpm test"
+    "prepublishOnly": "pnpm build && pnpm test",
+    "prepare": "node scripts/prepare.mjs",
+    "prepack": "pnpm build"
   },
   "keywords": [
     "agentskit",
@@ -69,20 +75,32 @@
     "zod": "^3.24.2"
   },
   "peerDependencies": {
-    "@agentskit/adapters": "^0.13.0",
-    "@agentskit/core": "^1.10.0",
-    "@agentskit/ink": "^0.9.0",
-    "@agentskit/memory": "^0.10.0",
-    "@agentskit/rag": "^0.4.0",
+    "@agentskit/adapters": ">=0.12.0 <1",
+    "@agentskit/core": ">=1.0.0 <2",
+    "@agentskit/ink": ">=0.8.0 <1",
+    "@agentskit/memory": ">=0.9.0 <1",
+    "@agentskit/rag": ">=0.3.0 <1",
     "react": ">=18.0.0"
   },
   "peerDependenciesMeta": {
-    "@agentskit/adapters": { "optional": true },
-    "@agentskit/core": { "optional": true },
-    "@agentskit/ink": { "optional": true },
-    "@agentskit/memory": { "optional": true },
-    "@agentskit/rag": { "optional": true },
-    "react": { "optional": true }
+    "@agentskit/adapters": {
+      "optional": true
+    },
+    "@agentskit/core": {
+      "optional": true
+    },
+    "@agentskit/ink": {
+      "optional": true
+    },
+    "@agentskit/memory": {
+      "optional": true
+    },
+    "@agentskit/rag": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.0",

package/scripts/prepare.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * Ensure dist/ exists for git installs and local clones.
+ * Published npm tarballs already include dist/ — this is a no-op then.
+ */
+import { existsSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const marker = join(root, 'dist', 'cli', 'program.js')
+
+if (existsSync(marker)) {
+  process.exit(0)
+}
+
+const attempts = [
+  ['pnpm', ['exec', 'tsup']],
+  ['npx', ['--yes', 'tsup@8.5.1']],
+  ['npm', ['exec', '--', 'tsup']],
+]
+
+let ok = false
+for (const [cmd, args] of attempts) {
+  const result = spawnSync(cmd, args, {
+    cwd: root,
+    stdio: 'inherit',
+    env: process.env,
+    shell: process.platform === 'win32',
+  })
+  if (result.status === 0 && existsSync(marker)) {
+    ok = true
+    break
+  }
+}
+
+if (!ok) {
+  process.stderr.write(
+    '[@agentskit/doc-bridge] prepare: could not build dist/. Run: pnpm build (or npm run build)\n',
+  )
+  // Don't fail install of dependents hard when used as file: link with prebuilt dist elsewhere
+  process.exit(0)
+}