@c4a/context 0.6.11 → 0.6.16

package/codeIndexPlan.d.ts

@@ -0,0 +1,74 @@
+export declare const CODE_INDEX_MODULE_TYPES: readonly ["api-service", "service", "background-runtime", "sdk-library", "web-application", "adapter", "cli-tool", "monorepo-container", "contract-source", "derived-source", "unknown"];
+export type CodeIndexModuleType = typeof CODE_INDEX_MODULE_TYPES[number];
+export declare const CODE_INDEX_MODULE_FACETS: readonly ["page-routing", "public-api", "protocol-provider", "protocol-consumer", "event-producer", "event-consumer", "persistence", "plugin-extension", "configuration-runtime", "build-release", "cross-module-chain", "generated-contract"];
+export type CodeIndexModuleFacet = typeof CODE_INDEX_MODULE_FACETS[number];
+export declare const CODE_INDEX_OUTPUT_PROFILES: readonly ["protocol-index", "service-boundary", "runtime-map", "public-api-reference", "module-map", "application-map", "adapter-contract", "command-map", "module-registry", "cross-module-flow", "provenance-only"];
+export type CodeIndexOutputProfile = typeof CODE_INDEX_OUTPUT_PROFILES[number];
+export declare const CODE_INDEX_COVERAGE_KINDS: readonly ["responsibility", "entrypoint", "operation", "contract", "handoff", "state-boundary", "failure-recovery", "delivery", "source-authority"];
+export type CodeIndexCoverageKind = typeof CODE_INDEX_COVERAGE_KINDS[number];
+export declare function requiredCodeIndexCoverage(input: {
+    outputProfile: CodeIndexOutputProfile;
+    facets?: readonly CodeIndexModuleFacet[];
+}): CodeIndexCoverageKind[];
+export declare const CODE_INDEX_CAPABILITIES: readonly ["complete", "project-adapter", "material-required"];
+export type CodeIndexCapability = typeof CODE_INDEX_CAPABILITIES[number];
+export declare const CODE_INDEX_LIFECYCLES: readonly ["authoritative", "generated", "mirrored", "legacy", "vendored"];
+export type CodeIndexLifecycle = typeof CODE_INDEX_LIFECYCLES[number];
+/** Stable knowledge intent for one user-visible code index unit. */
+export interface CodeIndexUnitPlan {
+    id: string;
+    inputSources: readonly string[];
+    outputOwner: string;
+    /** Primary classification retained for compact reports and existing plans. */
+    moduleType: CodeIndexModuleType;
+    /** All applicable module archetypes. A hybrid module may declare more than one. */
+    moduleTypes?: readonly CodeIndexModuleType[];
+    /** Composable behavior and contract facets used to select extraction guidance. */
+    facets?: readonly CodeIndexModuleFacet[];
+    /** Source-backed reasons for the selected module type. */
+    moduleTypeEvidence?: readonly string[];
+    outputProfile: CodeIndexOutputProfile;
+    responsibility: string;
+    entries: readonly string[];
+    pageKinds: readonly string[];
+    protocols: readonly string[];
+    dependencies: readonly string[];
+    exclusions: readonly string[];
+    lifecycle?: CodeIndexLifecycle;
+    sourceOfTruth?: string;
+    capability: CodeIndexCapability;
+}
+export type CodeIndexInspectionFindingKind = "module" | "entry" | "protocol" | "dependency" | "lifecycle" | "source-of-truth";
+export interface CodeIndexInspectionFinding {
+    indexUnitId: string;
+    source: string;
+    kind: CodeIndexInspectionFindingKind;
+    summary: string;
+    path?: string;
+}
+export interface CodeIndexCapabilityGap {
+    indexUnitId: string;
+    reason: string;
+    requestedMaterial?: string;
+}
+export interface CodeIndexInspectionResult {
+    findings: readonly CodeIndexInspectionFinding[];
+    capabilityGaps?: readonly CodeIndexCapabilityGap[];
+}
+export interface CodeIndexInspectionContext {
+    projectRoot: string;
+    sources: readonly {
+        name: string;
+        materializedAt: string;
+        absolutePath: string;
+    }[];
+}
+export type CodeIndexInspectionAdapter = (context: CodeIndexInspectionContext) => CodeIndexInspectionResult | Promise<CodeIndexInspectionResult>;
+export declare const NO_ENTRY_DETECTED: "NO_ENTRY_DETECTED";
+export declare class ExtractTsConfigurationError extends TypeError {
+    readonly code: "NO_ENTRY_DETECTED";
+    constructor(message: string);
+}
+export declare function normalizeExtractEntry(value: string): string;
+export declare function normalizeIndexUnit(unit: CodeIndexUnitPlan, field: string): CodeIndexUnitPlan;
+export declare function assertUniqueIndexUnits(units: readonly CodeIndexUnitPlan[], field: string): void;

package/docs/guides/package-outputs.md

@@ -89,26 +89,20 @@ package needs project-specific terminology, entry points, known limits, or
 task workflows. Authors may explicitly accept the generic default when it is
 intentionally sufficient.
 
-When approved pages reference materialized document resources, Context keeps
-their production copies in content-addressed `knowledge/assets/` paths. New KB
-setup should offer Git raw delivery first. It rewrites package links to either
-an automatically derived raw prefix or an explicit author-provided prefix.
-Context does not check whether resource files are committed, pushed, or
-remotely readable; that is the package author's responsibility. With no
-explicit prefix, supported remotes use an immutable commit URL. An explicit
-prefix can contain `{commit}` when the Context workspace is in Git, or name a
-mutable branch when that lifecycle is intentional; a literal prefix also works
-when resources are published from a separate repository.
-
-Workspaces without usable Git or an explicit raw prefix can choose bundled
-delivery, which copies only selected resources to `others/assets/`, or explicit
-omission, which does not copy resources and reports that links remain
-unresolved. Bundled output may
-optionally install `sharp` in the workspace and configure
-`assets.optimize`; Context itself has no image dependency. Optimization changes
-only `dist/`, content-addresses smaller WebP output, and leaves `sources/` and
-`knowledge/assets/` unchanged. Source audit XML and capture reports are never
-distributed as reader assets. See [Lark Resource Materialization](./lark-resources.md).
+When approved pages reference materialized resources, Context keeps their
+production copies in content-addressed `knowledge/assets/` paths and bundles
+selected resources into `others/assets/` by default. Supported images are
+adaptively compressed only when needed: every packaged image must be at most 1
+MiB and all packaged images together must be at most 40 MiB. The CLI owns the
+processor. Optimization changes only `dist/`, content-addresses smaller WebP
+output, and leaves `sources/` and `knowledge/assets/` unchanged.
+
+Configure Git raw delivery only when external immutable links are an explicit
+project requirement. Context can derive supported Git URLs or use an explicit
+HTTPS `urlPrefix`, but it does not publish or probe those resources. Explicit
+omission remains available and reports unresolved links. Source audit XML and
+capture reports are never distributed as reader assets. See
+[Lark Resource Materialization](./lark-resources.md).
 
 The same inventory exposes `structure.relationship_coverage`. It records
 whether selected codegraph pages have current source-backed AST relationship

package/docs/reference/code-extractors.md

@@ -6,8 +6,9 @@ chooses how those facts become source-backed code knowledge.
 
 ## Inspect Before Declaring
 
-Run every read-only inspection command returned by the extraction-scope Gate.
-The result identifies each confirmed module and its recognized `manifests`.
+Run the single batch inspection command returned by the extraction-scope Gate.
+The result identifies every confirmed module, its recognized `manifests`,
+README locations, entry candidates, protocol locators, and lifecycle markers.
 Treat these as deterministic technology signals, not as product semantics:
 
 | Signal | Technology candidate |
@@ -43,6 +44,19 @@ Current reusable capabilities are:
 | React Router route declarations | `extractReactRouterRoutes()` from `@c4a/extract-ts` | call from `extractCustom()`; complements TypeScript symbols |
 | Rust, Python, Java/JVM, or an unsupported framework/protocol | no assumed built-in parser | project-owned `extractCustom()` adapter |
 
+The custom extraction preview verifies this selection mechanically. Context
+detects applicable community capabilities from source manifests and stable path
+signals, then checks that candidate evidence covers every required entry,
+route, implementation boundary, workspace, or protocol probe. One aggregated
+module page is valid when it closes that structural coverage. A callback that
+only hashes a few filenames or renders configured prose does not satisfy the
+probe, even when its Markdown count is small.
+
+The probe does not assign business meaning and does not require one page per
+fact. The project adapter still owns grouping, titles, explanations, and
+cross-module semantics. If the source uses an unsupported language or protocol,
+report a capability gap instead of claiming that a known probe was consumed.
+
 An optional package does not create a new CLI phase. Add it as an explicit
 workspace dependency, then map its structural facts to candidates in the
 project callback. Do not add a parser package when its documented coverage does
@@ -50,23 +64,18 @@ not match the inspected source.
 
 ## Read The Contract Before Extending
 
-Before editing `src/index.ts`, read the relevant installed public manual or
-package README. Do not infer APIs from bundled JavaScript.
-
-- Context lifecycle and `extractCustom()`:
-  `node_modules/@c4a/context/docs/reference/project-api.md`
-- Generic plugin protocol:
-  `node_modules/@c4a/extract/README.md`
-- TypeScript:
-  `node_modules/@c4a/extract-ts/README.md`
-- Go:
-  `node_modules/@c4a/extract-go/README.md`
-- Rush:
-  `node_modules/@c4a/extract-rush/README.md`
+Before editing `src/index.ts`, read the Route-selected Context lifecycle and
+extractor resources completely. They are the installed contract for
+Context-owned phases such as `extractTs()`; do not require a separate
+workspace copy of an implementation package and do not infer APIs from bundled
+JavaScript.
 
-If an optional package is not installed, use this capability matrix to decide
-whether it is relevant, add only that dependency, and then read its shipped
-README before implementing the callback.
+Only a capability imported directly by a project-owned `extractCustom()`
+adapter requires its package README. Use this matrix to decide whether that
+optional capability is relevant, add only that dependency, then read the
+README from the resolved installed package before implementing the callback.
+Never assume that a transitive or dev-only package is present at a hard-coded
+`node_modules` path.
 
 A project-owned adapter may use an existing parser, compiler API, or command
 whose output is deterministic. It must return source-backed candidates through
@@ -83,6 +92,54 @@ Before the first extraction preview, state briefly:
 - whether coverage is complete or which facts remain project-owned; and
 - why another available extractor is not needed.
 
+After preview, use `inspection.structuralProbes` and each index unit's
+`structuralCoverage` as the exact audit result. An uncovered probe is a
+configuration problem, not a Review decision.
+
 If no current capability can parse the source reliably, stop at configuration
 and report the missing generic capability. Do not silently emit an empty
 codegraph or reuse an unrelated parser.
+
+## Plan Before Parsing
+
+Classify the user-visible module before selecting language tooling or reading an
+archetype template: API/service, background runtime, SDK/library, interactive
+application, adapter, CLI/tool, monorepo container, derived source,
+authoritative contract source, or unknown.
+A hybrid module may declare several `moduleTypes` and several behavior `facets`;
+keep one primary `moduleType` for concise reports. Record inspected paths in
+`moduleTypeEvidence`, then read all matching Route-recommended files below
+`resources/semantic/code-index/templates/` and combine them into one plan.
+After that, choose exactly one closed output profile: `module-map`,
+`application-map`, `protocol-index`, `service-boundary`, `runtime-map`,
+`public-api-reference`, `command-map`, `adapter-contract`, `module-registry`,
+`cross-module-flow`, or `provenance-only`. The profile selects structural probes
+and advisory checks; an invented value is rejected.
+
+Each archetype resource is a working template for an Agent with limited prior
+context. It provides a minimum evidence pass, the reader questions the index
+must answer, suggested knowledge units, Markdown chapter blueprints,
+aggregation and relationship rules, composition examples, and stop conditions.
+The blueprints are illustrative: omit unsupported sections and merge overlap
+across selected templates instead of producing empty headings or duplicate
+pages. They shape content before the batch preview; they do not prescribe or
+override projected page counts.
+
+Extractor shape defines what can be emitted. `extractTs()` creates one page per
+selected symbol and permits one owning index unit per source. Use it for an
+intentional granular public reference. Use `extractCustom()` for module-level
+aggregation, registries, protocol indexes, cross-module flows, or multiple
+candidate owners over one source; each candidate declares its `module` and
+evidence-scoped `sections`. Each section's typed coverage and exact evidence is
+checked against the output profile during preview. Resolve repositories from
+the extractor context's `sources[].absolutePath`, never from a
+machine-specific checkout path. Cross-module flow output must also emit
+source-backed structured edges. Generated clients/models, mirrored sources, legacy
+implementations, and internal helpers should normally be excluded or recorded
+as provenance rather than expanded one symbol per page.
+
+If a repository uses service manifests or protocol registrations that the
+community inspector cannot interpret, keep that interpretation in a generic
+project-owned `inspect` adapter attached to `extractCustom()`. Return findings
+and capability gaps through the public Context contract; do not add internal
+framework names or directory rules to the CLI.

package/docs/reference/package-templates.md

@@ -31,10 +31,7 @@ kbPackage({
     foldDirectoryIndexes: true,
     maxInlineEntries: 50,
   },
-  assets: {
-    delivery: "git-raw",
-    urlPrefix: "https://code.example.com/team/knowledge/raw/{commit}",
-  },
+  assets: { delivery: "bundle" },
 });
 ```
 
@@ -56,10 +53,16 @@ llmsPackage({
 | `template` | yes | Project-relative template directory or `{ path, vars }`. |
 | `select` | no | Approved knowledge selector. Omit to include all approved knowledge. Supports internal `collections`, OKF `okfRoots`, and `include` / `exclude` path patterns relative to `knowledge/`. |
 | `navigation` | no | KB directory-index policy. Defaults to `{ foldDirectoryIndexes: true, maxInlineEntries: 50 }`. |
-| `assets` | no | Resource delivery: Git raw links, bundled files, or explicit omission. New KB setup should offer Git raw first. Omit for legacy byte-for-byte bundling. |
+| `assets` | no | Resource delivery: bundled files by default, explicit Git raw links, or explicit omission. |
 | `distribution` | no | Legacy input accepted from older workspaces. It no longer changes package paths and should not be added to new declarations. |
 
-Use Git raw delivery when resources are published from a Git repository.
+Bundled delivery is the default. Selected resources are written below
+`others/assets/`. Supported images are automatically compressed when required
+to keep each image at or below 1 MiB and all package images at or below 40 MiB.
+The source snapshots and approved `knowledge/assets/` files are never changed.
+
+Use Git raw delivery only when it is explicitly configured for resources
+published from a Git repository.
 Without `urlPrefix`, the Context workspace must be inside Git; GitHub remotes
 are derived automatically and pinned to the current commit. Other hosts accept
 an explicit HTTPS prefix. `{commit}` is replaced only when the workspace is
@@ -70,14 +73,14 @@ appends the project-relative `knowledge/assets/...` path.
 For a non-GitHub service that exposes raw files through the GitHub-compatible
 same-host layout
 `https://<host>/<namespace>/<repository>/raw/<ref>/<path>`, derive and configure
-the explicit prefix before choosing bundled delivery. For example, use
+the explicit prefix before choosing Git raw delivery. For example, use
 `https://git.example.com/team/knowledge/raw/{commit}` for a workspace at the
 repository root. If the workspace is nested, append its repository-relative
 directory to the prefix because Context appends only the project-relative
 `knowledge/assets/...` path. This derivation is appropriate only when the
 service's raw convention and repository identity are confirmed; otherwise ask
-for the prefix or use bundled delivery. The fact that Context does not
-automatically recognize a host is not, by itself, a reason to bundle.
+for the prefix or keep the default bundled delivery. Never invent a raw URL
+only because Context does not automatically recognize a host.
 
 The resolved commit and raw URL participate in package freshness, so changing
 Git HEAD or the selected remote makes an existing package stale. Context does
@@ -108,26 +111,12 @@ assets: { delivery: "bundle" }
 assets: { delivery: "omit" } // keeps unresolved links and reports them
 ```
 
-Bundled resources are copied byte-for-byte unless image optimization is
-configured. When optimizable PNG/JPEG resources exceed 20 MiB, build and status
-return `package.assets.optimization-recommended`. To optimize bundled output:
-
-```bash
-bun add -D sharp
-```
-
-```ts
-assets: {
-  delivery: "bundle",
-  optimize: { processor: "sharp", mode: "lossless-webp" },
-}
-```
-
-`optimize.mode: "webp"` additionally accepts `quality` from 1 to 100. Both modes accept
+Explicit `assets.optimize` overrides the automatic output policy.
+`optimize.mode: "webp"` accepts `quality` from 1 to 100. Both modes accept
 an optional positive `maxDimension`; images are never enlarged. Context adopts
 a generated image only when it is smaller, uses a digest-derived `.webp` path,
-and rewrites package links. A configured but missing processor blocks before
-the previous `dist/` package is replaced.
+and rewrites package links. If explicit settings cannot meet the package image
+budgets, build stops before replacing the previous `dist/` package.
 
 `template` is required. Do not call `kbPackage({ name })` or
 `llmsPackage({ name })`.
@@ -281,13 +270,17 @@ Default navigation rules:
 
 - `wikis/index.md` is the required default bundle index. Other selected OKF
   roots always use their own `<okf-root>/index.md`.
-- With `foldDirectoryIndexes: true`, a non-root directory gets its own
-  `index.md` only when its descendant knowledge-page count is greater than
-  `maxInlineEntries`. The default threshold is `50`.
+- With `foldDirectoryIndexes: true`, directory indexes are planned bottom-up.
+  A non-root directory gets its own `index.md` only when the page and child-index
+  entries it would expose to its parent are greater than `maxInlineEntries`.
+  The default threshold is `50`.
 - A folded directory is not discarded. Its pages are listed in the nearest
-  generated ancestor index, grouped by their relative directory path.
-- The threshold counts selected knowledge pages in the path tree. It does not
-  inspect Markdown line counts, headings, or content semantics.
+  generated ancestor index, grouped by their relative directory path, while
+  retained descendant indexes are linked directly from that ancestor. This
+  also removes large but navigation-thin intermediate directories.
+- The threshold counts visible navigation entries after descendant indexes are
+  planned. It does not inspect Markdown line counts, headings, or content
+  semantics.
 - Set `foldDirectoryIndexes: false` to generate an `index.md` for every
   directory, matching the fully expanded navigation shape.
 - A generated directory index uses OKF frontmatter with `type: Knowledge

package/docs/reference/project-api.md

@@ -606,8 +606,65 @@ Options:
 | `mode` | `"exports"` (default) traces public exports from automatic or configured entries; `"scan"` uses every file matched by `include` as an entry root |
 | `entries` | Optional source-relative entry files for `"exports"` mode. They override `package.json` entry detection and live only in the Context project configuration |
 | `exportedOnly` | Defaults to `true` in `"exports"` mode and `false` in `"scan"` mode |
+| `indexUnits` | Stable module/index plans used for ownership, capability and per-unit scale checks. A single-source exports-only package gets a compatible public-contract default; scan, collection and custom extraction require an explicit plan before formal writes |
 | `transform` | Optional markdown transform function or functions |
 
+An explicit index unit records production intent rather than parser settings:
+
+```ts
+extractTs({
+  source: componentLib,
+  collection: "codegraph",
+  indexUnits: [{
+    id: "component-public-api",
+    inputSources: ["20260712/component-lib"],
+    outputOwner: "component-lib",
+    moduleType: "sdk-library",
+    moduleTypes: ["sdk-library"],
+    facets: ["public-api", "plugin-extension"],
+    moduleTypeEvidence: ["package.json exports and src/index.ts public entry"],
+    outputProfile: "public-api-reference",
+    responsibility: "Document stable exported component contracts.",
+    entries: ["src/index.ts"],
+    pageKinds: ["module-map", "public-contract"],
+    protocols: [],
+    dependencies: [],
+    exclusions: ["src/internal/**", "src/generated/**"],
+    lifecycle: "authoritative",
+    sourceOfTruth: "src/index.ts",
+    capability: "complete",
+  }],
+});
+```
+
+`inputSources` names registered evidence sources; `outputOwner` is the one
+stable page owner used for accounting and navigation. `capability` is
+`"complete"`, `"project-adapter"`, or `"material-required"`. The last value
+stops the Route until the plan is narrowed or reliable source material is
+provided.
+
+`moduleType` is the primary compact classification. `moduleTypes` may add other
+applicable archetypes for a hybrid module, while `facets` records composable
+behaviors such as routing, protocol consumption, events, persistence, plugins,
+release, or cross-module chains. `moduleTypeEvidence` records the inspected
+paths that support the classification. Classify first, then read the matching
+Route-provided code-index templates, and only then finish the extraction plan.
+`lifecycle` is `"authoritative"`, `"generated"`, `"mirrored"`, `"legacy"`,
+or `"vendored"`; derived sources normally use `"provenance-only"` rather
+than duplicating reader-facing pages. These are generic project facts, not
+framework names inferred by the CLI.
+
+`moduleType`, `moduleTypes`, `facets`, `outputProfile`, `lifecycle`, and
+`capability` are runtime-validated closed values. Supported output profiles are
+`module-map`, `application-map`, `protocol-index`, `service-boundary`,
+`runtime-map`, `public-api-reference`, `command-map`, `adapter-contract`,
+`module-registry`, `cross-module-flow`, and `provenance-only`.
+
+`extractTs()` projects one candidate page per selected symbol, and each source
+can belong to only one of its index units. Use `extractCustom()` for aggregated
+maps, registries, protocol indexes, cross-module flows, or multiple candidate
+owners over one source; custom candidates declare their owning `module`.
+
 `source` is the only package/module boundary. `include` narrows files inside
 that source; it does not select a second module. Standard packages can omit
 `entries` and use `package.json` `exports`, `main`, or `bin` detection. For a
@@ -625,7 +682,9 @@ extractTs({
 
 When the intended knowledge scope is every declaration in the selected files
 rather than a public export graph, use `mode: "scan"`. Scan mode does not accept
-`entries`; `include` supplies its file roots.
+`entries`; `include` supplies its file roots. Because scan mode can expand
+internal declarations into a symbol catalog, it requires an explicit
+`indexUnits` plan before formal extraction.
 
 Entry failures use the stable machine code `NO_ENTRY_DETECTED`. This includes
 `entries: []`, exports mode with no detected/configured entry, and scan mode
@@ -657,6 +716,21 @@ does not infer which symbols are meaningful to a particular product or
 audience. Modules with skipped files include the deterministic traversal
 reason, such as files not reachable from exports-mode entries.
 
+Before formal extraction, the workflow runs one batch preview for all pending
+phases. Each `indexUnits[]` result reports projected Markdown pages, output
+profile/owner, content-byte estimates, and risks. Per unit, 0–100 pages is
+normal, 101–300 is a warning that may continue, and more than 300 is blocked.
+The limit is non-delegatable, including in managed mode. A passing preview is
+cached by digest under `.tmp/context-runtime/extract/previews/` and reused by
+formal extraction when the source scope, phase declaration, project `src/`,
+dependency lock, and preview protocol still match. A missing cache is
+recoverable by rerunning the preview. The report includes cache hits,
+extractor invocation count, current and projected page counts, changes,
+exported/internal distribution, top directories, and advisory large-page
+risks; only the 300-page per-unit limit is a hard scale gate.
+A batch-total page advisory and quality risks such as a thin custom aggregate
+remain report signals and do not create another Gate.
+
 Phase id shape:
 
 ```text
@@ -700,19 +774,53 @@ extractCustom({
   id: "extract:service:protocol",
   sources: [service],
   collection: "codegraph",
-  extract: async ({ projectRoot }) => ({
+  indexUnits: [{
+    id: "service-protocol",
+    inputSources: ["20260811/service"],
+    outputOwner: "service",
+    moduleType: "api-service",
+    moduleTypes: ["api-service", "adapter"],
+    facets: ["protocol-provider", "protocol-consumer", "cross-module-chain"],
+    moduleTypeEvidence: ["src/protocol.ts registration and src/handler.ts dispatch"],
+    outputProfile: "protocol-index",
+    responsibility: "Document the stable service protocol boundary.",
+    entries: ["src/protocol.ts"],
+    pageKinds: ["protocol-index"],
+    protocols: ["declared service protocol"],
+    dependencies: [],
+    exclusions: ["generated/**"],
+    lifecycle: "authoritative",
+    capability: "project-adapter",
+  }],
+  extract: async ({ sources }) => {
+    const serviceRoot = sources.find((item) => item.name === "20260811/service")?.absolutePath;
+    if (serviceRoot === undefined) throw new Error("service source is not materialized");
+    const protocolEvidence = inspectProtocol(serviceRoot);
+    return {
     candidates: [{
       nodeRef: "service/protocol",
       kind: "protocol",
       visibility: "exported",
       module: "service",
-      markdown: renderProtocol(projectRoot),
-      evidence: [{
-        source: "20260811/service",
-        file: "src/protocol.ts",
-        symbol: "protocol",
-        kind: "variable",
-        digest: "0123456789ab",
+      evidence: [protocolEvidence],
+      sections: [{
+        id: "contract",
+        kind: "contract",
+        title: "Provided contract",
+        markdown: renderContract(serviceRoot),
+        evidence: [protocolEvidence],
+      }, {
+        id: "operations",
+        kind: "operation",
+        title: "Operations",
+        markdown: renderOperations(serviceRoot),
+        evidence: inspectOperations(serviceRoot),
+      }, {
+        id: "handoff",
+        kind: "handoff",
+        title: "Implementation handoff",
+        markdown: renderHandoff(serviceRoot),
+        evidence: inspectHandoff(serviceRoot),
       }],
       review: {
         title: "Service protocol",
@@ -721,18 +829,50 @@ extractCustom({
         reason: "Review the project-owned extraction.",
       },
     }],
-  }),
+  }},
 });
 ```
 
-`sources` is the complete registered repo scope for the phase. Every candidate
-and edge carries structured `evidence`; the CLI validates that evidence against
+`sources` is the complete CLI-resolved repo scope for the phase. Resolve files
+from `sources[].absolutePath`; do not embed a local or remote Agent checkout
+path. Every candidate section and edge carries structured `evidence`; the CLI validates that evidence against
 the declared sources, creates canonical `source_ref` values, writes the symbol
 index, candidate ledger and Review snapshots atomically, and records a phase
-fingerprint. `context status` therefore treats this phase exactly like another
+fingerprint. Evidence-scoped section `kind` values satisfy the selected output
+profile's semantic coverage contract. A cross-module flow also requires at
+least one source-backed structured edge. `context status` therefore treats this phase exactly like another
 pending code extraction target, and Review can verify snapshot freshness
 without a placeholder `extractTs` phase.
 
+`indexUnits` is also the batch scale and ownership contract. Candidate
+`module` must match one declared unit id or output owner. Older callbacks that
+omit `indexUnits` remain compatible: Context groups candidates by `module` and
+marks the plan as inferred. Once explicit units exist, an unmatched or
+multiply-owned candidate blocks formal extraction instead of being guessed.
+An inferred plan can be previewed for migration diagnostics, but formal writes
+require the project to declare stable units and owners.
+
+For a large adapter, `candidates` may be an `AsyncIterable` instead of an
+array. Context consumes it incrementally and stops retaining full candidates
+for an index unit after the 301st item proves that the unit is blocked. Array
+callbacks remain supported and are reported as `legacy-preview`.
+
+An optional generic `inspect` adapter can return source-backed module, entry,
+protocol, dependency, lifecycle, and source-of-truth findings before candidate
+collection. It may also return capability gaps tied to declared index-unit ids;
+those gaps enter the one non-delegatable capability Gate. Internal framework
+meaning stays in the project adapter and its referenced material.
+
+The CLI also runs a lightweight structural probe before every custom preview.
+It recognizes TypeScript symbols, React Router routes, Go symbols, Rush
+workspace structure, and source-owned protocol schemas from generic manifests
+and paths. The preview exposes all detected probes in
+`inspection.structuralProbes` and records `structuralCoverage` on each index
+unit. Candidate evidence must cover every probe applicable to the selected
+output profile. Coverage is based on source-backed evidence paths, not Markdown
+page count, so one aggregate page can pass while an entry-only static module
+card cannot.
+
 The extractor returns knowledge semantics (`nodeRef`, rendered Markdown,
 Review summary and source-backed evidence). It must not write `knowledge/`,
 `.tmp/context-runtime/lifecycle/candidates.jsonl`, extraction fingerprints or
@@ -772,7 +912,9 @@ Available structural libraries include:
 The packages return syntax and repository facts only. They do not classify
 product meaning, choose candidate identities, or write lifecycle state. The
 knowledge project owns that mapping. Context CLI does not auto-install these
-packages and does not expose a built-in Go or Rush phase.
+packages and does not expose a built-in Go or Rush phase. Detection does not
+execute or replace an optional parser; it makes the matching parser contract
+and its evidence coverage auditable before candidate writes.
 
 ### `reviewValidity`
 

package/docs/reference/template-variables.md

@@ -231,9 +231,10 @@ The default KB template uses the variables above to generate a starter index:
 - links to generated directory indexes when a directory exceeds the configured
   inline-entry threshold.
 
-`context build` always provides selected OKF root indexes. By default, a
-non-root directory gets its own index only when it contains more than 50
-descendant knowledge pages. Configure this with
+`context build` always provides selected OKF root indexes. By default,
+directory indexes are planned bottom-up, and a non-root directory gets its own
+index only when it would expose more than 50 page or retained child-index
+entries to its parent. Configure this with
 `kbPackage({ navigation: { foldDirectoryIndexes, maxInlineEntries } })`.
 
 The output is only a starter. Edit the files under

package/index.d.ts

@@ -5,8 +5,8 @@ export type { CodegraphCollection, DocumentMainlineCollection, EntityStatus, Kno
 export { assertDocumentMainlineCollection, assertKnowledgeCollection, assertMainlineCollection, assertOkfRoot, assertTopLevelNamespace, DOC_MAINLINE_COLLECTIONS, DEFAULT_PACKAGE_NAVIGATION, KNOWLEDGE_COLLECTIONS, MAINLINE_COLLECTIONS, OKF_ROOTS, TOP_LEVEL_NAMESPACES, } from "./contracts.js";
 export { assertDocumentEvidenceSectionMetadata, DOCUMENT_COMPILE_ACTION_SCHEMA_VERSION, DOCUMENT_EVIDENCE_SECTION_VALIDATION_STAGES, DOCUMENT_SECTION_CONTENT_MODES, DOCUMENT_STRUCTURE_SCHEMA_VERSION, } from "./documentEvidence.js";
 export type { DocumentEvidenceSectionMetadata, DocumentEvidenceSectionValidationOptions, DocumentEvidenceSectionValidationStage, DocumentSectionContentMode, } from "./documentEvidence.js";
-export { alignProse, captureFile, captureLark, compileProse, customPhase, extractCustom, extractTs, ExtractTsConfigurationError, NO_ENTRY_DETECTED, mdxJsonDocs, reviewValidity, } from "./phases.js";
-export type { AlignProsePhaseDefinition, CaptureFilePhaseDefinition, CaptureLarkPhaseDefinition, CompileProsePhaseDefinition, ContextPhase, ContextPhaseContext, CustomPhaseDefinition, CustomCodeCandidateDraft, CustomCodeCandidateEdge, CustomCodeCandidateReview, CustomCodeEvidence, CustomCodeExtractionContext, CustomCodeExtractionResult, CustomCodeExtractor, ExtractCustomPhaseDefinition, ExtractTsPhaseDefinition, PhaseDefinition, PhaseResourceReference, ReviewValidityPhaseDefinition, ReviewValidityScope, } from "./phases.js";
+export { alignProse, captureFile, captureLark, compileProse, CODE_INDEX_CAPABILITIES, CODE_INDEX_COVERAGE_KINDS, CODE_INDEX_LIFECYCLES, CODE_INDEX_MODULE_FACETS, CODE_INDEX_MODULE_TYPES, CODE_INDEX_OUTPUT_PROFILES, customPhase, extractCustom, extractTs, ExtractTsConfigurationError, NO_ENTRY_DETECTED, requiredCodeIndexCoverage, mdxJsonDocs, reviewValidity, } from "./phases.js";
+export type { AlignProsePhaseDefinition, CaptureFilePhaseDefinition, CaptureLarkPhaseDefinition, CompileProsePhaseDefinition, ContextPhase, ContextPhaseContext, CustomPhaseDefinition, CustomCodeCandidateDraft, CustomCodeCandidateEdge, CustomCodeCandidateSection, CustomCodeCandidateReview, CustomCodeEvidence, CustomCodeExtractionContext, CustomCodeExtractionResult, CustomCodeExtractor, CodeIndexCapability, CodeIndexCapabilityGap, CodeIndexCoverageKind, CodeIndexInspectionAdapter, CodeIndexInspectionContext, CodeIndexInspectionFinding, CodeIndexInspectionFindingKind, CodeIndexInspectionResult, CodeIndexLifecycle, CodeIndexModuleFacet, CodeIndexModuleType, CodeIndexOutputProfile, CodeIndexUnitPlan, ExtractCustomPhaseDefinition, ExtractTsPhaseDefinition, PhaseDefinition, PhaseResourceReference, ReviewValidityPhaseDefinition, ReviewValidityScope, } from "./phases.js";
 export { allSources, DEFAULT_FILE_SOURCES_REGISTRY_PATH, DEFAULT_LARK_SOURCES_REGISTRY_PATH, DEFAULT_REPO_SOURCES_REGISTRY_PATH, loadSourcesRegistry, resolveSourceReference, source, } from "./sources.js";
 export type { DocumentSourceDefinition, DocumentSourceReference, DocumentSourceType, FileSourceDefinition, FileSourceReference, FileSourceRegistryEntry, LarkSourceDefinition, LarkSourceReference, LarkSourceRegistryEntry, LoadSourcesRegistryOptions, ProjectSourceDefinition, RepoProjectSourceDefinition, RepoSourceDefinition, RepoSourceReference, RepoSourceRegistryEntry, RepoSourcesRegistry, SourceCollectionReference, SourceDefinition, SourceReference, SourcesRegistry, SourceType, } from "./sources.js";
 export type TemplateVarValue = string | number | boolean | null | Record<string, unknown> | readonly Record<string, unknown>[];
@@ -23,9 +23,9 @@ export type PackageDistributionDefinition = {
     knowledgeNamespace: string;
 };
 export type PackageAssetOptimizationDefinition = {
-    /** Image codec provider resolved from the Context workspace. */
+    /** Image codec provider supplied by Context CLI. */
     processor: "sharp";
-    /** Lossless is the safe default; lossy WebP must be selected explicitly. */
+    /** Explicit output policy. Omit optimize to use Context's adaptive package budget. */
     mode?: "lossless-webp" | "webp";
     /** WebP quality for lossy mode. */
     quality?: number;
@@ -40,7 +40,7 @@ export type PackageAssetDefinition = {
     /** Optional HTTPS raw root. Context appends knowledge/assets/**; {commit} is supported. */
     urlPrefix?: string;
 } | {
-    /** Copy resources into the package. */
+    /** Copy resources into the package. This is the default delivery. */
     delivery: "bundle";
     /** Optional image optimization, resolved from the Context workspace. */
     optimize?: PackageAssetOptimizationDefinition;

package/index.js

@@ -7019,7 +7019,95 @@ var assertDocumentEvidenceSectionMetadata = (section, options, field = "document
   }
   assertHasSourceRefs(section, field);
 };
-// src/phases.ts
+// src/codeIndexPlan.ts
+var CODE_INDEX_MODULE_TYPES = [
+  "api-service",
+  "service",
+  "background-runtime",
+  "sdk-library",
+  "web-application",
+  "adapter",
+  "cli-tool",
+  "monorepo-container",
+  "contract-source",
+  "derived-source",
+  "unknown"
+];
+var CODE_INDEX_MODULE_FACETS = [
+  "page-routing",
+  "public-api",
+  "protocol-provider",
+  "protocol-consumer",
+  "event-producer",
+  "event-consumer",
+  "persistence",
+  "plugin-extension",
+  "configuration-runtime",
+  "build-release",
+  "cross-module-chain",
+  "generated-contract"
+];
+var CODE_INDEX_OUTPUT_PROFILES = [
+  "protocol-index",
+  "service-boundary",
+  "runtime-map",
+  "public-api-reference",
+  "module-map",
+  "application-map",
+  "adapter-contract",
+  "command-map",
+  "module-registry",
+  "cross-module-flow",
+  "provenance-only"
+];
+var CODE_INDEX_COVERAGE_KINDS = [
+  "responsibility",
+  "entrypoint",
+  "operation",
+  "contract",
+  "handoff",
+  "state-boundary",
+  "failure-recovery",
+  "delivery",
+  "source-authority"
+];
+var PROFILE_COVERAGE = {
+  "module-map": ["responsibility", "entrypoint"],
+  "application-map": ["entrypoint", "operation", "handoff"],
+  "protocol-index": ["contract", "operation", "handoff"],
+  "service-boundary": ["operation", "handoff"],
+  "runtime-map": ["entrypoint", "operation", "failure-recovery"],
+  "public-api-reference": ["contract"],
+  "adapter-contract": ["contract", "handoff"],
+  "command-map": ["entrypoint", "operation", "failure-recovery"],
+  "module-registry": ["responsibility", "source-authority"],
+  "cross-module-flow": ["operation", "handoff"],
+  "provenance-only": ["source-authority"]
+};
+function requiredCodeIndexCoverage(input) {
+  const required = new Set(PROFILE_COVERAGE[input.outputProfile]);
+  for (const facet of input.facets ?? []) {
+    if (facet === "build-release")
+      required.add("delivery");
+    if (facet === "persistence" || facet === "configuration-runtime")
+      required.add("state-boundary");
+    if (facet === "generated-contract")
+      required.add("source-authority");
+  }
+  return [...required];
+}
+var CODE_INDEX_CAPABILITIES = [
+  "complete",
+  "project-adapter",
+  "material-required"
+];
+var CODE_INDEX_LIFECYCLES = [
+  "authoritative",
+  "generated",
+  "mirrored",
+  "legacy",
+  "vendored"
+];
 var NO_ENTRY_DETECTED = "NO_ENTRY_DETECTED";
 
 class ExtractTsConfigurationError extends TypeError {
@@ -7037,6 +7125,68 @@ function normalizeExtractEntry(value) {
   }
   return segments.join("/");
 }
+function requiredIndexText(value, field) {
+  const normalized = value.trim();
+  if (normalized.length === 0)
+    throw new TypeError(`${field} must be a non-empty string`);
+  return normalized;
+}
+function requiredIndexEnum(value, field, allowed) {
+  if (typeof value !== "string" || !allowed.includes(value)) {
+    throw new TypeError(`${field} must be one of: ${allowed.join(", ")}`);
+  }
+  return value;
+}
+function normalizeIndexUnit(unit, field) {
+  const inputSources = [...new Set(unit.inputSources.map((source, index) => requiredIndexText(source, `${field}.inputSources[${index}]`)))];
+  if (inputSources.length === 0) {
+    throw new TypeError(`${field}.inputSources must contain at least one registered source name`);
+  }
+  const moduleType = requiredIndexEnum(unit.moduleType, `${field}.moduleType`, CODE_INDEX_MODULE_TYPES);
+  const moduleTypes = [...new Set([moduleType, ...(unit.moduleTypes ?? []).map((value, index) => requiredIndexEnum(value, `${field}.moduleTypes[${index}]`, CODE_INDEX_MODULE_TYPES))])];
+  if (moduleTypes.includes("unknown") && moduleTypes.length > 1) {
+    throw new TypeError(`${field}.moduleTypes cannot combine unknown with a known module type`);
+  }
+  const facets = [...new Set((unit.facets ?? []).map((value, index) => requiredIndexEnum(value, `${field}.facets[${index}]`, CODE_INDEX_MODULE_FACETS)))];
+  return {
+    id: requiredIndexText(unit.id, `${field}.id`),
+    inputSources,
+    outputOwner: requiredIndexText(unit.outputOwner, `${field}.outputOwner`),
+    moduleType,
+    moduleTypes,
+    facets,
+    ...unit.moduleTypeEvidence === undefined ? {} : {
+      moduleTypeEvidence: unit.moduleTypeEvidence.map((item, index) => requiredIndexText(item, `${field}.moduleTypeEvidence[${index}]`))
+    },
+    outputProfile: requiredIndexEnum(unit.outputProfile, `${field}.outputProfile`, CODE_INDEX_OUTPUT_PROFILES),
+    responsibility: requiredIndexText(unit.responsibility, `${field}.responsibility`),
+    entries: unit.entries.map((entry, index) => requiredIndexText(entry, `${field}.entries[${index}]`)),
+    pageKinds: unit.pageKinds.map((kind, index) => requiredIndexText(kind, `${field}.pageKinds[${index}]`)),
+    protocols: unit.protocols.map((protocol, index) => requiredIndexText(protocol, `${field}.protocols[${index}]`)),
+    dependencies: unit.dependencies.map((dependency, index) => requiredIndexText(dependency, `${field}.dependencies[${index}]`)),
+    exclusions: unit.exclusions.map((exclusion, index) => requiredIndexText(exclusion, `${field}.exclusions[${index}]`)),
+    ...unit.lifecycle === undefined ? {} : {
+      lifecycle: requiredIndexEnum(unit.lifecycle, `${field}.lifecycle`, CODE_INDEX_LIFECYCLES)
+    },
+    ...unit.sourceOfTruth === undefined ? {} : { sourceOfTruth: requiredIndexText(unit.sourceOfTruth, `${field}.sourceOfTruth`) },
+    capability: requiredIndexEnum(unit.capability, `${field}.capability`, CODE_INDEX_CAPABILITIES)
+  };
+}
+function assertUniqueIndexUnits(units, field) {
+  const ids = new Set;
+  const owners = new Set;
+  for (const unit of units) {
+    if (ids.has(unit.id))
+      throw new TypeError(`${field} contains duplicate id: ${unit.id}`);
+    if (owners.has(unit.outputOwner)) {
+      throw new TypeError(`${field} contains duplicate outputOwner: ${unit.outputOwner}`);
+    }
+    ids.add(unit.id);
+    owners.add(unit.outputOwner);
+  }
+}
+
+// src/phases.ts
 var getSourceType = (sourceDefinition) => {
   if (sourceDefinition.kind === "source.collection" || sourceDefinition.kind === "source.ref") {
     if (!("type" in sourceDefinition)) {
@@ -7239,6 +7389,26 @@ var extractTs = (definition) => {
     throw new ExtractTsConfigurationError("extractTs entries must contain at least one source-relative file path");
   }
   const entries = definition.entries === undefined ? undefined : [...new Set(definition.entries.map(normalizeExtractEntry))];
+  const defaultSourceName = sourceDefinition.kind === "source.collection" ? sourceDefinition.type : sourceDefinition.name;
+  const exportedOnly = definition.exportedOnly ?? mode === "exports";
+  const indexUnits = (definition.indexUnits ?? (sourceDefinition.kind === "source.collection" ? [] : [{
+    id: defaultSourceName,
+    inputSources: [defaultSourceName],
+    outputOwner: defaultSourceName,
+    moduleType: mode === "exports" ? "sdk-library" : "unknown",
+    moduleTypes: [mode === "exports" ? "sdk-library" : "unknown"],
+    facets: mode === "exports" ? ["public-api"] : [],
+    moduleTypeEvidence: mode === "exports" ? ["Package export entries selected by extractTs exports mode."] : [],
+    outputProfile: mode === "exports" ? "public-api-reference" : "module-map",
+    responsibility: mode === "exports" ? "Index the stable exported contracts of this module." : "Index the configured structural scope of this module.",
+    entries: entries ?? [],
+    pageKinds: mode === "exports" ? ["public-contract"] : ["module-map"],
+    protocols: [],
+    dependencies: [],
+    exclusions: [],
+    capability: "complete"
+  }])).map((unit, index) => normalizeIndexUnit(unit, `extractTs indexUnits[${index}]`));
+  assertUniqueIndexUnits(indexUnits, "extractTs indexUnits");
   const phase = {
     kind: "phase.extract.ts",
     id: `extract:${sourceId}:${definition.collection}`,
@@ -7257,7 +7427,9 @@ var extractTs = (definition) => {
     include: definition.include ?? ["src/**/*.{ts,tsx}"],
     mode,
     ...entries !== undefined ? { entries } : {},
-    exportedOnly: definition.exportedOnly ?? mode === "exports",
+    exportedOnly,
+    indexPlan: definition.indexUnits !== undefined || sourceDefinition.kind !== "source.collection" && mode === "exports" && exportedOnly ? "declared" : "inferred",
+    indexUnits,
     out: {
       kind: "codegraph-entities",
       candidateFile: ".tmp/context-runtime/lifecycle/candidates.jsonl",
@@ -7280,6 +7452,8 @@ var extractCustom = (definition) => {
     throw new TypeError(`extractCustom collection must be codegraph: ${definition.collection}`);
   }
   const sources = definition.sources.map((sourceDefinition) => bindSourceType(sourceDefinition, "repo", "extractCustom source"));
+  const indexUnits = (definition.indexUnits ?? []).map((unit, index) => normalizeIndexUnit(unit, `extractCustom indexUnits[${index}]`));
+  assertUniqueIndexUnits(indexUnits, "extractCustom indexUnits");
   return {
     kind: "phase.extract.custom",
     id,
@@ -7292,6 +7466,9 @@ var extractCustom = (definition) => {
     }],
     sources,
     collection: definition.collection,
+    indexPlan: definition.indexUnits === undefined ? "inferred" : "declared",
+    indexUnits,
+    ...definition.inspect === undefined ? {} : { inspect: definition.inspect },
     extract: definition.extract
   };
 };
@@ -11940,7 +12117,7 @@ var normalizePackageAssetOptimization = (assets) => {
 };
 var normalizePackageAssets = (assets) => {
   if (assets === undefined)
-    return;
+    return { delivery: "bundle" };
   if (assets.delivery === "bundle") {
     return {
       delivery: "bundle",
@@ -12017,7 +12194,7 @@ var kbPackage = (definition) => {
     ...base,
     navigation: normalizePackageNavigation(definition.navigation),
     ...distribution === undefined ? {} : { distribution },
-    ...assets === undefined ? {} : { assets }
+    assets
   };
 };
 var llmsPackage = (definition) => ({
@@ -12028,6 +12205,7 @@ export {
   source,
   reviewValidity,
   resolveSourceReference,
+  requiredCodeIndexCoverage,
   mdxJsonDocs,
   loadSourcesRegistry,
   llmsPackage,
@@ -12061,5 +12239,11 @@ export {
   DEFAULT_REPO_SOURCES_REGISTRY_PATH,
   DEFAULT_PACKAGE_NAVIGATION,
   DEFAULT_LARK_SOURCES_REGISTRY_PATH,
-  DEFAULT_FILE_SOURCES_REGISTRY_PATH
+  DEFAULT_FILE_SOURCES_REGISTRY_PATH,
+  CODE_INDEX_OUTPUT_PROFILES,
+  CODE_INDEX_MODULE_TYPES,
+  CODE_INDEX_MODULE_FACETS,
+  CODE_INDEX_LIFECYCLES,
+  CODE_INDEX_COVERAGE_KINDS,
+  CODE_INDEX_CAPABILITIES
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context",
-  "version": "0.6.11",
+  "version": "0.6.16",
   "type": "module",
   "description": "Declarative SDK for Context knowledge sources, workflows, review, and package outputs",
   "license": "MIT",

package/phases.d.ts

@@ -1,5 +1,8 @@
 import { type FileCaptureProcessorDefinition, type KnowledgeCollection, type MarkdownTransform, type PackageKind, type PackageSelectDefinition, type DocumentMainlineCollection } from "./contracts.js";
 import { DOCUMENT_COMPILE_ACTION_SCHEMA_VERSION } from "./documentEvidence.js";
+import { type CodeIndexCoverageKind, type CodeIndexInspectionAdapter, type CodeIndexUnitPlan } from "./codeIndexPlan.js";
+export { CODE_INDEX_CAPABILITIES, CODE_INDEX_COVERAGE_KINDS, CODE_INDEX_LIFECYCLES, CODE_INDEX_MODULE_FACETS, CODE_INDEX_MODULE_TYPES, CODE_INDEX_OUTPUT_PROFILES, ExtractTsConfigurationError, NO_ENTRY_DETECTED, requiredCodeIndexCoverage, } from "./codeIndexPlan.js";
+export type { CodeIndexCapability, CodeIndexCapabilityGap, CodeIndexCoverageKind, CodeIndexInspectionAdapter, CodeIndexInspectionContext, CodeIndexInspectionFinding, CodeIndexInspectionFindingKind, CodeIndexInspectionResult, CodeIndexLifecycle, CodeIndexModuleFacet, CodeIndexModuleType, CodeIndexOutputProfile, CodeIndexUnitPlan, } from "./codeIndexPlan.js";
 import type { DocumentSourceDefinition, DocumentSourceType, FileSourceDefinition, FileSourceReference, LarkSourceDefinition, LarkSourceReference, RepoProjectSourceDefinition, SourceCollectionReference, SourceDefinition } from "./sources.js";
 export type PhaseResourceReference = {
     kind: "source";
@@ -66,6 +69,8 @@ export type ExtractTsPhaseDefinition = {
     mode: "exports" | "scan";
     entries?: readonly string[];
     exportedOnly: boolean;
+    indexPlan: "declared" | "inferred";
+    indexUnits: readonly CodeIndexUnitPlan[];
     transform?: MarkdownTransform | readonly MarkdownTransform[];
     out: {
         kind: "codegraph-entities";
@@ -97,22 +102,37 @@ export interface CustomCodeCandidateEdge {
     relationType: string;
     evidence: readonly CustomCodeEvidence[];
 }
+export interface CustomCodeCandidateSection {
+    id: string;
+    kind: CodeIndexCoverageKind;
+    title: string;
+    markdown: string;
+    evidence: readonly CustomCodeEvidence[];
+}
 export interface CustomCodeCandidateDraft {
     nodeRef: string;
     kind: string;
     visibility: string;
     module: string;
-    markdown: string;
+    markdown?: string;
+    /** Evidence-scoped aggregate sections used to prove output-profile coverage. */
+    sections?: readonly CustomCodeCandidateSection[];
     evidence: readonly CustomCodeEvidence[];
     review: CustomCodeCandidateReview;
     edges?: readonly CustomCodeCandidateEdge[];
 }
 export interface CustomCodeExtractionResult {
-    candidates: readonly CustomCodeCandidateDraft[];
+    candidates: readonly CustomCodeCandidateDraft[] | Iterable<CustomCodeCandidateDraft> | AsyncIterable<CustomCodeCandidateDraft>;
 }
 export interface CustomCodeExtractionContext {
     projectRoot: string;
     runId: string;
+    /** CLI-resolved source roots. Use these paths instead of environment-specific checkout paths. */
+    sources: readonly {
+        name: string;
+        materializedAt: string;
+        absolutePath: string;
+    }[];
 }
 export type CustomCodeExtractor = (context: CustomCodeExtractionContext) => CustomCodeExtractionResult | Promise<CustomCodeExtractionResult>;
 export type ExtractCustomPhaseDefinition = {
@@ -122,13 +142,11 @@ export type ExtractCustomPhaseDefinition = {
     writes: readonly PhaseResourceReference[];
     sources: readonly RepoProjectSourceDefinition[];
     collection: "codegraph";
+    indexPlan: "declared" | "inferred";
+    indexUnits: readonly CodeIndexUnitPlan[];
+    inspect?: CodeIndexInspectionAdapter;
     extract: CustomCodeExtractor;
 };
-export declare const NO_ENTRY_DETECTED: "NO_ENTRY_DETECTED";
-export declare class ExtractTsConfigurationError extends TypeError {
-    readonly code: "NO_ENTRY_DETECTED";
-    constructor(message: string);
-}
 export type CaptureFilePhaseDefinition = {
     kind: "phase.capture.file";
     id: string;
@@ -226,12 +244,15 @@ export declare const extractTs: (definition: {
     mode?: "exports" | "scan";
     entries?: readonly string[];
     exportedOnly?: boolean;
+    indexUnits?: readonly CodeIndexUnitPlan[];
     transform?: MarkdownTransform | readonly MarkdownTransform[];
 }) => ExtractTsPhaseDefinition;
 export declare const extractCustom: (definition: {
     id: string;
     sources: readonly RepoProjectSourceDefinition[];
     collection: "codegraph";
+    indexUnits?: readonly CodeIndexUnitPlan[];
+    inspect?: CodeIndexInspectionAdapter;
     extract: CustomCodeExtractor;
 }) => ExtractCustomPhaseDefinition;
 export declare const reviewValidity: (definition: {