@c4a/context 0.6.19 → 0.7.1

package/README.md

@@ -86,9 +86,9 @@ maintain this declaration from the user's requirements.
 |---|---|
 | `defineProject()` | Declares the complete project graph. |
 | `source()` and `allSources()` | References registered repo, file, or Lark source boundaries. |
-| `extractTs()` | Extracts TypeScript/TSX symbols and relationships into `codeindex` candidates. |
+| `extractTs()` | Extracts TypeScript/JavaScript and TSX/JSX symbols and relationships into `codeindex` candidates. |
 | `extractCustom()` | Runs a project-owned code extractor while Context owns candidate, evidence, freshness, and Review state. |
-| `alignProse()` and `compileProse()` | Structures document evidence and compiles source-bound knowledge candidates. |
+| `alignProse()` and `compileProse()` | Legacy explicit phase factories retained for existing workspace migration and repair. New workspaces use `src/indexers.yaml` and the Context Indexer lifecycle. |
 | `reviewValidity()` | Declares the review gate for one collection or the project. |
 | `customPhase()` | Adds project-specific orchestration when built-in phase factories are not enough. |
 | `kbPackage()` | Builds an Agent knowledge-base package from approved knowledge and templates. |

package/README.zh-CN.md

@@ -80,9 +80,9 @@ Route 会按需选择维护这份声明所需的操作说明、Schema 和手册
 |---|---|
 | `defineProject()` | 声明完整的项目处理图。 |
 | `source()` 和 `allSources()` | 引用已经登记的代码仓库、本地文件或飞书来源边界。 |
-| `extractTs()` | 从 TypeScript/TSX 中提取符号和关系，生成 `codeindex` 候选。 |
+| `extractTs()` | 从 TypeScript/JavaScript 与 TSX/JSX 中提取符号和关系，生成 `codeindex` 候选。 |
 | `extractCustom()` | 运行项目自有代码提取器，同时由 Context 维护候选、证据、新鲜度和审核状态。 |
-| `alignProse()` 和 `compileProse()` | 整理文档证据，并生成与来源绑定的知识候选。 |
+| `alignProse()` 和 `compileProse()` | 仅为既有工作区迁移和修复保留的显式阶段工厂；新工作区使用 `src/indexers.yaml` 与统一 Indexer 生命周期。 |
 | `reviewValidity()` | 声明单个知识类型或整个项目的审核门禁。 |
 | `customPhase()` | 在内置阶段无法覆盖时增加项目专用编排。 |
 | `kbPackage()` | 使用审核通过的知识和模板构建 Agent 知识库。 |

package/codeIndexPlan.d.ts

@@ -53,6 +53,34 @@ export interface CodeIndexCapabilityGap {
     reason: string;
     requestedMaterial?: string;
 }
+export interface CodeIndexIdentityGroup {
+    id: string;
+    /** Stable target identities represented by one reader-facing capability group. */
+    members: readonly string[];
+    /** Reader-facing page that explains the common responsibility of the members. */
+    viewRef: string;
+    /** Eligible source files that prove the group membership. */
+    sourceFiles: readonly string[];
+}
+export type CodeIndexChainCandidateFamily = "entry-operation" | "operation-handler" | "handler-downstream" | "event-processing" | "command-effect" | "export-implementation" | "cross-source-handoff";
+export interface CodeIndexChainCandidate {
+    id: string;
+    family: CodeIndexChainCandidateFamily;
+    from: string;
+    to: string;
+    sourceFiles: readonly string[];
+    confidence: "structural" | "declared" | "ambiguous";
+}
+export interface CodeIndexChainCandidateDecision {
+    candidateId: string;
+    decision: "document" | "merge" | "exclude" | "request-input";
+    /** Required for document decisions and must identify the reader-facing chain page. */
+    viewRef?: string;
+    /** Required when an equivalent candidate is merged into a canonical chain. */
+    canonicalChainId?: string;
+    /** Required for exclude and request-input decisions. */
+    reason?: string;
+}
 /** Complete source inventory returned by a project adapter for mechanical quality scoring. */
 export interface CodeIndexInspectionInventory {
     indexUnitId: string;
@@ -92,6 +120,12 @@ export interface CodeIndexInspectionInventory {
         kind: "entry" | "export" | "route" | "operation" | "handler" | "downstream" | "command" | "event" | "plugin" | "handoff";
         identity: string;
     }[];
+    /** Source-constrained groups that cover target identities without listing every member in prose. */
+    identityGroups?: readonly CodeIndexIdentityGroup[];
+    /** Static or declared chain candidates discovered during source inspection. */
+    chainCandidates?: readonly CodeIndexChainCandidate[];
+    /** Explicit disposition for every discovered chain candidate. */
+    chainCandidateDecisions?: readonly CodeIndexChainCandidateDecision[];
     excludedFiles: number;
     /** Complete identities deliberately excluded after discovery. */
     excludedFileTargets: readonly string[];

package/docs/README.md

@@ -25,6 +25,9 @@ preload the whole manual set.
 | Understand the whole knowledge-project shape | [Getting Started](./getting-started.md) |
 | Know what the Agent may decide or change | [Agent Guide](./guides/agent-guide.md) and [Agent Dialogue](./guides/agent-dialogue.md) |
 | Configure sources, phases, review, or packages | [Project API](./reference/project-api.md) |
+| Author or inspect an Indexer Provider protocol | [Indexer Provider Protocol](./reference/indexer-provider-protocol.md) |
+| Select or customize an Indexer Provider | [Provider Selection and Customization](./guides/indexer-provider-and-customization.md) |
+| Author a Code or Markdown Indexer Skill | [Code Indexer Authoring](./guides/code-indexer-skill-authoring.md) and [Markdown Indexer Authoring](./guides/markdown-indexer-skill-authoring.md) |
 | Choose a code extraction path | [Code Extractor Selection](./reference/code-extractors.md) |
 | Choose an Agent package or LLM document | [Package Outputs](./guides/package-outputs.md) |
 | Customize package files and indexes | [Package Templates](./reference/package-templates.md) and [Template Variables](./reference/template-variables.md) |
@@ -38,6 +41,10 @@ preload the whole manual set.
 - [Package Outputs](./guides/package-outputs.md) — how to choose between an agent knowledge-base package, LLM text, or no package output.
 - [Lark Resource Materialization](./guides/lark-resources.md) — how embedded resources move from source evidence to approved knowledge and package assets.
 - [Project API](./reference/project-api.md) — `defineProject`, sources, phases, review, and packages.
+- [Indexer Provider Protocol](./reference/indexer-provider-protocol.md) — manifest, controlled execution, detector/inspector I/O, customization, and staged project apply.
+- [Provider Selection and Customization](./guides/indexer-provider-and-customization.md) — registry-only selection, the six-level customization ladder, upgrade conflicts, debugging, and completion conditions.
+- [Code Indexer Authoring](./guides/code-indexer-skill-authoring.md) — the 23-point Provider Skill release contract and anonymous fixture expectations.
+- [Markdown Indexer Authoring](./guides/markdown-indexer-skill-authoring.md) — capture/semantic boundaries, Section placement, material answers, editorial policy, and local incremental behavior.
 - [Code Extractor Selection](./reference/code-extractors.md) — inspect module technology signals and choose a built-in extractor, reusable structural package, or project adapter.
 - [Package Templates](./reference/package-templates.md) — `kbPackage`, `llmsPackage`, template variables, and examples.
 - [Template Variables](./reference/template-variables.md) — Handlebars variables, loops, comments, and default knowledge inventories.

package/docs/README.zh-CN.md

@@ -16,6 +16,8 @@
 | 理解完整知识项目的形态 | [Getting Started](./getting-started.md) |
 | 判断 Agent 可以决定或修改什么 | [Agent Guide](./guides/agent-guide.md) 和 [Agent Dialogue](./guides/agent-dialogue.md) |
 | 配置来源、阶段、审核或产物 | [Project API](./reference/project-api.md) |
+| 选择或定制 Indexer Provider | [Provider Selection and Customization](./guides/indexer-provider-and-customization.md) |
+| 编写 Code/Markdown Indexer Skill | [Code Indexer Authoring](./guides/code-indexer-skill-authoring.md) 和 [Markdown Indexer Authoring](./guides/markdown-indexer-skill-authoring.md) |
 | 选择代码提取方式 | [Code Extractor Selection](./reference/code-extractors.md) |
 | 选择 Agent 知识包或 LLM 文档 | [Package Outputs](./guides/package-outputs.md) |
 | 自定义包文件和索引 | [Package Templates](./reference/package-templates.md) 和 [Template Variables](./reference/template-variables.md) |
@@ -29,6 +31,9 @@
 - [Package Outputs](./guides/package-outputs.md)：如何选择 Agent 知识包、LLM 文本或不构建产物。
 - [Lark Resource Materialization](./guides/lark-resources.md)：内嵌资源如何从来源证据进入正式知识和知识包。
 - [Project API](./reference/project-api.md)：`defineProject`、来源、阶段、审核和知识包声明。
+- [Provider Selection and Customization](./guides/indexer-provider-and-customization.md)：registry-only 选择、六级最小定制阶梯、升级冲突、调试与退出条件。
+- [Code Indexer Authoring](./guides/code-indexer-skill-authoring.md)：Code Provider Skill 的 23 项作者/发布契约。
+- [Markdown Indexer Authoring](./guides/markdown-indexer-skill-authoring.md)：capture/semantic 边界、Section 投影、material answer、编辑策略与局部增量。
 - [Code Extractor Selection](./reference/code-extractors.md)：如何根据技术信号选择内建提取器、结构库或项目适配器。
 - [Package Templates](./reference/package-templates.md)：`kbPackage`、`llmsPackage`、模板变量和示例。
 - [Template Variables](./reference/template-variables.md)：Handlebars 变量、循环、注释和默认知识清单。

package/docs/getting-started.md

@@ -81,12 +81,14 @@ processor, confirm the source boundary and add the processor before capture.
 If the selected page is only a runtime shell, capture the rendered-site source
 or project-specific data source explicitly; do not ask the agent to invent
 missing body text. The concrete command shape is available from
-`context source add file --help`; after registration, declare `captureFile`,
-`alignProse`, `compileProse`, and `reviewValidity`.
+`context source add file --help`; after registration, declare `captureFile`
+and `reviewValidity`, then let the Context Indexer lifecycle create the
+confirmed requirements and exact Provider registry in `src/indexers.yaml`.
 
 For a Lark / Feishu document, register a Lark source with exactly one identity
-form, then declare `captureLark`, `alignProse`, `compileProse`, and
-`reviewValidity`.
+form, then declare `captureLark` and `reviewValidity`. Do not add
+`alignProse`/`compileProse` to a new workspace; those factories remain only for
+explicit migration and repair of older declarations.
 
 File and Lark sources use the same date-batch shape as repo sources. Multiple
 documents belong under one date instead of receiving `-2` / `-A` suffixes:
@@ -140,17 +142,17 @@ of returning an unexecutable command. Read every
 semantic rules remain available as files and are loaded only for the route that
 needs them.
 
-After capture, status selects `route.document.classification-required` for
-document modules without an align declaration. Run the Gate's returned
-collection-neutral inspection commands first; only then propose a mainline
-collection and ask for confirmation. Batch read permission does not choose a
-collection.
+After capture, status selects `route.indexer.lifecycle-required`. Follow its
+`run-indexer-lifecycle` resource and the exact `context indexer ...` outcomes:
+confirm the complete requirement set, discover and resolve an exact Markdown
+Provider, execute its evidence-bound worksets, reconcile/layout/audit the
+Result, and compile the current Candidate batch. Batch read permission does
+not choose requirements, a Provider, or a collection.
 
 When the workspace also contains repo sources, Context prioritizes untouched
-code after all document captures finish: the current reason is
-`route.extract.pending-target` until the code extraction round is current,
-then routing returns to document investigation. An existing document
-structure/compile gate is never interrupted.
+code and document owner cells through that same Indexer Route. It does not
+switch to a second extraction or prose lifecycle and does not interrupt an
+accepted workset that is already durably recorded.
 
 For a single component package, use the package directory as the repo source
 boundary:
@@ -221,15 +223,14 @@ current Route rather than duplicating them in the project Skill.
 
 ### Document Source Flow
 
-For source documents, keep the project declaration small and let the CLI guide
-the evidence views, structure confirmation, deterministic compile projection,
-review, and close steps:
+For source documents, keep the project declaration small. `src/index.ts`
+declares the trusted source/capture/review/package surface; the confirmed
+requirements and exact Provider selection live separately in
+`src/indexers.yaml`:
 
 ```ts
 import {
-  alignProse,
   captureFile,
-  compileProse,
   defineProject,
   reviewValidity,
   source,
@@ -241,9 +242,7 @@ export default defineProject({
   sources: [docs],
   phases: [
     captureFile({ source: docs }),
-    alignProse({ source: docs, collection: "architecture" }),
-    compileProse({ source: docs, collection: "architecture" }),
-    reviewValidity({ collection: "architecture" }),
+    reviewValidity({ scope: "all" }),
   ],
   packages: [],
 });
@@ -254,11 +253,18 @@ Then return to the installed Context Agent entry. For maintainer inspection,
 sequence is:
 
 1. capture the source into committed snapshots;
-2. investigate evidence and confirm the CLI-managed lifecycle structure;
-3. compile every source-bound View from confirmed structure;
-4. review/apply the complete candidate batch once;
+2. confirm requirements and resolve exact Code/Markdown Providers through the
+   sole Indexer Route;
+3. execute and reconcile evidence-bound worksets, then derive layout and audit
+   the Result;
+4. compile and review/apply the complete Indexer Candidate batch once;
 5. run close once, then verify and build when packages are declared.
 
+See [Indexer Provider selection and customization](./guides/indexer-provider-and-customization.md)
+for the registry and Provider flow. Existing workspaces that still declare
+`alignProse`/`compileProse` may use their explicit diagnostic commands during
+migration, but Context does not select them as the default workflow.
+
 Do not read `sources/` or raw Markdown directly after entering the Context
 workflow; use the evidence views and `source_ref` values returned by the CLI.
 

package/docs/guides/agent-guide.md

@@ -122,12 +122,11 @@ Present only the current workflow surface:
 |---|---|
 | Register a knowledge boundary | `context source add file/lark/repo ...`, followed by the matching project phase declaration. Source registration is a user-confirmed boundary decision. |
 | Capture document sources | Run the declared `capture:file:<date>/<module>` or `capture:lark:<date>/<module>` phase only after read permission. Capture writes a sibling document file under the matching date directory, updates that directory's single `manifest.json`, and mechanically materializes supported Lark resources. Do not download or rewrite embedded resources outside the CLI. |
-| Investigate captured material | Use `context status` and the returned `context run align:<type>:<source>:<collection> --view ...` commands. Evidence views drive reading; raw directory grep is not the workflow. |
-| Confirm prose structure | `alignProse` validates and stages CLI-managed lifecycle structure. Validation does not equal user confirmation; only confirmed lifecycle state may enter prose compile. |
-| Compile source-bound drafts | `compileProse` turns confirmed structure into source-bound draft pages. It does not approve knowledge. |
-| Review and apply | Use `context review html` and `context review apply`. Approved prose pages are source-mirrored; rewrite/compression problems should return to structure/compile repair before apply. |
+| Investigate captured material | Follow `route.indexer.lifecycle-required` and its `run-indexer-lifecycle` resource. Use only the evidence views and `context indexer ...` commands returned by the current subroute; raw directory grep is not the workflow. |
+| Index documents and code | Confirm requirements, resolve exact Providers, execute/recover worksets, reconcile Results, derive layout, audit, and compile the current Indexer Candidate batch. There is no separate default extraction, classification, align, or structure-confirmation route. |
+| Review and apply | Use `context review html` and `context review apply`. Approved pages retain their exact Indexer Result/evidence binding; quality problems return to the affected Indexer revision before apply. |
 | Close, verify, build | Run `context close`, `context verify`, then `context build`. Close derives `knowledge/structure.yaml`, approved edge projection, and the final verify gate. |
-| Code extraction | Use `context source inspect <source-name>` and the declared extract phase preview before code draft writes. |
+| Code evidence | The Code Indexer uses registered parser capabilities and evidence adapters through the same Indexer Route. Legacy explicit extract phases are migration/repair entrypoints, not the default workflow. |
 | Source retraction | Follow the current status or lifecycle command if one exists. Do not delete `sources/`, `knowledge/`, `dist/`, or `.tmp` to simulate lifecycle actions. |
 
 Judgment behavior is part of evidence views, source span resolvers, repair
@@ -197,9 +196,10 @@ workspace-relative repo root plus `subpath`; do not rewrite it back to an
 absolute machine path. Local Markdown/MDX sources
 are registered with `context source add file [YYYYMMDD] --module <module> --local <path>` plus any
 needed `--include` patterns, captured with `captureFile`, then planned through
-`alignProse` and compiled with
-`compileProse`. A one-file-to-one-page outcome is a degenerate structure plan,
-not a separate content path. Remote Git operations require explicit user approval before any
+the confirmed requirement set and exact Markdown Indexer registry in
+`src/indexers.yaml`. Artifact and Section layout is derived from the validated
+Provider Result; it does not require a default align/structure-confirmation
+round. Remote Git operations require explicit user approval before any
 clone/checkout; clone into an ignored local path, checkout the requested commit,
 then register that local checkout. Do not commit cloned source content. Lark /
 Feishu sources are registered as document modules under a shared date batch,
@@ -238,47 +238,37 @@ revision-bound Context command and read the returned file. Long procedures and
 semantic rules live in these resources; they are loaded progressively, not
 discarded or shortened into the status response.
 
-Status also returns `declarationGraph` and `configurationGaps`. These expose
-capture, align, compile, and Review coverage for each canonical document source
-and declared align collection. Missing declarations are early warnings while
-structure is still being planned; after confirmation, every collection planned
-by the structure must have an exact compile route for the same source. Do not
-run a compile command from another collection as a fallback. A
-`reviewValidity({ scope: "all" })` declaration covers every collection.
-
-When `workflow.current.reason_code` is
-`route.document.classification-required`, execute its read-only
-`inspection_action` commands before adding align/compile declarations. Inspect
-every unclassified target, explain the evidence behind the proposed mainline
-collection, and wait for user confirmation. Filenames, URLs, source titles,
-and collection names are hints, not sufficient classification evidence.
-
-Also inspect `pendingStructureTargets`. A non-empty list means captured document
-work remains outside the active structure snapshots, even if the current package
-is already built. Follow `needs-prose-configuration` first when declarations are
-missing, then run the exact returned align command. Continue in the same
-workspace; do not replace a valid earlier structure round or create a second
-workspace merely to add the next document. Missing declarations are selected
-by `route.prose.configuration-required`; do not branch on an old top-level
-`needs-prose-configuration` state.
-
-Use `structureBatch` for the complete multi-source slot overview. Evidence View
-commands are workspace-read-only and parallel-safe; structure stage/confirm,
-compile stage, Review apply, and close mutate workspace state and must run
-serially.
-
-The confirmation and Review scopes are different: confirm each canonical source
-plus collection structure slot independently, but do not open Review while
-another declared slot remains pending in the same round. Compile every View from
-all slots first, open one collection-level Review, and let deterministic close
-merge the active slots into `knowledge/structure.yaml`.
+Status also returns `declarationGraph` and `configurationGaps`. For new
+workspaces, use them to diagnose source/capture/review/package declarations;
+requirements, owner cells, Provider selection, worksets, audit, and Candidate
+progress come from the Indexer lifecycle. `reviewValidity({ scope: "all" })`
+covers the unified Candidate batch.
+
+When `workflow.current.reason_code` is `route.indexer.lifecycle-required`, read
+the selected lifecycle resource and follow the first structured Indexer
+outcome. Do not invent a collection from filenames, URLs, source titles, or old
+align declarations. The confirmed requirement set and exact Provider registry
+are the durable authority.
+
+Indexer evidence reads may be parallel when the current worksets and Host permit
+it. Ledger transitions, Candidate compile, Review apply, and close mutate
+workspace state and must follow their exact CAS-bound commands. Do not open
+Review until every required owner cell has an accepted current Result and the
+batch audit is ready.
 
 Do not infer permission from the presence of a command. When
 `workflow.current.commands` is empty, do not derive a lifecycle command from
 prose; complete the returned `configuration` action or resolve the returned
 gate, then rerun status.
 
-Extraction scope is also a human gate. If no extract phase is declared, explain
+## Legacy Explicit Code Extraction Commands
+
+The following `extractTs`/`extractCustom` route applies only when maintaining an
+existing project that still declares an explicit extraction phase. New
+workspaces express code ownership and scope as Indexer requirements and use the
+Code Indexer through `route.indexer.lifecycle-required`.
+
+For an existing explicit phase, extraction scope is a human gate. If no extract phase is declared, explain
 what code area and symbol policy will become draft knowledge, then ask which
 registered source and file/symbol range to ingest. Do not inspect the source
 repository to choose packages or globs on the user's behalf. The
@@ -390,10 +380,15 @@ count packages, parse `package.json`, or sample the lifecycle candidate ledger.
   These commands still enforce the scoped candidate-id gate.
 - Do not edit approved Markdown by hand as part of review apply.
 
-## Prose Align And Compile Rules
+## Legacy Prose Migration And Repair Commands
+
+`alignProse` and `compileProse` remain callable for existing workspace
+migration, explicit diagnostics, and repair. They are not selected by the
+default Graph and must not be added to a new project as an alternate indexing
+workflow. Use the commands below only when the current CLI explicitly returns
+one of these legacy phase ids.
 
-After document capture, do not ask the user to choose an SDK path. Explain the
-product sequence:
+For such an existing declaration, the compatibility sequence is:
 
 1. investigate material through Context evidence views;
 2. propose a structure draft with nodes, section plans, supported edges, and

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

@@ -0,0 +1,124 @@
+# Code Indexer Skill authoring
+
+This guide defines the release checklist for a Code Indexer Provider Skill.
+It does not reproduce Context's internal Agent Graph lifecycle. The Provider
+receives validated requirements, scopes, worksets and evidence views and
+returns only its declared structured Results/fragments.
+
+## Minimal package
+
+Use one `context-indexer.yaml` with protocol
+`context.indexer.provider/v1`. Give the Skill a SemVer version and publish the
+complete Bundle with a reproducible integrity digest. Instructions, templates,
+fixtures and portable program entries live below the Skill root. Do not invent
+source-specific manifest names or a second schema tree.
+
+Programs use a structured `runtime: node`, portable `entry` and literal `args`.
+They never use a free-form command. A detector only reports activation signals;
+an inspector only returns bounded evidence/enrichment. Neither is a hard-gate
+authority. CLI profile contracts and verified data-only overlays own mechanical
+rules, metric operators and thresholds.
+
+## Author contract checklist
+
+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.
+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.
+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;
+   select only CLI-registered Artifact kinds/policy variants. Keep logical unit
+   identity separate from physical Artifact count.
+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.
+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.
+10. **Inspector safety.** Accept only the versioned stdin request and bounded
+    authorized evidence view; emit strict JSON within limits. Never read the
+    repository, environment or network implicitly, and never expose raw
+    config values, secrets or unbounded stderr/stdout.
+11. **Base gates.** Do not reduce source scope integrity, identity, evidence,
+    requirement, disposition, reference-only or provenance gates. Provider
+    integrity identifies content; it does not grant pass authority.
+12. **Anonymous fixtures.** Cover at least a component library, Web app, API
+    service, SDK/library and runtime/worker with neutral paths and identifiers.
+13. **Release tests.** Validate the manifest/resource ledger, run positive and
+    negative fixtures, forward-test the complete Skill, pack it, reinstall the
+    exact artifact and compare Bundle bytes/digest.
+14. **Content ownership.** Public technology belongs in the community Skill;
+    company-wide infrastructure belongs in a separate namespaced Provider;
+    repository, service, team and business mappings belong in business/project
+    Providers. Community fixtures remain anonymous.
+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.
+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.
+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.
+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.
+20. **Requirement direction.** `IndexRequirementSet` constrains registry,
+    extractor and Result in one direction. Apply requirement/registry changes
+    through staged, digest-bound proposals and transactional apply; do not edit
+    a live registry around the Route.
+21. **Program and remote authority.** Programs must pass static policy and the
+    applicable trusted/sandbox authorization. Optional remote tools use a
+    versioned Host Action, exact source-bound request and readable receipt;
+    they never expand scope or perform writes.
+22. **End-to-end recovery.** Test discovery, exact Provider resolution,
+    content-addressed staging, controlled execution, Artifact/Evidence Result
+    validation and crash recovery. A resumed run reuses only complete accepted
+    records and never infers success from a partial receipt.
+23. **Customization ladder.** Preserve this order: Provider only → config →
+    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).
+
+## Result and composition rules
+
+Exactly one primary layer returns a complete partition/author Result for an
+operation. Pre-author extensions return only declared fragments and cannot
+change ownership, denominator or Subject identity. Post-author composers bind
+one current `PrimaryResultView` and return only a derived proposal fragment;
+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
+enricher uses the supplied TargetResolutionView (`resolved`, `absent` or
+`ambiguous`) and never guesses identity from a title or path resemblance.
+
+## Publication gate
+
+Do not publish until the exact packed artifact passes manifest/schema
+validation, anonymous positive/negative fixtures, no-scope-expansion and
+secret-leak tests, deterministic Bundle reconstruction, exact-version install,
+controlled execution and forward tests. Publishing a new version does not make
+existing workspace pins current; workspace selection must re-resolve it.

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

@@ -0,0 +1,140 @@
+# Indexer Provider selection and customization
+
+This guide is for workspace users and Agents selecting Code or Markdown
+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.
+
+Context is registry-only by default. The durable selection lives in
+`src/indexers.yaml`; `package.json`, discovered Skill paths, Host cache paths,
+resolved transport paths and runtime staging directories are not selection
+authority. A Provider-only project does not create `src/indexer/`.
+
+## Selection flow
+
+1. Inspect and confirm the complete `IndexRequirementSet`. 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.
+
+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.
+
+## Six-level customization ladder
+
+Use the first level that closes the CLI-proven capability gap. Do not start at
+a more powerful level because it is convenient.
+
+| Level | Change | Entry evidence | Exit condition |
+| --- | --- | --- | --- |
+| 1. Provider only | Select an existing exact Provider/profile | The confirmed requirements are fully owned by declared capabilities | Final selection validation passes and no project customization files exist |
+| 2. Config | Select declared variants, resources or data-only options | The manifest exposes a closed config schema that covers the difference | Config validates; no instruction, template or program change is needed |
+| 3. Instructions append | Add bounded project guidance | The gap is semantic guidance and does not change contracts, scope, identity, denominators or hard rules | Appended resource closes the gap and the origin/version fingerprint is retained |
+| 4. Template override | Replace one declared template for one profile | The Artifact policy is already valid; only reader organization/rendering differs | One exact template id/profile is overridden; unrelated templates remain Provider-owned |
+| 5. Program extension | Add a fixed local program under the declared indexer root | A structured algorithm is required and smaller levels are proven insufficient | Static policy passes and independent program/dependency authorization is complete |
+| 6. Restricted replace | Replace only the capability named by the final gap proof | Extension cannot satisfy the exact owner cells and a human accepts the larger maintenance boundary | Replacement remains requirement-compatible, content-addressed and explicitly reviewable |
+
+Levels 3–6 are allowed only after the Route returns
+`indexer-customization-required` with a current `capability_gap_proof`. Copy the
+proof into the draft unchanged. A draft cannot weaken requirements, widen
+source scope, copy a parser, add an evaluator, or claim that it has been
+applied. If no safe level closes the gap, stop instead of emitting a
+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.
+
+- An unchanged upstream resource keeps the local override current.
+- A changed resource outside the override makes only its dependent units stale.
+- 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.
+- Multiple primary owners return a conflict for explicit resolution. Do not
+  use discovery order or a preferred Provider name as a tie-breaker.
+
+The optional `@context-indexer-origin <skill>@<version>` comment records where
+a local customization began. It grants no trust and never bypasses revalidation.
+
+## Outcome handling
+
+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. |
+| `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:
+
+```bash
+context indexer catalog --format json
+context indexer inspect-index-requirements --help
+context indexer compare-index-requirements --help
+context indexer route-indexer-provider-selection --help
+context indexer validate-indexer-selection-proposal --help
+context indexer resolve-indexer-providers --help
+context indexer stage-indexer-provider-bundle --help
+context indexer validate-indexer-customization --help
+context indexer prepare-indexer-customization-project --help
+context indexer stage-indexer-project-proposal --help
+context indexer apply-indexer-project --help
+context indexer observe-indexer-project --help
+```
+
+Keep full runtime reports under `.tmp/context-runtime/`. Do not persist Bundle
+bytes, resolution receipts, selection discovery, run ledgers or audit reports
+in `src/`, `knowledge/` or `dist/`.
+
+## Completion check
+
+Selection/customization is complete only when all of these are true:
+
+- the confirmed requirement digest is unchanged;
+- every required owner cell has exactly one primary owner;
+- every Provider is exact-versioned, integrity-checked and staged from a
+  portable distribution;
+- profile variants, SubjectKey authority, config and resources pass final
+  validation;
+- each local change is the smallest proven ladder level and has no unrelated
+  copied resources;
+- program and dependency receipts exist when required and do not claim a
+  sandbox the Host does not provide;
+- the transactional apply observation matches every target digest;
+- a final static/final selection validation passes after apply.
+
+For the complete manifest and execution surface, see
+[Indexer Provider protocol](../reference/indexer-provider-protocol.md).