@sumrco/cli 0.2.1 → 0.3.0

package/ai/modules/kontract/resources/schema-reuse.rf.md

@@ -17,6 +17,10 @@ operations or services, define it once and reference it with `$ref`.
 This reduces drift in the source specs immediately. It also gives Kontract a
 clear path to emit more shared generated code as the generator evolves.
 
+Before extracting or naming a shared component, choose a name from the domain
+language. Shared names should stay specific enough for generated DTO/model/SDK
+symbols.
+
 ## What to share
 
 Prefer shared components for concepts that mean the same thing everywhere:
@@ -80,6 +84,83 @@ content:
       $ref: ../shared/common.yml#/components/schemas/ImageMimeType
 ```
 
+## Sharing schemas across OpenAPI and AsyncAPI fragments
+
+When one domain has both HTTP and messaging contracts, keep protocol entrypoints
+separate and share only neutral business schemas.
+
+```text
+schema/
+  bookstore/
+    bookstore.openapi.yml
+    bookstore.asyncapi.yml
+    paths/books.yml
+    messages/books.yml
+    models/shared.yml
+    models/books.yml
+```
+
+Good shared fragment:
+
+```yaml
+# schema/bookstore/models/shared.yml
+BookSlug:
+  type: string
+  minLength: 1
+  maxLength: 120
+  pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+
+PaginationMeta:
+  $ref: ../../shared/common.yml#/components/schemas/PaginationMeta
+```
+
+OpenAPI can use it through path and response fragments:
+
+```yaml
+# schema/bookstore/paths/books.yml
+paths:
+  /books/{bookSlug}:
+    parameters:
+      - name: bookSlug
+        in: path
+        required: true
+        schema:
+          $ref: ../models/shared.yml#/BookSlug
+    get:
+      operationId: getBook
+      responses:
+        "200":
+          description: Book detail.
+          content:
+            application/json:
+              schema:
+                $ref: ../models/books.yml#/Book
+```
+
+AsyncAPI can use the same payload schema from a message fragment:
+
+```yaml
+# schema/bookstore/messages/books.yml
+messages:
+  GetBookQuery:
+    payload:
+      $ref: ../models/books.yml#/GetBookQuery
+  BookReply:
+    payload:
+      $ref: ../models/books.yml#/Book
+```
+
+Keep protocol-specific pieces out of `models/`:
+
+- OpenAPI paths, parameters, request bodies, responses → `paths/` or
+  `components/`.
+- AsyncAPI channels, operations, messages → `messages/`.
+- Payload objects, enums, scalars, pagination, and reusable business shapes →
+  `models/`.
+
+This keeps HTTP DTOs, NATS zod messages, and generated models aligned without
+making either protocol depend on the other's metadata.
+
 ## Response envelopes
 
 If every endpoint repeats the same envelope fields, do not retype them in every
@@ -211,6 +292,8 @@ components when:
   needs;
 - a request DTO and response DTO intentionally differ, even if fields overlap;
 - names would become vague (`CommonThing`, `BaseData`, `GenericConfig`);
+- the reusable name would hide a real product term, such as using `Collection`
+  when collections are a domain concept in the product;
 - sharing would force unrelated teams/domains to coordinate every future change.
 
 A good shared component has a clear product meaning and a stable owner.

package/ai/modules/kontract/resources/scope-and-splitting.rf.md

@@ -72,6 +72,10 @@ Split or optimize before adding more content when a file shows any of these:
 Do not split only by line count. First identify the product or technical
 boundary that gives the new file a stable name and owner.
 
+Visual section comments can help readers navigate a healthy file, but they are
+not a substitute for splitting an oversized or mixed-domain spec. If comments
+start acting like a table of contents, split by domain/subdomain instead.
+
 ## Domain and subdomain spec structure
 
 Use directory nesting to communicate product ownership. The path should answer
@@ -93,14 +97,51 @@ schema/
     stations.openapi.yml
     prep-jobs.asyncapi.yml
     inventory.asyncapi.yml
+  bookstore/
+    bookstore.openapi.yml       # OpenAPI root entrypoint
+    bookstore.asyncapi.yml      # AsyncAPI root entrypoint
+    paths/
+      books.yml                 # HTTP paths by subdomain
+      authors.yml
+    messages/
+      books.yml                 # NATS channels/messages by subdomain
+      authors.yml
+    models/
+      shared.yml                # model fragments shared by both roots
+      books.yml
+      authors.yml
 ```
 
+When a folder already carries the domain name, prefer `*.schema.yml` for
+subdomain surfaces that should generate as one domain package:
+
+```text
+schema/
+  recipes/
+    catalog.schema.yml          # openapi: 3.0.3
+    publishing.schema.yml       # asyncapi: 3.0.0
+    inventory.schema.yml        # asyncapi: 3.0.0
+```
+
+Kontract content-detects the protocol marker and groups those files under the
+first folder (`recipes` in this example). Use explicit `*.openapi.yml` or
+`*.asyncapi.yml` when each nested file should remain an independently generated
+service path.
+
+When one domain should keep a single generated package but the contract is too
+large for one file, keep the explicit root files and split the internals into
+plain `.yml` fragments. This mirrors Redocly-style authoring: roots are the
+public entrypoints, fragments are implementation detail, and schemas can be
+shared by OpenAPI and AsyncAPI only when the business shape is protocol-neutral.
+
 Guidelines:
 
 - Keep one entry-point spec per bounded API surface, not one giant file per
   repo.
 - Split by product meaning: `recipes`, `ingredients`, `orders`, `jobs`, or
   `inventory`, not by generic words like `common`, `misc`, or `helpers`.
+- Use short section markers only as editor landmarks inside a file that is still
+  small enough to review.
 - Use `schema/shared/` only for cross-domain concepts with stable semantics and
   an obvious owner.
 - Prefer domain-local shared components when a concept is reused only inside one

package/ai/modules/kontract/resources/spec-layout.rf.md

@@ -17,19 +17,49 @@ directory (default `schema/`).
 schema/
   recipes.openapi.yml           ← one OpenAPI doc per service/domain
   recipes.asyncapi.yml          ← one AsyncAPI doc per service/domain
+  recipes.schema.yml            ← neutral suffix; detected by openapi:/asyncapi:
   base.yml                      ← shared components, referenced via $ref
+  bookstore/
+    bookstore.openapi.yml       ← root entrypoint
+    bookstore.asyncapi.yml      ← root entrypoint
+    paths/catalog.yml           ← OpenAPI path fragments
+    messages/events.yml         ← AsyncAPI channel/message fragments
+    models/shared.yml          ← protocol-neutral model fragments
 ```
 
 ## Rules
 
 - OpenAPI specs end in `*.openapi.yml` / `*.openapi.yaml`.
 - AsyncAPI specs end in `*.asyncapi.yml` / `*.asyncapi.yaml`.
+- Use `*.schema.yml` / `*.schema.yaml` when a domain folder already makes the
+  protocol obvious less useful than the business surface name. Kontract reads
+  the file marker and treats `openapi:` as OpenAPI and `asyncapi:` as AsyncAPI.
 - Discovery is recursive; `base.yml` is skipped as an entry point.
 - Service output paths mirror nested spec paths under the configured source
   input directory.
+- A root `*.openapi.yml` or `*.asyncapi.yml` may reference plain `.yml`
+  fragments for paths, messages, parameters, and schemas. Kontract bundles the
+  root before generation when it finds external `$ref` links.
+- OpenAPI and AsyncAPI roots may share neutral model fragments when the shapes
+  mean the same thing for HTTP and messaging. Keep protocol-specific path,
+  operation, parameter, channel, and message metadata in separate fragments.
+- Nested `*.schema.yml` files are grouped by their first folder. This supports a
+  DDD layout where the folder is the domain and each file is a subdomain surface:
+
+  ```text
+  schema/
+    recipes/
+      catalog.schema.yml        ← OpenAPI
+      publishing.schema.yml     ← AsyncAPI
+  ```
+
+  Both files generate under `contracts/recipes/`.
 - Use nested domain/subdomain paths when one root file would mix independently
   owned API surfaces; see the scope and splitting reference for line-count
   thresholds and naming rules.
+- Use comments only as editor navigation markers. Comments may label groups such
+  as `Catalog paths` or `Response schemas`, but they must not explain endpoint
+  behavior or replace `summary` / `description`.
 - Share common schemas through `$ref` into `base.yml`. Do **not** duplicate
   schemas across specs and do **not** merge by hand-mutating parsed JSON.
 - Prefer a `schema/shared/` folder for cross-domain components such as common
@@ -41,11 +71,174 @@ schema/
   with CLI fallback, AsyncAPI via `@asyncapi/cli bundle`); keep `$ref` paths
   repo-relative.
 
+## Split root-entrypoint layout
+
+Use this layout when one product domain should generate as one contract package,
+but the root files are getting too large:
+
+```text
+schema/
+  bookstore/
+    bookstore.openapi.yml
+    bookstore.asyncapi.yml
+    components/
+      parameters.yml
+    paths/
+      books.yml
+      authors.yml
+    messages/
+      books.yml
+      authors.yml
+    models/
+      shared.yml
+      books.yml
+      authors.yml
+```
+
+The root files stay small and readable. Fragment files are plain `.yml` because
+they are not standalone OpenAPI or AsyncAPI documents.
+
+If a root file needs many visual section markers to stay readable, split the
+internals into domain/subdomain fragments before adding more comments.
+
+```yaml
+# schema/bookstore/bookstore.openapi.yml
+openapi: 3.0.3
+info:
+  title: Bookstore Contracts
+  version: 1.0.0
+paths:
+  /books:
+    $ref: ./paths/books.yml#/paths/~1books
+components:
+  schemas:
+    Book:
+      $ref: ./models/books.yml#/Book
+    PaginatedBooks:
+      $ref: ./models/books.yml#/PaginatedBooks
+```
+
+```yaml
+# schema/bookstore/paths/books.yml
+paths:
+  /books:
+    get:
+      operationId: listBooks
+      responses:
+        "200":
+          description: Paginated book list.
+          content:
+            application/json:
+              schema:
+                $ref: ../models/books.yml#/PaginatedBooks
+```
+
+```yaml
+# schema/bookstore/bookstore.asyncapi.yml
+asyncapi: 3.0.0
+info:
+  title: Bookstore
+  version: 1.0.0
+channels:
+  listBooks:
+    $ref: ./messages/books.yml#/channels/listBooks
+  listBooksReply:
+    $ref: ./messages/books.yml#/channels/listBooksReply
+operations:
+  listBooks:
+    $ref: ./messages/books.yml#/operations/listBooks
+components:
+  messages:
+    ListBooksQuery:
+      $ref: ./messages/books.yml#/messages/ListBooksQuery
+    PaginatedBooksReply:
+      $ref: ./messages/books.yml#/messages/PaginatedBooksReply
+  schemas:
+    ListBooksQuery:
+      $ref: ./models/books.yml#/ListBooksQuery
+    PaginatedBooks:
+      $ref: ./models/books.yml#/PaginatedBooks
+```
+
+```yaml
+# schema/bookstore/messages/books.yml
+channels:
+  listBooks:
+    address: qry.bookstore.books.list
+    messages:
+      listBooksQuery:
+        $ref: ./books.yml#/messages/ListBooksQuery
+  listBooksReply:
+    address: qry.bookstore.books.list.reply
+    messages:
+      paginatedBooksReply:
+        $ref: ./books.yml#/messages/PaginatedBooksReply
+operations:
+  listBooks:
+    action: receive
+    channel:
+      $ref: "#/channels/listBooks"
+    messages:
+      - $ref: "#/channels/listBooks/messages/listBooksQuery"
+    reply:
+      channel:
+        $ref: "#/channels/listBooksReply"
+      messages:
+        - $ref: "#/channels/listBooksReply/messages/paginatedBooksReply"
+messages:
+  ListBooksQuery:
+    payload:
+      $ref: ../models/books.yml#/ListBooksQuery
+  PaginatedBooksReply:
+    payload:
+      $ref: ../models/books.yml#/PaginatedBooks
+```
+
+Shared schemas can be referenced by both roots when they carry the same business
+meaning:
+
+```yaml
+# schema/bookstore/models/shared.yml
+BookSlug:
+  type: string
+  minLength: 1
+  maxLength: 120
+  pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+```
+
+```yaml
+# schema/bookstore/models/books.yml
+Book:
+  type: object
+  required: [id, slug, title]
+  properties:
+    id:
+      type: string
+      format: uuid
+    slug:
+      $ref: ./shared.yml#/BookSlug
+    title:
+      type: string
+      minLength: 1
+```
+
+Do not put graph, routing, or protocol behavior into shared model fragments.
+Share only business payload shapes.
+
 ## OpenAPI authoring rules
 
 - Put reusable HTTP payloads in `components.schemas`.
 - Operation request/response schemas should reference components with `$ref`.
   Inline operation schemas are rejected so generated DTO/model names stay stable.
+- Use operation `summary` to name the action. Use `description` to explain
+  outcome, scope, caller context, constraints, or next steps; do not repeat the
+  summary in sentence form.
+- Avoid tag echo. If the API docs already show a tag such as `Playbook` or
+  `Accounts`, omit that word from the summary unless the operation would become
+  ambiguous.
+- Route public or developer-facing `summary`, `description`, parameter, schema,
+  and response text through the repo's copywriter/microcopy standard before
+  validating.
 - Prefer explicit object schemas over anonymous nested shapes when a payload is
   shared by multiple operations.
 - If multiple responses repeat the same envelope fields, extract the envelope
@@ -67,3 +260,16 @@ schema/
 
 Run `sumr kontract validate` after any layout change to confirm specs still
 resolve before generating.
+
+## AsyncAPI copy rules
+
+AsyncAPI `title`, `summary`, and `description` fields can appear in generated
+docs, SDK docs, and AI answers. Write them with the same copy gate as OpenAPI:
+
+- `title` names the message or operation.
+- `summary` states the job or event in one concise sentence.
+- `description` adds context only when the outcome, constraint, or event
+  semantics need more detail.
+- Do not repeat the channel, operation id, schema key, or title in the summary.
+- Keep transport terms such as subject, payload, NATS, command, and query only
+  when the reader needs that exact implementation detail.

package/ai/modules/kontract/resources/team-members/contract-author.tm.md

@@ -2,8 +2,9 @@
 category: team-member
 name: contract-author
 title: Contract Author
-description: "Owns API spec authoring and Kontract regeneration discipline: edits OpenAPI/AsyncAPI specs, validates, regenerates, and keeps generated contracts consistent without hand-editing outputs."
+description: "Owns API spec authoring and Kontract regeneration discipline. Use when changing OpenAPI/AsyncAPI specs, validating, regenerating, or reviewing generated contract diffs."
 modelTier: reasoning
+access: write
 channels:
   codex:
     sandbox_mode: workspace-write
@@ -16,18 +17,25 @@ and let Kontract generate the TypeScript — you never hand-write or hand-patch
 generated contracts.
 
 Apply the generated **sumr-kontract-usage** skill, plus the configuration,
-spec-layout, schema-reuse, scope-and-splitting, and generated-output
-references, before acting.
+spec-layout, schema-reuse, scope-and-splitting, and generated-output references,
+before acting.
 
 ## Responsibilities
 
 - Translate API requirements into OpenAPI/AsyncAPI specs under `schema/`.
 - After writing or updating any `*.openapi.yml` / `*.asyncapi.yml` file, review
   it against Kontract reuse, layout, and generation rules before validating.
+- Route changed public or developer-facing summaries, descriptions, parameter
+  descriptions, response descriptions, message titles, and message summaries
+  through the repo's copywriter/microcopy standard before generation.
 - Keep shared shapes in shared component files and reference them with `$ref`.
 - Keep specs domain-aligned and reviewable: use domain/subdomain paths, split
   oversized files at documented thresholds, and avoid generic `common` buckets
   for unrelated concepts.
+- Use comments only as visual editor landmarks. Do not explain endpoint behavior
+  with comments; use OpenAPI/AsyncAPI descriptions for that.
+- Name schemas from domain meaning first, using operation-specific response
+  names only when the shape belongs to one operation.
 - Proactively spot duplicated envelope fields, pagination metadata, error
   schemas, path/query params, regex scalar constraints, schedules, and config
   objects before generating.

package/ai/modules/kontract/resources/workflows/contract-change.wf.md

@@ -2,7 +2,9 @@
 category: workflow
 name: contract-change
 title: Contract Change
-description: "Guides an AI agent through safely changing an API spec and regenerating Kontract contracts."
+description: "Guides an AI agent through safely changing an API spec and regenerating Kontract contracts. Use when an API surface changes and generated contracts must follow."
+modelTier: coding
+access: write
 ---
 
 # Contract Change

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:
@@ -21,7 +21,7 @@ spec:
       summary: Activate Kontract AI guidance for this workspace
       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