@stacksjs/defaults 0.70.207 → 0.70.208

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

@@ -0,0 +1,267 @@
+---
+name: stacks-models
+description: Use when working with data models in Stacks — the defineModel() API, model attributes with validation and factories, relationships (hasOne/hasMany/belongsTo/belongsToMany), traits (useAuth, useUuid, useTimestamps, useSearch, useApi, billable, taggable, categorizable, commentable, likeable, observe), computed properties (get/set), model generation, and the 50+ built-in framework models. Covers model definitions 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 Models
+
+## Key Paths
+- Your models: `app/Models/` (create it; it does not exist in a fresh project)
+- Built-in models: `storage/framework/defaults/app/Models/` (62 files, grouped
+  into `commerce/`, `Content/`, `realtime/` and a flat top level)
+- `ModelOptions` / `Attribute` types: `storage/framework/core/types/src/model.ts`
+- Attribute presets: `storage/framework/types/attributes.ts`
+
+To customize a built-in model, create the same filename under `app/Models/` -
+`app/Models/User.ts` wins over the default. `buddy publish:model User` copies the
+default across as a starting point.
+
+## Writing a model
+
+Everything - schema, validation, factory, relationships, behavior - is declared
+in one `defineModel()` call. Migrations are derived from this; you do not write
+the SQL.
+
+```ts
+// app/Models/Product.ts
+import { defineModel } from '@stacksjs/orm'
+import { schema } from '@stacksjs/validation'
+
+export default defineModel({
+  name: 'Product',        // defaults to the file name
+  table: 'products',      // defaults to lowercase plural of `name`
+  primaryKey: 'id',       // default
+  autoIncrement: true,    // default
+
+  traits: {
+    useUuid: true,
+    useTimestamps: true,
+    useApi: { uri: 'products', routes: ['index', 'store', 'show', 'update', 'destroy'] },
+    useSearch: { searchable: ['name'], filterable: ['status'] },
+    observe: true,
+  },
+
+  belongsTo: ['Category'],
+  hasMany: ['Review'],
+
+  attributes: {
+    name: {
+      required: true,
+      fillable: true,
+      order: 1,
+      validation: {
+        rule: schema.string().min(3).max(100),
+        message: { max: 'Name must have a maximum of 100 characters' },
+      },
+      factory: faker => faker.commerce.productName(),
+    },
+    status: {
+      required: true,
+      fillable: true,
+      default: 'draft',
+      validation: { rule: schema.enum(['draft', 'published', 'archived']) },
+      factory: faker => faker.helpers.arrayElement(['draft', 'published', 'archived']),
+    },
+  },
+} as const)
+```
+
+`as const` is what the built-in models use - it narrows literal types so the
+generated model types stay precise.
+
+### Attribute fields
+
+`validation.rule` is the only required key on an attribute.
+
+| Field | Effect |
+|---|---|
+| `required` | Value required; emits a `NOT NULL` column |
+| `nullable` | Explicit nullability override |
+| `default` | Column default (`string \| number \| boolean \| Date`) |
+| `unique` | Unique constraint |
+| `type` | Force the column type instead of inferring from the rule |
+| `order` | Column order in the table and in dashboard forms |
+| `fillable` | Allow mass assignment |
+| `guarded` | Block mass assignment |
+| `hidden` | Exclude from JSON serialization (passwords, tokens) |
+| `foreignKey` | Disable, infer, or configure the FK constraint |
+| `factory` | `(faker) => value`, used by seeders and tests |
+| `validation` | `{ rule, message? }` - `rule` from `schema`, `message` keyed by rule name |
+
+### Traits
+
+| Trait | What it adds |
+|---|---|
+| `useUuid` | UUID column alongside the primary key |
+| `useTimestamps` (alias `timestampable`) | `created_at` / `updated_at`. On by default |
+| `useSoftDeletes` (alias `softDeletable`) | `deleted_at` plus soft-delete query scopes |
+| `useAuth` (alias `authenticatable`) | Auth columns; `{ usePasskey: true }` adds passkeys |
+| `useApi` | Generates REST actions and routes: `{ uri, routes }` |
+| `useSearch` (alias `searchable`) | Search-engine indexing: `{ displayable, searchable, sortable, filterable }` |
+| `useSocials` | OAuth identities, e.g. `['github']` |
+| `useActivityLog` | Writes an `Activity` row per change |
+| `observe` | Emits `{model}:created` / `:updated` / `:deleted` events |
+| `billable` | Stripe methods (`checkout()`, `activeSubscription()`, ...) |
+| `taggable` / `categorizable` / `commentable` / `likeable` | Pivot tables and their relation methods |
+
+Also at the top level: `indexes: [{ name, columns, unique?, where? }]` for
+composite and partial-unique indexes, and `dashboard: { highlight: true }` to
+feature the model in the admin UI.
+
+### Relationships
+
+`hasOne`, `hasMany`, `belongsTo`, `belongsToMany`, `hasOneThrough`,
+`hasManyThrough`, `morphOne`, `morphMany`, `morphTo`, `morphToMany`,
+`morphedByMany`. Each takes an array of model names, or an object form when you
+need to name the foreign key.
+
+### Computed properties and scopes
+
+```ts
+get: {
+  fullName: (model) => `${model.firstName} ${model.lastName}`,
+},
+set: {
+  password: (value) => makeHash(value),
+},
+scopes: {
+  published: (query) => query.where('status', 'published'),
+},
+```
+
+## Workflow
+
+```sh
+buddy make:model Product        # scaffold app/Models/Product.ts
+buddy generate:migrations       # diff models against the schema, emit SQL
+# review the generated file in database/migrations/
+buddy migrate                   # apply it
+buddy migrate:fresh --seed      # dev only: drop, re-migrate, seed
+```
+
+Models resolve at runtime through `createModel()` from `bun-query-builder` -
+there is no build step between editing a model and querying it. Only migrations
+need generating.
+
+## Seeding
+
+Seed data is declared on the model, through the `useSeeder` trait plus the
+per-attribute `factory` functions:
+
+```ts
+traits: {
+  useSeeder: {
+    count: 20,
+    // Optional: pin specific rows over the generated ones. Keys use the
+    // model's camelCase attribute names.
+    fixtures: [
+      { name: 'Flagship Widget', status: 'published' },
+    ],
+  },
+},
+```
+
+`buddy seed` walks every model carrying the trait and fills its table from the
+attribute factories. Nothing else is needed - no seeder files, no registration.
+
+```bash
+buddy seed                       # every model with a useSeeder trait
+buddy seed --fresh               # truncate each table first
+buddy seed --only Product,Review # just these models
+buddy seed --except User         # everything but these
+buddy seed --include-defaults    # framework built-ins too
+```
+
+A model with no `useSeeder` trait is never seeded. Auth and OAuth models are
+skipped on a non-fresh database so re-seeding cannot invalidate live sessions -
+pass `--allow-protected` to override.
+
+## All 62 built-in models by category
+
+### Users & Auth
+- **User** — name, email, password | traits: useAuth(passkey), useUuid, useTimestamps, useSocials(github) | hasOne: Subscriber, Driver, Author | hasMany: PersonalAccessToken, Customer
+- **Author** — name, email | belongsTo: User | hasMany: Post
+- **Customer** — name, email, phone, totalSpent, lastOrder, status, avatar | belongsTo: User | hasMany: Order, GiftCard, Review, Payment
+- **Driver** — name, phone, vehicleNumber, license, status | belongsTo: User | hasMany: DeliveryRoute
+- **Subscriber** — email, status, source | belongsTo: User | hasMany: SubscriberEmail
+
+### Content
+- **Post** — title, content, poster, excerpt, views, publishedAt, status, isFeatured | belongsTo: Author | traits: categorizable, taggable, commentable | seeder: 20
+- **Page** — similar to Post with taggable, categorizable
+- **Comment** — author info, approval, content fields
+- **Tag** — name(unique), slug(unique), description, postCount, color | seeder: 15
+- **Category** — name, description, slug, imageUrl, isActive, parentCategoryId, displayOrder | hasMany: Product | seeder: 10
+
+### Commerce (20+ models)
+- **Product** — name(max100), description, price(min1), imageUrl, isAvailable, inventoryCount, preparationTime, allergens(JSON), nutritionalInfo(JSON) | belongsTo: Category, Manufacturer | hasMany: Review, ProductUnit, ProductVariant, LicenseKey, WaitlistProduct, Coupon | seeder: 10, dashboard: highlighted
+- **ProductVariant** — SKU, options, pricing
+- **ProductUnit** — unit-specific pricing
+- **Cart** — status(active|abandoned|converted|expired), totalItems, subtotal, taxAmount, discountAmount, total, expiresAt, currency(USD), notes | hasMany: CartItem | belongsTo: Customer, Coupon
+- **CartItem** — quantity(min1), unitPrice, totalPrice, taxRate, taxAmount, discountPercentage, productName, productSku | belongsTo: Cart
+- **Order** — status, totalAmount, taxAmount, discountAmount, deliveryFee, tipAmount, orderType(DINE_IN|TAKEOUT|DELIVERY), deliveryAddress, specialInstructions | hasMany: OrderItem, Payment | belongsTo: Customer, Coupon | observe: true | seeder: 20
+- **OrderItem** — quantity(min1), price(min0), specialInstructions | belongsTo: Order, Product
+- **Coupon** — code(unique), discountType(fixed_amount|percentage), discountValue, minOrderAmount, usageLimit, usageCount, startDate, endDate | seeder: 15
+- **GiftCard** — code(unique), initialBalance, currentBalance, currency, status, recipientEmail, isDigital, isReloadable, expiryDate | seeder: 20
+- **Manufacturer** — manufacturer info
+- **Review** — rating(1-5), title, content(max2000), isVerifiedPurchase, isApproved, isFeatured, helpfulVotes, unhelpfulVotes | belongsTo: Product, Customer | seeder: 50
+
+### Shipping & Delivery
+- **ShippingMethod**, **ShippingRate** (weightFrom, weightTo, rate), **ShippingZone**
+- **DeliveryRoute** — driver, vehicle, stops, totalDistance | belongsTo: Driver
+- **DigitalDelivery** — name, downloadLimit, expiryDays, automaticDelivery
+- **LicenseKey** — key(XXXX-XXXX-XXXX-XXXX-XXXX), template, expiryDate, status
+
+### Payments & Financial
+- **Payment** — amount, method(creditCard|debitCard|paypal|...), status(pending|completed|failed|refunded), currency, transactionId(unique) | belongsTo: Order, Customer | seeder: 50
+- **PaymentMethod**, **PaymentProduct**, **PaymentTransaction**
+- **Subscription** — type, providerId, providerStatus, unitPrice
+- **Transaction** — standard transaction tracking
+- **TaxRate** — name, rate(0-100), type(VAT|GST|Sales Tax|Customs Duty), country, region, isDefault
+
+### Engagement & Marketing
+- **Notification** — type, channel, recipient, subject, body, status(pending|sent|delivered|failed|read) | belongsTo: User | seeder: 30
+- **Campaign** — name, type(email|sms|push|social|multi-channel), status, audienceSize, openRate, clickRate, budget | seeder: 10
+- **Activity** — type, description, subjectType, subjectId, causer, properties(JSON), ipAddress | belongsTo: User | seeder: 50
+- **EmailList**, **SocialPost**, **LoyaltyPoint** (walletId, points, source, expiryDate), **LoyaltyReward**
+
+### System
+- **Job** — queue, payload, attempts, available_at, reserved_at | seeder: 15
+- **FailedJob** — failed background jobs
+- **Error** — type, message, stack, status, additionalInfo | seeder: 10
+- **Log** — application logs
+- **Request** — method, path, statusCode, durationMs, ipAddress, memoryUsage, userAgent, errorMessage | seeder: 50
+- **Websocket** — connection tracking
+- **PrintDevice** — name, location, terminal, lastPing, printCount, isActive
+- **WaitlistProduct**, **WaitlistRestaurant** — waitlist tracking
+- **Receipt** — receipt records
+
+## CLI Commands
+- `buddy make:model [name]` — scaffold a model in `app/Models/`
+- `buddy publish:model [name]` — copy a built-in model into `app/Models/` to override it
+- `buddy generate:migrations` — diff models against the schema and emit SQL
+- `buddy migrate` / `buddy migrate:fresh --seed` — apply migrations
+- `buddy make:migration [name]` — hand-write a migration instead
+- `buddy make:factory [name]` — standalone factory
+- `buddy seed` — seed every model carrying a `useSeeder` trait
+
+## Gotchas
+- **No code generation step for models.** `defineModel()` calls `createModel()`
+  from bun-query-builder at runtime, so a model is queryable the moment you save
+  it. Only migrations are generated.
+- **Migrations come from models.** Change the model, run `buddy generate:migrations`,
+  review the SQL, then `buddy migrate`. Editing a generated migration by hand
+  will be overwritten by the next diff.
+- **`commentable`, not `commentables`.** `define-model` only checks the singular
+  key. The plural spelling used to type check while leaving the trait inert.
+- **Seeding is model-declared.** `useSeeder` sets the count and fixtures; the
+  per-attribute `factory` functions produce the values. There are no seeder
+  files to write or register.
+- **`hidden` is serialization, `guarded` is mass assignment.** They are different
+  protections; a password wants both `hidden` and no `fillable`.
+- **`validation.rule` is mandatory** on every attribute - it drives both request
+  validation and the inferred column type.
+- Dashboard-highlighted models (`dashboard: { highlight: true }`) appear
+  prominently in the admin UI.

package/ai/skills/stacks-new-feature/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: stacks-new-feature
+description: Use when adding a new feature end-to-end in a Stacks application — the complete workflow from model definition through migration, action, route, test, and deployment. Covers the recommended order of operations for building features.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Adding a New Feature to Stacks
+
+Step-by-step guide for building features end-to-end.
+
+## Workflow Overview
+
+```
+1. Model → 2. Migration → 3. Action → 4. Route → 5. Test → 6. Lint → 7. Deploy
+```
+
+## Step 1: Define the Model
+
+```typescript
+// Create or edit in storage/framework/defaults/app/Models/
+import { defineModel } from '@stacksjs/orm'
+import { schema } from '@stacksjs/validation'
+
+export default defineModel({
+  name: 'Article',
+  table: 'articles',
+  primaryKey: 'id',
+  autoIncrement: true,
+
+  traits: {
+    useTimestamps: true,
+    useSearch: {
+      searchable: ['title', 'content'],
+      sortable: ['title', 'created_at'],
+      filterable: ['status']
+    },
+    useApi: {
+      uri: 'articles',
+      routes: ['index', 'store', 'show', 'update', 'destroy']
+    },
+    useSeeder: { count: 10 },
+    observe: true
+  },
+
+  belongsTo: ['User'],
+
+  attributes: {
+    title: {
+      fillable: true,
+      required: true,
+      validation: { rule: schema.string().maxLength(200) },
+      factory: (faker) => faker.lorem.sentence()
+    },
+    content: {
+      fillable: true,
+      required: true,
+      validation: { rule: schema.string() },
+      factory: (faker) => faker.lorem.paragraphs(3)
+    },
+    status: {
+      fillable: true,
+      default: 'draft',
+      validation: { rule: schema.enum(['draft', 'published', 'archived']) },
+      factory: () => 'draft'
+    }
+  },
+
+  get: {
+    excerpt: (attrs) => attrs.content?.substring(0, 150) + '...'
+  }
+} as const)
+```
+
+## Step 2: Generate & Run Migration
+
+```bash
+buddy generate:migrations      # generate migration SQL from model diffs
+buddy migrate                  # apply migration
+buddy seed                     # seed with factory data
+```
+
+## Step 3: Create Actions
+
+```typescript
+// app/Actions/CreateArticle.ts
+export default {
+  name: 'CreateArticle',
+  description: 'Create a new article',
+
+  async handle(request: any) {
+    const title = request.get('title')
+    const content = request.get('content')
+    const user = await request.user()
+
+    const article = await Article.create({
+      title,
+      content,
+      user_id: user.id,
+      status: 'draft'
+    })
+
+    return { success: true, data: article }
+  }
+}
+```
+
+## Step 4: Define Routes
+
+```typescript
+// routes/api.ts (add to existing)
+route.group({ prefix: '/articles', middleware: ['auth'] }, () => {
+  route.get('/', 'Actions/ListArticles')
+  route.post('/', 'Actions/CreateArticle')
+  route.get('/{id}', 'Actions/ShowArticle')
+  route.put('/{id}', 'Actions/UpdateArticle')
+  route.delete('/{id}', 'Actions/DeleteArticle')
+})
+```
+
+Or rely on auto-generated routes from `useApi` trait — they're created automatically.
+
+## Step 5: Add Event Listeners (Optional)
+
+```typescript
+// app/Events.ts — add to existing
+{
+  'article:created': ['NotifySubscribers'],
+  'article:published': ['SendNewsletter', 'IndexInSearchEngine']
+}
+```
+
+## Step 6: Write Tests
+
+```typescript
+// tests/feature/articles.test.ts
+import { describe, test, expect, beforeAll } from 'bun:test'
+import { setupDatabase, refreshDatabase } from '@stacksjs/testing'
+
+describe('Articles', () => {
+  beforeAll(async () => {
+    await setupDatabase()
+  })
+
+  test('can create an article', async () => {
+    const article = await Article.create({
+      title: 'Test Article',
+      content: 'Test content',
+      status: 'draft'
+    })
+    expect(article.title).toBe('Test Article')
+  })
+
+  test('can list articles', async () => {
+    const articles = await Article.all()
+    expect(articles.length).toBeGreaterThan(0)
+  })
+})
+```
+
+## Step 7: Lint & Deploy
+
+```bash
+bunx --bun pickier . --fix    # lint and auto-fix
+buddy test                     # run tests
+buddy deploy                   # deploy to cloud
+```
+
+## Common Patterns
+
+### Adding a Dashboard View
+Models with `useApi` + `dashboard: { highlight: true }` auto-appear in the admin dashboard.
+
+### Adding Email Notifications
+```typescript
+// app/Mail/ArticlePublished.ts
+export async function sendArticlePublished({ to, article }) {
+  const { html, text } = await template('article-published', {
+    variables: { title: article.title, url: `${config.app.url}/articles/${article.id}` }
+  })
+  await mail.send({ to, subject: `New: ${article.title}`, html, text })
+}
+```
+
+### Adding Background Processing
+```typescript
+// app/Jobs/IndexArticle.ts
+export default new Job({
+  name: 'IndexArticle',
+  queue: 'search',
+  tries: 3,
+  async handle(payload: { articleId: number }) {
+    const article = await Article.find(payload.articleId)
+    await search.addDocuments('articles', [article])
+  }
+})
+```
+
+## Gotchas
+- Models work directly via the dynamic ORM — no generation step needed before migrations
+- The `useApi` trait auto-generates both routes AND dashboard views
+- Model events (observe: true) emit `article:created`, `article:updated`, `article:deleted`
+- Factories in model attributes are used by `buddy seed`
+- Always lint after code generation: `bunx --bun pickier . --fix`
+- Use conventional commits: `feat: add article management`

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

@@ -0,0 +1,210 @@
+---
+name: stacks-notifications
+description: Use when implementing notifications in Stacks — multi-channel notifications (email, SMS, push, chat, database), the database notification driver with read/unread tracking, notification factories (useEmail, useSMS, useChat, useDatabase), or notification configuration. Covers @stacksjs/notifications and config/notification.ts.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Notifications
+
+Multi-channel notification system with 5 channel types: email, SMS, chat, push, and database.
+
+## Key Paths
+- Core package: `storage/framework/core/notifications/src/`
+- Main entry: `storage/framework/core/notifications/src/index.ts`
+- Drivers: `storage/framework/core/notifications/src/drivers/`
+- Database driver: `storage/framework/core/notifications/src/drivers/database.ts`
+- Configuration: `config/notification.ts`
+- Notification model: `storage/framework/defaults/app/Models/Notification.ts`
+
+## Package Exports
+
+```typescript
+import {
+  useChat,
+  useEmail,
+  useSMS,
+  useDatabase,
+  useNotification,
+  notification,
+  DatabaseNotificationDriver,
+} from '@stacksjs/notifications'
+
+// Types
+import type { CreateNotificationOptions, DatabaseNotification } from '@stacksjs/notifications'
+```
+
+## Channel Factories
+
+Each factory returns the underlying driver module for that channel.
+
+```typescript
+// Email -- defaults to 'mailtrap', returns @stacksjs/email driver
+const emailDriver = useEmail('ses')
+const emailDriver = useEmail('sendgrid')
+const emailDriver = useEmail('mailgun')
+const emailDriver = useEmail('mailtrap')
+const emailDriver = useEmail('smtp')
+
+// SMS -- defaults to 'twilio', returns @stacksjs/sms driver
+const smsDriver = useSMS('twilio')
+const smsDriver = useSMS('vonage')
+
+// Chat -- defaults to 'slack', returns @stacksjs/chat driver
+const chatDriver = useChat('slack')
+const chatDriver = useChat('discord')
+const chatDriver = useChat('teams')
+
+// Database -- returns DatabaseNotificationDriver object
+const dbDriver = useDatabase()
+
+// Auto-detect by type -- dispatches to the correct factory
+const driver = useNotification('email', 'ses')
+const driver = useNotification('sms', 'twilio')
+const driver = useNotification('chat', 'slack')
+const driver = useNotification('database')
+
+// Default (uses config.default, falls back to 'email' + 'mailtrap')
+const driver = notification()
+```
+
+`useNotification()` reads `config/notification.ts` for the default type. If no default is set, it throws `'No default notification type set in config/notification.ts'`.
+
+The channel drivers are re-exports from their respective packages:
+- `email` driver: `@stacksjs/email`
+- `sms` driver: `@stacksjs/sms`
+- `chat` driver: `@stacksjs/chat`
+- `push` driver: `@stacksjs/push`
+
+## Database Notification Driver
+
+The `DatabaseNotificationDriver` provides CRUD operations for notifications stored in the `notifications` database table using Kysely query builder.
+
+### Send a Notification
+
+```typescript
+const db = useDatabase()
+
+const notification = await db.send({
+  userId: 1,
+  type: 'order.shipped',
+  data: { orderId: 42, trackingNumber: 'ABC123' },
+})
+// Returns the created DatabaseNotification with auto-generated id, timestamps
+```
+
+`send()` inserts a row into the `notifications` table with:
+- `user_id` from `options.userId`
+- `type` from `options.type`
+- `data` -- JSON.stringify'd from `options.data`
+- `read_at` set to `null`
+- `created_at` and `updated_at` set to current ISO timestamp
+
+### Query Notifications
+
+```typescript
+// All notifications for a user, ordered by created_at desc
+const all = await db.getUserNotifications(userId)
+
+// Only unread (where read_at is null), ordered by created_at desc
+const unread = await db.getUnreadNotifications(userId)
+
+// Count of unread notifications
+const count = await db.unreadCount(userId)
+```
+
+### Mark as Read
+
+```typescript
+// Mark a single notification as read (sets read_at to current timestamp)
+await db.markAsRead(notificationId)
+
+// Mark all unread notifications for a user as read
+await db.markAllAsRead(userId)
+```
+
+`markAllAsRead()` only updates rows where `read_at` is null.
+
+### Delete Notifications
+
+```typescript
+// Delete a single notification by ID
+await db.deleteNotification(notificationId)
+
+// Delete all notifications for a user
+await db.deleteAllNotifications(userId)
+```
+
+### DatabaseNotification Interface
+
+```typescript
+interface DatabaseNotification {
+  id: number
+  user_id: number
+  type: string          // e.g., 'order.shipped', 'payment.received'
+  data: string          // JSON stringified -- parse with JSON.parse() when reading
+  read_at: string | null  // ISO timestamp or null if unread
+  created_at: string    // ISO timestamp
+  updated_at: string | null  // ISO timestamp
+}
+```
+
+### CreateNotificationOptions Interface
+
+```typescript
+interface CreateNotificationOptions {
+  userId: number
+  type: string
+  data: Record<string, any>
+}
+```
+
+## Notification Model Fields
+
+The Notification model (at `storage/framework/defaults/app/Models/Notification.ts`) defines:
+- `type` -- notification type: email, sms, push, slack, webhook
+- `channel` -- delivery channel
+- `recipient` -- target email, phone, or user
+- `subject` -- notification subject line
+- `body` -- notification body content
+- `status` -- pending, sent, delivered, failed, read
+- `readAt`, `sentAt`, `metadata`
+
+Note: The Notification model uses 30 seeded records by default.
+
+## CLI Commands
+- `buddy make:notification [name]` -- scaffold a new notification
+
+## config/notification.ts
+
+```typescript
+import type { NotificationConfig } from '@stacksjs/types'
+
+export default {
+  default: 'email',
+} satisfies NotificationConfig
+```
+
+The `default` field controls which channel type `useNotification()` and `notification()` use when no type is specified. Valid values: `'email'`, `'sms'`, `'chat'`, `'database'`.
+
+## Architecture
+
+The notifications package is a thin aggregation layer. Each channel delegates to its own dedicated package:
+
+- **Email channel** (`useEmail`) -- re-exports `@stacksjs/email` (configured via `config/email.ts`)
+- **SMS channel** (`useSMS`) -- re-exports `@stacksjs/sms` (configured via `config/sms.ts`)
+- **Chat channel** (`useChat`) -- re-exports `@stacksjs/chat` (configured via `config/services.ts`)
+- **Push channel** -- re-exports `@stacksjs/push`
+- **Database channel** (`useDatabase`) -- built-in driver using `@stacksjs/database`
+
+The driver modules (`drivers/email.ts`, `drivers/sms.ts`, etc.) are single-line re-exports: `export * as email from '@stacksjs/email'`, `export * as sms from '@stacksjs/sms'`, etc.
+
+## Gotchas
+- The `data` field in database notifications is stored as a JSON string -- always `JSON.parse()` when reading
+- `read_at` is `null` for unread notifications -- use this to filter unread
+- The database driver uses Kysely's query builder with `as any` type casts on table/column names since the notifications table is dynamically referenced
+- Channel-specific configuration (SMTP credentials, Twilio keys, Slack tokens) lives in each channel's own config file, not in `config/notification.ts`
+- `useNotification()` throws if `config.default` is not set in `config/notification.ts`
+- The `notification()` function (without arguments) is a shorthand for `useNotification()` with defaults
+- The `nexmo` driver is a legacy alias for `vonage` in the SMS drivers index