@open-mercato/cli 0.6.8-develop.6961.1.5b7ca407e7 → 0.6.8-develop.6962.1.bd029a2bb2

package/dist/lib/generators/module-facts.js

@@ -1723,6 +1723,36 @@ function extractModuleFacts(options) {
   return facts;
 }
 const EMPTY_SECTION_MARKER = "_none_";
+const MAX_ANCHORED_SECTION_BYTES = 32 * 1024;
+function renderGroupedTableSection(sectionHeading, header, divider, groups) {
+  const renderedGroups = [];
+  for (const group of groups) {
+    const chunks = [];
+    let currentRows = [];
+    const renderChunk = (rows, chunkIndex) => {
+      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, sourcePackage, sourceVersion) {
   if (sourcePackage) {
     return `<!-- generated from ${sourcePackage} ${sourceVersion || "<unknown>"}; core ${coreVersion || "<unknown>"} \u2014 R1 staleness stamp -->`;
@@ -1730,18 +1760,18 @@ function renderVersionStamp(coreVersion, sourcePackage, sourceVersion) {
   const version = coreVersion && coreVersion.length > 0 ? coreVersion : "<unknown>";
   return `<!-- generated from @open-mercato/core ${version} \u2014 R1 staleness stamp -->`;
 }
-function renderEntitiesSection(entities, lookup) {
+function renderEntitiesSection(entities, lookup, context) {
   if (entities.length === 0) return `## Entities
 
 ${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) => `| ${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, lookup) {
+function renderEventsSection(events, lookup, context) {
   const heading = `## Events  (${events.length})`;
   if (events.length === 0) return `${heading}
 
@@ -1750,7 +1780,7 @@ ${EMPTY_SECTION_MARKER}`;
   const divider = "|---|---|---|---|---|";
   const rows = events.map((event) => {
     const transports = [event.clientBroadcast ? "client" : null, event.portalBroadcast ? "portal" : null].filter((value) => value !== null);
-    return `| ${event.id} | ${event.category ?? "\u2014"} | ${event.entity ?? "\u2014"} | ${transports.join(", ") || "\u2014"} | ${renderLookedUpSource(lookup, "event", event.id)} |`;
+    return `| ${event.id} | ${event.category ?? "\u2014"} | ${event.entity ?? "\u2014"} | ${transports.join(", ") || "\u2014"} | ${renderLookedUpSource(lookup, "event", event.id, context)} |`;
   });
   return [heading, "", header, divider, ...rows].join("\n");
 }
@@ -1762,29 +1792,36 @@ ${EMPTY_SECTION_MARKER}`;
 
 ${values.join(" \xB7 ")}`;
 }
-function renderSourceLinkedListSection(heading, values, lookup, kind, idColumnLabel) {
+function renderSourceLinkedListSection(heading, values, lookup, kind, idColumnLabel, context) {
   if (values.length === 0) return `${heading}
 
 ${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");
 }
 function isExactSourceFilePath(sourcePath) {
   return MODULE_CODE_EXTENSIONS.some((extension) => sourcePath.endsWith(extension));
 }
-function renderSourceLink(sourcePath) {
+function renderSourceLabel(sourcePath, sourceRoot, line) {
+  const relativeSourcePath = sourcePath.startsWith(`${sourceRoot}/`) ? sourcePath.slice(sourceRoot.length + 1) : sourcePath;
+  return line ? `${relativeSourcePath}:${line}` : relativeSourcePath;
+}
+function renderSourceLink(sourcePath, context) {
   if (!isExactSourceFilePath(sourcePath)) return sourcePath;
-  return `[${sourcePath}](../../../${sourcePath})`;
+  const label = context ? renderSourceLabel(sourcePath, context.sourceRoot) : sourcePath;
+  return `[${label}](${context?.sourceLinkPrefix ?? "../../../"}${sourcePath})`;
 }
-function renderSourceRefLink(source) {
+function renderSourceRefLink(source, context) {
   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, kind, id) {
+function renderLookedUpSource(lookup, kind, id, context) {
   const source = lookup(kind, id);
-  return source ? renderSourceRefLink(source) : "\u2014";
+  return source ? renderSourceRefLink(source, context) : "\u2014";
 }
 function renderSafeScalar(value) {
   if (value === void 0 || value === null) return "\u2014";
@@ -1797,18 +1834,18 @@ function renderOwnedContractMetadata(metadata) {
   if (keys.length === 0) return "\u2014";
   return keys.map((key) => `${key}=${renderSafeScalar(metadata[key])}`).join("; ");
 }
-function renderOwnedContractSection(heading, facts) {
+function renderOwnedContractSection(heading, facts, context) {
   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) {
+function renderDiRegistrationsSection(facts, context) {
   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)",
@@ -1836,25 +1873,30 @@ function renderApiRouteAuthCell(route) {
   }
   return groups.map((group) => `${group.methods.join("/")} \u2192 ${group.label}`).join(" \xB7 ");
 }
-function renderApiRoutesSection(routes) {
+function renderApiRoutesSection(routes, context) {
   if (routes.length === 0) return `## API routes
 
 ${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) : "\u2014"} |`
+    (route) => `| ${route.path} | ${route.methods.join(" ")} | ${renderApiRouteAuthCell(route)} | ${route.sourcePath ? renderSourceLink(route.sourcePath, context) : "\u2014"} |`
   );
   return ["## API routes", "", header, divider, ...rows].join("\n");
 }
-function renderLinkedFactsSection(heading, facts) {
+function renderLinkedFactsSection(heading, facts, context) {
   if (facts.length === 0) return `${heading}
 
 ${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) {
+  if (hostTokens.entityIds.length === 0 && hostTokens.tableIds.length === 0) {
+    return `## Host extension points
+
+${EMPTY_SECTION_MARKER}`;
+  }
   const entityIdsLine = hostTokens.entityIds.length > 0 ? hostTokens.entityIds.join(" \xB7 ") : EMPTY_SECTION_MARKER;
   const tableIdsLine = hostTokens.tableIds.length > 0 ? hostTokens.tableIds.join(" \xB7 ") : EMPTY_SECTION_MARKER;
   return ["## Host extension points", "", `- Entity IDs: ${entityIdsLine}`, `- Table IDs: ${tableIdsLine}`].join("\n");
@@ -1862,25 +1904,36 @@ function renderHostTokensSection(hostTokens) {
 function renderExtensionHostContext(host) {
   return host.contextContract ?? host.runtimeContract ?? host.scopeContract ?? "\u2014";
 }
-function renderExtensionHostSource(host) {
+function renderExtensionHostSource(host, context) {
   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) {
+function renderExtensionHostsSection(extensionSurfaces, context) {
   const boundHosts = extensionSurfaces.hosts.filter((host) => host.bound);
   if (boundHosts.length === 0) return `## UMES hosts
 
 ${EMPTY_SECTION_MARKER}`;
-  const rows = boundHosts.map(
-    (host) => `| ${host.id} | ${host.family} | ${host.capabilities.join(", ") || "\u2014"} | ${renderExtensionHostContext(host)} | ${host.stability.toUpperCase()} | ${renderExtensionHostSource(host)} |`
-  );
-  return [
+  const header = [
     "## UMES hosts",
     "",
     "| ID / pattern | Family | Supports | Context | Stability | Source |",
+    "|---|---|---|---|---|---|"
+  ];
+  const renderRows = (hosts) => hosts.map(
+    (host) => `| ${host.id} | ${host.family} | ${host.capabilities.join(", ") || "\u2014"} | ${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 |",
     "|---|---|---|---|---|---|",
-    ...rows
-  ].join("\n");
+    families.map((family) => ({
+      title: family,
+      rows: renderRows(boundHosts.filter((host) => host.family === family))
+    }))
+  );
 }
 function compactContributionDetails(contribution) {
   const details = contribution.details;
@@ -1898,7 +1951,7 @@ function compactContributionDetails(contribution) {
     return [`${key}=${String(value)}`];
   }).join("; ");
 }
-function renderExtensionContributionsSection(extensionSurfaces) {
+function renderExtensionContributionsSection(extensionSurfaces, context) {
   if (extensionSurfaces.contributions.length === 0) return `## UMES contributions
 
 ${EMPTY_SECTION_MARKER}`;
@@ -1906,7 +1959,7 @@ ${EMPTY_SECTION_MARKER}`;
     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(", ") || "\u2014";
-    const source = renderSourceRefLink({ sourcePath: contribution.source.path });
+    const source = renderSourceRefLink({ sourcePath: contribution.source.path }, context);
     return `| ${contribution.id} | ${contribution.kind} | ${targets || "\u2014"} | ${phases} | ${compactContributionDetails(contribution)} | ${resolution || "\u2014"} | ${source} |`;
   });
   return [
@@ -1931,14 +1984,14 @@ function renderExtensionTargetRef(target) {
   const owner = target.moduleId ? ` @${target.moduleId}` : "";
   return `${target.kind}:${target.id}${method}${owner}`;
 }
-function renderActivationBindingsSection(extensionSurfaces) {
+function renderActivationBindingsSection(extensionSurfaces, context) {
   const activations = extensionSurfaces.activations ?? [];
   if (activations.length === 0) return `## Active extension bindings
 
 ${EMPTY_SECTION_MARKER}`;
   const rows = activations.map((activation) => {
     const phases = activation.phases && activation.phases.length > 0 ? activation.phases.join(", ") : "\u2014";
-    const source = activation.source ? renderSourceRefLink(activation.source) : "\u2014";
+    const source = activation.source ? renderSourceRefLink(activation.source, context) : "\u2014";
     const bridge = activation.bridge ? `${activation.bridge.factSection}:${activation.bridge.factKey}` : "\u2014";
     return `| ${activation.id} | ${activation.kind} | ${renderExtensionTargetRef(activation.host)} | ${activation.contributionKinds.join(", ") || "\u2014"} | ${phases} | ${bridge} | ${source} |`;
   });
@@ -1950,14 +2003,14 @@ ${EMPTY_SECTION_MARKER}`;
     ...rows
   ].join("\n");
 }
-function renderIncomingContributionsSection(extensionSurfaces) {
+function renderIncomingContributionsSection(extensionSurfaces, context) {
   const incoming = extensionSurfaces.incoming ?? [];
   if (incoming.length === 0) return `## Incoming installed contributions
 
 ${EMPTY_SECTION_MARKER}`;
   const rows = incoming.map((entry) => {
     const activation = entry.activationId ?? "\u2014";
-    const source = entry.source ? renderSourceRefLink(entry.source) : "\u2014";
+    const source = entry.source ? renderSourceRefLink(entry.source, context) : "\u2014";
     return `| ${entry.contributorModuleId} | ${entry.contributionKind} | ${renderExtensionTargetRef(entry.target)} | ${entry.resolution} | ${activation} | ${entry.contributionId} \xB7 ${source} |`;
   });
   return [
@@ -1968,14 +2021,14 @@ ${EMPTY_SECTION_MARKER}`;
     ...rows
   ].join("\n");
 }
-function renderContributionResolutionsSection(extensionSurfaces, lookup) {
+function renderContributionResolutionsSection(extensionSurfaces, lookup, context) {
   const resolutions = extensionSurfaces.contributionResolutions ?? [];
   if (resolutions.length === 0) return `## Contribution resolutions
 
 ${EMPTY_SECTION_MARKER}`;
   const rows = resolutions.map((resolution) => {
     const activations = resolution.activationIds.length > 0 ? resolution.activationIds.join(", ") : "\u2014";
-    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 [
@@ -1995,19 +2048,30 @@ function renderOverrideTargetPath(target) {
   }
   return display;
 }
-function renderOverrideTargetsSection(targets) {
+function renderOverrideTargetsSection(targets, context) {
   if (!targets || targets.length === 0) return `## Exact override targets
 
 ${EMPTY_SECTION_MARKER}`;
   const header = "| Domain | Path / key | Supported modes | Referenced fact | Source |";
   const divider = "|---|---|---|---|---|";
-  const rows = targets.map((target) => {
+  const renderRows = (group) => group.map((target) => {
     const path2 = `\`${renderOverrideTargetPath(target)}\``;
     const modes = target.modes.join(", ") || "\u2014";
     const fact = `${target.factRef.factSection}:${target.factRef.factKey}`;
-    return `| ${target.domain} | ${path2} | ${modes} | ${fact} | ${renderSourceRefLink(target.source)} |`;
+    return `| ${target.domain} | ${path2} | ${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))
+    }))
+  );
 }
 function renderReferenceProjectionHeader(facts, fingerprints) {
   return [
@@ -2017,81 +2081,191 @@ function renderReferenceProjectionHeader(facts, fingerprints) {
     `Source root: ${renderSourceLink(facts.sourceRoot)}`
   ];
 }
-function renderModuleFactsMarkdown(facts, referenceProjection) {
+function buildModuleFactsSections(facts, context) {
   const extensionSurfaces = facts.extensionSurfaces ?? { hosts: [], contributions: [], unresolved: [] };
   const lookup = buildFactSourceLookup(facts);
-  const header = facts.sourceKind === "local-reference" && referenceProjection ? renderReferenceProjectionHeader(facts, referenceProjection) : [
-    `# ${facts.module} \u2014 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"
+      "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 \u2014 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) {
+  return section.split("\n", 1)[0].replace(/^## /, "").replace(/\s+\(\d+\)\s*$/, "");
+}
+function sectionSlug(title) {
+  return title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function approximateSize(markdown) {
+  return `~${Math.max(1, Math.ceil(Buffer.byteLength(markdown) / 1024))} KB`;
+}
+function collectSectionAnchors(sections) {
+  const anchors = [];
+  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, header, sections) {
+  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} \u2014 L${firstSectionLine + anchor.offset}, ${anchor.size}`;
+  });
+  return [
+    ...header,
     "",
-    renderExtensionHostsSection(extensionSurfaces),
-    "",
-    renderExtensionContributionsSection(extensionSurfaces),
-    "",
-    renderActivationBindingsSection(extensionSurfaces),
+    "## Contents",
     "",
-    renderIncomingContributionsSection(extensionSurfaces),
+    ...contents,
     "",
-    renderContributionResolutionsSection(extensionSurfaces, lookup),
+    "Read caps: a read that does not reach the end-of-facts marker was truncated \u2014 re-read the missing sections by their line anchors.",
     "",
-    renderExtensionDiagnosticsSection(extensionSurfaces),
+    sections.join("\n\n"),
     "",
-    renderSourceLinkedListSection("## Notifications", facts.notifications, lookup, "notification", "Notification ID"),
+    `<!-- end module facts: ${facts.module} \u2014 ${sections.length} sections -->`,
+    ""
+  ].join("\n");
+}
+function renderModuleFactsMarkdown(facts, referenceProjection) {
+  const header = facts.sourceKind === "local-reference" && referenceProjection ? renderReferenceProjectionHeader(facts, referenceProjection) : [
+    `# ${facts.module} \u2014 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));
+}
+function renderModuleFactsDirectory(facts, referenceProjection) {
+  const header = facts.sourceKind === "local-reference" && referenceProjection ? renderReferenceProjectionHeader(facts, referenceProjection) : [
+    `# ${facts.module} \u2014 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(`
+
+${EMPTY_SECTION_MARKER}`));
+  const sectionEntries = renderedSections.map((section) => {
+    const title = sectionTitle(section);
+    const slug = sectionSlug(title);
+    const markdown = [
+      `# ${facts.module} \u2014 ${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) \u2014 ${approximateSize(section.markdown)} \u2014 ${section.description}`,
+    ...subsections.map(
+      (anchor) => `  - ${anchor.title} \u2014 ${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} \u2014 ${sections.length} sections -->`,
     ""
-  ];
-  const owned = facts.ownedContracts ?? {};
-  const ownedSections = [
-    renderOwnedContractSection("## Owned contract \u2014 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 };
 }
 function toModuleFactsJsonEntry(facts) {
   return {
@@ -2290,6 +2464,7 @@ function extractLocalReferenceModuleFacts(options) {
       facts: jsonEntry
     },
     markdown: renderModuleFactsMarkdown(facts, fingerprints),
+    directory: renderModuleFactsDirectory(facts, fingerprints),
     warnings: activated.warnings,
     unresolvedTargets: activated.unresolvedFirstPartyTargets ?? []
   };
@@ -2310,6 +2485,7 @@ function extractAllModuleFactsWithCache(options) {
   })) : [];
   const factsByModule = {};
   const markdownByModule = {};
+  const directoryByModule = {};
   const warnings = [];
   for (const source of sources) {
     const facts = extractModuleFacts({
@@ -2373,6 +2549,7 @@ function extractAllModuleFactsWithCache(options) {
   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})`
     ));
@@ -2380,6 +2557,7 @@ function extractAllModuleFactsWithCache(options) {
   return {
     factsByModule,
     markdownByModule,
+    directoryByModule,
     warnings,
     frameworkMarkdown: renderFrameworkExtensionPointsMarkdown(),
     unresolvedFirstPartyTargets,
@@ -2990,6 +3168,7 @@ export {
   extractLocalReferenceModuleFacts,
   extractModuleFacts,
   isExactSourceFilePath,
+  renderModuleFactsDirectory,
   renderModuleFactsJson,
   renderModuleFactsMarkdown,
   renderReferenceModuleFactsJson,