@agentskit/doc-bridge 1.7.45 → 1.9.0

package/src/render/engine.ts

@@ -0,0 +1,398 @@
+import {
+  createEngine,
+  parse,
+  standardFilterMetadata,
+  standardFilters,
+  validateFilters,
+  type ASTNode,
+  type Expression,
+  type FilterContext,
+  type IfNode,
+  type ForNode,
+  type SetNode,
+  type VariableNode,
+} from 'knap'
+
+/**
+ * The template engine behind every Markdown rendering.
+ *
+ * Templates are knap templates: knap's parser produces the AST, knap's validators reject an
+ * unknown filter or a malformed tag before anything is rendered, and knap's own filters run on
+ * the values. What is not knap's is the walk over the AST. knap renders asynchronously — its
+ * evaluator awaits at every node so filters and variable resolvers may be promises — and the
+ * index pipeline that writes `llms.txt`, the conformance profile that re-renders it to check
+ * freshness, and the gates that run both are synchronous. Making them asynchronous to render a
+ * template would change the signature of every artifact writer for a property the templates do
+ * not use: the application computes every variable before rendering, and none of them is a
+ * promise.
+ *
+ * So the evaluator below is a synchronous port of knap's, node for node, including its
+ * whitespace rules — a `for` body is trimmed and joined line by line, `-%}` marks a pending trim
+ * that the next text node consumes — and a test renders every bundled template through knap's
+ * real engine as well and asserts byte-identical output. The port exists to keep the pipeline
+ * synchronous, not to diverge from knap; when the pipeline becomes asynchronous, delete it and
+ * call `renderTemplateWithKnap`.
+ */
+
+export type TemplateVariables = Record<string, unknown>
+
+export class TemplateError extends Error {
+  constructor(
+    message: string,
+    readonly line?: number,
+    readonly column?: number,
+  ) {
+    super(line === undefined ? message : `${message} (line ${line}, column ${column ?? 1})`)
+    this.name = 'TemplateError'
+  }
+}
+
+export type CompiledTemplate = {
+  readonly name: string
+  readonly source: string
+  readonly ast: readonly ASTNode[]
+}
+
+/** Parse and validate a template. A template that references an unknown filter fails here, not mid-render. */
+export const compileTemplate = (source: string, name = 'template'): CompiledTemplate => {
+  const parsed = parse(source)
+  const errors = [...parsed.errors, ...(parsed.errors.length ? [] : validateFilters(parsed.ast, standardFilterMetadata))]
+  const first = errors[0]
+  if (first) throw new TemplateError(`${name}: ${first.message}`, first.line, first.column)
+  return { name, source, ast: parsed.ast }
+}
+
+type RenderState = {
+  variables: TemplateVariables
+  pendingTrimRight: boolean
+  readonly name: string
+}
+
+// --- knap's value semantics, ported verbatim so `{{ x }}` prints what knap would print.
+
+/*
+ * What /[\t ]*\r?\n?$/ did, without the backtracking: a quantified class anchored at the end runs
+ * quadratically on a template line of blanks, and a template is repository input.
+ */
+const trimTrailingWhitespace = (value: string): string => {
+  let end = value.length
+  if (end > 0 && value[end - 1] === '\n') {
+    end -= 1
+    if (end > 0 && value[end - 1] === '\r') end -= 1
+  }
+  while (end > 0 && (value[end - 1] === ' ' || value[end - 1] === '\t')) end -= 1
+  return value.slice(0, end)
+}
+const trimLeadingWhitespace = (value: string): string => value.replace(/^[\t ]*\r?\n?/, '')
+
+const isTruthy = (value: unknown): boolean => {
+  if (value === undefined || value === null) return false
+  if (value === '') return false
+  if (value === 0) return false
+  if (value === false) return false
+  if (Array.isArray(value) && value.length === 0) return false
+  return true
+}
+
+const valueToString = (value: unknown): string => {
+  if (value === undefined || value === null) return ''
+  if (Array.isArray(value) && value.length === 1 && typeof value[0] !== 'object') return String(value[0])
+  if (typeof value === 'object') return JSON.stringify(value)
+  return String(value)
+}
+
+const ownProperty = (value: unknown, key: unknown): { exists: boolean; value: unknown } => {
+  if (value === null || value === undefined || typeof value === 'function' || (typeof key !== 'string' && typeof key !== 'number')) {
+    return { exists: false, value: undefined }
+  }
+  const descriptor = Object.getOwnPropertyDescriptor(Object(value), key)
+  return descriptor && 'value' in descriptor ? { exists: true, value: descriptor.value } : { exists: false, value: undefined }
+}
+
+const getNestedValue = (object: unknown, keys: readonly string[]): unknown => {
+  if (keys.length === 0 || !object) return undefined
+  let value: unknown = object
+  for (const key of keys) {
+    if (value === undefined || value === null) return undefined
+    if (key.includes('[') && key.includes(']')) {
+      const match = key.match(/^([^[]*)\[([^\]]+)\]/)
+      if (match) {
+        const arrayKey = match[1] as string
+        const indexText = match[2] as string
+        const base = arrayKey ? ownProperty(value, arrayKey).value : value
+        if (Array.isArray(base)) value = ownProperty(base, Number.parseInt(indexText, 10)).value
+        else if (base && typeof base === 'object') value = ownProperty(base, indexText.replace(/^["']|["']$/g, '')).value
+        else return undefined
+        continue
+      }
+    }
+    const wrapped = ownProperty(value, `{{${key}}}`).value
+    value = wrapped !== undefined ? wrapped : ownProperty(value, key).value
+  }
+  return value
+}
+
+const resolveVariable = (name: string, variables: TemplateVariables, path: readonly string[] | undefined): unknown => {
+  const trimmed = name.trim()
+  const wrapped = ownProperty(variables, `{{${trimmed}}}`).value
+  if (wrapped !== undefined) return wrapped
+  const direct = ownProperty(variables, trimmed).value
+  if (direct !== undefined) return direct
+  if (trimmed.includes('.')) return getNestedValue(variables, path ?? trimmed.split('.'))
+  return undefined
+}
+
+const evaluateContains = (left: unknown, right: unknown): boolean => {
+  if (left === undefined || left === null) return false
+  if (right === undefined || right === null) return false
+  if (Array.isArray(left)) {
+    return left.some((item) => (typeof item === 'string' && typeof right === 'string' ? item.toLowerCase() === right.toLowerCase() : item == right))
+  }
+  if (typeof left === 'string') {
+    const search = typeof right === 'string' ? right : String(right)
+    return left.toLowerCase().includes(search.toLowerCase())
+  }
+  return false
+}
+
+const isQuotedString = (value: string): boolean => /^["'][\s\S]*["']$/.test(value) || value.includes('":"') || value.includes("':'")
+
+const unwrapGroup = (expression: Expression): Expression => {
+  let current = expression
+  while (current.type === 'group') current = current.expression
+  return current
+}
+
+const isPromiseLike = (value: unknown): value is PromiseLike<unknown> =>
+  typeof value === 'object' && value !== null && typeof (value as { then?: unknown }).then === 'function'
+
+const evaluateExpression = (expression: Expression, state: RenderState): unknown => {
+  switch (expression.type) {
+    case 'literal':
+      return expression.value
+    case 'identifier':
+      return resolveVariable(expression.name, state.variables, expression.path)
+    case 'group':
+      return evaluateExpression(expression.expression, state)
+    case 'member': {
+      const object = evaluateExpression(expression.object, state)
+      const property = evaluateExpression(expression.property, state)
+      if (object === undefined || object === null) return undefined
+      return ownProperty(object, property).value
+    }
+    case 'unary': {
+      const argument = evaluateExpression(expression.argument, state)
+      if (expression.operator === 'not') return !isTruthy(argument)
+      throw new TemplateError(`${state.name}: unknown unary operator "${expression.operator}"`, expression.line, expression.column)
+    }
+    case 'binary': {
+      if (expression.operator === '??') {
+        const left = evaluateExpression(expression.left, state)
+        return isTruthy(left) ? left : evaluateExpression(expression.right, state)
+      }
+      const left = evaluateExpression(expression.left, state)
+      const right = evaluateExpression(expression.right, state)
+      switch (expression.operator) {
+        case '==':
+          return left == right
+        case '!=':
+          return left != right
+        case '>':
+          return (left as number) > (right as number)
+        case '<':
+          return (left as number) < (right as number)
+        case '>=':
+          return (left as number) >= (right as number)
+        case '<=':
+          return (left as number) <= (right as number)
+        case 'contains':
+          return evaluateContains(left, right)
+        case 'and':
+          return isTruthy(left) && isTruthy(right)
+        case 'or':
+          return isTruthy(left) || isTruthy(right)
+        default:
+          throw new TemplateError(`${state.name}: unknown binary operator "${expression.operator}"`, expression.line, expression.column)
+      }
+    }
+    case 'filter':
+      return evaluateFilter(expression, state)
+    default:
+      throw new TemplateError(`${state.name}: unknown expression type "${(expression as { type: string }).type}"`)
+  }
+}
+
+/**
+ * A filter call, exactly as knap makes it: the value is serialised to a string, the arguments to
+ * one parameter string, and knap's own filter function runs on both. A filter that returns a
+ * promise cannot be honoured synchronously and is refused rather than rendered as "[object
+ * Promise]"; none of the standard filters does.
+ */
+const evaluateFilter = (expression: Extract<Expression, { type: 'filter' }>, state: RenderState): unknown => {
+  const value = evaluateExpression(expression.value, state)
+  const args: unknown[] = expression.args.map((argument) => {
+    const evaluated = evaluateExpression(argument, state)
+    return evaluated === undefined && argument.type === 'identifier' ? argument.name : evaluated
+  })
+  const rawArguments = args.map((argument, index) => {
+    const source = unwrapGroup(expression.args[index] as Expression)
+    return source.type === 'literal' ? (source.unquotedValue ?? argument) : argument
+  })
+  const stringValue = valueToString(value)
+  const paramString = args.length
+    ? args
+        .map((argument) => {
+          if (typeof argument === 'string') {
+            if (isQuotedString(argument)) return argument
+            if (/\w\s*=>/.test(argument)) return argument
+            if (/^[\w.:+\-*/]+$/.test(argument)) return argument
+            return `"${argument}"`
+          }
+          return String(argument)
+        })
+        .join(',')
+    : undefined
+  const filter = Object.prototype.hasOwnProperty.call(standardFilters, expression.name) ? standardFilters[expression.name] : undefined
+  if (!filter) return stringValue
+  const context: FilterContext = {
+    variables: state.variables,
+    rawValue: value,
+    rawArguments,
+    allowRegex: true,
+    reportWarning: () => undefined,
+    checkValue: () => undefined,
+    checkLength: () => undefined,
+  }
+  let result: unknown
+  try {
+    result = filter(stringValue, paramString, context)
+  } catch (error) {
+    throw new TemplateError(`${state.name}: filter "${expression.name}" failed: ${error instanceof Error ? error.message : String(error)}`, expression.line, expression.column)
+  }
+  if (isPromiseLike(result)) {
+    throw new TemplateError(`${state.name}: filter "${expression.name}" is asynchronous and cannot be used in a synchronous rendering`, expression.line, expression.column)
+  }
+  return result
+}
+
+const appendNodeOutput = (output: string, nodeOutput: string, node: ASTNode, state: RenderState): string => {
+  let next = output
+  if ('trimLeft' in node && node.trimLeft && next.length > 0) next = trimTrailingWhitespace(next)
+  if (state.pendingTrimRight && nodeOutput.length > 0) {
+    state.pendingTrimRight = false
+    return next + trimLeadingWhitespace(nodeOutput)
+  }
+  return next + nodeOutput
+}
+
+const renderNodes = (nodes: readonly ASTNode[], state: RenderState): string => {
+  let output = ''
+  for (const node of nodes) output = appendNodeOutput(output, renderNode(node, state), node, state)
+  return output
+}
+
+const renderVariable = (node: VariableNode, state: RenderState): string => {
+  const result = valueToString(evaluateExpression(node.expression, state))
+  if (node.trimRight) state.pendingTrimRight = true
+  return result
+}
+
+const renderIf = (node: IfNode, state: RenderState): string => {
+  if (isTruthy(evaluateExpression(node.condition, state))) {
+    const result = renderNodes(node.consequent, state)
+    if (node.trimRight) state.pendingTrimRight = true
+    return result
+  }
+  for (const branch of node.elseifs) {
+    if (isTruthy(evaluateExpression(branch.condition, state))) {
+      const result = renderNodes(branch.body, state)
+      if (node.trimRight) state.pendingTrimRight = true
+      return result
+    }
+  }
+  if (node.alternate) {
+    const result = renderNodes(node.alternate, state)
+    if (node.trimRight) state.pendingTrimRight = true
+    return result
+  }
+  if (node.trimRight) state.pendingTrimRight = true
+  return ''
+}
+
+const renderFor = (node: ForNode, state: RenderState): string => {
+  const iterable = evaluateExpression(node.iterable, state)
+  if (iterable === undefined || iterable === null) {
+    if (node.trimRight) state.pendingTrimRight = true
+    return ''
+  }
+  let items: unknown = iterable
+  if (!Array.isArray(items) && typeof items === 'string') {
+    try {
+      const parsed: unknown = JSON.parse(items)
+      if (Array.isArray(parsed)) items = parsed
+    } catch {
+      // A string that is not a JSON array is reported below, as knap reports it.
+    }
+  }
+  if (!Array.isArray(items)) {
+    throw new TemplateError(`${state.name}: for loop iterable is not an array: ${typeof items}`, node.line, node.column)
+  }
+  const results: string[] = []
+  const length = items.length
+  for (let index = 0; index < length; index += 1) {
+    const loop = { index: index + 1, index0: index, first: index === 0, last: index === length - 1, length }
+    const loopState: RenderState = {
+      ...state,
+      variables: { ...state.variables, [node.iterator]: items[index], [`${node.iterator}_index`]: index, loop },
+    }
+    const result = trimLeadingWhitespace(renderNodes(node.body, loopState))
+    if (result !== '') results.push(result)
+  }
+  if (node.trimRight) state.pendingTrimRight = true
+  return results
+    .map((result, index) => {
+      if (index === results.length - 1) return trimTrailingWhitespace(result)
+      return result.endsWith('\n') ? result : `${result}\n`
+    })
+    .join('')
+}
+
+const renderSet = (node: SetNode, state: RenderState): string => {
+  state.variables[node.variable] = evaluateExpression(node.value, state)
+  if (node.trimRight) state.pendingTrimRight = true
+  return ''
+}
+
+const renderNode = (node: ASTNode, state: RenderState): string => {
+  switch (node.type) {
+    case 'text': {
+      if (!state.pendingTrimRight) return node.value
+      state.pendingTrimRight = false
+      return trimLeadingWhitespace(node.value)
+    }
+    case 'variable':
+      return renderVariable(node, state)
+    case 'if':
+      return renderIf(node, state)
+    case 'for':
+      return renderFor(node, state)
+    case 'set':
+      return renderSet(node, state)
+    default:
+      throw new TemplateError(`${state.name}: unknown node type "${(node as { type: string }).type}"`)
+  }
+}
+
+/** Render a compiled template synchronously. The variables are copied: `{% set %}` never reaches the caller. */
+export const renderCompiledTemplate = (template: CompiledTemplate, variables: TemplateVariables): string =>
+  renderNodes(template.ast, { name: template.name, variables: { ...variables }, pendingTrimRight: false })
+
+export const renderTemplate = (source: string, variables: TemplateVariables, name = 'template'): string =>
+  renderCompiledTemplate(compileTemplate(source, name), variables)
+
+/**
+ * The same template through knap's own engine. Tests hold the synchronous evaluator to this;
+ * a caller that can await may use it directly.
+ */
+export const renderTemplateWithKnap = async (source: string, variables: TemplateVariables): Promise<string> =>
+  createEngine({ filters: standardFilters }).renderOrThrow(source, { variables })

package/src/render/generated.ts

@@ -0,0 +1,77 @@
+import { createHash } from 'node:crypto'
+
+/**
+ * The marker every generated region carries.
+ *
+ * `<!-- doc-bridge:generated hash=… -->` … `<!-- /doc-bridge:generated -->` is what the Markdown
+ * analyzer already recognises (`src/discovery/markdown.ts`): it skips mentions inside the region,
+ * so Doc Bridge never reads its own output back in as evidence about the repository. The hash is
+ * over the region's body, which is what lets the documentation audit tell a regenerated region
+ * from one a person edited by hand: recompute the hash, compare it with the marker.
+ */
+
+export const GENERATED_REGION_HASH_LENGTH = 16
+
+export const GENERATED_REGION_CLOSE = '<!-- /doc-bridge:generated -->'
+
+export const generatedRegionOpen = (hash: string): string => `<!-- doc-bridge:generated hash=${hash} -->`
+
+/**
+ * The hash of a region body. Line endings are normalised first: an editor that converts a file
+ * to CRLF has not changed what the generator wrote.
+ */
+export const generatedRegionHash = (body: string): string =>
+  createHash('sha256').update(body.replace(/\r\n/g, '\n'), 'utf8').digest('hex').slice(0, GENERATED_REGION_HASH_LENGTH)
+
+/**
+ * Strip the blank lines around a region body.
+ *
+ * A loop rather than /\n+$/: a quantified group anchored at the end backtracks quadratically on a
+ * body of newlines, and a rendered body comes from a repository's own template.
+ */
+export const trimRegionBlankLines = (body: string): string => {
+  let start = 0
+  while (start < body.length && body[start] === '\n') start += 1
+  let end = body.length
+  while (end > start && body[end - 1] === '\n') end -= 1
+  return body.slice(start, end)
+}
+
+/** Wrap a body in markers. The body is stripped of surrounding blank lines so the hash covers exactly the lines between the markers. */
+export const wrapGeneratedRegion = (body: string): string => {
+  const inner = trimRegionBlankLines(body)
+  return `${generatedRegionOpen(generatedRegionHash(inner))}\n${inner}\n${GENERATED_REGION_CLOSE}\n`
+}
+
+export type GeneratedRegionRef = {
+  readonly lineStart: number
+  readonly lineEnd: number
+  readonly hash?: string | undefined
+}
+
+export type GeneratedRegionMismatch = {
+  readonly lineStart: number
+  readonly lineEnd: number
+  readonly expected: string
+  readonly actual: string
+}
+
+/**
+ * Which regions of a document no longer hash to what their marker claims.
+ *
+ * The regions come from the analyzer, which is the one detector of markers; this only recomputes
+ * the hash of the lines strictly between the opening and closing marker lines. A region whose
+ * marker carries no hash was written by an older generator and cannot be verified, so it is not
+ * reported.
+ */
+export const verifyGeneratedRegions = (content: string, regions: readonly GeneratedRegionRef[]): GeneratedRegionMismatch[] => {
+  const lines = content.replace(/^/, '').split(/\r?\n/)
+  const mismatches: GeneratedRegionMismatch[] = []
+  for (const region of regions) {
+    if (!region.hash) continue
+    const body = lines.slice(region.lineStart, Math.max(region.lineStart, region.lineEnd - 1)).join('\n')
+    const actual = generatedRegionHash(body)
+    if (actual !== region.hash) mismatches.push({ lineStart: region.lineStart, lineEnd: region.lineEnd, expected: region.hash, actual })
+  }
+  return mismatches
+}

package/src/render/render.ts

@@ -0,0 +1,209 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import { discoverRepository } from '../discovery/repository.js'
+import { buildDocBridgeIndex } from '../index-builder/build-index.js'
+import { renderLlmsTxt } from '../index-builder/llms-txt.js'
+import { toPosix } from '../lib/paths.js'
+import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
+import type { ReconciliationReportV1 } from '../schemas/knowledge.js'
+import { parseDiscoverySnapshot, parseDocBridgeIndex, parseReconciliationReport } from '../validate.js'
+import { loadWorkflowStepOutput } from '../workflow/engine.js'
+import type { TemplateVariables } from './engine.js'
+import {
+  areaPagesView,
+  changeDigestView,
+  overlayReviewView,
+  ownershipPagesView,
+  pageFileName,
+  type OverlayReviewInput,
+  type RenderedPage,
+  type SnapshotForDigest,
+} from './data.js'
+import { GENERATED_REGION_CLOSE, generatedRegionHash, generatedRegionOpen, trimRegionBlankLines } from './generated.js'
+import { renderNamedTemplate, resolveTemplateSource } from './template-source.js'
+import { RENDER_TEMPLATES, type RenderTemplateName } from './templates.js'
+
+/**
+ * `ak-docs render`: the canonical artifacts, rendered as Markdown a person can read.
+ *
+ * Rendering never calls an agent and never reads the Registry: its inputs are the index (built
+ * in memory from the working tree, or the artifact `--data` names), the workflow's last
+ * reconciliation report and snapshot, and an overlay file. Equal inputs, equal bytes.
+ */
+
+export type RenderArtifactOptions = {
+  readonly root: string
+  readonly config: DocBridgeConfigV1
+  readonly template: RenderTemplateName
+  /** An artifact to render instead of the default source for the template. Relative to `root`. */
+  readonly dataPath?: string
+}
+
+export type RenderArtifactResult = {
+  readonly template: RenderTemplateName
+  /** `bundled`, or the project override path. */
+  readonly origin: string
+  readonly pages: readonly RenderedPage[]
+}
+
+/*
+ * A template says where its generated region begins and ends with `{{ region.open }}` and
+ * `{{ region.close }}`. The hash in the opening marker is over the text between them, which is
+ * not known until the template has rendered — so the template prints placeholders, and the
+ * markers replace them afterwards. A template that prints neither is wrapped whole.
+ */
+const OPEN_PLACEHOLDER = '@@doc-bridge:generated-open@@'
+const CLOSE_PLACEHOLDER = '@@doc-bridge:generated-close@@'
+
+export const REGION_VARIABLES = { open: OPEN_PLACEHOLDER, close: CLOSE_PLACEHOLDER } as const
+
+const trimRegionBody = trimRegionBlankLines
+
+export const applyGeneratedRegions = (output: string, name: string): string => {
+  if (!output.includes(OPEN_PLACEHOLDER)) {
+    if (output.includes(CLOSE_PLACEHOLDER)) throw new Error(`template "${name}" prints region.close without region.open`)
+    const body = trimRegionBody(output)
+    return `${generatedRegionOpen(generatedRegionHash(body))}\n${body}\n${GENERATED_REGION_CLOSE}\n`
+  }
+  let result = output
+  for (;;) {
+    const open = result.indexOf(OPEN_PLACEHOLDER)
+    if (open === -1) break
+    const close = result.indexOf(CLOSE_PLACEHOLDER, open)
+    if (close === -1) throw new Error(`template "${name}" prints region.open without a matching region.close`)
+    const body = trimRegionBody(result.slice(open + OPEN_PLACEHOLDER.length, close))
+    const replacement = `${generatedRegionOpen(generatedRegionHash(body))}\n${body}\n${GENERATED_REGION_CLOSE}`
+    result = result.slice(0, open) + replacement + result.slice(close + CLOSE_PLACEHOLDER.length)
+  }
+  if (result.includes(CLOSE_PLACEHOLDER)) throw new Error(`template "${name}" prints region.close without region.open`)
+  return result
+}
+
+const renderPage = (name: RenderTemplateName, variables: TemplateVariables, config: DocBridgeConfigV1, root: string): string => {
+  const output = renderNamedTemplate(name, { ...variables, region: REGION_VARIABLES }, config, root)
+  return RENDER_TEMPLATES[name].generatedRegion ? applyGeneratedRegions(output, name) : output
+}
+
+const readJson = (root: string, path: string): unknown => JSON.parse(readFileSync(resolve(root, path), 'utf8')) as unknown
+
+const stateDirOf = (root: string, config: DocBridgeConfigV1): string => resolve(root, config.workflow?.stateDir ?? '.doc-bridge/workflow')
+
+const loadIndex = (options: RenderArtifactOptions): DocBridgeIndexV1 =>
+  options.dataPath
+    ? parseDocBridgeIndex(readJson(options.root, options.dataPath))
+    : buildDocBridgeIndex({ root: options.root, config: options.config, write: false }).index
+
+/** The last reconciliation report the workflow wrote, when there is one. Findings are optional on a page; a missing report is not an error. */
+const loadReconciliation = (root: string, config: DocBridgeConfigV1): ReconciliationReportV1 | undefined => {
+  try {
+    const value = loadWorkflowStepOutput(stateDirOf(root, config), 'reconcile')
+    return value ? parseReconciliationReport(value) : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The snapshot the digest compares against: the one `--data` names, otherwise the last
+ * `ak-docs scan` (the workflow's `normalize` output). Rendering does not move that baseline —
+ * only a scan does — so the digest can be rendered repeatedly while a change is being reviewed.
+ */
+const loadPreviousSnapshot = (options: RenderArtifactOptions): SnapshotForDigest => {
+  if (options.dataPath) return parseDiscoverySnapshot(readJson(options.root, options.dataPath))
+  let value: unknown
+  try {
+    value = loadWorkflowStepOutput(stateDirOf(options.root, options.config), 'normalize')
+  } catch {
+    value = undefined
+  }
+  if (!value) throw new Error('No previous snapshot to compare against. Run `ak-docs scan` to record one, or pass --data <snapshot.json>.')
+  return parseDiscoverySnapshot(value)
+}
+
+const DEFAULT_OVERLAY_PATH = '.doc-bridge/enrich/overlay.json'
+
+const loadOverlay = (options: RenderArtifactOptions): { readonly overlay: OverlayReviewInput | undefined; readonly source?: string } => {
+  const path = options.dataPath ?? (existsSync(resolve(options.root, DEFAULT_OVERLAY_PATH)) ? DEFAULT_OVERLAY_PATH : undefined)
+  if (!path) return { overlay: undefined }
+  const value = readJson(options.root, path)
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${path} is not an overlay object.`)
+  const pending = (value as { pending?: unknown }).pending
+  if (pending !== undefined && !Array.isArray(pending)) throw new Error(`${path}: "pending" must be an array of proposals.`)
+  return { overlay: value as OverlayReviewInput, source: toPosix(path) }
+}
+
+export const renderArtifact = (options: RenderArtifactOptions): RenderArtifactResult => {
+  const { root, config, template } = options
+  const origin = resolveTemplateSource(template, config, root).origin
+  const page = (path: string, variables: TemplateVariables): RenderedPage => ({ path, content: renderPage(template, variables, config, root) })
+
+  switch (template) {
+    case 'llms.txt': {
+      const index = loadIndex(options)
+      return {
+        template,
+        origin,
+        pages: [{ path: toPosix(config.index?.llmsTxt?.outFile ?? 'llms.txt'), content: renderLlmsTxt(config, index.knowledge, index.project?.name ?? 'project', { root }) }],
+      }
+    }
+    case 'area': {
+      const index = loadIndex(options)
+      const reconciliation = loadReconciliation(root, config)
+      return {
+        template,
+        origin,
+        pages: areaPagesView(index, config, { root, ...(reconciliation ? { reconciliation } : {}) }).map((area) => page(pageFileName(area.path), { area })),
+      }
+    }
+    case 'ownership': {
+      const index = loadIndex(options)
+      return { template, origin, pages: ownershipPagesView(index, config, { root }).map((owner) => page(pageFileName(owner.id), { owner })) }
+    }
+    case 'change-digest': {
+      const previous = loadPreviousSnapshot(options)
+      const current = discoverRepository({ root, config })
+      return { template, origin, pages: [page('change-digest.md', { digest: changeDigestView(previous, current) })] }
+    }
+    case 'overlay-review': {
+      const { overlay, source } = loadOverlay(options)
+      return { template, origin, pages: [page('overlay-review.md', { overlay: overlayReviewView(overlay, source) })] }
+    }
+    default:
+      throw new Error(`Unknown template "${String(template)}".`)
+  }
+}
+
+/**
+ * Write the pages. A single page goes to `target` itself unless `target` is an existing
+ * directory; several pages go under `target` as a directory. Returns what was written, relative
+ * to `root`, in page order.
+ */
+export const writeRenderedPages = (result: RenderArtifactResult, target: string, root: string): string[] => {
+  const single = result.pages.length === 1 && !RENDER_TEMPLATES[result.template].multiPage
+  const written: string[] = []
+  const write = (path: string, content: string): string => {
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, content, 'utf8')
+    return toPosix(relative(root, path))
+  }
+  for (const page of result.pages) {
+    if (!single) {
+      written.push(write(join(target, page.path), page.content))
+      continue
+    }
+    /*
+     * A single page is written to `target` itself, and lands inside it when `target` is already a
+     * directory. The write is what asks: a stat first would decide from one moment on disk and
+     * act in another, and between the two the path can become — or stop being — a directory.
+     */
+    try {
+      written.push(write(target, page.content))
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EISDIR') throw error
+      written.push(write(join(target, page.path), page.content))
+    }
+  }
+  return written
+}