@c4a/context-cli 0.6.18 → 0.7.0

package/indexers/bundles/context-code-indexer/templates/monorepo-container.md

@@ -0,0 +1,124 @@
+---
+id: context.code-indexer.template.monorepo-container
+kind: procedure
+media-type: text/markdown
+---
+
+# Monorepo and module-container template
+
+Use for `monorepo-container`: a workspace whose stable knowledge is the
+registration, ownership, dependency, build, or release topology of multiple
+child modules. Do not treat the physical repository as one application merely
+because it has one Git remote.
+
+Use the exact profile and Artifact policy variant supplied by the workset.
+
+## Evidence pass
+
+Locate:
+
+- workspace/package/service manifests and child-module discovery rules;
+- build graph, task orchestration, cache, dependency, and affected-scope logic;
+- ownership, tags, boundaries, layering, or dependency constraints;
+- shared configuration and tooling inherited by child modules;
+- release groups, independent packages, deployment units, and version policy;
+- generated, mirrored, vendored, fixture, example, and legacy subtrees;
+- cross-module registries or contracts that warrant separate chain units.
+
+Use declared manifests as the primary inventory. Directory discovery is a
+fallback and must not silently include generated output or dependency caches.
+
+## Questions the knowledge must answer
+
+1. How are child modules discovered and identified?
+2. Which modules are applications, services, libraries, tools, or derived
+   sources, and who owns them?
+3. What dependency and layering rules connect or constrain them?
+4. How do build, test, cache, release, and deployment boundaries work?
+5. Which configuration is inherited globally versus owned by a child module?
+6. Which cross-module flows are important enough to index separately?
+7. Which large or generated subtrees are intentionally excluded?
+
+## Suggested knowledge units
+
+- **Module registry**: child identity, path, type, owner, manifest, supported
+  entry, build/release unit, and lifecycle.
+- **Dependency/topology map**: declared dependency directions, layering rules,
+  shared contracts, and source-backed edges.
+- **Build and release map**: task graph, affected-scope behavior, cache,
+  artifacts, release groups, and deployment units.
+- **Shared tooling/configuration**: only stable workspace-level behavior that
+  materially affects multiple children.
+- **Cross-module chain unit**: independently owned, source-backed flow joining
+  several child modules; do not hide it inside the container summary.
+
+Every user-visible child application, service, library, or CLI is classified as
+its own index unit before deeper extraction.
+
+Each independently visible child package must have one canonical inventory
+identity and one primary partition owner. If source registration intentionally
+remains at repository level, keep the container registry as an aggregate
+logical unit and let Context build child worksets from canonical package facts;
+do not use file filters to simulate package ownership.
+
+## Chapter blueprints
+
+```markdown
+# <Workspace> module registry
+## Workspace purpose and discovery rules
+## Child module inventory
+## Module types, ownership, and lifecycle
+## Dependency and layering constraints
+## Shared configuration and tooling
+## Build, test, cache, and release topology
+## Generated/mirrored boundaries and exclusions
+## Cross-module knowledge entrypoints
+```
+
+One child-module record may use:
+
+```markdown
+## <Module>
+- Path and manifest:
+- Primary/additional types and facets:
+- Responsibility and owner:
+- Stable entrypoints:
+- Direct module dependencies:
+- Build/release unit:
+- Lifecycle/source of truth:
+- Deeper index unit:
+```
+
+## Granularity and relationships
+
+Do not perform a repository-wide symbol scan as the container extraction. The
+container owns topology; child units own reader-facing application/service/API
+knowledge. Aggregate the registry when hundreds of children share the same
+shape, but preserve exact identities and locators.
+
+A workspace manifest, package registry, build graph, or release manifest is a
+valid stable `entries` locator even when the container has no executable
+process. Every registry page must retain exact child identities and locators;
+a directory listing is not a module map.
+
+Use manifest/build-graph evidence for dependency edges. Imports can supplement
+but should not override declared workspace ownership or package boundaries.
+
+## Template composition examples
+
+- A workspace containing a Web app, API gateway, CLI, and generated client
+  produces one registry plus separately classified child units.
+- A workspace with independent release groups reads the
+  `development-and-delivery.md` composer contract; retain the release map at
+  the container level and package-specific compatibility in each `sdk-library`
+  unit.
+- A cross-module request flow reads `cross-module-chain.md` and receives its
+  own output owner when it spans several child units.
+
+## Revise or stop when
+
+- module discovery relies only on a broad filesystem scan;
+- the plan treats all repository files as one index unit;
+- child ownership or source-of-truth boundaries are ambiguous;
+- generated/cache/vendor directories dominate projected output;
+- dependencies are inferred solely from names without manifest or graph proof.

package/indexers/bundles/context-code-indexer/templates/plugin-extension.md

@@ -0,0 +1,52 @@
+---
+id: context.code-indexer.template.plugin-extension
+kind: procedure
+media-type: text/markdown
+---
+
+# Plugin and extension boundary template
+
+Use for `plugin-extension`. This file owns the complete plugin contract
+blueprint. CLI, SDK, and adapter templates should point here and only add their
+module-specific command, public API, or mapping context.
+
+## Evidence pass
+
+Locate:
+
+- discovery mechanism, manifest, registry, or installation contract;
+- activation, deactivation, update, and removal lifecycle;
+- contribution points, commands, hooks, providers, and host services;
+- configuration, identity, compatibility, permissions, and isolation;
+- failure containment, fallback, diagnostics, and version negotiation;
+- public extension API and maintained examples when consumers implement it.
+
+## Questions the knowledge must answer
+
+1. How does the host discover, install, and activate an extension?
+2. What may the extension contribute or call?
+3. Which configuration, identity, permission, and compatibility rules apply?
+4. How are failures isolated, surfaced, and recovered?
+
+## Chapter blueprint
+
+```markdown
+# <Plugin boundary>
+## Host and extension responsibilities
+## Discovery and installation
+## Activation and removal lifecycle
+## Contribution and capability contracts
+## Configuration, permissions, and isolation
+## Compatibility, failure, diagnostics, and recovery
+## Source-backed host-to-extension relationships
+```
+
+## Granularity and stop conditions
+
+Prefer one contract per host/extension model, with compact records for coherent
+contribution families. Do not create separate copies under CLI, adapter, and
+SDK pages. Every page must name concrete manifests, registries, hooks, or
+capability identities and their source locators.
+
+Revise or stop when discovery or activation is inferred, permissions and
+isolation would be guessed, or examples describe an unsupported extension API.

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

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

package/indexers/bundles/context-code-indexer/templates/storage-repository.md

@@ -0,0 +1,56 @@
+---
+id: context.code-indexer.template.storage-repository
+kind: procedure
+media-type: text/markdown
+---
+
+# Storage repository template
+
+Use for `storage-repository` when durable state, cache behavior, consistency, or
+recovery is part of the confirmed reader goal. This template supplements the
+service or runtime that owns the operations; it is not a request to catalog
+every model or query.
+
+## Evidence pass
+
+Locate:
+
+- repository/data-access interface and concrete callers;
+- datastore, table, collection, keyspace, entity, or file identity when
+  source-backed;
+- transaction, consistency, cache, lock, idempotency, and concurrency bounds;
+- read/write/query families and domain mapping;
+- schema/migration authority, versioning, and operational recovery;
+- generated models, query helpers, fixtures, and migrations that should remain
+  supporting evidence.
+
+## Questions the knowledge must answer
+
+1. Which service or domain operation owns each read or write family?
+2. What durable or cached state is addressed?
+3. Where are transaction, consistency, locking, and idempotency boundaries?
+4. Which schema or migration source is authoritative?
+5. What failure, migration, or recovery behavior is maintained?
+
+## Chapter blueprint
+
+```markdown
+# <Persistence boundary>
+## Owned state and authoritative schema
+## Repository or data-access entry
+## Callers and operation families
+## Transaction, consistency, cache, and locking behavior
+## Failure, migration, and recovery boundaries
+## Source evidence and excluded query helpers
+```
+
+## Granularity and stop conditions
+
+Group operations by owned state and consistency policy. Split only when schema
+authority, transaction ownership, datastore, or recovery semantics differ.
+Every page must identify real state and caller boundaries with source locators;
+a directory or class inventory is not a persistence model.
+
+Revise or stop when the datastore identity or owning operation is unknown,
+transaction/consistency behavior would be guessed, or generated bindings and
+migrations would dominate reader-facing pages.

package/indexers/bundles/context-code-indexer/templates/web-application.md

@@ -0,0 +1,146 @@
+---
+id: context.code-indexer.template.web-application
+kind: procedure
+media-type: text/markdown
+---
+
+# Web and interactive application template
+
+Use only after evidence classifies a module as `web-application`. This covers
+browser applications, server-rendered sites, embedded WebViews, desktop Web
+shells, native mobile/desktop applications, cross-platform UI runtimes, and
+similar interactive modules. The `web-application` identifier is retained for
+the current contract but represents an interactive application boundary, not
+only browser code. It does
+not automatically cover every package containing UI components; a reusable
+component package is usually `sdk-library`.
+
+Use the exact profile and Artifact policy variant supplied by the workset.
+
+## Evidence pass
+
+Locate the concrete application bootstrap and trace outward just far enough to
+find:
+
+- application mounting, server rendering, shell, or host-container entry;
+- route/page/screen registries and navigation guards;
+- page-to-state, loader, query, client, bridge, or controller boundaries;
+- runtime configuration, environment selection, feature registration, and
+  authentication/session initialization;
+- build, local development, test, bundle, and release entrypoints;
+- generated clients, assets, styles, fixtures, and legacy routes that should
+  remain evidence rather than reader-facing pages.
+
+If the route registry is generated, locate both its generator or source of
+truth and the runtime consumer. Do not infer page identity from a directory
+tree when an explicit registry exists.
+
+## Questions the knowledge must answer
+
+A useful application index should let a reader determine:
+
+1. How does the application start, and which runtime or host does it expect?
+2. What are the stable pages/routes/screens and their entry components?
+3. How does a page obtain data or call an external capability?
+4. Which state, session, bridge, or configuration boundaries affect behavior?
+5. How is the module run, debugged, built, and released?
+6. Which implementation details are intentionally outside the knowledge scope?
+
+## Suggested knowledge units
+
+Select only units supported by the confirmed goal and evidence:
+
+- **Application map**: responsibility, runtime, bootstrap, major subsystems,
+  stable dependencies, and navigation to deeper pages.
+- **Route or page registry**: concrete route/page identity, entry component,
+  loader/guard, main data boundary, and source locator. Aggregate related
+  routes when a page-per-route layout would be repetitive.
+- **Data and protocol boundaries**: add application-specific page, state, and
+  session context to the canonical operation record in `protocol-boundary.md`;
+  do not create a second operation registry.
+- **State and host integration**: only stable stores, bridges, extension points,
+  or host contracts that affect multiple pages or public behavior.
+- **Runtime and delivery guide**: module-owned development commands,
+  configuration, build output, deployment/release entry, and evidenced recovery
+  paths.
+- **Cross-layer flow**: a source-backed page-to-client-to-provider chain when
+  both sides are registered sources.
+
+These are possible page families, not a required number of Markdown files.
+
+## Chapter blueprints
+
+An application-map page may use:
+
+```markdown
+# <Application> module map
+## Responsibility and supported runtime
+## Bootstrap sequence
+## Route/page organization
+## State, data, and protocol boundaries
+## Host integrations and extension points
+## Configuration and environment selection
+## Development, build, and release entrypoints
+## Known exclusions and source-of-truth links
+```
+
+A route/page registry may use a compact record rather than prose repetition:
+
+```markdown
+## <Route or page family>
+- Identity and registration:
+- Entry component or controller:
+- Loader, guard, or initialization:
+- Main client/state dependencies:
+- User-visible outcome:
+- Source evidence:
+```
+
+A cross-layer page may use:
+
+```markdown
+# <User interaction> execution path
+## Trigger and route entry
+## UI/state orchestration
+## Protocol request and authoritative contract
+## Provider boundary and response handling
+## Failure, fallback, and observability
+## Source-backed relationship chain
+```
+
+Do not fill a heading with generic text. Omit or mark a section as a material
+gap when the source cannot support it.
+
+## Granularity and relationships
+
+Prefer stable application concepts over one page per component, hook, state
+field, style, generated type, or internal helper. A page registry must contain
+real identities and source locators, not just folder names. A protocol page
+must name concrete operations or contract locations, not merely state that the
+application “uses HTTP”.
+
+Create structured relationships only when registration, call sites, imports
+with unambiguous ownership, or parser evidence support them. Keep inferred
+product intent out of the index.
+
+## Template composition examples
+
+- A server-rendered application with local API routes also reads
+  `api-service.md` and `protocol-boundary.md`.
+- An embedded application with a host bridge also reads `adapter-integration.md` and the
+  applicable `plugin-extension.md` or `protocol-boundary.md` template.
+- A design-system package rendered in a demo application may need separate
+  index units: `sdk-library` for the supported package and `web-application`
+  for the demo host.
+
+## Revise or stop when
+
+- no executable bootstrap or route registry can be located;
+- the proposed output is only a directory summary;
+- protocol semantics depend on unavailable material;
+- generated routes or clients are being mistaken for authoritative behavior;
+- one-symbol-per-page selection expands components or API types without a
+  deliberate public-reference goal.
+
+Resolve these issues before returning the current author Result for mechanical
+audit.