@c4a/context-cli 0.7.0 → 0.7.1

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

@@ -1,118 +0,0 @@
----
-id: semantic.code-index.template.adapter
-kind: procedure
-media-type: text/markdown
----
-
-# Adapter, bridge, and integration template
-
-Use for `adapter`: BFFs, protocol bridges, host integrations, plugin adapters,
-compatibility layers, gateways, and translators whose stable responsibility is
-to connect two boundaries. An ordinary internal helper that converts one object
-is not automatically an adapter module.
-
-Recommended `outputProfile`: `adapter-contract`. For an inbound gateway whose
-reader goal is the provided operation surface, use `protocol-index` instead.
-
-## Evidence pass
-
-Locate both sides of the boundary and the code that joins them:
-
-- inbound operation, event, command, host hook, or extension registration;
-- outbound operation, client, plugin contribution, or runtime capability;
-- authoritative input and output contract locations;
-- identity, field, enum, version, and lifecycle mappings;
-- authentication, authorization, credential, and context propagation;
-- validation, normalization, batching, caching, fallback, and compatibility;
-- timeout, retry, partial failure, and error/status translation;
-- configuration, feature selection, ownership, and release entrypoints;
-- generated DTOs/clients and converter helpers that should remain evidence.
-
-Sample representative paths from each mapping family. Do not claim a mapping
-from matching field names alone.
-
-## Questions the knowledge must answer
-
-1. Which two boundaries does the adapter connect, and who owns each one?
-2. What triggers the mapping and where is it registered?
-3. Which fields, identities, versions, or lifecycle states are transformed?
-4. Which values pass through unchanged, default, or intentionally disappear?
-5. How are credentials, context, errors, retries, and fallbacks translated?
-6. Which contracts are authoritative and which artifacts are generated?
-7. What compatibility obligation makes the adapter stable knowledge?
-
-## Suggested knowledge units
-
-- **Adapter contract**: responsibility, inbound/outbound boundaries,
-  registration, ownership, and authoritative contracts.
-- **Operation mapping registry**: use the canonical operation record from
-  `protocol-boundary.md` and add only adapter-specific transformation fields.
-- **Data or identity mapping**: only stable, non-trivial mappings that readers
-  must understand; summarize generated field copies.
-- **Lifecycle and failure translation**: when activation, cancellation,
-  retries, partial failure, or compatibility behavior is material.
-- **Cross-module execution path**: when both connected modules are registered
-  sources and the chain is source-backed.
-
-## Chapter blueprints
-
-```markdown
-# <Adapter> contract
-## Responsibility and connected boundaries
-## Activation or registration
-## Inbound contracts
-## Outbound contracts
-## Data, identity, and lifecycle mapping
-## Authentication and context propagation
-## Error, retry, fallback, and compatibility behavior
-## Configuration, ownership, and release
-## Evidence and exclusions
-```
-
-For adapter-specific detail attached to a canonical operation record:
-
-```markdown
-## Adapter transformation
-- Mapper/handler entry:
-- Field/identity/default transformations:
-- Context and credential propagation:
-- Error and fallback mapping:
-```
-
-## Granularity and relationships
-
-Group mappings that share the same boundary pair and transformation policy.
-Split when protocol authority, ownership, lifecycle, or failure semantics
-differ. Do not publish every DTO, converter, generated client, or transport
-helper separately.
-
-Add structured edges only for concrete registration and call paths. Keep a
-narrative locator when dynamic dispatch prevents an unambiguous edge.
-
-Return `identityGroups` when several target identities share one explained
-adapter responsibility. Return every source-backed adjacency in
-`chainCandidates`, then provide one `chainCandidateDecisions` record for each
-candidate. A documented decision names the reader-facing view and emits its
-structured edge; an equivalent candidate merges into that canonical candidate;
-false positives and missing external material use `exclude` or `request-input`
-with a concrete reason. Read `contracts-and-chains.md` for the complete generic
-contract.
-
-## Template composition examples
-
-- An HTTP endpoint backed by an RPC client is `api-service` + `adapter`; combine
-  one operation registry with one mapping contract rather than duplicating the
-  route facts.
-- A host plugin bridge reads `plugin-extension.md` and may also be `sdk-library`
-  when consumers import
-  a supported extension API.
-- A compatibility wrapper over generated clients also reads
-  `derived-source.md` and identifies the authoritative schemas.
-
-## Revise or stop when
-
-- either side of the adapter cannot be identified;
-- mappings are inferred only from same-named types or fields;
-- credential, identity, or error behavior would be guessed;
-- generated DTOs are replacing authoritative contracts in the plan;
-- the adapter page would merely say that one module “calls” another.

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

@@ -1,116 +0,0 @@
----
-id: semantic.code-index.template.api-service
-kind: procedure
-media-type: text/markdown
----
-
-# API service and gateway template
-
-Use after classifying an inbound HTTP, RPC, GraphQL, message-request, or similar
-surface as `api-service`. A module that only calls a remote API is a protocol
-consumer, not automatically an API service. Gateways that translate to another
-protocol normally also select `adapter`.
-
-Recommended `outputProfile`: `protocol-index`. If the reader goal is primarily
-the transformation between inbound and outbound boundaries, use
-`adapter-contract` instead and retain one canonical operation registry.
-
-## Evidence pass
-
-Locate and connect:
-
-- process/server entry and service startup;
-- route, method, resolver, or service registration;
-- middleware, authentication, authorization, validation, and request context;
-- handler dispatch and the first stable domain/downstream boundary;
-- authoritative IDL, OpenAPI, schema, service definition, or registration;
-- response/error mapping, retry, timeout, and compatibility behavior;
-- configuration, local run, test, deployment, and release entrypoints;
-- generated models or clients and their actual source of truth.
-
-Prefer explicit registrations over handler filenames. Sample enough operations
-from each registration family to verify that the proposed aggregation is real.
-
-## Questions the knowledge must answer
-
-1. What protocol does the module provide, and where is it registered?
-2. Which operations are stable and who handles each one?
-3. What authentication, validation, middleware, or request context applies?
-4. Where does each operation hand off to domain logic or a downstream system?
-5. How are successful responses and failures translated?
-6. Which schema is authoritative, and which files are generated projections?
-7. How is the service run, configured, observed, and released?
-
-## Suggested knowledge units
-
-- **Service boundary**: responsibility, startup, supported protocols,
-  middleware order, downstream systems, and ownership.
-- **Operation registry**: use the canonical operation record from
-  `protocol-boundary.md`, adding handler and middleware detail from this
-  template rather than creating a second registry.
-- **Dispatch and dependency map**: route/service registration to handler to
-  domain/RPC/repository boundary, grouped by coherent operation family.
-- **Error and compatibility contract**: only when status/error mapping,
-  versioning, fallback, or compatibility is stable and source-backed.
-- **Runtime and delivery guide**: configuration, startup, diagnostics,
-  deployment, and release entrypoints owned by this service.
-
-Do not create a page per generated request/response model, constant, converter,
-pack/unpack helper, or handler-local function.
-
-## Chapter blueprints
-
-A service-boundary page may use:
-
-```markdown
-# <Service> boundary
-## Responsibility and consumers
-## Startup and protocol registration
-## Middleware and request lifecycle
-## Operation families
-## Domain and downstream dependencies
-## Error, timeout, and compatibility behavior
-## Configuration, observability, and release
-## Exclusions and authoritative schemas
-```
-
-A focused execution-path page may use:
-
-```markdown
-# <Operation> execution path
-## Inbound contract
-## Middleware and validation
-## Handler orchestration
-## Domain/downstream handoff
-## Response and error mapping
-## Source-backed edges
-```
-
-## Granularity and relationships
-
-Aggregate operations that share registration, middleware, handler family, and
-downstream ownership. Split when operation families have different contracts,
-owners, or execution paths—not merely because they are separate methods.
-
-Record a route-to-handler or handler-to-downstream edge only when the route
-table, registration, call site, or parser evidence is unambiguous. Generated
-types can locate fields but do not prove runtime behavior.
-
-## Template composition examples
-
-- A gateway that receives HTTP and calls RPC reads `adapter.md` and
-  `protocol-boundary.md` in addition to this template.
-- An RPC service containing stable domain orchestration also reads
-  `domain-service.md`.
-- An event-triggered endpoint may require `event-flow.md`; background consumers
-  use `background-runtime.md`.
-
-## Revise or stop when
-
-- no registration or authoritative operation identity is available;
-- the plan lists handlers without connecting them to provided operations;
-- the only contract source is generated code with an unknown upstream schema;
-- security or error behavior would be guessed from names;
-- scan mode would expand models and helpers into hundreds of pages.
-
-Mark unavailable protocol semantics as `material-required` before preview.

package/providers/context/resources/semantic/code-index/templates/background-runtime.md

@@ -1,109 +0,0 @@
----
-id: semantic.code-index.template.background-runtime
-kind: procedure
-media-type: text/markdown
----
-
-# Background runtime template
-
-Use for `background-runtime`: queue or stream consumers, scheduled jobs,
-pipelines, functions, controllers, watchers, and long-running agents activated
-by a trigger instead of an interactive request.
-
-Recommended `outputProfile`: `runtime-map`.
-
-## Evidence pass
-
-Locate:
-
-- process/runtime bootstrap and worker/job registration;
-- trigger identity: topic, queue, schedule, hook, file, controller event, or
-  platform invocation;
-- payload/schema locator and producer when available;
-- handler dispatch, concurrency, partitioning, ordering, and state changes;
-- downstream services, persistence, emitted events, and side effects;
-- retry, timeout, checkpoint, idempotency, dead-letter, and recovery behavior;
-- configuration, scaling, health, observability, deployment, and ownership;
-- replay/test fixtures and generated payload types that are not authoritative.
-
-Distinguish code defaults from runtime configuration. Do not describe delivery
-guarantees unless registration, framework configuration, or maintained
-documentation proves them.
-
-## Questions the knowledge must answer
-
-1. What activates the runtime and where is that trigger registered?
-2. What input contract is consumed, and who produces it?
-3. How does work move from dispatch through orchestration and side effects?
-4. What are the concurrency, ordering, retry, and idempotency boundaries?
-5. How does the runtime checkpoint, recover, or surface failed work?
-6. How is it configured, operated, observed, scaled, and deployed?
-
-## Suggested knowledge units
-
-- **Runtime map**: bootstrap, trigger families, handler registry, dependencies,
-  state boundaries, and operating model.
-- **Trigger/workflow registry**: stable trigger identity, input contract,
-  handler, downstream effects, retry/idempotency, and source locator.
-- **Processing flow**: focused end-to-end path for a high-value workflow family.
-- **Recovery and operations guide**: checkpointing, failed work, observability,
-  configuration, local execution, deployment, and safe replay where evidenced.
-- **Producer-consumer chain**: only when both registered modules and the event
-  identity are source-backed.
-
-## Chapter blueprints
-
-```markdown
-# <Background runtime> map
-## Responsibility and activation model
-## Bootstrap and trigger registration
-## Workflow or handler families
-## State and downstream side effects
-## Concurrency, ordering, retry, and idempotency
-## Failure recovery and observability
-## Configuration, scaling, and deployment
-## Contract sources and exclusions
-```
-
-For a trigger family:
-
-```markdown
-## <Trigger or workflow>
-- Trigger identity and registration:
-- Input contract and producer:
-- Dispatch and handler:
-- State changes and downstream effects:
-- Retry/idempotency/checkpoint behavior:
-- Failure destination and operator action:
-- Source evidence:
-```
-
-## Granularity and relationships
-
-Prefer one record per stable trigger or coherent workflow family. Do not create
-one page per handler helper, event field, retry branch, or generated payload
-type. Split a page when triggers have different contracts, ownership, delivery,
-or recovery semantics.
-
-Every retained page must name concrete trigger, handler, state, side-effect,
-and recovery identities with source locators. A runtime page that only lists
-directories or says a worker “processes events” is too thin.
-
-Connect producers and consumers only through a concrete topic/trigger/schema
-identity. A shared type name or import is insufficient.
-
-## Template composition examples
-
-- A consumer that invokes a domain boundary reads `domain-service.md`.
-- A scheduler that calls external APIs selects `protocol-consumer` and reads
-  `protocol-boundary.md`.
-- A controller exposing administrative commands may combine this template with
-  `cli-tool.md` or `api-service.md`, but should still produce one runtime map.
-
-## Revise or stop when
-
-- no trigger registry or executable worker entry can be found;
-- delivery, ordering, retry, or idempotency would be guessed;
-- the producer or authoritative payload contract is required but unavailable;
-- the plan expands generated event structures or helpers one symbol per page;
-- runtime configuration cannot be distinguished from test setup.

package/providers/context/resources/semantic/code-index/templates/cli-tool.md

@@ -1,129 +0,0 @@
----
-id: semantic.code-index.template.cli-tool
-kind: procedure
-media-type: text/markdown
----
-
-# CLI and developer tool template
-
-Use for `cli-tool`: command-line applications, developer tools, administrative
-executables, generators, and command-driven plugin hosts. A build script used
-only internally does not need a CLI knowledge unit unless it is a supported
-operator or contributor surface.
-
-Recommended `outputProfile`: `command-map`.
-
-## Evidence pass
-
-Locate:
-
-- executable/bin entry, runtime requirement, and command parser;
-- root and nested command registration;
-- positional arguments, flags, defaults, mutually exclusive options, and input
-  schemas;
-- configuration files, environment variables, profiles, credential sources,
-  and precedence;
-- interactive prompts versus non-interactive/automation behavior;
-- filesystem, repository, network, platform, and plugin side effects;
-- output formats, stdout/stderr behavior, exit codes, polling, and recovery;
-- local development, packaging, installation, compatibility, and release;
-- deprecated commands, aliases, parser helpers, and formatters to exclude.
-
-Inspect actual command registration and representative execution paths. Help
-text is useful evidence but may not describe hidden preconditions or effects.
-
-## Questions the knowledge must answer
-
-1. How is the CLI installed or invoked, and what runtime does it require?
-2. What stable command families exist and what user outcomes do they produce?
-3. What inputs, configuration, credentials, and precedence rules apply?
-4. Which commands mutate files, repositories, remote services, or user state?
-5. What output and exit behavior supports automation and diagnosis?
-6. Which plugin or extension points change the command surface?
-7. How does a user recover from common source-backed failure states?
-
-## Suggested knowledge units
-
-- **Command map**: invocation model, command families, configuration,
-  credentials, side effects, output formats, and extension points.
-- **Task workflow**: an end-to-end supported user goal spanning several
-  commands, with preconditions, state transitions, and recovery.
-- **Command-family reference**: coherent subcommands with inputs, outputs,
-  side effects, and examples.
-- **Configuration and credentials**: when precedence or environment behavior is
-  complex and stable enough for a dedicated page.
-- **Plugin/extension contract**: use the single complete blueprint in
-  `plugin-extension.md`; the command map only links commands and configuration
-  to that contract.
-- **Development and release guide**: only source-backed contributor workflows
-  owned by this module.
-
-## Chapter blueprints
-
-```markdown
-# <CLI> command map
-## Purpose, installation, and invocation
-## Command families
-## Configuration and precedence
-## Credentials and external dependencies
-## Filesystem/repository/remote side effects
-## Output formats and exit semantics
-## Plugins, compatibility, and release
-## Diagnostics, recovery, and exclusions
-```
-
-For a command family:
-
-```markdown
-# <Command family>
-## User outcomes and preconditions
-## Commands and arguments
-## Configuration and credential requirements
-## Execution and side effects
-## Output and exit behavior
-## Failure recovery
-## Source-backed examples
-```
-
-A workflow page may use:
-
-```markdown
-# <User task>
-## Starting state
-## Command sequence
-## State and artifact changes
-## Remote operations
-## Success checks
-## Recovery and rollback boundaries
-```
-
-## Granularity and relationships
-
-Prefer command families and user tasks over one page per parser node, flag,
-prompt, formatter, or implementation function. Split only when commands have
-different state ownership, external systems, or safety/recovery contracts.
-
-Every retained page must name real commands, task outcomes, state changes, or
-extension identities with source locators. A list of command directories or
-parser nodes is not a command map.
-
-Connect commands to configuration, package/file outputs, plugin providers, and
-platform operations only when source registrations or call sites prove them.
-
-## Template composition examples
-
-- A CLI with installable providers also reads `adapter.md` and
-  `plugin-extension.md`.
-- A CLI that primarily wraps a remote protocol selects `protocol-consumer` and
-  reads `protocol-boundary.md`.
-- A monorepo release tool may combine this template with
-  `monorepo-container.md` and `build-release` without duplicating its command
-  registry.
-
-## Revise or stop when
-
-- no stable command registry or executable entry is found;
-- examples require inventing flags or commands not present in source;
-- side effects or credential behavior are unclear but material to safe use;
-- every option/parser helper is becoming an independent page;
-- deprecated or hidden implementation commands are presented as supported.

package/providers/context/resources/semantic/code-index/templates/contract-source.md

@@ -1,73 +0,0 @@
----
-id: semantic.code-index.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.
-
-Recommended `outputProfile`: `protocol-index`. Also select
-`protocol-provider`, and use `generated-contract` only for generated projections
-that point back to this authority. The normal lifecycle is `authoritative`.
-
-## 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/providers/context/resources/semantic/code-index/templates/contracts-and-chains.md

@@ -1,81 +0,0 @@
----
-id: semantic.code-index.template.contracts-and-chains
-kind: procedure
-media-type: text/markdown
----
-
-# Contracts, identity groups, and execution chains
-
-Use this resource after module classification when a code index must connect
-stable identities without turning the inventory into reader-facing prose. It
-applies to application, service, library, runtime, command, adapter, and
-cross-source units.
-
-## Separate inspection facts from reader content
-
-The adapter inventory is complete machine evidence. A reader page should group
-members only when they share a source-backed responsibility, boundary, or
-lifecycle. Do not create one sentence, bullet, row, or page per discovered
-identity.
-
-An `identityGroups` record must provide:
-
-- a stable group `id`;
-- the exact target `members` from the same index-unit inventory;
-- one reader-facing `viewRef` that explains their common responsibility;
-- `sourceFiles` from the eligible-file inventory that prove membership.
-
-The referenced page must cite every declared source file. A group does not pass
-coverage merely because its members exist in frontmatter or evidence.
-
-## Discover chain candidates
-
-Emit a candidate only when code structure or an authoritative declaration
-supports both adjacent endpoints. Supported families are:
-
-- `entry-operation`;
-- `operation-handler`;
-- `handler-downstream`;
-- `event-processing`;
-- `command-effect`;
-- `export-implementation`;
-- `cross-source-handoff`.
-
-Each candidate records a stable `id`, `from`, `to`, confidence, and the exact
-eligible `sourceFiles` that support the adjacency. Imports, filenames, symbol
-co-occurrence, or similar names alone are ambiguous evidence; mark such a
-candidate ambiguous or request material instead of asserting a runtime chain.
-
-## Decide every candidate
-
-Every discovered candidate receives exactly one decision:
-
-- `document`: add a source-backed structured edge and name its reader-facing
-  `viewRef`;
-- `merge`: point `canonicalChainId` at an equivalent candidate whose decision
-  is `document`;
-- `exclude`: explain why the static match is not a stable runtime relation;
-- `request-input`: explain which external protocol, runtime registration, or
-  authoritative material is missing.
-
-Decision coverage is 100%. Excluding all candidates does not close an external
-boundary family: at least one representative chain must be documented, merged
-into a documented chain, or explicitly require material.
-
-## Reader-facing chain blueprint
-
-```markdown
-## <Reader goal or boundary>
-
-<Explain the starting trigger and the stable outcome.>
-
-1. **Entry or trigger** — <identity and responsibility>.
-2. **Operation or handler** — <validation, transformation, or state change>.
-3. **External handoff or effect** — <contract, ownership, and next boundary>.
-
-Failure and retry boundary: <only source-backed behavior>.
-Evidence: <section-scoped locators for each adjacent handoff>.
-```
-
-Remove stages that do not apply. Do not leave empty template headings, repeat a
-module inventory, or infer missing runtime behavior.