@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

package/dist/templates/monorepo/.claude/skills/catalyst-backlog/frontier-worker-addendum.md

@@ -97,15 +97,17 @@ exist:
   {{WORKER_EDIT_COMMAND}} --subtask \
     --title "IPC bridge" \
     --desc-file .claude/worktrees/dispatch-b/subtask-desc.txt \
-    --labels tier:medium,lane:frontier,path:direct,bc:desktop \
+    --labels tier:medium,lane:frontier,path:direct,mode:headless,bc:desktop \
     --ac "Renderer can invoke a main-process handler and receive its result"
   ```
 
   Never pass `--parent`: {{TASK_ID}} IS the parent, already bound by the wrapper. `--title` and
   `--labels` are mandatory, plus exactly one of `--desc`/`--desc-file` (never both). `--labels` needs
-  exactly one `tier:`/`lane:`/`path:`/`bc:` (`tier:complex` forces `lane:frontier`, and `lane:local`
-  forces `tier:minor` — the local lane never accepts a `tier:medium` or `tier:complex` subtask), and
-  the description needs a `Test command:` line the same allowlist accepts — plus a
+  exactly one each of `tier:`/`lane:`/`path:`/`mode:`/`bc:` (`tier:complex` forces `lane:frontier`,
+  and `lane:local` forces `tier:minor` — the local lane never accepts a `tier:medium` or
+  `tier:complex` subtask; `mode:` must be exactly one legal value, same as the other three — a
+  missing or duplicated `mode:` is refused here for the same reason a missing `tier:`/`lane:`/`path:`
+  is), and the description needs a `Test command:` line the same allowlist accepts — plus a
   `Files to touch:` line if the subtask is `lane:local`. Mixing `--subtask` with any of the four
   flags above, or with `--view`, is refused.
 
@@ -134,4 +136,10 @@ the question for the person who reads it. Never assume the answer.
 
 Never run `git`, `gh`, or a package install command. The close commits, pushes and opens the PR
 itself once the mechanical checks and the acceptance gate pass; a worker that pushed would put work
-on the remote nothing verified. The worktree slot is already provisioned and installed.
+on the remote nothing verified. The worktree slot is already provisioned and installed — except
+`packages/cli`: its dependencies are installed, but its `dist/` is removed on every provision
+(the slot's previous occupant may have built it from different sources, so keeping it around would
+let you run the generator against someone else's templates without knowing it). **If your task
+needs the generator, run `pnpm cli:build` before the first `node packages/cli/bin/run.js`** — that
+build always has to happen in your own slot, on every attempt, regardless of what changed. Skip both
+commands entirely if your task never touches the generator.

package/dist/templates/monorepo/.claude/skills/catalyst-backlog/worker-system-prompt.md

@@ -8,8 +8,8 @@ beyond this system prompt and that user prompt.
 
 ## Repository facts
 
-- pnpm workspace monorepo: `backend/` (NestJS 11, Jest), `frontend/` (Angular 22, Vitest),
-  `packages/core-back` (`@aurorajs.dev/core-back`, Jest), `packages/core-front`.
+- pnpm workspace monorepo: `backend/` (NestJS 12, Vitest), `frontend/` (Angular 22, Vitest),
+  `packages/core-back` (`@aurorajs.dev/core-back`, Vitest), `packages/core-front`.
 - Run only the scoped test command the operating envelope gives you. Never run a whole suite.
 - Code style: Prettier, single quotes, trailing commas. Match the Prettier config of the repo and
   the surrounding code — do not guess an indentation width.

package/dist/templates/monorepo/.claude/skills/catalyst-cli/references/origin-conciliation.md

@@ -156,6 +156,21 @@ resolve it. Triage it once, into one of three destinations:
 | Actively harmful (e.g. the own-barrel imports that broke NestJS DI at boot — fixed in the templates on 2026-08-25) | That is a **template bug**, not a reconciliation problem. Rejecting it here cures this module only — the next `generate` emits it again, in every module. File it against `packages/cli` (framework mode owns the fix). |
 | Unclear | Reject and move on, knowing the `.origin` will recur. Recurrence is the cost of an unresolved divergence, not a malfunction. |
 
+**A fourth case the table above does not fit: a BC-scoped file re-proposing on EVERY module's
+regen, not just this one's.** Measured during `add-tenant-scope-decorators` (2026-09):
+regenerating `business-partner-portal/partner-contact` produced an `.origin` for
+`business-partner-portal.seeder.ts` proposing to drop its `TOOLS_KEY_VALUE_SEEDER` injection and
+`keyValueSeeder.seedAll(...)` call — content with nothing to do with tenant scoping. Rejected, and
+correctly so: seeding that BC's key-value config is real, wanted behavior. But this file lives at
+the BOUNDED-CONTEXT root (`<bc>.seeder.ts`), not under a module subdirectory — the generator
+regenerates it as a side effect of regenerating ANY module in the BC, so **the identical `.origin`
+will reappear the next time ANY OTHER module in `business-partner-portal` regenerates**, forever,
+regardless of what that regen is actually about. The "tell" that distinguishes this from ordinary
+per-module drift: check whether the diverging file sits at the BC root (`<bc>.seeder.ts`,
+`<bc>.module.ts`, `<bc>.relations.ts`) rather than under `<bc>/<module>/`. If it does, do not read
+its recurrence as a sign the reconciliation was wrong the first time — reject it again, every time,
+until the seeder's own content changes for a real reason.
+
 ---
 
 ## Session-aware merge — when YOU wrote some of the divergence
@@ -219,8 +234,65 @@ hand-merge.
 
 ---
 
+## Never run the packager while `.origin` files are pending
+
+`packages/cli/src/templates/backend/**` is a generated **mirror** of `backend/`, produced by
+`node scripts/packager/publish.mjs` and guarded by the CI gate *Check mirror <-> source drift*. It
+carries the same module layout, so any module you regenerate exists there too.
+
+**The packager copies `backend/` wholesale, untracked files included — so it copies pending
+`.origin` files straight into the mirror.** Regenerating does not do this; the packager does.
+Measured 2026-09-15 on T-82, as a controlled experiment on a tree carrying 26 pending `.origin`:
+
+| Step | Changes under `packages/cli/src/templates/` |
+|---|---|
+| after `generate back module --name=iam/account --force` | **0** |
+| after `node scripts/packager/publish.mjs` | **29** — the same 26 `.origin`, plus 3 silent rewrites |
+
+So a reconciliation that is merely half-finished stays local and recoverable. Run the packager on
+top of it and the same mess exists twice, in a tree nobody thinks to look at, and it reaches the
+commit.
+
+**The rule is an ordering rule.** Reconcile first, mirror last:
+
+```
+regenerate → reconcile every .origin → delete them → THEN run the packager
+```
+
+The packager belongs at the very end of a change, just before the pull request, where it is a
+required pre-push step for any diff touching `backend/`. It is never a step inside a
+reconciliation.
+
+**If the mirror is already dirty**, do not reconcile those copies — they are build output, and the
+next packager run overwrites them. Restore the whole path and let the final packager run reproduce
+it:
+
+```
+git checkout -- packages/cli/src/templates/
+git clean -fdq -- packages/cli/src/templates/
+```
+
+**Enumerate before you reconcile**, and never work from the list of files you expect:
+
+```
+git status --short | grep '\.origin'      # every pending .origin
+git status --short | grep -v '\.origin'   # the silent rewrites: DTOs, seeds, locks
+```
+
+That second line matters: some files are rewritten with NO `.origin` beside them — in the measured
+run, two DTOs and the bounded context's `seed.ts`. A `.origin`-only sweep misses them.
+
+If your lane forbids `git checkout` (the frontier lane does), restore each file by reading it with
+`git show HEAD:<path>` and rewriting it with `Write`.
+
 ## Pitfalls
 
+- **Invoke `origin accept|reject|ignore` as a bare command.** The dispatch lanes grant
+  `Bash(catalyst:*)` and `Bash(node packages/cli/bin/run.js:*)`, and the match is on the command's
+  PREFIX. Anything in front of the binary — a `\` line continuation, a `cd <dir> && `, an
+  `env VAR=1` — makes the granted rule miss, and a headless worker then reads the result as a flat
+  permission denial with no way forward. Measured 2026-09-15 on T-82: 9 consecutive denials of a
+  command the lane allows, because the string began with `\` and a newline.
 - **The `.origin` file already contains user preservation regions.** The codegen merges them in *before* writing `.origin`, so the proposal you see is not the raw template output. If a region's body is identical in current and origin, it is because the merge preserved it — that hunk is not a divergence the merge engine cares about.
 - **`accept` is atomic on POSIX**, non-atomic on Windows (`fs.renameSync` does not overwrite there; the implementation falls back to `unlink` + `rename`). If you are on Windows and the host crashes mid-`accept`, the current file may be missing for a millisecond. Acceptable; documented.
 - **A `noop` from `accept`/`reject`/`ignore` is not an error**, it means there was no `.origin` at the path (idempotent). If you expected one and got `noop`, the file was already reconciled or never had divergence.

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

@@ -35,11 +35,19 @@ Use this skill when:
 
 - [Types & Varchar Standards](types-reference.md) — Type selection guide, byte-optimized varchar lengths
 - [Patterns & Workflow](patterns-workflow.md) — Common patterns, analysis/editing workflows, change log template
+- [Front Presentation](front-presentation.md) — `displayFields`, `front.dialogWidth` tokens, form layout (`group`/`span`/`detailSort`), the auto-expand row rule, group-title i18n keys
 
 ---
 
 ## Critical Patterns
 
+### The YAML declares; the framework never infers
+
+Every flag is a decision of the developer for THAT entity only — see the golden rule in the root
+`CLAUDE.md` (Golden rules). When analyzing a schema, never propose a flag because a related entity
+has it (`hasTenant: true` on a parent says nothing about its children). Point out an apparent
+inconsistency and leave the decision to the developer.
+
 ### Module Description (REQUIRED)
 
 Every `*.aurora.yaml` must have a `description` property **before** `aggregateProperties:`.
@@ -80,12 +88,29 @@ aggregateProperties:
 | `camelCase`           | All field names     | `firstName`, `orderDate`, `totalAmount` |
 | `is*`, `has*`, `can*` | Boolean flags       | `isActive`, `hasChildren`, `canEdit`    |
 | `*At`                 | Timestamps          | `createdAt`, `updatedAt`, `publishedAt` |
-| `*Date`               | Date-only fields    | `birthDate`, `startDate`, `endDate`     |
+| `*Date`               | Date-only fields    | `birthDate`, `dueDate`, `invoiceDate`   |
 | `*Id`                 | Foreign keys        | `authorId`, `categoryId`, `parentId`    |
 | `sort`                | Display/UI ordering | `sort` (NOT `displayOrder`, `order`)    |
 
 ---
 
+### `date` vs `dateTime` — Which to Pick
+
+| Type       | Column semantics                                             | Naming | Examples                             |
+| ---------- | -------------------------------------------------------------- | ------ | ------------------------------------- |
+| `date`     | A calendar day — a Postgres `date` column, no time, no timezone | `*Date` | `birthDate`, `dueDate`, `invoiceDate` |
+| `dateTime` | An instant — a Postgres `timestamp` column, timezone-bearing unless `applyTimezone: false` | `*At`  | `createdAt`, `updatedAt`, `expiresAt` |
+
+Pick `date` when the field answers "which day", never "at what moment" — a birthday has no hour.
+Pick `dateTime` when the field marks a moment in time that could be compared, ordered, or displayed
+with an hour — an audit timestamp, an expiry instant. The `*Date`/`*At` naming convention above is
+the preferred signal of this choice for new fields, but the suffix never decides the type: an
+`*At` property is legitimately a `date` when the field answers "which day". Decide by the question
+the field answers. What each type then does at runtime — column, wire shape, handler, form seed,
+display — is in `types-reference.md` → "How a date value travels".
+
+---
+
 ### Field Descriptions (MANDATORY)
 
 **Every field MUST have a description that explains WHY, not WHAT:**
@@ -155,101 +180,48 @@ aggregateProperties:
     key: parentId
 ```
 
----
-
-### Web Component — `displayFields` (for `grid-select-element`)
-
-When a field uses `webComponent.type: grid-select-element`, define `displayFields` to control
-which fields from the related entity are shown in the readonly input.
-
-```yaml
-# ✅ CORRECT — displayFields defined
-- name: meterId
-  type: id
-  webComponent:
-    type: grid-select-element
-    displayFields:
-      - model
-      - serialNumber
-  relationship:
-    type: many-to-one
-    aggregateName: IsuMeter
-    modulePath: isu/meter
-    key: id
-    field: meter
-```
-
-**Rendering rules:**
-
-- 1 field → `selected()?.field1`
-- 2+ fields → `selected() ? selected().field1 + ' (' + selected().field2 + ')' : ''`
-- Not defined → falls back to `?.name` (backward compatible)
-
-**`displayFields` values MUST be valid field names from the related module.**
+A `modulePath` whose target `cliter/<bc>/<module>.aurora.yaml` does not exist is an authoring
+error: `catalyst generate` fails at its load step, naming the property, the declared `modulePath`,
+and the expected file path, before writing anything — a target that exists but has not been
+generated yet only prints a `[CROSS-BC RELATION SKIPPED]` warning at generation time.
 
 ---
 
-### Front Config — `front.dialogWidth` (for `front.detailMode: dialog`)
-
-`front.dialogWidth` controls how wide the create/edit dialog opens. It is **only meaningful
-when `front.detailMode: dialog`** — in `view` mode (full-route screen) the property is inert,
-since the page sizes itself by the layout, not by this token.
-
-```yaml
-front:
-  detailMode: dialog
-  dialogWidth: lg
-```
+### Front Presentation — `displayFields`, `front.dialogWidth`, form layout
 
-**Named tokens:** `sm | md | lg | xl | full`. Default `md` when unset.
+Three YAML surfaces drive how the generated UI looks. The rules that bite are here; examples,
+tables and mechanics are in [front-presentation.md](front-presentation.md).
 
-| Token  | Use for                                       |
-| ------ | ---------------------------------------------- |
-| `sm`   | Very short forms (1–2 fields)                   |
-| `md`   | Typical forms — the default                     |
-| `lg`   | Dense forms with several fields/sections         |
-| `xl`   | Very wide or multi-column forms                  |
-| `full` | Near-full-screen dialogs for the heaviest forms |
+- **`webComponent.displayFields`** (for `grid-select-element`) picks which fields of the related
+  entity the readonly input shows. Values MUST be valid field names of the related module. Unset
+  falls back to `?.name`.
+- **`front.displayField`** (aggregate-level, singular) drives the option label AND trigger text of
+  every OTHER relational widget — `select`/`multiple-select` and the `search-select` family.
+  Identifier (`email`) or `'{code} - {name}'` template; default `name`.
+- **`front.dialogWidth`** takes a named token — `sm | md | lg | xl | full`, default `md` — never
+  raw CSS. It is inert unless `front.detailMode: dialog`.
+- **Form layout** — `widget.group` (section), `widget.span` (1–12 on a 12-column grid) and
+  `widget.detailSort` (ordinal). ONE global sort drives everything: a group appears where its
+  first field appears, and there is no group-level sort key. Give every field a `detailSort`.
 
-Choose a larger token up front for forms with more fields that need more room from the start —
-don't wait until the dialog feels cramped to size it correctly.
+⚠️ **Every ROW must close at exactly 12, not the group total.** The generator fills rows left to
+right and silently widens the LAST field of a short row — `[4,4]` renders as `[4,8]`, and
+`[7,7,10]` sums to 24 yet renders as `[7,7,12]`. No warning is emitted.
 
-**Why tokens, not raw CSS:** each token declares *intent*, not a pixel value. It maps to a
-definite, responsive, viewport-bounded width, so the dialog never resizes with whatever content
-happens to be selected inside it. Raw CSS width values are intentionally not accepted — the
-generator turns the token into a definite Tailwind width class (mechanics documented in the
-`catalyst-cli` skill, not here).
+⚠️ **Name a group after the concept it holds, never after a field** — `contact`, not `email`.
+Group titles share one flat i18n key space with field labels, so a group named like a field
+renders its heading with that FIELD's translation, and it reads as correct.
 
 ---
 
-### Property Flag — `readonly: true` (client cannot instantiate or modify)
+### Property Flags — `readOnly` and `createOnly` (client writability)
 
-`readonly: true` on a property declares that NO client (REST or GraphQL) can ever set or change
-that value. It is the single switch for the whole contract — no per-surface opt-out:
-
-| Surface | Effect |
-| ------- | ------ |
-| Generated form (render, model, default, validators) | Property is absent from all four — not rendered, no FormGroup entry, no default, no `required`/`maxLength`/etc. validator |
-| Create/update inputs (GraphQL SDL) and DTOs (REST) | Property excluded — not optional, ABSENT |
-| Generated `*.field-schema.ts` | Entry carries `readonly: true`; the backend's `sanitizeRecord` (`@ApplySchema`/`@Sanitize`) REJECTS a write that carries the key, with a `400` naming the field |
-| Read surfaces (output type, list column, fragment) | UNCHANGED — still selected, still returned, still visible in the list |
-| Persistence column (Drizzle) | UNCHANGED — governed only by `nullable`/`defaultValue`/`type`/`index`, exactly as without the flag |
-
-Only the database (a column default or a trigger/procedure) or the backend's own write services
-(handlers calling a service directly, bypassing `@ApplySchema`) may set the value going forward.
-Real example: `production-order-header.status` — the column default fixes it to `PENDING` on
-create, and only the `provision` action / backend cascades change it afterward.
-
-**Schema warning — do not combine `readonly: true` with `nullable: false` and no way to fill the
-column.** If the property is `readonly: true` + `nullable: false` and NOTHING else populates the
-column (no `defaultValue`, no database trigger, no procedure), the INSERT will fail: no client can
-supply the value, and nothing else will. The generator cannot see triggers/procedures declared
-outside the YAML, so it does not fail-fast on this — verify by hand that some other mechanism
-fills the column before shipping a `readonly: true` + `nullable: false` property.
-
-`readonly` is orthogonal to `widget.isDetailHidden` (which only hides the control from the
-detail form — the property still lives in the model/payload) and to `type: 'secret'` /
-`type: 'password'` (which mask a value on read, not block a write).
+See [Types & Varchar Standards — Property flags: readOnly and createOnly](types-reference.md#property-flags-readonly-and-createonly)
+for the full contract: the three writability states, what each one emits surface by surface
+(create/update inputs and DTOs, the generated form, the field schema, the runtime pipeline), what
+does NOT belong in `createOnly`, the three hand-written guards that coexist without migrating to
+it, the `createOnly` + `upsert` generation-time rule, and the `readOnly` + `nullable: false`
+warning.
 
 ---
 
@@ -340,7 +312,11 @@ Fixed set of options? ────YES───> type: enum with enumOptions
       │
       NO
       │
-Date and time? ────YES───> type: dateTime   (ISO datetime string; `timestamp` is now a numeric epoch — rarely used)
+Date and time (an instant)? ────YES───> type: dateTime   (timestamp column, timezone-bearing unless `applyTimezone: false`; ISO string on write, raw Postgres text on read; `timestamp` is a numeric epoch — rarely used)
+      │
+      NO
+      │
+Calendar day only, no time? ────YES───> type: date   (Postgres `date` column; birthdays, deadlines)
       │
       NO
       │

package/dist/templates/monorepo/.claude/skills/catalyst-schema/front-presentation.md

@@ -0,0 +1,209 @@
+# Front Presentation — How the YAML Drives the UI
+
+## Web Component — `displayFields` (for `grid-select-element`)
+
+When a field uses `webComponent.type: grid-select-element`, define `displayFields` to control
+which fields from the related entity are shown in the readonly input.
+
+```yaml
+# ✅ CORRECT — displayFields defined
+- name: meterId
+  type: id
+  webComponent:
+    type: grid-select-element
+    displayFields:
+      - model
+      - serialNumber
+  relationship:
+    type: many-to-one
+    aggregateName: IsuMeter
+    modulePath: isu/meter
+    key: id
+    field: meter
+```
+
+**Rendering rules:**
+
+- 1 field → `selected()?.field1`
+- 2+ fields → `selected() ? selected().field1 + ' (' + selected().field2 + ')' : ''`
+- Not defined → falls back to `?.name` (backward compatible)
+
+**`displayFields` values MUST be valid field names from the related module.**
+
+Not to be confused with `front.displayField` (singular, aggregate-level) below — a different
+attribute for a different widget family.
+
+---
+
+## Aggregate — `front.displayField` (for `select`, `multiple-select`, and the `search-select` family)
+
+`front.displayField`, declared on the TARGET aggregate, controls the label the six select-type
+widgets below show for one of its rows — both the option list and the trigger/summary text.
+`grid-select-element` and `grid-select-multiple-elements` do not read it (see
+`webComponent.displayFields` above). Two shapes:
+
+- **Identifier** — a bare field name (`name`, `email`). Unset defaults to `name`.
+- **Template** — an interpolation pattern with one or more `{<field>}` placeholders
+  (`'{code} - {name}'`, `'{name} ({reference})'`). Text outside a placeholder, including a
+  separator, is emitted verbatim. A `null`/`undefined` field expands to an empty string.
+
+```yaml
+# cliter/production-planning/product.aurora.yaml
+front:
+  displayField: '{name} ({reference})'
+```
+
+Honored in both the form (`__module_name__-form.component.ts`) and the embedded-dialog form
+(`__module_name__-form-embed.component.ts`):
+
+- **`select` / `multiple-select`** (Spartan `<hlm-select>`) — the option list is a static Angular
+  interpolation of the resolved template, generated at codegen time (`{{ option.name }} ({{ option.reference }})`
+  for `'{name} ({reference})'`): each placeholder becomes its own `{{ option.<field> }}` binding, so
+  Angular's strict template type-checking (`strictTemplates`) catches a field that does not exist on
+  the target aggregate at compile time. The `[itemToString]` trigger label is `itemLabelOf(options, template)`
+  from `@aurora/lib`, given the SAME resolved template — both render identical text for the same
+  target.
+- **`search-select` / `multiple-search-select` / `async-search-select` / `async-multiple-search-select`**
+  — `ToOptionsPipe`, bound at `[options]`, given the same resolved template.
+
+Both `templateToAngularInterpolation` (`packages/cli/src/generator/domain/display-field.ts`, generator
+side) and `expandDisplayFieldTemplate` (`@aurora/lib`, runtime side, shared by `ToOptionsPipe` and
+`itemLabelOf`) parse the same `{<field>}` placeholder grammar. On the `select` / `multiple-select`
+path only, a literal `{`, `}`, or `@` outside a placeholder fails generation with an error that names
+the offending template — Angular would otherwise parse it as an interpolation or a control-flow
+block. The `search-select` family passes the template to `ToOptionsPipe` as a string and runs no
+such check.
+
+---
+
+## Front Config — `front.dialogWidth` (for `front.detailMode: dialog`)
+
+`front.dialogWidth` controls how wide the create/edit dialog opens. It is **only meaningful
+when `front.detailMode: dialog`** — in `view` mode (full-route screen) the property is inert,
+since the page sizes itself by the layout, not by this token.
+
+```yaml
+front:
+  detailMode: dialog
+  dialogWidth: lg
+```
+
+**Named tokens:** `sm | md | lg | xl | full`. Default `md` when unset.
+
+| Token  | Use for                                       |
+| ------ | ---------------------------------------------- |
+| `sm`   | Very short forms (1–2 fields)                   |
+| `md`   | Typical forms — the default                     |
+| `lg`   | Dense forms with several fields/sections         |
+| `xl`   | Very wide or multi-column forms                  |
+| `full` | Near-full-screen dialogs for the heaviest forms |
+
+Choose a larger token up front for forms with more fields that need more room from the start —
+don't wait until the dialog feels cramped to size it correctly.
+
+**Why tokens, not raw CSS:** each token declares *intent*, not a pixel value. It maps to a
+definite, responsive, viewport-bounded width, so the dialog never resizes with whatever content
+happens to be selected inside it. Raw CSS width values are intentionally not accepted — the
+generator turns the token into a definite Tailwind width class (mechanics documented in the
+`catalyst-cli` skill, not here).
+
+---
+
+## Form Layout — `widget.group`, `widget.span`, `widget.detailSort`
+
+These three properties lay out the fields inside a form section. All three are optional. A module
+that declares none renders a flat, single-section form. (`widget.tab` is the container ABOVE
+groups; it is not covered here.)
+
+| Property     | Type    | Range      | Meaning                                                                                                                                      |
+| ------------ | ------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `group`      | string  | non-empty  | The section this field belongs to. Fields that share a group render together under one `<h4>` title. Every group but the first is preceded by a separator. |
+| `span`       | integer | 1–12       | Width of the field on the form's 12-column grid. An out-of-range value is clamped at codegen time with a `console.warn`. Unset → a width picked by field type. |
+| `detailSort` | number  | ≥ 1        | Ordinal position of the field in the form, ascending. Unset sorts last. The sort is stable, so YAML declaration order breaks ties.            |
+
+```yaml
+# ✅ CORRECT — cliter/<bounded-context>/customer.aurora.yaml
+- name: code
+  type: varchar
+  widget:
+    group: identification
+    detailSort: 1
+    span: 2
+- name: name
+  type: varchar
+  widget:
+    group: identification
+    detailSort: 2
+    span: 4
+- name: surname
+  type: varchar
+  widget:
+    group: identification
+    detailSort: 3
+    span: 4
+- name: taxId
+  type: varchar
+  widget:
+    group: identification
+    detailSort: 4
+    span: 2
+```
+
+**One sort drives everything.** `detailSort` orders the flat list of all visible form fields,
+globally across the module — it knows nothing about groups. The form template then buckets that
+already-sorted list by `group`. So both the order of fields inside a group AND the order of the
+groups on screen are side effects of this single sort: a group appears where its first field
+appears. There is no group-level sort key.
+
+`group` is independent of `detailSort`: grouping works with neither declared. Give every field
+an explicit `detailSort` anyway, because that is what makes the group order deterministic and
+readable instead of an accident of YAML order.
+
+### The auto-expand rule — one row must close at exactly 12
+
+The generator never leaves a short row. It walks a group's spans left to right, filling rows of
+12 columns. A field that does not fit starts a new row. **If the last row is still short when the
+fields run out, the LAST field of the group is widened to fill it.**
+
+Widening is silent. You get no warning, and the field you carefully declared as `span: 4` renders
+at 8.
+
+⚠️ **The rule is per ROW, not per group total.** A group whose spans add up to a multiple of 12
+is NOT automatically safe:
+
+| Spans in a group | Sum | Renders as   | Why                                                            |
+| ---------------- | --- | ------------ | -------------------------------------------------------------- |
+| `[2,4,4,2]`      | 12  | `[2,4,4,2]`  | one full row                                                    |
+| `[5,3,4]`        | 12  | `[5,3,4]`    | one full row                                                    |
+| `[7,7,10]`       | 24  | `[7,7,12]`   | 7+7=14 overflows, so each field opens its own row; the last row holds 10 and is widened |
+| `[8,8,8]`        | 24  | `[8,8,12]`   | same — three rows of one field each                            |
+| `[4,4]`          | 8   | `[4,8]`      | single short row                                                |
+
+To keep your declared widths, read the spans in order and check that **every row you form closes
+at exactly 12**. Sum-of-the-group arithmetic is a trap.
+
+This pass runs once per container, and a group is a container. Groups therefore never interfere
+with each other: a short last row in `identification` widens a field in `identification` only.
+
+### The group title is an i18n key
+
+The template renders the title as `t('<bc-kebab>.<module-kebab>.<PascalCase(group)>')`. So
+`group: identification` in the `partner` BC's `customer` module resolves
+`partner.customer.Identification`.
+
+`catalyst generate` seeds that key with a PascalCase default, add-if-missing — an already
+translated value is never touched.
+
+**Group titles share ONE flat key space** with field labels, enum options and the module's own
+keys (`Title`, `<Singular>Details`, `No<Plural>Found`). The generator seeds group titles LAST, so
+add-if-missing always finds the rightful owner of a name already in place. A group therefore never
+takes a key away from anything.
+
+⚠️ **That protects the data, not your screen.** A group named after a field renders its `<h4>`
+with that FIELD's translation: declare a field `address` and a group `address`, and the section
+heading shows whatever `Address` was translated to. It reads as correct, so nobody investigates.
+The generator emits a `console.warn` for exactly this case — read it.
+
+**Name a group after the concept it holds, not after one of its fields** — `contact`, not
+`email`. The module's own key names deserve the same care: a group called `title` renders its
+heading with the list page's title text.

package/dist/templates/monorepo/.claude/skills/catalyst-schema/patterns-workflow.md

@@ -18,7 +18,7 @@
 
 ```yaml
 - name: deletedAt
-  type: timestamp
+  type: dateTime
   nullable: true
   description: >
     Soft delete timestamp. NULL means active record. When set, record is
@@ -183,7 +183,7 @@ Check for:
 
 ```yaml
 - name: publishedAt
-  type: timestamp
+  type: dateTime
   nullable: true
   description: >
       Timestamp when the book was published. NULL indicates unpublished.