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

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.2",
   "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": "npm run build && npm test",
+    "prepare": "node scripts/prepare.mjs",
+    "prepack": "npm run build"
   },
   "keywords": [
     "agentskit",
@@ -77,12 +83,24 @@
     "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)
+}