@c4a/context-cli 0.6.13 → 0.6.17

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

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

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

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

@@ -0,0 +1,73 @@
+---
+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/cross-module-chain.md

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

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