@c4a/context 0.6.19 → 0.7.0

package/README.md

@@ -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 `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. |
 | `reviewValidity()` | Declares the review gate for one collection or the project. |

package/README.zh-CN.md

@@ -80,7 +80,7 @@ Route 会按需选择维护这份声明所需的操作说明、Schema 和手册
 |---|---|
 | `defineProject()` | 声明完整的项目处理图。 |
 | `source()` 和 `allSources()` | 引用已经登记的代码仓库、本地文件或飞书来源边界。 |
-| `extractTs()` | 从 TypeScript/TSX 中提取符号和关系，生成 `codeindex` 候选。 |
+| `extractTs()` | 从 TypeScript/JavaScript 与 TSX/JSX 中提取符号和关系，生成 `codeindex` 候选。 |
 | `extractCustom()` | 运行项目自有代码提取器，同时由 Context 维护候选、证据、新鲜度和审核状态。 |
 | `alignProse()` 和 `compileProse()` | 整理文档证据，并生成与来源绑定的知识候选。 |
 | `reviewValidity()` | 声明单个知识类型或整个项目的审核门禁。 |

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

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

@@ -0,0 +1,118 @@
+# Markdown Indexer Skill authoring
+
+Markdown Providers use the same `context.indexer.provider/v1` manifest,
+versioning, Bundle, requirement, trust, Result and customization contracts as
+Code Providers. Read the shared
+[Code Indexer author checklist](./code-indexer-skill-authoring.md) and
+[Provider selection/customization guide](./indexer-provider-and-customization.md)
+first. This page defines the Markdown-specific boundary.
+
+## Capture before semantics
+
+Capture owns source authorization, retrieval, revision identity, complete bytes,
+Markdown/MDX parsing and evidence spans. A Markdown Indexer starts only from a
+current captured source report and authorized evidence view. URLs, titles,
+filenames, headings and capture success are activation candidates, not semantic
+classification or proof that the whole document was read.
+
+The Provider cannot fetch the document again, follow new links, rewrite source
+revisions or widen capture scope. Missing/unsupported capture capability is an
+explicit unsupported result, never a prose fallback.
+
+## Activation and source roles
+
+Declare document activation signals and map evidence-backed sources to declared
+roles such as authoritative, explanatory, operational, decision or example
+material. Keep role selection separate from collection placement. One document
+may support multiple reader questions, but every consumed span retains its
+source/revision identity and cannot be promoted to a stronger authority by an
+instruction.
+
+## Section projection and collection mapping
+
+Author Results propose logical Sections and their intent; they do not write
+`knowledge/` paths. Each Section binds:
+
+- the canonical SubjectKey/Node target or an explicit independent target;
+- its reader-question refs and exact evidence spans;
+- an Artifact kind and Section key stable across content-only changes;
+- a projection intent describing purpose, not a physical filename;
+- structured content layers and their digests.
+
+Context owns the closed mapping from profile/Section intent to collection and
+path. The layout resolver reuses an existing Artifact by stable identity,
+detects add/remove/rename/split/merge/move changes and requests a human Gate
+only for destructive or ambiguous existing-layout changes. A Provider cannot
+avoid that Gate by emitting a path or relabeling the change.
+
+## Reusing Code Nodes
+
+Use the supplied subject catalog and TargetResolutionView. Equal SubjectKeys use
+the same NodeRef across Code and Markdown. `resolved` enriches the existing
+Node; `absent` may create an explicitly independent subject or a material gap;
+`ambiguous` fails before authoring. Titles, heading similarity and filenames
+are never identity fallback. Unrelated catalog changes must not make a workset
+stale.
+
+## Artifact and Section planning
+
+One logical unit may produce an Artifact Bundle with multiple meaningful
+Sections or semantic split Artifacts. Do not use fixed-count, ordinal or
+alphabetic batches. Do not create one page per heading/member or inflate page
+count to satisfy a metric. The CLI owns Artifact-policy eligibility, physical
+fan-out audit, layout actualization and the final Candidate compile.
+
+Each Section carries exact positive and negative dependency refs. Incremental
+impact is Section/Artifact-local: a source membership, question denominator,
+candidate pool, evidence span or run-envelope change invalidates only the
+dependent scope. A Provider must not replace this with source-wide or
+collection-wide recomputation.
+
+## Editorial policy
+
+Editorial instructions may guide clarity, consolidation, ordering and
+reader-facing terminology. They cannot alter facts, evidence, source role,
+requirement scope, protected values, revision identity, collection authority or
+hard metrics. Deterministic blocks render only registered facts; semantic prose
+must cite consumed evidence. Placeholders, speculation, fabricated transitions
+and “content unavailable” pages are invalid even when the structure looks rich.
+
+## Material questions and answers
+
+When current material cannot answer a required canonical question, return the
+exact material-question disposition for the supplied owner cell, question
+contract and Subject target. Do not invent a new question contract or landing.
+Context stores the retained `material_gap_ledger`, derives the
+MaterialQuestionWorkset and schedules a separate `material-answer` operation.
+
+A material-answer Result contains only the question revision and source/span/
+content-digest claims allowed by the workset. It does not return reader prose,
+future Artifact/Section identity or self-authored EvidenceItem refs. Context
+canonicalizes evidence, reviews the answer binding, derives the planned answer
+and actualizes it into an approved landing. Stale source, Provider, question,
+binding or landing returns the ledger item to unresolved atomically.
+
+The ledger, answer body, answer provenance and revision scratch pages do not
+enter reader Markdown or `dist`. A blocking gap closes only through current
+evidence or an explicit non-delegable requirement change.
+
+## Markdown author fixture checklist
+
+Release fixtures should cover:
+
+- complete Markdown and MDX capture plus unsupported parser/capture paths;
+- authoritative reference, guide, runbook, FAQ, decision, incident, policy,
+  test and release/migration document shapes using anonymous content;
+- per-Section projection into every supported collection intent;
+- existing Code Node reuse, independent subject, ambiguity and material gap;
+- content-only reuse plus add/remove/rename/split/merge/collection/path/Section
+  move in both directions;
+- protected values, links, images/assets and source-span fidelity;
+- editorial positives and placeholder/speculation/unsupported negatives;
+- material-answer approval, stale/rebind/deletion recovery and no-output-leak;
+- Section-local incremental invalidation, new membership/denominator/candidate
+  pool changes and unaffected Section reuse.
+
+Source authorization, capture revision safety, canonical question/collection
+contracts, layout confirmation, review and build remain Context authority and
+cannot be replaced by the Skill.

package/docs/reference/code-extractors.md

@@ -38,10 +38,10 @@ Current reusable capabilities are:
 
 | Source fact | Preferred capability | Lifecycle integration |
 |---|---|---|
-| TypeScript/TSX package or file scope | `extractTs()` | Context-owned phase |
+| TypeScript/JavaScript package or TSX/JSX file scope | `extractTs()` | Context-owned phase |
 | Go declarations, imports, calls, and common HTTP routes | `@c4a/extract-go` | call from `extractCustom()` |
 | Rush workspace packages, tags, dependencies, entries, and owners | `@c4a/extract-rush` | call from `extractCustom()`; may complement a language extractor |
-| React Router route declarations | `extractReactRouterRoutes()` from `@c4a/extract-ts` | call from `extractCustom()`; complements TypeScript symbols |
+| React Router route declarations | `extractReactRouterRoutes()` from `@c4a/extract-ts` | call from `extractCustom()`; complements ECMAScript symbols |
 | Rust, Python, Java/JVM, or an unsupported framework/protocol | no assumed built-in parser | project-owned `extractCustom()` adapter |
 
 The custom extraction preview verifies this selection mechanically. Context