@c4a/context-cli 0.6.19 → 0.7.1

package/indexers/bundles/context-code-indexer/references/metrics.md

@@ -0,0 +1,201 @@
+# Profile metric revision guide
+
+Use the current CLI audit as the sole source of actual, recommended, and hard values. This guide explains how to revise a Result; it does not define thresholds or authorize changing a denominator.
+
+## inventory-disposition-coverage
+
+### Meaning
+
+Every identity in the CLI inventory needs an owned, excluded, or unsupported disposition.
+
+### Revise
+
+Return decisions for the reported missing identities, preserving the complete inventory denominator and citing the evidence behind exclusions or unsupported cases.
+
+### Positive example
+
+An internal generated file is retained in the inventory and marked excluded with its generated-source evidence.
+
+### Anti-example
+
+The Result omits files that did not fit the selected template.
+
+## duplicated-fact-target-ratio
+
+### Meaning
+
+The same reader fact should have one canonical target rather than competing copies across Artifacts.
+
+### Revise
+
+Choose the canonical owner, replace other copies with explicit relationships, and keep evidence on the owning fact.
+
+### Positive example
+
+One contract Artifact owns the request semantics while the overview links to it.
+
+### Anti-example
+
+Several pages repeat the same behavior paragraph with different headings.
+
+## narrative-enumeration-ratio
+
+### Meaning
+
+Reader prose should explain capabilities and boundaries instead of restating a deterministic inventory as sentences.
+
+### Revise
+
+Move exhaustive identities into the deterministic catalog, group related items by a reader question, and explain responsibility, differences, and handoffs.
+
+### Positive example
+
+A capability section explains dispatch choices and links to a complete generated route catalog.
+
+### Anti-example
+
+The page turns every discovered symbol into an “observed” bullet.
+
+## normalized-template-repetition-ratio
+
+### Meaning
+
+Repeated sentence frames with only identity substitutions indicate template residue rather than evidence-specific explanation.
+
+### Revise
+
+Merge repeated observations, describe the shared rule once, and record meaningful exceptions with their own evidence.
+
+### Positive example
+
+A family section states the common lifecycle and separately explains the exceptional member.
+
+### Anti-example
+
+Every member receives the same sentence with only its name changed.
+
+## implementation-body-ratio
+
+### Meaning
+
+Reader knowledge should describe stable behavior without copying implementation bodies, generated payloads, or declaration dumps.
+
+### Revise
+
+Replace copied code with an evidence-bound behavioral statement and retain only a small excerpt when it is necessary to explain a contract or failure boundary.
+
+### Positive example
+
+The page explains the validation and rollback sequence and links to the exact implementation locator.
+
+### Anti-example
+
+The page embeds the complete function or generated type file as its main content.
+
+## reference-only-reader-targets
+
+### Meaning
+
+A reader target requires a CLI-authorized declaration, registration, public contract, approved Subject, or Partition Subject identity.
+
+### Revise
+
+Merge aliases and ordinary references into their canonical owner, or remove the target when no authorized identity observation exists.
+
+### Positive example
+
+A re-export alias points to the canonical public target instead of creating another page.
+
+### Anti-example
+
+A frequently imported helper becomes a target solely because it has many references.
+
+## unresolved-ordinal-partitions
+
+### Meaning
+
+Partition identity must come from a stable semantic boundary, not traversal order or a fixed batch label.
+
+### Revise
+
+Regroup members by capability, entrypoint, lifecycle stage, state owner, protocol boundary, or handoff; if none applies, return the protocol outcome for CLI-owned catalog fallback.
+
+### Positive example
+
+Handlers are grouped by the reader-visible protocol capability they implement.
+
+### Anti-example
+
+Files are divided into successive numbered batches to reduce page size.
+
+## discretionary-artifacts-per-logical-unit
+
+### Meaning
+
+Optional Artifacts must answer distinct reader questions allowed by the selected Bundle variant.
+
+### Revise
+
+Remove unsupported optional Artifacts, merge overlapping ones, or select another CLI-eligible variant when canonical facts justify it.
+
+### Positive example
+
+An examples Artifact is retained because it explains a distinct usage scenario with independent evidence.
+
+### Anti-example
+
+The Result creates extra pages to spread the same prose across a larger Bundle.
+
+## example-candidate-decision-coverage
+
+### Meaning
+
+Every CLI-discovered example candidate needs one explicit terminal or merge decision.
+
+### Revise
+
+Decide each reported candidate as linked, merged, documentation-only, excluded with reason, or blocked by a material request.
+
+### Positive example
+
+A duplicate scenario is merged into a canonical example through its full example identity.
+
+### Anti-example
+
+Unclear examples disappear from the Result without a disposition.
+
+## example-representative-coverage
+
+### Meaning
+
+Eligible scenarios need retained representatives that explain setup, key calls, parameters, and expected behavior.
+
+### Revise
+
+Promote or merge evidence-backed examples for the reported uncovered scenarios and close each required facet explicitly.
+
+### Positive example
+
+A canonical example covers the scenario and records evidence-backed not-applicable facets.
+
+### Anti-example
+
+A path is listed as an example without explaining how or why it is used.
+
+## example-public-target-linkage
+
+### Meaning
+
+Eligible examples should resolve to the exact public target they demonstrate whenever that target exists.
+
+### Revise
+
+Resolve aliases, repair the terminal decision chain, and bind the representative to the CLI-supplied public target identity.
+
+### Positive example
+
+A scenario variant merges into a representative whose terminal decision links the canonical public target.
+
+### Anti-example
+
+An example is linked to a similarly named internal helper or only to a directory.

package/{providers/context/resources/semantic/code-index/templates/adapter.md → indexers/bundles/context-code-indexer/templates/adapter-integration.md}

@@ -1,18 +1,19 @@
 ---
-id: semantic.code-index.template.adapter
+id: context.code-indexer.template.adapter-integration
 kind: procedure
 media-type: text/markdown
 ---
 
 # Adapter, bridge, and integration template
 
-Use for `adapter`: BFFs, protocol bridges, host integrations, plugin adapters,
+Use for `adapter-integration`: 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.
+Use the exact profile and Artifact policy variant supplied by the workset. For
+an inbound operation surface, combine this template with the selected gateway
+or protocol evidence without creating a second operation registry.
 
 ## Evidence pass
 
@@ -89,16 +90,25 @@ 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
+- An HTTP endpoint backed by an RPC client is `api-service` + `adapter-integration`; 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.
+  `derived-generated-source.md` and identifies the authoritative schemas.
 
 ## Revise or stop when
 

package/{providers/context/resources/semantic/code-index → indexers/bundles/context-code-indexer}/templates/api-service.md

@@ -1,5 +1,5 @@
 ---
-id: semantic.code-index.template.api-service
+id: context.code-indexer.template.api-service
 kind: procedure
 media-type: text/markdown
 ---
@@ -9,11 +9,12 @@ media-type: text/markdown
 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`.
+protocol normally also selects `adapter-integration`.
 
-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.
+Use the exact profile and Artifact policy variant supplied by the workset. If
+the reader goal is primarily the transformation between inbound and outbound
+boundaries, use the selected adapter-integration profile and retain one
+canonical operation registry.
 
 ## Evidence pass
 
@@ -98,7 +99,7 @@ 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
+- A gateway that receives HTTP and calls RPC reads `adapter-integration.md` and
   `protocol-boundary.md` in addition to this template.
 - An RPC service containing stable domain orchestration also reads
   `domain-service.md`.
@@ -113,4 +114,5 @@ types can locate fields but do not prove runtime behavior.
 - 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.
+Return a `request-material` disposition tied to a blocking material-question
+proposal when required protocol semantics remain unavailable before preview.

package/{providers/context/resources/semantic/code-index → indexers/bundles/context-code-indexer}/templates/background-runtime.md

@@ -1,5 +1,5 @@
 ---
-id: semantic.code-index.template.background-runtime
+id: context.code-indexer.template.background-runtime
 kind: procedure
 media-type: text/markdown
 ---
@@ -10,7 +10,7 @@ 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`.
+Use the exact profile and Artifact policy variant supplied by the workset.
 
 ## Evidence pass
 
@@ -95,7 +95,7 @@ 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
+- A scheduler that calls external APIs selects `adapter-integration` 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.

package/{providers/context/resources/semantic/code-index → indexers/bundles/context-code-indexer}/templates/cli-tool.md

@@ -1,5 +1,5 @@
 ---
-id: semantic.code-index.template.cli-tool
+id: context.code-indexer.template.cli-tool
 kind: procedure
 media-type: text/markdown
 ---
@@ -11,7 +11,7 @@ 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`.
+Use the exact profile and Artifact policy variant supplied by the workset.
 
 ## Evidence pass
 
@@ -112,13 +112,13 @@ platform operations only when source registrations or call sites prove them.
 
 ## Template composition examples
 
-- A CLI with installable providers also reads `adapter.md` and
+- A CLI with installable providers also reads `adapter-integration.md` and
   `plugin-extension.md`.
-- A CLI that primarily wraps a remote protocol selects `protocol-consumer` and
+- A CLI that primarily wraps a remote protocol selects `adapter-integration` 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.
+  `monorepo-container.md` and the `development-and-delivery.md` composer
+  contract without duplicating its command registry.
 
 ## Revise or stop when
 

package/indexers/bundles/context-code-indexer/templates/component-library.md

@@ -0,0 +1,99 @@
+---
+id: context.code-indexer.template.component-library
+kind: procedure
+media-type: text/markdown
+---
+
+# Component library template
+
+Use for `component-library`: a supported collection of UI components, tokens,
+hooks, primitives, or design-system packages consumed through documented
+imports and component contracts. A web application that happens to contain
+shared components remains a `web-application` unless the component surface is
+published as an independent consumer boundary.
+
+Use the exact profile and Artifact policy variant supplied by the workset.
+
+## Evidence pass
+
+Locate:
+
+- public package exports, component registries, barrels, or documented imports;
+- component props, slots, events, variants, composition, and lifecycle rules;
+- theme, token, styling, accessibility, locale, and provider requirements;
+- maintained examples, stories, visual tests, and consumer integration tests;
+- compatibility, peer dependency, platform, and release constraints;
+- generated declarations, documentation sites, demos, and internal primitives
+  that must not become independent reader pages without a public contract.
+
+Treat stories and examples as usage evidence, not as authority for unsupported
+props or behavior. When generated declarations disagree with source, identify
+the authoritative source and record the gap.
+
+## Questions the knowledge must answer
+
+1. Which component families are public, and how are they imported?
+2. What props, events, variants, slots, and composition rules are supported?
+3. Which providers, themes, tokens, runtimes, or peer packages are required?
+4. What accessibility, state, lifecycle, and failure constraints apply?
+5. Which examples demonstrate supported use and important combinations?
+6. Which implementation primitives or demo-only components are excluded?
+
+## Suggested knowledge units
+
+- **Library map**: purpose, supported entrypoints, providers, component
+  families, compatibility, and navigation.
+- **Component-family guide**: shared concepts, composition, variants,
+  accessibility, and representative source-backed examples.
+- **Granular component reference**: only when consumers search for the exact
+  public component and its contract contains meaningful behavior.
+- **Tokens and theming**: only the stable consumer contract, including scope,
+  defaults, override order, and compatibility.
+- **Migration or compatibility guide**: only when maintained sources describe
+  version transitions or supported platform constraints.
+
+## Chapter blueprints
+
+```markdown
+# <Component library> map
+## Purpose and intended consumers
+## Supported imports and providers
+## Component and token families
+## Composition and state model
+## Accessibility and localization
+## Theming and customization
+## Compatibility and release constraints
+## Examples, evidence, and exclusions
+```
+
+For a component family:
+
+```markdown
+# <Component family>
+## When to use it
+## Supported components and imports
+## Props, events, slots, and variants
+## Composition and state
+## Accessibility and interaction
+## Source-backed examples
+## Related families and evidence
+```
+
+## Granularity and relationships
+
+Prefer component families over one page per export. Use a granular page only
+when the exact public identity has a stable consumer contract beyond a type
+signature. Relate components to providers, tokens, accessibility behavior,
+examples, and compatible peers only when source evidence supports the link.
+
+Do not copy implementation bodies, generated declarations, every story, or
+every styling variant into reader-facing content. Do not use ordinal batches
+to disguise an enumeration-heavy index.
+
+## Revise or stop when
+
+- public components cannot be distinguished from internal or demo-only code;
+- component behavior is inferred only from screenshots or names;
+- examples invent combinations that maintained usage does not support;
+- accessibility or provider requirements are asserted without evidence;
+- one-page-per-component expansion has no consumer-navigation justification.

package/{providers/context/resources/semantic/code-index → indexers/bundles/context-code-indexer}/templates/contract-source.md

@@ -1,5 +1,5 @@
 ---
-id: semantic.code-index.template.contract-source
+id: context.code-indexer.template.contract-source
 kind: procedure
 media-type: text/markdown
 ---
@@ -11,9 +11,9 @@ 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`.
+Use the exact profile and Artifact policy variant supplied by the workset.
+Generated projections must point back to this authority and remain supporting
+evidence rather than a second contract authority.
 
 ## Evidence pass
 

package/{providers/context/resources/semantic/code-index/templates/cross-module-chain.md → indexers/bundles/context-code-indexer/templates/data-sync-reconciliation.md}

@@ -1,15 +1,15 @@
 ---
-id: semantic.code-index.template.cross-module-chain
+id: context.code-indexer.template.data-sync-reconciliation
 kind: procedure
 media-type: text/markdown
 ---
 
-# Cross-module flow template
+# Data synchronization and reconciliation 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.
+Use for `data-sync-reconciliation` when a stable reader question crosses source,
+transformation, persistence, delivery, or reconciliation boundaries. The flow
+is an independently owned logical unit; each participating module keeps its own
+non-duplicated responsibility map.
 
 ## Evidence pass
 
@@ -52,13 +52,12 @@ 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
+## Partition 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.
+A flow normally cites sources already owned by module units. Give the flow one
+stable SubjectKey and keep module inventory ownership unchanged; its author
+workset may reference the exact cross-source evidence views but must not claim
+the same inventory members as a second primary owner.
 
 The aggregate candidate may cite evidence from every participating source. It
 must cover all Route-reported structural probes selected by the flow profile;

package/{providers/context/resources/semantic/code-index/templates/derived-source.md → indexers/bundles/context-code-indexer/templates/derived-generated-source.md}

@@ -1,12 +1,12 @@
 ---
-id: semantic.code-index.template.derived-source
+id: context.code-indexer.template.derived-generated-source
 kind: procedure
 media-type: text/markdown
 ---
 
 # Generated, mirrored, vendored, and legacy source template
 
-Use for `derived-source` and lifecycle values `generated`, `mirrored`,
+Use for `derived-generated-source` and source states `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.
@@ -49,10 +49,11 @@ markers, build steps, headers, manifests, or source mapping.
 - **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.
+Default to a narrow provenance Artifact unless the workset also selects a
+supported consumer surface. A consumer-facing derived unit must bind its
+authority evidence to the confirmed source locator; a missing authority remains
+a material gap rather than a reason to invent semantics or hide the supported
+consumer surface.
 
 ## Chapter blueprints
 
@@ -94,17 +95,17 @@ 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.
+or upstream meaning in a `request-material` disposition tied to a blocking
+material-question proposal until the missing authority is provided.
 
 ## Template composition examples
 
-- A generated API client is `sdk-library` + `derived-source` and reads
+- A generated API client is `sdk-library` + `derived-generated-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.
+  `adapter-integration.md`; document only proven compatibility and migration behavior.
 
 ## Revise or stop when
 

package/{providers/context/resources/semantic/code-index → indexers/bundles/context-code-indexer}/templates/domain-service.md

@@ -1,17 +1,17 @@
 ---
-id: semantic.code-index.template.domain-service
+id: context.code-indexer.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
+Use for `domain-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`.
+Use the exact profile and Artifact policy variant supplied by the workset.
 
 ## Evidence pass
 
@@ -95,7 +95,7 @@ similar names or shared models.
 
 - 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
+- A service backed by durable storage also selects `storage-repository` and reads
   `persistence-boundary.md`.
 - A service activated only by events also reads `background-runtime.md` and the
   `event-flow.md` template.

package/{providers/context/resources/semantic/code-index/templates/event-flow.md → indexers/bundles/context-code-indexer/templates/event-consumer.md}

@@ -1,14 +1,14 @@
 ---
-id: semantic.code-index.template.event-flow
+id: context.code-indexer.template.event-consumer
 kind: procedure
 media-type: text/markdown
 ---
 
-# Event producer and consumer template
+# Event 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.
+Use for `event-consumer`. This template supplements the owning runtime, service,
+application, or adapter Artifact; an event signal does not by itself justify a
+separate end-to-end Artifact.
 
 ## Evidence pass
 

package/{providers/context/resources/semantic/code-index/templates/protocol-boundary.md → indexers/bundles/context-code-indexer/templates/gateway-facade.md}

@@ -1,15 +1,15 @@
 ---
-id: semantic.code-index.template.protocol-boundary
+id: context.code-indexer.template.gateway-facade
 kind: procedure
 media-type: text/markdown
 ---
 
-# Protocol provider and consumer template
+# Gateway and protocol facade 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.
+Use for `gateway-facade` when the selected reader goal is the boundary exposed
+or translated by one gateway. This template owns the canonical operation
+record. Application, API, service, SDK, contract-source, and adapter templates
+provide context but must not create a second registry for the same operations.
 
 ## Evidence pass
 
@@ -60,15 +60,16 @@ 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.
+For generated contract material, also select `derived-generated-source` and
+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
+When the upstream authority is unavailable, a separate provenance Artifact 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.
+known authority gap. Keep the question that would explain field semantics or
+compatibility unresolved as a material gap; do not block an independently
+supported provenance record.
 
 For a `contract-source` module, preserve exact operation identities, namespaces,
 versions, compatibility declarations, imports, and generator targets. Do not