@agentskit/doc-bridge 0.1.0-alpha.1

package/docs/spec/registry-agents.md

@@ -0,0 +1,65 @@
+# Registry Agent Topology
+
+doc-bridge exposes deterministic tools; Registry agents can compose them into maintenance flows.
+
+## `doc-curator`
+
+Supervisor flow:
+
+```yaml
+id: doc-curator
+version: 1
+description: Classify documentation changes, draft updates, and verify gates.
+inputs:
+  diff:
+    type: string
+  projectRoot:
+    type: string
+tools:
+  - doc-bridge.mcp.handoff.resolve
+  - doc-bridge.mcp.doc.search
+  - doc-bridge.mcp.doc.get
+  - doc-bridge.mcp.gate.status
+delegates:
+  docsChat:
+    agent: docs-chat
+    purpose: Answer grounded questions using deterministic search first.
+  knowledgePromoter:
+    agent: knowledge-promoter
+    purpose: Convert accepted findings into draft documentation changes.
+  codeReview:
+    agent: code-review
+    purpose: Review doc-only diffs before human merge.
+steps:
+  - id: classify
+    delegate: docsChat
+    input:
+      question: "Which docs and owners are affected by this diff?"
+  - id: draft
+    delegate: knowledgePromoter
+    input:
+      finding: "${classify.output}"
+      mode: draft-pr
+  - id: verify
+    tool: doc-bridge.mcp.gate.status
+    input:
+      gates:
+        - index-freshness
+        - human-guide-links
+        - okf-type
+  - id: review
+    delegate: codeReview
+    input:
+      diff: "${draft.diff}"
+mergePolicy:
+  autoMerge: false
+  requiresHuman: true
+```
+
+## Runtime Notes
+
+- The MCP server is local: `ak-docs mcp`.
+- The flow must not require a private repository shape.
+- `knowledge-promoter` may draft PR content, but must never merge.
+- `code-review` runs after gates so reviewers see deterministic failures first.
+- Future RAG mode should inject `createDocBridgeRetriever(index)` and keep exact handoff resolution ahead of semantic results.

package/examples/docusaurus-only.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from '@agentskit/doc-bridge'
+
+/** Docusaurus bridge only: no chat, no memory, no provider key. */
+export default defineConfig({
+  schemaVersion: 1,
+  corpus: {
+    agent: { root: 'docs/for-agents' },
+    human: {
+      plugin: 'docusaurus',
+      options: {
+        docsDir: 'website/docs',
+        sidebarsFile: 'website/sidebars.js',
+        urlPrefix: '/docs',
+      },
+    },
+  },
+  gates: { preset: 'standard' },
+})

package/examples/docusaurus-with-memory.config.ts

@@ -0,0 +1,37 @@
+import { defineConfig } from '@agentskit/doc-bridge'
+
+/** Assisted profile: Docusaurus + memory ingest + classification (opt-in, HITL) */
+export default defineConfig({
+  schemaVersion: 1,
+  corpus: {
+    agent: { root: '.agent-docs' },
+    human: {
+      plugin: 'docusaurus',
+      options: {
+        docsDir: 'website/docs',
+        sidebarsFile: 'website/sidebars.js',
+        urlPrefix: '/docs',
+      },
+    },
+  },
+  intelligence: {
+    enabled: true,
+    adapter: {
+      provider: 'openrouter',
+      model: 'openai/gpt-4o-mini',
+      apiKeyEnv: 'OPENROUTER_API_KEY',
+    },
+    chat: { enabled: true, sources: ['agent', 'human'] },
+    memory: {
+      enabled: true,
+      adapters: ['cursor-rules', 'playbook-memory'],
+      classify: true,
+      promote: {
+        enabled: true,
+        targets: ['agent', 'human'],
+        requireApproval: true,
+      },
+    },
+    runtime: 'agentskit',
+  },
+})

package/examples/fumadocs-only.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from '@agentskit/doc-bridge'
+
+/** Fumadocs bridge only: no chat, no memory, no provider key. */
+export default defineConfig({
+  schemaVersion: 1,
+  corpus: {
+    agent: { root: 'docs/for-agents' },
+    human: {
+      plugin: 'fumadocs',
+      options: {
+        contentDir: 'apps/web/content/docs',
+        urlPrefix: '/docs',
+        metaFile: 'meta.json',
+      },
+    },
+  },
+  gates: { preset: 'standard' },
+})

package/examples/fumadocs-with-chat.config.ts

@@ -0,0 +1,42 @@
+import { defineConfig } from '@agentskit/doc-bridge'
+
+/**
+ * Standard profile: monorepo + Fumadocs human bridge + Layer 1 chat/RAG.
+ * Requires optional peers:
+ *   npm i -D @agentskit/rag @agentskit/ink @agentskit/adapters @agentskit/memory react
+ * Then: ak-docs index && ak-docs rag ingest && ak-docs chat
+ */
+export default defineConfig({
+  schemaVersion: 1,
+  corpus: {
+    agent: { root: 'docs/for-agents' },
+    human: {
+      plugin: 'fumadocs',
+      options: {
+        contentDir: 'apps/web/content/docs',
+        urlPrefix: '/docs',
+        metaFile: 'meta.json',
+      },
+    },
+  },
+  routing: { plugin: 'pnpm-monorepo' },
+  gates: { preset: 'standard' },
+  intelligence: {
+    enabled: true,
+    adapter: {
+      provider: 'ollama',
+      model: 'llama3.2',
+      apiKeyEnv: '', // local — no cloud key
+    },
+    chat: {
+      enabled: true,
+      sources: ['agent', 'human'],
+      handoffFirst: true,
+    },
+    retriever: {
+      enabled: true,
+      mode: 'agentskit-rag',
+    },
+    runtime: 'agentskit',
+  },
+})

package/examples/minimal-plain-markdown.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from '@agentskit/doc-bridge'
+
+/** Solo project — Layer 0 only, no LLM, no monorepo plugin */
+export default defineConfig({
+  schemaVersion: 1,
+  corpus: {
+    agent: {
+      root: 'docs',
+      index: 'docs/INDEX.md',
+    },
+  },
+  gates: { preset: 'minimal' },
+})

package/examples/pnpm-monorepo.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from '@agentskit/doc-bridge'
+
+/** Monorepo — ownership routing, standard gates, still no LLM */
+export default defineConfig({
+  schemaVersion: 1,
+  corpus: {
+    agent: { root: 'docs/for-agents' },
+  },
+  routing: {
+    plugin: 'pnpm-monorepo',
+    options: {
+      packages: ['packages/*', 'apps/*'],
+    },
+  },
+  gates: { preset: 'standard' },
+  surfaces: {
+    mcp: { enabled: true, tools: ['handoff.resolve', 'doc.search', 'doc.get'] },
+  },
+})

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@agentskit/doc-bridge",
+  "version": "0.1.0-alpha.1",
+  "description": "Human↔agent documentation bridge — deterministic handoffs, doc-site links, memory→docs, optional AgentsKit RAG/chat.",
+  "type": "module",
+  "bin": {
+    "ak-docs": "bin/ak-docs.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "bin",
+    "docs",
+    "examples",
+    "README.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CODE_OF_CONDUCT.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "smoke:packaged": "node scripts/smoke-packaged.mjs",
+    "smoke:docsites": "node scripts/smoke-docsites.mjs",
+    "smoke:real-docsites": "node scripts/smoke-real-docsites.mjs",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "pnpm build && pnpm test && changeset publish",
+    "prepublishOnly": "pnpm build && pnpm test"
+  },
+  "keywords": [
+    "agentskit",
+    "documentation",
+    "mcp",
+    "for-agents",
+    "llms-txt",
+    "agent-handoff",
+    "rag",
+    "human-agent-bridge"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgentsKit-io/doc-bridge.git"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "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",
+    "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 }
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.31.0",
+    "@types/node": "^22.15.3",
+    "@vitest/coverage-v8": "4.1.10",
+    "tsup": "^8.5.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  },
+  "directories": {
+    "doc": "docs",
+    "example": "examples",
+    "test": "tests"
+  },
+  "author": "AgentsKit",
+  "bugs": {
+    "url": "https://github.com/AgentsKit-io/doc-bridge/issues"
+  },
+  "homepage": "https://github.com/AgentsKit-io/doc-bridge#readme"
+}