@sumrco/cli 0.2.1 → 0.3.1

package/ai/modules/kontract/resources/authoring/design-profile/overview.md

@@ -0,0 +1,64 @@
+---
+name: design-profile
+title: Contract Design Profile
+description: "How Kontract profile values guide HTTP, async schema, and schema directory examples without changing generation."
+tags: [kontract, design-profile, http, asyncapi, schema-layout]
+---
+
+# Contract Design Profile
+
+`sumr kontract init` writes a guidance-only profile to `sumr.yaml`.
+`sumr kontract config` shows or updates it later without hand-editing YAML:
+
+```yaml
+kontract:
+  guidance:
+    profile:
+      apiStyle: pragmatic-rest
+      asyncStyle: command-event
+      schemaLayoutStyle: by-product-capability
+```
+
+The profile guides docs and AI examples. It does not change generator output,
+API schema validation, async schema validation, or application architecture.
+
+```bash
+sumr kontract config
+sumr kontract config --api-style rpc-action --async-style cloud-events
+```
+
+## Profile axes
+
+| Config key | Reader-facing meaning | Axis reference |
+|---|---|---|
+| `apiStyle` | API path and component example style. | `api-styles.rf.md` |
+| `asyncStyle` | async schema channel/address and message example style. | `async-styles.rf.md` |
+| `schemaLayoutStyle` | Schema layout style for schema file and folder examples. | `schema-layout-styles.rf.md` |
+
+Read the axis-specific references before writing examples. Do not infer file
+moves from the profile alone: the profile is guidance-only.
+
+## CLI and YAML names
+
+Use `schemaLayoutStyle` in `sumr.yaml` and `--schema-layout-style` in the CLI.
+Do not use organization wording for this axis.
+
+## Safe interpretation
+
+- HTTP examples must follow `apiStyle`.
+- async schema examples must follow `asyncStyle`, but only when the repo has
+  async schema sources/targets or the user asks for messaging contracts.
+- Schema file/folder examples must follow `schemaLayoutStyle`, described as the
+  schema layout style.
+- If the repo is API-only, keep examples API-only; do not add
+  `*.async.yml`, channels, messages, or `messages/` folders only because the
+  profile has an `asyncStyle` default.
+- If the repo is async-only, keep examples async-only; do not add
+  `*.api.yml`, paths, parameters, or HTTP responses only because the profile
+  has an `apiStyle` default.
+- If the repo has both protocols, keep API schema and async schema roots and
+  protocol-specific folders separate. Share only components with
+  identical meaning, especially enums and scalar value objects.
+- If an agent recommends moving root specs, it must call out that generated
+  output namespaces/import paths can change because Kontract mirrors root spec
+  paths under the configured source input directory.

package/ai/modules/kontract/resources/authoring/design-profile/schema-layout-styles.rf.md

@@ -0,0 +1,356 @@
+---
+category: reference
+name: schema-layout-styles
+title: Schema Layout Style Examples
+description: "Schema layout styles for Kontract profile examples, including canonical folder trees and generated-output migration warnings."
+label: Schema Layout Styles
+when: Choosing or explaining `kontract.guidance.profile.schemaLayoutStyle`, schema folder layout, root spec locations, or generated namespace impact
+order: 18
+---
+
+# Schema Layout Style Examples
+
+Use `kontract.guidance.profile.schemaLayoutStyle` to choose the schema layout
+examples an agent should produce. Use the same wording in user-facing guidance.
+
+This is guidance only; it does not move files or change generation by itself.
+
+## Style summary
+
+| Style | Choose this when | Sample layout |
+|---|---|---|
+| `by-product-capability` | A product capability owns one or more focused contract surfaces; it may be API-only. | `schema/recipes/recipes.api.yml`, `schema/recipes/catalog.api.yml` |
+| `by-api-surface` | Public, partner, admin, or internal surfaces are released separately. | `schema/public.api.yml`, `schema/admin.api.yml` |
+| `by-service-owner` | Teams generate contracts by deployable service ownership. | `schema/catalog-service/catalog.api.yml` |
+| `by-resource-area` | Specs are easiest to review by stable resource area. | `schema/recipes/recipes.api.yml`, `schema/ingredients/ingredients.api.yml` |
+| `by-workflow` | A workflow spans several resources and needs one contract owner. | `schema/checkout/checkout.api.yml` |
+| `by-message-family` | Messaging files are owned by command, event, or query family. | `schema/events/recipe-events.async.yml` |
+| `mixed` | A repo has intentional legacy or multi-team layout differences. | Document the style per folder before adding examples. |
+
+## Canonical folder trees
+
+Use these trees as the source of truth when an agent proposes schema files,
+folder moves, or examples. Do not combine two schema layout styles unless
+`schemaLayoutStyle: mixed`.
+
+## Protocol-aware rule
+
+First inspect the configured source directory and targets. If the repo currently
+contains only API schema roots, show API-only folder trees and examples. Do not
+add async schema roots, channels, message folders, or NATS naming samples unless the
+user asks for messaging contracts or the repo already has async schema files.
+
+Use one of these three protocol scenarios before choosing a layout tree:
+
+1. **API-only** — HTTP roots, path fragments, parameters, responses, and
+   `components.schemas` only.
+2. **async-only** — messaging roots, channels, operations, messages, and
+   message payload schemas only.
+3. **API + async** — keep API schema and async schema roots and protocol
+   layers separate. Share only components with identical meaning across
+   both protocols, especially enums, scalar value objects, IDs, slugs, and other
+   reusable payload shapes.
+
+Do not share API schema paths, parameters, responses, async schema channels,
+operations, or messages across protocols. Those are protocol-specific layers.
+
+### `by-product-capability`
+
+The first folder is a product capability. Start with focused API schema roots when
+the capability only exposes HTTP contracts. Add messaging roots only when the
+capability actually owns async schema contracts.
+
+API-only example:
+
+```text
+schema/
+  recipes/
+    recipes.api.yml         # API schema root; generates under recipes/http
+    shared/                     # only if promoted reusable recipe components exist
+      enums.yml
+  kitchen/
+    stations.api.yml        # API schema root; generates under kitchen/http
+```
+
+API-only with multiple sub-areas in one generated capability package:
+
+```text
+schema/
+  recipes/
+    main.api.yml             # api: 3.0.3; groups under recipes/http
+    catalog.api.yml          # api: 3.0.3; groups under recipes/http
+    ingredients.api.yml      # api: 3.0.3; groups under recipes/http
+    shared/                     # capability-local promoted components only
+      enums.yml
+      components.yml
+```
+
+Use this grouped API schema pattern when the capability folder owns the generated
+package and the filenames describe focused surfaces. Keep one-off schemas in the
+surface file's `components.schemas`; move only repeated capability concepts into
+the capability's `shared/` folder. Promote again to `schema/shared/` only when
+another capability shares the same semantics.
+
+async-only example:
+
+```text
+schema/
+  recipes/
+    recipes.async.yml        # async schema root; generates under recipes/nats
+    messages/
+      recipe-commands.yml       # channels, operations, messages
+      recipe-events.yml
+    models/
+      recipe.yml                # message payload schemas
+      enums.yml                 # message enums
+```
+
+API schema plus async schema example only when both protocols exist:
+
+```text
+schema/
+  recipes/
+    recipes.api.yml         # HTTP root
+    recipes.async.yml        # messaging root
+    paths/
+      recipes.yml               # API schema path fragments
+    messages/
+      recipes.yml               # async schema channels/messages
+    models/
+      recipe.yml                # protocol-payload shapes
+      enums.yml                 # shared enums when meanings match
+```
+
+Combined preview when teaching all product-capability scenarios together:
+
+```text
+schema/
+  recipes/
+    # API-only
+    recipes.api.yml
+
+  recipes-messaging/
+    # async-only capability
+    recipes.async.yml
+    messages/
+      recipe-events.yml
+
+  bookstore/
+    # Both protocols, separate layers
+    bookstore.api.yml
+    bookstore.async.yml
+    paths/
+      books.yml
+    messages/
+      books.yml
+    models/
+      enums.yml
+```
+
+Do **not** describe this as `by-resource-area` only because fragments or routes
+inside `recipes/` are named `recipes.yml`, `ingredients.yml`, or `orders.yml`.
+Those are resource-area fragments inside a product-capability root.
+
+Do **not** add `paths/` fragments to a simple API-only capability unless the
+root file is too large, mixes independently owned surfaces, or needs reusable
+path-item fragments.
+
+### `by-api-surface`
+
+The root entrypoints are released API surfaces. Use this when public, partner,
+admin, and internal contracts need independent review and generation boundaries.
+
+```text
+schema/
+  public.api.yml            # public HTTP surface
+  partner.api.yml           # partner HTTP surface
+  admin.api.yml             # admin HTTP surface
+  internal.api.yml          # internal HTTP surface, when HTTP
+  internal-events.async.yml  # internal messaging surface, when messaging
+  shared/
+    enums.yml                   # shared only when semantics match
+```
+
+If the internal surface is messaging, use a separate async schema root such as
+`internal-events.async.yml`; do not imply it exists for API-only repos.
+When both protocols exist, share components through `schema/shared/` or
+surface-local `models/enums.yml`; keep `public.api.yml` and
+`internal-events.async.yml` independent entrypoints.
+
+### `by-service-owner`
+
+The first folder is the deployable service or owning team boundary.
+
+```text
+schema/
+  catalog-service/
+    catalog.api.yml         # API-only service surface
+  fulfillment-service/
+    fulfillment.api.yml
+  notification-service/
+    notifications.async.yml  # async-only service surface
+  order-service/
+    orders.api.yml          # both protocols for one service owner
+    orders.async.yml
+    models/
+      enums.yml
+```
+
+Add service-owned async schema roots only when the service owns messaging contracts:
+
+```text
+schema/
+  catalog-service/
+    catalog.async.yml
+  fulfillment-service/
+    fulfillment.async.yml
+```
+
+When a service owns both protocols, put both roots under the same service owner
+folder and share only `models/enums.yml` or scalar/value-object
+fragments.
+
+### `by-resource-area`
+
+Top-level roots are stable resource areas. There is no product-capability parent
+folder above them. Each resource area can become an independent generated
+namespace.
+
+```text
+schema/
+  books/
+    books.api.yml
+  authors/
+    authors.api.yml
+  book-events/
+    books.async.yml
+```
+
+A true `by-resource-area` recommendation should not say "keep resource-area
+files inside product-capability roots." That is a `by-product-capability` layout
+with resource-area fragments.
+
+### `by-workflow`
+
+The first folder is an end-to-end workflow that spans multiple resources.
+
+```text
+schema/
+  checkout/
+    checkout.api.yml        # API-only workflow
+  fulfillment/
+    fulfillment.async.yml    # async-only workflow
+  returns/
+    returns.api.yml         # both protocols, shared enums only
+    returns.async.yml
+    models/
+      enums.yml
+```
+
+If a workflow includes both HTTP and messaging contracts, keep both roots under
+the workflow folder and name each root by the contract surface.
+If the workflow is API-only, do not add an async schema file. If it is
+async-only, do not add HTTP path folders.
+
+### `by-message-family`
+
+async schema roots are grouped by message family. Use this only when messaging
+families are the real ownership/review boundary. This style is normally
+async-only; if the repo also has API schema, keep HTTP specs in a separate
+layout island or use `mixed`.
+
+```text
+schema/
+  commands/
+    recipe-commands.async.yml
+    order-commands.async.yml
+  events/
+    recipe-events.async.yml
+    order-events.async.yml
+  queries/
+    recipe-queries.async.yml
+  shared/
+    message-enums.yml
+```
+
+### `mixed`
+
+Use `mixed` only when a repo intentionally has more than one directory structure
+style. Document the style at each top-level folder before adding examples.
+
+```text
+schema/
+  public.api.yml              # by-api-surface, API-only
+  recipes/                        # by-product-capability, both protocols
+    recipes.api.yml
+    recipes.async.yml
+    models/
+      enums.yml                    # shared enums
+  events/                         # by-message-family, async-only
+    recipe-events.async.yml
+  README.md                       # explains why styles differ
+```
+
+## Do / don't examples
+
+### When `schemaLayoutStyle: by-product-capability`
+
+Do:
+
+```text
+schema/
+  recipes/
+    recipes.api.yml
+    shared/
+      enums.yml                 # only if promoted reusable recipe components exist
+```
+
+Or, when one product capability intentionally groups several API schema sub-areas
+into one generated package:
+
+```text
+schema/
+  recipes/
+    main.api.yml
+    catalog.api.yml
+    ingredients.api.yml
+    shared/
+      enums.yml                 # only if more than one surface uses it
+      components.yml
+```
+
+Do not call this repo-wide `by-resource-area` only because the files or optional
+fragments inside `recipes/` are named by resources.
+
+Do not move every schema into `shared/` just to keep root files short. Split by
+surface first, then promote only repeated concepts with the same product
+meaning.
+
+When both protocols exist in the same capability, keep `recipes.api.yml`,
+`recipes.async.yml`, `paths/`, and `messages/` separate. Share only
+`models/enums.yml` or other schemas when the meaning is identical.
+
+### When `schemaLayoutStyle: by-resource-area`
+
+Do:
+
+```text
+schema/
+  recipes/
+    recipes.api.yml
+  ingredients/
+    ingredients.api.yml
+```
+
+Don't nest resource areas under a product-capability parent unless
+`schemaLayoutStyle: mixed` and the folder documents that exception.
+
+## Generated output warning
+
+Schema paths affect generated output namespaces and import paths. Moving schema
+roots is a generated contract layout migration, not docs cleanup.
+
+Before recommending a folder move, state whether the user wants:
+
+1. a guidance-only profile change, or
+2. an actual schema and generated-output namespace migration.

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

@@ -0,0 +1,56 @@
+---
+name: authoring
+title: Spec Authoring
+description: "How Kontract spec authors should configure guidance, organize specs, reuse schemas, and change API or async schema files safely."
+tags: [kontract, authoring, api, async, schema-layout, contracts]
+---
+
+# Spec Authoring
+
+Use this folder when an agent is asked to create, move, review, or refactor
+Kontract source specs. Authoring guidance is about the source of truth under the
+configured `kontract.sources[].input` directory, not generated TypeScript output.
+Source roots use `*.api.yml` / `*.api.yaml` for API schemas and
+`*.async.yml` / `*.async.yaml` for async schemas.
+
+Start here before proposing schema files or folder moves:
+
+1. Read the repo's `sumr.yaml` and identify `kontract.sources[]`, targets, and
+   `kontract.guidance.profile`.
+2. Inspect the actual source specs under each configured input directory. If the
+   repo only has API schema roots, produce API-only examples; do not introduce
+   async schema files, channels, messages, or `messages/` folders unless the user
+   asks for messaging contracts.
+3. Use the contract design profile to align API paths, async schema channels, and
+   schema folder examples with the selected styles.
+4. Use the spec layout rules before creating or moving API/async roots.
+5. Use schema reuse guidance before adding new payloads, envelopes, errors,
+   pagination, scalar constraints, schedules, or config objects.
+6. Use scope and splitting guidance before expanding a large spec or proposing a
+   folder migration.
+7. Run the spec-change workflow when a spec change must be validated,
+   generated, and reviewed.
+
+## Non-negotiables
+
+- The selected profile is guidance-only; it does not move files or change
+  generation by itself.
+- Moving root spec files changes generated output namespaces/import paths because
+  output mirrors paths under the configured source input directory.
+- Do not mix schema layout styles unless `schemaLayoutStyle: mixed` and
+  each top-level folder documents the exception.
+- Do not call resource-area fragments inside a product-capability folder a
+  repo-wide `by-resource-area` layout.
+- Do not split a simple API schema root into `paths/` fragments by default. Use a
+  single focused root with local `components.schemas` first; split into fragments
+  only when size, ownership, or reuse pressure justifies it.
+- Keep schemas local to the owning API surface first. Promote to a
+  capability-local `shared/` folder only when multiple surfaces in that
+  capability reuse the same product concept; promote to `schema/shared/` only
+  when multiple capabilities share the same meaning.
+- Separate the three protocol scenarios: API-only, async-only, and
+  API + async. When both protocols exist, keep protocol-specific layers
+  separate and share only components with identical meaning, especially
+  enums and scalar value objects.
+- Generated files are outputs. Change specs first, validate, generate, then
+  review the generated diff.