@stacksjs/defaults 0.70.207 → 0.70.208

package/ai/skills/stacks-objects/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: stacks-objects
+description: Use when working with object manipulation in Stacks — deep merging with type safety, object mapping/transformation, strict key checking, typed entries/keys, property picking, clearing undefined values, or the DeepMerge utility type. Covers @stacksjs/objects.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Object Utilities
+
+Type-safe object manipulation helpers. All functions are exported from a single file.
+
+## Key Path
+- Core package: `storage/framework/core/objects/src/index.ts` (single file, all functions)
+
+## Dependencies
+- `@stacksjs/types` -- `DeepMerge` type
+- `@stacksjs/utils` -- `notNullish` filter function
+- `@stacksjs/validation` -- `isObject` type guard
+
+## Functions
+
+### objectMap -- Transform Object Key/Value Pairs
+```typescript
+function objectMap<K extends string, V, NK = K, NV = V>(
+  obj: Record<K, V>,
+  fn: (key: K, value: V) => [NK, NV] | undefined,
+): Record<K, V>
+```
+
+The callback receives `(key, value)` and must return either:
+- `[newKey, newValue]` tuple to include the entry
+- `undefined` to filter out the entry
+
+Implementation uses `Object.fromEntries(Object.entries(obj).map(...).filter(notNullish))`.
+
+```typescript
+// Transform values
+objectMap({ a: 1, b: 2 }, (k, v) => [k, v * 2])
+// { a: 2, b: 4 }
+
+// Rename keys
+objectMap({ a: 1, b: 2 }, (k, v) => [`prefix_${k}`, v])
+// { prefix_a: 1, prefix_b: 2 }
+
+// Swap key/value
+objectMap({ a: 1, b: 2 }, (k, v) => [v, k])
+// { 1: 'a', 2: 'b' }
+
+// Filter entries (return undefined to exclude)
+objectMap({ a: 1, b: 2, c: 3 }, (k, v) => k === 'b' ? undefined : [k, v])
+// { a: 1, c: 3 }
+```
+
+### deepMerge -- Deep Merge Objects
+```typescript
+function deepMerge<T extends object = object, S extends object = T>(
+  target: T,
+  ...sources: S[]
+): DeepMerge<T, S>
+```
+
+Recursively merges source objects into target. Handles multiple sources via recursive spread.
+
+Key behaviors:
+- Only merges "mergeable objects" (objects that are not arrays, checked via `isObject()` and `!Array.isArray()`)
+- Arrays are NOT deeply merged -- they are replaced entirely
+- Missing keys in target are created as empty objects `{}` before recursive merge
+- **Mutates the target object** -- the return value IS the modified target
+- Processes sources left to right
+
+```typescript
+const target = { a: 1, nested: { x: 1, y: 2 } }
+const source = { b: 2, nested: { y: 3, z: 4 } }
+const result = deepMerge(target, source)
+// result === target (same reference, mutated)
+// { a: 1, b: 2, nested: { x: 1, y: 3, z: 4 } }
+
+// Multiple sources
+const merged = deepMerge(defaults, userConfig, overrides)
+```
+
+The `DeepMerge<T, S>` type (from `@stacksjs/types`) provides full type inference:
+```typescript
+type DeepMerge<F, S> = MergeInsertions<{
+  [K in keyof F | keyof S]: K extends keyof S & keyof F
+    ? DeepMerge<F[K], S[K]>
+    : K extends keyof S ? S[K]
+    : K extends keyof F ? F[K]
+    : never
+}>
+```
+
+### objectPick -- Pick Properties by Key
+```typescript
+function objectPick<O extends object, T extends keyof O>(
+  obj: O,
+  keys: T[],
+  omitUndefined?: boolean,   // default: false
+): Pick<O, T>
+```
+
+Creates a new object with only the specified keys. Uses `reduce` internally.
+
+```typescript
+const user = { id: 1, name: 'John', email: 'john@test.com', password: 'secret' }
+objectPick(user, ['id', 'name', 'email'])
+// { id: 1, name: 'John', email: 'john@test.com' }
+
+// With omitUndefined=true, skips keys whose values are undefined
+const partial = { id: 1, name: 'John', bio: undefined }
+objectPick(partial, ['id', 'name', 'bio'], true)
+// { id: 1, name: 'John' }  (bio omitted)
+```
+
+- Only includes keys that exist in the object (`k in obj` check)
+- With `omitUndefined=true`, additionally skips keys where `obj[k] === undefined`
+
+### clearUndefined -- Remove Undefined Fields
+```typescript
+function clearUndefined<T extends object>(obj: T): T
+```
+
+**Mutates the object** by deleting keys whose values are `undefined`. Returns the same object reference.
+
+```typescript
+const data = { name: 'John', age: undefined, email: 'john@test.com' }
+clearUndefined(data)
+// data is now { name: 'John', email: 'john@test.com' }
+// Returns same reference as input
+```
+
+- Only removes `undefined` values -- `null`, `0`, `''`, `false` are preserved
+- Uses `delete obj[key]` for removal
+
+### isKeyOf -- Type Guard for Object Keys
+```typescript
+function isKeyOf<T extends object>(obj: T, k: keyof any): k is keyof T
+```
+
+Type guard that narrows `k` to `keyof T` if the key exists in `obj`. Uses `k in obj`.
+
+```typescript
+const config = { debug: true, verbose: false }
+const key: string = 'debug'
+
+if (isKeyOf(config, key)) {
+  // TypeScript knows: key is 'debug' | 'verbose'
+  console.log(config[key])  // type-safe access
+}
+```
+
+### objectKeys -- Strictly Typed Object.keys
+```typescript
+function objectKeys<T extends object>(obj: T): Array<`${keyof T & (string | number | boolean | null | undefined)}`>
+```
+
+Returns `Object.keys(obj)` with a stricter return type than the built-in `Object.keys()` (which returns `string[]`).
+
+```typescript
+const user = { name: 'John', age: 30 }
+const keys = objectKeys(user)
+// Type: ('name' | 'age')[]  (not string[])
+```
+
+### objectEntries -- Strictly Typed Object.entries
+```typescript
+function objectEntries<T extends object>(obj: T): Array<[keyof T, T[keyof T]]>
+```
+
+Returns `Object.entries(obj)` with a stricter return type than the built-in `Object.entries()` (which returns `[string, any][]`).
+
+```typescript
+const user = { name: 'John', age: 30 }
+const entries = objectEntries(user)
+// Type: ['name' | 'age', string | number][]
+```
+
+### hasOwnProperty -- Safe Property Check
+```typescript
+function hasOwnProperty<T>(obj: T, v: PropertyKey): boolean
+```
+
+Null-safe wrapper around `Object.prototype.hasOwnProperty.call()`. Returns `false` if `obj` is `null` or `undefined`.
+
+```typescript
+hasOwnProperty({ a: 1 }, 'a')     // true
+hasOwnProperty({ a: 1 }, 'b')     // false
+hasOwnProperty(null, 'a')          // false (no throw)
+hasOwnProperty(undefined, 'a')     // false (no throw)
+```
+
+## Gotchas
+- `deepMerge` **mutates the target object** -- it does not create a new object. The return value is the same reference as `target`.
+- `clearUndefined` **mutates the input object** -- it deletes properties in place.
+- `objectPick` creates a NEW object -- original is not affected.
+- `objectMap` creates a NEW object via `Object.fromEntries`.
+- `deepMerge` does NOT deeply merge arrays -- arrays from source replace arrays in target entirely.
+- `deepMerge` uses `isObject()` from `@stacksjs/validation` combined with `!Array.isArray()` to determine mergeability.
+- `objectMap` can filter entries by returning `undefined` from the callback -- filtered via `notNullish` from `@stacksjs/utils`.
+- `objectKeys` return type uses a template literal type to handle non-string keys.
+- `clearUndefined` only removes `undefined` -- `null` values are preserved.
+- `hasOwnProperty` accepts `null`/`undefined` objects without throwing.
+- `objectPick` with `omitUndefined=false` (default) includes keys even if their values are `undefined`, as long as the key exists in the object.
+- These utilities are also re-exported through `@stacksjs/utils`.

package/ai/skills/stacks-office-hours/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: stacks-office-hours
+description: Use for structured product brainstorming about Stacks features — two modes (startup diagnostic for new ideas, builder generative for existing features). Produces design documents, never code. Invoke with /stacks-office-hours.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# /stacks-office-hours — Product Brainstorming
+
+You are a product thinking partner for the Stacks ecosystem. You produce **design documents and strategic analysis**, never code.
+
+## Determine Mode
+
+- **New idea** → Startup Mode (diagnostic)
+- **Existing feature/package** → Builder Mode (generative)
+
+If context makes it obvious (e.g., a feature for an existing Stacks package), skip the question.
+
+---
+
+## Startup Mode: Diagnostic
+
+Work through 6 questions. Push back on vague answers.
+
+### 1. Demand Signal
+> "What evidence do you have that people want this?"
+Red flags: "Everyone needs this", no concrete evidence
+Green flags: GitHub issues, users building workarounds, measurable pain
+
+### 2. Existing Alternatives
+> "What do people use today? Why isn't that good enough?"
+
+### 3. Target User
+> "Describe the specific person who would use this."
+Red flags: "All developers"
+Green flags: Named personas, specific workflows
+
+### 4. Scope Trap
+> "What's the smallest version that would be useful?"
+
+### 5. Stacks Ecosystem Fit
+> "How does this interact with existing Stacks packages? Does it extend, replace, or stand alone?"
+Check against the 39+ existing packages. Flag duplication.
+
+### 6. Maintenance Burden
+> "Who maintains this? What's the ongoing cost?"
+
+### Diagnostic Output
+
+```
+## Idea Diagnostic: [name]
+
+### Verdict: [BUILD / ITERATE / PAUSE / KILL]
+
+### Strengths
+- [with evidence]
+
+### Concerns
+- [with evidence]
+
+### If proceeding, start with:
+[smallest deliverable that tests the core hypothesis]
+```
+
+---
+
+## Builder Mode: Generative
+
+### Step 1: Understand the Goal
+> "What should the user be able to do that they can't today?"
+
+### Step 2: Forced Alternatives
+
+For every design decision, generate 3 approaches:
+
+```
+### [Decision]
+
+**Minimal**: [simplest thing]
+- Pros / Cons / Build time
+
+**Ideal**: [right solution if complexity wasn't a factor]
+- Pros / Cons / Build time
+
+**Creative**: [lateral approach]
+- Pros / Cons / Build time
+
+**Recommendation**: [which and why]
+```
+
+### Step 3: Design Document
+
+```
+## Design: [feature name]
+
+### Problem
+[What user problem, specifically]
+
+### Solution
+[Chosen approach]
+
+### User Experience
+[Step-by-step: what does the user do?]
+
+### Technical Approach
+[How it fits into Stacks. Key data flows. Which @stacksjs/* packages involved.]
+
+### API Surface
+[CLI commands (buddy *), config options, package exports]
+
+### Edge Cases
+[Error states, empty states, invalid input]
+
+### Non-Goals
+[What this deliberately does NOT do]
+
+### Open Questions
+[Decisions needing input]
+```
+
+---
+
+## Rules
+
+- **Never write code.** Documents and analysis only.
+- **Push back on vague answers.** Demand evidence.
+- **Respect the Stacks ecosystem.** Check existing packages before suggesting new ones.
+- **Be direct about bad ideas.** A polite "KILL" saves time.
+- **One session, one idea.**
+
+## Downstream
+
+> **Design document complete.** Run `/stacks-plan-review` to get architecture review and implementation plan.

package/ai/skills/stacks-orm/SKILL.md

@@ -0,0 +1,342 @@
+---
+name: stacks-orm
+description: Use when working with the Stacks ORM — defining models with defineModel(), model relationships (hasOne, hasMany, belongsTo, belongsToMany, morphOne, hasManyThrough), attributes, traits, factories, computed properties, query building, transactions, or the 50+ built-in models. Covers @stacksjs/orm, storage/framework/orm/, and storage/framework/defaults/app/Models/.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript, SQLite >= 3.47.2
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks ORM
+
+## Key Paths
+- Core ORM package: `storage/framework/core/orm/src/`
+- ORM implementation: `storage/framework/orm/`
+- Model definitions: `storage/framework/defaults/app/Models/` (50+ models)
+- Application models: `app/Models/`
+- Default model templates: `storage/framework/defaults/app/Models/`
+- ORM type globals: `storage/framework/types/orm-globals.d.ts`
+- Attribute types: `storage/framework/types/attributes.ts` (240+ attributes)
+- Model events: `storage/framework/types/events.ts`
+
+## Source Files
+```
+orm/src/
+├── define-model.ts     # defineModel() + buildEventHooks() + buildTraitMethods()
+├── index.ts            # Re-exports orm/src + db + subquery + transaction + types
+├── db.ts               # Database query builder bridge
+├── subquery.ts         # Subquery support
+├── transaction.ts      # transaction(), savepoint(), transactional()
+├── model-types.ts      # ModelRow<T>, NewModelData<T>, UpdateModelData<T>
+├── types.ts            # ORM type definitions
+├── utils.ts            # modelTableName, getRelations, getFillableAttributes, etc.
+├── builder.ts          # Query builder integration
+├── generated/          # Auto-generated model types and table traits
+│   ├── types.ts
+│   ├── index.ts
+│   └── table-traits.ts
+└── traits/
+    ├── index.ts         # Re-exports all trait creators
+    ├── taggable.ts      # createTaggableMethods()
+    ├── categorizable.ts # createCategorizableMethods()
+    ├── commentable.ts   # createCommentableMethods()
+    ├── billable.ts      # createBillableMethods()
+    ├── likeable.ts      # createLikeableMethods()
+    └── two-factor.ts    # createTwoFactorMethods()
+```
+
+## defineModel() API (define-model.ts)
+
+Wraps bun-query-builder's `createModel()` with Stacks-specific enhancements:
+- Event dispatching via `traits.observe` (emits `{model}:created`, `{model}:updated`, `{model}:deleted` via `@stacksjs/events`)
+- Trait methods (billable, taggable, categorizable, commentable, likeable, 2FA)
+- Raw definition access for generators (`getDefinition()`, `_isStacksModel`)
+
+```typescript
+import { defineModel } from '@stacksjs/orm'
+
+export default defineModel({
+  name: 'Product',
+  table: 'products',
+  primaryKey: 'id',        // default: 'id'
+  autoIncrement: true,     // default: true
+
+  traits: {
+    useUuid: true,          // adds uuid column
+    useTimestamps: true,    // adds created_at, updated_at
+    useAuth: { usePasskey: true },  // adds auth columns + passkey support
+    useSocials: ['github'], // social login providers
+    useSearch: {            // search engine indexing
+      displayable: ['name', 'email'],
+      searchable: ['name', 'email'],
+      sortable: ['name', 'created_at'],
+      filterable: ['status']
+    },
+    useSeeder: { count: 10 },  // or just `true` (defaults to 10)
+    useApi: {
+      uri: 'products',
+      routes: ['index', 'store', 'show', 'update', 'destroy']
+    },
+    categorizable: true,    // adds category relations via categorizable table
+    taggable: true,         // adds tag relations via taggable table
+    commentables: true,     // adds comment relations (NOTE: plural 's' in key)
+    billable: true,         // adds Stripe integration methods
+    likeable: true,         // or { table?: string, foreignKey?: string }
+    observe: true,          // emit model events (true = all, or array: ['create','update','delete'])
+  },
+
+  // Relationships
+  hasOne: ['Subscriber'],
+  hasMany: ['Post', 'Order'],
+  belongsTo: ['User', 'Category'],
+  belongsToMany: ['Tag'],
+  hasOneThrough: ['Profile'],
+  morphOne: 'Image',       // or { model, morphName?, type?, id? }
+
+  indexes: [
+    { name: 'idx_email', columns: ['email'] },
+    { name: 'idx_composite', columns: ['email', 'name'] }
+  ],
+
+  attributes: {
+    name: {
+      order: 1,
+      fillable: true,
+      required: true,
+      unique: false,
+      validation: {
+        rule: schema.string().maxLength(100),
+        message: { maxLength: 'Name is too long' }
+      },
+      factory: (faker) => faker.lorem.word()
+    },
+    price: {
+      fillable: true,
+      required: true,
+      validation: { rule: schema.number().min(1) },
+      factory: (faker) => faker.datatype.number({ min: 100, max: 10000 })
+    },
+    status: {
+      fillable: true,
+      default: 'draft',
+      validation: { rule: schema.enum(['draft', 'published', 'archived']) }
+    },
+    password: {
+      hidden: true,  // excluded from JSON serialization
+      guarded: true, // not mass-assignable
+    }
+  },
+
+  // Computed properties (accessors)
+  get: {
+    fullName: (attrs) => `${attrs.first_name} ${attrs.last_name}`,
+    formattedPrice: (attrs) => `$${(attrs.price / 100).toFixed(2)}`
+  },
+
+  // Mutators (setters)
+  set: {
+    email: (attrs) => attrs.email?.toLowerCase()
+  },
+
+  // Model hooks (lifecycle callbacks)
+  hooks: {
+    afterCreate: (model) => { /* ... */ },
+    afterUpdate: (model) => { /* ... */ },
+    afterDelete: (model) => { /* ... */ },
+  },
+
+  dashboard: { highlight: true }  // highlight in admin dashboard
+} as const)
+```
+
+### How defineModel() Works Internally
+1. `buildEventHooks(definition)` -- if `traits.observe` is truthy, creates `afterCreate`/`afterUpdate`/`afterDelete` hooks that lazy-import `@stacksjs/events` and call `dispatch()`
+2. Merges event hooks with any user-defined hooks
+3. Calls `createModel(defWithHooks)` from bun-query-builder (provides typed query methods)
+4. `buildTraitMethods(definition)` -- checks each trait flag and creates method objects
+5. Returns `Object.assign(baseModel, traitMethods, definition)` + `getDefinition()` + `_isStacksModel`
+
+## Transactions (transaction.ts)
+
+```typescript
+import { transaction, savepoint, transactional } from '@stacksjs/orm'
+
+// Basic transaction -- auto-commit on success, auto-rollback on error
+const result = await transaction(async (tx) => {
+  await tx.insertInto('users').values({ name: 'John' }).execute()
+  await tx.insertInto('profiles').values({ user_id: 1 }).execute()
+  return 'success'
+})
+
+// With options
+await transaction(callback, {
+  retries: 3,
+  isolation: 'serializable',  // 'read committed' | 'repeatable read' | 'serializable'
+  readOnly: false,
+  onRollback: (error) => console.error(error),
+  afterRollback: () => { /* cleanup */ }
+})
+
+// Savepoints (nested transactions)
+await transaction(async (tx) => {
+  await tx.insertInto('users').values({ name: 'Bob' }).execute()
+  await savepoint(async (sp) => {
+    await sp.insertInto('logs').values({ action: 'created' }).execute()
+    // If this fails, only this savepoint rolls back
+  })
+})
+
+// Decorator-style -- wraps function to auto-run in transaction
+const createUser = transactional(async (tx, name: string, email: string) => {
+  const user = await tx.insertInto('users').values({ name }).returningAll().executeTakeFirst()
+  await tx.insertInto('profiles').values({ user_id: user.id }).execute()
+  return user
+})
+await createUser('Alice', 'alice@example.com') // auto-wrapped
+```
+
+Both `transaction()` and `savepoint()` delegate to `db.transaction()` and `db.savepoint()` from `@stacksjs/database`.
+
+## Trait Methods (traits/)
+
+### Taggable (when `traits.taggable: true`)
+Uses `taggable` table with polymorphic `taggable_type` + `taggable_id` columns.
+- `Model._taggable.tags(id: number): Promise<any[]>`
+- `Model._taggable.tagCount(id: number): Promise<number>` -- uses `count(*)`
+- `Model._taggable.addTag(id, { name, description? }): Promise<any>` -- auto-generates slug
+- `Model._taggable.activeTags(id): Promise<any[]>` -- filters `is_active = true`
+- `Model._taggable.inactiveTags(id): Promise<any[]>` -- filters `is_active = false`
+- `Model._taggable.removeTag(id, tagId): Promise<void>`
+
+### Categorizable (when `traits.categorizable: true`)
+Uses `categorizable` + `categorizable_models` pivot table.
+- `Model._categorizable.categories(id): Promise<any[]>` -- joins through pivot
+- `Model._categorizable.categoryCount(id): Promise<number>`
+- `Model._categorizable.addCategory(id, { name, description? }): Promise<any>` -- creates category if not exists, then links
+- `Model._categorizable.activeCategories(id): Promise<any[]>`
+- `Model._categorizable.inactiveCategories(id): Promise<any[]>`
+- `Model._categorizable.removeCategory(id, categoryId): Promise<void>` -- removes pivot link
+
+### Commentable (when `traits.commentables: true`)
+Uses `comments` table with `commentables_id` + `commentables_type` columns.
+- `Model._commentable.comments(id): Promise<any[]>`
+- `Model._commentable.commentCount(id): Promise<number>`
+- `Model._commentable.addComment(id, { title, body }): Promise<any>` -- status defaults to `'pending'`
+- `Model._commentable.approvedComments(id): Promise<any[]>` -- status = `'approved'`
+- `Model._commentable.pendingComments(id): Promise<any[]>` -- status = `'pending'`
+- `Model._commentable.rejectedComments(id): Promise<any[]>` -- status = `'rejected'`
+
+### Likeable (when `traits.likeable: true` or `{ table?, foreignKey? }`)
+Table defaults to `{tableName}_likes`, FK defaults to `{singular}_id`.
+- `Model._likeable.likes(id): Promise<any[]>`
+- `Model._likeable.likeCount(id): Promise<number>`
+- `Model._likeable.like(id, userId): Promise<any>`
+- `Model._likeable.unlike(id, userId): Promise<void>`
+- `Model._likeable.isLiked(id, userId): Promise<boolean>`
+
+### Billable (when `traits.billable: true`) -- Stripe integration
+All methods lazy-import `@stacksjs/payments`.
+- `createStripeUser(model, options)`, `updateStripeUser(model, options)`, `deleteStripeUser(model)`
+- `createOrGetStripeUser(model, options)`, `retrieveStripeUser(model)`
+- `defaultPaymentMethod(model)`, `setDefaultPaymentMethod(model, pmId)`, `addPaymentMethod(model, paymentMethodId)`, `paymentMethods(model, cardType?)`
+- `newSubscription(model, type, lookupKey, options)` -- returns `{ subscription, paymentIntent }`
+- `updateSubscription(model, type, lookupKey, options)`, `cancelSubscription(model, providerId, options)`
+- `activeSubscription(model)` -- queries `subscriptions` table for `provider_status = 'active'`, then retrieves from Stripe
+- `checkout(model, priceIds[], options)` -- supports `enableTax`, `allowPromotions` options
+- `createSetupIntent(model, options)`, `subscriptionHistory(model)`, `transactionHistory(model)`
+
+### Two-Factor Auth (when `traits.useAuth.useTwoFactor: true`)
+- `Model._twoFactor.generateTwoFactorForModel(model)` -- generates secret, calls `model.update()`
+- `Model._twoFactor.verifyTwoFactorCode(model, code): Promise<boolean>`
+
+## Auto-Generated System Fields
+- `id` -- primary key (auto-increment)
+- `created_at`, `updated_at` -- when `useTimestamps: true`
+- `uuid` -- when `useUuid: true`
+- `deleted_at` -- when soft deletes enabled
+- `stripe_id` -- when `billable: true`
+- `two_factor_secret`, `public_key` -- when `useAuth: { usePasskey: true }`
+
+## Naming Conventions
+- Model: PascalCase (`ProductVariant`)
+- Table: snake_case plural (`product_variants`)
+- Column: snake_case (`first_name`)
+- Foreign key: `{singular_model}_id` (`user_id`)
+- Pivot table: alphabetical sort of both table names (`category_product`)
+
+## ORM Utility Types (model-types.ts)
+```typescript
+type Def<T> = T extends { getDefinition: () => infer D } ? D : never
+type BelongsToForeignKeys<TDef>  // extracts { modelname_id: number } from belongsTo array
+type ModelRow<T> = ModelAttributes<Def<T>> & BelongsToForeignKeys<Def<T>>
+type NewModelData<T> = Partial<InferModelAttributes<Def<T>> & BelongsToForeignKeys<Def<T>>>
+type UpdateModelData<T> = Partial<InferModelAttributes<Def<T>> & BelongsToForeignKeys<Def<T>>>
+```
+
+## ORM Utility Functions (utils.ts)
+- `modelTableName(model: Model | string): Promise<string>` -- uses `model.table` or converts `model.name` to snake_case plural
+- `getModelName(model, modelPath): string` -- from definition or filename
+- `getTableName(model, modelPath): TableNames` -- from definition or snake_case plural of name
+- `getPivotTableName(modelA, modelB): string` -- alphabetical sort + join with `_`
+- `getRelations(model, name): Promise<RelationConfig[]>` -- processes hasOne, hasMany, belongsTo, hasOneThrough, belongsToMany, morphOne
+- `getHiddenAttributes(attrs): string[]` -- filters for `hidden: true`
+- `getGuardedAttributes(model): string[]` -- filters for `guarded: true`, returns snake_case
+- `getFillableAttributes(model, relations): string[]` -- filters for `fillable: true`, adds FK columns, stripe_id, uuid, etc.
+- `extractFields(model, file): Promise<ModelElement[]>` -- parses model file for field metadata
+- `findCoreModel(name): string` -- searches `storage/framework/defaults/app/Models/` recursively
+- `findUserModel(name): string` -- searches `app/Models/`
+- `fetchOtherModelRelations(modelName?): Promise<RelationConfig[]>` -- scans all models for relations pointing to this model
+- `formatDate(date): string` -- ISO format `YYYY-MM-DD HH:MM:SS`
+
+## Relationship Processing (utils.ts)
+Each relationship type is processed into a `RelationConfig` object:
+- **hasOne / hasMany**: FK = `{parent_snake}_id`, model key = `{related_snake}_id`
+- **belongsTo**: FK is empty string (set on the owning model's side), supports custom `foreignKey`
+- **belongsToMany**: auto-creates pivot table name via `getPivotTableName()`, supports `pivotTable`, `firstForeignKey`, `secondForeignKey` overrides
+- **hasOneThrough**: includes `throughModel` and `throughForeignKey`
+- **morphOne**: uses `{modelName}able` pattern, generates `_type` and `_id` columns
+
+## Model Events (when `traits.observe: true`)
+`observe: true` emits all three events. `observe: ['create', 'update']` emits only those.
+- `'{modelname}:created'` -- via `afterCreate` hook, lazy-imports `@stacksjs/events`
+- `'{modelname}:updated'` -- via `afterUpdate` hook
+- `'{modelname}:deleted'` -- via `afterDelete` hook
+
+If `@stacksjs/events` is not available (browser, tests), errors are caught and silently ignored.
+
+## Stub Types in index.ts
+The ORM exports stub types for commonly used models to keep typecheck green before code generation:
+- `UserModel`, `NewUser`, `User` (class stub with static `where`, `find`, `create`, `all`)
+- `Job`, `FailedJob` (query stubs)
+- `PaymentMethod` (CRUD stubs)
+- `CategorizableTable`, `CategorizableModelsTable`, `CommentablesTable`, `TaggableTable`
+
+## All 50+ Framework Models
+Content: Author, Page, Post, Comment, Tag, Category
+Users: User, Customer, Driver, Subscriber, SubscriberEmail
+Commerce: Product, ProductVariant, ProductUnit, Cart, CartItem, Order, OrderItem, Coupon, GiftCard, Manufacturer, Review, LicenseKey, DigitalDelivery, WaitlistProduct, WaitlistRestaurant
+Payments: Payment, PaymentMethod, PaymentProduct, PaymentTransaction, Subscription, Transaction, Receipt
+Shipping: ShippingMethod, ShippingRate, ShippingZone, DeliveryRoute
+Loyalty: LoyaltyPoint, LoyaltyReward, TaxRate
+System: Job, FailedJob, Error, Log, Notification, Activity, Request, Websocket, PrintDevice
+Marketing: Campaign, EmailList, SocialPost
+
+## CLI Commands
+- `buddy make:migration` -- create migration for model changes
+- `buddy generate:migrations` -- generate migrations from model diffs
+- `buddy migrate` -- run pending migrations
+
+## Gotchas
+- Models work directly via the dynamic ORM — no code generation step needed
+- `defineModel()` calls `createModel()` from bun-query-builder at runtime, providing all typed query methods immediately
+- Two ORM locations: `storage/framework/core/orm/` (package) and `storage/framework/orm/` (implementation)
+- Factories use `@stacksjs/faker` -- each attribute can have a `factory` function
+- The `hidden` attribute flag excludes fields from JSON serialization (e.g., passwords)
+- The `guarded` flag prevents mass assignment
+- The `fillable` flag explicitly allows mass assignment
+- Pivot tables for belongsToMany are auto-created using alphabetical naming of both table names
+- Model events are only emitted when `observe: true` (or array) trait is set
+- The trait key for commentable is `commentables` (with 's'), not `commentable`
+- Trait methods are accessed via underscore-prefixed properties: `_taggable`, `_categorizable`, `_commentable`, `_billable`, `_likeable`, `_twoFactor`
+- The `useAuth.useTwoFactor` check (not `usePasskey`) determines if two-factor methods are added
+- `defineModel()` calls `createModel()` from bun-query-builder which returns the typed query builder interface at runtime
+- Model file loading uses `findUserModel()` (app/Models/) with fallback to `findCoreModel()` (storage/framework/defaults/app/Models/)