@c4a/context 0.7.0 → 0.7.4

package/docs/guides/code-indexer-skill-authoring.md

@@ -34,18 +34,22 @@ rules, metric operators and thresholds.
 4. **Activation and profiles.** Declare strong/supporting/negative signals.
    Dependency names are candidates, not runtime proof. One module may combine
    one primary profile with supporting/extensions and selected composers.
-5. **Sources and Artifacts.** Declare source roles and logical-unit intent;
+5. **Sources and Artifacts.** Write for a reader outside the indexed module:
+   make responsibility, stable interfaces/entrypoints, handoffs and the core
+   state, failure, operation and source-of-truth facts needed for correct use
+   and attribution discoverable. Declare source roles and logical-unit intent;
    select only CLI-registered Artifact kinds/policy variants. Keep logical unit
-   identity separate from physical Artifact count.
+   identity separate from physical Artifact count, and measure useful coverage
+   by answered profile questions rather than symbol or path counts.
 6. **Inventory protocols.** Close every input member with an explicit
    disposition. Use stable aggregation, full-path example identity and
    structured chain decisions; do not substitute page prose for inventory.
-7. **Metrics.** Reference registered metric ids and revision guidance. The CLI
-   alone owns recommended ranges, `inflation-sensitive` 150% enforcement and
-   mechanical audit results; a Provider cannot return a pass or threshold.
-8. **Revision boundary.** Use metric-specific revisions for at most the Route-
-   supplied attempts. After three failed attempts, report the complete issue
-   set for the human Gate. Forced approval cannot bypass base integrity rules.
+7. **Metrics.** Reference registered metric ids as reader-quality guidance.
+   The CLI may report advisory observations, but a Provider cannot return a
+   pass, threshold, retry count, or risk-acceptance decision.
+8. **Revision boundary.** Hard contract or source failures block at their
+   owner. Reader-quality feedback reopens the same Author or Composer through
+   `context revise`; it does not create a metric retry ledger or risk Gate.
 9. **Reader questions.** Declare reusable question templates with stable refs,
    target domains and allowed evidence contracts. Do not make a question id
    globally unique to one SubjectKey group.
@@ -68,11 +72,13 @@ rules, metric operators and thresholds.
 15. **Marketplace layout.** Archives keep one top-level Skill directory with
     `SKILL.md`, the manifest and referenced runtime resources. Exclude tests,
     caches, credentials, local paths and Host-specific temporary manifests.
-16. **Material handoff.** Return structured material questions when required
-    evidence is missing. Bind owner cell, question contract, Subject target and
-    intended landing. Never render gaps as empty pages or speculative prose;
-    Context owns the retained ledger, checkpoints, reconciliation and any
-    Markdown answer run.
+16. **Material gaps.** Return a canonical question disposition in the same
+    main Result when required evidence is missing. Never render a gap as an
+    empty page or speculative prose. Registered Markdown or tool material may
+    enrich the same main indexing batch before Candidate generation; do not
+    create a separate answer operation, Candidate, checkpoint or Review. The
+    CLI projects allowed enrichment material into that same Authorized
+    Workset View; Providers must not reopen registered sources themselves.
 17. **Backend profiles.** Test neutral RPC/HTTP, Gateway, Event/function,
     Cron/worker, sync/reconciliation, stateful service/storage and library
     shapes. Local facts remain baseline when optional remote metadata is absent.
@@ -115,6 +121,11 @@ Markdown Indexers must reuse the same Node when the SubjectKey is equal. An
 enricher uses the supplied TargetResolutionView (`resolved`, `absent` or
 `ambiguous`) and never guesses identity from a title or path resemblance.
 
+Every Section uses the exact `document_kind`, `reader_goal` and
+`artifact_kind` tuple from the current profile's unique layout mapping. The
+Provider never returns a collection name; Context resolves the collection from
+that tuple and rejects missing or ambiguous mappings.
+
 ## Publication gate
 
 Do not publish until the exact packed artifact passes manifest/schema

package/docs/guides/markdown-indexer-skill-authoring.md

@@ -62,6 +62,11 @@ alphabetic batches. Do not create one page per heading/member or inflate page
 count to satisfy a metric. The CLI owns Artifact-policy eligibility, physical
 fan-out audit, layout actualization and the final Candidate compile.
 
+The first actual Section of each reader Artifact begins with one concise,
+source-backed level-one heading. Context uses that heading as the outline and
+Candidate Review display title. It never participates in SubjectKey derivation
+or ownership, and later Sections in the same Artifact do not repeat it.
+
 Each Section carries exact positive and negative dependency refs. Incremental
 impact is Section/Artifact-local: a source membership, question denominator,
 candidate pool, evidence span or run-envelope change invalidates only the
@@ -77,24 +82,19 @@ hard metrics. Deterministic blocks render only registered facts; semantic prose
 must cite consumed evidence. Placeholders, speculation, fabricated transitions
 and “content unavailable” pages are invalid even when the structure looks rich.
 
-## Material questions and answers
+## Missing material
 
 When current material cannot answer a required canonical question, return the
 exact material-question disposition for the supplied owner cell, question
 contract and Subject target. Do not invent a new question contract or landing.
-Context stores the retained `material_gap_ledger`, derives the
-MaterialQuestionWorkset and schedules a separate `material-answer` operation.
-
-A material-answer Result contains only the question revision and source/span/
-content-digest claims allowed by the workset. It does not return reader prose,
-future Artifact/Section identity or self-authored EvidenceItem refs. Context
-canonicalizes evidence, reviews the answer binding, derives the planned answer
-and actualizes it into an approved landing. Stale source, Provider, question,
-binding or landing returns the ledger item to unresolved atomically.
+Context reports the unresolved set in current reconciliation state; it does not
+create a second checkpoint ledger or published gap artifact.
 
-The ledger, answer body, answer provenance and revision scratch pages do not
-enter reader Markdown or `dist`. A blocking gap closes only through current
-evidence or an explicit non-delegable requirement change.
+Capture the missing Markdown or other source normally, then rerun `main-index`.
+The new Result updates the same knowledge Candidate and enters the same final
+content Review. There is no answer-only operation or evidence-specific Review.
+A blocking gap closes only through current source or an explicit non-delegable
+requirement change.
 
 ## Markdown author fixture checklist
 
@@ -109,7 +109,7 @@ Release fixtures should cover:
   move in both directions;
 - protected values, links, images/assets and source-span fidelity;
 - editorial positives and placeholder/speculation/unsupported negatives;
-- material-answer approval, stale/rebind/deletion recovery and no-output-leak;
+- material-gap runtime recovery, main-index retry and no-output-leak;
 - Section-local incremental invalidation, new membership/denominator/candidate
   pool changes and unaffected Section reuse.
 

package/docs/reference/code-extractors.md

@@ -1,146 +1,39 @@
-# Code Extractor Selection
+# Code Parser Selection
 
-Use this manual only when the current code-extraction Route asks the Agent to
-choose or declare an extractor. The CLI reports repository facts; the Agent
-chooses how those facts become source-backed code knowledge.
+Code parsing is an Indexer Provider implementation detail. A knowledge
+workspace selects the Provider and profile in `src/indexers.yaml`; it does not
+declare a separate extraction phase in `src/index.ts`.
 
-## Inspect Before Declaring
+## Selection order
 
-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:
+1. Identify the target boundary and the knowledge questions.
+2. Let the selected Provider inspect language, manifests, entries, routes, and
+   contracts.
+3. Use the smallest parser set that covers those questions.
+4. Keep deterministic parser output as Provider facts; let the Provider author
+   reader-oriented knowledge pages from those facts and readable sources.
 
-| Signal | Technology candidate |
-|---|---|
-| `package.json` | TypeScript, TSX, JavaScript, or JSX |
-| `go.mod` | Go |
-| `Cargo.toml` | Rust |
-| `pyproject.toml` or `setup.py` | Python |
-| `pom.xml` or `build.gradle` | Java or JVM |
-| multiple manifests | a mixed module that may need more than one extractor |
-
-Do not select `extractTs()` merely because a repository contains some
-TypeScript. Decide against the exact confirmed module and include boundary. A
-mixed module may compose multiple structural passes; parser selection is not an
-exclusive repository-wide switch.
-
-## Selection Order
-
-Use the narrowest reusable capability that covers the confirmed source:
-
-1. Use a Context-owned phase when its contract matches the source.
-2. Otherwise use a reusable structural package inside `extractCustom()`.
-3. If no reusable package covers the syntax or repository protocol, implement a
-   project-owned adapter and keep it in the Context workspace.
-
-Current reusable capabilities are:
-
-| Source fact | Preferred capability | Lifecycle integration |
-|---|---|---|
-| TypeScript/JavaScript package or TSX/JSX file scope | `extractTs()` | Context-owned phase |
-| Go declarations, imports, calls, and common HTTP routes | `@c4a/extract-go` | call from `extractCustom()` |
-| Rush workspace packages, tags, dependencies, entries, and owners | `@c4a/extract-rush` | call from `extractCustom()`; may complement a language extractor |
-| React Router route declarations | `extractReactRouterRoutes()` from `@c4a/extract-ts` | call from `extractCustom()`; complements ECMAScript 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
-not match the inspected source.
+## Community parser packages
 
-## Read The Contract Before Extending
-
-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.
-
-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
-`extractCustom()`; it must not write lifecycle, knowledge, or Review files.
-Framework-specific classification and rendering remain in the project. The CLI
-and structural parser must not infer product meaning.
-
-## Decision To Report
-
-Before the first extraction preview, state briefly:
-
-- the inspected module and manifest signals;
-- the selected Context phase or structural package;
-- 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
-codeindex or reuse an unrelated parser.
+| Package | Useful structural facts |
+|---|---|
+| `@c4a/extract-ts` | TypeScript/JavaScript symbols, exports, imports, calls, and React Router routes |
+| `@c4a/extract-go` | Go declarations, imports, calls, and common HTTP routes |
+| `@c4a/extract-rush` | Rush projects, tags, entries, dependencies, and owner boundaries |
+| `@c4a/extract` | Shared extraction result and adapter contracts |
 
-## Plan Before Parsing
+These packages do not create Candidate rows, write `knowledge/`, or control
+Review. The Code Indexer Provider owns those lifecycle responsibilities.
 
-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`, record every Markdown file actually read in `documents`, 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.
+## Unsupported technologies
 
-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.
+When the current Provider cannot parse a required boundary, first use its
+supported customization ladder (`config`, instruction append, template
+override, then program extension). Add a reusable parser to the Provider only
+when the same technology boundary is useful across projects. Do not create a
+project-local parallel knowledge pipeline.
 
-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
-at least one evidence-scoped `section`; there is no page-level Markdown
-fallback. 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.
+Parser coverage is complete when every required inventory item has an explicit
+disposition and the resulting pages answer the declared reader questions. A
+large symbol count by itself is not useful coverage.
 
-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/indexer-provider-protocol.md

@@ -184,8 +184,8 @@ Bundles, expanded variants, semantic split parts and the single CLI
 `catalog-fallback` parent do not. Counts up to 100 continue, 101 through 300
 continue with a warning, and counts above 300 return the non-Gate
 `indexer-plan-revision-required` outcome before any author workset runs. That
-partial outcome consumes neither a user Gate nor the three-attempt profile
-revision ledger.
+partial outcome reopens the owning semantic step; it does not create a profile
+revision ledger or an override route.
 
 Artifact content has three mechanically separate layers. `facts[]` contains
 canonical, source-bound values and never reader prose. A structured
@@ -310,32 +310,20 @@ Graph outcome. Only `selection-validation-required` returns a selection
 proposal input. The Route writes no workspace or runtime state, and neither a
 visible-Skill claim nor the Route report authorizes Bundle materialization.
 
-## Contract overlay validation and trust
+## Contract overlay validation
 
 `validate-indexer-contract-overlays` recomputes the complete data-only overlay
 against the exact CLI base and operator contracts. Invalid DSL, executable
 fields, identity redefinition, threshold weakening, digest drift or a partial
-attestation/trust bundle fails before any authorization Route exists. A
-resolver's self-reported `verified` value is not an accepted input.
-
-A valid detached Ed25519 attestation is checked locally against a matching key
-in the complete Host trust-bundle policy, including key validity and
-revocation, and directly produces the common
-`context.indexer.overlay-trust-receipt/v1`. The receipt binds the exact Host
-adapter identity/version and management-authority digest as well as the policy
-digest, so any policy-envelope drift makes the audit stale. An unsigned overlay, an attestation
-without an installed trust bundle, or an attestation whose issuer/key is absent
-from the canonical bundle returns `authorization-required`; the request binds
-the exact attestation digest (or null) together with the
-project/overlay/base/operator/Provider/conformance digest set. The
-non-delegable `authorize-indexer-contract-overlay` Gate may issue that
-project-exact authorization under the independent
-`context.indexer-contract-overlay` authority; revalidation then produces the
-same trust-receipt protocol with trust class
-`project-authorized-exact-digest`. Cross-project or stale reports cannot be
-reused. Once the bundle contains the declared issuer/key, an invalid signature,
-expired key, revoked key, or malformed policy is a hard trust failure and
-cannot downgrade to project authorization.
+Provider identity fails validation. The selected Provider Bundle integrity is
+an exact input, not a self-reported trust assertion.
+
+Successful validation emits
+`context.indexer.overlay-validation-receipt/v1`. The receipt binds the exact
+project, overlay, base contract, operator contract, Provider Bundle integrity
+and canonical conformance report. There is no signature, KMS, trust-bundle or
+overlay-authorization protocol. Changing any bound digest requires
+revalidation; a stale receipt cannot be reused.
 
 ## Question amendment back-edge
 
@@ -347,8 +335,8 @@ and durable single-file journal. A Skill question ref is guidance only; it
 cannot provide or alter the contract payload.
 
 An overlay-backed question follows a different sequence. Context first
-recomputes overlay DSL conformance and verifies an enterprise or exact-project
-trust receipt. Only then may
+recomputes overlay DSL conformance and verifies the exact validation receipt.
+Only then may
 `context.indexer.overlay-question-amendment/v1` expand namespaced question and
 target-domain additions from that overlay. The target coverage domain must
 already be in scope and have one existing primary owner. The amendment is a
@@ -359,23 +347,24 @@ The executable sequence is
 `propose-overlay-question-amendment`,
 `confirm-overlay-question-amendment`, then
 `rebind-indexer-selection-to-requirement`. Proposal and rebind inputs carry the
-exact trusted overlay validation input and result; Context recomputes and
+exact overlay validation input and result; Context recomputes and
 compares that pair instead of accepting a detached receipt. Confirmation emits
 the exact amendment decision and performs no project write.
 
 The rebind Action then proves that Indexer/provider
 identity, operations, scopes, profile composition, requirement bindings, owner
-closure and read authority are byte-identical. It revalidates overlay trust,
+closure and read authority are byte-identical. It revalidates overlay
+conformance,
 reuses the exact staged Bundles, and reruns both static and final selection
 against the target requirement digest. Provider and SubjectKey authority must
 remain unchanged. Final selection resolves every CLI-base question back to its
-exact selected profile contract and requires one current trust/conformance proof
+exact selected profile contract and requires one current validation proof
 for every overlay question; forged bindings and duplicate, stale, or unused
 proofs fail before the final report is issued. The report binds the resulting
 question authority set digest. The resulting
 `context.indexer.overlay-question-registry-apply-proposal/v1` contains the full
 target `src/indexers.yaml` snapshot and binds the amendment, confirmation,
-overlay trust, rebound selection, SubjectKey schema set and finalized reports.
+overlay validation, rebound selection, SubjectKey schema set and finalized reports.
 The proposal goes through the same `stage-indexer-project-proposal` and
 `apply-indexer-project` Actions as ordinary registry/customization proposals.
 The latter dispatches this typed proposal to one expected-base CAS, project
@@ -403,9 +392,8 @@ verified or exact project-authorized program may use the `trusted-program` path,
 which is not an isolation claim. An untrusted program without a real sandbox is
 not executable.
 
-The program input remains the operation-discriminated
-`context.indexer.run-request/v1` (`main-index` or `material-answer`). Its output
-is `context.indexer.run-result/v1`, wrapped by
+The program input is `context.indexer.run-request/v2` with the single
+`main-index` operation. Its output is `context.indexer.run-result/v1`, wrapped by
 `context.indexer.controlled-program-result/v1` to bind the exact invocation and
 payload digest. Context still validates the operation-specific Result and
 recomputes mechanical gates independently.
@@ -423,9 +411,9 @@ program, instructions, templates, config, CLI/profile contracts and only
 `primary_resource_binding_digest`; a post-author resource cannot satisfy that
 schema.
 
-`context.indexer.main-workset/v1` digests its complete canonical payload. A
+`context.indexer.main-workset/v2` digests its complete canonical payload. A
 workset set permits only one author workset for an Indexer, owner cohort and
-group key. `context.indexer.main-transport-batch/v1` may carry several complete
+group key. `context.indexer.main-transport-batch/v2` may carry several complete
 worksets but intentionally has no batch identity, digest, page number or
 reader-facing name. Regrouping worksets for Host transport therefore cannot
 change an individual workset or Result identity.
@@ -440,17 +428,14 @@ same workset with the next authorized strategy. This path has no user Gate and
 does not consume profile-revision attempts; an exhausted strategy set routes
 to the CLI catalog fallback.
 
-Source and evidence are read through
-`context.indexer.workset-read-request/v1`. The stable request identity binds the
-current workset, read kind and exact authorized ref set. Cursor and page size
-are transport fields and do not enter that identity. Every response carries a
-digest of its canonical page payload; cursor fields are again excluded. The
-CLI closes a complete, acyclic cursor chain into
-`context.indexer.workset-read-receipt/v1`, requiring exact coverage of the
-requested refs. A main Result contains the canonically sorted receipt digest
-set, and operation validation compares it with the actual CLI-issued receipts.
-Changing a cursor, page size, call grouping or Host batch cannot manufacture a
-new logical unit such as `batch-1` or alter an Artifact identity.
+Context projects every source-specific fact, dependency and verified Provider
+fragment authorized for one main workset into the single
+`context.indexer.authorized-workset-view/v1` resource. The Agent reads that
+managed resource and uses its file locators directly. It does not construct
+source-specific reads, semantic windows, cursors or receipt fields. Workset,
+View and execution-request identity bind the accepted Result; Host call grouping
+cannot manufacture a new logical unit such as `batch-1` or alter an Artifact
+identity.
 
 Post-author composition uses its own
 `context.indexer.post-author-run-ledger/v1`; it never reuses primary main-run
@@ -526,7 +511,7 @@ derived under `knowledge/<collection>/` and never accepted from a Provider.
 
 Template Artifacts enter layout only after validated rendering. Only rendered
 Sections exist; an omitted optional projection does not create an empty
-Section, while a retained material gap remains a planned landing without
+Section, while a retained material gap remains unresolved without
 reader-visible placeholder content. Artifact Bundle purpose and `split_of`
 lineage are retained in the proposal. A proposal set rejects duplicate Node
 owners, Artifact identities, logical Section identities, Section placements
@@ -556,12 +541,9 @@ fan-out to an already approved Node, removing or renaming an Artifact,
 splitting/merging its declared lineage, moving a logical Section, or changing
 an approved collection/path is represented by a digest-bound layout change
 report and requires the human, non-delegable `confirm-layout-change` Gate.
-`context.indexer.layout-transition/v1` first validates an explicit
-no-planned-output state or a material-answer actualization whose digest and
-actual ArtifactRef/SectionRef all belong to the current proposal set; only
-then does it expose the conditional Gate. Replacing the proposal set makes the
-prior actualization stale. The legacy align Route remains available only until
-the workflow cutover; it is not an authority for the new Indexer protocol.
+`context.indexer.layout-transition/v1` binds the current proposal set and base
+projections before exposing the conditional Gate. No parallel align Route can
+approve or rewrite that transition.
 
 ## Explicit Result-bound Candidate compile
 
@@ -570,7 +552,7 @@ author Results from the durable main-run store. Its input repeats only the
 exact workset, execution-request, acceptance and Artifact Result digests; the
 CLI rejects a missing, extra, forged or stale Result reference before
 materialization. Callers cannot provide an alternate Result body, Provider
-contract, default plan or prose-compile payload.
+contract or a second document-authoring payload.
 
 The compiler validates every accepted run envelope and acceptance record,
 then binds each Candidate to the same Indexer Result, source identity,
@@ -593,62 +575,19 @@ customization may be proposed only after the explicit
 `indexer-customization-required` outcome and its capability-gap proof; compile
 itself never invents one.
 
-## Material-answer dispatch, baseline, Review, and layout actualization
-
-`context.indexer.material-question-workset/v1` is built only by the CLI after a
-material-gap checkpoint. It binds the current requirement and registry digests,
-question contract and target inventory, source-input digests, exact question
-revision, predecessor ledger revision, authorized sources, and eligible answer
-Indexers. Eligibility is derived from the registry-enabled `material-answer`
-operation, an enricher binding, the primary Provider manifest, read scope, and
-the evidence-kind intersection; callers cannot add an eligible Indexer.
-
-The CLI creates one `context.indexer.run-request/v1` per eligible answer Indexer.
-Its Provider composition fingerprint is recomputed from the answer Indexer,
-exact final Provider authority, and layer-composition view digest. The separate
-material-answer run ledger uses CAS transitions and content-addressed accepted
-records. A complete accepted empty Result is recovered without another dispatch;
-an interrupted running entry without its accepted record returns to pending.
-Before acceptance, every evidence claim must resolve through an exact current
-source-span read receipt, and unused or stale receipts are rejected.
-
-A `material-answer` Result cannot move a retained gap directly to an approved
-state. Context first validates the exact workset, question revision, eligible
-Indexer, Provider fingerprint, source authority, canonical spans, evidence
-content digests, provenance selector and minimum item/origin counts. Only a
-passing candidate can produce
-`context.indexer.material-answer-baseline-report/v1`. Its fixed Review scope is
-`question-target-source-span-evidence-binding`; the strict schema has no field
-for approving a reader page, Artifact content or final knowledge candidate.
-
-`context.indexer.material-answer-review-decision/v1` binds that report, the
-candidate set, workset, question revision and binding digest. Applying an
-`approved` decision uses the workset's predecessor ledger revision as a CAS
-base, consumes that workset and records the decision digest in the canonical
-answer binding. A successor ledger revision does not make the consumed workset
-self-stale. A rejected, insufficient, forged or differently scoped decision
-cannot create `answer-approved` state.
-
-Layout uses an unapplied
-`context.indexer.material-answer-layout-proposal/v1`. Each planned or existing
-answer landing must map uniquely to an actual `node:`, `artifact:` or
-`section:` ref. Before creating a resolved actualization, Context recomputes
-`context.indexer.material-answer-evidence-compatibility/v1` from the retained
-canonical evidence and current question/source authority. A changed source set,
-origin, snapshot, kind, span, content digest, provenance rule or minimum count
-reopens the gap to `unresolved`. A missing or colliding landing remains
-`answer-approved`; rejecting or replacing a layout proposal invalidates its
-resolved mappings back to `answer-approved`.
-
-`context.indexer.material-answer-flow-status/v1` is the admission fact for the
-next stages. An unresolved blocking gap stops layout. An `answer-approved`
-blocking gap may enter layout but cannot consume a conditional layout Gate or
-enter the main Candidate Review. Those two admissions become true only when
-every blocking answer has a current actualization for the exact layout digest.
-Optional gaps remain reported but do not become blocking. Final close removes
-a resolved ledger entry only when the approved structure projection carries
-the same question, binding, actualized target and complete canonical evidence
-ref set.
+## Material gaps and the single authoring path
+
+Reconciliation reports unresolved material gaps from the current accepted
+Results. Required gaps keep the current lifecycle blocked; optional gaps remain
+diagnostics in that report. Context does not create a second checkpoint, audit
+ledger, answer workset, or special close route for them.
+
+Newly captured Markdown, tool snapshots, or other authorized material re-enter
+the normal `main-index` operation. The affected Partition and Author worksets
+run again, reconciliation is recomputed, and the user reviews the resulting
+knowledge Candidate once. Successful close writes only approved knowledge and
+the recovery metadata in `knowledge/structure.yaml`, then clears transient
+Indexer runtime state.
 
 ## Detector and inspector
 
@@ -671,12 +610,19 @@ payloads fail closed.
 `present`, `absent` or `unknown`; a present signal requires evidence. Context,
 not the detector, derives `matched`, `not-matched` or `indeterminate`.
 
-An authoring inspector consumes `context.indexer.inspector-request/v1` and
-returns `context.indexer.inspector-result/v1`. Its evidence payload is the
-shared `context.indexer.evidence-adapter-result/v1`. Inspector files are always
+An authoring inspector consumes `context.indexer.inspector-request/v1`, including
+the exact active Provider profiles and Registry variants, and returns
+`context.indexer.inspector-result/v1`. Its evidence payload is the shared
+`context.indexer.evidence-adapter-result/v1`; its `fact_payloads` carry only
+validated profile variants, source Fact refs, bounded template variables and a
+structured availability status. Context requires one payload for every
+enrichment fact, verifies each payload digest and source ref, rejects Registry
+variant drift, then adapts the values into the same internal Authorized Workset
+View projection source used by other inputs. Inspector files are always
 `enricher` plus `lightweight-evidence`; they cannot own baseline inventory or
 contribute a denominator. The Result must close the requested inventory and
-authorized source/module scope. Detector and inspector entries run only from
+authorized source/module scope. No Inspector protocol or technical identifier
+is exposed as a separate Agent input. Detector and inspector entries run only from
 the reverified content-addressed stage through the same empty-environment,
 no-shell, bounded JSON subprocess runner. Timeout, stdin/stdout/stderr overflow,
 invalid UTF-8/JSON, undeclared evidence and scope expansion are typed failures;
@@ -793,27 +739,3 @@ structured claim passed owner-local evidence coverage, and lists every
 semantic-prose block or direct authored template variable as
 `semantic-prose-agent-review-required`. It does not scan free prose to claim
 that unsupported natural-language assertions were mechanically detected.
-
-## Material-question target exclusion
-
-A target exclusion is not a Provider Result and does not change the confirmed
-requirement. Context first emits
-`context.indexer.material-question-exclusion-report/v1` for one current
-unresolved `QuestionTargetKey`. The report binds the project, predecessor
-ledger revision, question-target inventory, question contract and revision,
-target ref/item digest, exact allowlisted reason, derived severity and the
-reader-visible impact.
-
-`confirm-material-question-exclusion` accepts only that report and always emits
-`context.indexer.material-question-exclusion-confirmation/v1` with human,
-non-delegable authority. Managed mode, Provider omission, wildcard targets and
-non-allowlisted reasons cannot create the decision. Apply revalidates the
-report against the current resolved question and ledger before retaining only
-the reason code and decision digest in the entry.
-
-The successor ledger is checkpointed with the predecessor revision through the
-same durable structure journal. A question contract, owner, target item,
-question revision or other pair dependency change replaces the retained
-exclusion with an unresolved entry in one checkpoint. The Material Gap ledger
-is intentionally absent from the main-workset identity, so this target-level
-decision does not invalidate unrelated main indexing worksets.

package/docs/reference/package-templates.md

@@ -348,9 +348,8 @@ src-N#span:<heading-hint> L<start>-<end>@<span-hash>
 
 The code symbol form includes the source-relative file so same-name symbols in
 different files resolve to one exact symbol-index row. Consumers should still
-treat the complete `source_ref` as opaque. Production codeindex pages keep
-`candidate_fingerprint` at the top level and do not duplicate this evidence in
-`code_origin`.
+treat the complete `source_ref` as opaque. Production pages do not expose
+Candidate fingerprints, Indexer digests, or `code_origin`.
 
 `#span:` refs retain source snapshot line ranges for human review, diffing, and
 stable re-pinning. They resolve against committed file/lark document snapshots,