@agentskit/doc-bridge 1.2.6 → 1.4.0

package/docs/MARKETPLACE.md

@@ -21,7 +21,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: AgentsKit-io/doc-bridge@v1.2.1
+      - uses: AgentsKit-io/doc-bridge@v1.3.0
         with:
           config-path: doc-bridge.config.json
 ```

package/docs/POSITIONING.md

@@ -70,7 +70,7 @@ Engineering teams with real ownership (monorepos first). Secondary: solo libs, i
 
 ```
 required:  index, CLI, MCP handoff tools, gate presets
-optional:  fumadocs | docusaurus | plain-markdown plugins
+optional:  fumadocs | docusaurus | vitepress | starlight | nextra | plain-markdown plugins
 optional:  memory ingest → promote
 optional:  @agentskit/rag + ink chat (intelligence.*)
 optional:  Playbook / Registry federation

package/docs/examples.md

@@ -11,8 +11,12 @@ Config sketches under [`examples/`](../examples/):
 |------|---------|
 | `minimal-plain-markdown.config.ts` | Solo markdown, Layer 0 only |
 | `pnpm-monorepo.config.ts` | Workspace discovery + ownership |
+| `nx-monorepo.config.ts` | Static Nx project discovery + inferred checks |
 | `fumadocs-only.config.ts` | Human bridge via Fumadocs |
 | `docusaurus-only.config.ts` | Human bridge via Docusaurus |
+| `vitepress-only.config.ts` | Human bridge via VitePress |
+| `starlight-only.config.ts` | Human bridge via Astro Starlight |
+| `nextra-only.config.ts` | Human bridge via Nextra |
 | `fumadocs-with-chat.config.ts` | Standard + intelligence (AgentsKit peers) |
 | `docusaurus-with-memory.config.ts` | Assisted memory promotion path |
 

package/docs/getting-started.md

@@ -105,7 +105,7 @@ Tools: `handoff.resolve`, `doc.search`, `doc.get`, `gate.status`, …
 ## Human ↔ agent bridge
 
 ```bash
-# After configuring corpus.human (fumadocs | docusaurus | plain-markdown)
+# After configuring corpus.human (fumadocs | docusaurus | vitepress | starlight | nextra | plain-markdown)
 ak-docs index
 ak-docs query package <id> --agent   # includes humanDoc when linked
 ak-docs gate run human-guide-links

package/docs/guides/choose-context-layer.md

@@ -0,0 +1,129 @@
+---
+title: Choose the right context layer
+description: Decide when an agent needs repository rules, deterministic routing, code search, RAG, or human review.
+---
+
+# Choose the right context layer
+
+Coding agents rarely fail because a repository has no context. They fail because the right context arrives too late, or because several different kinds of context are treated as interchangeable.
+
+`AGENTS.md`, Doc Bridge, code search, RAG, and human review solve different problems. The most reliable workflow composes them in that order instead of asking one layer to do every job.
+
+## The short version
+
+| Layer | Best question | Use it for | Do not rely on it for |
+| --- | --- | --- | --- |
+| `AGENTS.md` | What rules apply here? | Repository-wide invariants, conventions, safety rules, and workflow expectations | Selecting the owner of every task in a large monorepo |
+| Doc Bridge | Where does this task belong? | Deterministic ownership, starting docs, declared edit roots, package checks, and matching human docs | Explaining every implementation detail or enforcing filesystem permissions |
+| Code search | Where is this exact thing used? | Symbols, imports, references, call sites, and concrete strings | Deciding ownership from similarity alone |
+| RAG | What broader context may be relevant? | Design history, migrations, scattered documentation, and open-ended questions | Overriding an explicit ownership contract |
+| Human review | Is this boundary still correct? | Ambiguous, cross-cutting, security-sensitive, or high-impact decisions | Routine routing that the repository can declare and test |
+
+## Start with repository rules
+
+An `AGENTS.md` file is the right place for rules that should survive individual tasks:
+
+- required coding conventions;
+- security and privacy constraints;
+- commands that must run before a change is accepted;
+- architectural invariants;
+- contribution and release expectations.
+
+Doc Bridge does not replace those rules. A handoff can include `AGENTS.md` in `readBeforeEditing`, then narrow the task to the package-specific material that matters.
+
+## Use Doc Bridge for deterministic routing
+
+When the repository already knows which package owns authentication, the agent should not infer ownership from filenames or semantic similarity. Resolve a handoff first:
+
+```bash
+ak-docs query package auth --agent
+```
+
+A useful handoff answers four operational questions:
+
+```json
+{
+  "startHere": "docs/for-agents/packages/auth.md",
+  "editRoots": ["packages/auth"],
+  "checks": [
+    "pnpm --filter @example/auth test",
+    "pnpm --filter @example/auth lint"
+  ],
+  "humanDoc": "docs/guides/auth.md"
+}
+```
+
+This is intentionally smaller than a repository dump. It gives the agent an explicit starting point, declared scope, evidence to run, and a human-facing description of the same feature.
+
+`editRoots` is a routing and audit contract. It does not create an operating-system sandbox by itself. If a workflow must technically prevent writes outside those roots, enforce that boundary with the agent runner, sandbox, permissions, or CI policy.
+
+## Search after scope is known
+
+Code search is strongest after the owner is resolved. Inside the intended scope, use it to find:
+
+- the implementation of a symbol;
+- all imports of an adapter;
+- tests for an error code;
+- callers affected by a signature change.
+
+Search can reveal that a task is genuinely cross-cutting. When it does, expand the declared handoff or ask for human review. Do not quietly turn a package-scoped change into a repository-wide edit.
+
+## Add RAG for open-ended context
+
+RAG is useful when the question does not have one exact answer:
+
+- Why did the authentication design change?
+- Which migration notes mention token rotation?
+- What guidance exists for moving from one provider to another?
+
+That context can improve the implementation, but it should expand a deterministic handoff rather than replace one. Similar documents are evidence, not ownership.
+
+Doc Bridge keeps this distinction explicit: Layer 0 indexing and handoffs work offline without a model or API key; RAG and chat are optional intelligence layers.
+
+## Escalate ambiguity to a human
+
+Some changes should not be forced into a convenient directory. Ask for human review when:
+
+- multiple packages legitimately own part of the change;
+- a public contract or security boundary may change;
+- the handoff conflicts with the current repository shape;
+- checks are missing or no longer prove the behavior;
+- the cost of a wrong boundary is high.
+
+A useful routing system should make uncertainty visible. It should not produce false confidence when the repository has not declared an answer.
+
+## Recommended order
+
+```text
+resolve handoff
+  → read AGENTS.md and startHere
+  → search exact code inside the declared scope
+  → retrieve broader context when needed
+  → edit the intended roots
+  → run the declared checks
+  → request human review for unresolved boundaries
+```
+
+For an existing repository, the smallest adoption path is:
+
+```bash
+npm install --save-dev @agentskit/doc-bridge@1.2.6
+npx ak-docs init
+npx ak-docs index
+npx ak-docs query package example --agent
+npx ak-docs gate run
+```
+
+The gate makes drift visible when ownership inputs or linked documentation change without a refreshed index. That keeps the routing contract reviewable instead of silently rebuilding it during validation.
+
+## A practical decision rule
+
+If the question begins with **must**, put the invariant in repository instructions. If it begins with **where**, resolve a Doc Bridge handoff. If it begins with **which exact reference**, search the code. If it begins with **why** or **what else**, retrieve broader context. If the answers disagree, stop and ask a human.
+
+## Related
+
+- [Index and query](./index-and-query.md)
+- [For agents](../for-agents.md)
+- [Chat and RAG](../chat-and-rag.md)
+- [Gate in CI](./gate-ci.md)
+- [AgentHandoff schema](../schemas/agent-handoff-v1.md)

package/docs/guides/gate-ci.md

@@ -38,7 +38,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: AgentsKit-io/doc-bridge@v1.2.1
+      - uses: AgentsKit-io/doc-bridge@v1.3.0
         with:
           config-path: doc-bridge.config.json
 ```

package/docs/guides/meta.json

@@ -3,6 +3,7 @@
   "pages": [
     "install-and-run",
     "index-and-query",
+    "choose-context-layer",
     "gate-ci",
     "mcp-agents",
     "memory-pipeline",

package/docs/landing/index.html

@@ -272,7 +272,7 @@
             <tr><td>CLI</td><td>Query ownership, inspect handoffs, run doctor, search docs.</td><td><code>ak-docs query package auth --agent</code></td></tr>
             <tr><td>MCP</td><td>Lets Cursor, Claude Code, and Codex-style agents resolve before editing.</td><td><code>ak-docs mcp install --cursor</code></td></tr>
             <tr><td>CI</td><td>Blocks stale indexes and broken human-doc bridges.</td><td><code>ak-docs index && ak-docs gate run</code></td></tr>
-            <tr><td>Adapters</td><td>Connect Fumadocs, Docusaurus, plain markdown, and pnpm workspaces.</td><td><code>fumadocs</code> · <code>docusaurus</code> · <code>plain-markdown</code></td></tr>
+            <tr><td>Adapters</td><td>Connect Fumadocs, Docusaurus, VitePress, Starlight, Nextra, plain markdown, and pnpm workspaces.</td><td><code>fumadocs</code> · <code>docusaurus</code> · <code>vitepress</code> · <code>starlight</code> · <code>nextra</code> · <code>plain-markdown</code></td></tr>
             <tr><td>Memory pipeline</td><td>Classifies local agent memory and drafts documentation updates.</td><td><code>ak-docs memory promote --pr</code></td></tr>
             <tr><td>Optional RAG/chat</td><td>Adds handoff-first chat when you install AgentsKit peers.</td><td><code>ak-docs rag ingest && ak-docs chat</code></td></tr>
           </tbody>
@@ -337,7 +337,7 @@
           <div class="terminal-bar"><span class="dot dot-r"></span><span class="dot dot-y"></span><span class="dot dot-g"></span></div>
           <div class="terminal-body">
             <div class="t-dim"># .github/workflows/pr.yml</div>
-            <div>- uses: <span class="t-hi">AgentsKit-io/doc-bridge@v1.2.1</span></div>
+            <div>- uses: <span class="t-hi">AgentsKit-io/doc-bridge@v1.3.0</span></div>
             <div>&nbsp;&nbsp;with:</div>
             <div>&nbsp;&nbsp;&nbsp;&nbsp;config-path: doc-bridge.config.json</div>
           </div>

package/docs/playbook/doc-bridge-pattern.md

@@ -77,7 +77,7 @@ Agents call `handoff.resolve` before editing `packages/*`:
 ## CI gate
 
 ```yaml
-- uses: AgentsKit-io/doc-bridge@v1.2.1
+- uses: AgentsKit-io/doc-bridge@v1.3.0
 ```
 
 Or: `ak-docs index && ak-docs gate run` — stale index fails the PR.

package/docs/qa/vitepress-starlight-adapters.md

@@ -0,0 +1,19 @@
+# VitePress and Starlight adapter QA plan
+
+This plan records the local acceptance criteria for the first-party VitePress and Astro Starlight human-documentation adapters.
+
+## Contract checks
+
+- A VitePress corpus scans Markdown and MDX below its configured documentation root, maps `index` files to their directory route, follows the framework's default `.html` routes or optional `cleanUrls`, applies declarative `srcExclude` globs, respects an optional `urlPrefix`, and keeps Doc Bridge join metadata (`package`, `module`, or `id`) stable.
+- A Starlight corpus scans Markdown and MDX below its configured content root, uses Astro's optional `slug` frontmatter for the public route, maps index pages correctly, respects an optional `urlPrefix`, and keeps Doc Bridge join metadata stable.
+- Both adapters reject roots outside the project through the shared bounded, containment-aware scanner.
+- Neither adapter executes framework configuration or user JavaScript.
+- Existing Fumadocs, Docusaurus, and plain-Markdown behavior remains unchanged.
+
+## Local verification
+
+1. Add focused fixtures for default routes, index routes, metadata overrides, URL prefixes, and nested agent-corpus exclusion.
+2. Run `pnpm vitest run tests/human-adapters.test.ts tests/schemas.test.ts`.
+3. Run `pnpm typecheck` and `pnpm build` to validate the public configuration type and emitted declarations.
+4. Run the complete `pnpm test` suite to detect regressions.
+5. Run `git diff --check` and inspect the final diff for scope and generated-file noise.

package/docs/recipes/index-pipeline.md

@@ -71,7 +71,7 @@ Root `package.json`:
 ## CI (GitHub Action)
 
 ```yaml
-- uses: AgentsKit-io/doc-bridge@v1.2.1
+- uses: AgentsKit-io/doc-bridge@v1.3.0
 ```
 
 Or manual:

package/docs/spec/config-v1.md

@@ -129,10 +129,34 @@ type HumanCorpusPluginId =
   | 'fumadocs'          // markdown scan with index routes, (group) slugs, pages allowlists
   | 'docusaurus'        // markdown scan with id/slug frontmatter + static sidebars.js
   | 'mkdocs'            // planned
-  | 'vitepress'         // planned
+  | 'vitepress'         // file routes, srcDir/docsDir, optional cleanUrls
+  | 'starlight'         // Astro content routes, slug and draft frontmatter
+  | 'nextra'            // content-directory routes and contentDirBasePath
   | 'custom'            // path to user plugin module
 ```
 
+VitePress options accept `docsDir` (also `root` or `srcDir`), `urlPrefix`,
+`cleanUrls`, and up to 64 declarative `srcExclude` glob patterns. Doc Bridge
+uses `.html` routes unless `cleanUrls: true`, matching
+VitePress routing without loading or executing `.vitepress/config.*`. Route
+rewrites must therefore be reflected in the configured corpus or URL prefix.
+
+Starlight options accept `contentDir` (also `docsDir` or `root`) and
+`urlPrefix`. The adapter reads the standard `slug` and `draft` frontmatter,
+follows the default filename sluggifier, excludes underscore-prefixed
+partials, and never executes `astro.config.*`. Sites using a custom
+`docsLoader({ generateId })` should add explicit `slug` frontmatter so Doc
+Bridge can resolve the same public route without executing project code.
+
+Nextra options accept `contentDir` (also `docsDir` or `root`), `urlPrefix`,
+and `contentDirBasePath`. The adapter maps `index.md` and `index.mdx` to the
+containing route and uses Doc Bridge `package`, `module`, or `id` frontmatter
+as the join key. `urlPrefix` takes precedence over `contentDirBasePath`. Point
+`contentDir` at either `content` or `src/content`; Doc Bridge never imports or
+executes `next.config.*`, `_meta.*`, themes, or other project code. This
+adapter targets Nextra's content-directory convention; app-router `page.mdx`
+trees are not inferred by this plugin.
+
 ### Bridge to agent docs
 
 When `corpus.human` is set, plugins MUST:
@@ -199,7 +223,7 @@ Without `routing`, handoffs are inferred from agent corpus links only. Monorepo
 
 ```ts
 type RoutingConfig = {
-  plugin?: 'pnpm-monorepo' | 'npm-workspaces' | 'yarn-workspaces' | 'custom'
+  plugin?: 'pnpm-monorepo' | 'npm-workspaces' | 'yarn-workspaces' | 'nx' | 'pattern-files' | 'custom'
 
   options?: {
     /** Workspace globs; default from package manager */
@@ -240,6 +264,13 @@ type ChangeRouteEntry = {
 }
 ```
 
+`routing.plugin: 'nx'` reads `project.json` and package manifests with an `nx`
+object. It does not load Nx plugins or execute workspace code. Project roots must
+resolve inside the configured project root. Declared `test` targets become Nx test
+checks; non-minimal gate presets also include declared `lint` targets. Explicit
+`routing.options.ownership` remains authoritative. Targets created only at runtime
+by Nx plugins are intentionally not inferred by this read-only adapter.
+
 ### Join keys (agent ↔ human ↔ ownership)
 
 | Entity | Primary key | Human plugin maps via |

package/examples/nextra-only.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from '@agentskit/doc-bridge'
+
+/** Nextra bridge only: no chat, no memory, no provider key. */
+export default defineConfig({
+  schemaVersion: 1,
+  corpus: {
+    agent: { root: 'docs/for-agents' },
+    human: {
+      plugin: 'nextra',
+      options: {
+        contentDir: 'content',
+        contentDirBasePath: '/docs',
+      },
+    },
+  },
+  gates: { preset: 'standard' },
+})

package/examples/nx-monorepo.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from '@agentskit/doc-bridge'
+
+/** Nx — infer project ownership and available test/lint checks without executing Nx */
+export default defineConfig({
+  schemaVersion: 1,
+  corpus: {
+    agent: { root: 'docs/for-agents' },
+  },
+  routing: { plugin: 'nx' },
+  gates: { preset: 'standard' },
+})

package/examples/starlight-only.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from '@agentskit/doc-bridge'
+
+/** Starlight bridge only: no chat, no memory, no provider key. */
+export default defineConfig({
+  schemaVersion: 1,
+  corpus: {
+    agent: { root: 'docs/for-agents' },
+    human: {
+      plugin: 'starlight',
+      options: {
+        contentDir: 'src/content/docs',
+        urlPrefix: '/docs',
+      },
+    },
+  },
+  gates: { preset: 'standard' },
+})

package/examples/vitepress-only.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from '@agentskit/doc-bridge'
+
+/** VitePress bridge only: no chat, no memory, no provider key. */
+export default defineConfig({
+  schemaVersion: 1,
+  corpus: {
+    agent: { root: 'docs/for-agents' },
+    human: {
+      plugin: 'vitepress',
+      options: {
+        docsDir: 'docs',
+        urlPrefix: '/docs',
+        cleanUrls: true,
+        srcExclude: ['archive/**'],
+      },
+    },
+  },
+  gates: { preset: 'standard' },
+})

package/mcpb/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "doc-bridge",
   "display_name": "Doc Bridge",
-  "version": "1.2.6",
+  "version": "1.4.0",
   "description": "Deterministic repository handoffs for coding agents, running locally without an LLM or API key.",
   "long_description": "Doc Bridge turns a repository's own documentation and ownership metadata into deterministic handoffs: where an agent should start, which paths it may edit, which checks it must run, and when a human must take over. The local connector exposes the same read-only contract available through Doc Bridge CLI and CI.",
   "author": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentskit/doc-bridge",
-  "version": "1.2.6",
+  "version": "1.4.0",
   "mcpName": "io.github.AgentsKit-io/doc-bridge",
   "description": "Human↔agent documentation bridge — deterministic handoffs, doc-site links, memory→docs, optional AgentsKit RAG/chat.",
   "type": "module",
@@ -40,12 +40,13 @@
     "mcpb",
     "tsup.config.ts",
     "tsconfig.json",
-    "src"
+    "src",
+    "skills"
   ],
   "scripts": {
     "prebuild": "node scripts/sync-version.mjs",
     "build": "tsup",
-    "test": "vitest run",
+    "test": "vitest run && pnpm test:cursor-plugin && pnpm test:portable-skill",
     "test:watch": "vitest",
     "coverage": "vitest run --coverage",
     "check:ecosystem-upstream": "node scripts/check-ecosystem-upstream.mjs",
@@ -60,6 +61,8 @@
     "mcpb:smoke": "node scripts/smoke-mcpb.mjs",
     "mcpb:pack": "npm run mcpb:stage && npm run mcpb:smoke && node scripts/build-mcpb.mjs pack",
     "test:mcpb": "node --test scripts/mcpb-contract.test.mjs",
+    "test:cursor-plugin": "node --test scripts/cursor-plugin-contract.test.mjs",
+    "test:portable-skill": "node --test scripts/portable-skill-contract.test.mjs",
     "coverage:badge": "node scripts/update-coverage-badge.mjs",
     "changeset": "changeset",
     "version-packages": "changeset version && node scripts/sync-version.mjs",
@@ -85,12 +88,18 @@
     "agentskit",
     "documentation",
     "mcp",
+    "pi-package",
     "for-agents",
     "llms-txt",
     "agent-handoff",
     "rag",
     "human-agent-bridge"
   ],
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -103,7 +112,9 @@
     "access": "public"
   },
   "dependencies": {
-    "mermaid": "^11.16.0",
+    "github-slugger": "^2.0.0",
+    "mermaid": "^11.16.1",
+    "minimatch": "^10.2.6",
     "zod": "^3.24.2"
   },
   "peerDependencies": {

package/skills/doc-bridge-handoff/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: doc-bridge-handoff
+description: Resolve Doc Bridge boundaries before changing code.
+version: 1.0.0
+author: AgentsKit
+license: MIT
+platforms:
+  - darwin
+  - linux
+  - windows
+metadata:
+  hermes:
+    tags:
+      - documentation
+      - coding-agents
+      - repository-routing
+---
+
+# Doc Bridge handoff
+
+Use this skill before editing a repository that contains `doc-bridge.config.json`.
+
+1. Resolve the package or ownership id that best matches the requested change:
+   - Prefer the read-only MCP tool `handoff.resolve` when it is available.
+   - Otherwise run `node <skill-directory>/scripts/resolve-handoff.mjs <id>` from the repository.
+2. Read every file in `readBeforeEditing`, beginning with `startHere`.
+3. Keep changes inside `editRoots`. If the requested path is not covered, stop and report the missing route instead of guessing.
+4. Make the smallest change that satisfies the request.
+5. Run every command in `checks` before claiming completion.
+6. If documentation changed, refresh the Doc Bridge index and run its gate.
+
+If resolution fails, returns incomplete fields, or names an unknown target, stop. Do not infer edit permission from repository layout.
+
+The resolver and MCP tools are read-only. They resolve project guidance but never authorize edits, publish changes, execute returned checks, or replace repository instructions. The skill uses no credentials and has no provider, hosted service, or AKOS dependency.
+
+## Portable runtimes
+
+This directory follows the open Agent Skills layout: one `SKILL.md` plus optional scripts and fixtures. It can be loaded as a local skill by OpenClaw-compatible clients, Hermes Agent, Pi, Cursor, or another runtime that supports Agent Skills and shell execution. Runtime-specific publication metadata is intentionally kept outside the skill.

package/skills/doc-bridge-handoff/fixtures/synthetic-repo/doc-bridge.config.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "corpus": {
+    "agent": {
+      "root": "docs/for-agents"
+    }
+  },
+  "routing": {
+    "options": {
+      "ownership": {
+        "payments": {
+          "path": "packages/payments",
+          "purpose": "Synthetic package used only to verify portable handoff routing",
+          "checks": ["npm test -- payments"],
+          "agentDoc": "docs/for-agents/packages/payments.md"
+        }
+      }
+    }
+  },
+  "gates": {
+    "preset": "minimal"
+  }
+}

package/skills/doc-bridge-handoff/fixtures/synthetic-repo/docs/for-agents/packages/payments.md

@@ -0,0 +1,5 @@
+# Payments package
+
+This is public synthetic guidance for the portable skill compatibility test.
+
+Only edit `packages/payments` and run the checks returned by Doc Bridge.

package/skills/doc-bridge-handoff/fixtures/synthetic-repo/packages/payments/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "synthetic-payments",
+  "private": true
+}

package/skills/doc-bridge-handoff/scripts/resolve-handoff.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process'
+import { isAbsolute } from 'node:path'
+
+const VERSION = '1.4.0'
+const kinds = new Set(['package', 'ownership'])
+const args = process.argv.slice(2)
+const id = args[0]
+const kindFlag = args.indexOf('--kind')
+const configFlag = args.indexOf('--config')
+const kind = kindFlag === -1 ? 'package' : args[kindFlag + 1]
+const config = configFlag === -1 ? undefined : args[configFlag + 1]
+
+const fail = (message) => {
+  process.stderr.write(`Doc Bridge handoff blocked: ${message}\n`)
+  process.exit(1)
+}
+
+if (!id || id.startsWith('--') || /[\u0000-\u001f\u007f]/u.test(id)) {
+  fail('provide a package or ownership id')
+}
+if (!kind || !kinds.has(kind)) fail('--kind must be package or ownership')
+if (configFlag !== -1 && (!config || config.startsWith('--'))) fail('--config requires a path')
+
+const queryArgs = ['query', kind, id, '--agent']
+if (config) queryArgs.push('--config', config)
+
+const localBin = process.env.DOC_BRIDGE_BIN
+const command = localBin ? process.execPath : 'npx'
+const commandArgs = localBin
+  ? [localBin, ...queryArgs]
+  : ['-y', `@agentskit/doc-bridge@${VERSION}`, ...queryArgs]
+const result = spawnSync(command, commandArgs, {
+  cwd: process.cwd(),
+  encoding: 'utf8',
+  timeout: 60_000,
+  maxBuffer: 1024 * 1024,
+})
+
+if (result.error) fail(result.error.message)
+if (result.status !== 0) fail(result.stderr.trim() || `resolver exited with status ${result.status}`)
+
+let handoff
+try {
+  handoff = JSON.parse(result.stdout)
+} catch {
+  fail('resolver returned invalid JSON')
+}
+
+const nonEmptyStrings = (value) =>
+  Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === 'string' && item.trim())
+const safeRelativePath = (value) => {
+  if (typeof value !== 'string' || !value.trim() || isAbsolute(value)) return false
+  if (/^(?:[a-z]:[\\/]|\\\\)/iu.test(value)) return false
+  return !value.split(/[\\/]+/u).includes('..')
+}
+
+if (handoff?.target?.id !== id) fail('resolver returned a different target')
+if (!safeRelativePath(handoff.startHere)) fail('startHere is missing or unsafe')
+if (!nonEmptyStrings(handoff.readBeforeEditing) || !handoff.readBeforeEditing.every(safeRelativePath)) {
+  fail('readBeforeEditing is missing or unsafe')
+}
+if (!handoff.readBeforeEditing.includes(handoff.startHere)) fail('readBeforeEditing omits startHere')
+if (!nonEmptyStrings(handoff.editRoots) || !handoff.editRoots.every(safeRelativePath)) {
+  fail('editRoots is missing or unsafe')
+}
+if (!nonEmptyStrings(handoff.checks)) fail('checks are missing')
+
+process.stdout.write(`${JSON.stringify(handoff, null, 2)}\n`)

package/src/config/schema.ts

@@ -8,6 +8,8 @@ export const HumanCorpusPluginIdSchema = z.enum([
   'docusaurus',
   'mkdocs',
   'vitepress',
+  'starlight',
+  'nextra',
   'custom',
 ])
 
@@ -71,7 +73,7 @@ export const OwnershipEntrySchema = z
 export const RoutingConfigSchema = z
   .object({
     plugin: z
-      .enum(['pnpm-monorepo', 'npm-workspaces', 'yarn-workspaces', 'pattern-files', 'custom'])
+      .enum(['pnpm-monorepo', 'npm-workspaces', 'yarn-workspaces', 'nx', 'pattern-files', 'custom'])
       .optional(),
     options: z
       .object({

package/src/index-builder/build-handoffs.ts

@@ -70,6 +70,7 @@ export const collectPackages = (
       id: pkg.id,
       path: existing.path || pkg.path,
       ...(pkg.name ? { name: pkg.name } : existing.name ? { name: existing.name } : {}),
+      ...(pkg.checks ? { checks: pkg.checks } : existing.checks ? { checks: existing.checks } : {}),
     })
   }
 
@@ -163,6 +164,7 @@ export const buildLookup = (
     const checks = [
       ...(override?.checks ??
         fm?.checks ??
+        pkg.checks ??
         defaultChecksForTarget(root, {
           packageId: pkg.id,
           packagePath: path,