@stacksjs/defaults 0.70.229 → 0.70.231

package/ai/skills/stacks-dashboard/scripts/audit.ts

@@ -0,0 +1,374 @@
+#!/usr/bin/env bun
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+
+interface ModelSummary {
+  href: string
+}
+
+interface ModelIndex {
+  categoryGroups?: Array<{ models?: ModelSummary[] }>
+}
+
+interface Failure {
+  body?: string
+  contentType?: string
+  error?: string
+  fragment?: string | null
+  kind: string
+  path: string
+  status?: number
+}
+
+const projectRoot = resolve(process.cwd())
+const args = process.argv.slice(2)
+const baseUrlFlagIndex = args.indexOf('--base-url')
+const baseUrlFlag = baseUrlFlagIndex >= 0
+  ? args[baseUrlFlagIndex + 1]
+  : args.find(arg => arg.startsWith('--base-url='))?.slice('--base-url='.length)
+const positionalBaseUrl = args.find((arg, index) =>
+  !arg.startsWith('-') && index !== baseUrlFlagIndex + 1)
+const baseUrl = (baseUrlFlag || positionalBaseUrl || process.env.DASHBOARD_URL || 'http://127.0.0.1:3002')
+  .replace(/\/+$/, '')
+const timeoutMs = 15_000
+const failures: Failure[] = []
+
+function files(directory: string): string[] {
+  if (!existsSync(directory))
+    return []
+
+  return readdirSync(directory).flatMap((name) => {
+    const path = join(directory, name)
+    return statSync(path).isDirectory() ? files(path) : [path]
+  })
+}
+
+function dashboardViewRoots(): string[] {
+  return [
+    resolve(projectRoot, 'storage/framework/defaults/views/dashboard'),
+    resolve(projectRoot, 'resources/views/dashboard'),
+  ].filter(existsSync)
+}
+
+function viewRoute(root: string, path: string): string {
+  const relativePath = relative(root, path).replace(/\.stx$/, '')
+  return relativePath === 'index'
+    ? '/'
+    : `/${relativePath.replace(/\/index$/, '')}`
+}
+
+function discoveredViewRoutes(): { dynamic: string[], static: string[] } {
+  const routeMap = new Map<string, string>()
+
+  for (const root of dashboardViewRoots()) {
+    for (const path of files(root)) {
+      if (!path.endsWith('.stx') || path.includes('/layouts/'))
+        continue
+
+      routeMap.set(viewRoute(root, path), path)
+    }
+  }
+
+  const routes = [...routeMap.keys()].filter(route => route !== '/[...all]')
+  return {
+    dynamic: routes.filter(route => route.includes('[')).sort(),
+    static: routes.filter(route => !route.includes('[')).sort(),
+  }
+}
+
+async function request(path: string, init?: RequestInit): Promise<Response> {
+  return fetch(`${baseUrl}${path}`, {
+    ...init,
+    signal: AbortSignal.timeout(timeoutMs),
+  })
+}
+
+async function validatePageResponse(
+  path: string,
+  kind: string,
+  response: Response,
+): Promise<void> {
+  const contentType = response.headers.get('content-type') || ''
+  const body = await response.text()
+
+  if (!contentType.includes('text/html')) {
+    failures.push({
+      path,
+      kind: `${kind}-content`,
+      status: response.status,
+      contentType,
+    })
+    return
+  }
+  if (!body.trim()) {
+    failures.push({ path, kind: `${kind}-empty`, status: response.status })
+    return
+  }
+
+  const renderedMarkup = body.replace(/<!--[\s\S]*?-->/g, '')
+  const unresolved = renderedMarkup
+    .match(/<\/?[A-Z][A-Za-z0-9]*(?:\s|>|\/>)/)?.[0]
+  if (unresolved) {
+    failures.push({
+      path,
+      kind: `${kind}-component`,
+      status: response.status,
+      body: unresolved,
+    })
+  }
+}
+
+async function auditPage(path: string): Promise<void> {
+  try {
+    const full = await request(path)
+    if (full.status !== 200)
+      failures.push({ path, kind: 'full-page', status: full.status })
+    else
+      await validatePageResponse(path, 'full-page', full)
+  }
+  catch (error) {
+    failures.push({ path, kind: 'full-page', error: String(error) })
+  }
+
+  try {
+    const fragment = await request(path, {
+      headers: { 'X-STX-Router': 'true', Accept: 'text/html' },
+    })
+    const fragmentHeader = fragment.headers.get('x-stx-fragment')
+    if (fragment.status !== 200 || fragmentHeader !== 'true') {
+      failures.push({
+        path,
+        kind: 'stx-fragment',
+        status: fragment.status,
+        fragment: fragmentHeader,
+      })
+    }
+    else {
+      await validatePageResponse(path, 'stx-fragment', fragment)
+    }
+  }
+  catch (error) {
+    failures.push({ path, kind: 'stx-fragment', error: String(error) })
+  }
+}
+
+async function json(path: string): Promise<Record<string, any>> {
+  try {
+    const response = await request(path)
+    if (!response.ok)
+      return {}
+    return await response.json() as Record<string, any>
+  }
+  catch {
+    return {}
+  }
+}
+
+function firstId(payload: Record<string, any>, key: string): string | undefined {
+  const item = Array.isArray(payload[key]) ? payload[key][0] : undefined
+  return item?.id == null ? undefined : String(item.id)
+}
+
+async function discoverDynamicPages(
+  templates: string[],
+  modelRoutes: string[],
+): Promise<string[]> {
+  const [
+    products,
+    deployments,
+    jobs,
+    boards,
+    queries,
+    servers,
+    teams,
+  ] = await Promise.all([
+    json('/api/dashboard/commerce/products'),
+    json('/api/dashboard/deployments'),
+    json('/api/dashboard/jobs'),
+    json('/api/dashboard/kanban/boards'),
+    json('/api/dashboard/queries'),
+    json('/api/dashboard/servers'),
+    json('/api/dashboard/data/teams'),
+  ])
+
+  const replacements: Record<string, string> = {
+    '/commerce/products/[id]': firstId(products, 'products') || '1',
+    '/deployments/[id]': firstId(deployments, 'deployments') || 'missing',
+    '/jobs/[id]': firstId(jobs, 'data') || 'missing',
+    '/kanban/[id]': firstId(boards, 'boards') || 'missing',
+    '/queries/[id]': firstId(queries, 'queries') || 'missing',
+    '/servers/[id]': firstId(servers, 'servers') || 'missing',
+    '/team-invitations/[token]': 'missing',
+    '/teams/[id]': firstId(teams, 'teams') || 'missing',
+  }
+
+  return templates
+    .filter(template => template !== '/models/[model]')
+    .map((template) => {
+      const replacement = replacements[template] || 'missing'
+      return template.replace(/\[[^\]]+\]/g, replacement)
+    })
+    .concat(modelRoutes)
+}
+
+function dashboardApiRoutes(): string[] {
+  const path = resolve(
+    projectRoot,
+    'storage/framework/defaults/routes/dashboard-api.ts',
+  )
+  const source = readFileSync(path, 'utf8')
+  return [...source.matchAll(/route\.get\(\s*['"]([^'"]+)['"]/g)]
+    .map(match => `/api/dashboard${match[1]}`)
+}
+
+function concreteApiPath(
+  path: string,
+  dynamicPages: string[],
+  modelRoutes: string[],
+): string {
+  const match = (prefix: string) => dynamicPages
+    .find(route => route.startsWith(`${prefix}/`))
+    ?.slice(prefix.length + 1)
+
+  if (path === '/api/dashboard/models/{slug}')
+    return `/api/dashboard/models/${modelRoutes[0]?.split('/').pop() || 'activity'}`
+  if (path === '/api/dashboard/servers/{id}')
+    return `/api/dashboard/servers/${match('/servers') || 'missing'}`
+  if (path === '/api/dashboard/jobs/{id}')
+    return `/api/dashboard/jobs/${match('/jobs') || 'missing'}`
+  if (path === '/api/dashboard/commerce/products/{id}')
+    return `/api/dashboard/commerce/products/${match('/commerce/products') || '1'}`
+  if (path === '/api/dashboard/teams/{id}/people')
+    return `/api/dashboard/teams/${match('/teams') || '1'}/people`
+  if (path === '/api/dashboard/kanban/boards/{id}')
+    return `/api/dashboard/kanban/boards/${match('/kanban') || '1'}`
+  if (path === '/api/dashboard/queries/{id}')
+    return `/api/dashboard/queries/${match('/queries') || '1'}`
+
+  return path
+    .replace('{owner}', 'stacksjs')
+    .replace('{name}', 'stacks')
+    .replace('{runId}', '1')
+    .replace('{slug}', 'missing-post')
+    .replace('{id}', '1')
+}
+
+async function auditApi(
+  routes: string[],
+  dynamicPages: string[],
+  modelRoutes: string[],
+): Promise<Record<number, number>> {
+  const statuses: Record<number, number> = {}
+
+  for (const route of routes) {
+    const path = concreteApiPath(route, dynamicPages, modelRoutes)
+
+    try {
+      const response = await request(path)
+      const status = response.status
+      const contentType = response.headers.get('content-type') || ''
+      const body = await response.text()
+      statuses[status] = (statuses[status] || 0) + 1
+
+      if (status >= 500 || status === 405) {
+        failures.push({
+          path,
+          kind: 'api-status',
+          status,
+          body: body.slice(0, 160),
+        })
+        continue
+      }
+      if (contentType.includes('text/html')) {
+        failures.push({ path, kind: 'api-content', status, contentType })
+        continue
+      }
+      if (status !== 200 || !contentType.includes('json'))
+        continue
+
+      try {
+        const payload = JSON.parse(body)
+        if (
+          payload
+          && typeof payload === 'object'
+          && (
+            payload.ok === false
+            || payload.success === false
+            || typeof payload.error === 'string'
+          )
+        ) {
+          failures.push({
+            path,
+            kind: 'api-hidden-error',
+            status,
+            body: body.slice(0, 160),
+          })
+        }
+      }
+      catch {
+        failures.push({ path, kind: 'api-json', status, error: 'Invalid JSON' })
+      }
+    }
+    catch (error) {
+      failures.push({ path, kind: 'api-request', error: String(error) })
+    }
+  }
+
+  return statuses
+}
+
+const views = discoveredViewRoutes()
+if (views.static.length === 0) {
+  failures.push({
+    path: projectRoot,
+    kind: 'static-route-discovery',
+    error: 'No dashboard route views were discovered',
+  })
+}
+const modelIndex = await json('/api/dashboard/models') as ModelIndex
+const modelRoutes = (modelIndex.categoryGroups || [])
+  .flatMap(group => group.models || [])
+  .map(model => model.href)
+  .filter(Boolean)
+if (modelRoutes.length === 0) {
+  failures.push({
+    path: '/api/dashboard/models',
+    kind: 'model-route-discovery',
+    error: 'No model destinations were discovered',
+  })
+}
+const dynamicPages = await discoverDynamicPages(views.dynamic, modelRoutes)
+
+for (const path of views.static)
+  await auditPage(path)
+for (const path of dynamicPages)
+  await auditPage(path)
+
+const apiRoutes = dashboardApiRoutes()
+if (apiRoutes.length === 0) {
+  failures.push({
+    path: '/api/dashboard',
+    kind: 'api-route-discovery',
+    error: 'No GET dashboard API routes were discovered',
+  })
+}
+const statuses = await auditApi(apiRoutes, dynamicPages, modelRoutes)
+const remainingDynamicCount = dynamicPages.length - modelRoutes.length
+
+console.log(JSON.stringify({
+  baseUrl,
+  pages: {
+    static: { routes: views.static.length, requests: views.static.length * 2 },
+    models: { routes: modelRoutes.length, requests: modelRoutes.length * 2 },
+    dynamic: {
+      routes: remainingDynamicCount,
+      requests: remainingDynamicCount * 2,
+    },
+  },
+  api: { routes: apiRoutes.length, statuses },
+  failures,
+}, null, 2))
+
+if (failures.length > 0)
+  process.exitCode = 1

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

@@ -282,5 +282,9 @@ Entity-centric API for single-table design:
 - `Database.fromConfig()` appends `_testing` to database name/path when `env === 'testing'`
 - DynamoDB support uses a separate entity-centric API, not the standard query builder
 - Soft deletes are disabled by default in qb.ts config (`enabled: false`)
+- Keep the process-wide raw query-builder soft-delete filter disabled. Raw
+  `db.selectFrom()` calls do not carry a model definition, so they cannot know
+  whether a table has `useSoftDeletes` or a `deleted_at` column. Model queries
+  and generated `useApi` routes apply the trait-aware scope themselves.
 - Transaction defaults: 2 retries, `read committed` isolation, with exponential backoff + jitter
 - The ORM lives in TWO locations: `storage/framework/core/orm/` (package) and `storage/framework/orm/` (implementation)

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

@@ -143,13 +143,16 @@ Uses `bun-plugin-stx` serve function with pattern-based view resolution:
 - Serves on `127.0.0.1` at `config.ports.api` (default 3008)
 
 ### Dashboard Dev Server (dashboard.ts)
-- Starts STX server + config API + native Craft window in parallel
-- Config API runs on `dashboardPort + 1` (default 3003), handles `POST /api/config/update`
-- Config API allows live editing of `config/*.ts` files via regex-based key replacement
+- Starts the STX server on `config.ports.admin` and optionally opens a native Craft window
+- Mounts the config API on the same dashboard origin under `/api/config/*`
+- Config routes list, read, expose source for, and atomically update `config/*.ts` files
+- Config updates support top-level scalar literals only and preserve comments and environment-backed expressions
 - Discovers ORM models from `app/Models/` and `storage/framework/defaults/app/Models/`
 - Writes `.discovered-models.json` manifest for sidebar population
-- Opens `@craft-native/ts` native window (1400x900, titlebar hidden, native sidebar)
-- Sidebar has 10 sections: Home, Library, Content, App, Data, Commerce, Marketing, Analytics, Management, Utilities
+- Preloads ORM model globals for server scripts, while framework server helpers use explicit imports
+- Leaves `resources/functions` to the STX client auto-import pipeline because browser helpers may depend on signals and other browser-only primitives
+- Opens a Craft `createApp()` window when a supported SDK and native binary are available (1400x900, titlebar hidden)
+- Builds the web sidebar from configured sections and discovered model dashboard metadata
 
 ### Docs Dev Server (docs.ts)
 - Uses `@stacksjs/bunpress` with `{ watch: true, quiet: true }`
@@ -288,7 +291,7 @@ Note: Dashboard mode overrides these settings via its own `serve()` options.
 - Dev actions are executed with `bun --watch` automatically -- do NOT add `--watch` manually or you get double-restart behavior
 - The `dev/views` action is special-cased in `runAction()` to run in-process (no subprocess) for performance -- other dev actions spawn subprocesses
 - `NODE_PATH` is injected to include `pantry/` directory so compiled pantry packages can resolve `@stacksjs/*` dependencies at runtime
-- The dashboard config API (port 3003) modifies `config/*.ts` files via regex replacement -- it only handles simple key-value patterns, not nested objects or arrays
+- The dashboard config API shares the dashboard origin and atomically modifies top-level scalar literals in `config/*.ts`. Nested values, arrays, and environment-backed expressions remain read-only.
 - SSL certificates are stored in `~/.stacks/ssl/`, NOT in the project directory -- they persist across projects using the same domain
 - Custom server configuration in `server/` at the project root overrides the default server config via file copy (checked by `useCustomOrDefaultServerConfig()`)
 - The production server doubles as a queue worker when `QUEUE_WORKER` env var is set -- it imports the job by name from `app/Jobs/` and exits after completion

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

@@ -8,7 +8,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Email
 
-Multi-driver email system with template rendering, S3-based inbox management, and 5 built-in drivers.
+Multi-driver email system with template rendering, S3-based inbox management, and 7 built-in drivers.
 
 ## Key Paths
 - Core package: `storage/framework/core/email/src/`
@@ -34,6 +34,12 @@ email/src/
     └── smtp.ts       # Raw SMTP driver (TLS/STARTTLS)
 ```
 
+`log` and `capture` are also registered by the Mail singleton. `log` writes
+messages to `storage/logs/mail/` for local inspection. `capture` keeps messages
+in memory for deterministic tests. Unsupported names fail at the first send,
+so `MAIL_MAILER` must be one of `smtp`, `ses`, `sendgrid`, `mailgun`,
+`mailtrap`, `log`, or `capture`.
+
 ## Mail Singleton
 
 ```typescript
@@ -118,7 +124,7 @@ await deleteEmail('chris', messageId)
 ## Built-in Drivers
 
 ### SES Driver
-- Uses `@aws-sdk/client-ses` SESClient
+- Uses the `SESClient` from `@stacksjs/ts-cloud`
 - Lazy-loads client on first send
 - Supports `Source` formatting: `"Name" <address>`
 
@@ -147,6 +153,26 @@ await deleteEmail('chris', messageId)
 - 30-second connection timeout
 - Command queue-based protocol
 
+## Environment-backed configuration
+
+The source of truth for dashboard mail settings is `.env`:
+
+- Common: `MAIL_MAILER`, `MAIL_FROM_NAME`, `MAIL_FROM_ADDRESS`
+- SMTP: `MAIL_HOST`, `MAIL_PORT`, `MAIL_USERNAME`, `MAIL_PASSWORD`,
+  `MAIL_ENCRYPTION`
+- SES: `AWS_SES_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`
+- SendGrid: `SENDGRID_API_KEY`
+- Mailgun: `MAILGUN_API_KEY`, `MAILGUN_DOMAIN`, `MAILGUN_ENDPOINT`
+- Mailtrap: `MAILTRAP_HOST`, `MAILTRAP_TOKEN`, `MAILTRAP_INBOX_ID`
+
+The dashboard endpoints are `GET` and `PUT` at
+`/api/dashboard/mail-settings`. They are guarded outside local development,
+return no stored secret values, preserve a secret when its input is blank, and
+require an explicit clear flag to remove one. Writes use the shared atomic
+environment-file service, create a machine-local backup under
+`storage/framework/runtime/dashboard/`, and reject stale revisions instead of
+overwriting concurrent edits.
+
 ## Driver Interface
 
 ```typescript
@@ -169,7 +195,7 @@ abstract class BaseEmailDriver {
   mailboxes: ['chris', 'blake', 'glenn'],
   url: env.APP_URL,
   charset: 'UTF-8',
-  default: 'ses',  // 'ses' | 'sendgrid' | 'mailgun' | 'mailtrap' | 'smtp' | 'postmark'
+  default: 'ses',  // 'ses' | 'sendgrid' | 'mailgun' | 'mailtrap' | 'smtp' | 'log' | 'capture'
   server: {
     enabled: true,
     scan: { enabled: true },

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-env
-description: Use when working with environment variables in Stacks — the typed env proxy with auto-coercion, .env file loading, AES-256-GCM encryption/decryption of env values, runtime/platform detection, CI provider detection, or the env CLI commands. Covers @stacksjs/env, config/env.ts, and .env files.
+description: Use when working with environment variables in Stacks - the typed env proxy with auto-coercion, .env file loading, X25519 and AES-256-GCM encryption/decryption of env values, runtime/platform detection, CI provider detection, or the env CLI commands. Covers @stacksjs/env, config/env.ts, and .env files.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -23,7 +23,7 @@ env/src/
 ├── plugin.ts    # Bun plugin for auto .env loading
 ├── parser.ts    # .env file parser with encryption support
 ├── cli.ts       # CLI commands (get, set, encrypt, decrypt, rotate)
-├── crypto.ts    # AES-256-GCM + secp256k1 encryption
+├── crypto.ts    # X25519 + HKDF-SHA-256 + AES-256-GCM encryption
 └── types.ts     # StacksEnv interface (100+ typed vars)
 ```
 
@@ -105,7 +105,7 @@ const vars = parse(envContent, {
 })
 ```
 
-## Encryption (AES-256-GCM)
+## Encryption (X25519 + AES-256-GCM)
 
 ```typescript
 import { aesEncrypt, aesDecrypt, generateKeypair, encryptValue, decryptValue, getPrivateKey } from '@stacksjs/env'
@@ -114,7 +114,7 @@ import { aesEncrypt, aesDecrypt, generateKeypair, encryptValue, decryptValue, ge
 const encrypted = aesEncrypt(plaintext, password)
 const decrypted = aesDecrypt(encrypted, password)
 
-// Asymmetric encryption (secp256k1 ECIES-style)
+// Versioned ephemeral-static X25519 envelope encryption
 const keypair = generateKeypair()
 const encrypted = encryptValue(value, keypair.publicKey)
 const decrypted = decryptValue(encrypted, keypair.privateKey)
@@ -167,6 +167,25 @@ from a slug prefix by shape alone. Slug punctuation is ignored, so
 The API is `partitionTenantEnv(values, { self, tenants })` from
 `@stacksjs/env`, plus `stripForeignTenantEnv` and `foreignTenantKeys`.
 
+## Dashboard environment editor
+
+The dashboard reads and writes `.env` through guarded
+`/api/dashboard/environment` GET and PUT endpoints. The write contract:
+
+- validates uppercase environment keys and duplicate definitions
+- limits the file to 1 MB and rejects null bytes
+- requires the SHA-256 revision returned by the latest read
+- writes through a 0600 temporary file and atomic rename
+- stores the previous content under
+  `storage/framework/runtime/dashboard/environment.backup`
+- returns `Cache-Control: no-store` because the response contains secrets
+
+Structured settings pages should use `updateEnvironmentEntries()` from the
+dashboard environment-file service. It updates only named keys while
+preserving comments, ordering, unrelated values, and the same revision and
+backup guarantees. Do not implement settings with repeated `writeFileSync`
+calls or raw client-side `fetch`.
+
 ## Gotchas
 - **A tenant's keys in your env file get shipped everywhere.** `buddy deploy`
   sends the entire env file as each site's `.env`. Declare `tenants` in
@@ -174,7 +193,8 @@ The API is `partitionTenantEnv(values, { self, tenants })` from
 - Bun natively loads `.env` — no dotenv package needed
 - The `env` proxy auto-coerces strings to booleans/numbers
 - `.env` should never be committed — use `.env.example` as template
-- Encryption uses AES-256-GCM for values and secp256k1 for key exchange
+- New encrypted values use ephemeral-static X25519, HKDF-SHA-256, and
+  AES-256-GCM. Legacy ciphertext remains readable for migration
 - `autoLoadEnv()` loads in order: `.env`, `.env.local`, `.env.{APP_ENV}`
 - Runtime detection uses Bun globals and process properties
 - CI provider detection checks environment variables specific to each CI system

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

@@ -12,7 +12,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 ## Key Paths
 - Core package: `storage/framework/core/faker/src/`
-- Source: `storage/framework/core/faker/src/index.ts` (265 lines)
+- Source: `storage/framework/core/faker/src/index.ts`
 - Tests: `storage/framework/core/faker/tests/faker.test.ts`
 - Seeder integration: `storage/framework/core/database/src/seeder.ts`
 
@@ -90,10 +90,10 @@ faker.helpers.objectValue<T>(obj: T): T[keyof T]
 ```typescript
 faker.lorem.word(): string
 faker.lorem.words(count?: number): string              // default: 3
-faker.lorem.sentence(maxWords?: number): string        // default: 3-10 words
+faker.lorem.sentence(wordCount?: number | { min, max }): string
 faker.lorem.sentences(count?, separator?): string      // default: 3, sep: ' '
 faker.lorem.paragraph(sentenceCount?): string
-faker.lorem.paragraphs(count?, separator?): string     // default: 3, sep: '\n\n'
+faker.lorem.paragraphs(count?: number | { min, max }, separator?): string
 faker.lorem.text(length?: number): string              // default: 200 chars
 faker.lorem.slug(wordCount?: number): string           // URL-safe, default: 3
 faker.lorem.lines(count?: number): string              // default: 3

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

@@ -13,6 +13,7 @@ Schema change management via migration files.
 ## Key Paths
 - Migration files: `database/migrations/` (96+ files)
 - Database config: `config/database.ts`
+- Model snapshot: `storage/framework/database/model-snapshot.<dialect>.json`
 
 ## CLI Commands
 
@@ -44,7 +45,20 @@ When you define or modify a model, generate migrations automatically:
 buddy generate:migrations
 ```
 
-This diffs model definitions against the current schema and generates the necessary SQL.
+This recursively loads both model roots, with `app/Models/` overriding framework
+models that have the same model name:
+
+- `storage/framework/defaults/app/Models/`
+- `app/Models/`
+
+It diffs the merged registry against the committed dialect snapshot and
+generates the necessary SQL. An application does not need an `app/Models/`
+directory for framework model migrations to be discovered.
+
+The snapshot is part of the schema history and must be committed with the
+generated migration. It lives under `storage/framework/database/`, not `.qb/`.
+Run the generator a second time before committing. A stable change reports
+`Nothing to migrate` and `Model snapshot unchanged`.
 
 ## Built-in Migrations (96+)
 
@@ -93,12 +107,17 @@ The framework includes migrations for all built-in models:
 1. Define/modify model in `storage/framework/defaults/app/Models/` or `app/Models/`
 2. Run `buddy generate:migrations` to generate SQL diffs
 3. Review generated migration files
-4. Run `buddy migrate` to apply
+4. Run `buddy generate:migrations` again and confirm there is no remaining diff
+5. Run `buddy migrate` to apply
+6. Commit the generated SQL and `storage/framework/database/model-snapshot.<dialect>.json`
 
 ## Gotchas
 - `migrate:fresh` drops ALL tables — only use in development
 - Migrations run in filename order (timestamps ensure correct sequence)
 - Never edit a migration that's been run in production — create a new one
+- Keep the committed model snapshot in sync with every generated migration
+- Do not commit a second snapshot under `.qb/`; that indicates a missing `snapshotDir` configuration
+- If a generated SQLite migration rebuilds tables, test it against a copy of the current database and run `PRAGMA integrity_check` plus `PRAGMA foreign_key_check`
 - `--seed` flag after `migrate:fresh` seeds the database with factory data
 - 96+ migration files exist by default for all framework models
 - SQLite >= 3.47.2 is required (system requirement)