@c4a/context 0.6.18 → 0.7.0

package/README.md

@@ -58,8 +58,8 @@ const sampleLib = source("20260712", "sample-lib");
 export default defineProject({
   sources: [sampleLib],
   phases: [
-    extractTs({ source: sampleLib, collection: "codegraph" }),
-    reviewValidity({ collection: "codegraph" }),
+    extractTs({ source: sampleLib, collection: "codeindex" }),
+    reviewValidity({ collection: "codeindex" }),
   ],
   packages: [
     kbPackage({
@@ -68,7 +68,7 @@ export default defineProject({
         path: "src/package-templates/kb",
         vars: { displayName: "Sample Library KB" },
       },
-      select: { collections: ["codegraph"], okfRoots: ["wikis"] },
+      select: { collections: ["codeindex"], okfRoots: ["wikis"] },
     }),
   ],
 });
@@ -86,7 +86,7 @@ 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 `codegraph` 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. |
 | `reviewValidity()` | Declares the review gate for one collection or the project. |
@@ -120,7 +120,7 @@ Approved Markdown is organized under `knowledge/<collection>/`:
 
 | Collection | What it contains | Typical sources |
 |---|---|---|
-| `codegraph` | Code symbols, modules, and relationships | Code repositories |
+| `codeindex` | Code symbols, modules, and relationships | Code repositories |
 | `business` | Business concepts, roles, and relationships | Business and Lark documents |
 | `product` | Product capabilities and behavior | Product and requirement documents |
 | `architecture` | System structure and design explanations | Architecture and design documents |

package/README.zh-CN.md

@@ -54,8 +54,8 @@ const sampleLib = source("20260712", "sample-lib");
 export default defineProject({
   sources: [sampleLib],
   phases: [
-    extractTs({ source: sampleLib, collection: "codegraph" }),
-    reviewValidity({ collection: "codegraph" }),
+    extractTs({ source: sampleLib, collection: "codeindex" }),
+    reviewValidity({ collection: "codeindex" }),
   ],
   packages: [
     kbPackage({
@@ -64,7 +64,7 @@ export default defineProject({
         path: "src/package-templates/kb",
         vars: { displayName: "Sample Library KB" },
       },
-      select: { collections: ["codegraph"], okfRoots: ["wikis"] },
+      select: { collections: ["codeindex"], okfRoots: ["wikis"] },
     }),
   ],
 });
@@ -80,7 +80,7 @@ Route 会按需选择维护这份声明所需的操作说明、Schema 和手册
 |---|---|
 | `defineProject()` | 声明完整的项目处理图。 |
 | `source()` 和 `allSources()` | 引用已经登记的代码仓库、本地文件或飞书来源边界。 |
-| `extractTs()` | 从 TypeScript/TSX 中提取符号和关系，生成 `codegraph` 候选。 |
+| `extractTs()` | 从 TypeScript/JavaScript 与 TSX/JSX 中提取符号和关系，生成 `codeindex` 候选。 |
 | `extractCustom()` | 运行项目自有代码提取器，同时由 Context 维护候选、证据、新鲜度和审核状态。 |
 | `alignProse()` 和 `compileProse()` | 整理文档证据，并生成与来源绑定的知识候选。 |
 | `reviewValidity()` | 声明单个知识类型或整个项目的审核门禁。 |
@@ -109,7 +109,7 @@ Context CLI 不会把所有语言和仓库解析器都打入自身。知识项
 
 | 知识类型 | 主要内容 | 常见来源 |
 |---|---|---|
-| `codegraph` | 代码符号、模块和调用关系 | 代码仓库 |
+| `codeindex` | 代码符号、模块和调用关系 | 代码仓库 |
 | `business` | 业务概念、角色和业务关系 | 业务文档、飞书文档 |
 | `product` | 产品能力、功能行为和产品关系 | 产品文档、需求文档 |
 | `architecture` | 系统结构、模块职责和设计说明 | 架构文档、设计文档 |

package/codeIndexPlan.d.ts

@@ -27,6 +27,8 @@ export interface CodeIndexUnitPlan {
     facets?: readonly CodeIndexModuleFacet[];
     /** Source-backed reasons for the selected module type. */
     moduleTypeEvidence?: readonly string[];
+    /** Source-relative Markdown documents read while classifying this index unit. */
+    documents?: readonly string[];
     outputProfile: CodeIndexOutputProfile;
     responsibility: string;
     entries: readonly string[];
@@ -51,9 +53,91 @@ 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;
+    eligibleFiles: number;
+    analyzedFiles: number;
+    /** Complete eligible source identities used as the file denominator. */
+    eligibleFileTargets: readonly string[];
+    /** Complete source identities successfully analyzed by the adapter. */
+    analyzedFileTargets: readonly string[];
+    eligibleLoc: number;
+    analyzedLoc: number;
+    documentsDiscovered: number;
+    documentsRead: number;
+    /** Discovered Markdown identities, relative to the registered source root. */
+    documentTargets?: readonly string[];
+    /** Root README or documentation entry identities that require complete reading. */
+    rootDocumentTargets?: readonly string[];
+    /** Discovered document identities read during module classification. */
+    readDocumentTargets?: readonly string[];
+    /** Documents already referenced by emitted knowledge candidates. */
+    referencedDocumentTargets?: readonly string[];
+    symbolsDiscovered: number;
+    symbolsAnalyzed: number;
+    targetSymbols: number;
+    exportedSymbols: number;
+    /** Stable target identities, normally exported or profile-selected symbol names. */
+    targetSymbolIdentities: readonly string[];
+    /** Public export identities that must remain discoverable. */
+    exportedTargetIdentities: readonly string[];
+    entryTargets: readonly string[];
+    protocolTargets: readonly string[];
+    boundaryTargets?: readonly {
+        kind: "entry" | "export" | "route" | "operation" | "handler" | "downstream" | "command" | "event" | "plugin" | "handoff";
+        identity: string;
+    }[];
+    coveredBoundaryTargets?: readonly {
+        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[];
+    excludedReasons: readonly string[];
+    parserSkippedFiles: number;
+    /** Complete eligible identities that the parser could not analyze. */
+    parserSkippedFileTargets: readonly string[];
+}
 export interface CodeIndexInspectionResult {
     findings: readonly CodeIndexInspectionFinding[];
     capabilityGaps?: readonly CodeIndexCapabilityGap[];
+    inventories?: readonly CodeIndexInspectionInventory[];
 }
 export interface CodeIndexInspectionContext {
     projectRoot: string;

package/contracts.d.ts

@@ -1,6 +1,7 @@
 export type DocumentMainlineCollection = "business" | "product" | "architecture" | "sop" | "faq" | "standards" | "decision" | "incident" | "test";
 export type CodegraphCollection = "codegraph";
-export type MainlineCollection = CodegraphCollection | DocumentMainlineCollection;
+export type CodeIndexCollection = "codeindex" | CodegraphCollection;
+export type MainlineCollection = CodeIndexCollection | DocumentMainlineCollection;
 export type TopLevelNamespace = MainlineCollection | "feats";
 export type OkfRoot = "guides" | "rules" | "wikis" | "feats";
 export type KnowledgeCollection = TopLevelNamespace;

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

@@ -186,8 +186,8 @@ For a monorepo or subspace, choose the boundary deliberately:
 The long-term multi-module knowledge shape is stable across capture dates:
 
 ```text
-knowledge/codegraph/module-a/...
-knowledge/codegraph/module-b/...
+knowledge/codeindex/module-a/...
+knowledge/codeindex/module-b/...
 ```
 
 The CLI records each module's git root and subpath, then materializes
@@ -274,8 +274,8 @@ const componentLib = source("20260712", "component-lib");
 export default defineProject({
   sources: [componentLib],
   phases: [
-    extractTs({ source: componentLib, collection: "codegraph" }),
-    reviewValidity({ collection: "codegraph" }),
+    extractTs({ source: componentLib, collection: "codeindex" }),
+    reviewValidity({ collection: "codeindex" }),
   ],
   packages: [],
 });
@@ -285,8 +285,8 @@ Inspect and run:
 
 ```bash
 context run --list
-context run extract:20260712/component-lib:codegraph --dry-run
-context run extract:20260712/component-lib:codegraph
+context run extract:20260712/component-lib:codeindex --dry-run
+context run extract:20260712/component-lib:codeindex
 ```
 
 When operating through an Agent, use `--dry-run --format json` as the CLI
@@ -298,11 +298,11 @@ Treat that preview as a structural scope check before producing draft
 candidates; the CLI does not decide which symbols are important to a business
 or audience.
 
-The codegraph path keeps the stable module identity. The date stays in the repo
+The codeindex path keeps the stable module identity. The date stays in the repo
 source ref and phase id, not in the knowledge path:
 
 ```text
-knowledge/codegraph/<module>/symbol/<slug>.md
+knowledge/codeindex/<module>/symbol/<slug>.md
 ```
 
 Show the tree/path preview to the user before first extraction and describe it
@@ -423,8 +423,8 @@ const componentLib = source("20260712", "component-lib");
 export default defineProject({
   sources: [componentLib],
   phases: [
-    extractTs({ source: componentLib, collection: "codegraph" }),
-    reviewValidity({ collection: "codegraph" }),
+    extractTs({ source: componentLib, collection: "codeindex" }),
+    reviewValidity({ collection: "codeindex" }),
   ],
   packages: [
     kbPackage({
@@ -433,7 +433,7 @@ export default defineProject({
         path: "src/package-templates/kb",
         vars: { displayName: "Component Library KB" },
       },
-      select: { include: ["codegraph/component-lib/**"] },
+      select: { include: ["codeindex/component-lib/**"] },
     }),
   ],
 });
@@ -446,7 +446,7 @@ of the agent knowledge-base package:
 llmsPackage({
   name: "component-lib-llms",
   template: "src/package-templates/llms",
-  select: { include: ["codegraph/component-lib/**"] },
+  select: { include: ["codeindex/component-lib/**"] },
 });
 ```
 

package/docs/guides/agent-guide.md

@@ -146,7 +146,7 @@ action as adding a knowledge source, not as filling CLI placeholders. Treat this
 as a source boundary decision. Document sources use today's local date as their
 name. Repo sources use the date as a batch and require the confirmed module
 identity. Do not invent semantic date suffixes. The concrete repo selector
-appears in source refs, phase ids, and codegraph paths:
+appears in source refs, phase ids, and codeindex paths:
 
 ```text
 knowledge/<collection>/<slug>.md
@@ -178,6 +178,15 @@ If the user supplies several repo/file/Lark sources in one request, create one
 register them under a single project write lock. Never parallelize mutating
 `source add` commands; on a lock-held error, wait and retry.
 
+Do not select sources from repository layout or Git metadata. After the user
+has named an exact local module or path, however, resolving one unique matching
+directory and reading its Git root, `origin`, and current commit are mechanical
+identity checks. Pass the resolved local path relative to the Context project
+root; when the workspace was initialized in a child `context/` directory,
+recompute sibling paths from that new root. In ordinary and fully managed modes,
+do not request a remote URL again when that confirmed local checkout provides
+it.
+
 Current execution supports repo sources, local Markdown/MDX file sources, and Lark /
 Feishu document sources. Local
 repo/package sources are registered with `context source add repo [YYYYMMDD] --module <module> --local <path>`;
@@ -286,16 +295,16 @@ prose align. Once a document structure draft exists, keep that current human
 gate and do not switch workflows mid-review.
 
 For monorepos, the date is one registration batch and every selected package is
-a module under it. Stable codegraph paths omit that batch date and therefore
-look like `knowledge/codegraph/module-a/...` and
-`knowledge/codegraph/module-b/...`. Date/module remains in phase ids and
+a module under it. Stable codeindex paths omit that batch date and therefore
+look like `knowledge/codeindex/module-a/...` and
+`knowledge/codeindex/module-b/...`. Date/module remains in phase ids and
 repo source refs. Use the whole repo/subspace
 only for inspection when it contains multiple modules. If the user chooses
 `packages/button`, register it with `--module button` under the same date and
 write `extractTs({ source: source("20260712", "button"), ... })`. Do not use
 `include: ["packages/button/src/**"]` to choose a package from a larger source;
 `include` only filters files inside the selected source. Repo module names are
-project-wide codegraph identities; refresh an existing module through its
+project-wide codeindex identities; refresh an existing module through its
 original date/module selector instead of reusing its name under a later date.
 
 For a non-standard package, configure source-relative `entries` on `extractTs`;
@@ -318,17 +327,17 @@ context source inspect <date>/<module> --format json
 context run <extract-phase-id> --dry-run --format json
 ```
 
-After the preview, run codegraph extraction normally unless the user explicitly
+After the preview, run codeindex extraction normally unless the user explicitly
 asked for CI/CD automation. The first normal run requires Review for all code
 candidates. Subsequent normal runs require Review only for added, changed, or
 removed symbols; unchanged approved symbols stay approved. After each result,
-run `context status --format json`. `continue-codegraph-batch` only requests
+run `context status --format json`. `continue-codeindex-batch` only requests
 workspace re-evaluation. Open Review only when
 `workflow.current.gate.id=knowledge-review`; otherwise execute the current
 route.
 
 For a non-interactive pipeline, use `context run <extract-phase-id>
---auto-promote --format json`. This flag applies only to codegraph, applies its
+--auto-promote --format json`. This flag applies only to codeindex, applies its
 deterministic deltas, refreshes deterministic close when needed, runs verify,
 and fails the command if close or verify fails. Read `autoPromotion.close` and
 `autoPromotion.verify` before continuing. Package build remains explicit: when
@@ -354,7 +363,7 @@ tsconfig/jsconfig `baseUrl` and `paths`, so do not ask users to rewrite `@/`
 imports solely for Context. Explain the concrete output shape:
 
 ```text
-knowledge/codegraph/<module>/symbol/<slug>.md
+knowledge/codeindex/<module>/symbol/<slug>.md
 ```
 
 If the module or resulting path shape looks wrong, stop and repair the

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).