@stacksjs/defaults 0.72.98 → 0.72.99

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

@@ -363,16 +363,44 @@ await authUser.authorize('edit-post', post)  // throws if denied
 
 ## Middleware Aliases (app/Middleware.ts)
 
-Available middleware names: `maintenance`, `auth`, `guest`, `api`, `team`, `logger`, `abilities`, `can`, `throttle`, `local`, `development`, `staging`, `production`, `env.local`, `env.development`, `env.staging`, `env.production`, `role`, `permission`, `verified` (EnsureEmailIsVerified)
+Auth-relevant aliases: `auth`, `guest`, `verified` (EnsureEmailIsVerified),
+`abilities`, `can`, `role`, `permission`, `team`, `signed`, `throttle`. The
+environment aliases are `env`, `env:local`, `env:development` / `env:dev`,
+`env:staging`, `env:production` / `env:prod` — with a COLON, not a dot; an
+earlier version of this list wrote `env.local` and those never existed. See
+`stacks-middleware` for the full set and for the `!alias` and `alias:params`
+forms.
 
-## Application Gates Example (app/Gates.ts)
+## Application Gates (app/Gates.ts)
 
 ```typescript
-Gate.define('access-admin', (user) => user?.email?.endsWith('@stacksjs.org') ?? false)
-Gate.define('edit-settings', (user) => !!user)
-Gate.define('view-dashboard', (user) => !!user)
+import { defineGates } from '@stacksjs/auth'
+
+export default defineGates({
+  gates: {
+    'access-admin': user => user?.email?.endsWith('@stacksjs.org') ?? false,
+    'edit-settings': user => !!user,
+    'view-dashboard': user => !!user,
+  },
+  policies: {
+    Post: 'PostPolicy',
+  },
+})
 ```
 
+Registered at boot by `initializeAuthorization()`, from
+`injectGlobalAutoImports()` — the one place every entry point comes through, so
+HTTP, `buddy seed`, a scheduled job and a console command all get the same
+gates.
+
+Both halves of `policies` are checked: the key names a model the ORM exposes,
+the value a policy file under `app/Policies/` or the framework defaults. An
+explicit mapping WINS over the `<Model>Policy` naming convention, which is the
+reason to write one.
+
+`Gate.define(...)` still works for a gate registered at runtime; `defineGates`
+is the declarative form and the one the ability-name completions come from.
+
 ## Default API Routes
 
 - `POST /login` → LoginAction (validates email + password)
@@ -409,6 +437,8 @@ traits: {
 - RBAC has an internal cache (`userRoles`, `userPermissions`, `rolePermissions`) — call `Rbac.flushCache()` after direct DB changes
 - `syncRoles()` and `syncPermissions()` are guard-scoped replacements: they preserve assignments belonging to other guards
 - Gate `before` callbacks can short-circuit — return `true` to allow, `null` to continue checking
+- An ability with no gate and no policy method **denies**. That is the right default, and it means a gate that was never registered is indistinguishable from one that says no — which is how `initializeAuthorization()` went unnoticed while nothing called it
+- `allows()` and friends take `Ability`, which is open (`GateName | PolicyAbility | (string & {})`). A `/can/:ability` route passes an ability straight through, so narrowing it would reject correct code; the union is for completions
 - `withRbac()` and `withAuthorization()` return new objects with methods mixed in
 - The `RbacStore` interface must be implemented and set via `Rbac.setStore()` for RBAC to work
 - Password reset tokens expire after 60 minutes by default

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

@@ -44,7 +44,17 @@ export default defineApp({
 }) satisfies AppConfig
 ```
 
-All builders: `defineApp`, `defineCache`, `defineCdn`, `defineChat`, `defineCli`, `defineDatabase`, `defineDependencies`, `defineDns`, `defineEmailConfig`, `defineEmail`, `defineGit`, `defineHashing`, `defineLibrary`, `defineNotification`, `definePayment`, `defineQueue`, `defineSearchEngine`, `defineSecurity`, `defineServices`, `defineSms`, `defineFilesystems`, `defineUi`, `defineModel`, `defineEvents`
+All builders: `defineApp`, `defineCache`, `defineCdn`, `defineChat`, `defineCli`, `defineDatabase`, `defineDependencies`, `defineDns`, `defineEmailConfig`, `defineEmail`, `defineGit`, `defineHashing`, `defineLibrary`, `defineNotification`, `definePayment`, `defineQueue`, `defineSearchEngine`, `defineSecurity`, `defineServices`, `defineSms`, `defineFilesystems`, `defineUi`, `defineEvents`
+
+`defineModel` is NOT among them: it comes from `@stacksjs/orm`, and it builds a
+model rather than returning a config object. `@stacksjs/config` used to export a
+second one typed `(config: Model) => Model`, which widened every literal a model
+declared - its table name, its attribute names - so a model that imported the
+wrong one silently lost the typing the ORM version exists to provide.
+
+The app-level registries have their own helpers, in the packages that own what
+they name: `defineEvents` and `defineListener` from `@stacksjs/events`,
+`defineMiddleware` from `@stacksjs/router`, `defineGates` from `@stacksjs/auth`.
 
 ## Helper Functions
 - `determineAppEnv(): 'dev' | 'stage' | 'prod' | string`

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

@@ -74,6 +74,52 @@ interface Desktop {
 }
 ```
 
+## Local-first apps: owning the launcher
+
+The launcher Stacks compiles opens a Craft window on the URL in `desktop.json`,
+which is what a hosted Stacks application wants. An app whose subject is the
+machine it runs on — a disk cleaner, a log viewer, a device tool — has no such
+URL: it starts something locally and opens a window on that, on a port it does
+not know until launch.
+
+Write `app/Desktop/launcher.ts` and `build:desktop` compiles that instead, the
+same way anything under `app/` overrides its framework default. `DESKTOP_URL`
+and `APP_URL` then become optional, because the launcher decides what to open.
+
+```ts
+// app/Desktop/launcher.ts — compiled to Contents/MacOS/<AppName>
+import { dirname, join } from 'node:path'
+
+const macos = dirname(process.execPath)          // siblings live here
+const server = Bun.spawn([join(macos, 'my-agent')], { stdout: 'pipe' })
+const port = await readPortFrom(server.stdout)   // the agent picks a free one
+
+const craft = Bun.spawn([
+  join(macos, 'craft-runtime'),
+  `http://127.0.0.1:${port}`,
+  '--title', 'My App',
+], { stdout: 'inherit' })
+
+process.exit(await craft.exited)
+```
+
+Two things follow from declaring your own launcher:
+
+- **Every file `build:desktop` leaves in `storage/framework/desktop-dist` is
+  copied into `Contents/MacOS`.** Compile the sibling binaries your launcher
+  spawns into that directory and they ship with it.
+- **`app/Desktop/Resources/` is copied into `Contents/Resources`.** A
+  prerendered UI, a schema, seed data — a local-first app has a payload, and
+  this is where it goes.
+
+`build:dmg` also narrows App Transport Security for these bundles: an exception
+for `127.0.0.1` rather than `NSAllowsArbitraryLoads`, which would additionally
+permit every unencrypted host on the internet.
+
+Application data belongs in `~/Library/Application Support/<AppName>`, never
+inside the bundle — `/Applications` is not writable by the user, and the bundle
+is replaced wholesale on update.
+
 ## CLI Commands
 
 ```bash

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

@@ -57,6 +57,30 @@ The `env` proxy auto-coerces: `'true'` → `true`, `'123'` → `123`, etc.
 ## StacksEnv Type (100+ typed variables)
 App, Ports, API, Database, AWS, Mail, Services (Stripe, Meilisearch), Frontend, Realtime, Redis, Pusher, Auth, Storage, Queue, plus `[key: string]` catch-all.
 
+## Adding your own variables
+
+Declare them in `config/env.ts`. That is the whole step:
+
+```typescript
+// config/env.ts
+export default defineEnv({
+  STRIPE_WEBHOOK_SECRET: { validation: schema.string(), default: '' },
+  BILLING_RETRIES: { validation: schema.number(), default: 3 },
+  DEPLOY_TARGET: { validation: schema.enum(['staging', 'production']), default: 'staging' },
+})
+```
+
+`env.BILLING_RETRIES` is a `number` and `env.DEPLOY_TARGET` is
+`'staging' | 'production'` everywhere, from the validator - nothing is
+generated, so a variable that exists only in your deploy secrets is typed
+exactly like one in your local `.env`.
+
+`storage/framework/types/env.d.ts` reads the schema and extends `StacksEnv`.
+Do NOT write a `declare module '@stacksjs/env'` block of your own: the
+framework already has one, and a second augmentation listing your keys again
+typechecks while letting a key be typed without being validated or defaulted -
+which is the failure `config/env.ts` exists to prevent.
+
 ## Runtime Detection
 
 ```typescript
@@ -199,3 +223,5 @@ calls or raw client-side `fetch`.
 - Runtime detection uses Bun globals and process properties
 - CI provider detection checks environment variables specific to each CI system
 - The `StacksEnv` type provides autocomplete for 100+ known variables
+- Every variable is `| undefined` - the process may simply not have it set
+- `Bun.env.X` is NOT typed, and holds raw strings. `Bun.env.DEBUG` is `'false'`, which is truthy; use `env.DEBUG`, which coerces. A generator used to declare `Bun.env` from whichever `.env` was on the machine that ran it, typing `DEBUG` as `boolean` - it was removed, and nothing read it

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

@@ -109,16 +109,33 @@ type Off = <Key extends keyof StacksEvents>(type: Key, handler?: Handler<StacksE
 ## Built-in Event Types (StacksEvents)
 
 ```typescript
-interface StacksEvents extends ModelEvents, Record<EventType, unknown> {
-  'user:registered': Record<string, any>
-  'user:logged-in': Record<string, any>
-  'user:logged-out': Record<string, any>
-  'user:password-reset': Record<string, any>
-  'user:password-changed': Record<string, any>
+// @stacksjs/events
+interface AuthEvents {
+  'user:registered': UserRegisteredEvent
+  'user:logged-in': UserLoggedInEvent
+  'user:logged-out': UserLoggedOutEvent
+  'user:password-reset': UserPasswordEvent
+  'user:password-changed': UserPasswordEvent
 }
+
+// Augmentation target - model events land here, and so do yours.
+interface AppEvents {}
+
+type StacksEvents = AppEvents & AuthEvents
+type EventName = keyof StacksEvents & string
 ```
 
-The `Record<EventType, unknown>` intersection allows arbitrary event names beyond the declared ones.
+There is **no** trailing index signature, deliberately: an arbitrary event name is
+what made `dispatch('user:creatd', …)` compile and reach nobody. Declare an
+application's own events on `AppEvents` and the typo becomes a compile error.
+
+```typescript
+declare module '@stacksjs/events' {
+  interface AppEvents {
+    'invoice:settled': { id: number, total: number }
+  }
+}
+```
 
 ## Model Events
 
@@ -188,87 +205,86 @@ answer to "which models emit events" is "the ones that exist".
 ## Event-to-Listener Mapping (app/Events.ts)
 
 ```typescript
-import type { Events } from '@stacksjs/types'
+import { defineEvents } from '@stacksjs/events'
 
-export default {
+export default defineEvents({
   'user:registered': ['SendWelcomeEmail'],
   'user:created': ['NotifyUser'],
-} satisfies Events
+})
 ```
 
-Keys are event names (must match StacksEvents keys). Values are arrays of **Action names** -- these correspond to files in `app/Actions/`.
+Both halves are checked. A key must be an event that exists (`EventName`, above);
+a value must name a listener that is on disk (`ListenerName`, generated into
+`storage/framework/types/actions.d.ts` from `app/Listeners/`, `app/Actions/` and
+the framework defaults behind them). `satisfies Events` is equivalent and still
+supported; `defineEvents` is preferred because it also keeps the literal types,
+so `keyof typeof events` is the two names the file declares rather than `string`.
 
 ## Listener Resolution (app/Listener.ts)
 
-The `handleEvents()` function sets up the entire event-to-action pipeline:
+`handleEvents()` delegates to `registerAppListeners()`, which registers both
+conventions and is idempotent:
 
-### Setup
-```typescript
-export async function handleEvents() {
-  emitter.on('*', listenEvents as WildcardHandler<StacksEvents>)
-}
-```
-Subscribes a single wildcard handler that intercepts ALL events.
-
-### Event Processing Flow
-1. **Fast path**: `eventTypes` Set (pre-computed from `Object.keys(events)`) provides O(1) lookup. Events not in the map are skipped immediately.
-2. **Listener resolution**: For each listener name in the array, `resolveAction(listener)` is called:
-   - Checks `actionCache` Map (in-memory module cache)
-   - Checks `pendingImports` Map (deduplicates concurrent imports of the same action)
-   - Dynamically imports `app/Actions/{listener}.ts`
-   - Validates the module exports a `handle(event)` method
-   - Caches the resolved module in `actionCache`
-3. **Execution**: `processListeners()` iterates listeners sequentially (`for...of`), awaiting each action's `handle(event)` method
-4. **Error handling**: Errors are caught per-listener via `handleError()` from `@stacksjs/error-handling` -- one listener failure does not prevent others
-
-### Caching Details
 ```typescript
-const actionCache = new Map<string, { handle: (event: any) => Promise<any> | any }>()
-const pendingImports = new Map<string, Promise<...>>()
-const eventTypes = new Set(Object.keys(events))  // pre-computed at module load
-```
-
-- `actionCache`: stores resolved action modules permanently
-- `pendingImports`: prevents double-importing when multiple events fire simultaneously for the same listener
-- `eventTypes`: O(1) lookup to skip events with no registered listeners
+import { registerAppListeners } from '@stacksjs/events'
+import { path as p } from '@stacksjs/path'
 
-### Listener Type Support
-The listener can also be a function (not just a string):
-```typescript
-if (typeof listener === 'function') {
-  await listener(event)
-  continue
+export async function handleEvents(): Promise<number> {
+  return registerAppListeners({ base: p.projectPath() })
 }
 ```
 
+Names in the map resolve against `app/Listeners/`, `app/Actions/`, then the same
+two directories under the framework defaults - first match wins.
+
+### Registration Flow
+1. **The map**: `registerFromMap()` imports `app/Events.ts` and, for each name,
+   resolves a module with a `handle` method out of `app/Listeners/`,
+   `app/Actions/` or the framework defaults, then subscribes it to that event
+   directly. A name that resolves to nothing is warned about by name.
+2. **The scan**: `discoverListeners()` walks `app/Listeners/` and registers any
+   default export shaped `{ listensTo, handle }`. `listensTo` may be an array.
+3. **Dedup**: every `(event, module)` pair is claimed once per process, so a
+   listener that appears in both conventions - or a dev server that re-runs
+   boot - registers once rather than twice.
+4. **Payload check**: if the resolved action declares `validations`, a dispatched
+   payload that does not match them is warned about. It is not thrown: the
+   dispatcher has already committed the thing the event announces.
+
+### Where it is called from
+- `injectGlobalAutoImports()` (`@stacksjs/server`), so every path that dispatches -
+  HTTP, `buddy seed`, a scheduled job, a console command - has listeners on the bus
+- `handleEvents()` in `app/Listener.ts`, the app's own override hook
+
+Both on the same boot in dev. The claim registry is what keeps that from being
+two of every listener.
+
 ## Implementation Details
 
 ### Thread Safety
-- mitt handlers are stored in arrays -- `emit()` calls `.slice()` before iterating to safely handle additions/removals during iteration
-- Wildcard handler registration happens once in `handleEvents()` -- the single handler routes all events
+- handlers are stored in arrays -- `emit()` calls `.slice()` before iterating to safely handle additions/removals during iteration
 
 ### Synchronous vs Asynchronous
-- **mitt itself is synchronous**: `emit()` calls handlers directly, does not await them
-- **Listener resolution is asynchronous**: `processListeners()` uses `async/await` for dynamic imports and action execution
-- The wildcard handler in `app/Listener.ts` calls `processListeners()` as fire-and-forget (no await) since mitt doesn't support async wildcard handlers
+- **`emit` is synchronous**: it calls handlers directly and does not await them; an async handler's rejection is logged rather than lost
+- **`emitAsync` / `dispatchAsync` awaits** every matching handler and resolves with their results
+- **Registration is asynchronous**: resolving a listener name imports a module
 
 ### Memory
-- The emitter is a module-level singleton -- created once at import time
-- Action modules are cached permanently in `actionCache` -- hot-reloading new actions requires server restart
-- The `pendingImports` Map entries are cleaned up in the `finally` block of each import
+- The emitter is one per *process*, keyed on `Symbol.for('stacks.events.emitter')` rather than per copy of the package -- two installed copies would otherwise be two separate buses, and a dispatch into the wrong one looks exactly like a dispatch nobody listened for
+- Resolved listener modules are held by the closures registered on the emitter, so adding an action requires a restart
 
 ## Gotchas
 - Events are functional, not class-based -- no need to create event classes
 - The emitter is a **singleton** -- shared across the entire application process
 - Wildcard `'*'` listeners receive `(type, event)` -- regular handlers receive just `(event)`
-- Listeners in `app/Events.ts` are **Action names** (strings), not file paths or handler functions
-- The action module must export a default with a `handle(event)` method
-- Event dispatch via mitt is **synchronous** but listener action resolution (dynamic import) is **asynchronous**
+- Listeners in `app/Events.ts` are **names** (strings), not file paths or handler functions -- resolved against `app/Listeners/`, `app/Actions/`, then the framework defaults
+- The listener module must export a default with a `handle(event)` method
+- Event dispatch is **synchronous** but listener resolution (dynamic import) happens once, at boot
 - Model events only fire when the model has `observe: true` (or array) trait set
 - The event system is ~200 bytes total -- it is intentionally minimal
-- Listener caching means hot-reloading new actions requires server restart
-- If `evt` is `undefined`, handlers are NOT called (mitt checks `if (evt !== undefined)`)
+- Listeners are resolved once at boot, so adding an action requires a server restart
+- If `evt` is `undefined`, handlers are NOT called (`emit` checks `if (evt !== undefined)`)
 - The `'*'` event type cannot be manually emitted -- it only receives forwarded events
 - `off(type)` without a handler argument clears ALL handlers for that type (sets to empty array, not delete)
-- The `StacksEvents` interface extends `Record<EventType, unknown>` allowing any string as an event name
+- `StacksEvents` has **no** index signature: an undeclared event name is a compile error, not a dispatch into the void. Declare your own on `AppEvents`
 - Error logging in mitt uses `console.error` (not `@stacksjs/logging`) to avoid circular dependencies

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

@@ -82,6 +82,9 @@ await SendWelcomeEmail.dispatchNow({ email, name })
 ```typescript
 import { job } from '@stacksjs/queue'
 
+// Checked against `app/Jobs/` AND the framework defaults - the same three
+// directories `resolveJobFile` searches, so the jobs Stacks ships are
+// dispatchable and schedulable by name too.
 await job('SendWelcomeEmail', { email, name })
   .onQueue('emails')
   .delay(60)

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

@@ -18,23 +18,30 @@ Application-level event listeners in `app/Listeners/`.
 ## Event → Listener Mapping (app/Events.ts)
 
 ```typescript
-export default {
+import { defineEvents } from '@stacksjs/events'
+
+export default defineEvents({
   'user:registered': ['SendWelcomeEmail'],    // triggers app/Actions/SendWelcomeEmail.ts
   'user:created': ['NotifyUser'],             // triggers app/Actions/NotifyUser.ts
   'order:created': ['ProcessPayment', 'SendOrderConfirmation'],  // multiple listeners
-} satisfies Events
+})
 ```
 
-Keys are event names. Values are arrays of Action names from `app/Actions/`.
+Keys must be event names that exist; values must name listeners that exist. Both
+are compile errors otherwise, which matters here more than most places: a name
+that resolves to nothing produces one line in boot output and then behaves
+exactly like an event nobody cared about.
 
 ## How Listeners Work
 
 1. Events are dispatched: `dispatch('user:registered', { id: 1 })`
-2. The wildcard handler in `app/Listener.ts` catches ALL events
-3. Checks if the event has registered listeners in `app/Events.ts`
-4. For each listener, dynamically imports `app/Actions/{listener}.ts`
-5. Calls `action.handle(eventData)`
-6. Action modules are cached after first import
+2. At boot, `registerAppListeners()` reads `app/Events.ts` and subscribes each
+   named listener to its event directly
+3. Each name resolves against `app/Listeners/`, then `app/Actions/`, then the
+   same two under the framework defaults - first match wins
+4. Modules under `app/Listeners/` that declare their own `listensTo` are
+   registered by the same call, from a directory scan
+5. A listener that appears in both is registered once
 
 ## Creating a Listener Action
 
@@ -43,7 +50,7 @@ Keys are event names. Values are arrays of Action names from `app/Actions/`.
 export default {
   name: 'SendWelcomeEmail',
 
-  async handle(event: { id: number; email: string; name: string }) {
+  async handle(event: { id: number, email: string, name: string }) {
     // event contains the data passed to dispatch()
     await sendWelcomeEmail({ to: event.email, name: event.name })
     return { success: true }
@@ -51,6 +58,29 @@ export default {
 }
 ```
 
+## Creating a Standalone Listener
+
+A module under `app/Listeners/` that declares its own `listensTo` is registered
+by the boot scan, with no entry in `app/Events.ts`. Use `defineListener` so the
+event name is checked and the payload is inferred from it:
+
+```typescript
+// app/Listeners/SendWelcomeEmail.ts
+import { defineListener } from '@stacksjs/events'
+
+export default defineListener({
+  listensTo: 'user:registered',        // or ['user:created', 'user:updated']
+  handle: async (user, event) => {     // `user` is typed from the event name
+    await sendWelcomeEmail({ to: user.email })
+    void event                         // which event fired, for multi-event listeners
+  },
+})
+```
+
+A glob (`'user:*'`, `'*'`) is a legal subscription and receives the union of
+what the bus carries. A listener that appears here *and* in `app/Events.ts` is
+registered once.
+
 ## CLI Event Listeners (app/Listeners/Console.ts)
 
 For CLI-specific events (not HTTP):

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

@@ -83,16 +83,20 @@ throw new Response(JSON.stringify({ error: 'Rate limited' }), {
 Maps short names to middleware class filenames:
 
 ```typescript
-export default {
+import { defineMiddleware } from '@stacksjs/router'
+
+export default defineMiddleware({
   'maintenance': 'Maintenance',
   'auth': 'Auth',
   'guest': 'Guest',
   'api': 'Api',
   'team': 'Team',
+  'site': 'Site',
   'logger': 'Logger',
   'abilities': 'Abilities',
   'can': 'Can',
   'throttle': 'Throttle',
+  'signed': 'Signed',
   'env': 'Env',
   'env:local': 'EnvLocal',
   'env:development': 'EnvDevelopment',
@@ -103,9 +107,36 @@ export default {
   'role': 'Role',
   'permission': 'Permission',
   'verified': 'EnsureEmailIsVerified',
-} satisfies Middleware
+})
 ```
 
+The alias is yours to invent; the class name is checked against
+`app/Middleware/` and the framework defaults, so `{ auth: 'Auht' }` is a
+compile error rather than a route whose guard resolves to nothing.
+
+This map is **merged over** the framework defaults, not a replacement for them,
+so an alias Stacks adds later is available without editing the file.
+
+## Reference forms
+
+Three shapes are read off a reference, in this order:
+
+| Written | Means |
+|---|---|
+| `'auth'` | the alias, or a class name if no alias matches (`'signed'` → `Signed`) |
+| `'!auth'` | inverted: the route passes only when `auth` refuses |
+| `'throttle:60,1'` | `throttle` with `60,1` in `request._middlewareParams.throttle` |
+
+The **whole** reference is looked up as an alias before the colon is treated as
+a parameter separator. That is what makes `'env:production'` its own alias
+rather than `env` with a parameter - `Env` ignores parameters and accepts every
+known environment, so splitting first turned a production-only route into an
+unguarded one.
+
+Inversion counts a `Response` or a status-carrying error as a refusal, and
+nothing else. A `TypeError` from a bug inside `Auth` is a crash, not a
+declination, and must not let `!auth` through.
+
 ## Applying Middleware
 
 ### Per-Route (Chainable)
@@ -163,18 +194,24 @@ Parameters are stored on `request._middlewareParams[middlewareName]` and parsed
 
 ### Environment Negation Variants
 
-Files exist for `EnvNotLocal`, `EnvNotDevelopment`, `EnvNotStaging`, `EnvNotProduction` — but they have **no aliases registered** in `app/Middleware.ts`.
+`EnvNotLocal`, `EnvNotDevelopment`, `EnvNotStaging` and `EnvNotProduction` exist
+as classes with no alias. Reference them by class name, or write the negated
+form of the positive alias - `'!env:production'` is `EnvNotProduction`.
 
 ## Middleware Loading Flow
 
 ```
-1. Parse middleware name: 'throttle:60,1' → { name: 'throttle', params: '60,1' }
-2. Check middleware cache (loaded once, cached for performance)
-3. Resolve alias: 'throttle' → 'Throttle' (via app/Middleware.ts)
-4. Try loading from app/Middleware/Throttle.ts (user overrides)
-5. Fall back to storage/framework/defaults/app/Middleware/Throttle.ts
-6. Store params on request: request._middlewareParams.throttle = '60,1'
-7. Execute: await middleware.handle(enhancedRequest)
+1. Strip a leading '!', if any, and remember it
+2. Look the WHOLE remainder up in the merged alias map
+   'env:production' is an alias      → { name: 'env:production' }
+   'throttle:60,1' is not            → { name: 'throttle', params: '60,1' }
+3. Check middleware cache (loaded once, cached for performance)
+4. Resolve alias: 'throttle' → 'Throttle'; unaliased names PascalCase
+5. Try loading from app/Middleware/Throttle.ts (user overrides)
+6. Fall back to storage/framework/defaults/app/Middleware/Throttle.ts
+7. Store params on request: request._middlewareParams.throttle = '60,1'
+8. Wrap in the inverter if step 1 saw a '!'
+9. Sort the chain by priority, then execute: await middleware.handle(req)
 ```
 
 User middleware in `app/Middleware/` always takes precedence over framework defaults.
@@ -239,10 +276,11 @@ import { authMiddleware, authMiddlewareHandler } from '@stacksjs/auth'
 ```
 
 ## Gotchas
-- **Priority exists but isn't used for ordering** — the router executes middleware in registration order, not priority order
+- **Priority DOES order the chain** — entries are sorted by `priority` (lower first, default 10) before execution, so CORS can precede auth regardless of the order they were attached in. An earlier version of this file said otherwise. A non-finite or negative value is clamped to the default and warned about once
 - **`terminate()` doesn't exist** — some docs reference it, but it's not in the actual `MiddlewareConfig` interface
 - **Two auth middleware implementations** — defaults version (basic token check) and `@stacksjs/auth` version (full user loading)
-- **EnvNot* files have no aliases** — `EnvNotLocal.ts`, etc. exist but aren't registered in `app/Middleware.ts`
+- **EnvNot* files have no aliases** — reachable by class name, or as `'!env:production'` and friends
+- **The alias map merges over the defaults** — an app's `app/Middleware.ts` adds to and overrides them rather than replacing the set
 - **Middleware is cached after first load** — changes require server restart
 - **User overrides take precedence** — `app/Middleware/Auth.ts` replaces the framework default completely
 - **Group middleware accumulates** — nested groups combine all parent middleware

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

@@ -20,6 +20,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 queue/src/
 ├── action.ts          # Job class with dispatch/dispatchIf/dispatchAfter/dispatchNow
 ├── job.ts             # JobBuilder fluent API + job() helper + jobBatch() + runJob()
+│                     # also `Jobs` (the JobName registry) and `resolveJobFile`
 ├── discovery.ts       # Job auto-discovery from app/Jobs/ via Bun.Glob
 ├── scheduler.ts       # Cron-based job scheduling with overlap prevention
 ├── worker.ts          # Queue worker (database polling & Redis processing)
@@ -75,6 +76,10 @@ export class Job {
 ```typescript
 import { job } from '@stacksjs/queue'
 
+// The name is checked: `job('SendWelcomeEmial')` is a compile error, not a
+// queue row no worker can resolve. `dispatch()` does not look the job up - only
+// the worker does - so an unresolvable name used to enqueue successfully and
+// fail later, out of sight of the caller.
 await job('SendWelcomeEmail', { email, name })
   .onQueue('emails')
   .delay(60)           // seconds

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

@@ -15,7 +15,8 @@ Built on `@stacksjs/bun-router` with `ts-rate-limiter`.
 - Route files: `routes/` (api.ts, v1.ts, buddy.ts, users.ts)
 - Route registry: `app/Routes.ts`
 - Generated route manifest: `storage/framework/stx/routes.ts` (written by the dev server)
-- Generated action paths: `storage/framework/types/actions.d.ts`
+- Derived name types: `storage/framework/types/registries.d.ts`
+- The maps they read: `storage/framework/auto-imports/{actions,listeners,policies,middleware,emails,routes}.ts`
 
 ## Route Definition
 
@@ -56,12 +57,20 @@ route.group({ prefix: '/api/v1', middleware: ['auth', 'throttle'] }, () => {
 - Action object: an imported action, passed directly — see typed routes below
 - Controller: `'Controllers/UserController@index'` — calls controller method
 
-## The strings are typed (run `buddy generate:types`)
+## The strings are typed
 
 Action paths, middleware aliases and route names are all checked at compile
-time against what this application actually has. `buddy generate:types`
-discovers them and writes them into the router's type registry
-(`storage/framework/types/actions.d.ts`); nothing is maintained by hand.
+time against what this application actually has, and nothing is maintained by
+hand - or generated as a type.
+
+Each of them is `keyof` over a map the RESOLVER reads:
+`storage/framework/auto-imports/{actions,middleware,routes}.ts`, name to file,
+written by `buddy generate` alongside the models and jobs barrels. So a name
+that type-checks is a name that resolves; there is no second list to go stale.
+`storage/framework/types/registries.d.ts` is where the derivation lives.
+
+Middleware aliases need no map at all - `app/Middleware.ts` and the framework's
+own are ordinary modules, and `defineMiddleware` keeps their literal keys.
 
 ```typescript
 route.get('/login', 'Actions/Auth/LogniAction')   // ✗ no such action
@@ -78,8 +87,9 @@ Notes:
   member name, not a filename.
 - Negated (`'!auth'`) and parameterised (`'throttle:60,1'`) middleware forms are
   both accepted.
-- Regenerate after adding an action, a middleware alias, or a `.name()`. A stale
-  file rejects code that is correct.
+- The maps refresh on `buddy generate`, `buddy generate:types` and dev-server
+  boot, and the staleness check watches the directories they are built from. A
+  map written before a file was added rejects code that is correct.
 - `resource()` takes a BASE, and composes `Actions/<Base><Kind>Action` from it.
   `route.resource('posts', 'Post')` → `Actions/PostIndexAction`, matching where
   `buddy make:crud` writes. The base is checked against the actions that exist;

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

@@ -47,7 +47,7 @@ The `Schedule` class is the core scheduling API. The lowercase `schedule` export
 import { schedule } from '@stacksjs/scheduler'
 
 // Static factory methods — each returns UntimedSchedule
-schedule.job(name: string): UntimedSchedule      // Runs a job by name via runJob()
+schedule.job(name: JobName): UntimedSchedule     // Runs a job by name via runJob()
 schedule.action(name: string): UntimedSchedule    // Runs an action by name via runAction()
 schedule.command(cmd: string): UntimedSchedule    // Runs a shell command via runCommand()
 

package/app/Actions/Dashboard/Commerce/CommerceCustomersAction.ts

@@ -21,7 +21,7 @@ export default new Action({
       return {
         records,
         summary: summarizeCommerceCustomers(records),
-        currency: normalizeCommerceCustomerCurrency((config as any).commerce?.currency),
+        currency: normalizeCommerceCustomerCurrency(config.commerce?.currency),
       }
     }
     catch (error) {