@c4a/context 0.6.19 → 0.7.1

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
@@ -102,28 +102,13 @@ codeindex or reuse an unrelated parser.
 
 ## Plan Before Parsing
 
-Classify the user-visible module before selecting language tooling or reading an
-archetype template: API/service, background runtime, SDK/library, interactive
-application, adapter, CLI/tool, monorepo container, derived source,
-authoritative contract source, or unknown.
-A hybrid module may declare several `moduleTypes` and several behavior `facets`;
-keep one primary `moduleType` for concise reports. Record inspected paths in
-`moduleTypeEvidence`, record every Markdown file actually read in `documents`, then read all matching Route-recommended files below
-`resources/semantic/code-index/templates/` and combine them into one plan.
-After that, choose exactly one closed output profile: `module-map`,
-`application-map`, `protocol-index`, `service-boundary`, `runtime-map`,
-`public-api-reference`, `command-map`, `adapter-contract`, `module-registry`,
-`cross-module-flow`, or `provenance-only`. The profile selects structural probes
-and advisory checks; an invented value is rejected.
-
-Each archetype resource is a working template for an Agent with limited prior
-context. It provides a minimum evidence pass, the reader questions the index
-must answer, suggested knowledge units, Markdown chapter blueprints,
-aggregation and relationship rules, composition examples, and stop conditions.
-The blueprints are illustrative: omit unsupported sections and merge overlap
-across selected templates instead of producing empty headings or duplicate
-pages. They shape content before the batch preview; they do not prescribe or
-override projected page counts.
+The root workflow no longer owns module taxonomy or archetype templates. The
+Indexer registry selects the applicable Provider profile, and the resolved
+Provider Bundle supplies the semantic plan, evidence questions, composition
+rules, and output guidance. Context only validates the closed selection,
+digests, inventories, and resulting Candidate contracts. Do not reconstruct a
+parallel profile taxonomy in this reference or route around the Indexer
+lifecycle with an extractor-specific plan.
 
 Extractor shape defines what can be emitted. `extractTs()` creates one page per
 selected symbol and permits one owning index unit per source. Use it for an