@sumrco/cli 0.2.0 → 0.3.0

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

@@ -25,10 +25,12 @@ kontract:
             type: typescript-nestjs
             zod: true
             dtos: true
+            sdk: true
         - name: frontend
           output: frontend/src/shared/api
           generator:
             type: typescript-fetch
+            schemaMode: normalize
             modelPropertyNaming: original
             paramNaming: original
             stringEnums: true
@@ -56,21 +58,27 @@ Use `--target <name>` to scope generation to one target.
 
 ## Generator types
 
-| Type | Purpose |
-|---|---|
-| `typescript-nestjs` | Backend HTTP contracts for NestJS services. |
-| `asyncapi-nats` | NATS subjects, message schemas, server interfaces, and clients. |
-| `typescript-fetch` | TypeScript fetch SDK. |
-| `typescript-axios` | TypeScript axios SDK. |
-| `typescript-angular` | Angular SDK. |
-| `typescript-models` | Framework-neutral model-only output. |
+| Category | Type | Outputs |
+|---|---|---|
+| Server/framework | `typescript-nestjs` | Zod DTOs, class-validator DTOs, models, Swagger metadata, generated `ApiDoc` decorators. |
+| Messaging | `asyncapi-nats` | NATS subjects, message schemas, server interfaces, and clients. |
+| Client/SDK | `typescript-fetch` | TypeScript fetch SDK. |
+| Client/SDK | `typescript-axios` | TypeScript axios SDK. |
+| Client/SDK | `typescript-angular` | Angular SDK. |
+| Model | `typescript-models` | Framework-neutral model-only output. |
+
+Kontract is structured for more generator targets over time: runtime evidence,
+docs-ready OpenAPI artifacts, packaged API contracts, SDKs, mocks, contract
+tests, and breaking-change reports.
 
 ## `typescript-nestjs` options
 
 | Option | Output |
 |---|---|
 | `zod: true` | Emits `http/zod/*.contract.ts` with Zod schemas and `createZodDto()` classes. |
-| `dtos: true` | Emits `http/dto/*.dto.ts` plus `http/swagger.ts` operation metadata. |
+| `dtos: true` | Emits `http/dto/*.dto.ts`; also keeps the compatibility behavior of emitting `http/swagger.ts`. |
+| `swagger: true` | Emits per-service `http/swagger.ts` operation metadata and one shared `shared/http/decorators/api-doc.ts` helper for NestJS controllers. |
+| `sdk: true` | Emits a fetch-based `http/sdk/` client that reuses the target's `http/models/` and `http/enums/` types. |
 
 `dtos` is the canonical spelling. `dto: true` is accepted as a compatibility
 alias and is normalized internally to `dtos: true`.
@@ -78,15 +86,59 @@ alias and is normalized internally to `dtos: true`.
 Framework-neutral interfaces under `http/models/` and enums under `http/enums/`
 are emitted for OpenAPI object schemas regardless of the Zod/DTO flavor.
 
+Use `sdk: true` on a NestJS target when a backend service should call another
+generated HTTP API. Use a standalone `typescript-fetch`, `typescript-axios`, or
+`typescript-angular` target when a frontend/admin app should own its SDK output
+separately.
+
+## OpenAPI schema mode
+
+Standalone SDK and model targets default to `schemaMode: normalize`. In this
+mode, Kontract accepts real-world OpenAPI specs with inline operation request or
+response schemas, hoists those schemas into generated component names in memory,
+and emits named TypeScript models.
+
+Use `schemaMode: strict` when the source spec is product-owned and should fail
+fast unless operation request/response schemas use reusable `$ref` components.
+
+```yaml
+generator:
+  type: typescript-fetch
+  schemaMode: normalize # default for SDK/model targets
+```
+
+```yaml
+generator:
+  type: typescript-fetch
+  schemaMode: strict
+```
+
+Kontract still recommends reusable component schemas for owned APIs because they
+produce stable names and cleaner docs. Normalization exists so customers can
+generate SDKs from external or imperfect OpenAPI specs without rewriting the API
+description first.
+
+Use generic OpenAPI metadata for docs/runtime surfaces:
+
+```yaml
+x-kontract-surface: public
+security: []
+```
+
+`x-kontract-surface` values are consumer-defined strings. SUMR uses `public`,
+`app`, `admin`, and `internal`; another product might use `partner`, `mobile`,
+or `marketplace`.
+
 ## Common debugging cases
 
-### `http/dto/` or `http/swagger.ts` is missing
+### `http/dto/`, `http/swagger.ts`, or `shared/http/decorators/api-doc.ts` is missing
 
 Check both:
 
 1. The target config has `generator.type: typescript-nestjs` and `dtos: true`.
-   `dto: true` is also accepted, but prefer `dtos` in new config.
-2. The installed `SUMR Kontract module` version includes DTO/swagger support.
+   `dto: true` is also accepted, but prefer `dtos` in new config. If you use
+   Zod without class-validator DTOs, set `swagger: true` explicitly.
+2. The installed `SUMR Kontract module` version includes Swagger/ApiDoc support.
 
 If two configs generate identical output and both miss `dto/` + `swagger.ts`,
 the likely issue is the generator version being executed, not the consumer
@@ -97,6 +149,13 @@ repo's config.
 Check that the NestJS target has `zod: true` or that Zod generation has not been
 explicitly disabled.
 
+### `http/sdk/` is missing
+
+Check that the NestJS target has `sdk: true`. Standalone SDK generator targets
+emit service folders with `models.ts`, `runtime.ts`, and `api.ts`; the NestJS
+composed SDK emits under `http/sdk/` and imports types from existing
+`http/models/` and `http/enums/`.
+
 ### Generated files are stale
 
 Run a scoped clean generation:

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

@@ -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';
@@ -122,29 +129,149 @@ 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 OpenAPI `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 OpenAPI 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 OpenAPI 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';
+
+const api = new ProductsFetchClient({
+  baseUrl: '/api',
+  decodeJson: (value) => value as never,
+});
+
+export async function loadProduct(id: string) {
+  return api.getProduct({ id });
+}
+```
+
+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 AsyncAPI 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>;
 
@@ -164,13 +291,49 @@ export namespace Recipes {
 - 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 AsyncAPI 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/OpenAPI 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/language-sdk-generator-extension.rf.md

@@ -0,0 +1,62 @@
+---
+category: reference
+name: language-sdk-generator-extension
+title: Language SDK Generator Extension
+description: "How Kontract should add future non-TypeScript SDK generators such as Java or Rust."
+label: Language SDK Generator Extension
+when: Researching or implementing a new Kontract SDK generator for another language
+order: 47
+---
+
+# Language SDK Generator Extension
+
+Kontract can add Java, Rust, or other SDK generators, but only as explicit
+generator types after research and tests prove the output is useful.
+
+## Current support
+
+Implemented generators:
+
+- `typescript-nestjs`
+- `asyncapi-nats`
+- `typescript-fetch`
+- `typescript-axios`
+- `typescript-angular`
+- `typescript-models`
+
+Java and Rust are not implemented yet. Config such as `type: java` or
+`type: rust` must fail until a real generator exists.
+
+## Add a new language generator
+
+Use this sequence:
+
+1. Research mature public generators for the target language and record lessons
+   in `resources/`.
+2. Add the generator type to `src/types/contracts.types.ts`.
+3. Add config parsing and allowed options in `src/lib/sumr-yaml.ts`.
+4. Add dependency warnings in `src/cli/dependency-check.ts` only when generated
+   output requires runtime packages in the consumer repo.
+5. Add a generator implementation under `src/generators/openapi/<language>/` or
+   a shared SDK emitter if the language can reuse one.
+6. Wire generation planning in `src/cli/generate-plan.ts`.
+7. Add tests that prove config parsing, output shape, unsafe-schema failures,
+   and generated file roots.
+8. Update `README.md`, `docs/**`, `resources/**`, and regenerate AI resources
+   with `bun run sync`.
+
+## Test coverage required
+
+Every generator must have at least:
+
+- a config parsing test;
+- a direct generation test for expected root files;
+- an edge-case test for reserved names or language keywords;
+- query array serialization coverage for HTTP SDKs;
+- enum and `additionalProperties` coverage where the language supports them;
+- a rejection test for unsupported schema features such as unsafe polymorphism;
+- a catalog coverage test so the documented generator list and implemented list
+  stay aligned.
+
+Do not add a generator type first and fill behavior later. Unsupported language
+targets should stay rejected until they can generate useful, validated output.

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

@@ -0,0 +1,59 @@
+---
+category: reference
+name: openapi-sdk-generator-research
+title: OpenAPI SDK Generator Research
+description: "Public generator lessons Kontract applies when evolving TypeScript SDK output."
+label: OpenAPI SDK Generator Research
+when: Designing or reviewing Kontract SDK output, runtime helpers, config options, or schema preview work
+order: 46
+---
+
+# OpenAPI SDK Generator Research
+
+Kontract learns from public OpenAPI generators without inheriting their runtime
+shape, Java dependency chain, or template system.
+
+## References reviewed
+
+- OpenAPI Generator `typescript-fetch`:
+  <https://openapi-generator.tech/docs/generators/typescript-fetch/>
+- OpenAPI Generator `typescript-axios`:
+  <https://openapi-generator.tech/docs/generators/typescript-axios/>
+- OpenAPI Generator `typescript-angular`:
+  <https://openapi-generator.tech/docs/generators/typescript-angular/>
+- OpenAPI Generator `typescript-nestjs`:
+  <https://openapi-generator.tech/docs/generators/typescript-nestjs/>
+- OpenAPI TypeScript `openapi-fetch`:
+  <https://openapi-ts.dev/openapi-fetch/>
+
+## Lessons for Kontract
+
+- 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 OpenAPI `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.
+
+## 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.
+- Schema preview HTML needs a separate research spike because bundle size,
+  license, and static-output feasibility affect whether the feature belongs in
+  Kontract, Website, or both.

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

@@ -1,22 +1,24 @@
 ---
 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."
+description: "How to use the SUMR Kontract CLI to generate configured contract artifacts from OpenAPI and AsyncAPI sources. Use when adding, changing, reviewing, validating, or generating API contracts."
 tags: [kontract, contracts, openapi, asyncapi, nestjs, 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,
+framework decorators, SDKs, docs inputs, runtime evidence, and message contracts
+from OpenAPI and AsyncAPI sources.
 
 ## 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.
+- Adding domain/subdomain specs with the neutral `*.schema.yml` suffix when the
+  YAML marker (`openapi:` or `asyncapi:`) should decide the protocol.
+- Reviewing newly written or updated `*.openapi.yml`, `*.asyncapi.yml`, or
+  `*.schema.yml` files against Kontract best practices before validation or
+  generation.
 - Refactoring duplicated schema fields into shared `$ref` components.
 - Regenerating contracts after a spec change.
 - Validating specs before committing or in CI.
@@ -27,7 +29,7 @@ of truth so implementations do not drift from the contract.
 ```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 generate    # generate configured contract artifacts
 ```
 
 Useful flags:
@@ -46,11 +48,14 @@ Useful flags:
 schema/
   recipes.openapi.yml   →  contracts/recipes/http/
   recipes.asyncapi.yml  →  contracts/recipes/nats/index.ts
+  recipes/
+    catalog.schema.yml  →  contracts/recipes/http/
+    events.schema.yml   →  contracts/recipes/nats/index.ts
 ```
 
-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 OpenAPI or AsyncAPI source → many generated, always-consistent artifacts.
+Generated files are outputs: never hand-edit them — change the spec and
+regenerate.
 
 ## Configuration
 
@@ -68,7 +73,7 @@ kontract:
           generator:
             type: typescript-nestjs
             zod: true
-            dtos: true
+            swagger: true
         - name: frontend
           output: frontend/src/shared/api
           generator:
@@ -79,25 +84,69 @@ For `typescript-nestjs`:
 
 - `zod: true` emits NestJS-Zod contracts under `http/zod/`.
 - `dtos: true` emits class-validator DTOs under `http/dto/` plus
-  `http/swagger.ts` operation metadata.
+  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 for NestJS controllers.
+- `sdk: true` emits a fetch-based `http/sdk/` client that reuses the same
+  `http/models/` and `http/enums/` generated for the NestJS 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 `http/swagger.ts` or
+`shared/http/decorators/api-doc.ts`, first confirm the target has
+`swagger: true`, and that the installed `SUMR Kontract module` version contains
+Swagger/ApiDoc support.
+
+## Generator Catalog
+
+### Current
+
+| Category | Generator | Outputs |
+|---|---|---|
+| Server/framework | `typescript-nestjs` | Zod DTOs, class-validator DTOs, models, Swagger metadata, generated `ApiDoc`, optional SDK. |
+| Messaging | `asyncapi-nats` | NATS subjects, message schemas, client/server interfaces. |
+| Client/SDK | `typescript-fetch` / `typescript-axios` / `typescript-angular` | Standalone TypeScript clients with bundled models. |
+| Model | `typescript-models` | Framework-neutral model-only output. |
+
+### Near-term
+
+| Category | Generator | Outputs |
+|---|---|---|
+| Runtime evidence | NestJS Swagger extraction | OpenAPI JSON from real Nest routes. |
+| API package | API contracts package | Packaged OpenAPI artifacts. |
+| Docs | docs-ready OpenAPI | Filtered public/app/admin docs inputs. |
+| Preview | schema preview HTML | Static API reference output after Scalar/free-option research. |
+| SDK | TypeScript SDK | Public/app/admin clients. |
+| Quality | contract tests | Route/spec drift and response-shape tests. |
+
+### Future
+
+- Java, Rust, Python, Go, and Swift SDKs.
+- Postman or Bruno collections.
+- mock servers.
+- breaking-change and OpenAPI diff reports.
+- API changelog artifacts.
+- docs snippets and examples.
 
 ## 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 `*.openapi.yml`, `*.asyncapi.yml`, or
+  `*.schema.yml` file, review the spec 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. Route changed copy
+  through the repo's copywriter/microcopy 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`.
+- Use compact YAML readability rules for editor navigation: section comments are
+  visual landmarks only, naming follows domain meaning, and large files should
+  split by domain/subdomain before comments become a table of contents.
 - 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
@@ -106,6 +155,10 @@ the target has `dtos: true` (or `dto: true`) and that the installed
   generated diff with many near-identical DTO/model files.
 - See the OpenAPI generator lessons reference before changing query params,
   inline schemas, SDK serialization, or strict TypeScript compatibility rules.
+- See the OpenAPI SDK generator research reference before changing SDK runtime
+  shape, target defaults, model imports, or preview-docs direction.
+- See the language SDK generator extension reference before adding Java, Rust,
+  or any non-TypeScript SDK target.
 - Use scoped flags (`--source`, `--target`, `--specific`) before `--clean` in a
   large consumer repo.
 - Warm generation is manifest-driven. Kontract stores per-service manifests in