create-warlock 5.34.1 → 5.34.3

package/templates/warlock/skills/code-standards/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-standards
-description: 'Project-level TypeScript code standards for apps built on Warlock.js — `interface` vs `type`, access modifiers, no `any`, no inline-duplicated unions, file-naming suffixes (`.contract.ts` / `.type.ts` / `.service.ts` / `.model.ts` / `.resource.ts` / `.spec.ts`), single-responsibility files, FP-factory + internal-class pattern, brace-every-control-block readability with blank lines between consecutive blocks, JSDoc on public surface and non-obvious logic, error classes extending framework errors, async/await + `Promise.all`, `undefined` over `null`, Vitest co-located, Oxlint/Oxfmt. Triggers: writing/editing any `.ts` / `.tsx` file in this project; user asks "what are the code standards / style rules / conventions"; spawning a sub-agent that will write code; reviewing a diff for style issues; deciding `interface` vs `type`, when to use a class, where helpers live, how to name a file, or whether something needs JSDoc. Skip: pure-Markdown / JSON / YAML edits with no code change; runtime / behavior questions about a specific framework primitive — load the relevant `@warlock.js/<pkg>` skill instead; package-publishing or CI workflow questions.'
+description: "Shared TypeScript rules: contracts versus data types, function services, file names, app barrels, errors, async work, logging and Oxc enforcement. Use when writing or reviewing TypeScript. Use web-code-standards instead for web components, hooks and setup boundaries."
 ---
 
 # Code Standards
@@ -8,7 +8,7 @@ description: 'Project-level TypeScript code standards for apps built on Warlock.
 **Status:** Stable
 **Applies to:** All TypeScript in this project — services, models, resources, modules, app code, scripts.
 
-> **Sub-agent rule:** Before writing any code, read this file end-to-end and apply every rule. When spawning a sub-agent that will write code, prepend: _"First, read `skills/code-standards/SKILL.md` and apply every rule."_
+> **Sub-agent rule:** Before writing any code, read this file end-to-end and apply every rule. When spawning a sub-agent that will write code, prepend: _"First, read the `code-standards` skill and apply every rule."_
 
 The bar is **senior-level clean code**. Not "it compiles" — code that the next person on this codebase can read in one pass.
 
@@ -18,6 +18,7 @@ The bar is **senior-level clean code**. Not "it compiles" — code that the next
 
 ### 1.1 `interface` for contracts, `type` for data
 
+- Declaration-merging targets (for example framework module augmentations) also require `interface`.
 - `interface` describes a **contract** — anything with methods, anything a class implements, anything that holds actions.
 - `type` describes a **data shape** — plain objects, unions, tuples, mapped types, discriminated unions.
 
@@ -49,7 +50,7 @@ Never omit `public` / `private` / `protected`. Explicit is faster to read than i
 
 ```typescript
 // ✅
-export class CartService {
+export class Cart {
   public readonly currency: string;
   private items: CartItem[] = [];
   public add(item: CartItem) {
@@ -58,7 +59,7 @@ export class CartService {
 }
 
 // ❌
-export class CartService {
+export class Cart {
   readonly currency: string; // missing public
   items: CartItem[] = []; // missing private
   add(item: CartItem) {} // missing public
@@ -160,7 +161,7 @@ import { formatUserName } from "app/users/utils";
 import { listUsersService, formatUserName, User } from "app/users";
 ```
 
-The module-root barrel is the one that causes circular imports and tree-shaking misses. Sub-folder barrels are safe because they only group siblings of the same role.
+The module-root barrel is the one that causes circular imports and tree-shaking misses. This recommendation applies to server app modules under `src/app/**`. Web feature folders under `src/web/**` have no barrels: imports point to the exact component or hook file so client bundles stay lean and server-only code is never pulled through a barrel. See the `web-code-standards` skill.
 
 ### 2.3 No file extension in import paths
 
@@ -170,14 +171,24 @@ Always bare: `from "./order.service"`, never `from "./order.service.ts"` or `.js
 
 ## 3. File naming
 
-| Suffix         | Purpose                             | Example                |
-| -------------- | ----------------------------------- | ---------------------- |
-| `.contract.ts` | Interface only (blueprint)          | `payment.contract.ts`  |
-| `.type.ts`     | Types only (data shapes)            | `order.type.ts`        |
-| `.service.ts`  | Service class                       | `cart.service.ts`      |
-| `.model.ts`    | Domain model class                  | `user.model.ts`        |
-| `.resource.ts` | Output mapper (model → wire format) | `order.resource.ts`    |
-| `.spec.ts`     | Co-located test for a sibling `.ts` | `cart.service.spec.ts` |
+| Suffix                    | Purpose                                        | Example                                 |
+| ------------------------- | ---------------------------------------------- | --------------------------------------- |
+| `.contract.ts`            | Interface contract                             | `payment.contract.ts`                   |
+| `.type.ts`                | Data types                                     | `order.type.ts`                         |
+| `.service.ts`             | Named service function                         | `list-users.service.ts`                 |
+| `.controller.ts`          | HTTP handler function                          | `me.controller.ts`                      |
+| `.repository.ts`          | Framework repository subclass and instance     | `users.repository.ts`                   |
+| `.schema.ts`              | Seal schema and inferred type                  | `create-user.schema.ts`                 |
+| `.error.ts`               | Framework error subclass                       | `order-conflict.error.ts`               |
+| `.middleware.ts`          | Request middleware function                    | `require-owner.middleware.ts`           |
+| `.model.ts`               | Cascade model subclass                         | `user.model.ts`                         |
+| `.migration.ts`           | Timestamped model migration                    | `20-10-2026_12-00-00-user.migration.ts` |
+| `.seeder.ts` / `.seed.ts` | Seeder (starter uses `.seed.ts`)               | `users.seed.ts`                         |
+| `.page.tsx`               | Web page component                             | `index.page.tsx`                        |
+| `.setup.ts`               | Page, layout or root policy and server exports | `index.setup.ts`                        |
+| `use-*.ts`                | Named feature hook                             | `use-contact-form.ts`                   |
+| `.resource.ts`            | Output mapper                                  | `user.resource.ts`                      |
+| `.spec.ts` / `.test.ts`   | Co-located test                                | `cart.service.spec.ts`                  |
 
 **One primary export per file.** If a `.contract.ts` also defines closely-related data types used only by that contract, that's fine — but the primary export is the interface.
 
@@ -192,8 +203,8 @@ If the file's description needs an "and", split it. The same goes for classes an
 **File-level SRP.** If a file has more than one top-level helper that isn't a direct implementation detail of the main export, extract helpers into a `utils/` folder — one helper per file. The main file imports from leaf paths.
 
 ```
-❌ cart.service.ts holds CartService + calculateTax + formatLineItem + applyDiscount
-✅ cart.service.ts holds CartService only
+❌ cart.service.ts holds cartService + calculateTax + formatLineItem + applyDiscount
+✅ cart.service.ts holds cartService only
    utils/calculate-tax.ts
    utils/format-line-item.ts
    utils/apply-discount.ts
@@ -201,7 +212,7 @@ If the file's description needs an "and", split it. The same goes for classes an
 
 ### 4.2 Public API is functional, classes are an implementation detail
 
-The default shape of a public primitive is a **factory function returning a plain object**. Users of your service never call `new`.
+This rule governs app code: services are named functions such as `listUsersService(input)`. A stateful app primitive may use a **factory function returning a plain object**. Framework base classes are extended as their package skills require: models, repositories, connectors, and errors remain subclasses; resources returned by `defineResource` are constructed with `new`.
 
 Reach for a `class` in exactly three cases:
 
@@ -304,7 +315,7 @@ for (const item of items) {
 // ✅ the WHY isn't obvious from the code
 // Stripe returns idempotency_key on retry but not on first call —
 // fall back to the order id so downstream dedup still works.
-const key = response.idempotency_key ?? order.id;
+const key = response.idempotencyKey ?? order.id;
 ```
 
 ### 4.7 Pure helpers live outside classes
@@ -323,20 +334,19 @@ Define the class once, then throw it from the call site by name — the type its
 
 ```typescript
 // ✅ define
-import { HttpError } from "@warlock.js/core";
+import { ConflictError } from "@warlock.js/core";
 
-export class CartLockedError extends HttpError {
-  public readonly statusCode = 409;
+export class CartLockedError extends ConflictError {
   public constructor(public readonly cartId: string) {
     super(`Cart ${cartId} is locked`);
   }
 }
 
-// ✅ throw — the class name is the error code, the message stays useful
+// ✅ throw — the class identifies the exception; the HTTP formatter supplies the wire code
 import { CartLockedError } from "app/cart/errors/cart-locked.error";
 
 if (cart.isLocked) {
-  throw new CartLockedError(cart.id);
+  throw new CartLockedError(cart.get<string>("publicId"));
 }
 
 // ❌ bare Error — no status code, no type to catch, no classification
@@ -455,14 +465,14 @@ log.info("order-placed", { orderId, userId, total });
 **Other rules:**
 
 - Log at boundaries (request in, request out, error caught) — not every internal step.
-- **Redact at the source.** Tokens, passwords, credit card numbers, personal identifiers never appear in log context. Configure redaction once via `log.configure({ redact: ... })` — see `@warlock.js/logger/redact-sensitive-log-fields/SKILL.md`.
+- **Redact at the source.** Tokens, passwords, credit card numbers, personal identifiers never appear in log context. Configure redaction once via `log.configure({ redact: ... })` — see the `@warlock.js/logger` skill's `redact-sensitive-log-fields` topic.
 - `module` is the area of the app (`"orders"`, `"auth"`, `"payments"`), `action` is the verb-noun event (`"order-placed"`, `"login-failed"`, `"refund-issued"`). Both are searchable indexes — keep them consistent across the codebase.
 
 ---
 
 ## 9. Non-negotiable defaults
 
-Senior-team baseline rules. Each one prevents a real class of bug or incident. Each one is short because each one is unconditional. Deeper coverage lives in sibling skills — `skills/security-baseline/`, `skills/data-and-persistence/`, `skills/api-design/`, `skills/observability-and-resilience/`.
+Senior-team baseline rules. Each one prevents a real class of bug or incident. Each one is short because each one is unconditional. Deeper coverage lives in sibling skills — the `security-baseline` skill, the `data-and-persistence` skill, the `api-design` skill, the `observability-and-resilience` skill.
 
 ### 9.1 Validate untrusted input at the boundary
 
@@ -485,7 +495,7 @@ export type CreateOrderSchema = Infer<typeof createOrderSchema>;
 const input = request.body as CreateOrderSchema;
 ```
 
-Validation runs once at the route boundary; everything inward consumes the typed result. See `skills/security-baseline/SKILL.md` for the full input-trust model.
+Validation runs once at the route boundary; everything inward consumes the typed result. See the `security-baseline` skill for the full input-trust model.
 
 ### 9.2 Money is integer minor units, time is UTC at rest
 
@@ -500,13 +510,13 @@ type Order = { totalCents: number; placedAtUtc: Date };
 type Order = { total: number; placedAt: string }; // float money, ambiguous tz
 ```
 
-See `skills/data-and-persistence/SKILL.md`.
+See the `data-and-persistence` skill.
 
 ### 9.3 IDs in URLs are opaque
 
-Use UUIDs or nanoids for any identifier that crosses a process boundary — URLs, response bodies, log lines, webhooks. Never expose sequential primary keys: they leak business volume (anyone can tell `/orders/1042` means you've placed 1042 orders) and invite enumeration attacks.
+Use an opaque UUID for public resource IDs in URLs, responses, and webhooks. The starter models store a separate `publicId`, generated by `randomUUID()` from `node:crypto` through a Seal default, with a unique migration column. The resource emits `id: ["publicId", "string"]`; services look up `{ publicId: id }`, then use the model's internal identity for writes.
 
-Sequential keys are fine as internal database primary keys. They just don't leave the database.
+Cascade's default `id` is sequential (including its NoSQL-generated integer); `model.uuid` only stringifies the primary key. Neither creates an opaque identifier. Internal primary/foreign keys may remain numeric. Never use `find(publicId)` or repository `getCached(publicId)` unless the primary key was explicitly changed. The `data-and-persistence` skill covers the schema and migration.
 
 ### 9.4 Every external call has a timeout
 
@@ -514,7 +524,7 @@ HTTP, AI, queue, database driver — every call to something outside this proces
 
 `@warlock.js/http` accepts `timeout` per request and `timeout` per `Http` instance. Set a default at the instance level; override per request when a specific endpoint needs more.
 
-See `skills/observability-and-resilience/SKILL.md`.
+See the `observability-and-resilience` skill.
 
 ### 9.5 Idempotency keys for external side effects
 
@@ -524,7 +534,7 @@ This is the difference between "the network blipped" and "the customer got bille
 
 ### 9.6 One response envelope across the project
 
-Every HTTP response in the project uses the same shape — success and failure both. Pick once, document in `skills/api-design/SKILL.md`, use everywhere. The moment this rule lands, the frontend stops writing per-endpoint special cases.
+Every HTTP response follows the named success envelopes or the canonical `{ error: { code, message }, details?, requestId }` error envelope in the `api-design` skill. The moment this rule lands, the frontend stops writing per-endpoint special cases.
 
 ### 9.7 Config validated at boot, no scattered `process.env`
 
@@ -579,15 +589,14 @@ bounded regexes on input, one controller per file, `type` (not `kind`) as a
 union's discriminator. Each problem has a `WL` code and its fix
 (`npx warlock explain <CODE>`).
 
-For Oxlint, consider enabling these additional rules:
+The scaffold enables these Oxlint rules:
 
-- `typescript/explicit-member-accessibility` — enforces § 1.2
-- `typescript/no-explicit-any` — enforces § 1.3
-- `typescript/consistent-type-definitions` — supports § 1.1
-- `typescript/no-floating-promises` — enforces § 6.3 (requires `oxlint-tsgolint` and `options.typeAware: true`)
-- `typescript/await-thenable` (same type-aware engine requirement)
-- `curly` — enforces braces (§ 4.4)
-- `no-console` — enforces § 8
+- `typescript/explicit-member-accessibility` — § 1.2
+- `typescript/no-explicit-any` — § 1.3
+- `curly` — § 4.4
+- `no-console` — § 8
+
+`typescript/consistent-type-definitions` cannot express § 1.1's hybrid rule (interfaces for contracts, types for data); its global `type` or `interface` preference would contradict that rule, so it stays disabled. Review the distinction manually. `typescript/no-floating-promises` and `typescript/await-thenable` remain optional: both require `oxlint-tsgolint` and `options.typeAware: true`.
 
 Match `.oxfmtrc.json`: 100 columns, double quotes, semicolons, trailing commas and built-in import sorting.
 
@@ -619,7 +628,7 @@ Before any change ships:
 
 - [ ] Every untrusted input has a `@warlock.js/seal` schema at the boundary
 - [ ] Money fields are integer minor units, time stored as UTC
-- [ ] IDs exposed in URLs are opaque (UUID / nanoid)
+- [ ] IDs exposed in URLs are opaque (the starter uses a separate public UUID)
 - [ ] Every external call (HTTP, AI, queue, DB) has an explicit timeout
 - [ ] External side effects (payments, emails, webhooks) use idempotency keys
 - [ ] Response shape matches the project's canonical envelope

package/templates/warlock/skills/data-and-persistence/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: data-and-persistence
-description: 'How this project models, stores, and migrates data with `@warlock.js/cascade` — money as integer minor units (`total_cents`, `amount_cents`) with `currency` alongside, time as UTC `Date` columns named `<verb>_at` (e.g. `synced_at`, `checked_out_at`, `abandoned_at`), opaque IDs in URLs (UUID / nanoid), audit columns auto-managed by the framework (`created_at` / `updated_at`), soft-delete via cascade''s delete strategy (`@warlock.js/cascade/configure-delete-strategy/SKILL.md`), schemas defined with `v.object` and inferred into `Infer<>` types, models declared via `@RegisterModel()` + `Model<Schema>` + typed getters (`this.get<T>(key, default)`), migrations via `Migration.create(Model, {...columns}, { unique })` with column types `text() / integer() / double() / bool() / json() / arrayText()`, relations via `@BelongsTo("Name")` and `@HasMany("Name")`, snake_case columns + camelCase getters. Triggers: defining a model / schema / cascade blueprint; writing a migration; choosing a column type for currency, prices, totals, balances, refunds, fees; choosing how to store a timestamp / date; deciding ID format; adding audit columns; designing soft-delete vs hard-delete; defining relations (BelongsTo, HasMany); user asks "how do we store money", "UTC vs local time", "what ID format do we use", "should this be soft-deleted", "migration rules", "BelongsTo vs HasMany", "what does the model look like", "how do I add a column". Skip: API response shape (load `skills/api-design/SKILL.md`); query performance / N+1 / caching (load `skills/observability-and-resilience/SKILL.md`); pure business-logic refactors with no schema change; framework primitive deep-dive — load the relevant `@warlock.js/cascade/*` skill (define-model, paginate-results, configure-delete-strategy, etc.).'
+description: "Project persistence conventions: money, UTC dates, public UUIDs, Cascade models, migrations, indexes, relations and delete strategies. Use when changing stored data or model schemas. Use api-design instead for HTTP envelopes and resource output."
 ---
 
 # Data & persistence
@@ -8,7 +8,7 @@ description: 'How this project models, stores, and migrates data with `@warlock.
 **Status:** Stable
 **Applies to:** Every model, schema, migration, and persisted entity in `src/app/**`.
 
-How we store data so it survives a year of new requirements, a currency conversion bug, and a timezone-aware feature request. Framework mechanics live in `@warlock.js/cascade/skills/*` — this skill is the **project-level conventions** layered on top.
+How we store data so it survives a year of new requirements, a currency conversion bug, and a timezone-aware feature request. Framework mechanics live in the `@warlock.js/cascade` skill — this skill is the **project-level conventions** layered on top.
 
 > **Sub-agent rule:** Before writing any model, schema, or migration, read this file.
 
@@ -19,17 +19,17 @@ How we store data so it survives a year of new requirements, a currency conversi
 ### 1.1 The rule
 
 - Store money as **integers in the currency's smallest unit** — cents for USD, halalas for SAR.
-- Column name carries the unit: `total_cents`, `amount_cents`, `fee_cents`, `discount_cents`.
+- Column name carries the unit: `totalCents`, `amountCents`, `feeCents`, `discountCents`.
 - A `currency` column lives next to every money column (or once per row if the entity is mono-currency).
 
-The Cart model is the project's canonical example:
+For example:
 
 ```typescript
-// ✅ from cart.model.ts
+// ✅ example cart schema
 export const cartSchema = v.object({
   /* ... */
-  total_cents: v.number().default(0),
-  total_items: v.number().default(0),
+  totalCents: v.int().default(0),
+  totalItems: v.int().default(0),
   currency: v.string().default("USD"),
   /* ... */
 });
@@ -38,19 +38,19 @@ export const cartSchema = v.object({
 ### 1.2 Why never floats
 
 ```typescript
-0.1 + 0.2 === 0.3        // false
-1234.567 * 100           // 123456.69999999999
+0.1 + 0.2 === 0.3; // false
+1234.567 * 100; // 123456.69999999999
 ```
 
 Compound a million orders' subtotals across a payout report and you'll be off by enough to matter. Integer cents prevents this entire class of bug.
 
 ### 1.3 The AI-pricing exception
 
-`ai-models.input_price` and `ai-models.output_price` are stored as `v.number()` — not cents. This is **deliberate**: AI provider pricing is sub-cent per token (e.g. $0.000002), where integer minor units round to zero. The exception is *only* AI / token pricing; business money (orders, products, payments, balances, refunds) follows the cents rule.
+A token-pricing model may use a documented decimal or scaled sub-cent unit: AI provider pricing is sub-cent per token (e.g. $0.000002), where integer minor units round to zero. The exception is _only_ AI / token pricing; business money (orders, products, payments, balances, refunds) follows the cents rule.
 
 ### 1.4 Display formatting at the edge
 
-Formatting (`$12.99`, `12.99 SAR`) is the resource layer's job — see `skills/api-design/SKILL.md` § 5. The model and service work in cents; the resource converts.
+Formatting (`$12.99`, `12.99 SAR`) is the resource layer's job — see the `api-design` skill § 5. The model and service work in cents; the resource converts.
 
 ---
 
@@ -61,24 +61,24 @@ Formatting (`$12.99`, `12.99 SAR`) is the resource layer's job — see `skills/a
 - All timestamp columns store **UTC**, full stop.
 - The column type is `date()` in the migration; the schema type is `v.date()` returning `Date`.
 
-### 2.2 Naming — `<verb>_at`
+### 2.2 Naming — `<verb>At`
 
-Time columns end with `_at` and describe what happened, in past tense:
+Time columns end with `At` and describe what happened, in past tense:
 
-| Column          | Meaning                          |
-| --------------- | -------------------------------- |
-| `created_at`    | row was created                  |
-| `updated_at`    | row was last updated             |
-| `synced_at`     | row was synced from a source     |
-| `checked_out_at`| cart was checked out             |
-| `abandoned_at`  | cart was marked abandoned        |
-| `expires_at`    | row will become invalid          |
+| Column         | Meaning                      |
+| -------------- | ---------------------------- |
+| `createdAt`    | row was created              |
+| `updatedAt`    | row was last updated         |
+| `syncedAt`     | row was synced from a source |
+| `checkedOutAt` | cart was checked out         |
+| `abandonedAt`  | cart was marked abandoned    |
+| `expiresAt`    | row will become invalid      |
 
 ```typescript
-// ✅ from cart.model.ts
-synced_at: v.date().optional(),
-abandoned_at: v.date().optional(),
-checked_out_at: v.date().optional(),
+// ✅ example cart schema
+syncedAt: v.date().optional(),
+abandonedAt: v.date().optional(),
+checkedOutAt: v.date().optional(),
 ```
 
 ### 2.3 Conversion happens at the response layer
@@ -100,7 +100,22 @@ The project uses `dayjs` for time arithmetic and formatting (already in dependen
 
 ### 3.2 Project default
 
-Cascade generates string IDs by default for new records. Use those as the public identifier. Don't expose `_id` (Mongo) or sequential integers (Postgres serial) in URLs even if they exist internally.
+Cascade defaults to sequential `id` values (a NoSQL-generated integer or the SQL primary key). The `model.uuid` getter only stringifies the primary key; it does not generate a UUID. The starter keeps that internal key for relations and authentication and adds a separate public UUID:
+
+```typescript
+import { randomUUID } from "node:crypto";
+import { v } from "@warlock.js/seal";
+
+export const orderSchema = v.object({
+  publicId: v
+    .string()
+    .uuid()
+    .default(() => randomUUID()),
+  totalCents: v.int(),
+});
+```
+
+Add `publicId: string(36).unique()` in `Migration.create(Order, { ... })`; generate it server-side, and omit it from writable client schemas. A default is applied when the field is absent, not on every update. The resource emits `id: ["publicId", "string"]`. Resolve a validated route ID with `Order.findOne({ publicId: id })`, then write through that model instance. `find(id)` and repository `getCached(id)` still target the internal primary key. For an existing application, backfill a unique UUID per row before requiring this column; changing a resource cast to `"string"` does not make a sequential ID opaque.
 
 ### 3.3 Why
 
@@ -112,7 +127,7 @@ Sequential keys leak business volume (`/orders/42178` tells anyone you've placed
 
 ### 4.1 Framework-managed
 
-Cascade auto-adds `created_at` and `updated_at` to every model. You do **not** add them to the schema or migration — the framework handles them.
+Cascade timestamp storage names are driver-dependent: MongoDB defaults to `createdAt` / `updatedAt`, PostgreSQL to `created_at` / `updated_at`. `Migration.create` adds the driver's timestamp columns unless `{ timestamps: false }`; model writes maintain their configured columns. Keep the stored names aligned with the driver or explicitly declare the columns when customizing timestamps. API output keys remain `createdAt` / `updatedAt`: use `["created_at", "date"]` / `["updated_at", "date"]` source-key tuples for a PostgreSQL-backed resource. Do not claim that a camelCase schema key automatically reads a snake_case stored field.
 
 ### 4.2 Author tracking
 
@@ -120,15 +135,15 @@ For entities where "who created this" matters (most business entities), add auth
 
 ```typescript
 // ✅ from ai-model.resource.ts
-created_by: "string",
-updated_by: "string",
-deleted_by: "string",
+createdBy: "string",
+updatedBy: "string",
+deletedBy: "string",
 ```
 
 These store the user-id of the actor at the time of the action. Wire them in the service:
 
 ```typescript
-await ordersRepository.create({ ...input, created_by: user.id });
+await ordersRepository.create({ ...input, createdBy: user.get("publicId") });
 ```
 
 ### 4.3 What to audit
@@ -141,7 +156,7 @@ Every entity that's user-mutable: yes. Read-only reference data (countries, curr
 
 ### 5.1 Default to soft-delete for user-visible entities
 
-Soft-delete keeps the row, sets `deleted_at` + `deleted_by`. The entity is excluded from default queries but recoverable.
+Soft-delete keeps the row and sets the configured `deletedAt` column. Actor tracking such as `deletedBy` is app-owned. Cascade does not hide deleted rows automatically: add a global `whereNull("deletedAt")` scope or use the repository's active-read methods when you need active-only results.
 
 ### 5.2 Hard-delete for ephemeral data
 
@@ -154,7 +169,7 @@ Use hard-delete for:
 
 ### 5.3 Mechanics
 
-Configure the delete strategy at the model level — see `@warlock.js/cascade/configure-delete-strategy/SKILL.md` for the framework's per-model knobs (`paranoid`, `forever`, `cascade`).
+Configure the delete strategy at the model level — see the `@warlock.js/cascade` skill's `configure-delete-strategy` topic for the framework's per-model knobs (`deleteStrategy: "soft"`, `"permanent"`, or `"trash"`; per-call `destroy({ strategy })`).
 
 ### 5.4 Restore is admin-only
 
@@ -170,7 +185,7 @@ Never edit a shipped migration. Once it's on `main`, the only change is a new mi
 
 ### 6.2 File location
 
-Migrations live inside the model folder: `src/app/<module>/models/<model>/migrations/<timestamp>-<noun>.migration.ts`. The framework's `yarn cli migrate` discovers them.
+Migrations live inside the model folder: `src/app/<module>/models/<model>/migrations/<timestamp>-<noun>.migration.ts`. The framework's `npx warlock migrate` discovers them.
 
 ### 6.3 Definition shape
 
@@ -183,16 +198,16 @@ export default Migration.create(
   AiModel,
   {
     provider: text().notNullable(),
-    code: text().notNullable(),
+    providerModelId: text().notNullable(),
     name: text().notNullable(),
     context: integer().notNullable(),
-    is_free: bool().notNullable(),
-    input_price: double().notNullable(),
+    isFree: bool().notNullable(),
+    inputPrice: double().notNullable(),
     config: json().nullable(),
     features: arrayText().nullable(),
   },
   {
-    unique: [{ columns: ["provider", "provider_model_id"] }],
+    unique: [{ columns: ["provider", "providerModelId"] }],
   },
 );
 ```
@@ -218,9 +233,9 @@ If a backfill is going to touch millions of rows, gate it behind a feature flag
 
 ### 7.1 Every query path has a supporting index
 
-- Foreign keys are indexed by default.
+- Add an index for a frequently queried foreign key; do not assume declaring a relation adds one.
 - Any column you filter or sort on regularly gets an index.
-- Composite indexes match query order (`WHERE org_id = ? AND status = ?` → index `(org_id, status)`).
+- Composite indexes match query order (`WHERE orgId = ? AND status = ?` → index `(orgId, status)`).
 
 ### 7.2 Add the index alongside the query
 
@@ -228,23 +243,23 @@ If a new query is introduced, the index lands in the same PR. Don't push slow qu
 
 ### 7.3 Tooling
 
-`yarn db.indexes` runs the framework's index management. Define indexes declaratively in the migration's options.
+Define indexes alongside the migration using column `.index()` / `.unique()` or the migration options. See the `@warlock.js/cascade` skill's `write-migration` topic.
 
 ---
 
 ## 8. Schema conventions
 
-### 8.1 Column naming — snake_case
+### 8.1 Column naming — camelCase
 
-All database column names use `snake_case`: `created_at`, `total_cents`, `provider_model_id`. This matches the wire-format convention in resources.
+New model and database column names use `camelCase`: `createdAt`, `totalCents`, `providerModelId`. Resource output also uses camelCase. For legacy snake_case columns, use source-key tuples in the resource as shown in the `api-design` skill; do not rename a stored column merely by changing the output key.
 
-### 8.2 Foreign keys — `<noun>_id`
+### 8.2 Foreign keys — `<noun>Id`
 
-`user_id`, `organization_id`, `cart_id`. Always singular, always `_id` suffix. Cascade's `@BelongsTo("Name")` decorator wires the relation off this column by convention.
+`userId`, `organizationId`, `cartId`. Always singular, always `Id` suffix. Pass an explicit `foreignKey` to `@BelongsTo("Name", { foreignKey: "userId" })` when wiring a relation; match the stored column and the model schema.
 
 ### 8.3 Booleans — affirmative
 
-`is_active`, `is_free`, `has_shipped`, `was_refunded`. Never negative (`is_not_deleted`, `is_unverified`) — negative booleans break readability under negation (`!isNotDeleted` reads as a riddle).
+`isActive`, `isFree`, `hasShipped`, `wasRefunded`. Never negative (`isNotDeleted`, `isUnverified`) — negative booleans break readability under negation (`!isNotDeleted` reads as a riddle).
 
 ### 8.4 Enums — string in the column, enum in the schema
 
@@ -272,11 +287,11 @@ src/app/<module>/models/<noun>/
     <timestamp>-<noun>.migration.ts
 ```
 
-### 9.2 The model file shape (Cart is the gold standard)
+### 9.2 Example model file shape
 
 ```typescript
 // 1. schema first
-export const cartSchema = v.object({ /* columns */ });
+export const cartSchema = v.object({/* columns */});
 export type CartSchema = Infer<typeof cartSchema>;
 
 // 2. class with decorator
@@ -286,26 +301,26 @@ export class Cart extends Model<CartSchema> {
   public static schema = cartSchema;
 
   // 3. relations
-  @BelongsTo("Organization")
+  @BelongsTo("Organization", { foreignKey: "organizationId" })
   public organization?: Organization;
 
-  @HasMany("CartItem")
+  @HasMany("CartItem", { foreignKey: "cartId" })
   public items?: CartItem[];
 
   // 4. typed getters — one per persisted field accessed from app code
   public get totalCents() {
-    return this.get<number>("total_cents", 0);
+    return this.get<number>("totalCents", 0);
   }
 }
 ```
 
 ### 9.3 Typed getters over `.get<T>("field")` at call sites
 
-This is project policy (see memory `feedback_use_model_getters`). Every column accessed from application code gets a typed getter on the model. One line beats `cart.get<number>("total_cents")` across N call sites.
+This is project policy. Every column accessed from application code gets a typed getter on the model. One line beats `cart.get<number>("totalCents")` across N call sites.
 
 ### 9.4 Class-level JSDoc for non-obvious domain logic
 
-The Cart model has a multi-paragraph JSDoc explaining identity ownership, lead linkage, source-of-truth rules, and currency snapshotting. Mirror this for any model whose semantics aren't obvious from the columns alone.
+Explain identity ownership, source-of-truth rules, and persisted snapshots for any model whose semantics are not obvious from its columns.
 
 ---
 
@@ -314,16 +329,16 @@ The Cart model has a multi-paragraph JSDoc explaining identity ownership, lead l
 Before merging a change that touches a model, schema, or migration:
 
 - [ ] Money columns are `integer cents` with `currency` alongside (AI-pricing is the only exception)
-- [ ] Time columns end with `_at`, store UTC `Date`
+- [ ] Time columns end with `At`, store UTC `Date`
 - [ ] No timezone-adjusted timestamps in storage
 - [ ] IDs exposed in URLs / responses are opaque
-- [ ] Audit columns (`created_by`, `updated_by`) wired where author tracking matters
+- [ ] Audit columns (`createdBy`, `updatedBy`) wired where author tracking matters
 - [ ] Soft-delete strategy chosen deliberately, configured via cascade
 - [ ] Migration is forward-only, not editing a shipped file
 - [ ] Backfill is a separate migration / background job from the schema change
 - [ ] Every new query path has a supporting index
-- [ ] Column names snake_case, foreign keys `<noun>_id`
-- [ ] Booleans are affirmative (`is_active`, never `is_not_deleted`)
+- [ ] Column names camelCase, foreign keys `<noun>Id`
+- [ ] Booleans are affirmative (`isActive`, never `isNotDeleted`)
 - [ ] Enums defined once in `types/`, never repeated as string literals
 - [ ] Defaults declared in the schema, not only in the migration
 - [ ] Every accessed column has a typed getter on the model

package/templates/warlock/skills/git-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: git-workflow
-description: 'Git, branching, commit messages, PRs, and CI gates for this project — conventional commits with module-scoped types (`feat(orders): ...`, `fix(auth): ...`, `refactor(cart): ...`, `docs(users): ...`, `chore: ...`), branch naming (`feat/`, `fix/`, `chore/`, `refactor/`, `docs/` prefix + slug), PR size cap (~400 LoC), required reviewers, CI gates (`yarn tsc` / `yarn lint` / `yarn test` / `yarn audit --level=high`), no force-push to `main`, squash-merge policy, tagging and releases. Triggers: writing a commit message; opening / reviewing / merging a PR; naming a branch; setting up CI; user asks "commit format", "conventional commits", "branch naming", "how big should a PR be", "what CI gates do we need", "how do we release", "can I force push", "squash or merge", "scope in commit message", "what scopes are valid". Skip: code style inside files (load `skills/code-standards/SKILL.md`); deploy mechanics / pm2 setup; framework primitive questions; publishing / semantic-versioning of npm packages.'
+description: "Project Git conventions, branches, conventional commits, pull requests, review and CI gates. Use when preparing or reviewing commits and PRs. Use code-standards instead for implementation style."
 ---
 
 # Git workflow
@@ -200,14 +200,14 @@ A drive-by approve is worse than no approve — it gives false confidence. If yo
 
 Every PR runs these. All must pass before merge. The exact commands match `package.json` scripts:
 
-| Gate                         | Command                   | Blocks on                       |
-| ---------------------------- | ------------------------- | ------------------------------- |
-| Type-check                   | `yarn tsc`                | Any TS error                    |
-| Lint                         | `yarn lint`               | Any Oxlint error                |
-| Tests                        | `yarn test --run`         | Any failed test                 |
-| Coverage (recommended floor) | `yarn test:coverage`      | TBD per team policy             |
-| Dependency audit             | `yarn audit --level=high` | High / critical vulnerabilities |
-| Format check                 | `yarn format --check`     | Any unformatted file            |
+| Gate                         | Command                        | Blocks on                       |
+| ---------------------------- | ------------------------------ | ------------------------------- |
+| Type-check                   | `npm run tsc`                  | Any TS error                    |
+| Lint                         | `npm run lint:check`           | Any Oxlint error                |
+| Tests                        | `npm run test -- --run`        | Any failed test                 |
+| Coverage (recommended floor) | `npm run test:coverage`        | TBD per team policy             |
+| Dependency audit             | `npm audit --audit-level=high` | High / critical vulnerabilities |
+| Format check                 | `npm run format:check`         | Any unformatted file            |
 
 Additional rules:
 

package/templates/warlock/skills/module-boundaries/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: module-boundaries
-description: 'Architecture rules for how modules under `src/app/**` relate — each module owns one domain noun (`orders`, `users`, `carts`, `payments`); standard layout per module (`controllers/`, `services/`, `models/<noun>/`, `repositories/`, `schema/`, `resources/`, `types/`, `utils/`, `events/`, `errors/`, `routes.ts`); public surface exposed through sub-folder barrels (`services/index.ts`, `utils/index.ts`, `types/index.ts`) — NEVER a module-root `index.ts` re-exporting everything; no module reaches into another module''s internal files; zero circular dependencies between modules; inter-module communication is explicit — direct service call OR `@mongez/events` bus, never shared mutable globals; cross-cutting helpers live in `src/app/shared/`. Triggers: adding a new module under `src/app/**`; importing from another module; deciding where new code belongs; circular import error; Oxlint `import/no-restricted-paths` violation; user asks "can module A use module B''s internals", "how should modules talk", "where should this code live", "I''m getting a circular dependency", "what folders does a module need", "what goes in shared". Skip: intra-module file organization (load `skills/code-standards/SKILL.md` § 4); barrel mechanics within a module (load `skills/code-standards/SKILL.md` § 2.2); deploying / packaging / monorepo questions; framework primitive details — load relevant `@warlock.js/*` skill.'
+description: "Domain module ownership, dependency direction, app sub-folder exports, cross-module services and events, and shared helpers. Use when adding modules or changing imports between domains. Use code-standards instead for organization within one module."
 ---
 
 # Module boundaries
@@ -94,7 +94,7 @@ This is the one absolute rule:
 ✅ src/app/orders/types/index.ts           ← good
 ```
 
-See `skills/code-standards/SKILL.md` § 2.2 for the reasoning.
+See the `code-standards` skill § 2.2 for the reasoning.
 
 ---