@c4a/context-cli 0.6.13 → 0.6.17

package/providers/context/resources/semantic/code-index/templates/domain-service.md

@@ -0,0 +1,109 @@
+---
+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

@@ -0,0 +1,62 @@
+---
+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

@@ -0,0 +1,124 @@
+---
+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

@@ -0,0 +1,56 @@
+---
+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

@@ -0,0 +1,52 @@
+---
+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

@@ -0,0 +1,88 @@
+---
+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.

package/providers/context/resources/semantic/code-index/templates/sdk-library.md

@@ -0,0 +1,132 @@
+---
+id: semantic.code-index.template.sdk-library
+kind: procedure
+media-type: text/markdown
+---
+
+# SDK and shared library template
+
+Use for `sdk-library`: reusable code packages, component libraries, client
+SDKs, public framework extensions, or shared runtimes consumed through a
+deliberately supported interface. A package being imported elsewhere is not
+enough; confirm its supported entry and consumer contract.
+
+Recommended `outputProfile`: `public-api-reference`.
+
+## Evidence pass
+
+Locate:
+
+- package manifest, exports map, public barrels, binary/native entry, or
+  documented import paths;
+- initialization, providers, factories, configuration, and required runtime;
+- public capability families, components, hooks, types, commands, or clients;
+- supported extension/plugin points and lifecycle;
+- compatibility, platform, peer dependency, and version constraints;
+- maintained examples, tests, API comments, and migration/release notes;
+- external protocol schemas and generated declarations or clients;
+- internal implementation, fixtures, demos, and re-export chains that should
+  not become independent reader pages.
+
+Use public exports plus maintained documentation together. An exported symbol
+can still be incidental; a documented stable import path can remain public even
+when it re-exports another implementation.
+
+## Questions the knowledge must answer
+
+1. Who should use this package and what capabilities does it promise?
+2. What are the supported import/initialization paths?
+3. How are public APIs grouped into concepts a consumer can navigate?
+4. What configuration, lifecycle, compatibility, and failure rules apply?
+5. Which examples demonstrate supported use rather than test-only behavior?
+6. Which declarations are generated, and where is their authority?
+7. How is the package built, versioned, and released when that is in scope?
+
+## Suggested knowledge units
+
+- **Library/module map**: purpose, supported entrypoints, capability families,
+  runtime/peer requirements, extension points, and navigation.
+- **Getting started or lifecycle**: installation assumptions, initialization,
+  configuration, teardown, and minimal supported examples evidenced by source.
+- **Capability-family reference**: a coherent group of APIs/components with
+  usage, contracts, constraints, and related types.
+- **Granular API/component reference**: one symbol or component per page only
+  when the package intentionally exposes a granular public contract and the
+  measured preview remains appropriate.
+- **Compatibility and migration**: supported platforms/versions and evidenced
+  breaking or transitional behavior.
+- **Build/release entry**: only module-owned packaging and release behavior.
+
+## Chapter blueprints
+
+```markdown
+# <Library> module map
+## Purpose and intended consumers
+## Supported entrypoints and initialization
+## Capability families
+## Runtime, peer, and platform requirements
+## Configuration and lifecycle
+## Extension points and external protocols
+## Compatibility, build, and release
+## Examples, evidence, and exclusions
+```
+
+For a capability family:
+
+```markdown
+# <Capability family>
+## When to use it
+## Supported imports or components
+## Initialization and configuration
+## API/component contracts
+## Lifecycle, errors, and constraints
+## Minimal source-backed examples
+## Related capabilities and authoritative references
+```
+
+For a granular reference page:
+
+```markdown
+# <Public API or component>
+## Purpose
+## Import and signature/props
+## Required context and configuration
+## Behavior, lifecycle, and errors
+## Supported example
+## Compatibility and source evidence
+```
+
+## Granularity and relationships
+
+Prefer capability families over one page per export. A symbol page is justified
+when consumers search for that exact public identity and its contract contains
+meaningful behavior beyond a signature. Do not copy complete function bodies,
+private members, generated declarations, fixtures, or every re-export.
+
+The 300-page limit remains per index unit. When a granular public surface would
+cross it, keep the public identities navigable but aggregate them into
+capability-family pages through `extractCustom()`; the limit is not raised for
+large libraries, and splitting one `extractTs()` source into overlapping units
+is not a valid workaround.
+
+Relate public entries to capability families, configuration, examples, and
+external protocols. Internal call graphs are secondary unless the knowledge
+goal explicitly concerns extension or lifecycle behavior.
+
+## Template composition examples
+
+- A component library may use granular component pages plus family indexes,
+  while its demo site is a separate `web-application` unit.
+- A generated client reads `derived-source.md` and
+  `protocol-boundary.md`; document the supported client surface while naming
+  the upstream schema authority.
+- A library with a plugin host also reads `adapter.md` and
+  `plugin-extension.md`.
+
+## Revise or stop when
+
+- the public boundary cannot be distinguished from internal exports;
+- examples are invented instead of derived from maintained usage or tests;
+- generated declarations have no identifiable authority;
+- every export or component is selected without a consumer-navigation reason;
+- compatibility or lifecycle claims are unavailable but required by the goal.