@c4a/context-cli 0.6.11 → 0.6.16

package/providers/context/resources/dialogue/code-extraction.md

@@ -6,10 +6,16 @@ mediaType: text/markdown
 
 # Code-extraction dialogue
 
-Describe the proposed code scope before SDK fields. State:
+Begin with the Route-selected batch inspection. Classify all modules from that
+evidence before opening any archetype template, inspect source files only for
+unresolved facts, then read every matching Route-recommended type or facet
+template. For all modules in the current batch, state:
 
 - the confirmed repository module;
-- which files are included;
+- the primary and additional module types, composable facets, evidence paths,
+  stable responsibility, entries, external protocols and important dependencies;
+- the output owner/profile and planned page kinds;
+- which files or generated/derived areas are excluded;
 - whether extraction follows configured/public entries or scans all matched
   files;
 - whether internal symbols are included; and
@@ -22,23 +28,47 @@ whether a project-owned adapter supplies the missing mapping. Do not ask the
 user to choose between parser package names unless two genuinely incompatible
 technical choices remain.
 
+In fully managed mode, write the same fields into one batch report instead of
+asking or narrating them module by module. A typed `material-required` gap and
+the measured scale limit remain observable in both modes; advisory risks do not
+create another confirmation Gate.
+
 If a selected package lacks a standard entry, offer two Context-owned choices:
 configure source-relative API roots, or use scan mode for all declarations in
 the confirmed file scope. Do not ask the user to change source code or package
 metadata to satisfy Context.
 
-For a non-TypeScript source or an aggregated repository protocol, explain that
-the project will use `extractCustom()`. If an optional structural extractor is
-available, use it for syntax facts and keep project-specific classification in
-the project callback; do not imply that installing it adds a new CLI phase.
+`extractTs()` creates one candidate page per selected symbol and assigns a
+source to one index unit. Use it only when that granular shape is the intended
+public reference. For an aggregate module map, registry, protocol index, or
+cross-module flow—or multiple units over one source—use `extractCustom()` and
+declare candidate ownership. If an optional structural extractor is available,
+use it for syntax facts and keep project-specific classification in the project
+callback; do not imply that installing it adds a new CLI phase.
 
-Run the route-selected dry-run first. Report discovered, AST-analyzed, skipped,
-symbol, relation, and candidate counts separately, plus resolved entries,
-exported/internal counts, symbol-kind counts, and the proposed knowledge tree.
+Do not predict page counts from the template examples. Run the route-selected
+batch preview once after the plan is configured. Report discovered, AST-analyzed,
+skipped, symbol, relation, and candidate counts separately, plus resolved
+entries, exported/internal counts, symbol-kind counts, output ownership and the
+proposed knowledge tree.
 Treat those fields as structural scope evidence, not a semantic ranking. Stop
 when the preview crosses the confirmed module boundary or the module
 identity/path shape is wrong.
 
+Apply the per-index-unit policy exactly: up to 100 pages proceeds; 101–300 pages
+warns and proceeds; more than 300 pages stops even in fully managed mode. Group
+all oversized or capability-gap units into one explanation and one plan-revision
+Gate instead of asking about modules one by one. If the revision changes a
+module's classification, read the newly selected template before editing the
+plan; otherwise reuse the current classification and avoid another
+classification dialogue.
+
+When blocked, propose only legal revisions: narrow `include`, exclude generated
+or mirrored areas, enable `exportedOnly`, change to an aggregate
+`extractCustom()` shape, or register real child sources. Do not split one
+`extractTs()` source into overlapping index units. Report a batch-total page
+advisory as a cost signal, not a new Gate.
+
 For a multi-module round, finish every pending extraction target before opening
 one Review. For an unchanged repeat run, explain that no added, changed, or
 removed symbols need a decision. Mention `extractTs`, `include`, `entries`,

package/providers/context/resources/dialogue/package-output.md

@@ -25,14 +25,11 @@ package namespace. Ask whether Skills need a short optional prefix, then
 maintain their complete final names in the template. Do not expose downstream
 layout terminology or ask for platform-specific identity fields.
 
-Also ask how referenced resources should be delivered. Offer Git raw links,
-bundled files, or explicit omission. Git raw may derive a commit-pinned GitHub
-URL when the workspace is in Git, or use an author-provided HTTPS `urlPrefix`
-for resources published from another repository. A literal branch in that
-prefix is an explicit project choice, not a Context default. If neither local
-Git nor an explicit prefix is available, offer only bundle or omit.
-State that publishing the referenced resources and making private raw hosts
-reachable are the package author's responsibility; Context does not probe them.
+Referenced resources are bundled by default. Explain the 1 MiB per-image and
+40 MiB total-image package limits only when relevant. Offer Git raw links or
+explicit omission only when the author asks for another delivery policy. Git
+raw uses an immutable derived URL or an author-provided HTTPS `urlPrefix`;
+publishing and access remain the author's responsibility.
 
 Do not offer a hidden `both` shortcut. If the user wants multiple outputs,
 declare and inspect one first, then obtain confirmation for the next. Mention

package/providers/context/resources/manuals/guides/package-outputs.md

@@ -95,26 +95,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/providers/context/resources/manuals/reference/code-extractors.md

@@ -12,8 +12,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 |
@@ -49,6 +50,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
@@ -56,23 +70,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
@@ -89,6 +98,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/providers/context/resources/manuals/reference/package-templates.md

@@ -37,10 +37,7 @@ kbPackage({
     foldDirectoryIndexes: true,
     maxInlineEntries: 50,
   },
-  assets: {
-    delivery: "git-raw",
-    urlPrefix: "https://code.example.com/team/knowledge/raw/{commit}",
-  },
+  assets: { delivery: "bundle" },
 });
 ```
 
@@ -62,10 +59,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
@@ -76,14 +79,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
@@ -114,26 +117,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 })`.
@@ -287,13 +276,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/providers/context/resources/manuals/reference/project-api.md

@@ -612,8 +612,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
@@ -631,7 +688,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
@@ -663,6 +722,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
@@ -706,19 +780,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",
@@ -727,18 +835,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
@@ -778,7 +918,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/providers/context/resources/manuals/reference/template-variables.md

@@ -237,9 +237,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/providers/context/resources/procedures/close-and-build.md

@@ -18,6 +18,11 @@ Build runs only after close and verification are current. It writes declared
 packages under `dist/` and records an inventory receipt with added, updated,
 removed, and index changes.
 
+When document optimization is enabled, its current revision batch must also be
+resolved before build. Build compiles each approved page through its optional
+`__revision.md` sidecar and records the policy and decision counts in the
+package inventory. Revision sidecars are never emitted as separate knowledge.
+
 Run only the current route command, then evaluate again. A successful build
 means the currently declared scope is current; newly captured or newly declared
 targets can reopen earlier graph nodes.