@c4a/context-cli 0.7.0 → 0.7.1

package/providers/context/resources/semantic/code-index/templates/cross-module-chain.md

@@ -1,78 +0,0 @@
----
-id: semantic.code-index.template.cross-module-chain
-kind: procedure
-media-type: text/markdown
----
-
-# Cross-module flow template
-
-Use for `cross-module-chain` only when a stable reader question cannot be
-answered inside one module. The chain is an independently owned index unit with
-`outputProfile: "cross-module-flow"`; each participating module keeps its own
-non-duplicated 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.
-
-## Extractor and ownership rule
-
-A chain normally overlaps the sources already owned by module units. Use
-`extractCustom()` and assign each aggregate candidate to the chain unit through
-its `module` field. `extractTs()` assigns ownership at source level, so it cannot
-represent both a per-module unit and an overlapping cross-source chain unit in
-the same phase.
-
-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/providers/context/resources/semantic/code-index/templates/derived-source.md

@@ -1,116 +0,0 @@
----
-id: semantic.code-index.template.derived-source
-kind: procedure
-media-type: text/markdown
----
-
-# Generated, mirrored, vendored, and legacy source template
-
-Use for `derived-source` and lifecycle values `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 `outputProfile` to `provenance-only` unless a supported consumer surface
-requires another profile. A consumer-facing derived unit should set
-`sourceOfTruth` to the confirmed authority locator; a missing authority remains
-an advisory risk rather than a reason to 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 as `material-required` until the missing authority is
-provided.
-
-## Template composition examples
-
-- A generated API client is `sdk-library` + `derived-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.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/providers/context/resources/semantic/code-index/templates/domain-service.md

@@ -1,109 +0,0 @@
----
-id: semantic.code-index.template.domain-service
-kind: procedure
-media-type: text/markdown
----
-
-# Domain service template
-
-Use for `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`.
-
-Recommended `outputProfile`: `service-boundary`.
-
-## 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 selects the `persistence` facet 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/providers/context/resources/semantic/code-index/templates/event-flow.md

@@ -1,62 +0,0 @@
----
-id: semantic.code-index.template.event-flow
-kind: procedure
-media-type: text/markdown
----
-
-# Event producer and consumer template
-
-Use for `event-producer` or `event-consumer`. This template supplements the
-owning runtime, service, application, or adapter page; selecting an event facet
-does not by itself justify a separate end-to-end page.
-
-## 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/providers/context/resources/semantic/code-index/templates/monorepo-container.md

@@ -1,124 +0,0 @@
----
-id: semantic.code-index.template.monorepo-container
-kind: procedure
-media-type: text/markdown
----
-
-# Monorepo and module-container template
-
-Use for `monorepo-container`: a workspace whose stable knowledge is the
-registration, ownership, dependency, build, or release topology of multiple
-child modules. Do not treat the physical repository as one application merely
-because it has one Git remote.
-
-Recommended `outputProfile`: `module-registry`.
-
-## Evidence pass
-
-Locate:
-
-- workspace/package/service manifests and child-module discovery rules;
-- build graph, task orchestration, cache, dependency, and affected-scope logic;
-- ownership, tags, boundaries, layering, or dependency constraints;
-- shared configuration and tooling inherited by child modules;
-- release groups, independent packages, deployment units, and version policy;
-- generated, mirrored, vendored, fixture, example, and legacy subtrees;
-- cross-module registries or contracts that warrant separate chain units.
-
-Use declared manifests as the primary inventory. Directory discovery is a
-fallback and must not silently include generated output or dependency caches.
-
-## Questions the knowledge must answer
-
-1. How are child modules discovered and identified?
-2. Which modules are applications, services, libraries, tools, or derived
-   sources, and who owns them?
-3. What dependency and layering rules connect or constrain them?
-4. How do build, test, cache, release, and deployment boundaries work?
-5. Which configuration is inherited globally versus owned by a child module?
-6. Which cross-module flows are important enough to index separately?
-7. Which large or generated subtrees are intentionally excluded?
-
-## Suggested knowledge units
-
-- **Module registry**: child identity, path, type, owner, manifest, supported
-  entry, build/release unit, and lifecycle.
-- **Dependency/topology map**: declared dependency directions, layering rules,
-  shared contracts, and source-backed edges.
-- **Build and release map**: task graph, affected-scope behavior, cache,
-  artifacts, release groups, and deployment units.
-- **Shared tooling/configuration**: only stable workspace-level behavior that
-  materially affects multiple children.
-- **Cross-module chain unit**: independently owned, source-backed flow joining
-  several child modules; do not hide it inside the container summary.
-
-Every user-visible child application, service, library, or CLI is classified as
-its own index unit before deeper extraction.
-
-For `extractTs()`, each child package must first be registered as its own source
-boundary. One root source cannot be assigned to several index units because
-source-level ownership would be ambiguous. If source registration intentionally
-remains at repository level, use `extractCustom()` for the container registry
-and assign aggregate candidates explicitly; do not use `include` to simulate
-package ownership.
-
-## Chapter blueprints
-
-```markdown
-# <Workspace> module registry
-## Workspace purpose and discovery rules
-## Child module inventory
-## Module types, ownership, and lifecycle
-## Dependency and layering constraints
-## Shared configuration and tooling
-## Build, test, cache, and release topology
-## Generated/mirrored boundaries and exclusions
-## Cross-module knowledge entrypoints
-```
-
-One child-module record may use:
-
-```markdown
-## <Module>
-- Path and manifest:
-- Primary/additional types and facets:
-- Responsibility and owner:
-- Stable entrypoints:
-- Direct module dependencies:
-- Build/release unit:
-- Lifecycle/source of truth:
-- Deeper index unit:
-```
-
-## Granularity and relationships
-
-Do not perform a repository-wide symbol scan as the container extraction. The
-container owns topology; child units own reader-facing application/service/API
-knowledge. Aggregate the registry when hundreds of children share the same
-shape, but preserve exact identities and locators.
-
-A workspace manifest, package registry, build graph, or release manifest is a
-valid stable `entries` locator even when the container has no executable
-process. Every registry page must retain exact child identities and locators;
-a directory listing is not a module map.
-
-Use manifest/build-graph evidence for dependency edges. Imports can supplement
-but should not override declared workspace ownership or package boundaries.
-
-## Template composition examples
-
-- A workspace containing a Web app, API gateway, CLI, and generated client
-  produces one registry plus separately classified child units.
-- A workspace with independent release groups selects `build-release`; retain
-  the release map at the container level and package-specific compatibility in
-  each `sdk-library` unit.
-- A cross-module request flow reads `cross-module-chain.md` and receives its
-  own output owner when it spans several child units.
-
-## Revise or stop when
-
-- module discovery relies only on a broad filesystem scan;
-- the plan treats all repository files as one index unit;
-- child ownership or source-of-truth boundaries are ambiguous;
-- generated/cache/vendor directories dominate projected output;
-- dependencies are inferred solely from names without manifest or graph proof.

package/providers/context/resources/semantic/code-index/templates/persistence-boundary.md

@@ -1,56 +0,0 @@
----
-id: semantic.code-index.template.persistence-boundary
-kind: procedure
-media-type: text/markdown
----
-
-# Persistence boundary template
-
-Use for `persistence` when durable state, cache behavior, consistency, or
-recovery is part of the confirmed reader goal. This template supplements the
-service or runtime that owns the operations; it is not a request to catalog
-every model or query.
-
-## Evidence pass
-
-Locate:
-
-- repository/data-access interface and concrete callers;
-- datastore, table, collection, keyspace, entity, or file identity when
-  source-backed;
-- transaction, consistency, cache, lock, idempotency, and concurrency bounds;
-- read/write/query families and domain mapping;
-- schema/migration authority, versioning, and operational recovery;
-- generated models, query helpers, fixtures, and migrations that should remain
-  supporting evidence.
-
-## Questions the knowledge must answer
-
-1. Which service or domain operation owns each read or write family?
-2. What durable or cached state is addressed?
-3. Where are transaction, consistency, locking, and idempotency boundaries?
-4. Which schema or migration source is authoritative?
-5. What failure, migration, or recovery behavior is maintained?
-
-## Chapter blueprint
-
-```markdown
-# <Persistence boundary>
-## Owned state and authoritative schema
-## Repository or data-access entry
-## Callers and operation families
-## Transaction, consistency, cache, and locking behavior
-## Failure, migration, and recovery boundaries
-## Source evidence and excluded query helpers
-```
-
-## Granularity and stop conditions
-
-Group operations by owned state and consistency policy. Split only when schema
-authority, transaction ownership, datastore, or recovery semantics differ.
-Every page must identify real state and caller boundaries with source locators;
-a directory or class inventory is not a persistence model.
-
-Revise or stop when the datastore identity or owning operation is unknown,
-transaction/consistency behavior would be guessed, or generated bindings and
-migrations would dominate reader-facing pages.

package/providers/context/resources/semantic/code-index/templates/plugin-extension.md

@@ -1,52 +0,0 @@
----
-id: semantic.code-index.template.plugin-extension
-kind: procedure
-media-type: text/markdown
----
-
-# Plugin and extension boundary template
-
-Use for `plugin-extension`. This file owns the complete plugin contract
-blueprint. CLI, SDK, and adapter templates should point here and only add their
-module-specific command, public API, or mapping context.
-
-## Evidence pass
-
-Locate:
-
-- discovery mechanism, manifest, registry, or installation contract;
-- activation, deactivation, update, and removal lifecycle;
-- contribution points, commands, hooks, providers, and host services;
-- configuration, identity, compatibility, permissions, and isolation;
-- failure containment, fallback, diagnostics, and version negotiation;
-- public extension API and maintained examples when consumers implement it.
-
-## Questions the knowledge must answer
-
-1. How does the host discover, install, and activate an extension?
-2. What may the extension contribute or call?
-3. Which configuration, identity, permission, and compatibility rules apply?
-4. How are failures isolated, surfaced, and recovered?
-
-## Chapter blueprint
-
-```markdown
-# <Plugin boundary>
-## Host and extension responsibilities
-## Discovery and installation
-## Activation and removal lifecycle
-## Contribution and capability contracts
-## Configuration, permissions, and isolation
-## Compatibility, failure, diagnostics, and recovery
-## Source-backed host-to-extension relationships
-```
-
-## Granularity and stop conditions
-
-Prefer one contract per host/extension model, with compact records for coherent
-contribution families. Do not create separate copies under CLI, adapter, and
-SDK pages. Every page must name concrete manifests, registries, hooks, or
-capability identities and their source locators.
-
-Revise or stop when discovery or activation is inferred, permissions and
-isolation would be guessed, or examples describe an unsupported extension API.

package/providers/context/resources/semantic/code-index/templates/protocol-boundary.md

@@ -1,88 +0,0 @@
----
-id: semantic.code-index.template.protocol-boundary
-kind: procedure
-media-type: text/markdown
----
-
-# Protocol provider and consumer template
-
-Use for `protocol-provider`, `protocol-consumer`, or `generated-contract`. This
-template owns the canonical operation record. Application, API, service, SDK,
-and adapter templates provide module 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`, 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 unit may
-still record the generated boundary, generator markers, current consumers, and
-known authority gap with `outputProfile: "provenance-only"`. Keep the unit that
-would explain field semantics or compatibility as `material-required`; do not
-block the 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.