@c4a/context 0.6.18 → 0.7.0

package/docs/guides/lark-resources.md

@@ -33,6 +33,13 @@ resources remain explicit in the capture report. Unknown non-empty XML blocks
 stay auditable in the raw XML and receive a warning; the CLI does not infer
 their meaning.
 
+Document and resource reads share one access identity. Context first uses the
+user identity; it falls back to the bot identity only when user credentials
+are unavailable, never when the source denies permission or reports missing
+scopes. This prevents a capture from mixing document text read by one identity
+with attachments read by another. A bot fallback is reported in the capture
+result and remains subject to the bot's own access boundary.
+
 ## Storage lifecycle
 
 Resources have three distinct locations:

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/guides/package-outputs.md

@@ -105,8 +105,8 @@ capture reports are never distributed as reader assets. See
 [Lark Resource Materialization](./lark-resources.md).
 
 The same inventory exposes `structure.relationship_coverage`. It records
-whether selected codegraph pages have current source-backed AST relationship
-metadata, how many codegraph views were selected, and how many package-visible
+whether selected codeindex pages have current source-backed AST relationship
+metadata, how many codeindex views were selected, and how many package-visible
 edges were emitted. An empty edge list is therefore explicit evidence of a
 coverage state, not permission to invent a dependency.
 
@@ -130,7 +130,7 @@ Current collection mapping:
 
 | Internal collection | Package path | Role |
 |---|---|---|
-| `codegraph` | `wikis/codegraph/` | Structured code entities and relationships. |
+| `codeindex` | `wikis/codeindex/` | Source-backed code indexes with optional structured relationships. |
 | `business` | `wikis/business/` | Structured business entities and relationships. |
 | `product` | `wikis/product/` | Structured product entities, behavior, and relationships. |
 | `architecture` | `guides/architecture/` | Architecture explanations and design narratives. |

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
@@ -98,7 +98,7 @@ configuration problem, not a Review decision.
 
 If no current capability can parse the source reliably, stop at configuration
 and report the missing generic capability. Do not silently emit an empty
-codegraph or reuse an unrelated parser.
+codeindex or reuse an unrelated parser.
 
 ## Plan Before Parsing
 
@@ -108,7 +108,7 @@ 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`, then read all matching Route-recommended files below
+`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`,
@@ -130,8 +130,9 @@ selected symbol and permits one owning index unit per source. Use it for an
 intentional granular public reference. Use `extractCustom()` for module-level
 aggregation, registries, protocol indexes, cross-module flows, or multiple
 candidate owners over one source; each candidate declares its `module` and
-evidence-scoped `sections`. Each section's typed coverage and exact evidence is
-checked against the output profile during preview. Resolve repositories from
+at least one evidence-scoped `section`; there is no page-level Markdown
+fallback. Each section's typed coverage and exact evidence is checked against
+the output profile during preview. Resolve repositories from
 the extractor context's `sources[].absolutePath`, never from a
 machine-specific checkout path. Cross-module flow output must also emit
 source-backed structured edges. Generated clients/models, mirrored sources, legacy