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

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

@@ -0,0 +1,100 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { HumanCorpusConfig } from '../../config/schema.js'
+import { slugFromPath } from '../../lib/markdown.js'
+import { toPosix } from '../../lib/paths.js'
+import { walkFiles } from '../../lib/walk.js'
+
+export type HumanDocRecord = {
+  readonly id: string
+  readonly url: string
+  readonly path: string
+}
+
+export type HumanDocMap = Record<string, string>
+
+export type HumanAdapterContext = {
+  readonly root: string
+  readonly config: HumanCorpusConfig
+}
+
+export type HumanAdapter = {
+  readonly plugin: HumanCorpusConfig['plugin']
+  readonly scan: (ctx: HumanAdapterContext) => HumanDocRecord[]
+}
+
+export const optionString = (
+  options: Record<string, unknown> | undefined,
+  keys: readonly string[],
+): string | undefined => {
+  for (const key of keys) {
+    const value = options?.[key]
+    if (typeof value === 'string' && value) return value
+  }
+  return undefined
+}
+
+export const parseFrontmatter = (raw: string): Record<string, string> => {
+  if (!raw.startsWith('---\n')) return {}
+  const end = raw.indexOf('\n---', 4)
+  if (end === -1) return {}
+
+  const out: Record<string, string> = {}
+  for (const line of raw.slice(4, end).split('\n')) {
+    const match = /^([A-Za-z0-9_-]+):\s*(.+?)\s*$/.exec(line)
+    if (match?.[1] && match[2]) out[match[1]] = match[2].replace(/^['"]|['"]$/g, '')
+  }
+  return out
+}
+
+export const docId = (relToHumanRoot: string, raw: string): string => {
+  const meta = parseFrontmatter(raw)
+  return meta.package ?? meta.module ?? meta.id ?? slugFromPath(relToHumanRoot)
+}
+
+export const routeSlug = (relToHumanRoot: string, opts?: { stripGroups?: boolean }): string =>
+  relToHumanRoot
+    .split('/')
+    .filter((part) => !opts?.stripGroups || !/^\(.+\)$/.test(part))
+    .join('/')
+    .replace(/(?:^|\/)index\.mdx?$/, '')
+    .replace(/\.mdx?$/, '')
+
+export const humanUrl = (slug: string, urlPrefix: unknown): string => {
+  if (typeof urlPrefix !== 'string' || !urlPrefix) return slug
+  const prefix = urlPrefix.replace(/\/$/, '')
+  return slug ? `${prefix}/${slug.replace(/^\//, '')}` : prefix
+}
+
+export const scanMarkdownDocs = (
+  root: string,
+  humanRoot: string,
+  options?: {
+    readonly includeRelPath?: (relToHumanRoot: string, raw: string) => boolean
+    readonly idForDoc?: (relToHumanRoot: string, raw: string) => string
+    readonly slugForDoc?: (relToHumanRoot: string, raw: string) => string
+    readonly urlPrefix?: unknown
+    readonly stripGroups?: boolean
+  },
+): HumanDocRecord[] => {
+  const out: HumanDocRecord[] = []
+  const absRoot = join(root, humanRoot)
+
+  for (const abs of walkFiles(absRoot, { extensions: ['.md', '.mdx'] })) {
+    const relToHumanRoot = toPosix(abs.replace(`${toPosix(absRoot)}/`, ''))
+    const raw = readFileSync(abs, 'utf8')
+    if (options?.includeRelPath && !options.includeRelPath(relToHumanRoot, raw)) continue
+    out.push({
+      id: options?.idForDoc?.(relToHumanRoot, raw) ?? docId(relToHumanRoot, raw),
+      url: humanUrl(
+        options?.slugForDoc?.(relToHumanRoot, raw) ??
+          routeSlug(relToHumanRoot, options?.stripGroups ? { stripGroups: true } : undefined),
+        options?.urlPrefix,
+      ),
+      path: abs,
+    })
+  }
+
+  return out
+}

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

@@ -0,0 +1,113 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import vm from 'node:vm'
+
+import {
+  optionString,
+  parseFrontmatter,
+  routeSlug,
+  scanMarkdownDocs,
+  type HumanAdapter,
+} from './core.js'
+
+type SidebarDocFilter = {
+  readonly ids: ReadonlySet<string>
+  readonly autogenDirs: readonly string[]
+  readonly enabled: boolean
+}
+
+const docusaurusFileSlug = (relPath: string): string => {
+  const parts = relPath.split('/')
+  const file = parts.at(-1) ?? ''
+  const base = file.replace(/\.mdx?$/, '')
+  const parent = parts.at(-2)
+  if (/^(index|readme)$/i.test(base) || base === parent) return parts.slice(0, -1).join('/')
+  return routeSlug(relPath)
+}
+
+const docusaurusSlug = (relPath: string, raw: string): string => {
+  const slug = parseFrontmatter(raw).slug
+  if (!slug) return docusaurusFileSlug(relPath)
+  return slug.replace(/^\.\//, '').replace(/^\//, '').replace(/\/$/, '')
+}
+
+const docusaurusSidebarId = (relPath: string, raw: string): string => {
+  const id = parseFrontmatter(raw).id
+  if (!id) return routeSlug(relPath)
+  const parts = relPath.split('/').slice(0, -1)
+  return [...parts, id].filter(Boolean).join('/')
+}
+
+const docusaurusRecordId = (relPath: string, raw: string): string => {
+  const frontmatter = parseFrontmatter(raw)
+  return frontmatter.package ?? frontmatter.module ?? docusaurusSidebarId(relPath, raw)
+}
+
+const sidebarsValue = (file: string): unknown => {
+  if (!existsSync(file)) return undefined
+  const raw = readFileSync(file, 'utf8')
+    .replace(/import\s+type\s+[\s\S]*?;?\n/g, '')
+    .replace(/:\s*[A-Za-z0-9_.$<>{}\[\],\s]+(?=\s*=)/g, '')
+    .replace(/\s+satisfies\s+[A-Za-z0-9_.$<>{}\[\],\s]+(?=\s*(?:;|\n|$))/g, '')
+    .replace(/export\s+default/, 'module.exports =')
+  const sandbox = { module: { exports: {} as unknown }, exports: {} }
+  vm.runInNewContext(raw, sandbox, { timeout: 250 })
+  return sandbox.module.exports
+}
+
+const visitSidebar = (value: unknown, filter: { ids: Set<string>; autogenDirs: string[] }): void => {
+  if (typeof value === 'string') {
+    filter.ids.add(value)
+    return
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) visitSidebar(item, filter)
+    return
+  }
+  if (!value || typeof value !== 'object') return
+
+  const item = value as Record<string, unknown>
+  if ((item.type === 'doc' || item.type === 'ref') && typeof item.id === 'string') {
+    filter.ids.add(item.id)
+  }
+  if (item.type === 'autogenerated' && typeof item.dirName === 'string') {
+    filter.autogenDirs.push(item.dirName)
+  }
+  if (Array.isArray(item.items)) visitSidebar(item.items, filter)
+  if (item.link && typeof item.link === 'object') visitSidebar(item.link, filter)
+  for (const child of Object.values(item)) {
+    if (Array.isArray(child)) visitSidebar(child, filter)
+  }
+}
+
+const readSidebars = (root: string, sidebarsFile: string | undefined): SidebarDocFilter => {
+  if (!sidebarsFile) return { enabled: false, ids: new Set(), autogenDirs: [] }
+  const value = sidebarsValue(join(root, sidebarsFile))
+  const filter = { ids: new Set<string>(), autogenDirs: [] as string[] }
+  visitSidebar(value, filter)
+  return { enabled: true, ...filter }
+}
+
+const isIncludedBySidebar = (filter: SidebarDocFilter, id: string): boolean => {
+  if (!filter.enabled) return true
+  if (filter.ids.has(id)) return true
+  return filter.autogenDirs.some((dir) => {
+    const prefix = dir === '.' ? '' : dir.replace(/\/$/, '')
+    return prefix ? id === prefix || id.startsWith(`${prefix}/`) : true
+  })
+}
+
+export const docusaurusAdapter: HumanAdapter = {
+  plugin: 'docusaurus',
+  scan: ({ root, config }) => {
+    const docsDir = optionString(config.options, ['docsDir', 'root'])
+    if (!docsDir) return []
+    const sidebarFilter = readSidebars(root, optionString(config.options, ['sidebarsFile']))
+    return scanMarkdownDocs(root, docsDir, {
+      includeRelPath: (relPath, raw) => isIncludedBySidebar(sidebarFilter, docusaurusSidebarId(relPath, raw)),
+      idForDoc: docusaurusRecordId,
+      slugForDoc: docusaurusSlug,
+      urlPrefix: config.options?.urlPrefix,
+    })
+  },
+}

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

@@ -0,0 +1,70 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import { optionString, scanMarkdownDocs, type HumanAdapter } from './core.js'
+
+type FumadocsMeta = {
+  readonly pages?: unknown
+}
+
+const readMetaPages = (dir: string): string[] | undefined => {
+  const file = join(dir, 'meta.json')
+  if (!existsSync(file)) return undefined
+  try {
+    const meta = JSON.parse(readFileSync(file, 'utf8')) as FumadocsMeta
+    return Array.isArray(meta.pages) ? meta.pages.filter((page): page is string => typeof page === 'string') : undefined
+  } catch {
+    return undefined
+  }
+}
+
+const pageKey = (part: string): string => part.replace(/\.mdx?$/, '')
+
+const isDotFile = (relPath: string): boolean => {
+  const file = relPath.split('/').at(-1) ?? ''
+  return file.startsWith('.')
+}
+
+const isListedByMeta = (contentRoot: string, relPath: string): boolean => {
+  if (isDotFile(relPath)) return false
+
+  const parts = relPath.split('/')
+
+  for (let i = 0; i < parts.length; i += 1) {
+    const dir = join(contentRoot, ...parts.slice(0, i))
+    const pages = readMetaPages(dir)
+    if (!pages?.length || pages.includes('...')) continue
+
+    const key = pageKey(parts[i] ?? '')
+    if (!pages.includes(key) && !pages.includes(`./${key}`)) return false
+  }
+
+  return true
+}
+
+export const fumadocsAdapter: HumanAdapter = {
+  plugin: 'fumadocs',
+  scan: ({ root, config }) => {
+    const contentDir = optionString(config.options, ['contentDir', 'root'])
+    if (!contentDir) return []
+    const contentRoot = join(root, contentDir)
+    const excludePrefixes = Array.isArray(config.options?.excludePrefixes)
+      ? config.options.excludePrefixes.filter((v): v is string => typeof v === 'string')
+      : typeof config.options?.excludePrefix === 'string'
+        ? [config.options.excludePrefix]
+        : []
+    // Nested agent corpora under Fumadocs (e.g. content/docs/for-agents) should not be human docs
+    if (!excludePrefixes.includes('for-agents')) excludePrefixes.push('for-agents')
+
+    return scanMarkdownDocs(root, contentDir, {
+      includeRelPath: (relPath) => {
+        if (excludePrefixes.some((prefix) => relPath === prefix || relPath.startsWith(`${prefix}/`))) {
+          return false
+        }
+        return isListedByMeta(contentRoot, relPath)
+      },
+      urlPrefix: config.options?.urlPrefix,
+      stripGroups: true,
+    })
+  },
+}

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

@@ -0,0 +1,52 @@
+import type { DocBridgeConfigV1, HumanCorpusConfig } from '../../config/schema.js'
+import { docusaurusAdapter } from './docusaurus.js'
+import { fumadocsAdapter } from './fumadocs.js'
+import type { HumanAdapter, HumanDocMap, HumanDocRecord } from './core.js'
+import { plainMarkdownAdapter } from './plain-markdown.js'
+
+export type { HumanAdapter, HumanDocMap, HumanDocRecord } from './core.js'
+
+const ADAPTERS: readonly HumanAdapter[] = [
+  plainMarkdownAdapter,
+  fumadocsAdapter,
+  docusaurusAdapter,
+]
+
+const humanConfigs = (config: DocBridgeConfigV1): HumanCorpusConfig[] => {
+  const human = config.corpus.human
+  if (!human) return []
+  return Array.isArray(human) ? human : [human]
+}
+
+export const scanHumanDocRecords = (
+  root: string,
+  config: DocBridgeConfigV1,
+): HumanDocRecord[] => {
+  const out: HumanDocRecord[] = []
+  const seen = new Set<string>()
+  const agentRoot = config.corpus.agent.root.replace(/\/$/, '')
+
+  for (const human of humanConfigs(config)) {
+    const adapter = ADAPTERS.find((candidate) => candidate.plugin === human.plugin)
+    if (!adapter) continue
+    for (const record of adapter.scan({ root, config: human })) {
+      // Never treat agent-corpus files as human docs (nested for-agents, etc.)
+      if (
+        record.path === agentRoot ||
+        record.path.startsWith(`${agentRoot}/`) ||
+        record.path.includes('/for-agents/') ||
+        record.path.endsWith('/for-agents')
+      ) {
+        continue
+      }
+      if (seen.has(record.id)) continue
+      seen.add(record.id)
+      out.push(record)
+    }
+  }
+
+  return out
+}
+
+export const scanHumanDocs = (root: string, config: DocBridgeConfigV1): HumanDocMap =>
+  Object.fromEntries(scanHumanDocRecords(root, config).map((doc) => [doc.id, doc.url]))

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

@@ -0,0 +1,10 @@
+import { optionString, scanMarkdownDocs, type HumanAdapter } from './core.js'
+
+export const plainMarkdownAdapter: HumanAdapter = {
+  plugin: 'plain-markdown',
+  scan: ({ root, config }) => {
+    const humanRoot =
+      optionString(config.options, ['contentDir', 'root', 'docsDir']) ?? 'docs'
+    return scanMarkdownDocs(root, humanRoot, { urlPrefix: config.options?.urlPrefix })
+  },
+}

package/src/index-builder/llms-txt.ts

@@ -0,0 +1,19 @@
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import type { KnowledgeEntry } from '../schemas/doc-bridge-index.js'
+
+export const renderLlmsTxt = (
+  config: DocBridgeConfigV1,
+  knowledge: readonly KnowledgeEntry[],
+  projectName: string,
+): string => {
+  const preamble =
+    config.index?.llmsTxt?.preamble ??
+    `# ${projectName}\n\n> Agent-readable documentation index generated by ak-docs (@agentskit/doc-bridge).\n`
+
+  const lines = knowledge.slice(0, 500).map((entry) => {
+    const desc = entry.description ? `: ${entry.description}` : ''
+    return `- [${entry.title}](${entry.path})${desc}`
+  })
+
+  return `${preamble.trim()}\n\n## Knowledge\n\n${lines.join('\n')}\n`
+}

package/src/index-builder/plugins/human-markdown.ts

@@ -0,0 +1,7 @@
+export {
+  scanHumanDocRecords,
+  scanHumanDocs,
+  type HumanAdapter,
+  type HumanDocMap,
+  type HumanDocRecord,
+} from '../human-adapters/index.js'

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

@@ -0,0 +1,72 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { basename, join } from 'node:path'
+
+import type { DocBridgeConfigV1 } from '../../config/schema.js'
+import { expandWorkspaceGlobs } from '../../lib/glob-expand.js'
+import { toPosix } from '../../lib/paths.js'
+
+export type DiscoveredPackage = {
+  readonly id: string
+  readonly path: string
+  readonly name?: string
+}
+
+const parsePnpmWorkspace = (yaml: string): string[] => {
+  const lines = yaml.split('\n')
+  const patterns: string[] = []
+  let inPackages = false
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (trimmed === 'packages:') {
+      inPackages = true
+      continue
+    }
+    if (inPackages) {
+      if (trimmed.startsWith('- ')) {
+        patterns.push(trimmed.slice(2).trim().replace(/^['"]|['"]$/g, ''))
+        continue
+      }
+      if (trimmed && !trimmed.startsWith('#')) inPackages = false
+    }
+  }
+  return patterns
+}
+
+const readPackageJson = (dir: string): { name?: string } | null => {
+  const file = join(dir, 'package.json')
+  if (!existsSync(file)) return null
+  try {
+    return JSON.parse(readFileSync(file, 'utf8')) as { name?: string }
+  } catch {
+    return null
+  }
+}
+
+export const discoverPnpmPackages = (
+  root: string,
+  config: DocBridgeConfigV1,
+): DiscoveredPackage[] => {
+  const explicit = config.routing?.options?.packages
+  let patterns = explicit
+  if (!patterns?.length) {
+    const workspaceFile = join(root, 'pnpm-workspace.yaml')
+    if (existsSync(workspaceFile)) {
+      patterns = parsePnpmWorkspace(readFileSync(workspaceFile, 'utf8'))
+    }
+  }
+  if (!patterns?.length) return []
+
+  const dirs = expandWorkspaceGlobs(root, patterns)
+  const out: DiscoveredPackage[] = []
+
+  for (const abs of dirs) {
+    const pkg = readPackageJson(abs)
+    if (!pkg) continue
+    const rel = toPosix(abs.replace(`${toPosix(root)}/`, ''))
+    const folderId = basename(abs)
+    const id = pkg.name?.startsWith('@') ? pkg.name.split('/').pop() ?? folderId : (pkg.name ?? folderId)
+    out.push({ id, path: rel, ...(pkg.name ? { name: pkg.name } : {}) })
+  }
+
+  return out.sort((a, b) => a.id.localeCompare(b.id))
+}

package/src/index-builder/scan-corpus.ts

@@ -0,0 +1,181 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import {
+  firstHeading,
+  firstParagraph,
+  frontmatterString,
+  frontmatterStringList,
+  parseFrontmatter,
+  slugFromPath,
+  type FrontmatterData,
+} from '../lib/markdown.js'
+import { toPosix } from '../lib/paths.js'
+import { walkFiles } from '../lib/walk.js'
+import type { KnowledgeEntry } from '../schemas/doc-bridge-index.js'
+
+export type CorpusDoc = KnowledgeEntry & {
+  readonly absPath: string
+  readonly relPath: string
+  readonly frontmatter: FrontmatterData
+}
+
+export type OwnershipSeed = {
+  readonly id: string
+  readonly path: string
+  readonly purpose?: string
+  readonly checks?: readonly string[]
+  readonly agentDoc: string
+  readonly humanDoc?: string
+}
+
+const relFromRoot = (root: string, abs: string): string => toPosix(abs.replace(`${toPosix(root)}/`, ''))
+
+export const scanAgentCorpus = (root: string, config: DocBridgeConfigV1): CorpusDoc[] => {
+  const agentRoot = join(root, config.corpus.agent.root)
+  const files = walkFiles(agentRoot, { extensions: ['.md', '.mdx'] })
+  const corpusRelRoot = toPosix(config.corpus.agent.root)
+
+  return files.map((abs) => {
+    const relToCorpus = toPosix(abs.replace(`${toPosix(agentRoot)}/`, ''))
+    const relPath = `${corpusRelRoot}/${relToCorpus}`
+    const raw = readFileSync(abs, 'utf8')
+    const { data: frontmatter } = parseFrontmatter(raw)
+    const id =
+      frontmatterString(frontmatter, 'id') ??
+      frontmatterString(frontmatter, 'package') ??
+      slugFromPath(relToCorpus)
+    const title = firstHeading(raw) ?? id
+    const description = firstParagraph(raw)
+    return {
+      id,
+      type: 'agent-doc',
+      title,
+      path: relPath,
+      absPath: abs,
+      relPath,
+      frontmatter,
+      ...(description ? { description } : {}),
+    }
+  })
+}
+
+export const guessAgentDocForPackage = (
+  corpus: readonly CorpusDoc[],
+  packageId: string,
+): string | undefined => {
+  const candidates = [
+    (doc: CorpusDoc) => frontmatterString(doc.frontmatter, 'package') === packageId,
+    (doc: CorpusDoc) => doc.id === packageId,
+    (doc: CorpusDoc) => doc.relPath.endsWith(`/packages/${packageId}.md`),
+    (doc: CorpusDoc) => doc.relPath.endsWith(`/packages/${packageId}.mdx`),
+    (doc: CorpusDoc) => doc.relPath.endsWith(`/packages/${packageId}/index.md`),
+    (doc: CorpusDoc) => doc.relPath.endsWith(`/packages/${packageId}/index.mdx`),
+    (doc: CorpusDoc) => doc.relPath.endsWith(`/${packageId}.md`),
+    (doc: CorpusDoc) => doc.relPath.endsWith(`/${packageId}.mdx`),
+    (doc: CorpusDoc) => doc.relPath.includes(`/packages/${packageId}/`),
+  ]
+  for (const match of candidates) {
+    const hit = corpus.find(match)
+    if (hit) return hit.path
+  }
+  return undefined
+}
+
+/** Ownership seeds from agent-doc frontmatter (`package` + `editRoot`). */
+export const ownershipFromFrontmatter = (corpus: readonly CorpusDoc[]): readonly OwnershipSeed[] => {
+  const out: OwnershipSeed[] = []
+
+  for (const doc of corpus) {
+    const type = frontmatterString(doc.frontmatter, 'type')
+    const id =
+      frontmatterString(doc.frontmatter, 'package') ??
+      (type === 'package' || type === 'module' || type === 'pattern'
+        ? frontmatterString(doc.frontmatter, 'id') ?? doc.id
+        : undefined)
+    const path =
+      frontmatterString(doc.frontmatter, 'editRoot') ??
+      frontmatterString(doc.frontmatter, 'path') ??
+      (type === 'package' || type === 'module' ? `packages/${id}` : undefined)
+    if (!id || !path) continue
+    const purpose = frontmatterString(doc.frontmatter, 'purpose') ?? doc.description
+    const checks = frontmatterStringList(doc.frontmatter, 'checks')
+    const humanDoc = frontmatterString(doc.frontmatter, 'humanDoc')
+    out.push({
+      id,
+      path,
+      agentDoc: doc.path,
+      ...(purpose ? { purpose } : {}),
+      ...(checks ? { checks } : {}),
+      ...(humanDoc ? { humanDoc } : {}),
+    })
+  }
+
+  return out
+}
+
+/**
+ * Path-based ownership when frontmatter is incomplete:
+ * - packages/id.md(x) → package path packages/id
+ * - pillars/.../name-pattern.md → pattern ownership (edit root = file)
+ * - registry/id/README.md → registry agent
+ */
+export const ownershipFromCorpus = (corpus: readonly CorpusDoc[]): readonly OwnershipSeed[] => {
+  const out: OwnershipSeed[] = []
+  const seen = new Set<string>()
+
+  for (const doc of corpus) {
+    // already handled if package+editRoot present
+    if (frontmatterString(doc.frontmatter, 'package') && frontmatterString(doc.frontmatter, 'editRoot')) {
+      continue
+    }
+
+    let id: string | undefined
+    let path: string | undefined
+    let purpose = frontmatterString(doc.frontmatter, 'purpose') ?? doc.description
+
+    const packagesFile = /(?:^|\/)packages\/([^/]+)\.(?:md|mdx)$/.exec(doc.relPath)
+    const packagesIndex = /(?:^|\/)packages\/([^/]+)\/index\.(?:md|mdx)$/.exec(doc.relPath)
+    const registryReadme = /(?:^|\/)registry\/([^/]+)\/README\.(?:md|mdx)$/i.exec(doc.relPath)
+    const patternFile = /(?:^|\/)pillars\/[^/]+\/([^/]+(?:-pattern)?)\.(?:md|mdx)$/.exec(doc.relPath)
+    const topLevelPkg = /(?:^|\/)for-agents\/([^/]+)\.(?:md|mdx)$/.exec(doc.relPath)
+
+    if (packagesFile?.[1] && packagesFile[1] !== 'index') {
+      id = packagesFile[1]
+      path = `packages/${id}`
+    } else if (packagesIndex?.[1]) {
+      id = packagesIndex[1]
+      path = `packages/${id}`
+    } else if (registryReadme?.[1]) {
+      id = registryReadme[1]
+      path = `registry/${id}`
+    } else if (patternFile?.[1] && patternFile[1] !== 'index' && patternFile[1] !== 'universal') {
+      id = patternFile[1]
+      path = doc.path
+      purpose = purpose ?? `Playbook pattern: ${id}`
+    } else if (topLevelPkg?.[1] && topLevelPkg[1] !== 'index' && topLevelPkg[1] !== 'INDEX') {
+      // agentskit for-agents/core.mdx style
+      id = topLevelPkg[1]
+      path = `packages/${id}`
+    }
+
+    if (!id || !path || seen.has(id)) continue
+    seen.add(id)
+
+    const humanDoc = frontmatterString(doc.frontmatter, 'humanDoc')
+    const checks = frontmatterStringList(doc.frontmatter, 'checks')
+    out.push({
+      id,
+      path,
+      agentDoc: doc.path,
+      ...(purpose ? { purpose } : {}),
+      ...(checks ? { checks } : {}),
+      ...(humanDoc ? { humanDoc } : {}),
+    })
+  }
+
+  return out
+}
+
+export { relFromRoot }