@aurorajs.dev/catalyst-cli 1.0.0

package/dist/templates/monorepo/.claude/skills/business-rules-guard/references/workflow.md

@@ -0,0 +1,301 @@
+# Workflow reference — Business Rules Catalog
+
+Cómo crear, derogar y modificar reglas. Para el formato exacto del `.md`, ver `format.md`.
+
+> Tres workflows independientes (A, B, C) más temas operativos (cross-aggregate, asunciones,
+> citas `@rule`). La nomenclatura coincide con `docs/business-rules/README.md`.
+
+---
+
+## Workflow A — Vía OpenSpec (recomendado para cambios planificados)
+
+Aplicable cuando el cambio pasa por OpenSpec (`propose → apply → archive → promote`). El
+comando `/business-rules:promote` maneja **todas las acciones** declaradas en el `proposal.md`
+en una sola pasada.
+
+```
+┌───────────────────────────────────────────────────────────────────────────┐
+│  1. /opsx:propose <descripción>                                           │
+│     - El config.yaml inyecta instrucciones de business-rules.            │
+│     - Claude consulta cliter/<bc>/business-rules/* relevantes.            │
+│     - Si detecta conflicto, presenta opciones al user (a/b/c).            │
+│     - Genera proposal.md con sección "Business rules affected".           │
+│  2. (Si hay conflicto) Tú resuelves; Claude registra la decisión.         │
+│  3. /opsx:apply — Claude implementa el código.                            │
+│  4. /opsx:archive <name> — cierra el ciclo, mueve a archive/.             │
+│  5. /business-rules:promote — coordina dos sub-pasos:                     │
+│       5.a Script :promote (Node):                                         │
+│           - Para `mantiene BR-X`: no-op.                                  │
+│           - Para `deroga BR-Y`: state→derogated + sección ###Derogación.  │
+│           - Para `extiende BR-Z`: no-op del script (recordatorio manual). │
+│           - Para `Nuevas`: scaffold con ID secuencial real, state=        │
+│             proposed, body con [VERIFICAR].                               │
+│           Regenera índice.                                                │
+│       5.b Claude (continuación, misma sesión):                            │
+│           Para cada regla creada en 5.a:                                  │
+│           - Lee proposal.md archivado, código del agregado, tests,        │
+│             CONTEXT.md.                                                   │
+│           - Redacta body real (Enunciado, Casos, Implementa, Tests,       │
+│             Diagrama de cascada si aplica).                               │
+│           - Pide confirmación al usuario.                                 │
+│           - Sustituye [VERIFICAR] por contenido real.                     │
+│           - Cambia state=proposed → state=active.                         │
+│           pnpm br:generate && pnpm br:validate (o pre-commit hook).       │
+└───────────────────────────────────────────────────────────────────────────┘
+```
+
+### Sección "Business rules affected" en proposal.md
+
+Estructura mínima:
+
+```markdown
+## Business rules affected
+
+### Existentes
+- mantiene BR-PROD-EVENT-005 — descripción breve.
+- deroga BR-PROD-EVENT-003 — razón breve.
+- extiende BR-PROD-HEADER-001 — relación.
+
+### Nuevas
+- en `production-planning/production-order-position-event` — Validación de cancelación.
+- BR-PROD-EVENT en `production-planning/production-order-position-event` — Validación de cancelación.
+  (forma con prefijo de ID explícito; necesaria solo si el archivo destino no tiene reglas previas
+  de las que el script pueda inferir el prefijo)
+```
+
+Si no hay reglas afectadas: escribir `None` bajo la sección.
+
+### Asignación de IDs en reglas nuevas
+
+`:promote` lee el path del proposal y asigna el siguiente número secuencial. Para el prefijo:
+
+- **Inferencia automática**: si el archivo destino ya tiene reglas, el script toma el prefijo
+  más común (en la práctica, el del último spec/regla creada en ese archivo). Ejemplo: si las
+  reglas existentes son `BR-PROD-EVENT-001` y `BR-PROD-EVENT-002`, la nueva será
+  `BR-PROD-EVENT-003`.
+- **Prefijo explícito**: si el archivo está vacío, el proposal lo declara como
+  `- BR-PROD-EVENT en \`...\` — Título`. Por convención, el explícito debe coincidir con el
+  prefijo del último spec creado en agregados similares del mismo bounded context.
+
+### Estado del índice tras el flujo
+
+- Tras 5.a el script ya regeneró el índice automáticamente.
+- En 5.b Claude edita los `.md` (sustituye `[VERIFICAR]`, cambia `proposed` → `active`), por lo
+  que el índice se desactualiza.
+- Antes del commit hay que regenerar otra vez. La pre-commit hook lo hace automáticamente al
+  detectar cambios staged en el catálogo.
+
+---
+
+## Workflow B — Documentación retroactiva (vía `/business-rules:document`)
+
+Aplicable cuando:
+
+- El catálogo no cubre un agregado y quieres extraer reglas implícitas de código existente.
+- Un bug destapa una regla no documentada.
+- Tienes un Word funcional con reglas que quieres formalizar.
+
+```
+/business-rules:document <bc>/<aggregate>
+   o
+/business-rules:document <bc>/<aggregate> --from path/to/word-export.md
+```
+
+El script:
+
+1. Verifica que el agregado existe (busca `cliter/<bc>/<aggregate>.aurora.yaml`).
+2. Crea el archivo del catálogo con frontmatter scaffold (si no existe).
+3. Lista las fuentes que el LLM debe consultar (YAML, CONTEXT.md, código, tests).
+4. Imprime guidance para que el LLM identifique reglas implícitas.
+
+Después, el LLM (en sesión interactiva) sigue:
+
+1. Lee YAML del agregado → estados, relaciones, campos.
+2. Lee CONTEXT.md → flujo del BC.
+3. Recorre los archivos de dominio listados.
+4. Identifica reglas (precondiciones, cascadas, invariantes derivados, políticas).
+5. Para cada regla detectada:
+   - Asigna ID nuevo siguiendo el prefijo del último spec creado del agregado.
+   - Redacta enunciado en español.
+   - Construye tabla exhaustiva de casos. Marca `[VERIFICAR]` solo en filas concretas que no
+     pueda derivar claramente del código (NO en headers de secciones — el body es real).
+   - Cita paths reales en `Implementa` y `Tests`.
+6. **Pide confirmación al usuario** antes de escribir cada regla.
+7. Persiste y valida:
+   ```
+   pnpm br:generate && pnpm br:validate
+   ```
+
+Estado típico: `active` (la regla ya está implementada porque la deduces del código). Excepción:
+`proposed` cuando documentas una intención que el código no satisface todavía (ver "Gap
+producto↔código" más abajo).
+
+### Importar Word funcional con `--from`
+
+Cuando hay material externo:
+
+- Tratarlo como **candidato**, no autoritativo.
+- Verificar cada regla candidata contra el código real.
+- En cada divergencia, marcar `[VERIFICAR]` y resolver con producto/dominio.
+
+### Limitación
+
+Este workflow **solo crea** reglas nuevas. Para derogar o modificar reglas existentes, usa el
+Workflow C.
+
+---
+
+## Workflow C — Edición directa
+
+Aplicable cuando ni OpenSpec ni `:document` aplican: fixes ad-hoc, ajustes sin cambio
+semántico, derogations puntuales fuera de OpenSpec, modificaciones manuales del catálogo.
+
+### C.1 — Crear una regla nueva
+
+Editar el `.md` del agregado a mano:
+
+1. Asignar un ID nuevo siguiendo el prefijo del último spec creado del agregado (no reusar
+   derogados).
+2. Pegar la plantilla canónica (ver `format.md`).
+3. Rellenar enunciado, tabla de casos, `Implementa`, `Tests`.
+4. Marcar `[VERIFICAR]` o `[ASUNCIÓN]` solo en casos concretos que dudes.
+5. `pnpm br:generate && pnpm br:validate` (o lo hace la pre-commit hook al commitear).
+
+### C.2 — Derogar una regla
+
+Las reglas **no se editan en su semántica**. Para retirar o reemplazar una regla:
+
+```
+1. Localizar la regla:
+   pnpm br:check BR-PROD-EVENT-005
+
+2. En el archivo, abrir la regla y modificar la metadata:
+     | Estado | `derogated`                                          |
+     | Origen | retro-documentada (derogada por BR-PROD-EVENT-007)   |
+
+3. Añadir sección "### Derogación" al final del cuerpo:
+     ### Derogación
+     Derogada el 2026-06-15 por **BR-PROD-EVENT-007**.
+     Razón: <motivo en una frase>.
+
+4. (Si hay regla sustituta) crearla con un ID nuevo (no reusar 005):
+     ## BR-PROD-EVENT-007 — <Nuevo título>
+     ...
+     ### Reglas relacionadas
+     - BR-PROD-EVENT-005 (derogada por esta regla).
+
+5. Regenerar:
+   pnpm br:generate && pnpm br:validate
+   (o lo hace la pre-commit hook al commitear)
+
+6. Commit:
+   chore(business-rules): derogate BR-PROD-EVENT-005, add BR-PROD-EVENT-007
+```
+
+### C.3 — Modificar una regla (= derogar + crear)
+
+Modificar la semántica de una regla equivale a derogar la antigua y crear una nueva con ID
+nuevo. Sigue C.2 + C.1.
+
+#### Edits permitidos en sitio sin derogar (no son cambios semánticos)
+
+- Corregir typos, gramática, formato.
+- Reformular frases sin alterar significado.
+- Arreglar paths rotos en `Implementa` / `Tests`.
+- Refrescar `last_updated` tras cualquier cambio.
+- Resolver `[VERIFICAR]` o `[ASUNCIÓN]` sustituyendo por contenido validado.
+- Añadir filas a la tabla de casos (cubrir más espacio sin contradecir lo ya cubierto).
+
+#### Cambios que requieren derogación obligatoria
+
+- Cambiar resultado de un caso ya enumerado.
+- Cambiar enunciado en su significado.
+- Cambiar severidad (`blocking` ↔ `informational`).
+
+> **No se borra la regla derogada en ningún workflow**. Permanece visible para que las
+> citaciones históricas en código y commits sigan siendo unívocas.
+
+---
+
+## Temas operativos (transversales a los workflows)
+
+### Reglas cross-aggregate y cross-BC
+
+#### Decidir dónde vive la regla
+
+La regla **vive en un único archivo**: el del agregado donde se observa el invariante final.
+
+```
+Cascada delete(event) → position PENDING → header PENDING + startDate=null
+                                                              ↑
+                                                  invariante final
+                                                  (vive aquí)
+```
+
+→ Vive en `cliter/production-planning/business-rules/production-order-header.md`.
+
+#### Apuntadores
+
+Los archivos de los demás agregados/BCs llevan apuntadores cortos. Plantillas en `format.md`.
+
+#### Frontmatter en plural
+
+```yaml
+bounded_contexts:
+  - production-planning
+  - iam                    # si la regla es cross-BC
+aggregates:
+  - production-planning/production-order-header
+  - production-planning/production-order-position
+  - production-planning/production-order-position-event
+  - iam/role               # si afecta a un agregado de iam
+```
+
+Esto permite que el filtrado por BC en la detección de conflictos retorne la regla
+automáticamente desde cualquiera de los BCs declarados.
+
+### Resolver `[VERIFICAR]` y `[ASUNCIÓN]`
+
+Cuando una regla tiene una celda con `**[VERIFICAR caso 4]**` u otro caso del que no estás
+seguro:
+
+1. **Pregunta a producto/dominio** la pregunta concreta.
+2. Edita la regla en sitio:
+   - Sustituye `**[VERIFICAR caso 4]**` en la celda por el valor confirmado.
+   - Borra (o resume) la entrada en la sección "Asunciones a verificar".
+3. Refresca `last_updated`.
+4. `pnpm br:generate && pnpm br:validate` (o lo hace la pre-commit hook al commitear).
+
+Esto es **edit en sitio sin derogar** (es un sub-caso del Workflow C): rellenar un caso
+`[VERIFICAR]` no cambia el significado de la regla, solo cierra una laguna.
+
+### Gap producto↔código (estado `proposed` legítimo en el catálogo)
+
+Es legítimo dejar una regla en `Estado: proposed` y commitearla cuando documentas una intención
+que el código no satisface todavía y quieres que el gap sea visible y auditable.
+
+Ejemplo: `BR-PROD-HEADER-002` describe la cascada de revert al borrar el último evento;
+producto la quiere pero el código no la implementa. Marcarla como `proposed` hace el gap
+explícito y trazable.
+
+NO es legítimo dejar `proposed` con `[VERIFICAR]` en headers como resultado de una sesión
+interrumpida del Workflow A (sub-paso 5.b). Si ves uno, completa el body antes de commitear.
+
+### Citas `@rule` en código (opcional)
+
+```typescript
+/**
+ * Cancela un evento de producción.
+ *
+ * @rule BR-PROD-EVENT-001 — No cancelar eventos DONE
+ * @see cliter/production-planning/business-rules/production-order-position-event.md
+ */
+async cancel(eventId: string): Promise<void> {
+  ...
+}
+```
+
+- Es **opcional**, no enforcement.
+- Mejora la legibilidad para futuros lectores.
+- El audit reporta orphans (`@rule` sin entry en catálogo) y zombies (regla activa sin ningún
+  `@rule` tras 30 días). Ambos son advisory; no bloquean builds.

package/dist/templates/monorepo/.claude/skills/catalyst-cli/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: catalyst-cli
+description: >
+  Aurora Catalyst CLI usage for AI agents. Covers the `catalyst generate` and
+  `catalyst origin` workflow, the schema-first principle (always express
+  intent in `*.aurora.yaml` when possible), and the three-way reconciliation
+  of `.origin` files (codegen output vs user customization vs AI session
+  edits). Trigger: When running `catalyst …`, regenerating a module after
+  schema or `aurora.yaml` changes, reconciling `.origin` files left behind
+  by a regen, deciding whether a change belongs in YAML or in code, or
+  inspecting which CLI command applies. Loads alongside `catalyst-schema`
+  whenever a YAML edit might require regeneration afterwards.
+license: MIT
+metadata:
+  author: aurora
+  version: '1.0'
+  auto_invoke:
+    'Running catalyst commands, regenerating modules, reconciling .origin
+    files, deciding YAML-vs-code, post-schema-edit workflows'
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch, WebSearch, Task
+---
+
+## When to Use
+
+Load this skill when you are about to:
+
+- Run any `catalyst <command>` in this repo (generate, origin, env, sheets, deploy, provision, …).
+- Regenerate a module after editing its `*.aurora.yaml` schema.
+- Edit generated code where a `.origin` file is present or will be produced.
+- Decide whether a customization belongs in `aurora.yaml` (declarative) or in code (imperative).
+- Inspect a divergent file the codegen left in `.origin` form.
+
+**Always combine with:**
+
+- [`catalyst-schema`](../catalyst-schema/SKILL.md) — for the YAML side of any change. If a feature is expressible in YAML, that is where it must live.
+- [`conventional-commits`](../../skills/conventional-commits/SKILL.md) — when committing the result of a regen.
+- [`business-rules-guard`](../business-rules-guard/SKILL.md) — if the regenerated module has registered business rules.
+
+## Detailed References
+
+- [`references/origin-conciliation.md`](references/origin-conciliation.md) — the full reconciliation algorithm for `.origin` files (three-way merge between codegen output, user customization, and AI session edits).
+- [`references/schema-versioning.md`](references/schema-versioning.md) — how to discover the latest `aurora.yaml` schema version from SchemaStore and pin it.
+
+---
+
+## Critical Patterns
+
+### Schema-first: ALWAYS check whether a change is expressible in YAML before touching code
+
+Aurora's value proposition is that the YAML is the source of truth. The generator produces code from the YAML; user-facing meta-properties (icons, display fields, detail modes, embed support, widget types, validations, lengths, relationships, …) live in the schema, not in the emitted code.
+
+Before editing any generated file, ask:
+
+> Is this change something I could express in `cliter/<bc>/<module>.aurora.yaml`?
+
+If **yes** → edit the YAML, regenerate, and let the codegen propagate the change to every file that depends on it. If you change the icon by hand in `<bc>.navigation.ts`, the next regen will fight you (an `.origin` file appears, your edit is at risk).
+
+If **no** → the change is genuine custom logic. Make it in code, but put it where the merge engine will preserve it (inside an `AURORA:*-START/END` preservation region when one is available).
+
+The list of meta-properties that live in YAML is non-trivial; consult [`catalyst-schema`](../catalyst-schema/SKILL.md) for the full grammar. Quick lookup:
+
+| Want to change… | Where it lives in YAML |
+|---|---|
+| Module icon (sidebar / nav) | `front.icon` |
+| Human-readable label of a record | `front.displayField` |
+| Edit screen (full route vs dialog) | `front.detailMode: view | dialog` |
+| Whether the aggregate can be embedded inside another | `front.embedSupport: true` |
+| Relationship rendering (combobox, grid select, async search) | `<property>.widget.type` |
+| Field length, nullability, validators | property attributes |
+| Pivot / many-to-many membership UX | (currently disabled — see CLAUDE.md) |
+
+If you cannot find the property in the schema and you believe it should exist, that is a **schema gap**, not a code customization — flag it via the OpenSpec flow rather than papering over it in the emitted file.
+
+### Schema version discovery
+
+The Aurora YAML schema is versioned and published to SchemaStore. The catalog at
+`https://github.com/SchemaStore/schemastore/blob/master/src/api/json/catalog.json` lists every published version. When you need the canonical grammar for an edit, fetch the latest entry from the `aurora-N.N.json` family (currently `aurora-1.3.json`). See [`references/schema-versioning.md`](references/schema-versioning.md) for the exact fetch procedure.
+
+### `.origin` files exist for one reason: hash mismatch
+
+A `.origin` file is produced by `catalyst generate` if and only if the **stored skeleton hash** in the per-file lockfile does **not** match the **current skeleton hash** computed from the file on disk. In plain language: the file was modified by someone (a developer, an AI agent, a regex find-replace) since the last regen.
+
+Concretely:
+
+```
+<file>                       ← user's modified content (untouched by the regen)
+<file>.origin.<ext>          ← the new codegen proposal, with preservation
+                               regions already merged from the user's file
+```
+
+The `.origin` file is **not** the user's old version. It is the **codegen's proposed new content**, already merged with whatever bodies the user had inside `AURORA:*-START/END` regions. The reconciliation task is therefore: should I adopt the proposal, keep my current file, or take the proposal and re-apply the diverged parts on top?
+
+### Three-way reconciliation: who wrote which hunk?
+
+When you (the AI) face an `.origin` file in a session that you also generated code in, three sources can contribute to the divergent content:
+
+1. **Codegen** — the templates produced this. Likely improvements when templates evolve (new wrapper, new pattern, new import, restructured signal API).
+2. **User customization** — the human developer wrote this. Often outside preservation regions because they had no better place to put it. Must be preserved unless the user explicitly says otherwise.
+3. **AI session work** — code the AI agent wrote during the current conversation, before the regen ran. The AI knows what it wrote because it sees the conversation; it can also check `git diff` against the last commit.
+
+The reconciliation algorithm and the per-hunk decision tree live in [`references/origin-conciliation.md`](references/origin-conciliation.md). Read it before acting on `.origin` files in a non-trivial regen.
+
+**Default to safety.** When in doubt about a hunk: leave the user's version, run `catalyst origin diff <path>` for the human, and ask. Do not adopt the proposal and re-apply on top blindly.
+
+### Regenerate when YAML changes — always
+
+If any of these changes happens, the affected module(s) must be regenerated:
+
+- A property added, removed, renamed, or retyped.
+- `front.icon`, `front.displayField`, `front.detailMode`, `front.embedSupport`, or any other `front.*` meta-property edited.
+- A relationship added, removed, or its widget type changed.
+- A validation, length, nullability, or default changed.
+- A schema version bump that adds new emit paths.
+
+The regen is the contract: schema is the source of truth, and the only way for the code to reflect a YAML change is to run the codegen. Editing by hand defeats the model.
+
+---
+
+## Commands
+
+The CLI binary is `catalyst` (published as `@aurorajs.dev/catalyst-cli`). Run from the consumer repo root unless noted.
+
+### Generation
+
+```bash
+# Regenerate a back-end module
+catalyst generate back module --name=<bc>/<module>
+
+# Regenerate a front-end module
+catalyst generate front module --name=<bc>/<module>
+
+# Force overwrite of files even if user-modified (creates .origin pairs)
+catalyst generate <scope> module --name=<bc>/<module> --force
+
+# Generate e2e tests alongside the module
+catalyst generate back module --name=<bc>/<module> --tests
+
+# Skip GraphQL type regen (default runs `pnpm back:graphql:types`)
+catalyst generate back module --name=<bc>/<module> --noGraphQLTypes
+
+# Verbose: per-file, per-region log
+catalyst generate <scope> module --name=<bc>/<module> --verbose
+```
+
+`generate` is non-interactive. After it finishes, look at its closing line — if any `.origin` files were created, the count is printed and you are pointed at `catalyst origin list` and `catalyst origin review`.
+
+### `.origin` reconciliation (the AI workflow)
+
+```bash
+# List pending .origin files under cwd (or any pathspec)
+catalyst origin list
+catalyst origin list backend/
+catalyst origin list backend/foo.ts
+catalyst origin list --json                # machine-readable
+
+# Show a unified diff of <origin> against <current>
+# Output direction: + lines are what the codegen would add, - lines are what
+# the user currently has that the proposal removes
+catalyst origin diff <path>
+catalyst origin diff --json
+
+# Adopt the codegen proposal (atomic rename of .origin over current)
+catalyst origin accept <path>              # one file
+catalyst origin accept backend/iam/        # subtree
+catalyst origin accept                     # everything under cwd
+
+# Reject the proposal (delete .origin, keep current as-is)
+catalyst origin reject <path>
+
+# Reject the proposal AND mark the file as "skip on future regens"
+# (prepends `// ignored file` / `<!-- ignored file -->` / `# ignored file`
+# depending on extension; the next regen will skip the file entirely)
+catalyst origin ignore <path>
+
+# Interactive walk-through for humans (inquirer + optional VS Code diff)
+catalyst origin review
+```
+
+All five non-`review` verbs accept the same pathspec semantics:
+
+| Form | Behaviour |
+|---|---|
+| no arg | start from `cwd`, recurse |
+| file (`backend/foo.ts`) | act on that file's `.origin` if it exists |
+| `.origin` path | normalised to the current file path, then acted on |
+| directory | recurse under it |
+
+Idempotency: `accept`/`reject`/`ignore` on a path without a corresponding `.origin` is a silent no-op (exit 0). Retries are safe; AI agents do not need to check existence first.
+
+### Other commands (less central to the AI workflow)
+
+```bash
+catalyst env encrypt --env <name>          # SOPS encrypt .env.<env>
+catalyst env decrypt --env <name>          # SOPS decrypt .env.<env>.enc
+
+catalyst sheets pull --bc <bc>             # Pull schemas from Google Sheets
+catalyst sheets push --bc <bc>             # Push schemas to Google Sheets
+catalyst sheets diff --bc <bc>             # Compare YAML vs Sheet
+
+catalyst deploy --env <name>               # Trigger CI/CD pipeline
+catalyst provision --env <name>            # Provision DNS + hosting + CI/CD secrets
+
+catalyst keys                              # Generate RSA private/public key pair
+catalyst new <project-name>                # Scaffold a new Aurora monorepo
+catalyst add <package-name>                # Add an Aurora package
+catalyst pipeline                          # Generate a deploy workflow
+catalyst ai setup                          # Sync AI provider config (CLAUDE.md/AGENTS.md)
+```
+
+The full per-command surface is in `aurora-catalyst-cli/docs/<command>.md` (or `catalyst <command> --help`).
+
+---
+
+## Workflow: editing a generated module
+
+The decision tree the AI should run before touching any file under `backend/src/` or `frontend/src/` that was emitted by the codegen:
+
+```
+                  About to edit a generated file?
+                            │
+                            ▼
+              ┌─────────────────────────────────┐
+              │ Is the desired change           │
+              │ expressible in <module>.aurora  │
+              │ .yaml (icon, displayField,      │
+              │ detailMode, widget, validator,  │
+              │ length, relation, …)?           │
+              └─────────────────────────────────┘
+                  │ yes                  │ no
+                  ▼                      ▼
+        Edit the YAML.            Is the change inside an
+        Then regenerate.          AURORA:*-START/END
+        Reconcile .origin if      preservation region?
+        any.                          │ yes        │ no
+                                      ▼            ▼
+                              Edit inside     The customization will
+                              the region.     be lost on regen unless
+                              Safe forever:   you reject the proposal
+                              the merge       every time. Strongly
+                              engine will     consider:
+                              keep your body  - widening the YAML to
+                              across regens.    cover the case (file
+                                                a `catalyst-schema`
+                                                gap report)
+                                              - using `origin ignore`
+                                                permanently on the
+                                                file (only if the
+                                                whole file is custom
+                                                from now on)
+                                              - leaving the edit and
+                                                accepting that future
+                                                regens require
+                                                manual merge
+```
+
+---
+
+## Workflow: a regen produced `.origin` files — what to do
+
+```
+                catalyst generate finished
+                "N origin files pending review"
+                            │
+                            ▼
+                catalyst origin list --json
+                            │
+              for each entry in the list:
+                            │
+                            ▼
+                catalyst origin diff <path>
+                            │
+                  inspect the patch
+                            │
+              ┌─────────────┼─────────────────────────────┐
+              ▼             ▼                             ▼
+       hunk looks      hunk looks                  hunk looks like a
+       like template   like user                   change YOU wrote
+       improvement     custom logic                this session
+       (new wrapper,   (business rule,             (check `git diff`
+       new import,     custom validator,           since last commit;
+       new shape)      hand-written copy)          confer with the
+              │             │                     conversation log)
+              ▼             ▼                             ▼
+       accept the      reject the                  Three options, see
+       proposal IF     proposal: keep              `references/origin-
+       no user/AI      what the user               conciliation.md`
+       hunks are in    already had.                §"Session-aware
+       the same file.                              merge"
+       Otherwise:
+       three-way
+       merge (see
+       references/).
+```
+
+When `accept`-ing because the proposal carries genuine template improvements but the file also contains user/AI customization, the correct sequence is:
+
+1. `git stash` (or commit) the user/AI work in this file.
+2. `catalyst origin accept <path>` — adopt the new scaffolding.
+3. Re-apply the user/AI hunks on top of the new scaffolding manually (or via `git stash pop` and resolve).
+
+This is the **three-way reconciliation** mentioned above. Read [`references/origin-conciliation.md`](references/origin-conciliation.md) before doing it on a complex file — there are pitfalls.
+
+---
+
+## Anti-patterns to call out
+
+- **Editing a file the codegen owns to change an icon, label, or display field.** Refuse and edit the YAML.
+- **Running `catalyst origin accept` blindly across an entire subtree after a regen that touched files the AI edited this session.** This silently overwrites session work. Always `diff` first or check `git status`.
+- **Adding `--force` to `catalyst generate` without intent.** `--force` turns *every* user-modified file into an `.origin` pair to triage; without it, modified files are left as-is. Reach for `--force` only when you have a concrete reason to inspect divergence on multiple files.
+- **Treating `.origin` files as backups.** They are not. They are *proposals* that disappear once you decide. Never let them accumulate across many regens — they get stale and confusing.
+- **Ignoring (`origin ignore`) a file that should instead be expressed in YAML.** `ignore` is for genuinely hand-written files that no longer belong to the codegen. If the customization is YAML-expressible, fix the YAML, do not opt out of regens.
+
+---
+
+## Resources
+
+- **Templates**: this skill has no `assets/`. The CLI itself owns its emission templates (`aurora-catalyst-cli/src/templates/`).
+- **Documentation**: see [references/](references/) for the conciliation algorithm and schema versioning details.
+- **CLI source of truth**: `aurora-catalyst-cli/` (the published `@aurorajs.dev/catalyst-cli` package).
+- **Schema source of truth**: SchemaStore catalog → `aurora-1.3.json` (or latest) — see `references/schema-versioning.md`.