@c4a/context 0.7.4 → 0.7.8

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

@@ -21,16 +21,37 @@ rules, metric operators and thresholds.
 
 ## Author contract checklist
 
+For generated API tables, test the final Candidate as well as the parser payload
+and template preview. Cover direct and supporting references, partial contracts,
+shared types with different implementation defaults, ambiguous or cross-file
+links, and an approved-page regeneration after the source changes. Keep a known
+field when only part of its implementation can be extracted. Do not equate an
+accepted result with a corrected page.
+
+Document what each supported language adapter actually establishes. Preserve
+written expressions without evaluating arbitrary code, distinguish declaration
+defaults from implementation defaults, and explain unresolved imports or types.
+Unknown material, an unsupported parse, and a renderer contradicting a known fact
+need different responses. Use existing material requests and repair routes;
+neither a new content-quality gate nor a Provider-specific retry ledger is needed.
+
 1. **Responsibility.** Classify supported code modules and produce evidence-
    bound partitions, logical units, Artifact Bundles and Results. Do not own
    source authorization, requirement approval, final review, CLI metrics or
-   package publication.
+   package publication. Source-specific Note/Sessions layers may contribute
+   declared guidance to a code page; they do not become another primary or
+   turn a conversation's proposed change into implemented code behavior.
 2. **Manifest.** Use the sole `context-indexer.yaml` field tree. Bind domains,
    profiles, operations/fragments, resources, source roles, logical units,
    customization support and composition without duplicate aliases.
 3. **Resource composition.** Combine only declared programs, profile-bound
    instructions, templates and optional detector/inspector resources. Omitted
    capabilities remain unsupported; natural language cannot add them.
+   Put any Agent-executed grouping rules in those declared instructions or
+   templates so Context delivers them with the current View. A partition
+   strategy id or digest is not an instruction resource. Context selects and
+   records strategy attempts; the Agent returns semantic groups and dispositions,
+   without discovering strategy implementations or managing fallback order.
 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.
@@ -84,8 +105,8 @@ rules, metric operators and thresholds.
     shapes. Local facts remain baseline when optional remote metadata is absent.
 18. **Versioning.** Use Skill/Provider SemVer, exact Provider pins and Bundle
     integrity. Fixed dependencies require exact versions and resolved
-    integrity. `@context-indexer-origin` is optional on local customizations
-    only and grants no authority.
+    integrity. `@context-indexer-origin` is required on workspace-local customization
+    files and grants no authority. It is not required on Provider bundle files.
 19. **Trust boundary.** Skill/manifest describes capabilities; the verified
     Bundle supplies bytes; workspace customization supplies project deltas;
     CLI contracts supply hard rules. Keep these four authorities distinct.
@@ -105,6 +126,30 @@ rules, metric operators and thresholds.
     instructions append → one template override → program extension →
     restricted replace. Document the proof and exit condition at every step;
     see [Provider selection and customization](./indexer-provider-and-customization.md).
+24. **Batch neutrality.** Write instructions for one semantic task and accept
+    that Context may transport several independent tasks in one Agent step.
+    Never derive identity, ordering, ownership or evidence scope from a task
+    key or batch position. Partition should decide consumer-facing ownership
+    from public anchors and unresolved material; detailed supporting Facts are
+    consumed in the bounded Author View rather than copied into every
+    Partition decision.
+
+The current Route delivers readable task material with goals and constraints
+first, followed by the authorized sources and facts. For behavioral explanations,
+read the complete source excerpts. Copy the displayed `source_items` into the
+section's `source_items`; use Fact references in `facts`, not as source items.
+Context resolves a text item's authorized source spans internally. Inventory
+identities and a repository reference do not identify section source material.
+These process-local excerpts are not new Facts or reader-page metadata. Do not
+reopen the repository or infer behavior from a locator alone when the supplied
+lines do not establish it. Batch size does not define a knowledge page boundary.
+
+Author task resources may point to one shared batch reading file. Read that path
+once, use shared material only for its listed task keys, and consider each task's
+own goals and source excerpts. Context shares identical material, not conclusions:
+prepare a separate result for each task and submit the `results[]` together through
+the current completion command. A retry includes the remaining tasks' material in
+full; no earlier batch file or additional reading command is required.
 
 ## Result and composition rules
 
@@ -116,8 +161,8 @@ an empty composer run still has a receipt. Composer selection is the
 intersection of registry selection, manifest declaration and current profile
 applicability, not array order.
 
-Use canonical SubjectKey schemas and the Context NodeRef formula. Code and
-Markdown Indexers must reuse the same Node when the SubjectKey is equal. An
+Use canonical SubjectKey schemas and the Context NodeRef formula. All selected
+Providers 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.
 

package/docs/guides/indexer-manifest-example.md

@@ -0,0 +1,103 @@
+# A minimal Provider manifest
+
+This is the smallest `context-indexer.yaml` that validates. Start from it and add
+only what your bundle implements. Reading an installed Provider's manifest is
+still worthwhile for behavior, but do not copy its declarations wholesale: they
+describe that bundle's resources, not yours.
+
+```yaml
+protocol: context.indexer.provider/v1
+id: context-example-indexer
+version: 1.0.0
+domains: [markdown]
+activation:
+  target_kinds: [document-set]
+  required_signals:
+    - id: prose-source
+      description: The target contains prose a reader would consult.
+  supporting_signals: []
+  negative_signals: []
+provides:
+  profiles: [reader-guide]
+  operations:
+    - id: main-index
+      consumes: context.indexer.main-workset/v2
+      produces: context.indexer.main-result/v1
+provider:
+  instructions:
+    - path: references/indexer.md
+      profiles: [reader-guide]
+  templates:
+    - { id: guide, profile: reader-guide, path: templates/reader-guide.md }
+customization:
+  supports: [instructions-append, template-override]
+```
+
+The three groups below are the reason this file exists: a field being absent from
+a manifest means something different depending on which group it belongs to.
+
+## Required
+
+The schema rejects a manifest missing any of these.
+
+- `protocol`, `id`, `version` — the protocol literal, a discoverable Provider
+  identity, and a semver version.
+- `domains` — at least one. Note and Sessions Providers use `markdown`.
+- `activation.target_kinds` — at least one. This is projected into the Provider
+  selection catalog, so it decides when your Provider can be selected at all.
+- `activation.required_signals` — at least one `{ id, description }`.
+- `activation.supporting_signals`, `activation.negative_signals` — the arrays
+  themselves are required; an empty array is the normal value.
+- `provides.profiles` — at least one. A profile whose id contains `/` is a
+  namespaced extension profile and additionally requires a matching
+  `composition.extensions` entry.
+- `provides.operations` — at least one. `main-index` is the only operation.
+- `provider` — at least one of `program`, `instructions` or `templates`.
+
+## Required once you declare a capability
+
+Declaring a customization capability without the resource that implements it is
+rejected at manifest validation:
+
+- `customization.supports` containing `config` requires `provider.config_schema`.
+- `customization.supports` containing `program-extend` requires
+  `provider.program`.
+
+Both inconsistencies used to surface only at use time — a non-empty config while
+validating the selection, `program-extend` while preparing the customization
+project. Declare only the hooks your bundle actually backs; `instructions-append`
+and `template-override` need no additional resource.
+
+Two related rules hold for every resource. Each `instructions` and `templates`
+entry must name a profile that `provides.profiles` declares, and every declared
+path must exist inside the bundle. The reverse also matters: a reference file
+that no entry declares is never delivered to the Agent, so adding a file is not
+the same as making it available.
+
+## Optional, and not uniformly enforced
+
+These are accepted and carry authoring intent. It is worth knowing which ones
+have a consumer, because declaring a field is not the same as gaining a check.
+
+- `quality_guidance.metric_ids` and `quality_guidance.repair` — read when
+  projecting Provider contract references; the repair path ships as a resource.
+- `activation.agent_questions` — questions this Provider wants asked before it
+  interprets material.
+- `provides.partition_strategies`, `provides.logical_units`,
+  `provides.composers`, `composition.extensions` — declare only what you
+  implement. Priorities must be unique per profile, and a composer contract
+  requires a post-author `derived-artifact-proposal` layer fragment.
+- `provider.completion_checks`, `provider.forbidden_fallbacks` — the schema
+  accepts and deduplicates them, and no execution consumer reads them today.
+  Declaring them records intent for a reader of the manifest; it does not add a
+  runtime check, and omitting them does not remove one. Material gaps in
+  particular are handled by result reconciliation, which does not read
+  `completion_checks`.
+
+## Validate it
+
+Use the installed SDK, as described in [the authoring
+guide](indexer-skill-creation.md). `parseIndexerProviderManifest` accepts the
+manifest text directly, which is enough to confirm the field tree; loading the
+bundle directory additionally confirms that declared resource paths resolve.
+Neither establishes that the Provider produces useful pages.

package/docs/guides/indexer-provider-and-customization.md

@@ -1,6 +1,6 @@
 # Indexer Provider selection and customization
 
-This guide is for workspace users and Agents selecting Code or Markdown
+This guide is for workspace users and Agents selecting Code, Markdown, Note or Sessions
 Indexer Providers. Provider authors should also read the dedicated
 [Code Indexer](./code-indexer-skill-authoring.md) or
 [Markdown Indexer](./markdown-indexer-skill-authoring.md) authoring guide.
@@ -12,33 +12,219 @@ authority. A Provider-only project does not create `src/indexer/`.
 
 ## Selection flow
 
-1. Inspect and confirm the complete `IndexRequirementSet`. A Provider,
+Follow `workflow.current` from `context status --format json` or `context run`.
+When the registry is missing, the Route names `src/indexers.yaml` in
+`configuration`: declare the confirmed requirements with `indexers: []`, then
+re-evaluate. The next Route supplies the Provider selection input and completion
+command. An unconfigured project does not begin Partition or require a fabricated
+primary owner. `run --managed --until blocked-or-complete` stops at the same
+configuration or semantic input boundary; it does not make those decisions.
+
+1. Form the complete requirements using the initial registry contract below.
+   Reuse the user's stated meaning and research the selected material. Ask about
+   consequential missing purpose or scope even in managed mode; delegation
+   covers execution and eligible reviews, not unanswered intent. A Provider,
    registry entry or Result may strengthen it but cannot remove targets,
    questions, evidence obligations or required owner cells.
-2. Run `context indexer catalog --format json` and report those CLI-bundled
-   entry Skills together with Indexer Skills already visible to the Host.
-   When the Host exposes an exact Skill root, read only its `SKILL.md`
-   frontmatter and sibling `context-indexer.yaml`; the manifest version is
-   authoritative and `metadata.context-provider-version` must match it. Group
-   the same Skill name and exact version into one conversational item with all
-   observed source types. An installed projection of an identical CLI-bundled
-   identity is not a second Provider; different versions remain distinct. Do
-   not scan `.claude`, `.codex`, `.agents` or arbitrary user directories.
-3. Route the path-free visible identities with
-   `context indexer route-indexer-provider-selection`. Try the applicable
-   community fallback once when the Route requests it.
-4. Statically validate the returned selection proposal before a Host resolves
-   any Bundle. Resolve only the emitted exact requests, then stage and validate
-   the complete content ledger.
-5. Apply the registry and any declared customization through the staged,
-   CAS-bound project proposal. A successful static report is not write or
-   execution authority.
+2. Select applicable Providers from the Host-visible Skills and the CLI-bundled
+   catalog already in the current Action input. No separate catalog command,
+   installed-Skill inventory, discovery report, or discovery-only confirmation
+   is required. Use the supplied exact identity and cli-bundled distribution
+   for shipped Providers, even when their Skills are also visible to the Host.
+   For a relevant external Skill, read only its exact Host-exposed frontmatter
+   and sibling `context-indexer.yaml` needed for selection. Do not guess versions
+   or scan `.claude`, `.codex`, `.agents` or arbitrary user directories. Different
+   versions remain distinct; discovery order is not selection precedence.
+3. Submit the semantic `indexers` and any relevant non-CLI `host_visible_skills`
+   through the current Route's `context action complete-current` command. The
+   latter may be empty; it is not an inventory or an additional discovery step.
+4. The CLI performs routing, validation, resolution and staging internally.
+   Shipped Providers load directly from this CLI release; only external
+   Providers may require the returned Host resolution Action. Follow the
+   current Route if a distribution is missing, a version conflicts, or program
+   execution needs authorization. Do not call the low-level commands below as
+   a second production workflow.
+5. The CLI atomically applies the validated registry and any declared
+   customization. A successful static report alone is not write or execution
+   authority. Resume from the returned current Route.
 
 Every required requirement/domain/source/module cell has exactly one primary
 owner. Read scope may overlap for supporting profiles, extensions and
 enrichers. Array order is never precedence. Each Provider layer retains its own
 exact version, integrity, portable distribution, config and resource
 fingerprints.
+For CLI-bundled instruction Providers, these fields record the original
+selection; they are not a requirement to reinstall old bytes when resuming.
+The current CLI supplies its installed Provider's guidance automatically.
+
+## Resuming after a tool update
+
+Continue with the current Route and its supplied source material. Agents do not
+compare Provider, Fact, signature or inventory fingerprints and do not rewrite
+them in an old request. Context rebuilds the internal result from the submitted
+page content and references.
+
+An added parser field or a more complete line range in the same unchanged file
+does not invalidate Author work. Continuation compares selected sources and
+subjects rather than serialized Fact payloads; accepted work retains its
+original request/result pair. New results retain the source references used for
+later updates. Repeated Fact references or reader-question answers are deduplicated;
+multiple sections may answer the same question. A question ID only identifies a
+reader question to cover, not an additional user approval.
+
+Missing references, a changed source file, a different page owner/subject or a
+concurrent write remain meaningful conflicts. Requirements, membership and result
+contracts still determine whether a task can be reused. This does not introduce a
+new Agent protocol, hash-entry step or persistent audit file.
+
+## Provider selection result
+
+Use the current Action's output schema, which defines the accepted Indexer
+entry fields. This is a `complete-current` input, not a replacement registry
+and not the requirements-only bootstrap schema.
+
+For one component-library requirement, the following template selects one
+primary Code Provider. Replace the quoted placeholders using the **current
+Action input**, not values from a different CLI installation:
+
+```yaml
+stage: provider-selection
+host_visible_skills: []
+indexers:
+  - id: component-guide
+    operations: [main-index]
+    requirement_bindings:
+      - requirement_ref: "<requirement.id>"
+        coverage_domains: ["<required-domain>"]
+        owned_scope:
+          ref: "requirement:<requirement.id>#target_scope"
+        role: primary
+    read_scope:
+      refs:
+        - "requirement:<requirement.id>#target_scope"
+        - "requirement:<requirement.id>#evidence_source_scope"
+    profile:
+      primary:
+        id: component-library
+        provider: community
+    providers:
+      - id: community
+        role: primary
+        skill: "<catalog.skill>"
+        version: "<catalog.version>"
+        integrity: "<catalog.integrity>"
+        distribution:
+          kind: cli-bundled
+          locator: "<catalog.distribution.locator>"
+```
+
+- Choose `component-library` only if it matches the reader task and appears in
+  the selected catalog entry's `capabilities.profiles`. For captured documents,
+  notes or conversation summaries, select a profile from the corresponding
+  compatible Provider. Copy the actual catalog identity.
+- Bind each selected requirement and all required coverage domains it owns;
+  the single-domain template is not permission to drop other required domains.
+  `owned_scope` names the target being described. `read_scope` may also include
+  supporting evidence, which does not become another owned target.
+- `profile.primary.provider`, each additional profile's `provider`, and each
+  composer's `provider` reference a layer's `providers[].id`, not a Skill path.
+  Supporting or extension profiles use `profile.additional` with `kind`;
+  composers use `profile.composers`. Select only combinations supported by the
+  manifests; do not add empty customization or speculative config.
+- The current catalog includes domains, target kinds, profile IDs, operations,
+  composers and extension relationships. If more detail is needed, read the
+  selected entry's exact `guidance.skill_path` and `guidance.manifest_path`.
+  These paths and capabilities are reading aids, not fields to copy into the
+  persistent registry. No separate discovery command or cache scan is needed.
+- JSON Schema describes input shapes and accepted values. The CLI additionally
+  checks coverage ownership, scope relationships and Provider composition when
+  submitting. It atomically applies the selection; do not edit `indexers`
+  manually to bypass a rejected result.
+
+## Initial registry: `src/indexers.yaml`
+
+The initial configuration Route provides the registered source boundary view.
+Read it when the source identities are not already available from the current
+source registration results. It is a metadata view, not another source capture
+or a request to scan the repository. Use only the user's agreed source scope.
+
+Read the `context.indexer.registry-bootstrap` schema at the exact path in the
+current Route's required resources. It ships with the CLI, so it does not
+require a workspace SDK reinstall. It describes this **configuration file**,
+not an Action completion payload. It
+covers the requirements-only state before Provider selection: `indexers` must
+be empty here. Later the Provider selection Route fills that array.
+
+Start with this complete YAML example. Replace the example source reference,
+reader goals and coverage domains with the agreed project requirements:
+
+```yaml
+protocol: context.indexer.registry/v1
+requirements:
+  - id: component-guide
+    purpose: Help application developers integrate components and look up their public API.
+    reader_goals: [understand-components, integrate-components]
+    coverage_domains:
+      component-usage: required
+      public-api: required
+    target_scope:
+      targets:
+        - source_ref: repo:20260901/component-library
+    evidence_source_scope:
+      targets:
+        - source_ref: repo:20260901/component-library
+indexers: []
+```
+
+| Field | What to write |
+| --- | --- |
+| `protocol` | Exactly `context.indexer.registry/v1` for the file. |
+| `requirements` | One or more knowledge goals, grouped by reader need; not one entry per file or symbol. |
+| `id` | A unique, readable identifier for this requirement. |
+| `purpose` | Optional short natural-language reader and task purpose; reuse explicit existing goals when absent. |
+| `reader_goals` | One or more readable goal identifiers, such as `integrate-components`. These are not Provider names. |
+| `coverage_domains` | A nonempty map of intended information categories to `required`, `optional` or `out-of-scope`. Provider selection must cover the required categories. |
+| `target_scope.targets` | Sources whose subjects the knowledge should describe. At least one target is required. |
+| `evidence_source_scope.targets` | Sources the Agent may read to support that knowledge. Include the relevant target sources and any agreed supporting documents. At least one is required. |
+| `source_ref` | The source type plus its complete registered name, such as `repo:20260901/component-library`, `file:20260901/usage-guide` or `lark:20260901/faq`. Saved text uses `note:20260908/topic.md` or `sessions:20260908/topic.md`. Preserve the actual name, not these examples. |
+| `module_refs` | Optional on each target; omit for the complete registered source boundary. Supply only known module references for an explicitly narrower scope. Do not invent a module merely because the source is a code module. |
+| `questions` | Optional structured contract-question bindings, not free-text user questions. Omit unless an actual CLI/profile contract supplies their references, versions and digests. Never invent hashes. |
+| `exclusions` | Optional explicit exclusions with `id`, `scope.targets` and a nonempty `reason`. For repository input, optional `paths` lists exact source-relative files or directories, without globs; omitted means the whole named scope. Agreed paths are filtered before Parser and Partition. A shared Indexer retains material still needed by another requirement. Omit when none were agreed. |
+| `indexers` | `[]` until the next Route selects Providers. Do not copy version or integrity values from an unrelated project. |
+
+Requirement, goal, domain and exclusion identifiers use lowercase letters,
+digits and `._/-`; the first character is a letter or digit, and slash-separated
+segments cannot be empty, `.` or `..`. Requirement ids and goal lists must not
+contain duplicates. Each scope lists a source once; put its selected modules in
+that target's `module_refs` rather than repeating the source.
+
+For document-only knowledge, use the selected captured `file:` or `lark:` source,
+or saved `note:` or `sessions:` source, in both scopes. Saved text must first be
+explicitly selected in the project's `sources`; saving alone is not selection. For a code guide supported by a FAQ, keep the code source in the target
+scope and include both code and FAQ in the evidence scope. If the FAQ also needs
+independent knowledge coverage, include it as a target in the appropriate
+requirement; do not silently treat all captured documents as background.
+Source references identify selected source boundaries, not filesystem paths, URLs,
+image ids, span references or content digests. A repo source already registered
+at a package subdirectory remains bounded to that subdirectory when
+`module_refs` is omitted.
+
+Three existing input shapes have different roles:
+
+- `src/indexers.yaml`: `protocol: context.indexer.registry/v1`, `requirements`,
+  and `indexers`.
+- `IndexRequirementSet`: `protocol: context.indexer.requirement-set/v1` and
+  `requirements` only. This is the SDK's requirement value, not the whole file.
+- Diagnostic `inspect-index-requirements --input`: an envelope with
+  `protocol: context.indexer.requirement-inspection-input/v1`, `project_ref`
+  (the workspace root) and `requirements`; optional `question_contracts` are
+  only for real resolved contract questions. It does not accept the whole
+  registry or a bare requirement set, and is not a mandatory bootstrap step.
+
+After editing the named configuration file, run `context status --format json`
+and follow its new current Route. The next step is Provider selection. Do not
+submit the YAML through `complete-current`, fabricate a lifecycle Result,
+restart the workspace or recapture existing sources.
 
 ## Six-level customization ladder
 
@@ -63,20 +249,33 @@ conforming-looking file.
 
 ## Upgrade and conflict handling
 
-Provider upgrades never silently absorb a local override. Re-resolve the exact
-version and Bundle, then compare the new Provider config, instructions,
-templates, program resources, profile/SubjectKey contracts and the local
-customization fingerprint.
+For a CLI-bundled instruction Provider, resume with the installed Skill and
+portable distribution. A version or content change alone does not require
+Provider selection, registry edits, source capture or a restart. The CLI
+refreshes the current batch's instruction resources and Route revision;
+the Agent follows the returned Route without comparing fingerprints.
+
+Compatible tasks keep their original request/result records. Instruction or
+template edits do not, by themselves, discard accepted groups or authored
+content. Changes to sources, requirements, executable programs, configuration,
+result contracts or semantic extension inputs remain work invalidation reasons;
+old results must not be relabeled as outputs of a different task.
+
+Executable/external Providers continue using their resolved staged programs.
+Updating instruction delivery does not replace executable code or grant new
+execution permissions. Local customization files remain user-owned:
 
 - An unchanged upstream resource keeps the local override current.
-- A changed resource outside the override makes only its dependent units stale.
+- A changed instruction resource outside the override refreshes guidance for
+  pending work, without automatically regenerating completed knowledge.
 - A changed resource under an instruction/template/program override returns
   `indexer-customization-upstream-changed`; rebase or remove the override.
 - Missing, undeclared, escaping or contract-conflicting local resources return
   `indexer-customization-invalid`.
-- An exact Provider version/integrity that cannot be resolved returns
-  `indexer-provider-unavailable`; do not substitute another version or stale
-  cache.
+- A missing CLI-bundled Provider or selected profile/operation/composer returns
+  the existing Provider selection Action, with its schema and next command.
+  Captured sources and completed knowledge are retained. External distributions
+  that cannot be resolved still require the existing resolution/selection flow.
 - Multiple primary owners return a conflict for explicit resolution. Do not
   use discovery order or a preferred Provider name as a tie-breaker.
 
@@ -90,15 +289,17 @@ These outcomes all point back to this guide:
 | Outcome | Required next action |
 | --- | --- |
 | `indexer-provider-required` | Discover visible entry Skills, route a path-free proposal, and keep the requirement set unchanged. |
-| `indexer-provider-unavailable` | Restore the exact distribution or choose a new Provider through the selection Gate. Never use an approximate version. |
+| `provider-unavailable` / `indexer-provider-unavailable` | Follow the current selection/resolution Action to restore the missing capability. A historical bundled content pin alone is not a failure. |
 | `indexer-customization-required` | Follow the six-level ladder using only the returned current gap proof. |
 | `indexer-customization-invalid` | Remove undeclared/escaping/conflicting files, then rebuild and restage the proposal. |
 | `indexer-customization-upstream-changed` | Reconcile the upstream change with every affected override and rerun final validation. |
 
 ## Debugging commands
 
-Use `--help` for the current payload schema and copy Route-returned commands
-when available:
+These are diagnostic/manual primitives, not a checklist for normal selection.
+Use them only for an explicit diagnostic or a returned recovery. `--help`
+describes command options, not necessarily the payload fields. Use the current
+Route's schema and the initial registry contract above; prefer Route-returned commands:
 
 ```bash
 context indexer catalog --format json
@@ -138,3 +339,78 @@ Selection/customization is complete only when all of these are true:
 
 For the complete manifest and execution surface, see
 [Indexer Provider protocol](../reference/indexer-provider-protocol.md).
+
+## Purpose, page selection, and delivery
+
+`purpose` is an optional short description of the intended reader and task.
+Existing `reader_goals` remain valid when it is absent. Context passes this
+requirement through Partition, Author, and Review; it does not classify free
+text against a fixed vocabulary.
+
+After representative reading and necessary scope discussion, substantial new work
+can preserve the decisions in `.tmp/work-start-report.md` before Partition.
+The current workflow supplies `procedure.work-start-report` and
+`template.work-start-report`: a readable report with its existing requirement
+reference, use scenarios, scope choices, proposed classifications, first delivery
+and actual execution settings. Lightweight edits keep a short summary. The report
+is scratch context, not a published Artifact, a new approval or a condition for
+advancing the workflow. On its first presentation, invite the user to read and
+correct it and pause for that response, including in managed mode, unless they
+explicitly waived this reading opportunity. Reuse the response and report when
+continuing the same task; do not add a per-batch pause or report-status field.
+
+Partition may select `artifact_intent` and `template_id` from the current
+Provider catalog, along with `reader_task`, `outline`, `priority`, and
+`delivery_boundary`. These choices are saved in the existing page plan and
+reused by Author retries. Program templates declare `kind: page-program` in the
+Provider's template resources. Only the selected program is included in the
+Author View; procedure templates remain shared instructions. Workspace template
+overrides retain priority over the bundled default.
+
+Selected Code page programs append a deterministic public-contract table to the
+same Candidate as its semantic explanation. Declarations provide field types,
+requiredness, explicit defaults, signatures, and supported registration facts.
+Missing declarations remain explicit; reference tables do not substitute for
+source-backed examples, behavior, or change guidance.
+
+The first readable delivery normally contains one to three pages. Subsequent
+batches contain 30–50 pages, or a smaller final tail. Context retains accepted
+Results across Review, close, and build, then continues the remaining pages.
+`context run --deliver --format json` requests an earlier checkpoint. It keeps
+the current approval rules. Status reports page counts and built preview paths;
+Author task counts are reported separately.
+
+
+## Source-specific Providers and Host switches
+
+The default distribution includes Code, Markdown, Note and Sessions Providers.
+`context-note-indexer` interprets saved records/excerpts/observations;
+`context-sessions-indexer` interprets bounded conversation summaries, with or
+without code associations. Their shared markdown domain reuses document reading
+and profiles; it does not force all sources through Markdown's semantic policy.
+See [note preparation](note.md) and [sessions preparation](sessions.md).
+
+The host owns installation and enabled/disabled switches. Business skills may be
+installed by any supported host channel. Discover relevant currently visible
+`context-…-indexer…` skills and read the real sibling manifest; the prefix alone
+is not compatibility proof. Declare the selected business Provider through the
+existing host_visible_skills and indexers result. It can replace a default without
+enabling that default. CLI validates/resolves what was declared; it does not scan
+host caches or maintain a second business-skill enable registry. Respect explicit
+user exclusions even when the bundled catalog contains the default.
+
+Choose the page owner from reader need. A note may improve an existing guide,
+answer a FAQ or justify a new reference topic. A session without code may justify
+a decision or process guide. Neither saving nor source type requires a new page.
+For a Code/Markdown page retain its primary and include the actual supporting
+source in evidence/read scope. When specialized source interpretation is needed,
+select a Note/Sessions extension layer and the matching namespaced profile
+(`note/component-library` or `sessions/component-library`, for example) with
+`kind: extension`. The manifest declares each supported base. Supporting profiles
+with `kind: supporting` must come from the same primary layer. One primary writes
+the final page; extension guidance does not create another production target.
+
+Optional sessions `changes` records known commit/MR associations in the source
+file. Existing structure.yaml source/section links connect knowledge to it.
+Do not add per-page commit, session or Provider frontmatter. A reference is not
+proof of merging/testing and does not expand source-read authorization.