@stacksjs/defaults 0.75.460 → 0.75.463

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

@@ -20,7 +20,7 @@ Server actions are reusable business logic units invoked from routes, events, or
 
 ```typescript
 // app/Actions/CreateWidget.ts
-import { Action } from '@stacksjs/actions'
+import { Action } from '@stacksjs/actions/runtime'
 import { toSnakeCaseKeys } from '@stacksjs/orm'
 import { response } from '@stacksjs/router'
 
@@ -57,7 +57,7 @@ the rules used by an explicit `request.validate()` call; do not assume attaching
 a model means every custom handler has already validated all its input.
 
 ```ts
-import { Action } from '@stacksjs/actions'
+import { Action } from '@stacksjs/actions/runtime'
 import { schema } from '@stacksjs/validation'
 
 export default new Action({

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

@@ -222,17 +222,20 @@ response.json({ message: 'OK' })
 response.json(data, { status: 200, headers: { 'X-Custom': 'value' }, pretty: true })
 
 // Status shortcuts
-response.created({ id: 1 })              // 201
+response.success(data, 'Saved')          // 200, { success: true, data, message }
+response.created({ id: 1 })              // 201, { success: true, data }
 response.noContent()                      // 204
-response.badRequest({ error: 'Bad' })     // 400
-response.unauthorized()                   // 401 (default: { error: 'Unauthorized' })
-response.forbidden()                      // 403 (default: { error: 'Forbidden' })
-response.notFound()                       // 404 (default: { error: 'Not Found' })
-response.error()                          // 500 (default: { error: 'Internal Server Error' })
+response.badRequest('Bad', errors?)       // 400
+response.unauthorized()                   // 401
+response.forbidden()                      // 403
+response.notFound()                       // 404
+response.validationError(errors)          // 422
+response.error('Conflict', 409)           // (message, status = 400, errors?)
+response.serverError()                    // 500
 
 // Other content types
-response.text('Hello', { status: 200 })
-response.html('<h1>Hello</h1>')
+response.text('Hello', 200)
+response.view('<h1>Hello</h1>')           // HTML; there is no response.html()
 response.redirect('/new-url', 302)        // 301 | 302 | 303 | 307 | 308
 ```
 

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

@@ -102,7 +102,7 @@ cms.posts.fetchById(id: number): Promise<PostJsonResponse | undefined>
 cms.posts.fetchAll(): Promise<PostJsonResponse[]>
 cms.posts.fetchByStatus(status: 'published' | 'draft' | 'archived'): Promise<PostJsonResponse[]>
 cms.posts.fetchByCategory(category: string): Promise<PostJsonResponse[]>
-cms.posts.fetchByAuthor(author: string): Promise<PostJsonResponse[]>
+cms.posts.fetchByAuthor(authorId: number): Promise<PostJsonResponse[]>
 cms.posts.fetchByMinViews(minViews: number): Promise<PostJsonResponse[]>
 cms.posts.fetchPublishedAfter(timestamp: number): Promise<PostJsonResponse[]>
 
@@ -128,8 +128,10 @@ cms.authors.findByName(name: string): Promise<AuthorJsonResponse | undefined>
 cms.authors.findByUserId(userId: number): Promise<AuthorJsonResponse | undefined>
 cms.authors.fetchAll(): Promise<AuthorJsonResponse[]>
 cms.authors.fetchById(id: number): Promise<AuthorJsonResponse | undefined>
-cms.authors.update(id, data): Promise<AuthorJsonResponse>
-cms.authors.destroy(id): Promise<boolean>
+cms.authors.findByUuid(uuid: string): Promise<AuthorJsonResponse | undefined>
+cms.authors.update(id, data): Promise<AuthorJsonResponse | undefined>
+cms.authors.destroy(id): Promise<AuthorJsonResponse>
+cms.authors.destroyMany(ids: number[]): Promise<number>
 ```
 
 ## Tags API

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

@@ -92,7 +92,7 @@ buddy/src/commands/
 - `buddy dev:system-tray` (alias: `dev:tray`) -- System tray dev server
 
 ### Build Commands
-- `buddy build` -- Build stacks framework (default when no option specified)
+- `buddy build` -- Interactive target picker in a terminal; with no TTY (CI) or no pick it builds the frontend views. The framework builds only with `--stacks` / `build:stacks`
 - `buddy build components` -- Build component libraries
 - `buddy build docs` -- Build documentation site
 - `buddy build server` (alias: `build:docker`) -- Build Docker server image

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

@@ -132,7 +132,7 @@ buddy queue                  # queue management
 - Prefer `default new Job({...})` for dispatch methods. Discovery also supports default objects with handle and class exports with a handle method
 - The `handle()` method receives the payload passed to `dispatch()`
 - `dispatchNow()` runs immediately in the current process - no queue involved
-- Default queue driver is `sync` - jobs run immediately unless changed to `database` or `redis`
+- Default queue driver is `sync` locally and `database` when `APP_ENV=production` (`QUEUE_DRIVER` overrides both). On `sync`, `dispatchAfter` blocks the caller for the delay
 - Jobs with `rate` are auto-discovered by the scheduler
 - Backoff array `[10, 30, 60]` means: retry after 10s, then 30s, then 60s
 - Jobs should be idempotent - safe to retry on failure
@@ -148,6 +148,9 @@ driver. `.withIdempotencyKey(key)` claims a persistent dispatch key.
 Inside `db.transaction()` dispatch defers until commit by default;
 `.afterCommit()` states that intent, and `.withoutCommit()` explicitly opts
 out. Outside a transaction, afterCommit warns and dispatches immediately.
+Only the fluent builder is transaction-aware: `SomeJob.dispatch()` on a
+`new Job(...)` instance sends at once, even inside a transaction, so use
+`job(name, payload)` there.
 See `stacks-queue` for the complete envelope and batch lifecycle.
 
 Scheduling a named job through `schedule.job()` runs it in the scheduler by

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

@@ -1,83 +1,503 @@
 ---
 name: stacks-native
-description: Use when planning or implementing a Stacks feature, choosing a native API, or checking which framework capability already solves a task. Covers the complete native package catalog, model-driven workflows, feature gates, driver evidence, and cross-package gotchas.
+description: Use when planning or implementing a Stacks feature, choosing a native API, or checking which framework capability already solves a task. A verified cheat sheet of the idiomatic call for every subsystem (models, queries, actions, routes, auth, jobs, events, mail, cache, storage, search, CMS, commerce, AI, stx, CLI, tests, deploy) plus the native package catalog, driver evidence and cross-package gotchas.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
 ---
 
-# Native Stacks capabilities
-
-Start with the native feature that already owns the behavior. Read the selected
-subsystem skill before implementing its API. [CATALOG.md](CATALOG.md) maps every
-core package to task guidance and its current source entrypoint; browse the
-relevant section rather than loading the whole reference.
-
-## Choose a workflow
-
-| Need | Native workflow |
-|---|---|
-| Persist a new entity and expose CRUD | `stacks-models`, `stacks-migrations`, `stacks-orm`, `stacks-actions`, `stacks-router` |
-| Extend a built-in model without forking it | `extendModel`, then model-driven migration generation |
-| Typed requests and an inferred API client | `Action.validations`, directly registered actions, `createTypedRouter` and `createTypedClient` |
-| Authenticate or authorize rows | `stacks-auth`, model API ownership, middleware, policies and gates |
-| Render interactive pages and validate forms | `stacks-stx`, `stacks-composables`, `stacks-forms`, `stacks-ui` |
-| Queue work or run it later | `stacks-jobs`, `stacks-queue`, `stacks-scheduler` |
-| Send mail, notifications, SMS or push | `stacks-mail`, `stacks-email`, `stacks-notifications`, `stacks-sms`, `stacks-push` |
-| Publish CMS pages or run commerce | `stacks-cms`, `stacks-commerce`, `stacks-payments` |
-| Build sites, newsletters, charts or media | `stacks-sites`, `stacks-newsletter`, `stacks-charts`, `stacks-image`, `stacks-audio`, `stacks-video` |
-| Paginate, cache, search or store files | `stacks-pagination`, `stacks-cache`, `stacks-search-engine`, `stacks-storage` |
-| Enable an optional bundle or run an experiment | `stacks-features` for framework bundles, `stacks-feature-flags` for user-targeted flags |
-| Build, deploy or operate an app | `stacks-build`, `stacks-deploy`, `stacks-cloud`, `stacks-server`, `stacks-buddy` |
-
-## Model-first implementation
-
-Declare schema, validators, fillable fields, relationships, traits, and ownership
-in `app/Models/`. `defineModel()` produces the query surface immediately;
-`useApi` registers CRUD at runtime. It does not require generated ORM classes
-or generated action files. Add a custom Action only when the behavior differs
-from the native CRUD contract.
-
-Run `./buddy generate:migrations`, review the SQL and dialect snapshot, then
-run it again to confirm no further diff. Apply with `./buddy migrate`.
-Keep models, generated migrations, and the snapshot together in review.
-`migrate:fresh` destroys tables and is a separate development operation.
-
-See [RECIPES.md](RECIPES.md) for an end-to-end native tracer bullet and
-the cases that require an action, job, policy, or explicit route.
-
-## Important boundaries
-
-- Before adding imports in app code, consult the context-specific names in
-  `storage/framework/auto-imports/RUNTIME.md` at the project root. Use listed
-  runtime helpers directly; read `stacks-auto-imports` for initialization and
-  module boundaries. Generation refreshes the inventory for this app.
-- `app/` overrides framework defaults. Use `extendModel` for additive model
-  changes; an ordinary override replaces the definition.
-- Generated CRUD defaults to authenticated routes. Ownership and policies
-  govern rows separately; unscoped writes may be withheld by the default
-  row-scoping policy. Do not weaken that policy to make an example work.
-- Transactional queries use the supplied `tx` handle. Model calls do not
-  automatically join that transaction's connection.
-- Optional bundles control model/migration/view selection. Route mounting has
-  its own registry and default-bundle selection; a package being installed
-  does not mean every route is public or mounted.
-- Browser declarations, stx eager bindings, demand-inline bindings, and
-  explicit imported composables are different surfaces. Read
-  `stacks-auto-imports` before using an unfamiliar bare name.
-- Use request-time subpath exports when available. Tooling barrels may load
-  migrations, config discovery, or native modules that a handler does not need.
-- A typed configuration or exported adapter is not proof of provider support.
-  [CAPABILITIES.md](CAPABILITIES.md) is generated from the driver evidence
-  registry, including partial and experimental limits.
-
-## Completion and freshness
-
-Use the subsystem's actual signatures and retained tests, and verify the
-requested behavior. Run pickier through buddy, relevant tests, and the proper
-typecheck. UI changes also complete the design preflight.
-
-Within the framework repository, the native catalog and driver reference are generated by
-`./buddy docs:native-skills`; `./buddy docs:native-skills:check` detects missing
-package guidance and stale references. That check establishes coverage and
-source freshness, not semantic correctness of every prose sentence.
+# Stacks, natively
+
+Stacks already ships most of what an app needs. Find the row below, use that
+idiom, and read the named skill before going past it. Each snippet was checked
+against source. The **Gotcha** is the mistake that section most often causes.
+
+Companion files, loaded only when needed:
+[RECIPES.md](RECIPES.md) has end-to-end tracer bullets.
+[CATALOG.md](CATALOG.md) maps every core package to its skill, entrypoint and
+tests (browse one section, don't load all of it).
+[CAPABILITIES.md](CAPABILITIES.md) records which drivers are supported, partial
+or experimental.
+
+## Ten rules
+
+1. **Model first.** The schema, validation, relations, traits and factory all
+   live in one `defineModel()`. Migrations are generated from models, never
+   hand-written first.
+2. **`useApi` before a custom action.** It registers authenticated CRUD at
+   runtime. Write an Action only when the behavior differs from CRUD.
+3. **Override, don't fork.** A file at the same path under `app/` replaces
+   the default. Use `extendModel()` to add fields to a built-in model.
+4. **Don't import what Stacks auto-imports.** Actions, routes, jobs,
+   listeners, middleware, controllers, app commands and stx scripts use the
+   injected names bare (see [Auto-imports](#auto-imports)). Import only names
+   that aren't injected, and in the few files that load without a booted app.
+5. **When you do import, prefer runtime subpaths** such as
+   `@stacksjs/database/runtime` over full barrels. The barrels load tooling
+   that a request does not need.
+6. **Money is integer minor units** (cents), everywhere.
+7. **Writes in a transaction go through `tx`.** Model calls inside
+   `transaction()` do not join it.
+8. **Failures can be silent.** `mail.send`, `notify` and `dispatch` resolve
+   on failure, and every `log.*` call is async. Check results, use the
+   `OrFail`/`AndCollect` variants, and `await log.flush()` before exiting.
+9. **A config type is not driver support.** Check CAPABILITIES.md before
+   promising a provider.
+10. **Prove it.** Run `./buddy lint`, the relevant `./buddy test`, and
+    `./buddy typecheck`. UI work also has to pass the `stacks-design-taste`
+    preflight.
+
+## Auto-imports
+
+The full list for this app is `storage/framework/auto-imports/RUNTIME.md`
+(regenerate it with `./buddy generate:auto-imports`). The snippets below
+follow it, so **a missing import is deliberate.**
+
+- **Server, after boot:** every model (`User`, `Post`, ...) and every job
+  (`SendWelcomeEmail`, ...); `Action`, `route`, `response`, `request`,
+  `Middleware`, `url`, `schema`, `db`, `sql`, `log`, `config`, `path`, `HttpError`,
+  `Auth`, `dispatch`, `listen`, `mail`, `template`, `notify`, `emit`,
+  `emitToUser`, `createChannel`, `schedule`, `Feature`, `collect`, `t`,
+  `setLocale`, `makeHash`, `verifyHash`, `defineModel`; plus the exports of
+  `resources/functions/`.
+- **`<script client>`:** signals (`state`, `derived`, `effect`, `watch`),
+  lifecycle (`onMount`, `onDestroy`), `navigate`, `toast`, `useFetch`,
+  `useQuery`, `useMutation`, `useColorMode`, `useDark`, `keptState`, and the
+  macros (`defineProps`, ...). On-demand helpers such as `useForm`,
+  `useScroll` and `copyToClipboard` are bundled when you call them.
+- **Still import:**
+  - Names not in the list (`cache`, `env`, `Storage`, `transaction`, `job`,
+    `validate`, `defineEvents`, `defineGates`, `defineCommand`, ...).
+  - Type-only names, with `import type`.
+  - `Job` from `@stacksjs/queue`, because the global `Job` is the jobs-table
+    model.
+  - The `Error` and `Request` models, which are never made global.
+- **Files that load without globals, so they import everything:**
+  - Model files, because `generate:migrations`, `migrate` and `seed` read
+    them without booting.
+  - Standalone scripts and framework packages.
+  - `.ts` modules imported by a client script.
+- **Tests get the globals too:** `tests/setup.ts` runs
+  `await bootTestEnvironment()`, so bare-style actions and routes load under
+  `bun test`. An older app whose setup still calls `setupTestEnvironment()`
+  gets "Action is not defined" until it switches.
+
+## Data
+
+### Models (`stacks-models`, `stacks-orm`)
+
+```ts
+// app/Models/Post.ts: imports stay, because migrate/generate/seed load models without globals
+import { defineModel } from '@stacksjs/orm'
+import { schema } from '@stacksjs/validation'
+
+export default defineModel({
+  name: 'Post',
+  table: 'posts',
+  belongsTo: ['User'],                  // adds user_id; generated CRUD derives the owner from the session
+  hasMany: { comments: 'Comment' },     // the object form names the relation explicitly
+  traits: {
+    useUuid: true,
+    useSoftDeletes: true,               // useTimestamps is on unless set to false
+    useApi: { uri: 'posts', routes: ['index', 'store', 'show', 'update', 'destroy'] },
+    useSearch: { searchable: ['title'], filterable: ['status'] },
+    useSeeder: { count: 20 },
+    observe: true,                      // emits post:created / post:updated / post:deleted
+    taggable: true,
+    commentable: true,
+  },
+  attributes: {
+    title: { fillable: true, required: true, validation: { rule: schema.string().max(120) }, factory: f => f.lorem.words(3) },
+    status: { fillable: true, default: 'draft', validation: { rule: schema.enum(['draft', 'published']) } },
+    secret: { hidden: true, guarded: true, encrypted: true },
+  },
+  casts: { meta: 'json' },              // casts sit at model level; attributes have no `cast` key
+} as const)
+```
+
+- **Other attribute keys:** `unique`, `nullable`, `type`, `order`, `foreignKey`, `personal`.
+- **Other traits:** `useAuth`, `billable`, `likeable`, `categorizable`,
+  `useAudit`, `useActivityLog`, `prunable`, `gdpr`, `broadcastOn`/`broadcastWith`.
+- **Add fields to a built-in model:**
+  `export default extendModel(Order, { attributes: { note: {...} } })`.
+- **Gotcha:** a misspelled trait only logs a warning and is otherwise ignored.
+  Event names come from the lowercased model name with no separator, so
+  `StatusReport` emits `statusreport:created`.
+
+### Queries, transactions, pagination (`stacks-query-builder`, `stacks-database`, `stacks-pagination`)
+
+```ts
+const post = await Post.find(id)                   // undefined if missing; findOrFail throws
+const rows = await Post.where('status', 'published').with('user').orderBy('id', 'desc').get()
+const created = await Post.create({ title })
+await created.update({ title: 'New' }); await created.delete()
+await Post.update(id, data); await Post.delete(id) // static forms: row | undefined, boolean
+const page = await Post.where('status', 'published').paginate(20, 2)  // (perPage, page)
+
+import { transaction } from '@stacksjs/orm'
+await transaction(async tx => tx.insertInto('posts').values({ title }).execute(), { retries: 2 })
+
+await db.updateTable('posts').set({ status: 'archived' }).where('id', '=', id).execute()   // raw builder (db is a global)
+```
+
+- **More helpers:** `first`, `count`, `exists`, `pluck`, `whereIn`, `latest`,
+  `firstOrCreate`, `updateOrCreate`, `createMany`, `simplePaginate`,
+  `cursorPaginate(perPage, cursor, ['created_at', 'id'])`, `withoutEvents`.
+- **Pagination defaults:** with no arguments, `paginate()` reads
+  `?page&per_page`, uses 15 per page, and caps `per_page` at 100.
+- **Gotcha:** `paginate` takes `(perPage, page)`, the reverse of upstream.
+  `.where(...).update()` and `.delete()` on a builder return a count, not rows.
+
+### Migrations and seeding (`stacks-migrations`)
+
+```sh
+./buddy generate:migrations   # diff models against the snapshot and write SQL; review it, then run again to confirm no diff
+./buddy migrate               # apply (--diff previews; non-interactive runs need --generate to also generate)
+./buddy migrate:fresh --seed  # dev only: drops everything
+./buddy seed                  # skips tables that already have rows unless --fresh
+./buddy migrate:status
+```
+
+**Gotcha:** commit the model, its generated migration and the
+`model-snapshot.<dialect>.json` together. A stale snapshot fails the next deploy.
+
+## HTTP
+
+### Actions (`stacks-actions`)
+
+```ts
+// app/Actions/PublishPostAction.ts: Action, schema, response and Post are all globals
+export default new Action({
+  name: 'Publish Post',
+  method: 'POST',
+  validations: { note: { rule: schema.string().max(200) } },   // validated before authorize/handle
+  async authorize(request) { return request.can('update', await Post.findOrFail(request.getParam('id'))) },
+  async handle(request) {
+    const post = await Post.findOrFail(request.getParam('id'))
+    await post.update({ status: 'published' })
+    return response.success(post)
+  },
+})
+```
+
+**Gotcha:** `model: Post` only feeds rules to an explicit
+`await request.validate()`. It validates nothing by itself. An `authorize`
+that returns `false` produces a 403.
+
+### Routes, middleware, responses (`stacks-router`, `stacks-middleware`, `stacks-api`)
+
+```ts
+// routes/api.ts (mounted at /api automatically)
+route.post('/posts/{id}/publish', 'Actions/PublishPostAction').middleware('auth')
+route.group({ prefix: '/v1', middleware: ['auth'] }, () => {
+  route.get('/me', 'Actions/Auth/GetMeAction').name('me').rateLimit(60, 'minute')
+})
+route.resource('tags', 'Tag', { only: ['index', 'show'] })
+
+// Typed end to end: register imported actions, infer the client
+import { createTypedClient, createTypedRouter } from '@stacksjs/router'
+export const api = createTypedRouter().get('/v1/posts', PostIndexAction).post('/v1/posts', PostStoreAction, { middleware: 'auth' })
+const client = createTypedClient<typeof api>({ baseUrl })
+```
+
+```ts
+// app/Middleware/EnsureBeta.ts (Middleware is a global): return nothing to continue, throw to stop
+export default new Middleware({ name: 'EnsureBeta', priority: 5, async handle(request) { /* ... */ } })
+// app/Middleware.ts
+import { defineMiddleware } from '@stacksjs/router'
+export default defineMiddleware({ beta: 'EnsureBeta' })   // merged over the built-in aliases
+```
+
+- **Built-in middleware aliases:** `auth`, `guest`, `can:ability,model`,
+  `throttle`, `verified`, `role`, `permission`, `abilities`, `signed`, `csrf`,
+  `cors`, `site`, `env:production`, `maintenance`.
+- **Responses:** `response.json(data, { status })`, `success(data, msg?)`,
+  `created(data)` (both wrap the payload as `{ success, data }`), `noContent()`,
+  `notFound(msg?)`, `forbidden()`, `unauthorized()`,
+  `validationError(errors)`, `error(msg, status = 400)`, `serverError()`,
+  `redirect(url)`, `text(s, status?)`, `view(html)`, `download(path)`.
+  Returning a plain object gives raw JSON.
+- **Gotcha:** there is no `route.prefix()` (use `group({ prefix })`) and no
+  `response.html()` (use `view`). String action paths load lazily and don't
+  infer response types; pass the imported action when a typed client needs them.
+
+### Validation and errors (`stacks-validation`, `stacks-error-handling`)
+
+```ts
+import { validate } from '@stacksjs/validation'   // schema is a global, validate is not
+const data = await validate(request, { email: schema.string().email().required() })  // 422 HttpError on failure
+
+import { fromPromise } from '@stacksjs/error-handling'
+const r = await fromPromise(fetchThing()); if (r.isErr) log.warn(r.error)            // isOk / isErr are properties
+throw new HttpError(409, 'Already exists')                                            // HttpError is a global
+```
+
+**Gotcha:** `validate()` returns only the declared fields that were sent.
+Unknown fields are dropped silently.
+
+## Auth and access (`stacks-auth`)
+
+```ts
+const session = await Auth.login({ email, password })          // { user, token, ... } | null
+const user = await request.user()                              // set by the 'auth' middleware; undefined on public routes
+const viewer = await Auth.user()                               // resolves the bearer token or cookie itself
+const token = await Auth.createToken(user, 'cli', ['posts:read'])
+
+// app/Gates.ts
+import { defineGates } from '@stacksjs/auth'
+export default defineGates({ gates: { 'edit-settings': user => user.isAdmin }, policies: { Post: 'PostPolicy' } })
+// in an action
+await request.authorize('update', post)                        // throws a 403
+```
+
+- **2FA:** `generateTwoFactorSetup`, `enableTwoFactor`, `verifyTwoFactorLoginCode`.
+- **Passkeys:** `beginPasskeyRegistration` / `finishPasskeyAuthentication`. In the
+  browser, import from `@stacksjs/auth/passkeys-browser`.
+- **Gotcha:** an ability with no gate and no policy method is denied. Don't
+  loosen the default row-scoping policy to make an example work. Declare an
+  owner instead (see RECIPES.md).
+
+## Background work
+
+### Jobs and queues (`stacks-jobs`, `stacks-queue`)
+
+```ts
+// app/Jobs/SendWelcomeEmail.ts: import Job, because the global Job is the jobs-table model
+import { Job } from '@stacksjs/queue'
+export default new Job({ name: 'SendWelcomeEmail', queue: 'emails', tries: 3, backoff: [10, 30, 60], async handle({ email }: { email: string }) { /* ... */ } })
+
+await SendWelcomeEmail.dispatch({ email })                       // global; also dispatchAfter(60, p), dispatchNow(p)
+import { job } from '@stacksjs/queue'
+await job('SendWelcomeEmail', { email }).delay(60).afterCommit().dispatch()   // the transaction-aware builder
+```
+
+**Gotcha:** only `job(...)` waits for a transaction to commit. Inside
+`transaction()`, `Job.dispatch()` sends immediately. The driver is `sync`
+locally and `database` in production, and durable drivers need a worker.
+
+### Scheduler (`stacks-scheduler`)
+
+```ts
+// app/Scheduler.ts
+export default function () {
+  schedule.job('Inspire').hourly().onQueue('default')   // without onQueue it runs in the scheduler process
+  schedule.action('CleanupTempFiles').everyFiveMinutes().withoutOverlapping()
+  schedule.command('echo hi').dailyAt('02:00').onOneServer()
+}
+```
+
+**Gotcha:** keep each chain synchronous, because configuration applies in a
+microtask.
+
+### Events and listeners (`stacks-events`, `stacks-listeners`)
+
+```ts
+// app/Events.ts: values resolve against app/Listeners, then app/Actions
+import { defineEvents } from '@stacksjs/events'
+export default defineEvents({ 'user:registered': ['SendWelcomeEmail'] })
+// app/Listeners/NotifyOps.ts
+import { defineListener } from '@stacksjs/events'
+export default defineListener({ listensTo: 'invoice:settled', handle: async (payload) => { /* ... */ } })
+
+dispatch('invoice:settled', { id })                    // fire and forget (global)
+import { dispatchAndCollect } from '@stacksjs/events'
+const results = await dispatchAndCollect('invoice:settled', { id })   // when you need listener failures
+```
+
+**Gotcha:** the event function is `dispatch`. The `emit` global is realtime
+broadcasting, not events.
+
+## Messaging
+
+```ts
+// Mail (stacks-mail, stacks-email): mail, template, notify and emit are globals
+const { html, text } = await template('welcome', { variables: { name }, subject: 'Hi' })
+await mail.sendOrFail({ to: [email], subject: 'Hi', html, text })       // send() resolves on failure
+const r = await new WelcomeMail(user).send(); if (!r.success) await log.error(r.message)
+
+// Every channel at once (stacks-notifications)
+const results = await notify({ userId, email, phone }, { subject: 'Shipped', body }, ['email', 'sms', 'database'])
+
+// Single channels (stacks-sms, stacks-push, stacks-chat)
+import { sms } from '@stacksjs/sms'; await sms().to('+15551234567').body('Code 1234').send()
+import { send as push } from '@stacksjs/push'; await push(token, { title, body }, { driver: 'fcm' })
+import { send as chat } from '@stacksjs/chat'; await chat({ content: 'Deployed' }, { driver: 'slack' })
+
+// Realtime (stacks-realtime)
+emit('orders', 'created', { id })                      // emitToUser(42, 'notice', data) targets private-user.42
+```
+
+**Gotcha:** `notify` resolves even when a channel failed, so check each
+`result.success`. Only `notify` honors SMS STOP opt-outs. `emit` reaches only a
+broadcast server running in the same process; otherwise it warns and does
+nothing.
+
+## Platform services
+
+```ts
+// Cache (stacks-cache): not a global. TTL in seconds, 0 = forever, omitted = config.cache.ttl
+import { cache } from '@stacksjs/cache'
+await cache.remember(`post:${id}`, 300, () => Post.find(id)); await cache.del(`post:${id}`)
+
+// Storage (stacks-storage)
+import { Storage } from '@stacksjs/storage'   // the global `storage` is a lower-level namespace, not this facade
+const saved = await Storage.put(file, { disk: 'public', dir: 'avatars' })   // { path, url, ... }
+await Storage.disk('s3').write('x.txt', bytes)   // disk() returns an adapter: write/read/deleteFile/publicUrl
+
+// Search (stacks-search-engine), from the useSearch trait
+const hits = await Post.search('widget').where({ status: 'published' }).paginate(20, 1)
+
+// Logging, env, config (stacks-logging, stacks-env, stacks-config)
+await log.info('Order created', { orderId }); await log.error('Charge failed', err, { orderId })
+import { env } from '@stacksjs/env'
+const debug = env.DEBUG; const name = config.app.name   // config and log are globals; declare env keys in config/env.ts
+
+// i18n (stacks-i18n): t is a global; strings live in locales/*.yml with {name} interpolation
+t('greeting', { name })
+
+// Feature flags vs bundles (stacks-feature-flags, stacks-features)
+if (await Feature.for(user.id).active('new-checkout')) { /* user-scoped rollout, async */ }
+import { feature } from '@stacksjs/config'; if (feature('commerce')) { /* framework bundle, sync */ }
+```
+
+**Gotcha:** `cache` has no `forget()`; use `del`. `Storage.disk()` has no
+`put`/`get`. The search index holds only `id` plus the listed fields. Read
+`config` after `await overridesReady` in boot-time code. `setLocale` is
+process-global; use `applyRequestLocale(req)` per request.
+
+## Domains
+
+```ts
+// CMS (stacks-cms): built-in Post, Author, Page, Menu, Redirect, Comment, Tag models
+import { authors, posts } from '@stacksjs/cms'
+const published = await posts.fetchByStatus('published'); await posts.fetchByAuthor(authorId)
+// override a CMS endpoint: create app/Actions/Cms/PostIndexAction.ts
+
+// Payments and commerce (stacks-payments, stacks-commerce): integer cents
+import { Payment } from '@stacksjs/payments'
+const session = await Payment.checkout(user, { mode: 'payment', lines: [{ price: 'price_x', quantity: 1 }], successUrl, cancelUrl })
+await Payment.subscribe(user, 'premium-monthly')
+import { commerce } from '@stacksjs/commerce'; await commerce.orders.placeOrder({ order, items, payment, idempotencyKey })
+
+// AI (stacks-ai): provider comes from config ai.default, a provider name or model id
+import { createAIClient, createEmbedding } from '@stacksjs/ai'
+const { content } = await createAIClient(config.ai).generate([{ role: 'user', content: 'Hi' }], { system: 'Be brief.' })
+```
+
+- **Sites:** `@stacksjs/sites` provides `siteResolver`, `currentSite()` and
+  `forSite(query, column, siteId)`. Queries are not scoped to a site automatically.
+- **Newsletter:** `newsletter.subscribe(email, { list })` from `@stacksjs/newsletter`.
+- **Analytics:** render `getAnalyticsHead(analytics)` in your layout. Nothing
+  is injected for you.
+- **Images:** `image(src).widths([320, 640]).formats(['avif', 'webp']).generate()`.
+- **Charts:** `new Chart(canvas, { type, data })` from `@stacksjs/charts`.
+- **Gotcha:** the default `User` is not `billable`. Publish it and enable the
+  trait before calling `user.checkout()`. `ask()`/`summarize()` always use
+  Bedrock, and `createEmbedding` defaults to OpenAI.
+
+## Utilities (`stacks-strings`, `stacks-arrays`, `stacks-collections`, `stacks-datetime`, `stacks-slug`)
+
+```ts
+import { camelCase, plural, slug, truncate } from '@stacksjs/strings'   // slug('Hello World') -> 'hello-world'
+import { chunk, groupBy, sortBy, unique } from '@stacksjs/arrays'
+collect(users).pluck('name').toArray()                                  // collect is a server global
+import { now } from '@stacksjs/datetime'; now().addDays(3).format('YYYY-MM-DD')   // immutable, months 1-based
+import { uniqueSlug } from '@stacksjs/slug'; await uniqueSlug(title, { table: 'posts', column: 'slug' })
+```
+
+**Gotcha:** `uniqueSlug` checks first and writes later, so keep a UNIQUE
+index. `arrays.range()` is a statistic (max minus min), not a sequence.
+
+## Frontend (`stacks-stx`, `stacks-composables`, `stacks-ts-css`, `stacks-ui`)
+
+```stx
+@extends('layouts/default')
+<script server>
+const post = await Post.where('slug', String(params?.slug || '')).first()   // resources/views/posts/[slug].stx
+if (!post) notFound()
+</script>
+<script client>
+const likes = state(0)
+const label = derived(() => `${likes()} likes`)
+const { data: comments, loading } = useFetch('/api/comments')
+</script>
+@section('content')
+  <h1 class="text-2xl font-semibold dark:text-white">{{ post.title }}</h1>
+  @foreach (post.tags as tag) <span>{{ tag }}</span> @endforeach
+  <button @click="likes.update(n => n + 1)"><i class="i-hugeicons-favourite"></i> {{ label() }}</button>
+  <Card :title="post.title" />
+@endsection
+```
+
+- **Signals:** read with `count()`, write with `.set()` or `.update()`.
+  There is no `.value`.
+- **Composables in client scripts:** `useFetch`, `useQuery`, `useMutation`,
+  `navigate`, `toast.success()`, `useColorMode`, `useDark`, `keptState`.
+  `useForm` is delivered on demand.
+- **Gotchas:**
+  - No `var`, `document` or `window` in stx scripts.
+  - `@foreach` takes no `$` sigil.
+  - Class names must be complete static strings, or added to `safelist`.
+  - The bare stx `useForm(schema, initial)` and the imported
+    `@stacksjs/composables` `useForm({ ... })` are different APIs.
+  - Imported `.ts` modules get no auto-imports.
+
+## CLI, tests, dev, deploy
+
+```ts
+// app/Commands/Greet.ts, auto-discovered (scaffold with: buddy make:command)
+import { defineCommand } from '@stacksjs/cli'
+export default defineCommand({
+  name: 'greet <who>', description: 'Greet a user',
+  options: { '--loud, -l': { description: 'Shout', default: false } },
+  handle(options, who) { console.log(options.loud ? who.toUpperCase() : who) },  // options come first
+})
+```
+
+```ts
+// tests/feature/posts.test.ts (stacks-testing)
+import { actingAs, describe, expect, test } from '@stacksjs/testing'
+import { assertDatabaseHas, factory, refreshDatabase } from '@stacksjs/testing/database'   // DB helpers come from /database
+test('creates a post', async () => {
+  await refreshDatabase()
+  const user = await factory('User').create()                  // actingAs needs a persisted user
+  await actingAs(user).post('/api/posts', { title: 'Hi' })
+  await assertDatabaseHas('posts', { title: 'Hi' })
+})
+```
+
+```sh
+./buddy dev                   # frontend :3000, api :3008, dashboard :3002, docs :3006 (also dev:api, dev:dashboard)
+./buddy test                  # --feature / --unit / a path
+./buddy build                 # interactive picker; without a TTY it builds the frontend views
+./buddy deploy --dry-run      # preview first; CI needs --yes. Undo with buddy deploy:rollback
+./buddy tinker                # REPL with the app booted
+```
+
+**Dashboard, desktop, mobile:** override a dashboard page at
+`resources/views/dashboard/<path>.stx` (`stacks-dashboard`).
+`./buddy dev:desktop` runs the app in a native window (`stacks-desktop`). The
+mobile build reuses the stx views (`stacks-mobile`).
+
+## Cross-cutting boundaries
+
+- **Bundles and routes are separate.** Optional bundles control which models,
+  migrations and views are selected. Route mounting has its own registry, so
+  an installed package does not mean its routes are mounted or public.
+- **Four kinds of browser names.** Browser declarations, stx eager bindings,
+  demand-inline bindings and imported composables are different surfaces.
+  Read `stacks-auto-imports` before using an unfamiliar bare name.
+- **Ownership.** Generated CRUD derives the owner from the authenticated user.
+  Test it with real requests and another user's rows, not a source grep.
+- **Event dispatch.** Ordered dispatch is not the same as awaiting listeners.
+  Use the result-bearing API when the caller needs outcomes.
+- **Skill vs source.** If a skill and the source disagree, trust the source and
+  fix the skill in the same change.
+
+## Keeping this current
+
+Inside the framework repository, `./buddy docs:native-skills` regenerates
+CATALOG.md and CAPABILITIES.md. `./buddy docs:native-skills:check` reports a
+package without guidance or a stale reference. That check proves coverage, not
+that every sentence is right, so verify an idiom against its source entrypoint
+before relying on an edge case.

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

@@ -34,6 +34,16 @@ BigInts as decimal string entries inside a JSON array. Keep those tokens intact
 through query parameters; the ORM parser restores tuples and SQL bindings
 accept decimal strings without a lossy Number conversion.
 
+## Call order
+
+Stacks model pagination takes `(perPage, page)`, the reverse of upstream
+bun-query-builder: `Post.where('status', 'published').paginate(20, 2)`. With
+no arguments it reads `?page` and `?per_page` from the request, defaults to 15
+per page, and caps a query-string `per_page` at 100 (an explicit perPage is not
+capped). `simplePaginate(perPage, page)` and
+`cursorPaginate(perPage, cursor, columns, direction)` follow the same order.
+The ORM paginator does not read the query builder's `pagination.defaultPerPage`.
+
 ## HTTP and UI
 
 ORM request-aware pagination can derive page/limit and attach URLs from the

package/ai/skills/stacks-query-builder/SKILL.md

@@ -44,7 +44,7 @@ await db.insertInto('users')
   .execute()
 
 // Update
-await db.update('users')
+await db.updateTable('users')
   .set({ active: false })
   .where('id', '=', 1)
   .execute()

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

@@ -555,7 +555,7 @@ await SendWelcomeEmail.dispatchNow({ email, name })        // bypass queue
 ## config/queue.ts
 ```typescript
 {
-  default: 'sync',  // implemented dispatch drivers: sync | database | redis
+  default: env.QUEUE_DRIVER || (env.APP_ENV === 'production' ? 'database' : 'sync'),  // sync | database | redis
   connections: {
     sync: { driver: 'sync' },
     database: { driver: 'database', table: 'jobs', queue: 'default', retryAfter: 90 },

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

@@ -312,16 +312,19 @@ await req.tokenCant('delete-users')
 import { response } from '@stacksjs/router'
 
 response.json(data, { status: 200 })
-response.created(data)         // 201
-response.noContent()           // 204
-response.badRequest(data)      // 400
-response.unauthorized()        // 401
-response.forbidden()           // 403
-response.notFound()            // 404
-response.error()               // 500
+response.success(data, 'Saved')       // 200, { success: true, data, message }
+response.created(data, location?)     // 201, { success: true, data }
+response.noContent()                  // 204
+response.badRequest(message?, errors?) // 400
+response.unauthorized(message?)       // 401
+response.forbidden(message?)          // 403
+response.notFound(message?)           // 404
+response.validationError(errors)      // 422
+response.error(message, status?)      // defaults to 400, not 500
+response.serverError(message?)        // 500
 response.redirect(url, 302)
-response.text('hello')
-response.html('<h1>Hi</h1>')
+response.text('hello', 200)
+response.view('<h1>Hi</h1>')          // HTML; there is no response.html()
 ```
 
 ## Error Responses
@@ -367,7 +370,7 @@ route.use(logger)
 ```
 
 ### Available Middleware Aliases (from app/Middleware.ts)
-maintenance, auth, guest, api, team, logger, abilities, can, throttle, local, development, staging, production, env.local, env.development, env.staging, env.production, role, permission, verified
+maintenance, cors, auth, guest, api, team, site, logger, abilities, can, throttle, signed, env, env:local, env:development, env:dev, env:staging, env:production, env:prod, role, permission, verified, csrf, compress
 
 ## Query Tracking
 

package/ai/skills/stacks-search-engine/SKILL.md

@@ -44,7 +44,10 @@ await search.addDocuments('products', [
 ])
 
 // Search
-const results = await search.search('products', 'widget')
+const results = await search.search('products', { q: 'widget', limit: 20, filter: { status: 'active' } })
+
+// From a model with the useSearch trait (the usual call)
+const hits = await Product.search('widget').where({ status: 'active' }).get()
 
 // List indexes
 const indexes = await search.listAllIndexes()

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

@@ -38,14 +38,16 @@ const slug = await uniqueSlug('Product Name', {
 ## Basic Slugify (No Database Check)
 
 ```typescript
-import { slugify } from '@stacksjs/slug'
+import { slug } from '@stacksjs/strings'
 
-slugify('Hello World!')           // 'hello-world'
-slugify('Ünïcödé Têxt')          // 'unicode-text'
-slugify('  Extra   Spaces  ')    // 'extra-spaces'
+slug('Hello World!')           // 'hello-world'
+slug('Ünïcödé Têxt')          // 'unicode-text'
+slug('  Extra   Spaces  ')    // 'extra-spaces'
 ```
 
-Re-exported from `ts-slug` - handles Unicode transliteration.
+`@stacksjs/slug` exports only `uniqueSlug`. The sync helpers live in
+`@stacksjs/strings`: `slug()` lowercases and strips punctuation, while the
+lower-level `slugify()` defaults to `lower: false` and keeps case.
 
 ## Model Usage
 
@@ -77,14 +79,14 @@ interface SlugifyOptions {
 ## Gotchas
 - Omitting either table or column returns the base slug with no query.
 - A title with no letters or digits at all (`!!!`, an emoji) gets a random
-  eight-character slug from `uniqueSlug()`, never `""`; `slugify()` still returns `""`.
+  eight-character slug from `uniqueSlug()`, never `""`; `slug()` still returns `""`.
 - The check and insert are separate: keep a UNIQUE index and handle/retry an
   insert conflict. A helper cannot reserve the returned slug against a race.
 - Collision attempts are bounded; after repeated conflicts the helper returns
   a cryptographically randomized suffix instead of looping forever.
 - Declaring a slug attribute does not itself populate it from the title.
 - `uniqueSlug()` is async - it queries the database
-- `slugify()` is sync - no database interaction
+- `slug()` is sync - no database interaction
 - Collision detection appends `-2`, `-3`, etc. (not random suffixes)
 - Unicode characters are transliterated (u → u, e → e, etc.) where ts-slug's charmap
   romanizes the script (Latin, Greek, Cyrillic, Hebrew, Arabic, Devanagari, Georgian);

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

@@ -24,11 +24,21 @@ before deciding what to test, and this one for how.
 ## Test Setup
 
 ```typescript
-import { setupTestEnvironment } from '@stacksjs/testing'
-import { refreshDatabase, setupDatabase, truncateMysql, truncateSqlite } from '@stacksjs/testing/database'
+// tests/setup.ts, the bunfig [test] preload
+import { bootTestEnvironment } from '@stacksjs/testing'
+
+// NODE_ENV/APP_ENV = 'test', then the server auto-imports (models, jobs,
+// Action, route, response, ...), app listeners and gates
+await bootTestEnvironment()
+```
 
-// Set NODE_ENV and APP_ENV to 'test'
-setupTestEnvironment()
+`bun test` never runs the framework preloader, so this is what makes the
+auto-imported names exist in a test. Without it, loading an action written
+without imports throws "Action is not defined". `setupTestEnvironment()` still
+exists and only sets the env.
+
+```typescript
+import { refreshDatabase, setupDatabase, truncateMysql, truncateSqlite } from '@stacksjs/testing/database'
 
 // MySQL database setup; this helper does not initialize SQLite
 await setupDatabase()

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.75.460",
+  "version": "0.75.463",
   "description": "Stacks, built into VS Code: stx templates, pickier linting and formatting, encrypted env files, the dev server preview and every buddy command. No other extensions required.",
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/defaults",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.460",
+  "version": "0.75.463",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stacksjs/stacks.git",
@@ -45,7 +45,7 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@iconify-json/hugeicons": "^1.2.35",
-    "@stacksjs/mobile": "0.75.460",
+    "@stacksjs/mobile": "0.75.463",
     "@stacksjs/sanitizer": "0.2.798",
     "@stacksjs/stx": "0.2.798",
     "@xterm/addon-fit": "^0.11.0",