@agentskit/doc-bridge 1.2.4 → 1.3.0

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/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>

package/docs/mcp.md

@@ -43,6 +43,19 @@ Or with a global/local bin:
 
 Run from the repo root (or pass config discovery that resolves to it). Always `ak-docs index` after doc changes (or gate in CI).
 
+## Claude Desktop MCP Bundle
+
+Maintainers can build the local desktop extension from a clean checkout:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm mcpb:pack
+```
+
+The bundle asks the user to select the repository's `doc-bridge.config.json` and uses that file's directory as the project boundary. It contains a self-contained MCP runtime rather than the optional RAG, chat, or model-provider packages. The build validates the manifest, checks the archive inventory, and exercises all eight tools from the staged runtime.
+
+The stdio server accepts the newline-delimited JSON transport used by current MCP clients and the legacy `Content-Length` framing used by older integrations. Responses use the same framing as each request.
+
 ## Tools
 
 | Tool | Purpose |
@@ -53,6 +66,9 @@ Run from the repo root (or pass config discovery that resolves to it). Always `a
 | `gate.status` | Freshness / configured gates |
 | `retriever.query` | Local retriever chunks |
 | `memory.classify` / `memory.promoteDraft` | Memory pipeline |
+| `registry.topology` | Static curator and delegate topology |
+
+Every tool is annotated read-only. None of these MCP calls writes project files or publishes a memory promotion.
 
 ## Agent guidance (paste into AGENTS.md)
 

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/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/.mcpbignore

@@ -0,0 +1,8 @@
+.env*
+*.log
+*.map
+*.mcpb
+coverage/
+test/
+tests/
+src/

package/mcpb/manifest.json

@@ -0,0 +1,96 @@
+{
+  "manifest_version": "0.3",
+  "name": "doc-bridge",
+  "display_name": "Doc Bridge",
+  "version": "1.3.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": {
+    "name": "AgentsKit",
+    "url": "https://agentskit.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AgentsKit-io/doc-bridge.git"
+  },
+  "homepage": "https://doc-bridge.agentskit.io/",
+  "documentation": "https://doc-bridge.agentskit.io/docs/mcp",
+  "support": "https://github.com/AgentsKit-io/doc-bridge/issues",
+  "icon": "icon.png",
+  "server": {
+    "type": "node",
+    "entry_point": "server/ak-docs.js",
+    "mcp_config": {
+      "command": "node",
+      "args": [
+        "${__dirname}/server/ak-docs.js",
+        "mcp",
+        "--config",
+        "${user_config.project_config}"
+      ],
+      "env": {}
+    }
+  },
+  "tools": [
+    {
+      "name": "handoff.resolve",
+      "description": "Resolve a package or ownership id to its deterministic AgentHandoff."
+    },
+    {
+      "name": "doc.search",
+      "description": "Search the deterministic Doc Bridge index for repository documentation."
+    },
+    {
+      "name": "doc.get",
+      "description": "Read one indexed agent documentation file by id or indexed path."
+    },
+    {
+      "name": "gate.status",
+      "description": "Evaluate documentation gates without writing files."
+    },
+    {
+      "name": "retriever.query",
+      "description": "Return relevant local Doc Bridge index chunks for a query."
+    },
+    {
+      "name": "memory.classify",
+      "description": "Classify local memory candidates into agent, human, playbook, or discard routes."
+    },
+    {
+      "name": "memory.promoteDraft",
+      "description": "Build a reviewable draft promotion body from local memory candidates without publishing it."
+    },
+    {
+      "name": "registry.topology",
+      "description": "Return the static Doc Bridge curator and delegate topology."
+    }
+  ],
+  "tools_generated": false,
+  "keywords": [
+    "coding-agents",
+    "documentation",
+    "handoff",
+    "repository",
+    "developer-tools"
+  ],
+  "license": "MIT",
+  "privacy_policies": [
+    "https://github.com/AgentsKit-io/doc-bridge/blob/master/PRIVACY.md"
+  ],
+  "compatibility": {
+    "platforms": [
+      "darwin"
+    ],
+    "runtimes": {
+      "node": ">=22"
+    }
+  },
+  "user_config": {
+    "project_config": {
+      "type": "file",
+      "title": "Doc Bridge configuration",
+      "description": "Select the doc-bridge.config.json file at the root of the repository Doc Bridge may read.",
+      "required": true
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentskit/doc-bridge",
-  "version": "1.2.4",
+  "version": "1.3.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",
@@ -31,11 +31,13 @@
     "docs",
     "examples",
     "README.md",
+    "PRIVACY.md",
     "CONTRIBUTING.md",
     "SECURITY.md",
     "CODE_OF_CONDUCT.md",
     "CHANGELOG.md",
     "LICENSE",
+    "mcpb",
     "tsup.config.ts",
     "tsconfig.json",
     "src"
@@ -53,6 +55,11 @@
     "smoke:docsites": "node scripts/smoke-docsites.mjs",
     "smoke:real-docsites": "node scripts/smoke-real-docsites.mjs",
     "smoke:ollama": "node scripts/smoke-ollama.mjs",
+    "mcpb:stage": "npm run build && node scripts/build-mcpb.mjs stage",
+    "mcpb:validate": "node scripts/build-mcpb.mjs validate",
+    "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",
     "coverage:badge": "node scripts/update-coverage-badge.mjs",
     "changeset": "changeset",
     "version-packages": "changeset version && node scripts/sync-version.mjs",
@@ -96,7 +103,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": {
@@ -132,6 +141,7 @@
     "@agentskit/core": "1.12.3",
     "@agentskit/ink": "0.10.4",
     "@agentskit/react": "0.7.4",
+    "@anthropic-ai/mcpb": "2.1.2",
     "@changesets/cli": "^2.31.0",
     "@lhci/cli": "^0.15.1",
     "@playwright/test": "1.61.1",
@@ -140,11 +150,12 @@
     "@types/react": "19.2.17",
     "@types/react-dom": "19.2.3",
     "@vitest/coverage-v8": "4.1.10",
+    "esbuild": "^0.28.1",
     "fumadocs-core": "15.6.5",
     "fumadocs-mdx": "11.6.4",
     "fumadocs-ui": "15.6.5",
     "lucide-react": "0.460.0",
-    "next": "15.5.19",
+    "next": "15.5.21",
     "react": "19.2.0",
     "react-dom": "19.2.0",
     "tailwindcss": "4.3.2",
@@ -152,14 +163,6 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.9"
   },
-  "pnpm": {
-    "overrides": {
-      "esbuild": "^0.28.1",
-      "postcss": "8.5.19",
-      "tmp": "0.2.7",
-      "uuid": "11.1.1"
-    }
-  },
   "directories": {
     "doc": "docs",
     "example": "examples",

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,

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

@@ -9,6 +9,7 @@ import { renderCapabilitiesJson } from './capabilities.js'
 import { sha256NormalizedV1 } from './content-hash.js'
 import { renderLlmsTxt } from './llms-txt.js'
 import { scanHumanDocs } from './human-adapters/index.js'
+import { discoverNxProjects } from './plugins/nx.js'
 import { discoverPnpmPackages } from './plugins/pnpm-monorepo.js'
 import { scanAgentCorpus } from './scan-corpus.js'
 
@@ -66,7 +67,12 @@ export const buildDocBridgeIndex = (opts: BuildIndexOptions): BuildIndexResult =
     config.routing?.plugin === 'npm-workspaces' ||
     config.routing?.plugin === 'yarn-workspaces'
 
-  const discovered = shouldDiscover ? discoverPnpmPackages(root, config) : []
+  const discovered =
+    config.routing?.plugin === 'nx'
+      ? discoverNxProjects(root, config)
+      : shouldDiscover
+        ? discoverPnpmPackages(root, config)
+        : []
   const packages = collectPackages(config, discovered, corpus)
   const humanDocs = scanHumanDocs(root, config)
 

package/src/index-builder/human-adapters/index.ts

@@ -4,8 +4,11 @@ import { resolve, sep } from 'node:path'
 import type { DocBridgeConfigV1, HumanCorpusConfig } from '../../config/schema.js'
 import { docusaurusAdapter } from './docusaurus.js'
 import { fumadocsAdapter } from './fumadocs.js'
+import { nextraAdapter } from './nextra.js'
 import type { HumanAdapter, HumanDocMap, HumanDocRecord } from './core.js'
 import { plainMarkdownAdapter } from './plain-markdown.js'
+import { starlightAdapter } from './starlight.js'
+import { vitepressAdapter } from './vitepress.js'
 
 export type { HumanAdapter, HumanDocMap, HumanDocRecord } from './core.js'
 
@@ -13,6 +16,9 @@ const ADAPTERS: readonly HumanAdapter[] = [
   plainMarkdownAdapter,
   fumadocsAdapter,
   docusaurusAdapter,
+  vitepressAdapter,
+  starlightAdapter,
+  nextraAdapter,
 ]
 
 const humanConfigs = (config: DocBridgeConfigV1): HumanCorpusConfig[] => {

package/src/index-builder/human-adapters/nextra.ts

@@ -0,0 +1,43 @@
+import {
+  optionString,
+  parseFrontmatter,
+  routeSlug,
+  scanMarkdownDocs,
+  type HumanAdapter,
+  type HumanDocRecord,
+} from './core.js'
+
+const nextraRecordId = (relPath: string, raw: string): string => {
+  const frontmatter = parseFrontmatter(raw)
+  return frontmatter.package ?? frontmatter.module ?? frontmatter.id ?? (routeSlug(relPath) || 'index')
+}
+
+const isIndexPage = (path: string): boolean => /(^|[/\\])index\.mdx?$/i.test(path)
+
+const resolveRouteCollisions = (records: readonly HumanDocRecord[]): HumanDocRecord[] => {
+  const byUrl = new Map<string, { readonly record: HumanDocRecord; readonly indexPage: boolean }>()
+  for (const record of records) {
+    const normalized = { ...record, url: record.url || '/' }
+    const indexPage = isIndexPage(record.path)
+    const existing = byUrl.get(normalized.url)
+    if (!existing || indexPage || !existing.indexPage) {
+      byUrl.set(normalized.url, { record: normalized, indexPage })
+    }
+  }
+  return [...byUrl.values()].map(({ record }) => record)
+}
+
+export const nextraAdapter: HumanAdapter = {
+  plugin: 'nextra',
+  scan: ({ root, config }) => {
+    const contentDir = optionString(config.options, ['contentDir', 'docsDir', 'root'])
+    if (!contentDir) return []
+
+    return resolveRouteCollisions(
+      scanMarkdownDocs(root, contentDir, {
+        idForDoc: nextraRecordId,
+        urlPrefix: optionString(config.options, ['urlPrefix', 'contentDirBasePath']) ?? '/',
+      }),
+    )
+  },
+}

package/src/index-builder/human-adapters/starlight.ts

@@ -0,0 +1,40 @@
+import { slug as githubSlug } from 'github-slugger'
+
+import {
+  optionString,
+  parseFrontmatter,
+  routeSlug,
+  scanMarkdownDocs,
+  type HumanAdapter,
+} from './core.js'
+
+const isStarlightPage = (relPath: string, raw: string): boolean => {
+  if (relPath.split('/').some((part) => part.startsWith('.') || part.startsWith('_'))) return false
+  return parseFrontmatter(raw).draft !== 'true'
+}
+
+const starlightFileSlug = (relPath: string): string =>
+  routeSlug(relPath)
+    .split('/')
+    .map((part) => githubSlug(part))
+    .filter(Boolean)
+    .join('/')
+
+const starlightSlug = (relPath: string, raw: string): string => {
+  const slug = parseFrontmatter(raw).slug
+  return slug ? slug.replace(/^\/+|\/+$/g, '') : starlightFileSlug(relPath)
+}
+
+export const starlightAdapter: HumanAdapter = {
+  plugin: 'starlight',
+  scan: ({ root, config }) => {
+    const contentDir = optionString(config.options, ['contentDir', 'docsDir', 'root'])
+    if (!contentDir) return []
+
+    return scanMarkdownDocs(root, contentDir, {
+      includeRelPath: isStarlightPage,
+      slugForDoc: starlightSlug,
+      urlPrefix: config.options?.urlPrefix,
+    })
+  },
+}

package/src/index-builder/human-adapters/vitepress.ts

@@ -0,0 +1,43 @@
+import { minimatch } from 'minimatch'
+
+import { optionString, routeSlug, scanMarkdownDocs, type HumanAdapter } from './core.js'
+
+const isVitePressPage = (relPath: string): boolean =>
+  !relPath.split('/').some((part) => part === '.vitepress' || part.startsWith('.'))
+
+const srcExcludePatterns = (value: unknown): readonly string[] => {
+  if (value === undefined) return []
+  if (!Array.isArray(value) || value.length > 64) {
+    throw new Error('VitePress srcExclude must be an array of at most 64 glob patterns.')
+  }
+  return value.map((pattern) => {
+    if (typeof pattern !== 'string' || !pattern || pattern.length > 256 || pattern.includes('\0')) {
+      throw new Error('Each VitePress srcExclude pattern must be a non-empty string up to 256 characters.')
+    }
+    return pattern
+  })
+}
+
+const isExcluded = (relPath: string, patterns: readonly string[]): boolean =>
+  patterns.some((pattern) => minimatch(relPath, pattern, { dot: true }))
+
+const vitepressSlug = (relPath: string, cleanUrls: boolean): string => {
+  const slug = routeSlug(relPath)
+  if (cleanUrls || /(?:^|\/)index\.mdx?$/.test(relPath)) return slug
+  return `${slug}.html`
+}
+
+export const vitepressAdapter: HumanAdapter = {
+  plugin: 'vitepress',
+  scan: ({ root, config }) => {
+    const docsDir = optionString(config.options, ['docsDir', 'root', 'srcDir'])
+    if (!docsDir) return []
+    const srcExclude = srcExcludePatterns(config.options?.srcExclude)
+
+    return scanMarkdownDocs(root, docsDir, {
+      includeRelPath: (relPath) => isVitePressPage(relPath) && !isExcluded(relPath, srcExclude),
+      slugForDoc: (relPath) => vitepressSlug(relPath, config.options?.cleanUrls === true),
+      urlPrefix: config.options?.urlPrefix,
+    })
+  },
+}