@c4a/context-cli 0.6.19 → 0.7.0

package/indexers/bundles/context-code-indexer/templates/component-library.md

@@ -0,0 +1,99 @@
+---
+id: context.code-indexer.template.component-library
+kind: procedure
+media-type: text/markdown
+---
+
+# Component library template
+
+Use for `component-library`: a supported collection of UI components, tokens,
+hooks, primitives, or design-system packages consumed through documented
+imports and component contracts. A web application that happens to contain
+shared components remains a `web-application` unless the component surface is
+published as an independent consumer boundary.
+
+Use the exact profile and Artifact policy variant supplied by the workset.
+
+## Evidence pass
+
+Locate:
+
+- public package exports, component registries, barrels, or documented imports;
+- component props, slots, events, variants, composition, and lifecycle rules;
+- theme, token, styling, accessibility, locale, and provider requirements;
+- maintained examples, stories, visual tests, and consumer integration tests;
+- compatibility, peer dependency, platform, and release constraints;
+- generated declarations, documentation sites, demos, and internal primitives
+  that must not become independent reader pages without a public contract.
+
+Treat stories and examples as usage evidence, not as authority for unsupported
+props or behavior. When generated declarations disagree with source, identify
+the authoritative source and record the gap.
+
+## Questions the knowledge must answer
+
+1. Which component families are public, and how are they imported?
+2. What props, events, variants, slots, and composition rules are supported?
+3. Which providers, themes, tokens, runtimes, or peer packages are required?
+4. What accessibility, state, lifecycle, and failure constraints apply?
+5. Which examples demonstrate supported use and important combinations?
+6. Which implementation primitives or demo-only components are excluded?
+
+## Suggested knowledge units
+
+- **Library map**: purpose, supported entrypoints, providers, component
+  families, compatibility, and navigation.
+- **Component-family guide**: shared concepts, composition, variants,
+  accessibility, and representative source-backed examples.
+- **Granular component reference**: only when consumers search for the exact
+  public component and its contract contains meaningful behavior.
+- **Tokens and theming**: only the stable consumer contract, including scope,
+  defaults, override order, and compatibility.
+- **Migration or compatibility guide**: only when maintained sources describe
+  version transitions or supported platform constraints.
+
+## Chapter blueprints
+
+```markdown
+# <Component library> map
+## Purpose and intended consumers
+## Supported imports and providers
+## Component and token families
+## Composition and state model
+## Accessibility and localization
+## Theming and customization
+## Compatibility and release constraints
+## Examples, evidence, and exclusions
+```
+
+For a component family:
+
+```markdown
+# <Component family>
+## When to use it
+## Supported components and imports
+## Props, events, slots, and variants
+## Composition and state
+## Accessibility and interaction
+## Source-backed examples
+## Related families and evidence
+```
+
+## Granularity and relationships
+
+Prefer component families over one page per export. Use a granular page only
+when the exact public identity has a stable consumer contract beyond a type
+signature. Relate components to providers, tokens, accessibility behavior,
+examples, and compatible peers only when source evidence supports the link.
+
+Do not copy implementation bodies, generated declarations, every story, or
+every styling variant into reader-facing content. Do not use ordinal batches
+to disguise an enumeration-heavy index.
+
+## Revise or stop when
+
+- public components cannot be distinguished from internal or demo-only code;
+- component behavior is inferred only from screenshots or names;
+- examples invent combinations that maintained usage does not support;
+- accessibility or provider requirements are asserted without evidence;
+- one-page-per-component expansion has no consumer-navigation justification.

package/indexers/bundles/context-code-indexer/templates/contract-source.md

@@ -0,0 +1,73 @@
+---
+id: context.code-indexer.template.contract-source
+kind: procedure
+media-type: text/markdown
+---
+
+# Authoritative contract source template
+
+Use for `contract-source`: a module whose maintained value is an authoritative
+IDL, OpenAPI document, schema registry, message contract, or equivalent
+machine-readable interface definition. It defines contracts consumed by other
+modules but does not need to execute or dispatch them itself.
+
+Use the exact profile and Artifact policy variant supplied by the workset.
+Generated projections must point back to this authority and remain supporting
+evidence rather than a second contract authority.
+
+## Evidence pass
+
+Locate:
+
+- schema roots, namespaces/packages, service or message registries, and imports;
+- operation, event, request, response, and error identities;
+- versioning, compatibility, deprecation, and evolution rules;
+- generator configuration, target languages/packages, and generated output
+  boundaries;
+- known provider and consumer registrations when those modules are registered;
+- ownership, validation, publication, and release entrypoints.
+
+## Questions the knowledge must answer
+
+1. Which contracts are authoritative in this module?
+2. How are operations/messages grouped and identified?
+3. What versioning and compatibility rules are declared?
+4. Which generated artifacts and consumers derive from this source?
+5. How is the contract validated, published, and changed?
+
+## Suggested knowledge units
+
+- **Contract registry**: namespaces, service/message families, authority,
+  versions, owners, and navigation.
+- **Operation or message-family reference**: exact identities, payload roles,
+  errors, compatibility, and generated targets.
+- **Generation and publication map**: generator inputs/outputs, validation,
+  versioning, and release boundary.
+- **Provider-consumer flow**: only when both runtime endpoints are registered
+  and source-backed; use the cross-module template.
+
+## Chapter blueprint
+
+```markdown
+# <Contract module> registry
+## Authority, ownership, and schema roots
+## Namespaces and contract families
+## Operations, messages, and error identities
+## Versioning, compatibility, and deprecation
+## Generated targets and active consumers
+## Validation, publication, and release
+## Evidence and exclusions
+```
+
+Use the canonical operation record from `protocol-boundary.md` for detailed
+families. Do not duplicate every generated language binding or claim runtime
+behavior from the schema alone.
+
+## Granularity and stop conditions
+
+Aggregate related operations/messages by authoritative family. Split when
+namespace, owner, version policy, or compatibility behavior differs. Every page
+must contain exact contract identities and source locators, not just filenames.
+
+Revise or stop when authority cannot be distinguished from a generated copy,
+imports or versions are unresolved, or compatibility claims are not declared.

package/indexers/bundles/context-code-indexer/templates/data-sync-reconciliation.md

@@ -0,0 +1,77 @@
+---
+id: context.code-indexer.template.data-sync-reconciliation
+kind: procedure
+media-type: text/markdown
+---
+
+# Data synchronization and reconciliation template
+
+Use for `data-sync-reconciliation` when a stable reader question crosses source,
+transformation, persistence, delivery, or reconciliation boundaries. The flow
+is an independently owned logical unit; each participating module keeps its own
+non-duplicated responsibility map.
+
+## Evidence pass
+
+Establish:
+
+- an explicit start trigger and terminal outcome;
+- each registered module boundary in execution order;
+- operation, event, repository, command, or plugin identities joining adjacent
+  modules;
+- transformations, ownership handoffs, state changes, and failure boundaries;
+- source locators on both sides of every join;
+- authentication, retries, fallback, observability, and recovery only where
+  they are explicitly configured.
+
+Imports, filenames, symbol co-occurrence, and similar names do not prove a
+runtime chain.
+
+## Questions the knowledge must answer
+
+1. What reader goal and source-backed trigger start the flow?
+2. Which module owns each step and boundary?
+3. Which exact contract or identity joins each adjacent step?
+4. What state, identity, or data is transformed at every handoff?
+5. Where can the flow fail, retry, fall back, or terminate?
+
+## Chapter blueprint
+
+```markdown
+# <Cross-module flow>
+## Reader goal and starting trigger
+## Boundary sequence and module ownership
+## Contract and transformation at each handoff
+## State changes and terminal outcome
+## Authentication, failure, retry, and fallback
+## Source-backed edge inventory
+## Known gaps and excluded implementation detail
+```
+
+Examples include application-to-client-to-endpoint, endpoint-to-service-to-
+repository, producer-to-event-to-consumer, command-to-remote-operation, and
+plugin-host-to-provider.
+
+## Partition and ownership rule
+
+A flow normally cites sources already owned by module units. Give the flow one
+stable SubjectKey and keep module inventory ownership unchanged; its author
+workset may reference the exact cross-source evidence views but must not claim
+the same inventory members as a second primary owner.
+
+The aggregate candidate may cite evidence from every participating source. It
+must cover all Route-reported structural probes selected by the flow profile;
+one page may cover several probes when it carries each exact evidence locator.
+Use `operation` and `handoff` candidate sections and emit source-backed
+`depends_on` edges from the owning module candidate to the next registered
+module candidate. Narrative arrows or a textual sequence do not satisfy the
+structured relationship requirement.
+
+## Granularity and stop conditions
+
+Emit one deduplicated page per coherent end-to-end flow family. Split when the
+trigger, terminal outcome, ownership, contract, or failure policy differs.
+
+Revise or stop when either endpoint or a joining identity is missing, the chain
+crosses unregistered sources, relationships depend on inference, or the output
+repeats module pages without adding a handoff model.

package/indexers/bundles/context-code-indexer/templates/derived-generated-source.md

@@ -0,0 +1,117 @@
+---
+id: context.code-indexer.template.derived-generated-source
+kind: procedure
+media-type: text/markdown
+---
+
+# Generated, mirrored, vendored, and legacy source template
+
+Use for `derived-generated-source` and source states `generated`, `mirrored`,
+`vendored`, or `legacy`. Its main purpose is to prevent derived artifacts from
+being mistaken for independent knowledge authority while preserving useful
+consumer and provenance information.
+
+## Evidence pass
+
+Locate:
+
+- generation, sync, vendoring, migration, or deprecation markers;
+- authoritative repository, schema, template, source directory, or upstream
+  package;
+- generator/sync command, configuration, version pin, and output boundary;
+- ownership and update cadence;
+- consumers that still import or execute the derived tree;
+- local modifications, compatibility wrappers, or hand-maintained overlays;
+- release/build artifacts and whether they are committed or reproducible;
+- replacement path for legacy source when one is explicitly maintained.
+
+Do not assume all files in a generated-looking directory are derived. Confirm
+markers, build steps, headers, manifests, or source mapping.
+
+## Questions the knowledge must answer
+
+1. Why does this source exist and what lifecycle category applies?
+2. Where is the authoritative source of truth?
+3. How is the derived content produced, synchronized, or versioned?
+4. Which consumers depend on it and through what supported surface?
+5. Are local edits permitted, overwritten, or layered separately?
+6. What is safe to inspect here, and what knowledge belongs upstream?
+7. For legacy source, what current replacement and migration status are proven?
+
+## Suggested knowledge units
+
+- **Provenance record**: lifecycle, authority, generator/sync, version relation,
+  ownership, output boundary, and consumer summary.
+- **Generated public surface**: only when this tree is the supported consumer
+  interface; combine with `sdk-library` and keep the upstream schema explicit.
+- **Compatibility or migration boundary**: when maintained wrappers or legacy
+  behavior remain operationally relevant and source-backed.
+- **Update/recovery procedure**: only maintained generation or synchronization
+  commands, verification, and overwrite boundaries.
+
+Default to a narrow provenance Artifact unless the workset also selects a
+supported consumer surface. A consumer-facing derived unit must bind its
+authority evidence to the confirmed source locator; a missing authority remains
+a material gap rather than a reason to invent semantics or hide the supported
+consumer surface.
+
+## Chapter blueprints
+
+```markdown
+# <Derived source> provenance
+## Lifecycle classification
+## Authority and ownership
+## Generator, sync, or vendoring mechanism
+## Version and compatibility relationship
+## Output boundary and local-edit policy
+## Active consumers
+## Update, verification, and recovery
+## Reader-facing knowledge owned elsewhere
+```
+
+For a generated public client:
+
+```markdown
+# <Generated client> consumer surface
+## Intended consumers and supported import
+## Authoritative schema and generation version
+## Client initialization and operation families
+## Generated versus maintained behavior
+## Compatibility and regeneration
+## Evidence and excluded generated detail
+```
+
+## Granularity and relationships
+
+Do not duplicate pages already owned by the authoritative schema,
+implementation, or package. Generated files may provide exact locators and
+cross-checks but should not expand every model, constant, serializer, or method
+into reader-facing Markdown.
+
+Relate the derived unit to its authority and active consumers. A relationship
+to an upstream schema must use an explicit locator or generation configuration,
+not a naming guess.
+
+If the authority cannot be located, a narrow provenance unit may still record
+confirmed lifecycle markers, generator clues, output boundaries, and active
+consumers. Keep any separate unit that promises field semantics, compatibility,
+or upstream meaning in a `request-material` disposition tied to a blocking
+material-question proposal until the missing authority is provided.
+
+## Template composition examples
+
+- A generated API client is `sdk-library` + `derived-generated-source` and reads
+  `protocol-boundary.md` for protocol authority.
+- A vendored library with no project-owned surface remains one provenance page,
+  not a copied API reference.
+- A legacy adapter still serving callers combines this template with
+  `adapter-integration.md`; document only proven compatibility and migration behavior.
+
+## Revise or stop when
+
+- the authoritative source cannot be identified for semantic or compatibility
+  claims beyond a narrow provenance record;
+- generated and hand-maintained files cannot be separated;
+- the plan duplicates upstream reference material without consumer value;
+- legacy replacement or deprecation claims are inferred rather than evidenced;
+- generated symbols dominate projected pages.

package/indexers/bundles/context-code-indexer/templates/domain-service.md

@@ -0,0 +1,109 @@
+---
+id: context.code-indexer.template.domain-service
+kind: procedure
+media-type: text/markdown
+---
+
+# Domain service template
+
+Use for `domain-service` modules whose stable value is a domain/use-case boundary or a
+reusable service contract and its first-level orchestration. Do not classify a
+directory as a service merely because it contains classes or functions named
+`Service`.
+
+Use the exact profile and Artifact policy variant supplied by the workset.
+
+## Evidence pass
+
+Locate:
+
+- service construction, registration, dependency injection, or public entry;
+- supported operations and their callers or protocol handlers;
+- use-case/domain orchestration and the point where ownership changes;
+- repositories, transactions, caches, downstream clients, and event ports;
+- invariants, idempotency, consistency, permission, or failure boundaries;
+- configuration and runtime wiring that materially change the service;
+- generated clients/models and internal helpers that should remain evidence.
+
+Follow representative public operations through one orchestration layer. Stop
+at the first stable domain, persistence, or downstream protocol boundary unless
+the confirmed knowledge goal explicitly needs deeper implementation behavior.
+
+## Questions the knowledge must answer
+
+1. What responsibility and invariants does this service own?
+2. Which operations form its supported boundary, and who calls them?
+3. How do operations coordinate domain logic and dependencies?
+4. Where are transaction, consistency, idempotency, or state boundaries?
+5. What failures can cross the boundary, and how are they represented?
+6. Which dependencies are stable contracts versus internal implementation?
+
+## Suggested knowledge units
+
+- **Service boundary**: responsibility, public operations, ownership,
+  invariants, callers, and stable dependencies.
+- **Operation/use-case map**: operation to orchestration to first stable
+  downstream/persistence/event boundary.
+- **State and consistency contract**: only when transaction, idempotency,
+  caching, or durable state is important and evidenced.
+- **Dependency map**: concrete ports/clients/repositories and why each boundary
+  matters; avoid a raw import inventory.
+- **Runtime/configuration guide**: only module-owned configuration, startup,
+  diagnostics, or release behavior.
+
+## Chapter blueprints
+
+```markdown
+# <Domain service> boundary
+## Responsibility and non-responsibilities
+## Supported operations and callers
+## Domain rules and invariants
+## Dependency and port boundaries
+## State, transaction, and idempotency behavior
+## Failure and recovery behavior
+## Configuration and runtime wiring
+## Evidence and excluded implementation detail
+```
+
+For a use-case family:
+
+```markdown
+## <Use-case family>
+- Trigger or caller:
+- Supported operation:
+- Preconditions and invariants:
+- Orchestration steps:
+- Persistence/downstream/event boundary:
+- Result and failure semantics:
+- Source evidence:
+```
+
+## Granularity and relationships
+
+Group operations that share responsibility, invariants, and dependency paths.
+Split only when ownership or consistency semantics differ. Do not publish every
+exported method: language visibility is not proof of a supported service API.
+Every retained page must name supported operations, callers, ports, or state
+identities and include source locators; a folder/class inventory is not a
+service boundary.
+
+Relationships should connect supported operations to real callers, ports,
+repositories, or downstream operations. Do not infer a domain flow from
+similar names or shared models.
+
+## Template composition examples
+
+- An RPC implementation reads `api-service.md` for its inbound registration and
+  this template for domain orchestration.
+- A service backed by durable storage also selects `storage-repository` and reads
+  `persistence-boundary.md`.
+- A service activated only by events also reads `background-runtime.md` and the
+  `event-flow.md` template.
+
+## Revise or stop when
+
+- no stable caller or public service boundary can be found;
+- the proposed content is a class-by-class implementation listing;
+- invariants or data semantics depend on unavailable documentation;
+- generated models are being treated as the domain source of truth;
+- an end-to-end chain crosses undeclared source modules.

package/indexers/bundles/context-code-indexer/templates/event-consumer.md

@@ -0,0 +1,62 @@
+---
+id: context.code-indexer.template.event-consumer
+kind: procedure
+media-type: text/markdown
+---
+
+# Event consumer template
+
+Use for `event-consumer`. This template supplements the owning runtime, service,
+application, or adapter Artifact; an event signal does not by itself justify a
+separate end-to-end Artifact.
+
+## Evidence pass
+
+Locate:
+
+- topic, stream, queue, hook, notification, or event identity;
+- authoritative schema and versioning source;
+- producer call and publication condition;
+- subscription/consumer registration and handler dispatch;
+- delivery, ordering, partitioning, retry, dead-letter, checkpoint, and
+  idempotency configuration;
+- emitted side effects, observability, replay, and recovery entrypoints.
+
+Do not derive delivery guarantees from framework defaults.
+
+## Questions the knowledge must answer
+
+1. What event is emitted or consumed, under what condition, and by whom?
+2. Where is publication or subscription registered?
+3. What delivery and recovery behavior is actually configured?
+4. What state or side effects change, and how can failed work be identified?
+
+## Chapter blueprint
+
+```markdown
+# <Event flow or family>
+## Event identity and authoritative schema
+## Producer and publication condition
+## Delivery and routing semantics
+## Consumer registration and processing
+## Idempotency, retry, checkpoint, and failure destination
+## Side effects and observability
+## Source-backed producer-to-consumer relationship
+```
+
+When only one endpoint is registered, keep an event record inside that
+module's runtime or service map and omit the unavailable endpoint. Create a
+separate event-flow page only when both sides and their shared event identity
+are evidenced, or when one side alone has enough delivery and recovery
+semantics to be a stable operator-facing topic.
+
+## Granularity and stop conditions
+
+Group events with the same schema authority, delivery policy, ownership, and
+handler family. Do not create pages per event field, generated payload type,
+handler helper, or retry branch.
+
+Every retained record must name the event identity, registration or call site,
+and source locator. Revise or stop when delivery semantics would be guessed,
+the shared identity is missing, or the output would contain empty producer or
+consumer sections.

package/indexers/bundles/context-code-indexer/templates/gateway-facade.md

@@ -0,0 +1,89 @@
+---
+id: context.code-indexer.template.gateway-facade
+kind: procedure
+media-type: text/markdown
+---
+
+# Gateway and protocol facade template
+
+Use for `gateway-facade` when the selected reader goal is the boundary exposed
+or translated by one gateway. This template owns the canonical operation
+record. Application, API, service, SDK, contract-source, and adapter templates
+provide context but must not create a second registry for the same operations.
+
+## Evidence pass
+
+Locate:
+
+- the authoritative IDL, OpenAPI document, schema, service definition, or
+  explicit registration;
+- provider operation identity and dispatch when the provider is in scope;
+- consumer client construction and concrete operation call site when the
+  consumer is in scope;
+- request, response, message, identity, and context mapping boundaries;
+- authentication, authorization, timeout, retry, compatibility, and error
+  translation that are explicitly configured;
+- generated bindings, their generator/version, and their upstream authority.
+
+Do not infer protocol semantics from matching type names, generated model
+fields, imports, or transport-library dependencies.
+
+## Questions the knowledge must answer
+
+1. Which concrete operation or coherent operation family is provided or used?
+2. Where is it registered or called, and where is its contract authoritative?
+3. What request, response, identity, credential, and context mapping occurs?
+4. What timeout, retry, compatibility, and failure behavior is source-backed?
+5. Which generated artifacts are locators rather than independent authority?
+
+## Canonical operation record
+
+Use this record wherever another selected template asks for an operation,
+route-to-client, or adapter mapping registry. Add type-specific detail around
+it rather than copying the operation into another table.
+
+```markdown
+## <Protocol operation or family>
+- Provider identity and registration:
+- Consumer call site:
+- Authoritative contract:
+- Request, identity, and context mapping:
+- Response and error mapping:
+- Timeout, retry, and compatibility:
+- Source-backed relationship:
+```
+
+Provider-only records omit the consumer line. Consumer-only records omit
+provider dispatch and remain inside the owning module page unless the opposite
+endpoint is also a registered source and an evidenced cross-module flow is a
+separate reader goal.
+
+## Generated and authoritative contracts
+
+For generated contract material, also select `derived-generated-source` and
+record the upstream schema, generator, version/pin, generated output boundary,
+and runtime consumer. Generated code may locate operations and fields but does
+not become semantic authority by itself.
+
+When the upstream authority is unavailable, a separate provenance Artifact may
+still record the generated boundary, generator markers, current consumers, and
+known authority gap. Keep the question that would explain field semantics or
+compatibility unresolved as a material gap; do not block an independently
+supported provenance record.
+
+For a `contract-source` module, preserve exact operation identities, namespaces,
+versions, compatibility declarations, imports, and generator targets. Do not
+invent runtime dispatch or consumer behavior that the contract does not define.
+
+## Granularity and relationships
+
+Aggregate operations by contract, ownership, and execution family. Split when
+authority, mapping, security, versioning, or failure semantics materially
+differ. Do not create pages for every generated request/response type or field.
+
+Every page must contain concrete operation or schema identities and source
+locators. A page that only says a module “uses an API” is not sufficient.
+
+Revise or stop when operation identity is unavailable, authority is ambiguous,
+security/error behavior would be guessed, or a claimed provider-consumer join
+has no source-backed registration and call evidence.