@open-mercato/cli 0.6.8-develop.6961.1.5b7ca407e7 → 0.6.8-develop.6963.1.04a6d320e9

package/src/lib/generators/module-facts.ts

@@ -2419,6 +2419,59 @@ export interface ModuleFactsJsonEntry {
 }
 
 const EMPTY_SECTION_MARKER = '_none_'
+const MAX_ANCHORED_SECTION_BYTES = 32 * 1024
+
+interface ModuleFactsRenderContext {
+  sourceRoot: string
+  sourceLinkPrefix: string
+}
+
+interface ModuleFactsAnchor {
+  title: string
+  offset: number
+  size: string
+  depth: number
+}
+
+interface GroupedTableRows {
+  title: string
+  rows: string[]
+}
+
+function renderGroupedTableSection(
+  sectionHeading: string,
+  header: string,
+  divider: string,
+  groups: readonly GroupedTableRows[],
+): string {
+  const renderedGroups: string[] = []
+  for (const group of groups) {
+    const chunks: string[][] = []
+    let currentRows: string[] = []
+    const renderChunk = (rows: readonly string[], chunkIndex: number): string => {
+      const continuation = chunkIndex === 0 ? '' : ` (continued ${chunkIndex + 1})`
+      return [`### ${group.title}${continuation}`, '', header, divider, ...rows, ''].join('\n')
+    }
+    for (const row of group.rows) {
+      const candidateRows = [...currentRows, row]
+      if (Buffer.byteLength(renderChunk(candidateRows, chunks.length)) <= MAX_ANCHORED_SECTION_BYTES) {
+        currentRows = candidateRows
+        continue
+      }
+      if (currentRows.length === 0) {
+        throw new Error(`[module-facts] ${sectionHeading} group "${group.title}" contains a row larger than the anchored read cap`)
+      }
+      chunks.push(currentRows)
+      currentRows = [row]
+      if (Buffer.byteLength(renderChunk(currentRows, chunks.length)) > MAX_ANCHORED_SECTION_BYTES) {
+        throw new Error(`[module-facts] ${sectionHeading} group "${group.title}" contains a row larger than the anchored read cap`)
+      }
+    }
+    if (currentRows.length > 0) chunks.push(currentRows)
+    renderedGroups.push(...chunks.map((rows, chunkIndex) => renderChunk(rows, chunkIndex)))
+  }
+  return [sectionHeading, '', ...renderedGroups].join('\n').trimEnd()
+}
 
 function renderVersionStamp(
   coreVersion: string | null,
@@ -2432,18 +2485,26 @@ function renderVersionStamp(
   return `<!-- generated from @open-mercato/core ${version} — R1 staleness stamp -->`
 }
 
-function renderEntitiesSection(entities: ModuleEntityFact[], lookup: FactSourceLookup): string {
+function renderEntitiesSection(
+  entities: ModuleEntityFact[],
+  lookup: FactSourceLookup,
+  context: ModuleFactsRenderContext,
+): string {
   if (entities.length === 0) return `## Entities\n\n${EMPTY_SECTION_MARKER}`
   const header = '| Entity ID | Class | Table | Editable | CustomFields | Source |'
   const divider = '|---|---|---|---|---|---|'
   const rows = entities.map(
     (entity) =>
-      `| ${entity.id} | ${entity.class} | ${entity.table} | ${entity.editable ? 'yes' : 'no'} | ${entity.customFields ? 'yes' : 'no'} | ${renderLookedUpSource(lookup, 'entity', entity.id)} |`,
+      `| ${entity.id} | ${entity.class} | ${entity.table} | ${entity.editable ? 'yes' : 'no'} | ${entity.customFields ? 'yes' : 'no'} | ${renderLookedUpSource(lookup, 'entity', entity.id, context)} |`,
   )
   return ['## Entities', '', header, divider, ...rows].join('\n')
 }
 
-function renderEventsSection(events: ModuleEventFact[], lookup: FactSourceLookup): string {
+function renderEventsSection(
+  events: ModuleEventFact[],
+  lookup: FactSourceLookup,
+  context: ModuleFactsRenderContext,
+): string {
   const heading = `## Events  (${events.length})`
   if (events.length === 0) return `${heading}\n\n${EMPTY_SECTION_MARKER}`
   const header = '| ID | Category | Entity | Browser transport | Source |'
@@ -2451,7 +2512,7 @@ function renderEventsSection(events: ModuleEventFact[], lookup: FactSourceLookup
   const rows = events.map((event) => {
     const transports = [event.clientBroadcast ? 'client' : null, event.portalBroadcast ? 'portal' : null]
       .filter((value): value is string => value !== null)
-    return `| ${event.id} | ${event.category ?? '—'} | ${event.entity ?? '—'} | ${transports.join(', ') || '—'} | ${renderLookedUpSource(lookup, 'event', event.id)} |`
+    return `| ${event.id} | ${event.category ?? '—'} | ${event.entity ?? '—'} | ${transports.join(', ') || '—'} | ${renderLookedUpSource(lookup, 'event', event.id, context)} |`
   })
   return [heading, '', header, divider, ...rows].join('\n')
 }
@@ -2467,9 +2528,10 @@ function renderSourceLinkedListSection(
   lookup: FactSourceLookup,
   kind: ModuleFactSourceKind,
   idColumnLabel: string,
+  context: ModuleFactsRenderContext,
 ): string {
   if (values.length === 0) return `${heading}\n\n${EMPTY_SECTION_MARKER}`
-  const rows = values.map((value) => `| ${value} | ${renderLookedUpSource(lookup, kind, value)} |`)
+  const rows = values.map((value) => `| ${value} | ${renderLookedUpSource(lookup, kind, value, context)} |`)
   return [heading, '', `| ${idColumnLabel} | Source |`, '|---|---|', ...rows].join('\n')
 }
 
@@ -2484,22 +2546,37 @@ export function isExactSourceFilePath(sourcePath: string): boolean {
   return MODULE_CODE_EXTENSIONS.some((extension) => sourcePath.endsWith(extension))
 }
 
-function renderSourceLink(sourcePath: string): string {
+function renderSourceLabel(sourcePath: string, sourceRoot: string, line?: number): string {
+  const relativeSourcePath = sourcePath.startsWith(`${sourceRoot}/`)
+    ? sourcePath.slice(sourceRoot.length + 1)
+    : sourcePath
+  return line ? `${relativeSourcePath}:${line}` : relativeSourcePath
+}
+
+function renderSourceLink(sourcePath: string, context?: ModuleFactsRenderContext): string {
   if (!isExactSourceFilePath(sourcePath)) return sourcePath
-  return `[${sourcePath}](../../../${sourcePath})`
+  const label = context ? renderSourceLabel(sourcePath, context.sourceRoot) : sourcePath
+  return `[${label}](${context?.sourceLinkPrefix ?? '../../../'}${sourcePath})`
 }
 
-function renderSourceRefLink(source: ModuleFactSourceRef): string {
+function renderSourceRefLink(source: ModuleFactSourceRef, context: ModuleFactsRenderContext): string {
   const anchor = source.line ? `#L${source.line}` : ''
-  const label = source.line ? `${source.sourcePath}:${source.line}` : source.sourcePath
-  if (!isExactSourceFilePath(source.sourcePath)) return label
-  return `[${label}](../../../${source.sourcePath}${anchor})`
+  if (!isExactSourceFilePath(source.sourcePath)) {
+    return source.line ? `${source.sourcePath}:${source.line}` : source.sourcePath
+  }
+  const label = renderSourceLabel(source.sourcePath, context.sourceRoot, source.line)
+  return `[${label}](${context.sourceLinkPrefix}${source.sourcePath}${anchor})`
 }
 
 
-function renderLookedUpSource(lookup: FactSourceLookup, kind: ModuleFactSourceKind, id: string): string {
+function renderLookedUpSource(
+  lookup: FactSourceLookup,
+  kind: ModuleFactSourceKind,
+  id: string,
+  context: ModuleFactsRenderContext,
+): string {
   const source = lookup(kind, id)
-  return source ? renderSourceRefLink(source) : '—'
+  return source ? renderSourceRefLink(source, context) : '—'
 }
 
 function renderSafeScalar(value: ModuleFactSafeScalar | ModuleFactSafeScalar[] | undefined): string {
@@ -2518,19 +2595,23 @@ function renderOwnedContractMetadata(metadata: ModuleOwnedContractFact['metadata
 function renderOwnedContractSection(
   heading: string,
   facts: readonly ModuleOwnedContractFact[] | undefined,
+  context: ModuleFactsRenderContext,
 ): string {
   if (!facts || facts.length === 0) return ''
   const rows = facts.map(
-    (fact) => `| ${fact.id} | ${renderOwnedContractMetadata(fact.metadata)} | ${renderSourceRefLink(fact.source)} |`,
+    (fact) => `| ${fact.id} | ${renderOwnedContractMetadata(fact.metadata)} | ${renderSourceRefLink(fact.source, context)} |`,
   )
   return [heading, '', '| ID | Metadata | Source |', '|---|---|---|', ...rows].join('\n')
 }
 
-function renderDiRegistrationsSection(facts: readonly ModuleOwnedContractFact[] | undefined): string {
+function renderDiRegistrationsSection(
+  facts: readonly ModuleOwnedContractFact[] | undefined,
+  context: ModuleFactsRenderContext,
+): string {
   if (!facts || facts.length === 0) return ''
   const rows = facts.map((fact) => {
     const metadata = fact.metadata ?? {}
-    return `| ${fact.id} | ${renderSafeScalar(metadata.registrationKind)} | ${renderSafeScalar(metadata.lifetime)} | ${renderSafeScalar(metadata.injectionMode)} | ${renderSafeScalar(metadata.providerSymbol)} | ${renderSourceRefLink(fact.source)} |`
+    return `| ${fact.id} | ${renderSafeScalar(metadata.registrationKind)} | ${renderSafeScalar(metadata.lifetime)} | ${renderSafeScalar(metadata.injectionMode)} | ${renderSafeScalar(metadata.providerSymbol)} | ${renderSourceRefLink(fact.source, context)} |`
   })
   return [
     '## DI registrations (rich)',
@@ -2561,12 +2642,12 @@ function renderApiRouteAuthCell(route: ModuleApiRouteFact): string {
   return groups.map((group) => `${group.methods.join('/')} → ${group.label}`).join(' · ')
 }
 
-function renderApiRoutesSection(routes: ModuleApiRouteFact[]): string {
+function renderApiRoutesSection(routes: ModuleApiRouteFact[], context: ModuleFactsRenderContext): string {
   if (routes.length === 0) return `## API routes\n\n${EMPTY_SECTION_MARKER}`
   const header = '| Path | Methods | Auth (per-method requireFeatures) | Source |'
   const divider = '|---|---|---|---|'
   const rows = routes.map(
-    (route) => `| ${route.path} | ${route.methods.join(' ')} | ${renderApiRouteAuthCell(route)} | ${route.sourcePath ? renderSourceLink(route.sourcePath) : '—'} |`,
+    (route) => `| ${route.path} | ${route.methods.join(' ')} | ${renderApiRouteAuthCell(route)} | ${route.sourcePath ? renderSourceLink(route.sourcePath, context) : '—'} |`,
   )
   return ['## API routes', '', header, divider, ...rows].join('\n')
 }
@@ -2574,13 +2655,17 @@ function renderApiRoutesSection(routes: ModuleApiRouteFact[]): string {
 function renderLinkedFactsSection(
   heading: string,
   facts: ReadonlyArray<{ label: string; sourcePath: string }>,
+  context: ModuleFactsRenderContext,
 ): string {
   if (facts.length === 0) return `${heading}\n\n${EMPTY_SECTION_MARKER}`
-  const rows = facts.map((fact) => `| ${fact.label} | ${renderSourceLink(fact.sourcePath)} |`)
+  const rows = facts.map((fact) => `| ${fact.label} | ${renderSourceLink(fact.sourcePath, context)} |`)
   return [heading, '', '| ID / path | Source |', '|---|---|', ...rows].join('\n')
 }
 
 function renderHostTokensSection(hostTokens: ModuleHostTokens): string {
+  if (hostTokens.entityIds.length === 0 && hostTokens.tableIds.length === 0) {
+    return `## Host extension points\n\n${EMPTY_SECTION_MARKER}`
+  }
   const entityIdsLine = hostTokens.entityIds.length > 0 ? hostTokens.entityIds.join(' · ') : EMPTY_SECTION_MARKER
   const tableIdsLine = hostTokens.tableIds.length > 0 ? hostTokens.tableIds.join(' · ') : EMPTY_SECTION_MARKER
   return ['## Host extension points', '', `- Entity IDs: ${entityIdsLine}`, `- Table IDs: ${tableIdsLine}`].join('\n')
@@ -2590,24 +2675,38 @@ function renderExtensionHostContext(host: ModuleExtensionSurfaceFacts['hosts'][n
   return host.contextContract ?? host.runtimeContract ?? host.scopeContract ?? '—'
 }
 
-function renderExtensionHostSource(host: ModuleExtensionHostFact): string {
+function renderExtensionHostSource(host: ModuleExtensionHostFact, context: ModuleFactsRenderContext): string {
   if (host.source.kind === 'fact-ref') return `${host.source.factSection}:${host.source.factKey}`
-  return renderSourceRefLink({ sourcePath: host.source.path })
+  return renderSourceRefLink({ sourcePath: host.source.path }, context)
 }
 
-function renderExtensionHostsSection(extensionSurfaces: ModuleExtensionSurfaceFacts): string {
+function renderExtensionHostsSection(
+  extensionSurfaces: ModuleExtensionSurfaceFacts,
+  context: ModuleFactsRenderContext,
+): string {
   const boundHosts = extensionSurfaces.hosts.filter((host) => host.bound)
   if (boundHosts.length === 0) return `## UMES hosts\n\n${EMPTY_SECTION_MARKER}`
-  const rows = boundHosts.map((host) =>
-    `| ${host.id} | ${host.family} | ${host.capabilities.join(', ') || '—'} | ${renderExtensionHostContext(host)} | ${host.stability.toUpperCase()} | ${renderExtensionHostSource(host)} |`,
-  )
-  return [
+  const header = [
     '## UMES hosts',
     '',
     '| ID / pattern | Family | Supports | Context | Stability | Source |',
     '|---|---|---|---|---|---|',
-    ...rows,
-  ].join('\n')
+  ]
+  const renderRows = (hosts: readonly ModuleExtensionHostFact[]) => hosts.map((host) =>
+    `| ${host.id} | ${host.family} | ${host.capabilities.join(', ') || '—'} | ${renderExtensionHostContext(host)} | ${host.stability.toUpperCase()} | ${renderExtensionHostSource(host, context)} |`,
+  )
+  const compact = [...header, ...renderRows(boundHosts)].join('\n')
+  if (Buffer.byteLength(compact) <= MAX_ANCHORED_SECTION_BYTES) return compact
+  const families = [...new Set(boundHosts.map((host) => host.family))]
+  return renderGroupedTableSection(
+    '## UMES hosts',
+    '| ID / pattern | Family | Supports | Context | Stability | Source |',
+    '|---|---|---|---|---|---|',
+    families.map((family) => ({
+      title: family,
+      rows: renderRows(boundHosts.filter((host) => host.family === family)),
+    })),
+  )
 }
 
 function compactContributionDetails(contribution: ModuleExtensionContributionFact): string {
@@ -2627,13 +2726,16 @@ function compactContributionDetails(contribution: ModuleExtensionContributionFac
   }).join('; ')
 }
 
-function renderExtensionContributionsSection(extensionSurfaces: ModuleExtensionSurfaceFacts): string {
+function renderExtensionContributionsSection(
+  extensionSurfaces: ModuleExtensionSurfaceFacts,
+  context: ModuleFactsRenderContext,
+): string {
   if (extensionSurfaces.contributions.length === 0) return `## UMES contributions\n\n${EMPTY_SECTION_MARKER}`
   const rows = extensionSurfaces.contributions.map((contribution) => {
     const targets = contribution.targets.map((entry) => entry.id).join(', ')
     const resolution = contribution.targets.map((entry) => entry.resolution).join(', ')
     const phases = [...(contribution.phases ?? []), ...(contribution.operations ?? [])].join(', ') || '—'
-    const source = renderSourceRefLink({ sourcePath: contribution.source.path })
+    const source = renderSourceRefLink({ sourcePath: contribution.source.path }, context)
     return `| ${contribution.id} | ${contribution.kind} | ${targets || '—'} | ${phases} | ${compactContributionDetails(contribution)} | ${resolution || '—'} | ${source} |`
   })
   return [
@@ -2661,12 +2763,15 @@ function renderExtensionTargetRef(target: ModuleExtensionTargetRef): string {
   return `${target.kind}:${target.id}${method}${owner}`
 }
 
-function renderActivationBindingsSection(extensionSurfaces: ModuleExtensionSurfaceFacts): string {
+function renderActivationBindingsSection(
+  extensionSurfaces: ModuleExtensionSurfaceFacts,
+  context: ModuleFactsRenderContext,
+): string {
   const activations = extensionSurfaces.activations ?? []
   if (activations.length === 0) return `## Active extension bindings\n\n${EMPTY_SECTION_MARKER}`
   const rows = activations.map((activation) => {
     const phases = activation.phases && activation.phases.length > 0 ? activation.phases.join(', ') : '—'
-    const source = activation.source ? renderSourceRefLink(activation.source) : '—'
+    const source = activation.source ? renderSourceRefLink(activation.source, context) : '—'
     const bridge = activation.bridge ? `${activation.bridge.factSection}:${activation.bridge.factKey}` : '—'
     return `| ${activation.id} | ${activation.kind} | ${renderExtensionTargetRef(activation.host)} | ${activation.contributionKinds.join(', ') || '—'} | ${phases} | ${bridge} | ${source} |`
   })
@@ -2679,12 +2784,15 @@ function renderActivationBindingsSection(extensionSurfaces: ModuleExtensionSurfa
   ].join('\n')
 }
 
-function renderIncomingContributionsSection(extensionSurfaces: ModuleExtensionSurfaceFacts): string {
+function renderIncomingContributionsSection(
+  extensionSurfaces: ModuleExtensionSurfaceFacts,
+  context: ModuleFactsRenderContext,
+): string {
   const incoming = extensionSurfaces.incoming ?? []
   if (incoming.length === 0) return `## Incoming installed contributions\n\n${EMPTY_SECTION_MARKER}`
   const rows = incoming.map((entry) => {
     const activation = entry.activationId ?? '—'
-    const source = entry.source ? renderSourceRefLink(entry.source) : '—'
+    const source = entry.source ? renderSourceRefLink(entry.source, context) : '—'
     return `| ${entry.contributorModuleId} | ${entry.contributionKind} | ${renderExtensionTargetRef(entry.target)} | ${entry.resolution} | ${activation} | ${entry.contributionId} · ${source} |`
   })
   return [
@@ -2699,12 +2807,13 @@ function renderIncomingContributionsSection(extensionSurfaces: ModuleExtensionSu
 function renderContributionResolutionsSection(
   extensionSurfaces: ModuleExtensionSurfaceFacts,
   lookup: FactSourceLookup,
+  context: ModuleFactsRenderContext,
 ): string {
   const resolutions = extensionSurfaces.contributionResolutions ?? []
   if (resolutions.length === 0) return `## Contribution resolutions\n\n${EMPTY_SECTION_MARKER}`
   const rows = resolutions.map((resolution) => {
     const activations = resolution.activationIds.length > 0 ? resolution.activationIds.join(', ') : '—'
-    const source = renderLookedUpSource(lookup, 'extension-contribution', resolution.contributionId)
+    const source = renderLookedUpSource(lookup, 'extension-contribution', resolution.contributionId, context)
     return `| ${resolution.contributionId} | ${renderExtensionTargetRef(resolution.target)} | ${resolution.resolution} | ${activations} | ${source} |`
   })
   return [
@@ -2726,17 +2835,31 @@ function renderOverrideTargetPath(target: ModuleOverrideTarget): string {
   return display
 }
 
-function renderOverrideTargetsSection(targets: readonly ModuleOverrideTarget[] | undefined): string {
+function renderOverrideTargetsSection(
+  targets: readonly ModuleOverrideTarget[] | undefined,
+  context: ModuleFactsRenderContext,
+): string {
   if (!targets || targets.length === 0) return `## Exact override targets\n\n${EMPTY_SECTION_MARKER}`
   const header = '| Domain | Path / key | Supported modes | Referenced fact | Source |'
   const divider = '|---|---|---|---|---|'
-  const rows = targets.map((target) => {
+  const renderRows = (group: readonly ModuleOverrideTarget[]) => group.map((target) => {
     const path = `\`${renderOverrideTargetPath(target)}\``
     const modes = target.modes.join(', ') || '—'
     const fact = `${target.factRef.factSection}:${target.factRef.factKey}`
-    return `| ${target.domain} | ${path} | ${modes} | ${fact} | ${renderSourceRefLink(target.source)} |`
+    return `| ${target.domain} | ${path} | ${modes} | ${fact} | ${renderSourceRefLink(target.source, context)} |`
   })
-  return ['## Exact override targets', '', header, divider, ...rows].join('\n')
+  const compact = ['## Exact override targets', '', header, divider, ...renderRows(targets)].join('\n')
+  if (Buffer.byteLength(compact) <= MAX_ANCHORED_SECTION_BYTES) return compact
+  const domains = [...new Set(targets.map((target) => target.domain))]
+  return renderGroupedTableSection(
+    '## Exact override targets',
+    header,
+    divider,
+    domains.map((domain) => ({
+      title: domain,
+      rows: renderRows(targets.filter((target) => target.domain === domain)),
+    })),
+  )
 }
 
 export interface ReferenceProjectionFingerprints {
@@ -2744,6 +2867,18 @@ export interface ReferenceProjectionFingerprints {
   taxonomyFingerprint: string
 }
 
+export interface ModuleFactsMarkdownSection {
+  slug: string
+  title: string
+  description: string
+  markdown: string
+}
+
+export interface ModuleFactsMarkdownDirectory {
+  index: string
+  sections: ModuleFactsMarkdownSection[]
+}
+
 /**
  * Header for a `local-reference` projection. It never claims a package version — the
  * module is app-local — and it states in the document itself that the activations and
@@ -2762,86 +2897,225 @@ function renderReferenceProjectionHeader(
   ]
 }
 
-export function renderModuleFactsMarkdown(
+function buildModuleFactsSections(
   facts: ModuleFacts,
-  referenceProjection?: ReferenceProjectionFingerprints,
-): string {
+  context: ModuleFactsRenderContext,
+): string[] {
   const extensionSurfaces = facts.extensionSurfaces ?? { hosts: [], contributions: [], unresolved: [] }
   const lookup = buildFactSourceLookup(facts)
-  const header = facts.sourceKind === 'local-reference' && referenceProjection
-    ? renderReferenceProjectionHeader(facts, referenceProjection)
-    : [
-        `# ${facts.module} — module facts (generated, do not edit)`,
-        renderVersionStamp(facts.coreVersion, facts.sourcePackage, facts.sourceVersion),
-        `Source root: ${renderSourceLink(facts.sourceRoot)}`,
-      ]
   const sections = [
-    ...header,
-    '',
-    renderEntitiesSection(facts.entities, lookup),
-    '',
-    renderEventsSection(facts.events, lookup),
-    '',
+    renderEntitiesSection(facts.entities, lookup, context),
+    renderEventsSection(facts.events, lookup, context),
     renderSourceLinkedListSection(
       `## ACL features  (${facts.aclFeatures.length})`,
       facts.aclFeatures,
       lookup,
       'acl-feature',
       'Feature',
+      context,
     ),
-    '',
-    renderApiRoutesSection(facts.apiRoutes),
-    '',
-    renderLinkedFactsSection('## Backend pages', facts.backendPages.map((page) => ({ label: page.path, sourcePath: page.sourcePath }))),
-    '',
-    renderLinkedFactsSection('## Frontend pages', facts.frontendPages.map((page) => ({ label: page.path, sourcePath: page.sourcePath }))),
-    '',
-    renderSourceLinkedListSection('## DI service tokens', facts.diTokens, lookup, 'di-registration', 'Token'),
-    '',
-    renderSourceLinkedListSection('## Search entities', facts.searchEntities, lookup, 'search', 'Entity ID'),
-    '',
+    renderApiRoutesSection(facts.apiRoutes, context),
+    renderLinkedFactsSection(
+      '## Backend pages',
+      facts.backendPages.map((page) => ({ label: page.path, sourcePath: page.sourcePath })),
+      context,
+    ),
+    renderLinkedFactsSection(
+      '## Frontend pages',
+      facts.frontendPages.map((page) => ({ label: page.path, sourcePath: page.sourcePath })),
+      context,
+    ),
+    renderSourceLinkedListSection('## DI service tokens', facts.diTokens, lookup, 'di-registration', 'Token', context),
+    renderSourceLinkedListSection('## Search entities', facts.searchEntities, lookup, 'search', 'Entity ID', context),
     renderHostTokensSection(facts.hostTokens),
+    renderExtensionHostsSection(extensionSurfaces, context),
+    renderExtensionContributionsSection(extensionSurfaces, context),
+    renderActivationBindingsSection(extensionSurfaces, context),
+    renderIncomingContributionsSection(extensionSurfaces, context),
+    renderContributionResolutionsSection(extensionSurfaces, lookup, context),
+    renderExtensionDiagnosticsSection(extensionSurfaces),
+    renderSourceLinkedListSection('## Notifications', facts.notifications, lookup, 'notification', 'Notification ID', context),
+    renderLinkedFactsSection(
+      '## CLI commands',
+      facts.cliCommands.map((command) => ({ label: command.command, sourcePath: command.sourcePath })),
+      context,
+    ),
+    renderLinkedFactsSection(
+      '## AI tools / MCP capabilities',
+      facts.aiTools.map((tool) => ({ label: tool.name, sourcePath: tool.sourcePath })),
+      context,
+    ),
+    renderLinkedFactsSection(
+      '## AI agents',
+      facts.aiAgents.map((agent) => ({ label: agent.id, sourcePath: agent.sourcePath })),
+      context,
+    ),
+    renderOverrideTargetsSection(facts.overrideTargets, context),
+  ].filter((section) => section.length > 0)
+  const owned = facts.ownedContracts ?? {}
+  sections.push(...[
+    renderOwnedContractSection('## Owned contract — module metadata', owned['module-metadata'], context),
+    renderOwnedContractSection('## Domain commands', owned.command, context),
+    renderOwnedContractSection('## Workers', owned.worker, context),
+    renderOwnedContractSection('## Page middleware', owned['page-middleware'], context),
+    renderOwnedContractSection('## Setup', owned.setup, context),
+    renderOwnedContractSection('## Encryption', owned.encryption, context),
+    renderDiRegistrationsSection(owned['di-registration'], context),
+    renderOwnedContractSection('## Custom entities', owned['custom-entity'], context),
+    renderOwnedContractSection('## AI extensions', owned['ai-extension'], context),
+    renderOwnedContractSection('## Generator plugins', owned['generator-plugin'], context),
+  ].filter((section) => section.length > 0))
+  return sections
+}
+
+function sectionTitle(section: string): string {
+  return section.split('\n', 1)[0].replace(/^## /, '').replace(/\s+\(\d+\)\s*$/, '')
+}
+
+function sectionSlug(title: string): string {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+function approximateSize(markdown: string): string {
+  return `~${Math.max(1, Math.ceil(Buffer.byteLength(markdown) / 1024))} KB`
+}
+
+function collectSectionAnchors(sections: readonly string[]): ModuleFactsAnchor[] {
+  const anchors: ModuleFactsAnchor[] = []
+  let sectionOffset = 0
+  for (const section of sections) {
+    const lines = section.split('\n')
+    anchors.push({ title: sectionTitle(section), offset: sectionOffset, size: approximateSize(section), depth: 0 })
+    for (let index = 0; index < lines.length; index += 1) {
+      if (lines[index].startsWith('### ')) {
+        const nextSubheading = lines.slice(index + 1).findIndex((line) => line.startsWith('### '))
+        const end = nextSubheading === -1 ? lines.length : index + 1 + nextSubheading
+        anchors.push({
+          title: `${sectionTitle(section)} / ${lines[index].slice(4)}`,
+          offset: sectionOffset + index,
+          size: approximateSize(lines.slice(index, end).join('\n')),
+          depth: 1,
+        })
+      }
+    }
+    sectionOffset += lines.length + 1
+  }
+  return anchors
+}
+
+function renderSectionedMarkdown(
+  facts: ModuleFacts,
+  header: readonly string[],
+  sections: readonly string[],
+): string {
+  const anchors = collectSectionAnchors(sections)
+  const indexLineCount = 6 + anchors.length
+  const firstSectionLine = header.length + indexLineCount + 1
+  const contents = anchors.map((anchor) => {
+    const prefix = anchor.depth === 1 ? '  ' : ''
+    return `${prefix}- ${anchor.title} — L${firstSectionLine + anchor.offset}, ${anchor.size}`
+  })
+  return [
+    ...header,
     '',
-    renderExtensionHostsSection(extensionSurfaces),
-    '',
-    renderExtensionContributionsSection(extensionSurfaces),
+    '## Contents',
     '',
-    renderActivationBindingsSection(extensionSurfaces),
+    ...contents,
     '',
-    renderIncomingContributionsSection(extensionSurfaces),
+    'Read caps: a read that does not reach the end-of-facts marker was truncated — re-read the missing sections by their line anchors.',
     '',
-    renderContributionResolutionsSection(extensionSurfaces, lookup),
+    sections.join('\n\n'),
     '',
-    renderExtensionDiagnosticsSection(extensionSurfaces),
+    `<!-- end module facts: ${facts.module} — ${sections.length} sections -->`,
     '',
-    renderSourceLinkedListSection('## Notifications', facts.notifications, lookup, 'notification', 'Notification ID'),
+  ].join('\n')
+}
+
+/**
+ * @deprecated Superseded by {@link renderModuleFactsDirectory}, which both build
+ * pipelines write. The hrefs rendered here assume the retired flat
+ * `.ai/guides/modules/<id>.md` location and resolve one path segment short of the
+ * shipped `<id>/index.md` layout. Retained so existing callers keep working.
+ */
+export function renderModuleFactsMarkdown(
+  facts: ModuleFacts,
+  referenceProjection?: ReferenceProjectionFingerprints,
+): string {
+  const header = facts.sourceKind === 'local-reference' && referenceProjection
+    ? renderReferenceProjectionHeader(facts, referenceProjection)
+    : [
+        `# ${facts.module} — module facts (generated, do not edit)`,
+        renderVersionStamp(facts.coreVersion, facts.sourcePackage, facts.sourceVersion),
+        `Source root: ${renderSourceLink(facts.sourceRoot)}`,
+      ]
+  const context = { sourceRoot: facts.sourceRoot, sourceLinkPrefix: '../../../' }
+  return renderSectionedMarkdown(facts, header, buildModuleFactsSections(facts, context))
+}
+
+export function renderModuleFactsDirectory(
+  facts: ModuleFacts,
+  referenceProjection?: ReferenceProjectionFingerprints,
+): ModuleFactsMarkdownDirectory {
+  const header = facts.sourceKind === 'local-reference' && referenceProjection
+    ? renderReferenceProjectionHeader(facts, referenceProjection)
+    : [
+        `# ${facts.module} — module facts (generated, do not edit)`,
+        renderVersionStamp(facts.coreVersion, facts.sourcePackage, facts.sourceVersion),
+        `Source root: ${facts.sourceRoot}`,
+      ]
+  const context = { sourceRoot: facts.sourceRoot, sourceLinkPrefix: '../../../../' }
+  const renderedSections = buildModuleFactsSections(facts, context)
+    .filter((section) => !section.endsWith(`\n\n${EMPTY_SECTION_MARKER}`))
+  const sectionEntries = renderedSections.map((section) => {
+    const title = sectionTitle(section)
+    const slug = sectionSlug(title)
+    const markdown = [
+      `# ${facts.module} — ${title}`,
+      '',
+      '[Back to module index](index.md)',
+      '',
+      section,
+      '',
+      `<!-- end module facts section: ${facts.module}/${slug} -->`,
+      '',
+    ].join('\n')
+    const subsections = collectSectionAnchors([section])
+      .filter((anchor) => anchor.depth === 1)
+      .map((anchor) => ({ ...anchor, line: anchor.offset + 5 }))
+    return {
+      section: {
+        slug,
+        title,
+        description: `Generated ${title.toLowerCase()} facts for ${facts.module}.`,
+        markdown,
+      },
+      subsections,
+    }
+  })
+  const sections = sectionEntries.map((entry) => entry.section)
+  const sectionLinks = sectionEntries.flatMap(({ section, subsections }) => [
+    `- [${section.title}](${section.slug}.md) — ${approximateSize(section.markdown)} — ${section.description}`,
+    ...subsections.map((anchor) =>
+      `  - ${anchor.title} — ${section.slug}.md:L${anchor.line}, ${anchor.size}`,
+    ),
+  ])
+  const index = [
+    ...header,
     '',
-    renderLinkedFactsSection('## CLI commands', facts.cliCommands.map((command) => ({ label: command.command, sourcePath: command.sourcePath }))),
+    '## Sections',
     '',
-    renderLinkedFactsSection('## AI tools / MCP capabilities', facts.aiTools.map((tool) => ({ label: tool.name, sourcePath: tool.sourcePath }))),
+    ...sectionLinks,
     '',
-    renderLinkedFactsSection('## AI agents', facts.aiAgents.map((agent) => ({ label: agent.id, sourcePath: agent.sourcePath }))),
+    'Read only the section files needed for the task; every section ends with a completion marker.',
+    `A section absent from this list has no facts for ${facts.module}; this index is complete only when the read reaches the marker below.`,
     '',
-    renderOverrideTargetsSection(facts.overrideTargets),
+    `<!-- end module facts: ${facts.module} — ${sections.length} sections -->`,
     '',
-  ]
-  const owned = facts.ownedContracts ?? {}
-  const ownedSections = [
-    renderOwnedContractSection('## Owned contract — module metadata', owned['module-metadata']),
-    renderOwnedContractSection('## Domain commands', owned.command),
-    renderOwnedContractSection('## Workers', owned.worker),
-    renderOwnedContractSection('## Page middleware', owned['page-middleware']),
-    renderOwnedContractSection('## Setup', owned.setup),
-    renderOwnedContractSection('## Encryption', owned.encryption),
-    renderDiRegistrationsSection(owned['di-registration']),
-    renderOwnedContractSection('## Custom entities', owned['custom-entity']),
-    renderOwnedContractSection('## AI extensions', owned['ai-extension']),
-    renderOwnedContractSection('## Generator plugins', owned['generator-plugin']),
-  ].filter((section) => section.length > 0)
-  for (const section of ownedSections) {
-    sections.push(section, '')
-  }
-  return sections.join('\n')
+  ].join('\n')
+  return { index, sections }
 }
 
 export function toModuleFactsJsonEntry(facts: ModuleFacts): ModuleFactsJsonEntry {
@@ -3094,7 +3368,9 @@ export interface ExtractLocalReferenceModuleFactsOptions {
 
 export interface LocalReferenceModuleFactsResult {
   entry: ReferenceModuleFactsEntry
+  /** @deprecated Flat rendering; read `directory` for the shipped layout. */
   markdown: string
+  directory: ModuleFactsMarkdownDirectory
   warnings: string[]
   /**
    * First-party targets the activated projection could not correlate. They also remain in
@@ -3167,6 +3443,7 @@ export function extractLocalReferenceModuleFacts(
       facts: jsonEntry,
     },
     markdown: renderModuleFactsMarkdown(facts, fingerprints),
+    directory: renderModuleFactsDirectory(facts, fingerprints),
     warnings: activated.warnings,
     unresolvedTargets: activated.unresolvedFirstPartyTargets ?? [],
   }
@@ -3198,7 +3475,9 @@ export interface ExtractAllModuleFactsOptions {
 
 export interface ExtractAllModuleFactsResult {
   factsByModule: Record<string, ModuleFacts>
+  /** @deprecated Flat rendering; read `directoryByModule` for the shipped layout. */
   markdownByModule: Record<string, string>
+  directoryByModule: Record<string, ModuleFactsMarkdownDirectory>
   warnings: string[]
   frameworkMarkdown: string
   /** Always empty under the default `throw` policy, which aborts before returning. */
@@ -3245,6 +3524,7 @@ function extractAllModuleFactsWithCache(options: ExtractAllModuleFactsOptions):
 
   const factsByModule: Record<string, ModuleFacts> = {}
   const markdownByModule: Record<string, string> = {}
+  const directoryByModule: Record<string, ModuleFactsMarkdownDirectory> = {}
   const warnings: string[] = []
   for (const source of sources) {
     const facts = extractModuleFacts({
@@ -3312,6 +3592,7 @@ function extractAllModuleFactsWithCache(options: ExtractAllModuleFactsOptions):
   for (const moduleId of Object.keys(factsByModule).sort((left, right) => left.localeCompare(right))) {
     factsByModule[moduleId].extensionSurfaces = withIncoming[moduleId]
     markdownByModule[moduleId] = renderModuleFactsMarkdown(factsByModule[moduleId])
+    directoryByModule[moduleId] = renderModuleFactsDirectory(factsByModule[moduleId])
     warnings.push(...correlated[moduleId].unresolved.map((entry) =>
       `[module-facts] ${moduleId} ${entry.reason}: ${entry.key} (${entry.source.path})`,
     ))
@@ -3319,6 +3600,7 @@ function extractAllModuleFactsWithCache(options: ExtractAllModuleFactsOptions):
   return {
     factsByModule,
     markdownByModule,
+    directoryByModule,
     warnings,
     frameworkMarkdown: renderFrameworkExtensionPointsMarkdown(),
     unresolvedFirstPartyTargets,