@c4a/context-cli 0.7.0 → 0.7.4

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.

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.