@agentskit/doc-bridge 0.1.0-alpha.3 → 1.0.0

package/src/cli/program.ts

@@ -15,6 +15,16 @@ import { createDocBridgeRag } from '../intelligence/rag.js'
 import { firstHeading, firstParagraph } from '../lib/markdown.js'
 import { ingestMemoryCandidates } from '../memory/ingest.js'
 import { classifyMemoryCandidates, draftMemoryPromotion } from '../memory/pipeline.js'
+import { promoteMemoryToGithubPr } from '../memory/github-pr.js'
+import { watchDocBridgeIndex } from '../index-builder/watch-index.js'
+import {
+  formatDoctorBadgeJson,
+  formatDoctorBadgeMarkdown,
+} from '../doctor/badge.js'
+import { docBridgePatternMarkdown, docBridgePatternPayload } from '../playbook/doc-bridge-pattern.js'
+import { formatDemoText, runDemo, withDemoWorkspace, type DemoFixture } from './demo.js'
+import { formatDoctorText, runDoctor } from '../doctor/run-doctor.js'
+import { installMcpConfig, mcpSnippet } from '../mcp/install.js'
 import { startMcpStdioServer } from '../mcp/server.js'
 import { IndexNotFoundError, loadDocBridgeIndex } from '../query/load-index.js'
 import { runQuery, type QueryKind } from '../query/query.js'
@@ -36,6 +46,8 @@ type Command =
   | 'index'
   | 'gate'
   | 'mcp'
+  | 'doctor'
+  | 'demo'
   | 'query'
   | 'search'
   | 'retrieve'
@@ -48,14 +60,17 @@ const usage = `ak-docs — human↔agent documentation bridge (@agentskit/doc-br
 
 Core (no API key):
   ak-docs init [--demo] [--scaffold-workspaces]
-  ak-docs index
+  ak-docs demo [--fixture example|monorepo] [--text] [--in-project]
+  ak-docs doctor [--text] [--badge] [--write-badge]
+  ak-docs index [--watch]
   ak-docs query <package|ownership|intent|change> <id> [--agent] [--text]
   ak-docs search <term> [--agent] [--text]
   ak-docs list <packages|intents|changes|knowledge> [--text]
   ak-docs ask [question]          local consult (no LLM)
   ak-docs gate run [gate-id]
   ak-docs mcp
-  ak-docs memory ingest|classify|promote
+  ak-docs mcp install --cursor | --claude
+  ak-docs memory ingest|classify|promote [--pr] [--dry-run]
   ak-docs bootstrap agent-docs
   ak-docs validate-config | validate-handoff <file>
 
@@ -67,7 +82,7 @@ Intelligence (optional AgentsKit peers):
 Advanced / ecosystem:
   ak-docs retrieve <query>
   ak-docs registry topology
-  ak-docs playbook draft
+  ak-docs playbook draft | pattern [--text]
 
 Global flags:
   -h, --help   --version
@@ -112,6 +127,8 @@ const parseArgs = (argv: readonly string[]) => {
   else if (positional[0] === 'index') command = 'index'
   else if (positional[0] === 'gate') command = 'gate'
   else if (positional[0] === 'mcp') command = 'mcp'
+  else if (positional[0] === 'doctor') command = 'doctor'
+  else if (positional[0] === 'demo') command = 'demo'
   else if (positional[0] === 'query') command = 'query'
   else if (positional[0] === 'search') command = 'search'
   else if (positional[0] === 'retrieve') command = 'retrieve'
@@ -201,23 +218,60 @@ const writeTextSearch = (
   ])
 }
 
+const handoffSummaryLines = (
+  index: DocBridgeIndexV1,
+  config: DocBridgeConfigV1,
+  ownerId: string,
+): string[] => {
+  try {
+    const handoff = runQuery(index, config, { kind: 'ownership', id: ownerId, agent: true })
+    if (!handoff || typeof handoff !== 'object' || !('editRoots' in handoff)) return []
+    const payload = handoff as {
+      startHere?: string
+      editRoots?: string[]
+      checks?: string[]
+      humanDoc?: string | null
+      bridge?: { humanDoc?: string; action?: string }
+    }
+    const bridgeLine =
+      payload.bridge?.humanDoc === 'missing'
+        ? `Bridge: human guide missing → ${payload.bridge.action ?? 'ak-docs bootstrap agent-docs'}`
+        : payload.humanDoc
+          ? `Bridge: ${payload.humanDoc}`
+          : 'Bridge: (no human plugin configured)'
+    return [
+      '',
+      'Handoff preview',
+      `  start:  ${payload.startHere ?? '(unknown)'}`,
+      `  edit:   ${(payload.editRoots ?? []).join(', ') || '(none)'}`,
+      `  checks: ${(payload.checks ?? []).join(' · ') || '(none)'}`,
+      `  ${bridgeLine}`,
+    ]
+  } catch {
+    return []
+  }
+}
+
 const writeAsk = (
   question: string,
   matches: ReturnType<typeof searchIndex>,
   index: DocBridgeIndexV1,
+  config: DocBridgeConfigV1,
 ): void => {
   // Prefer ownership match for routing questions
   const owner =
     matches.find((match) => match.type === 'ownership') ??
     matches.find((match) => Boolean(index.lookup?.ownership?.[match.id]))
   const best = owner ?? matches[0]
-  const bestQuery =
-    best && (best.type === 'ownership' || index.lookup?.ownership?.[best.id])
-      ? `ak-docs query ownership ${best.id} --agent`
-      : 'ak-docs list knowledge --text'
+  const ownerId =
+    best && (best.type === 'ownership' || index.lookup?.ownership?.[best.id]) ? best.id : undefined
+  const bestQuery = ownerId
+    ? `ak-docs query ownership ${ownerId} --agent`
+    : 'ak-docs list knowledge --text'
   writeLines([
     `Question: ${question}`,
     best ? `Best match: ${best.type} ${best.id} (${best.path})` : 'Best match: none',
+    ...(ownerId ? handoffSummaryLines(index, config, ownerId) : []),
     '',
     'Matches:',
     ...(
@@ -231,8 +285,9 @@ const writeAsk = (
       ? [
           `ak-docs search "${question}" --agent`,
           bestQuery,
+          ...(ownerId ? [`ak-docs doctor --text`] : []),
         ]
-      : ['ak-docs list knowledge --text']),
+      : ['ak-docs list knowledge --text', 'ak-docs doctor --text']),
   ])
 }
 
@@ -271,7 +326,7 @@ const runAskRepl = async (root: string, config: DocBridgeConfigV1): Promise<numb
           const gateId = value || undefined
           writeJson(runGates(root, config, gateId ? [gateId as GateId] : undefined))
         } else {
-          writeAsk(line, searchIndex(index, line, 8), index)
+          writeAsk(line, searchIndex(index, line, 8), index, config)
         }
       } catch (error) {
         process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
@@ -605,7 +660,9 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
 
   if (command === 'memory') {
     if (!['ingest', 'classify', 'promote'].includes(positional[1] ?? '')) {
-      process.stderr.write('Usage: ak-docs memory <ingest|classify|promote> [--config <path>]\n')
+      process.stderr.write(
+        'Usage: ak-docs memory <ingest|classify|promote> [--pr] [--dry-run] [--force] [--config <path>]\n',
+      )
       return 1
     }
     try {
@@ -622,6 +679,23 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
         return 0
       }
       const draft = draftMemoryPromotion(classifications)
+      if (flags.has('--pr') || flags.has('--github')) {
+        const pr = promoteMemoryToGithubPr(root, draft, {
+          dryRun: flags.has('--dry-run'),
+          force: flags.has('--force'),
+        })
+        if (flags.has('--text')) {
+          writeLines([
+            pr.message,
+            ...(pr.draftPath ? [`Draft: ${pr.draftPath}`] : []),
+            ...(pr.prUrl ? [`PR: ${pr.prUrl}`] : []),
+            ...(pr.commands.length ? ['', 'Commands:', ...pr.commands.map((cmd) => `  ${cmd}`)] : []),
+          ])
+        } else {
+          writeJson({ ...draft, pr })
+        }
+        return pr.ok ? 0 : 1
+      }
       writeJson(draft)
       return draft.ok ? 0 : 1
     } catch (error) {
@@ -640,8 +714,18 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
   }
 
   if (command === 'playbook') {
-    if (positional[1] !== 'draft') {
-      process.stderr.write('Usage: ak-docs playbook draft [--config <path>]\n')
+    const action = positional[1]
+    if (action === 'pattern') {
+      const payload = docBridgePatternPayload()
+      if (flags.has('--text') || wantsTextOutput(flags, { schemaVersion: 1, corpus: { agent: { root: 'docs' } } } as DocBridgeConfigV1)) {
+        process.stdout.write(`${docBridgePatternMarkdown()}\n`)
+      } else {
+        writeJson(payload)
+      }
+      return 0
+    }
+    if (action !== 'draft') {
+      process.stderr.write('Usage: ak-docs playbook draft | pattern [--text] [--config <path>]\n')
       return 1
     }
     try {
@@ -652,6 +736,8 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
         ...draft,
         title: 'Draft Playbook feedback promotion',
         pattern: 'Doc Bridge Pattern',
+        patternDoc: 'docs/playbook/doc-bridge-pattern.md',
+        exportCommand: 'ak-docs playbook pattern --text',
       })
       return 0
     } catch (error) {
@@ -662,7 +748,14 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
 
   if (command === 'index') {
     try {
-      const { config, root } = loadProject(configPath)
+      const { config, root, configPath: loadedConfigPath } = loadProject(configPath)
+      if (flags.has('--watch')) {
+        return watchDocBridgeIndex({
+          root,
+          config,
+          configPath: loadedConfigPath,
+        })
+      }
       const result = buildDocBridgeIndex({ root, config })
       const diagnostics = indexDiagnostics(config, result)
       const handoffCount = Object.keys(result.index.handoffs ?? {}).length
@@ -710,6 +803,34 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
   }
 
   if (command === 'mcp') {
+    if (positional[1] === 'install') {
+      const target = flags.has('--claude') ? 'claude' : flags.has('--cursor') ? 'cursor' : undefined
+      if (!target) {
+        process.stderr.write('Usage: ak-docs mcp install --cursor | --claude\n')
+        return 1
+      }
+      try {
+        const { config, root } = loadProject(configPath)
+        const result = installMcpConfig(root, target)
+        if (wantsTextOutput(flags, config)) {
+          writeLines([
+            `Installed MCP server "${result.serverName}" for ${result.target}`,
+            `Config: ${result.configPath}`,
+            ...(result.created ? ['Created new config file'] : ['Merged into existing config']),
+            '',
+            'Next steps:',
+            ...result.nextSteps.map((step) => `  → ${step}`),
+          ])
+        } else {
+          writeJson({ ...result, snippet: mcpSnippet(root) })
+        }
+        return 0
+      } catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+        return 1
+      }
+    }
+
     try {
       const { config, root } = loadProject(configPath)
       startMcpStdioServer({ root, config })
@@ -720,6 +841,65 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
     }
   }
 
+  if (command === 'doctor') {
+    try {
+      const { config, root } = loadProject(configPath)
+      const report = runDoctor(root, config)
+      if (flags.has('--write-badge')) {
+        const badgePath = resolve(root, '.doc-bridge', 'coverage-badge.json')
+        mkdirSync(dirname(badgePath), { recursive: true })
+        writeFileSync(badgePath, `${formatDoctorBadgeJson(report.badge)}\n`, 'utf8')
+      }
+      if (flags.has('--badge')) {
+        writeLines([formatDoctorBadgeMarkdown(report.badge)])
+        return 0
+      }
+      if (wantsTextOutput(flags, config)) writeLines(formatDoctorText(report))
+      else writeJson(report)
+      return report.ok ? 0 : 1
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+      return 1
+    }
+  }
+
+  if (command === 'demo') {
+    const resolveDemoFixture = (): DemoFixture => {
+      const fixtureFlagIndex = positional.indexOf('--fixture')
+      if (fixtureFlagIndex >= 0) {
+        const value = positional[fixtureFlagIndex + 1]
+        if (value === 'monorepo' || value === 'example') return value
+      }
+      if (flags.has('--monorepo') || positional.includes('monorepo')) return 'monorepo'
+      if (positional[1] === 'monorepo') return 'monorepo'
+      return 'example'
+    }
+    const resolvedFixture = resolveDemoFixture()
+
+    try {
+      const useProject = flags.has('--in-project') || flags.has('--copy-fixture')
+      if (!useProject) {
+        const result = withDemoWorkspace(resolvedFixture, (root, config) =>
+          runDemo(root, config, resolvedFixture),
+        )
+        const textMode =
+          flags.has('--text') || (!flags.has('--json') && !flags.has('--agent'))
+        if (textMode) writeLines(formatDemoText(result))
+        else writeJson(result)
+        return result.ok ? 0 : 1
+      }
+
+      const { config, root } = loadProject(configPath)
+      const result = runDemo(root, config, resolvedFixture, { copyFixture: flags.has('--copy-fixture') })
+      if (wantsTextOutput(flags, config)) writeLines(formatDemoText(result))
+      else writeJson(result)
+      return result.ok ? 0 : 1
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+      return 1
+    }
+  }
+
   if (command === 'query') {
     const kind = positional[1] as QueryKind | undefined
     const id = positional[2]
@@ -889,7 +1069,7 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
         return 1
       }
       const index = loadDocBridgeIndex(root, config)
-      writeAsk(question, searchIndex(index, question, 8), index)
+      writeAsk(question, searchIndex(index, question, 8), index, config)
       return 0
     } catch (error) {
       process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)

package/src/doctor/badge.ts

@@ -0,0 +1,53 @@
+import type { DoctorReport } from './run-doctor.js'
+
+export type DoctorBadgeMetrics = {
+  readonly handoffPct: number
+  readonly bridgePct: number
+  readonly score: number
+  readonly grade: DoctorReport['grade']
+  readonly packages: number
+}
+
+export const doctorBadgeMetrics = (report: DoctorReport): DoctorBadgeMetrics => {
+  const { packages } = report.coverage
+  const handoffPct =
+    packages.total > 0 ? Math.round((packages.withAgentDoc / packages.total) * 100) : 0
+  const bridgePct =
+    packages.total > 0 ? Math.round((packages.withHumanDoc / packages.total) * 100) : 0
+
+  return {
+    handoffPct,
+    bridgePct,
+    score: report.score,
+    grade: report.grade,
+    packages: packages.total,
+  }
+}
+
+const badgeColor = (pct: number): string => {
+  if (pct >= 80) return '2ea44f'
+  if (pct >= 50) return 'dbab09'
+  return 'cb2431'
+}
+
+export const formatDoctorBadgeMarkdown = (metrics: DoctorBadgeMetrics): string => {
+  const handoff = `handoff_coverage-${metrics.handoffPct}%25-${badgeColor(metrics.handoffPct)}`
+  const bridge = `human_bridge-${metrics.bridgePct}%25-${badgeColor(metrics.bridgePct)}`
+  return [
+    `![handoff coverage](https://img.shields.io/badge/${handoff}?style=flat-square)`,
+    `![human bridge](https://img.shields.io/badge/${bridge}?style=flat-square)`,
+    `![doc-bridge score](https://img.shields.io/badge/doc--bridge_score-${metrics.score}%2F100-${badgeColor(metrics.score)}?style=flat-square)`,
+  ].join(' ')
+}
+
+export const formatDoctorBadgeJson = (metrics: DoctorBadgeMetrics): string =>
+  JSON.stringify(
+    {
+      schemaVersion: 1,
+      ...metrics,
+      markdown: formatDoctorBadgeMarkdown(metrics),
+      updatedAt: new Date().toISOString(),
+    },
+    null,
+    2,
+  )

package/src/doctor/run-doctor.ts

@@ -0,0 +1,286 @@
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import { buildDocBridgeIndex } from '../index-builder/build-index.js'
+import { scanAgentCorpus } from '../index-builder/scan-corpus.js'
+import { runGates, type GateRunResult } from '../gates/run-gates.js'
+import { IndexNotFoundError, loadDocBridgeIndex } from '../query/load-index.js'
+import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
+import { doctorBadgeMetrics, type DoctorBadgeMetrics } from './badge.js'
+
+export type DoctorIssue = {
+  readonly severity: 'error' | 'warn' | 'info'
+  readonly code: string
+  readonly message: string
+  readonly action?: string
+}
+
+export type DoctorCoverage = {
+  readonly packages: {
+    readonly total: number
+    readonly withAgentDoc: number
+    readonly withHumanDoc: number
+    readonly missingAgentDoc: readonly string[]
+    readonly missingHumanDoc: readonly string[]
+  }
+  readonly agentDocs: {
+    readonly total: number
+    readonly indexed: number
+    readonly unindexed: readonly string[]
+  }
+  readonly freshness: {
+    readonly ok: boolean
+    readonly message: string
+    readonly hasIndex: boolean
+  }
+  readonly gates: GateRunResult
+}
+
+export type DoctorReport = {
+  readonly ok: boolean
+  readonly score: number
+  readonly grade: 'A' | 'B' | 'C' | 'D' | 'F'
+  readonly coverage: DoctorCoverage
+  readonly badge: DoctorBadgeMetrics
+  readonly issues: readonly DoctorIssue[]
+  readonly nextActions: readonly string[]
+}
+
+const gradeForScore = (score: number): DoctorReport['grade'] => {
+  if (score >= 90) return 'A'
+  if (score >= 75) return 'B'
+  if (score >= 60) return 'C'
+  if (score >= 40) return 'D'
+  return 'F'
+}
+
+const agentDocPaths = (index: DocBridgeIndexV1): Set<string> => {
+  const paths = new Set<string>()
+  for (const owner of Object.values(index.lookup?.ownership ?? {})) {
+    if (owner.agentDoc) paths.add(owner.agentDoc)
+  }
+  for (const handoff of Object.values(index.handoffs ?? {})) {
+    if (handoff.startHere) paths.add(handoff.startHere)
+  }
+  return paths
+}
+
+const computeScore = (coverage: DoctorCoverage): number => {
+  let score = 0
+
+  if (coverage.freshness.hasIndex) score += 15
+  if (coverage.freshness.ok) score += 15
+
+  const { total, withAgentDoc, withHumanDoc } = coverage.packages
+  if (total > 0) {
+    score += Math.round((withAgentDoc / total) * 35)
+    score += Math.round((withHumanDoc / total) * 20)
+  } else if (coverage.agentDocs.indexed > 0) {
+    score += 35
+  }
+
+  if (coverage.gates.ok) score += 15
+  else {
+    const passed = coverage.gates.results.filter((gate) => gate.ok).length
+    const totalGates = coverage.gates.results.length || 1
+    score += Math.round((passed / totalGates) * 10)
+  }
+
+  return Math.min(100, Math.max(0, score))
+}
+
+const buildIssues = (coverage: DoctorCoverage): DoctorIssue[] => {
+  const issues: DoctorIssue[] = []
+
+  if (!coverage.freshness.hasIndex) {
+    issues.push({
+      severity: 'error',
+      code: 'index-missing',
+      message: 'No doc-bridge index found.',
+      action: 'ak-docs index',
+    })
+  } else if (!coverage.freshness.ok) {
+    issues.push({
+      severity: 'error',
+      code: 'index-stale',
+      message: coverage.freshness.message,
+      action: 'ak-docs index',
+    })
+  }
+
+  for (const id of coverage.packages.missingAgentDoc) {
+    issues.push({
+      severity: 'warn',
+      code: 'missing-agent-doc',
+      message: `Package "${id}" has no dedicated agent doc.`,
+      action: `ak-docs init --scaffold-workspaces  # or edit docs/for-agents/packages/${id}.md`,
+    })
+  }
+
+  for (const id of coverage.packages.missingHumanDoc) {
+    issues.push({
+      severity: 'info',
+      code: 'missing-human-doc',
+      message: `Package "${id}" has no linked human guide.`,
+      action: 'ak-docs bootstrap agent-docs',
+    })
+  }
+
+  for (const gate of coverage.gates.results.filter((result) => !result.ok)) {
+    issues.push({
+      severity: gate.id === 'index-freshness' ? 'error' : 'warn',
+      code: `gate-${gate.id}`,
+      message: gate.message,
+      action: gate.id === 'index-freshness' ? 'ak-docs index' : 'ak-docs gate run',
+    })
+  }
+
+  return issues
+}
+
+const buildNextActions = (issues: readonly DoctorIssue[], coverage: DoctorCoverage): string[] => {
+  const actions = new Set<string>()
+  for (const issue of issues) {
+    if (issue.action) actions.add(issue.action)
+  }
+
+  if (!coverage.freshness.hasIndex || !coverage.freshness.ok) {
+    actions.add('ak-docs index')
+  }
+  if (coverage.packages.missingHumanDoc.length) {
+    actions.add('ak-docs bootstrap agent-docs')
+  }
+  if (coverage.packages.total > 0) {
+    const sample =
+      coverage.packages.missingAgentDoc[0] ??
+      coverage.packages.missingHumanDoc[0]
+    if (sample) actions.add(`ak-docs query package ${sample} --agent`)
+  }
+  if (!actions.size) {
+    actions.add('ak-docs mcp install --cursor')
+    actions.add('ak-docs gate run')
+  }
+
+  return [...actions].slice(0, 6)
+}
+
+export const runDoctor = (root: string, config: DocBridgeConfigV1): DoctorReport => {
+  let index: DocBridgeIndexV1 | undefined
+  let hasIndex = true
+  let freshnessOk = false
+  let freshnessMessage = 'Index is fresh'
+
+  try {
+    index = loadDocBridgeIndex(root, config)
+    const next = buildDocBridgeIndex({ root, config, write: false }).index.contentHash
+    freshnessOk = index.contentHash === next
+    freshnessMessage = freshnessOk ? 'Index is fresh' : 'Index is stale. Run: ak-docs index'
+  } catch (error) {
+    if (error instanceof IndexNotFoundError) {
+      hasIndex = false
+      freshnessOk = false
+      freshnessMessage = error.message
+      index = buildDocBridgeIndex({ root, config, write: false }).index
+    } else {
+      throw error
+    }
+  }
+
+  const ownership = Object.entries(index.lookup?.ownership ?? {})
+  const missingAgentDoc = ownership
+    .filter(([, owner]) => !owner.agentDoc || owner.agentDoc === config.corpus.agent.index)
+    .map(([id]) => id)
+  const missingHumanDoc = ownership.filter(([, owner]) => !owner.humanDoc).map(([id]) => id)
+
+  const indexedPaths = new Set(index.knowledge.map((entry) => entry.path))
+  const expectedAgentDocs = agentDocPaths(index)
+  const unindexed = [...expectedAgentDocs].filter((path) => !indexedPaths.has(path))
+
+  const corpusDocs = scanAgentCorpus(root, config).filter(
+    (doc) => doc.path !== config.corpus.agent.index,
+  )
+
+  const gates = runGates(root, config)
+
+  const coverage: DoctorCoverage = {
+    packages: {
+      total: ownership.length,
+      withAgentDoc: ownership.length - missingAgentDoc.length,
+      withHumanDoc: ownership.length - missingHumanDoc.length,
+      missingAgentDoc,
+      missingHumanDoc,
+    },
+    agentDocs: {
+      total: corpusDocs.length,
+      indexed: corpusDocs.filter((doc) => indexedPaths.has(doc.path)).length,
+      unindexed: corpusDocs.filter((doc) => !indexedPaths.has(doc.path)).map((doc) => doc.path),
+    },
+    freshness: {
+      ok: freshnessOk,
+      message: freshnessMessage,
+      hasIndex,
+    },
+    gates,
+  }
+
+  const issues = buildIssues(coverage)
+  const score = computeScore(coverage)
+  const nextActions = buildNextActions(issues, coverage)
+
+  const report: DoctorReport = {
+    ok: issues.every((issue) => issue.severity !== 'error') && gates.ok,
+    score,
+    grade: gradeForScore(score),
+    coverage,
+    badge: { handoffPct: 0, bridgePct: 0, score, grade: gradeForScore(score), packages: 0 },
+    issues,
+    nextActions,
+  }
+  return { ...report, badge: doctorBadgeMetrics(report) }
+}
+
+export const formatDoctorText = (report: DoctorReport): string[] => {
+  const { coverage } = report
+  const handoffPct =
+    coverage.packages.total > 0
+      ? Math.round((coverage.packages.withAgentDoc / coverage.packages.total) * 100)
+      : 0
+  const humanPct =
+    coverage.packages.total > 0
+      ? Math.round((coverage.packages.withHumanDoc / coverage.packages.total) * 100)
+      : 0
+
+  const lines = [
+    'doc-bridge doctor',
+    '─'.repeat(40),
+    `Score: ${report.score}/100 (${report.grade})`,
+    '',
+    'Coverage',
+    `  Packages:        ${coverage.packages.total}`,
+    `  Agent docs:      ${coverage.packages.withAgentDoc}/${coverage.packages.total} (${handoffPct}% handoff-ready)`,
+    `  Human guides:    ${coverage.packages.withHumanDoc}/${coverage.packages.total} (${humanPct}% bridged)`,
+    `  Corpus indexed:  ${coverage.agentDocs.indexed}/${coverage.agentDocs.total} agent docs`,
+    `  Index freshness: ${coverage.freshness.ok ? 'fresh' : 'stale or missing'}`,
+    `  Gates:           ${coverage.gates.results.filter((g) => g.ok).length}/${coverage.gates.results.length} passing`,
+    `  Badge:           handoff ${report.badge.handoffPct}% · bridge ${report.badge.bridgePct}%`,
+  ]
+
+  if (coverage.packages.missingHumanDoc.length) {
+    lines.push('', 'Missing humanDoc (bridge gap)', ...coverage.packages.missingHumanDoc.map((id) => `  • ${id}`))
+  }
+  if (coverage.packages.missingAgentDoc.length) {
+    lines.push('', 'Missing agent doc', ...coverage.packages.missingAgentDoc.map((id) => `  • ${id}`))
+  }
+
+  if (report.issues.length) {
+    lines.push('', 'Issues')
+    for (const issue of report.issues.slice(0, 8)) {
+      const icon = issue.severity === 'error' ? '✗' : issue.severity === 'warn' ? '!' : '·'
+      lines.push(`  ${icon} [${issue.code}] ${issue.message}`)
+    }
+    if (report.issues.length > 8) {
+      lines.push(`  … +${report.issues.length - 8} more`)
+    }
+  }
+
+  lines.push('', 'Next actions', ...report.nextActions.map((action) => `  → ${action}`))
+  return lines
+}