@sumrco/cli 0.2.1 → 0.3.1

package/ai/modules/kontract/resources/generated-output.rf.md

@@ -14,9 +14,9 @@ Generated files are deterministic outputs. Import them; never edit them.
 Every generated TypeScript file starts with an `<auto-generated>` comment that
 warns users not to edit the file directly.
 
-## HTTP output — one folder per OpenAPI service
+## HTTP output — one folder per API schema service
 
-For an OpenAPI service such as `recipes.openapi.yml`, the NestJS target
+For an API schema service such as `recipes.api.yml`, the NestJS target
 emits a service folder:
 
 ```text
@@ -28,7 +28,13 @@ contracts/recipes/
     models/
     zod/              # when zod generation is enabled
     dto/              # when dtos generation is enabled
-    swagger.ts        # when dtos generation is enabled
+    sdk/              # when sdk generation is enabled
+    swagger.ts        # when swagger generation is enabled
+
+contracts/shared/
+  http/
+    decorators/
+      api-doc.ts      # one shared helper when swagger generation is enabled
 ```
 
 Shared `$ref` components keep the source spec DRY and semantically consistent.
@@ -45,6 +51,7 @@ symbol names:
 ```typescript
 export * as Dtos from './dto';
 export * as Models from './models';
+export * as Sdk from './sdk';
 export * as ZodContracts from './zod';
 export * from './enums';
 export * from './swagger';
@@ -53,7 +60,7 @@ export * from './swagger';
 Do not flatten-import everything blindly when DTO/model/Zod symbols collide.
 Use the namespace exports or import from the leaf folder.
 
-## Zod contract — one file per OpenAPI `components/schemas` entry
+## Zod contract — one file per API schema `components/schemas` entry
 
 ```typescript
 // contracts/recipes/http/zod/recipe.contract.ts
@@ -84,17 +91,17 @@ export interface Recipe {
 }
 ```
 
-Model interfaces are framework-neutral and are safe for backend and frontend
+Model interfaces are framework-and are safe for backend and frontend
 type-only imports.
 
-Map-shaped schemas follow OpenAPI `additionalProperties` semantics:
+Map-shaped schemas follow API schema `additionalProperties` semantics:
 
 - map-only schemas generate index signatures such as `[key: string]: string`;
 - named properties with `additionalProperties: true` preserve the named fields
   and use `[key: string]: unknown`;
 - named properties with typed `additionalProperties` preserve named fields and
   widen the index signature with known property value types, matching the
-  practical TypeScript approach used by current OpenAPI TypeScript generators.
+  practical TypeScript approach used by current API schema TypeScript generators.
 
 ## Class-validator DTO — when `dtos: true`
 
@@ -122,29 +129,154 @@ properties include `@Expose()` so they remain compatible with class-transformer
 serializers that use `excludeExtraneousValues: true`. Do not hand-write parallel
 DTOs for schemas Kontract owns.
 
-## Swagger operation metadata — when `dtos: true`
+## Swagger operation metadata — when `swagger: true`
 
 ```typescript
 // contracts/recipes/http/swagger.ts
-import type { RecipeDto } from './dto/recipe.dto';
+import { RecipeDto } from './zod/recipe.contract';
 
 export const SWG_LIST_RECIPES = {
+  operationId: 'listRecipes',
   method: 'GET',
   path: '/recipes',
-  operationId: 'listRecipes',
+  summary: 'List recipes',
+  description: 'Returns recipes available to the caller.',
+  surface: 'public',
+  security: [],
   responseDto: RecipeDto,
+  responseDescription: 'Recipes returned.',
 } as const;
 ```
 
-Controllers can consume `SWG_*` metadata to keep operation IDs, paths, params,
-body DTOs, and response DTOs aligned with OpenAPI.
+`swagger: true` works with either `zod: true` or `dtos: true`. Generated
+metadata preserves operation IDs, paths, summaries, descriptions, params, query
+params, body DTOs, response DTOs, success response status, `x-kontract-surface`,
+and standard API schema `security`.
+
+## Generated `ApiDoc` decorator — when `swagger: true`
+
+```typescript
+// contracts/shared/http/decorators/api-doc.ts
+export function ApiDoc(operation: ApiDocOperation): MethodDecorator {
+  // Applies ApiOperation, ApiParam, ApiQuery, ApiBody, ApiResponse,
+  // ApiExtension('x-kontract-surface', ...), and Swagger security metadata.
+}
+```
+
+Controllers can consume `ApiDoc(SWG_*)` metadata to keep runtime Swagger output
+aligned with the API schema design contract:
+
+```typescript
+import { SWG_LIST_RECIPES } from 'SUMR Schemas module/recipes/http';
+import { ApiDoc } from 'SUMR Schemas module/shared/http';
+
+@Get()
+@ApiDoc(SWG_LIST_RECIPES)
+async listRecipes() {
+  // controller implementation
+}
+```
+
+Generated `ApiDoc` depends only on NestJS and `@nestjs/swagger`; it does not
+import Kontract at runtime.
+
+## NestJS-composed SDK — when `sdk: true`
+
+```typescript
+// contracts/recipes/http/sdk/api.ts
+import type * as Models from '../models';
+import type * as Enums from '../enums';
+import type { RequestConfig } from './runtime';
+
+export interface GetRecipeRequest {
+  recipeId: string;
+  status?: Enums.RecipeStatus;
+}
+
+export class RecipesFetchClient {
+  constructor(private readonly config: RequestConfig = {}) {}
+
+  async getRecipe(request: GetRecipeRequest): Promise<Models.Recipe> {
+    // fetch call generated from API schema operation metadata
+  }
+}
+```
+
+The composed SDK is for NestJS services that call another generated HTTP API.
+It emits `http/sdk/runtime.ts`, `http/sdk/api.ts`, and a local barrel, but it
+does not duplicate the target's models. Component schema references import from
+`http/models/`; component enum references import from `http/enums/`; inline
+operation enums remain local literal unions.
+
+Use standalone `typescript-fetch`, `typescript-axios`, or `typescript-angular`
+targets when a frontend/admin application should own a separate SDK package.
+
+## Frontend SDKs — React and Angular apps
+
+Standalone SDK targets are meant to remove hand-written API calls from consumer
+apps:
+
+- `typescript-fetch` emits a browser-compatible fetch client that can be used
+  from React, Vue, Svelte, plain TypeScript, or any runtime with `fetch`.
+- `typescript-axios` emits an axios client for apps that already standardize on
+  axios interceptors or shared axios instances.
+- `typescript-angular` emits an Angular service that uses `HttpClient` and
+  returns `Observable<T>`.
+
+Example React usage with the fetch SDK:
+
+```typescript
+import { ProductsFetchClient } from './generated/api';
+import { decodeProductApiJson } from './product-api-decoder';
+
+const api = new ProductsFetchClient({
+  baseUrl: '/api',
+  decodeJson: decodeProductApiJson,
+});
+
+export async function loadProduct(id: string) {
+  return api.getProduct({ id });
+}
+```
+
+Use an application-owned decoder such as a generated Zod schema, Valibot schema,
+or reviewed type guard at the `decodeJson` boundary. Do not cast unknown JSON in
+consumer code.
 
-## NATS contract — one `nats/index.ts` per AsyncAPI service
+Example Angular usage:
+
+```typescript
+import { Component } from '@angular/core';
+import { ProductsApiService } from './generated/api';
+
+@Component({ /* ... */ })
+export class ProductPage {
+  constructor(private readonly api: ProductsApiService) {}
+
+  save(name: string) {
+    return this.api.createProduct({ name });
+  }
+}
+```
+
+The generated SDK owns path interpolation, query serialization, request body
+encoding, response typing, and generated model imports. Consumers call methods
+instead of rewriting API URLs and `fetch`/`HttpClient` calls by hand.
+
+## NATS contract — one `nats/index.ts` per async schema service
 
 ```typescript
 // contracts/recipes/nats/index.ts
+import { RecipeStatusValues } from './enums';
+
+export * from './enums';
+
 export namespace Recipes {
-  export const CreateRecipeMessage = z.object({ name: z.string(), slug: z.string() });
+  export const CreateRecipeMessage = z.object({
+    name: z.string(),
+    slug: z.string(),
+    status: z.enum(RecipeStatusValues),
+  });
   export type CreateRecipeMessage = z.infer<typeof CreateRecipeMessage>;
   export type CreateRecipeMessageInput = z.input<typeof CreateRecipeMessage>;
 
@@ -159,18 +291,54 @@ export namespace Recipes {
 }
 ```
 
-- Namespace name comes from AsyncAPI `info.title`.
+- Namespace name comes from async schema `info.title`.
 - Every message yields a Zod const + `z.infer<>` type + `z.input<>` input type.
 - Subjects live in a single `SUBJECTS` const used directly by NestJS NATS.
 - Clients validate input with `.parse()` before sending.
 
+## NATS enum constants — `nats/enums/` per async schema service
+
+Named `components/schemas` entries that are string or number enums emit one
+constant file each, mirroring `http/enums/`:
+
+```typescript
+// contracts/recipes/nats/enums/recipe-status.enum.ts
+export const RecipeStatusValues = ['draft', 'published', 'archived'] as const;
+
+export type RecipeStatus = (typeof RecipeStatusValues)[number];
+
+export const RecipeStatusMap = {
+  Draft: 'draft',
+  Published: 'published',
+  Archived: 'archived',
+} as const;
+```
+
+- Message schemas reference shared string enum components as
+  `z.enum(<Name>Values)` instead of inlining literals, so wire enums have one
+  importable source of truth. This also works for multi-file specs and external
+  `$ref` fragments: bundling runs with `--xOrigin`, and the generator resolves
+  dereferenced copies back to their named component.
+- `nats/index.ts` re-exports the folder (`export * from './enums';`); import
+  constants from the service NATS barrel instead of deriving them from Zod
+  internals such as `Schema.shape.field.enum`.
+- Anonymous inline property enums stay inline `z.enum([...])`. Promote an enum
+  to `components/schemas` when services need its constants.
+- Number enums get constant files but stay inline literal unions in message
+  schemas (`z.enum` accepts strings only).
+
 ## Consuming in NestJS
 
 - Use `http/zod` `${Name}Dto` classes when you want `nestjs-zod` request/response
   validation.
-- Use `http/dto` classes and `http/swagger.ts` when a controller follows the
-  class-validator + Swagger metadata pattern.
+- Use per-service `http/swagger.ts` and the shared
+  `shared/http/decorators/api-doc.ts` helper when a controller should prove
+  runtime Swagger/API schema behavior from generated metadata.
+- Use `http/dto` classes when a controller follows the class-validator DTO
+  pattern.
 - Use `http/models` interfaces for type-only internal code.
+- Use `http/sdk` clients when a NestJS service needs a generated HTTP client
+  without a separate frontend SDK target.
 - Use the generated `*Client` classes and `SUBJECTS` for NATS — do not
   hand-write subjects or message shapes.
 - Each generated directory has a barrel `index.ts` for local aggregation only.

package/ai/modules/kontract/resources/openapi-sdk-generator-research.rf.md

@@ -0,0 +1,57 @@
+---
+category: reference
+name: openapi-sdk-generator-research
+title: API schema SDK Generator Research
+description: "Generator design inputs Kontract uses for current TypeScript SDK output."
+label: API schema SDK Generator Research
+when: Designing or reviewing Kontract SDK output, runtime helpers, config options, or model imports
+order: 46
+---
+
+# API schema SDK Generator Research
+
+Kontract reviews public API schema generator behavior to keep TypeScript SDK output
+familiar, small, and Bun-native without inheriting Java dependency chains or
+template systems.
+
+## Reviewed generator inputs
+
+- API schema Generator `typescript-fetch`:
+  <https://openapi-generator.tech/docs/generators/typescript-fetch/>
+- API schema Generator `typescript-axios`:
+  <https://openapi-generator.tech/docs/generators/typescript-axios/>
+- API schema Generator `typescript-angular`:
+  <https://openapi-generator.tech/docs/generators/typescript-angular/>
+- API schema Generator `typescript-nestjs`:
+  <https://openapi-generator.tech/docs/generators/typescript-nestjs/>
+- API schema TypeScript `openapi-fetch`:
+  <https://openapi-ts.dev/openapi-fetch/>
+
+## SDK generation standards
+
+- Keep SDK config options familiar where they are useful:
+  `useSingleRequestParameter`, `paramNaming`, `modelPropertyNaming`,
+  `enumPropertyNaming`, `stringEnums`, `enumUnknownDefaultCase`,
+  `sortParamsByRequiredFlag`, and `sortModelPropertiesByRequiredFlag`.
+- Prefer strict, readable output over broad template compatibility. Public
+  generators support many options, but that breadth often creates heavy runtime
+  helpers and harder-to-review generated code.
+- Treat query serialization as contract behavior. Array query params should stay
+  repeated keys unless the spec says otherwise.
+- Keep reserved-word handling in the SDK path. Wire names such as `from`,
+  `class`, and `default` must remain valid request keys while local variables
+  stay valid TypeScript identifiers.
+- Preserve API schema `additionalProperties` semantics in models and SDK types.
+- Fail before partial output for unsupported polymorphism rather than generating
+  missing or unsafe symbols.
+- Keep the fetch runtime small. `openapi-fetch` is a useful benchmark for a
+  low-runtime client; Kontract should avoid pulling in a heavy client runtime
+  unless a target explicitly asks for it.
+
+## Current product decisions
+
+- `typescript-nestjs` remains a server-contract generator. Its `sdk: true`
+  option adds a companion fetch client for NestJS consumers; it does not turn
+  the target into a standalone frontend package.
+- `typescript-fetch`, `typescript-axios`, and `typescript-angular` remain
+  standalone SDK targets with their own generated models.

package/ai/modules/kontract/resources/overview.md

@@ -1,111 +1,197 @@
 ---
 name: usage
 title: Kontract Usage
-description: "How to use the SUMR Kontract CLI to generate NestJS-ready TypeScript contracts from OpenAPI and AsyncAPI specs. Use when adding, changing, reviewing, validating, or generating API contracts."
-tags: [kontract, contracts, openapi, asyncapi, nestjs, codegen]
+description: "How to use the Kontract module in the SUMR CLI to review, validate, and generate API and microservice contracts from API and async schemas. Use when adding, changing, reviewing, validating, or generating API contracts, validation schemas, DTOs, SDK models, message subjects, or microservice message contracts."
+tags: [kontract, contracts, api, async, microservices, codegen]
 ---
 
 # Kontract Usage
 
-Kontract turns YAML API specs into typed, validated TypeScript: NestJS HTTP
-contracts, optional class-validator DTOs, Swagger operation metadata, frontend
-SDKs, NATS subjects, server interfaces, and clients — all from a single source
-of truth so implementations do not drift from the contract.
+Kontract generates the artifacts that keep APIs honest: validation schemas,
+SDKs, docs inputs, runtime evidence, and message contracts from API and async
+schemas.
 
 ## When to Use
 
-- Adding or editing an OpenAPI (`*.openapi.yml`) or AsyncAPI (`*.asyncapi.yml`) spec.
-- Reviewing newly written or updated `*.openapi.yml` / `*.asyncapi.yml` files
-  against Kontract best practices before validation or generation.
-- Refactoring duplicated schema fields into shared `$ref` components.
+- Adding or editing an API schema (`*.api.yml`) or async schema (`*.async.yml`).
+- Adding product-capability/API-surface schema modules with local `shared/`
+  folders only when concepts are reused.
+- Reviewing newly written or updated `*.api.yml` or `*.async.yml` files against
+  Kontract best practices before validation or generation.
+- Refactoring duplicated schema fields into shared `$ref` components or
+  `kontract.sets` map fragments.
 - Regenerating contracts after a spec change.
 - Validating specs before committing or in CI.
-- Wiring generated contracts into a NestJS microservice.
+- Wiring generated contracts into a service or client.
 
 ## Commands
 
 ```bash
 sumr kontract init        # activate Kontract AI guidance for this repo
-sumr kontract validate    # validate configured OpenAPI/AsyncAPI sources
-sumr kontract generate    # generate TypeScript contracts and SDKs
+sumr kontract config      # show or update guidance profile settings
+sumr kontract validate    # validate configured schema sources
+sumr kontract generate    # generate configured contract artifacts
 ```
 
-Useful flags:
+Activation also keeps local VS Code Material Icon associations in sync for
+Kontract API and async YAML source files.
 
-- `--source <name>` — limit to one configured source
-- `--target <name>` — limit to one configured target
-- `-c, --concurrency <n>` — max parallel workers
-- `--verbose` / `--quiet` — log level (`CI=true` implies quiet)
-- `generate` also accepts `-s, --specific <name>` to generate one service spec
-- `generate` also accepts `--clean` to remove selected generated outputs and the
-  selected Kontract bundle cache before regenerating
+For the full current option list, run the CLI help instead of duplicating flags
+across resources:
+
+```bash
+sumr kontract help
+sumr kontract <command> --help
+```
+
+Common workflows:
+
+```bash
+# Review guidance profile settings.
+sumr kontract config
+
+# Generate one selected service/schema.
+sumr kontract generate --source api --target backend --specific recipes
+
+# Clean and regenerate selected outputs.
+sumr kontract generate --source api --target backend --clean
+```
 
 ## The Model
 
+Choose the protocol scenario first:
+
+- API-only: HTTP roots and API schema components.
+- async-only: messaging roots, channels, messages, and payload schemas.
+- API + async: separate roots and protocol layers, with shared neutral
+  components only when meanings match, especially enums and scalar value objects.
+- Keep schemas local to the owning surface first. Promote to capability
+  `shared/` only after multiple surfaces reuse the same concept; promote to
+  `schema/shared/` only after multiple capabilities need it.
+
 ```text
 schema/
-  recipes.openapi.yml   →  contracts/recipes/http/
-  recipes.asyncapi.yml  →  contracts/recipes/nats/index.ts
+  recipes.api.yml        →  contracts/recipes/http/
+  recipes.async.yml       →  contracts/recipes/nats/index.ts
+  orders/
+    main.api.yml          →  contracts/orders/http/
+    public.api.yml        →  contracts/orders/http/
+    lifecycle.api.yml     →  contracts/orders/http/
+    shared/
+      enums.yml              →  reused by multiple orders surfaces
+      components.yml         →  reused by multiple orders surfaces
+  shared/
+    errors.yml               →  reused by multiple capabilities
 ```
 
-One source of truth (the YAML spec) → many generated, always-consistent
-TypeScript artifacts. Generated files are outputs: never hand-edit them — change
-the spec and regenerate.
+One schema source → many generated, always-consistent artifacts. Generated files
+are outputs: never hand-edit them — change the spec and regenerate.
 
 ## Configuration
 
 Kontract is configured from the repo's `sumr.yaml` under `kontract.sources`.
-Each source points at an input directory and one or more targets:
+Optional guidance under `kontract.guidance.profile` selects documentation and AI
+examples only; it does not change validation or generation. Each source points
+at an input directory and one or more targets:
 
 ```yaml
 kontract:
+  guidance:
+    profile:
+      apiStyle: pragmatic-rest
+      asyncStyle: command-event
+      schemaLayoutStyle: by-product-capability
   sources:
     - name: api
       input: schema
       targets:
-        - name: backend
+        - name: service-contracts
           output: backend/src/shared/models
           generator:
             type: typescript-nestjs
             zod: true
-            dtos: true
+            swagger: true
         - name: frontend
           output: frontend/src/shared/api
           generator:
             type: typescript-fetch
 ```
 
-For `typescript-nestjs`:
+For server-contract targets:
 
-- `zod: true` emits NestJS-Zod contracts under `http/zod/`.
-- `dtos: true` emits class-validator DTOs under `http/dto/` plus
+- `zod: true` emits runtime validation contracts under `http/zod/`.
+- `dtos: true` emits DTO classes under `http/dto/` plus compatibility
   `http/swagger.ts` operation metadata.
+- `swagger: true` emits per-service `http/swagger.ts` operation metadata and one
+  shared `shared/http/decorators/api-doc.ts` helper.
+- `sdk: true` emits a fetch-based `http/sdk/` client that reuses the same
+  `http/models/` and `http/enums/` generated for the target.
 - `dto: true` is accepted as a compatibility alias for `dtos: true`; prefer
   `dtos` in new config.
 - Framework-neutral model interfaces are emitted under `http/models/`.
 
-If a consuming repo is missing `http/dto/` or `http/swagger.ts`, first confirm
-the target has `dtos: true` (or `dto: true`) and that the installed
-`SUMR Kontract module` version contains DTO/swagger support.
+If a consuming repo is missing API metadata output, first confirm the target has
+`swagger: true`, and that the installed `SUMR Kontract module` version contains
+the metadata helper.
+
+## Generator Catalog
+
+| Category | Generator | Outputs |
+|---|---|---|
+| Server contracts | `typescript-nestjs` | Runtime validation contracts, DTOs, models, API metadata, optional SDK. |
+| Messaging | `asyncapi-nats` | Message subjects, message schemas, client/server interfaces. |
+| Client/SDK | `typescript-fetch` / `typescript-axios` / `typescript-angular` | Standalone TypeScript clients with bundled models. |
+| Model | `typescript-models` | Framework-model-only output. |
+
+Roadmap and future generator ideas live in `docs/internal/generator-roadmap.md`; exported AI resources describe current supported behavior only.
 
 ## Core Rules
 
 - Validate before you generate: `sumr kontract validate` then `sumr kontract generate`.
 - Treat everything under the generated `contracts/` output as read-only.
 - Keep specs the single source of truth; do not hand-write Zod/DTOs that Kontract owns.
-- After writing or updating any `*.openapi.yml` or `*.asyncapi.yml` file, review
-  the spec for duplicated concepts before generation.
+- After writing or updating any `*.api.yml` or `*.async.yml` file, review the
+  schema for duplicated concepts before generation.
+- Treat `summary`, `description`, `title`, parameter descriptions, response
+  descriptions, and message descriptions as user-facing copy when they appear in
+  docs, Swagger, Scalar, generated SDKs, or AI answers. Review changed copy
+  against the repo's copywriter standard before generation.
 - Design specs for reuse: shared parameters, scalar constraints, error responses,
   response envelope fragments, pagination metadata, schedule/time-slot shapes,
   and common config objects belong in shared components referenced with `$ref`.
-- See the spec layout and generated output references for the exact file shapes.
-- See the scope and splitting reference when a spec or Kontract source file
-  crosses the review thresholds, mixes domains, or needs domain/subdomain
-  structure.
-- See the schema reuse reference before adding repeated fields or reviewing a
-  generated diff with many near-identical DTO/model files.
-- See the OpenAPI generator lessons reference before changing query params,
+- Read `kontract.guidance.profile` before writing examples. Align path,
+  channel, component, and folder samples to the selected API, async, and schema
+  layout styles.
+- Inspect the actual source protocols before writing examples. For an
+  API-only repo, do not invent async schema roots, channel examples, or
+  `messages/` folders.
+- For an async-only repo, do not invent API schema roots, `paths/` folders, or
+  HTTP component examples.
+- When API schema and async schema both exist, keep protocol-specific layers separate
+  and share only schemas with identical meaning, especially enums,
+  scalar value objects, IDs, and slugs.
+- Keep simple API schema specs simple: use a focused root file with local
+  `components.schemas` first, and split into `paths/` fragments only when size,
+  ownership, or reuse pressure justifies it.
+- Start from the contract authoring overview before proposing schema files,
+  folder moves, or profile-specific examples.
+- Use compact YAML readability rules for editor navigation: section comments are
+  visual landmarks only, naming follows product meaning, and large files should
+  split by product capability or API surface before comments become a table of
+  contents.
+- See the authoring design-profile overview and axis references before choosing
+  or explaining HTTP, async schema, and schema layout examples.
+- See the authoring spec layout and generated output references for the exact
+  source and output file shapes.
+- See the authoring scope and splitting reference when a spec or Kontract source
+  file crosses the review thresholds, mixes product areas, or needs
+  capability/surface structure.
+- See the authoring schema reuse reference before adding repeated fields or
+  reviewing a generated diff with many near-identical DTO/model files.
+- See the API schema generation standards reference before changing query params,
   inline schemas, SDK serialization, or strict TypeScript compatibility rules.
+- See the API schema SDK generator research reference before changing SDK runtime
+  shape, target defaults, or model imports.
 - Use scoped flags (`--source`, `--target`, `--specific`) before `--clean` in a
   large consumer repo.
 - Warm generation is manifest-driven. Kontract stores per-service manifests in

package/ai/modules/kontract/resources/performance.rf.md

@@ -40,17 +40,17 @@ CLI generation does not spawn Biome once per generated file. It writes changed f
 
 ## Bundling strategy
 
-OpenAPI roots with no `$ref` or only internal `#/...` refs skip bundling. Roots with external
-refs use Redocly's OpenAPI core in-process, and safe bundles are cached under:
+API schema roots with no `$ref` or only internal `#/...` refs skip bundling. Roots with external
+refs use Redocly's API schema core in-process, and safe bundles are cached under:
 
 ```text
 .sumr-cache/kontract/bundles/<source>/source-cache/bundle-cache/
 ```
 
-The source-scoped bundle cache is shared across targets in the same source. A BCHQ-style source
-that generates backend NestJS contracts and frontend models should bundle each unchanged external
-OpenAPI root once, not once per target. Unsafe or ambiguous refs still fall back to target-scoped
-temporary bundling.
+The source-scoped bundle cache is shared across targets in the same source. A
+source that generates backend contracts and frontend models should bundle each
+unchanged external API schema root once, not once per target. Unsafe or ambiguous
+refs still fall back to target-scoped temporary bundling.
 
 Ambiguous multiline or remote refs take the safe path and regenerate/bundle rather than trusting a stale cache.
 
@@ -83,7 +83,7 @@ bun run tools perf generate --count=20 --concurrency=8 --mode=both --refs=extern
 
 Benchmark output stays under `.tmp/` and writes both `results.json` and `README.md` with phase timings, counters, and subprocess resource usage. Use `--refs=internal` to confirm bundling is skipped, and `--refs=external --targets=both` to confirm the shared bundle cache keeps cold-run in-process bundling at roughly one per schema root instead of one per target.
 
-Local signal after in-process OpenAPI bundling:
+Local signal after in-process API schema bundling:
 
 - `--count=1000 --refs=external --targets=both --concurrency=8`: cold `8.72s`, warm `0.83s`.
 - Warm manifests skipped all `2000` source/target work items and ran zero formatter/bundler subprocesses.

package/ai/modules/kontract/sumr.module.yaml

@@ -3,7 +3,7 @@ kind: CliModule
 metadata:
   name: kontract
   package: "@sumrco/cli"
-  description: Generate and validate API contract code
+  description: Generate and validate API contract artifacts
   owners:
     - team: "@sumr-org/kontract-team"
   tags:
@@ -20,8 +20,11 @@ spec:
     - name: init
       summary: Activate Kontract AI guidance for this workspace
       visibility: public
+    - name: config
+      summary: Show or update Kontract guidance profile settings
+      visibility: public
     - name: generate
-      summary: Generate TypeScript contracts from API specs
+      summary: Generate configured contract artifacts from API specs
       visibility: public
     - name: validate
       summary: Validate API specifications

package/ai/modules/mission/sumr.module.yaml

@@ -29,6 +29,9 @@ spec:
     - name: next
       summary: Show the next mission action
       visibility: public
+    - name: sync
+      summary: Fetch issue context and board status from the tracker
+      visibility: public
     - name: list
       summary: List missions
       visibility: public
@@ -44,6 +47,9 @@ spec:
     - name: report
       summary: Create a mission report
       visibility: public
+    - name: reopen
+      summary: Record a QA failure and drive a corrective cycle
+      visibility: public
     - name: block
       summary: Mark a mission as blocked
       visibility: public