@aurorajs.dev/catalyst-cli 1.0.2 → 2.0.0

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

@@ -8,7 +8,7 @@ description: >
 license: MIT
 metadata:
   author: aurora
-  version: '1.1'
+  version: '1.2'
   auto_invoke:
     'Analyzing or editing *.aurora.yaml files, schema validation, field
     semantics'
@@ -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:`.
@@ -65,9 +73,9 @@ aggregateProperties:
 **All modules MUST include these fields:**
 
 1. `rowId` (after `id`) — `bigint`, autoIncrement, unique
-2. `createdAt` (end) — `timestamp`, nullable
-3. `updatedAt` (end) — `timestamp`, nullable
-4. `deletedAt` (end) — `timestamp`, nullable
+2. `createdAt` (end) — `dateTime`, nullable
+3. `updatedAt` (end) — `dateTime`, nullable
+4. `deletedAt` (end) — `dateTime`, nullable
 
 **Field order:** `id` → `rowId` → ... module fields ... → `createdAt` → `updatedAt` → `deletedAt`
 
@@ -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,37 +180,71 @@ aggregateProperties:
     key: parentId
 ```
 
+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.
+
 ---
 
-### Web Component — `displayFields` (for `grid-select-element`)
+### Front Presentation — `displayFields`, `front.dialogWidth`, form layout
 
-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.
+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).
 
-```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
-```
+- **`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`.
+
+⚠️ **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.
 
-**Rendering rules:**
+⚠️ **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.
 
-- 1 field → `selected()?.field1`
-- 2+ fields → `selected() ? selected().field1 + ' (' + selected().field2 + ')' : ''`
-- Not defined → falls back to `?.name` (backward compatible)
+---
+
+### Property Flags — `readOnly` and `createOnly` (client writability)
+
+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.
+
+---
+
+### JSONB Arrays vs Real Relationships (CRITICAL RULE)
+
+**NEVER use `array`/`jsonb` fields to store references to other aggregates unless explicitly justified.**
 
-**`displayFields` values MUST be valid field names from the related module.**
+Decision question — ask it for EVERY multi-value field:
+
+> Does each stored value reference an aggregate with its own identity
+> (own table, own lifecycle, own admin screen)?
+
+- **YES** → real `many-to-many` relationship with `pivot` config (canonical example: `permissions` in `cliter/iam/role.aurora.yaml`). An `array` of foreign IDs is a hidden relationship: no FK integrity (dangling IDs when the target is deleted), value drift if you denormalize labels, no Query DSL filtering, no reporting joins, and no `grid-select-multiple-elements` widget support.
+- **NO** → array/jsonb is legitimate, in exactly four categories:
+
+| # | Category | Rule | Real example |
+| - | -------- | ---- | ------------ |
+| 1 | Value arrays without identity | Plain strings/enums that reference nothing | `iam/account.tags`, `tools/webhook.events`, `translatedLocales` |
+| 2 | Deliberate snapshots | Frozen copy at a point in time; drift is the feature, not a bug | `production-order-position.equipments` |
+| 3 | Explicit denormalized caches | Hot-path performance copy; prefix with `d` and name the re-sync owner | `iam/account.dPermissions`, `.dTenants` |
+| 4 | Multi-tenancy | `tenantIds` GIN array | `message/inbox.tenantIds` |
+
+**Every exception MUST state its category and sync semantics in the field `description`** (see `production-order-position.equipments`: it explicitly documents "snapshot, NOT auto-synced, reassign to refresh"). A jsonb field holding foreign aggregate IDs with no such justification is a schema defect — refactor it to a pivot.
 
 ---
 
@@ -253,7 +312,11 @@ Fixed set of options? ────YES───> type: enum with enumOptions
       │
       NO
       │
-Date and time? ────YES───> type: timestamp
+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
       │
@@ -286,6 +349,7 @@ User explicitly requested edit? ────YES───> Edit mode
 | Write "The price" as description          | Explain context: "Retail price in base currency..." |
 | Use `float` for money                     | Always use `decimal` with proper scale            |
 | Duplicate relationship definitions        | FK side uses `type: id`, inverse uses `type: relationship` |
+| Store foreign aggregate IDs in jsonb arrays | Use `many-to-many` + `pivot`; jsonb only for the 4 justified categories |
 
 ---
 

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
@@ -103,6 +103,30 @@ the user sees after selecting an element in the dialog.
 **Note:** Always prefer defining `displayFields` — the `.name` fallback only works if the
 related entity has a `name` field.
 
+### Dialog Width for Detail Forms
+
+When a module uses `front.detailMode: dialog`, set `front.dialogWidth` to size the create/edit
+dialog to the form's density. It has no effect under `detailMode: view`.
+
+```yaml
+front:
+  detailMode: dialog
+  dialogWidth: lg
+```
+
+**Token guidance:**
+
+| `dialogWidth` | Best for                                      |
+| -------------- | ---------------------------------------------- |
+| `sm`           | 1–2 field forms                                |
+| `md`           | Typical forms (default when unset)             |
+| `lg`           | Dense forms, several fields/sections           |
+| `xl`           | Very wide or multi-column forms                |
+| `full`         | Near-full-screen, the heaviest forms           |
+
+**Note:** tokens express intent (a definite, responsive, viewport-bounded width), not a pixel
+value — this is why raw CSS widths are not accepted here.
+
 ## Analysis Workflow
 
 ### 1. Locate YAML Files
@@ -159,7 +183,7 @@ Check for:
 
 ```yaml
 - name: publishedAt
-  type: timestamp
+  type: dateTime
   nullable: true
   description: >
       Timestamp when the book was published. NULL indicates unpublished.

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

@@ -14,13 +14,49 @@
 | Small numbers       | `smallint`      | -                              | 0-255 range                                   |
 | Money/decimals      | `decimal`       | `decimals: [precision, scale]` | Never use float for money                     |
 | Approximate         | `float`         | -                              | Scientific only                               |
-| Date + time         | `timestamp`     | -                              | Most common                                   |
-| Date only           | `date`          | -                              | Birthdays, deadlines                          |
+| Date + time (ISO)   | `dateTime`      | -                              | An instant in a Postgres `timestamp` column (timezone-bearing unless `applyTimezone: false`), written as an ISO string, read back as raw Postgres text — see "How a date value travels" below (e.g. `expiresAt`) |
+| Date only           | `date`          | -                              | A calendar day in a Postgres `date` column — no time, no timezone (birthdays, deadlines) |
+| Epoch (numeric)     | `timestamp`     | -                              | Integer Unix epoch (`number`) in a `bigint` column; a string is rejected, even a numeric one; rarely needed |
 | True/false          | `boolean`       | -                              | Use is*/has*/can\* prefix                     |
 | Fixed options       | `enum`          | `enumOptions: [...]`           | Document each option                          |
 | Structured data     | `json`, `jsonb` | -                              | Use jsonb for PostgreSQL                      |
 | Navigation property | `relationship`  | `relationship: {...}`          | One-to-many, many-to-many inverse side        |
 
+## How a date value travels — the runtime chain
+
+Authoring picks the type; this is what each type then does at runtime. Read it before touching a
+form seed, a table cell or a type handler. The GraphQL layer transforms NOTHING:
+`GraphQLISODateTime` and `GraphQLTimestamp` are declared in `core.graphql` with no `@Scalar()`
+implementation, so graphql-js serializes them with `identityFunc` and the driver's raw value
+reaches the browser unchanged. The scalar's name promises nothing.
+
+| Link                        | `date`                                                    | `dateTime`                                                                     | `timestamp`                                                                               |
+| --------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
+| Drizzle column              | `date(col, { mode: 'string' })`                           | `timestamp(col, { mode: 'string', withTimezone: true })`                       | `bigint(col, { mode: 'number' })`                                                         |
+| Value the browser READS     | `2026-08-01`                                              | `2026-08-30 22:00:00+00` — raw Postgres text: a space, not `T`; `+00`, not `Z` | an epoch number                                                                           |
+| Type handler on WRITE       | `validate` only: rejects anything but a real `YYYY-MM-DD` | `validate` + `sanitize`: normalizes any parseable value to UTC ISO             | `validate` only: rejects anything but a safe integer epoch — a string, even a numeric one |
+| Form model seed             | `init?.x ?? null`                                         | `init?.x ?? null`                                                              | `init?.x ?? null`                                                                         |
+| Form control                | `<au-date-picker>`                                        | `<au-datetime-picker>`                                                         | —                                                                                         |
+| Display (`DateCell` `kind`) | `formatIsoDate` → `DD-MM-YYYY`, never converted           | `formatIsoDateTime` → `DD-MM-YYYY HH:mm` in the viewer's timezone              | —                                                                                         |
+
+Two consequences no single file shows:
+
+- **Read shape ≠ write shape for `dateTime`.** What you send may be ISO; what you read back is
+  Postgres text. Never assert an ISO string on a value read from the API. This is MORE load-bearing
+  now that the form seeds the raw value verbatim: when the user does not touch the control, that
+  Postgres text round-trips back to the server untouched, and it is the server's `dateTime` write
+  handler — not the form model — that normalizes it to UTC ISO before persisting.
+- **A `date` is never converted; a `dateTime` always is.** Converting a `date` to a timezone moves
+  it to the neighbouring day; NOT converting a `dateTime` shows the reader someone else's clock.
+  `DateCell`'s `kind` is the column's TYPE, not a formatting preference.
+
+No handler declares `format()`: the server applies no timezone to any date field. Sources: the
+column mappers in `packages/cli/src/generator/domain/config.ts`, the handlers under
+`packages/core-back/src/modules/type-handlers/handlers/`, the helpers under
+`frontend/src/@aurora/lib/`.
+
+---
+
 ## Varchar Length Standards (Byte-Optimized)
 
 **IMPORTANT: When defining varchar fields, ALWAYS use one of these standard lengths.**
@@ -80,3 +116,149 @@ These lengths are optimized for PostgreSQL byte storage efficiency:
 | Long description   | 1022               |
 | URL/Link           | 2046               |
 | Slug               | 2046               |
+
+---
+
+## Property flags: readOnly and createOnly
+
+A property in `*.aurora.yaml` can declare one of three writability states. `readOnly` and
+`createOnly` are mutually exclusive on the same property — declaring both is a load-time error
+(`catalyst generate` fails naming the file and the property, and writes nothing).
+
+### The three writability states
+
+| State | Who supplies the value, and when | Declared as |
+| ----- | --------------------------------- | ----------- |
+| Normal (default) | The client, on create AND on every update | no flag |
+| `createOnly: true` | The client, ONLY at creation — frozen forever after | `createOnly: true` |
+| `readOnly: true` | Never the client — a column default, a database trigger/procedure, or an internal backend flow (a lifecycle `status`, a cascade write) | `readOnly: true` |
+
+Concrete example already in this repo: `production-order-header.status` is `readOnly: true` — its
+column default fixes it to `PENDING` on create, and only the `provision` action / backend cascades
+change it afterward, never the client. A hypothetical external reference code chosen by the client
+once, at creation, and never editable afterward would be `createOnly: true`.
+
+### What each state emits, surface by surface
+
+| Surface | Normal | `createOnly: true` | `readOnly: true` |
+| ------- | ------ | ------------------- | ------------------ |
+| Create input (GraphQL) + create DTO, create-many input + DTO | present | **present** | excluded |
+| Update-by-id input (GraphQL) + DTO, update-many input + DTO | present | **excluded** | excluded |
+| Generated form, `new` mode — render / model / validators | rendered, validated | **rendered, validated** | absent everywhere |
+| Generated form, `edit` mode — render | editable | **rendered, `disabled()`** | absent |
+| Generated form, `edit` mode — emitted `save` payload | key present | **key OMITTED** (never emitted as `null`/`undefined`) | (already absent) |
+| Generated `*.field-schema.ts` entry | no entry | `createOnly: true` | `readOnly: true` |
+| Runtime write pipeline (`sanitizeRecord`, via `@ApplySchema`/`@Sanitize`) | accepted | key present on an **update** → `400`; on a **create** → accepted and written | key present, **any** operation → `400` |
+| Read surfaces (output type, list column, fragment) | unchanged | unchanged | unchanged |
+| Persistence column (Drizzle) | unchanged | unchanged | unchanged |
+
+The runtime distinction is operation-awareness: `readOnly` rejects a present key unconditionally;
+`createOnly` rejects it only when the write is an `update`. This is carried by a MANDATORY
+`operation: 'create' | 'update'` option on `@Sanitize` / `@ApplySchema` — both decorators accept
+ONLY the options-object form, and a call that omits `operation` fails to compile; there is no
+default. The generator declares `operation: 'create'` on create and create-many handlers,
+`operation: 'update'` on the two update handlers (by-id and bulk), and — counter-intuitively, since
+its payload type is the update-by-id input — `operation: 'update'` on the upsert handler too: five
+emission points in total, each stating its operation explicitly, whether or not the aggregate
+declares any `createOnly` property.
+
+### What does NOT belong in `createOnly`
+
+Three needs look similar but are a different mechanism — do not reach for `createOnly` for any of
+them:
+
+- **A UI-only lock.** Making the control look non-interactive on screen while the value is still
+  writable through the API (REST or GraphQL directly) is a form concern, not a schema flag — use
+  `widget` configuration. `createOnly` changes the WIRE contract itself (the key disappears from
+  the update input entirely); a UI lock never does.
+- **A system-computed value.** A value the client never supplies, in ANY operation, is `readOnly:
+  true`, not `createOnly`. `createOnly` requires the opposite: the client MUST be able to supply the
+  value once, at creation.
+- **A freeze conditioned on the record's state or a state machine.** For example, "immutable once
+  the record reaches an ACTIVE state" or "immutable only after the first related document is
+  issued." `createOnly` is unconditional — frozen from the moment the record exists, forever, with
+  no state check. A conditional freeze is hand-written logic in the handler, not a schema flag.
+
+### Coexistence: three hand-written guards are NOT migrated to `createOnly`
+
+`iam/account`, `hub/app`, and `tools/custom-field-definition` / `custom-field-option` each already
+freeze a field by hand, and none of them adopts `createOnly` — this is a deliberate decision, not a
+gap:
+
+| Site | Behavior today | Why it stays hand-written |
+| ---- | --------------- | -------------------------- |
+| `iam/account` (update-by-id handler) | `409 ConflictException` with a translated message; also covers the bulk update; compares against the PERSISTED value, so echoing back the SAME value is accepted | `createOnly` answers `400` on the key's mere presence — adopting it would change a documented public error code and would start rejecting an unchanged echoed value the current rule accepts |
+| `hub/app` (update-by-id handler) | Silently strips the frozen keys (`code`, `applicationId`) from the payload | `createOnly` rejects with `400` instead — a real behavior change for existing clients, which needs its own change |
+| `tools/custom-field-definition` / `custom-field-option` | `400 BadRequestException` naming the field | Already the same shape `createOnly` would produce, but migrating is a code change for zero behavioral gain — not done here |
+
+`createOnly` is the declarative mechanism for NEW fields going forward. None of these three existing
+guards is replaced by it.
+
+### The `createOnly` + `upsert` rule
+
+The generated `upsert` handler types its payload as the UPDATE input, and `createOnly` fields are
+excluded from that input by design. So an aggregate that declares `createOnly` while its upsert
+handler is still actually generated fails `catalyst generate` at load time — naming the aggregate,
+the property, and the remedy — before any file is written. The rule is keyed EXCLUSIVELY on
+`excludedOperations` — declare `upsert` there and the same aggregate generates normally.
+`excludedFiles` is deliberately NOT a suppression path for this rule: excluding
+only the upsert handler's own path still leaves the upsert RESOLVER generated, importing and
+injecting the handler class regardless, so the emitted backend does not compile; excluding the
+whole `src/@app/**` tree also removes every `*.field-schema.ts` file, so the runtime `createOnly`
+guard is never emitted at all while the still-generated `@api` contracts drop the key — a
+contract-only enforcement already measured insufficient to stop a write. Either shape leaves the
+module broken independent of `createOnly`, so use `excludedOperations` — the only mechanism that
+declares an operation coherently absent.
+
+### The `createOnly` + `autoIncrement` rule
+
+`buildFieldSchemaEntries` (property-mappers.ts) skips every `autoIncrement` property before it ever
+reaches `makeScalarEntry` — the only place that copies `createOnly` onto a generated
+`*.field-schema.ts` entry. So `createOnly` on an `autoIncrement` property has no runtime guard to
+attach to; the flag would silently do nothing. `catalyst generate` fails at load time naming the
+aggregate and the property, and the remedy is simply to drop `createOnly`.
+
+### Known limitation: `update-and-increment` is hand-written, not generator-aware
+
+`update-and-increment` ships a generated SERVICE but no generated handler — any handler driving it
+is hand-written. The generator's own `createOnly` wiring (the mandatory `operation` option on
+`@ApplySchema`/`@Sanitize`, above) only ever reaches the five write handlers it emits itself: create
+and create-many with `'create'`, update-by-id, bulk update and upsert with `'update'`. A
+hand-written `update-and-increment` handler is outside that reach: nothing in this codegen path
+declares `operation` for you, and the decorator will not compile without it. **If you hand-write an
+`update-and-increment` handler on an aggregate that declares `createOnly` properties, declare
+`operation: 'update'` yourself** on that handler's `@ApplySchema`/`@Sanitize` call — writing
+`operation: 'create'` there would compile but let the handler accept a `createOnly` key it should
+reject; the generator cannot choose this for you.
+
+### `readOnly` + `nullable: false` 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).
+
+### `readOnly` is the only spelling `core-back` accepts
+
+`readOnly` is the canonical, and only, spelling `sanitizeRecord` reads. The two places the flag
+travels through disagree on which spellings they accept, and that asymmetry is deliberate:
+
+- **YAML / CLI loader.** A property declaring `readonly: true` in `*.aurora.yaml` still loads
+  normally: the loader normalizes it to `readOnly` in memory and emits ONE deprecation warning
+  naming the file and the property before generating the `*.field-schema.ts`. Declaring BOTH
+  spellings on one property is a load-time error.
+- **`core-back` runtime.** `FieldSchemaScalar` has no `readonly` member at all — a hand-authored or
+  un-regenerated `*.field-schema.ts` that still carries the old key fails to compile as
+  `FieldSchema[]` (excess-property check), and if it reaches `sanitizeRecord` anyway (through a cast
+  or an unchecked consumer), the key is simply not read: the field is treated as writable, with no
+  warning.
+
+So a schema authored by hand or through the CLI's YAML normalization always ends up with the
+canonical `readOnly` key by the time it reaches the runtime — the compatibility surface lives
+entirely in the loader, not in `core-back`.