@agentskit/doc-bridge 1.2.6 → 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/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/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "doc-bridge",
   "display_name": "Doc Bridge",
-  "version": "1.2.6",
+  "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": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentskit/doc-bridge",
-  "version": "1.2.6",
+  "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",
@@ -103,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": {

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,
+    })
+  },
+}

package/src/index-builder/plugins/nx.ts

@@ -0,0 +1,161 @@
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs'
+import { basename, dirname, isAbsolute, relative, resolve, sep } from 'node:path'
+
+import type { DocBridgeConfigV1 } from '../../config/schema.js'
+import { detectPackageManager } from '../../lib/package-manager.js'
+import { toPosix } from '../../lib/paths.js'
+import { walkFiles } from '../../lib/walk.js'
+import type { DiscoveredPackage } from './pnpm-monorepo.js'
+
+const NX_SCAN_SKIP = new Set([
+  'node_modules',
+  '.git',
+  '.nx',
+  'dist',
+  'coverage',
+  '.doc-bridge',
+])
+const NX_PROJECT_NAME = /^(?:@[A-Za-z0-9._-]+\/)?[A-Za-z0-9][A-Za-z0-9._-]*$/
+
+type JsonRecord = Record<string, unknown>
+
+const isRecord = (value: unknown): value is JsonRecord =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const readJsonRecord = (path: string): JsonRecord | undefined => {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'))
+    return isRecord(parsed) ? parsed : undefined
+  } catch {
+    return undefined
+  }
+}
+
+const safeProjectPath = (
+  root: string,
+  manifestDir: string,
+  declaredRoot?: unknown,
+): string | undefined => {
+  const candidate = typeof declaredRoot === 'string' ? resolve(root, declaredRoot) : manifestDir
+  const rel = toPosix(relative(root, candidate)) || '.'
+  if (isAbsolute(rel) || rel === '..' || rel.startsWith('../')) return undefined
+  try {
+    if (!lstatSync(candidate).isDirectory()) return undefined
+    const canonicalRoot = realpathSync.native(root)
+    const canonicalCandidate = realpathSync.native(candidate)
+    const canonicalRel = relative(canonicalRoot, canonicalCandidate)
+    if (
+      isAbsolute(canonicalRel) ||
+      canonicalRel === '..' ||
+      canonicalRel.startsWith(`..${sep}`)
+    ) {
+      return undefined
+    }
+  } catch {
+    return undefined
+  }
+  return rel
+}
+
+const packageId = (name: string): string =>
+  name.startsWith('@') ? (name.split('/').at(-1) ?? name) : name
+
+const commandPrefix = (root: string): string => {
+  const manager = detectPackageManager(root)
+  if (manager === 'pnpm') return 'pnpm exec nx run'
+  if (manager === 'yarn') return 'yarn nx run'
+  if (manager === 'bun') return 'bunx nx run'
+  return 'npx nx run'
+}
+
+const inferredChecks = (
+  root: string,
+  config: DocBridgeConfigV1,
+  projectName: string,
+  targets: ReadonlySet<string>,
+): string[] | undefined => {
+  const prefix = commandPrefix(root)
+  const strict = (config.gates?.preset ?? 'minimal') !== 'minimal'
+  const checks = [
+    ...(targets.has('test') ? [`${prefix} ${projectName}:test`] : []),
+    ...(strict && targets.has('lint') ? [`${prefix} ${projectName}:lint`] : []),
+  ]
+  return checks.length ? checks : undefined
+}
+
+type RankedProject = DiscoveredPackage & {
+  readonly rank: number
+  readonly targets: readonly string[]
+}
+
+export const discoverNxProjects = (
+  root: string,
+  config: DocBridgeConfigV1,
+): DiscoveredPackage[] => {
+  if (!existsSync(resolve(root, 'nx.json'))) return []
+
+  const manifests = walkFiles(root, {
+    extensions: ['project.json', 'package.json'],
+    skipDirs: NX_SCAN_SKIP,
+    maxFiles: 10_000,
+  })
+  const projects = new Map<string, RankedProject>()
+
+  for (const manifest of manifests) {
+    const json = readJsonRecord(manifest)
+    if (!json) continue
+    const manifestDir = dirname(manifest)
+    const manifestName = basename(manifest)
+    const isProjectJson = manifestName === 'project.json'
+    if (!isProjectJson && manifestName !== 'package.json') continue
+    const nx = json.nx
+    if (!isProjectJson && !isRecord(nx)) continue
+
+    const path = safeProjectPath(root, manifestDir, isProjectJson ? json.root : undefined)
+    if (!path) continue
+    const projectPackage = isProjectJson
+      ? readJsonRecord(resolve(root, path, 'package.json'))
+      : undefined
+    const projectName =
+      typeof json.name === 'string'
+        ? json.name
+        : typeof projectPackage?.name === 'string'
+          ? projectPackage.name
+          : basename(path === '.' ? root : path)
+    if (!NX_PROJECT_NAME.test(projectName)) continue
+
+    const targets = new Set<string>()
+    const targetRecord = isProjectJson ? json.targets : isRecord(nx) ? nx.targets : undefined
+    if (isRecord(targetRecord)) {
+      for (const target of Object.keys(targetRecord)) targets.add(target)
+    }
+    if (!isProjectJson && isRecord(json.scripts)) {
+      for (const script of Object.keys(json.scripts)) targets.add(script)
+    }
+
+    const id = packageId(projectName)
+    const rank = isProjectJson ? 2 : 1
+    const existing = projects.get(id)
+    if (existing && existing.path !== path) {
+      throw new Error(
+        `Nx project identity collision for "${id}": "${existing.name ?? id}" at "${existing.path}" and "${projectName}" at "${path}". Use unique Nx project names.`,
+      )
+    }
+    const mergedTargets = [...new Set([...(existing?.targets ?? []), ...targets])]
+    const projectJsonWins = rank >= (existing?.rank ?? 0)
+    const resolvedName = projectJsonWins ? projectName : (existing?.name ?? projectName)
+    const checks = inferredChecks(root, config, resolvedName, new Set(mergedTargets))
+    projects.set(id, {
+      id,
+      path,
+      name: resolvedName,
+      ...(checks ? { checks } : {}),
+      rank: projectJsonWins ? rank : (existing?.rank ?? rank),
+      targets: mergedTargets,
+    })
+  }
+
+  return [...projects.values()]
+    .sort((a, b) => a.id.localeCompare(b.id))
+    .map(({ rank: _rank, targets: _targets, ...project }) => project)
+}

package/src/index-builder/plugins/pnpm-monorepo.ts

@@ -9,6 +9,7 @@ export type DiscoveredPackage = {
   readonly id: string
   readonly path: string
   readonly name?: string
+  readonly checks?: readonly string[]
 }
 
 const parsePnpmWorkspace = (yaml: string): string[] => {

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

@@ -13,6 +13,7 @@ export type WatchIndexOptions = {
 }
 
 const WATCH_PATTERN = /\.(md|mdx|json|ya?ml|mdc)$/i
+const NX_MANIFEST_PATTERN = /(^|[/\\])(project|package)\.json$/i
 
 const collectWatchRoots = (root: string, config: DocBridgeConfigV1, configPath?: string): string[] => {
   const roots = new Set<string>()
@@ -24,7 +25,7 @@ const collectWatchRoots = (root: string, config: DocBridgeConfigV1, configPath?:
     : []
   for (const source of humanSources) {
     const humanOpts = source.options ?? {}
-    for (const key of ['contentDir', 'docsDir', 'root']) {
+    for (const key of ['contentDir', 'docsDir', 'root', 'srcDir']) {
       const value = humanOpts[key]
       if (typeof value === 'string' && value.length) roots.add(resolve(root, value))
     }
@@ -74,6 +75,14 @@ export const watchDocBridgeIndex = (opts: WatchIndexOptions): Promise<number> =>
     })
   }
 
+  const nxRoot = resolve(opts.root)
+  if (opts.config.routing?.plugin === 'nx' && existsSync(nxRoot)) {
+    watch(nxRoot, { recursive: true }, (_event, filename) => {
+      if (!filename || !NX_MANIFEST_PATTERN.test(filename)) return
+      rebuild()
+    })
+  }
+
   const configDir = resolve(opts.root)
   if (existsSync(configDir)) {
     watch(configDir, (_event, filename) => {
@@ -91,4 +100,4 @@ export const watchDocBridgeIndex = (opts: WatchIndexOptions): Promise<number> =>
     process.once('SIGINT', onSignal)
     process.once('SIGTERM', onSignal)
   })
-}
+}

package/src/index.ts

@@ -155,6 +155,7 @@ export {
 export { PACKAGE_VERSION } from './version.js'
 
 export { collectPackages, buildLookup } from './index-builder/build-handoffs.js'
+export { discoverNxProjects } from './index-builder/plugins/nx.js'
 export { projectRootFromConfigPath } from './config/load-config.js'
 export { createDocBridgeRag } from './intelligence/rag.js'
 export { runChatOnce, startInkChat } from './intelligence/chat.js'

package/src/version.ts

@@ -1 +1 @@
-export const PACKAGE_VERSION = '1.2.6'
+export const PACKAGE_VERSION = '1.3.0'