@sumrco/cli 0.3.0 → 0.3.2

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
@@ -60,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
@@ -91,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`
 
@@ -151,7 +151,7 @@ export const SWG_LIST_RECIPES = {
 `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`.
+and standard API schema `security`.
 
 ## Generated `ApiDoc` decorator — when `swagger: true`
 
@@ -164,7 +164,7 @@ export function ApiDoc(operation: ApiDocOperation): MethodDecorator {
 ```
 
 Controllers can consume `ApiDoc(SWG_*)` metadata to keep runtime Swagger output
-aligned with the OpenAPI design contract:
+aligned with the API schema design contract:
 
 ```typescript
 import { SWG_LIST_RECIPES } from 'SUMR Schemas module/recipes/http';
@@ -197,7 +197,7 @@ export class RecipesFetchClient {
   constructor(private readonly config: RequestConfig = {}) {}
 
   async getRecipe(request: GetRecipeRequest): Promise<Models.Recipe> {
-    // fetch call generated from OpenAPI operation metadata
+    // fetch call generated from API schema operation metadata
   }
 }
 ```
@@ -227,10 +227,11 @@ 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: (value) => value as never,
+  decodeJson: decodeProductApiJson,
 });
 
 export async function loadProduct(id: string) {
@@ -238,6 +239,10 @@ export async function loadProduct(id: string) {
 }
 ```
 
+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.
+
 Example Angular usage:
 
 ```typescript
@@ -258,7 +263,7 @@ 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
+## NATS contract — one `nats/index.ts` per async schema service
 
 ```typescript
 // contracts/recipes/nats/index.ts
@@ -286,12 +291,12 @@ 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 AsyncAPI service
+## 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/`:
@@ -328,7 +333,7 @@ export const RecipeStatusMap = {
   validation.
 - 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.
+  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.

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

@@ -1,32 +1,33 @@
 ---
 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
+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
 ---
 
-# OpenAPI SDK Generator Research
+# API schema SDK Generator Research
 
-Kontract learns from public OpenAPI generators without inheriting their runtime
-shape, Java dependency chain, or template system.
+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.
 
-## References reviewed
+## Reviewed generator inputs
 
-- OpenAPI Generator `typescript-fetch`:
+- API schema Generator `typescript-fetch`:
   <https://openapi-generator.tech/docs/generators/typescript-fetch/>
-- OpenAPI Generator `typescript-axios`:
+- API schema Generator `typescript-axios`:
   <https://openapi-generator.tech/docs/generators/typescript-axios/>
-- OpenAPI Generator `typescript-angular`:
+- API schema Generator `typescript-angular`:
   <https://openapi-generator.tech/docs/generators/typescript-angular/>
-- OpenAPI Generator `typescript-nestjs`:
+- API schema Generator `typescript-nestjs`:
   <https://openapi-generator.tech/docs/generators/typescript-nestjs/>
-- OpenAPI TypeScript `openapi-fetch`:
+- API schema TypeScript `openapi-fetch`:
   <https://openapi-ts.dev/openapi-fetch/>
 
-## Lessons for Kontract
+## SDK generation standards
 
 - Keep SDK config options familiar where they are useful:
   `useSingleRequestParameter`, `paramNaming`, `modelPropertyNaming`,
@@ -40,20 +41,17 @@ shape, Java dependency chain, or template system.
 - 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.
+- 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.
 
-## Product decisions
+## 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.
-- 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,74 +1,111 @@
 ---
 name: usage
 title: Kontract Usage
-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]
+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 generates the artifacts that keep APIs honest: validation schemas,
-framework decorators, SDKs, docs inputs, runtime evidence, and message contracts
-from OpenAPI and AsyncAPI sources.
+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.
-- 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.
+- 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 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/
-    catalog.schema.yml  →  contracts/recipes/http/
-    events.schema.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 OpenAPI or AsyncAPI source → many generated, always-consistent 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
@@ -80,85 +117,81 @@ kontract:
             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
-  compatibility `http/swagger.ts` operation metadata.
+- `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 for NestJS controllers.
+  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 NestJS target.
+  `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/swagger.ts` or
-`shared/http/decorators/api-doc.ts`, first confirm the target has
+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
-Swagger/ApiDoc support.
+the metadata helper.
 
 ## 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. |
+| 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-neutral model-only output. |
+| Model | `typescript-models` | Framework-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.
+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`, `*.asyncapi.yml`, or
-  `*.schema.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. Route changed copy
-  through the repo's copywriter/microcopy standard before generation.
+  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`.
+- 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 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
-  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,
+  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 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.
+- 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

@@ -20,6 +20,9 @@ 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 configured contract artifacts from API specs
       visibility: public

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

package/ai/modules/playbook/resources/authoring/content-structure.rf.md

@@ -1,6 +1,6 @@
 ---
 category: reference
-name: playbook-authoring-structure
+name: authoring-structure
 title: Content Structure
 description: "Body templates for canonical Playbook topics and reference files, with required sections and structure rules."
 label: Structure

package/ai/modules/playbook/resources/authoring/cross-referencing.rf.md

@@ -1,6 +1,6 @@
 ---
 category: reference
-name: playbook-authoring-cross-referencing
+name: authoring-cross-referencing
 title: Cross-Referencing
 description: "How to reference other topics within SUMR docs: use name for main topics, label for references. Never use file paths."
 label: Cross-Refs

package/ai/modules/playbook/resources/authoring/descriptions.rf.md

@@ -1,6 +1,6 @@
 ---
 category: reference
-name: playbook-authoring-descriptions
+name: authoring-descriptions
 title: Writing Descriptions
 description: "Rules for writing effective frontmatter descriptions — third person, what-plus-when, specific key terms, length, and YAML safety."
 label: Descriptions

package/ai/modules/playbook/resources/authoring/extraction.rf.md

@@ -1,6 +1,6 @@
 ---
 category: reference
-name: playbook-authoring-extraction
+name: authoring-extraction
 title: Content Extraction
 description: "extract:examples marker syntax, code block classification, and size guidelines for SUMR docs."
 label: Extraction

package/ai/modules/playbook/resources/authoring/flows.rf.md

@@ -1,6 +1,6 @@
 ---
 category: reference
-name: playbook-authoring-flows
+name: authoring-flows
 title: Flow Documentation
 description: "Flow documentation patterns for Playbook docs, including compact arrow flows, human approval gates, Mermaid diagrams, and transition rules."
 label: Flows

package/ai/modules/playbook/resources/authoring/folder-structure.rf.md

@@ -1,6 +1,6 @@
 ---
 category: reference
-name: playbook-authoring-folder-structure
+name: authoring-folder-structure
 title: Folder Structure
 description: "Recommended Playbook folder layout, top-level naming, team-member placement patterns (root vs domain-embedded), and standards folder naming alternatives."
 label: Folder Structure

package/ai/modules/playbook/resources/authoring/frontmatter.rf.md

@@ -1,6 +1,6 @@
 ---
 category: reference
-name: playbook-authoring-frontmatter
+name: authoring-frontmatter
 title: Frontmatter Schema
 description: "Required and optional frontmatter fields, category values, and per-category validation rules for SUMR Playbook docs."
 label: Frontmatter
@@ -48,6 +48,7 @@ description: "Test isolation rules, temp dir pattern, and integration test appro
 | `effort` | `low \| medium \| high` | Reasoning depth for team-member/agent topics. Channels that support effort emit their native knob. |
 | `access` | `read-only \| write \| full` | Permission posture. Channels translate it into their sandbox, tool, or permission model. |
 | `tools` | `string[]` | Agnostic capability tokens (`read`, `edit`, `shell`, `web`, `todo`, `task`). Channels translate them into native tool names or permission keys. |
+| `nicknames` | `string[]` | Friendly display names for spawned team-member instances. Codex renders this as `nickname_candidates`; other channels ignore it until they expose an equivalent. |
 | `channels` | object | Legacy-compatible per-channel overrides. Prefer top-level native channel blocks in new docs. |
 | `target` | string | Output filename override (basename only, extension inferred) |
 
@@ -60,6 +61,7 @@ modelTier: reasoning   # reasoning | coding | fast  → model class
 effort: high           # low | medium | high        → Codex model_reasoning_effort
 access: read-only      # read-only | write | full   → channel-native permission posture
 tools: [read, web]     # read | edit | shell | web | todo | task  → channel-native tools/permissions
+nicknames: [Atlas, Delta, Echo] # friendly spawned-instance labels when supported
 ```
 
 `modelTier` → concrete model per channel:
@@ -101,6 +103,7 @@ name: codebase-reviewer
 title: Codebase Reviewer
 description: "Reviews code for correctness, security, behavior regressions, and missing tests."
 modelTier: reasoning
+nicknames: [Atlas, Delta, Echo]
 
 # Codex CLI agent profile options
 codex:

package/ai/modules/playbook/resources/authoring/markdown.rf.md

@@ -1,6 +1,6 @@
 ---
 category: reference
-name: playbook-authoring-markdown
+name: authoring-markdown
 title: Markdown Formatting
 description: "Markdown formatting rules: headings, callouts, emphasis, lists, code blocks, tables, and common anti-patterns."
 label: Markdown

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

@@ -1,5 +1,5 @@
 ---
-name: playbook-authoring
+name: authoring
 title: Playbook Authoring
 description: "How to write canonical SUMR Playbook docs: frontmatter schema, references, extraction markers, and authoring checklist. Use when creating or editing Markdown docs, technical docs, AI docs, agent skills, specs, runbooks, or Playbook sources."
 tags: [authoring, docs, markdown, ai-docs, technical-docs, specs, skills]