@stacksjs/defaults 0.75.109 → 0.75.110

package/ai/skills/stacks-auth/ACCOUNT-WORKFLOWS.md

@@ -0,0 +1,113 @@
+# Native account workflows
+
+Read this when an account feature needs the native workflow rather than a token
+or TOTP primitive. All source paths below start at
+`storage/framework/core/auth/`. Public exports are in `src/index.ts`.
+
+## Passwordless magic links
+
+`sendMagicLink(email, options?)` accepts redirectTo, siteId, ttlMinutes and
+createUser. Enable `config.auth.magicLink` and its route bundle before building
+a form around the default actions. The native link flow keeps the bearer hashed
+at rest and uses a POST to consume it; GET is an interstitial because mail
+scanners prefetch links.
+
+`consumeMagicLink(raw)` returns a discriminated result with userId/email/redirect
+on success, or invalid/expired/used/no-user. The transactional `withMagicLink`
+helper binds consumption to issuance; read its callback signature before writing
+an alternative action. `pruneMagicLinkTokens(olderThanDays?)` removes old state.
+Redirects must be local paths, and successful consume does not by itself set an
+HTTP cookie. Keep issuance inside the native completed-login flow.
+
+Source: `src/magic-link.ts`. Evidence: `tests/magic-link.test.ts`,
+`magic-link-owner.test.ts`, `magic-link-send-atomicity.test.ts` and
+`magic-link-drivers.test.ts`. A database failure or mail failure is not a reason
+to return an unusable credential as successful login.
+
+## Two-factor setup and completed login
+
+`TwoFactor` and its named functions manage setup, pending secrets, challenges,
+verification and recovery, beyond generating a TOTP code. Native functions
+include generateTwoFactorSetup, stashPendingTwoFactorSecret,
+consumePendingTwoFactorSecret, enableTwoFactor, disableTwoFactor,
+verifyTwoFactorLoginCode, createTwoFactorChallenge, consumeTwoFactorChallenge,
+withTwoFactorChallenge and revokeTwoFactorChallenges.
+
+Use the default action flow as the application reference: the password step
+creates a challenge, and completed verification issues the actual browser
+credential. The challenge carries the remembered-lifetime choice. Setup and
+disable actions impose their own proof and reauthentication requirements;
+low-level helper calls do not establish that the caller owns the account.
+
+Source: `src/two-factor.ts` and default auth actions. Evidence:
+`tests/two-factor-login-wiring.test.ts`, `two-factor-recovery.test.ts`,
+`two-factor-disable-reauth.test.ts`, `two-factor-challenge-atomicity.test.ts` and
+`two-factor-state-atomicity.test.ts`.
+
+## Cookie tokens and database sessions
+
+Bearer/token-cookie auth and `SessionAuth` database sessions use different
+credentials. The default Auth middleware tries a parsed bearer, then the
+configured auth token cookie, then `session_id`, and stamps the request user.
+`authCookieName`, authCookie/clearAuthCookie, userFromCookie/cookieCheck and
+logoutCookie are native cookie helpers. Cookie writes need the normal browser
+CSRF flow; a cookie is not a bearer header.
+
+`SessionAuth.login` persists a session with an expiry; logout/destroyAll are
+awaitable mutations. user/check/refresh validate owner, deadline and optional
+idle timeout. `config.auth.idleTimeout` is milliseconds; fingerprint enforcement
+is opt-in via `config.auth.session.enforceFingerprint`, true or individual
+ip/userAgent flags. A changing mobile IP can make enforcement inappropriate.
+Reads outside a request lack a client fingerprint. Session refresh accepts a
+positive finite TTL and uses an observed-version update so it cannot resurrect
+an expired/deleted credential.
+
+Browser-session policy is separately resolved by resolveBrowserSessionPolicy.
+Read `config/auth.ts`: baseline and remembered defaults currently share
+tokenExpiry, and an app may configure them differently. Dedicated personal
+access token and delegated OAuth issuance do not inherit the browser policy.
+
+Source: `src/cookie-auth.ts`, `browser-session.ts`, `request-token.ts`,
+`session-auth.ts`, `page-gate.ts`. Evidence: `tests/session-http-lifecycle.test.ts`,
+`session-idle-timeout.test.ts`, `session-refresh-atomicity.test.ts`,
+`browser-session-policy.test.ts` and `auth-cookie-name.test.ts`.
+
+## Roles, permissions and active teams
+
+RBAC lazily creates the native bun-query-builder store; a custom RbacStore is
+optional. Apply role/permission/pivot migrations before assigning roles.
+`seedDefaultRoles()` idempotently creates admin/dev/client role packs with their
+declared guards. It does not seed the application's permission taxonomy.
+Guard-scoped sync preserves other guards. Direct SQL changes require explicit
+RBAC cache invalidation. A role name that drives UI visibility is not a substitute
+for action authorization.
+
+`resolveTeamContext(request, { allowAnyTeam? })` returns user, current team,
+role, switchable teams and the active preference. Related helpers include
+resolveAuthenticatedMembership, resolveAuthenticatedTeamId,
+resolveAuthenticatedUser, buildActiveTeamCookie and clearActiveTeamCookie.
+An active-team cookie is a preference, not proof of membership; the resolver
+checks the authenticated user's active membership. An operator override is
+application policy and must remain server-owned.
+
+Source: `src/rbac.ts`, `rbac-store-bqb.ts`, `rbac-seed.ts` and `team.ts`.
+Evidence: `tests/rbac-default-store.test.ts`, `rbac-guard-sync.test.ts`,
+`rbac-seed.test.ts` and `active-team.test.ts`.
+
+## Social identity linking and referrals
+
+`resolveSocialSignIn(provider, identity, store?)` resolves durable provider-id
+links first, then applies `config.auth.socials.matching`: link/create/refuse.
+An email match is subject to the identity verification policy; copying an email
+from a provider payload is not sufficient proof to link an existing account.
+Use SocialSignInRefusedError to distinguish configured refusal from infrastructure
+failure. `stacks-socials` owns provider authorization and callback exchange.
+
+Referrals expose createReferralCode(ownerId), attributeReferral(newUserId, input),
+qualifyReferral(referredUserId) and referralSummary(ownerId), with optional
+database injection. Normalize/attribute at registration and qualify at the
+application's real conversion milestone. Attribution alone is not a paid reward.
+
+Source: `src/socials.ts`, `referrals.ts`. Evidence: `tests/social-linking.test.ts`,
+`referrals.test.ts`. All account features remain subject to model loading,
+selected route bundles, config gates and applied migrations.

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

@@ -44,14 +44,14 @@ auth/src/
 └── session-auth.ts        # Session-based SPA auth
 ```
 
-## Auth Class (authentication.ts) — Static Methods
+## Auth Class (authentication.ts) - Static Methods
 
 ### Login & Authentication
-- `Auth.attempt(credentials: AuthCredentials): Promise<boolean>` — validate credentials without creating token
-- `Auth.validate(credentials: AuthCredentials): Promise<boolean>` — alias for attempt
-- `Auth.login(credentials: AuthCredentials, options?: TokenCreateOptions): Promise<{ user, token } | null>` — login and create token
-- `Auth.loginUsingId(userId: number, options?: TokenCreateOptions): Promise<{ user, token } | null>` — login by user ID
-- `Auth.logout(): Promise<void>` — revoke current token
+- `Auth.attempt(credentials: AuthCredentials): Promise<boolean>` - validate credentials without creating token
+- `Auth.validate(credentials: AuthCredentials): Promise<boolean>` - checks credentials without setting the request's authenticated user
+- `Auth.login(credentials: AuthCredentials, options?: TokenCreateOptions): Promise<{ user, token } | null>` - login and create token
+- `Auth.loginUsingId(userId: number, options?: TokenCreateOptions): Promise<{ user, token } | null>` - login by user ID
+- `Auth.logout(): Promise<void>` - revoke current token
 
 ### Personal access tokens (Sanctum-shaped)
 
@@ -59,38 +59,38 @@ auth/src/
 name (`users`, `authors`) and `tokenable_id` its id there, so any model
 declaring `useAuth` can hold tokens - not only `User`.
 
-- `createToken(id, name, scopes, { tokenableType })` — mint one. Returns the
+- `createToken(id, name, scopes, { tokenableType })` - mint one. Returns the
   plaintext ONCE (`plainTextToken`); the table stores a hash and nothing can
   recover it afterwards. `tokenableType` defaults to `users`.
-- `tokens(id, tokenableType?)` — list an owner's live tokens.
-- `tokenCan(scope)` / `tokenCanAll` / `tokenCanAny` / `tokenAbilities` — check
+- `tokens(id, tokenableType?)` - list an owner's live tokens.
+- `tokenCan(scope)` / `tokenCanAll` / `tokenCanAny` / `tokenAbilities` - check
   the current request's token.
 - `revokeToken`, `revokeTokenById`, `revokeAllTokens(id, type?)`,
-  `revokeOtherTokens(id, type?)` — revocation also revokes the paired refresh
+  `revokeOtherTokens(id, type?)` - revocation also revokes the paired refresh
   token, which a raw row delete does not.
-- `setTrailActor(id)` — attribute writes in a queue job or CLI run that has no
+- `setTrailActor(id)` - attribute writes in a queue job or CLI run that has no
   request to read a user from.
 
 The `PersonalAccessToken` model maps the same table, so `owner.with('tokenable')`
 lists exactly what `createToken` minted. It deliberately generates no CRUD
 routes: minting and revoking both carry semantics a generic route does not.
-- `Auth.once(credentials: AuthCredentials): Promise<boolean>` — one-time auth without token
+- `Auth.once(credentials: AuthCredentials): Promise<boolean>` - one-time auth without token
 - `Auth.requestUserTokenWithClient(credentials, clientId, clientSecret): Promise<{ token } | null>` authenticates both a legacy OAuth client and an end user password, then issues a user token. It is not the client credentials grant.
 - `Auth.requestToken(...)` is the deprecated compatibility alias for that same legacy exchange. New delegated integrations use the authorization-code provider.
 
 ### User State
-- `Auth.user(): Promise<UserModel | undefined>` — get authenticated user from bearer token
-- `Auth.check(): Promise<boolean>` — is user authenticated?
-- `Auth.guest(): Promise<boolean>` — is user a guest?
-- `Auth.id(): Promise<number | undefined>` — get authenticated user ID
-- `Auth.setUser(user: UserModel): void` — manually set user
+- `Auth.user(): Promise<UserModel | undefined>` - resolve the current request user through bearer/token-cookie state
+- `Auth.check(): Promise<boolean>` - is user authenticated?
+- `Auth.guest(): Promise<boolean>` - is user a guest?
+- `Auth.id(): Promise<number | undefined>` - get authenticated user ID
+- `Auth.setUser(user: UserModel | undefined): void` - set or clear the current request user
 
 ### Token Creation
 - `Auth.createTokenForUser(user, options?: TokenCreateOptions): Promise<NewAccessToken>`
 - `Auth.createToken(user, name?, abilities?): Promise<AuthToken>`
 
 ### Token Validation
-- `Auth.validateToken(token: string): Promise<boolean>` — validate bearer token
+- `Auth.validateToken(token: string): Promise<boolean>` - validate bearer token
 - `Auth.getUserFromToken(token: string): Promise<UserModel | undefined>`
 - `Auth.currentAccessToken(): Promise<PersonalAccessToken | undefined>`
 
@@ -113,9 +113,9 @@ routes: minting and revoking both carry semantics a generic route does not.
 - `Auth.findToken(tokenId: number): Promise<PersonalAccessToken | null>`
 
 ### Utility
-- `Auth.guard(name?: string): typeof Auth` — select guard (returns self)
-- `Auth.viaRemember(): boolean` — always false currently
-- `Auth.clearState(): void` — clear cached user/token
+- `Auth.guard(name?: string): typeof Auth` - select guard (returns self)
+- `Auth.viaRemember(): boolean` - always false currently
+- `Auth.clearState(): void` - clear cached user/token
 
 ## Token System (tokens.ts)
 
@@ -215,8 +215,8 @@ authenticated and CSRF protected.
 ### Gate Functions
 - `define<T>(ability: string, callback: GateCallback<T>): void`
 - `policy(model: string | { name }, policyClass: new () => Policy): void`
-- `before(callback): void` — run before any gate check
-- `after(callback): void` — run after any gate check
+- `before(callback): void` - run before any gate check
+- `after(callback): void` - run after any gate check
 - `allows(ability, user, ...args): Promise<boolean>`
 - `denies(ability, user, ...args): Promise<boolean>`
 - `can(ability, user, ...args): Promise<boolean>`
@@ -224,21 +224,21 @@ authenticated and CSRF protected.
 - `any(abilities[], user, ...args): Promise<boolean>`
 - `all(abilities[], user, ...args): Promise<boolean>`
 - `none(abilities[], user, ...args): Promise<boolean>`
-- `authorize(ability, user, ...args): Promise<AuthorizationResponse>` — throws on deny
-- `inspect(ability, user, ...args): Promise<AuthorizationResponse>` — never throws
+- `authorize(ability, user, ...args): Promise<AuthorizationResponse>` - throws on deny
+- `inspect(ability, user, ...args): Promise<AuthorizationResponse>` - never throws
 - `has(ability): boolean`
 - `hasPolicy(model): boolean`
 - `abilities(): string[]`
 - `getPolicyFor<T>(model: T): Policy<T> | null`
-- `flush(): void` — clear all gates
+- `flush(): void` - clear all gates
 
-### Gate Facade — `Gate.define()`, `Gate.can()`, etc
+### Gate Facade - `Gate.define()`, `Gate.can()`, etc
 
 ### AuthorizationResponse Class
 - `static allow(message?): AuthorizationResponse`
 - `static deny(message?, code?): AuthorizationResponse`
 - `allowed(): boolean`, `denied(): boolean`
-- `authorize(): void` — throws AuthorizationException if denied
+- `authorize(): void` - throws AuthorizationException if denied
 
 ### Policy Interface
 Methods: `before?`, `viewAny?`, `view?`, `create?`, `update?`, `delete?`, `restore?`, `forceDelete?`
@@ -287,7 +287,7 @@ Protected helpers: `allow(message?)`, `deny(message?, code?)`, `denyIf(condition
 - `Rbac.syncRolePermissions(roleName, permissionNames[], guardName?): Promise<void>`
 
 ### withRbac Mixin
-`withRbac(user)` — adds `hasRole()`, `hasPermission()`, `assignRole()`, `givePermission()`, etc. to any user object
+`withRbac(user)` - adds `hasRole()`, `hasPermission()`, `assignRole()`, `givePermission()`, etc. to any user object
 
 ### RBAC Types
 ```typescript
@@ -299,10 +299,10 @@ interface RbacStore { findRoleByName, createRole, deleteRole, getAllRoles, findP
 ## Session Auth (session-auth.ts)
 
 - `SessionAuth.login(email, password): Promise<{ user, sessionId }>`
-- `SessionAuth.logout(sessionId): void`
+- `SessionAuth.logout(sessionId): Promise<void>`
 - `SessionAuth.user(sessionId): Promise<UserModel | undefined>`
-- `SessionAuth.check(sessionId): boolean`
-- `SessionAuth.refresh(sessionId, ttlMs?): boolean`, rejects non-positive or non-finite TTLs without changing the session
+- `SessionAuth.check(sessionId): Promise<boolean>`
+- `SessionAuth.refresh(sessionId, ttlMs?): Promise<boolean>`, rejects non-positive or non-finite TTLs without changing the session
 
 Internal: database-backed `sessions` rows with expiry, optional IP/User-Agent fingerprint checks, transactional logout and refresh, and timing-safe password comparison with a dummy bcrypt hash. Sessions survive process restarts and are shared by workers through the configured database.
 
@@ -359,21 +359,27 @@ export const authMiddlewareHandler = {
 }
 ```
 
+
 ## Rate Limiter (rate-limiter.ts)
 
-```typescript
-class RateLimiter {
-  static MAX_ATTEMPTS = 5
-  static LOCKOUT_DURATION = 15 * 60 * 1000  // 15 minutes
-  static MAX_STORE_SIZE = 10_000
-  static EVICTION_INTERVAL = 5 * 60 * 1000  // 5 minutes
-
-  static isRateLimited(email): boolean
-  static recordFailedAttempt(email): void
-  static resetAttempts(email): void
-  static validateAttempt(email): void  // throws HttpError 429
-}
-```
+Every check/update is async, including when the backing store is memory:
+
+~~~ts
+import { RateLimiter } from '@stacksjs/auth'
+
+await RateLimiter.validateAttempt(email)
+await RateLimiter.recordFailedAttempt(email)
+const locked = await RateLimiter.isRateLimited(email)
+await RateLimiter.resetAttempts(email)
+~~~
+
+Five failed attempts lock an email for fifteen minutes. The configured store
+selects atomic Redis when the cache config selects Redis, otherwise process-local
+memory. `useSharedStore(options?)` explicitly chooses Redis;
+`useStore(custom)` installs a store with atomic recordFailedAttempt;
+`useMemoryStore()` and `useConfiguredStore()` reset that choice.
+Shared deployments need a shared atomic store. Partial counters expire, and
+cleanup thresholds are not hard capacities that evict live lockouts.
 
 ## Authorizable Mixin (authorizable.ts)
 
@@ -390,7 +396,8 @@ await authUser.authorize('edit-post', post)  // throws if denied
 
 ### config/auth.ts
 ```typescript
-{
+const tokenExpiry = 60 * 60 * 1000
+const authOptions = {
   default: 'api',
   guards: { api: { driver: 'token', provider: 'users' } },
   providers: { users: { driver: 'database', table: 'users' } },
@@ -399,8 +406,8 @@ await authUser.authorize('edit-post', post)  // throws if denied
   tokenExpiry: 60 * 60 * 1000, // milliseconds, 1 hour
   refreshTokenExpiry: 30 * 24 * 60 * 60 * 1000, // milliseconds
   browserSession: {
-    baselineLifetime: 7 * 24 * 60 * 60 * 1000, // absolute milliseconds
-    rememberedLifetime: 30 * 24 * 60 * 60 * 1000,
+    baselineLifetime: tokenExpiry, // absolute milliseconds, default one hour
+    rememberedLifetime: tokenExpiry, // customize explicitly for a longer remembered tier
     withRefreshToken: false, // fixed browser lifetime, no unused refresh token
     logoutRedirect: '/login?logged_out=1', // local path for HTML logout only
   },
@@ -451,7 +458,7 @@ Retain application-specific onboarding and event hooks.
 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
+`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.
@@ -474,7 +481,7 @@ export default defineGates({
 ```
 
 Registered at boot by `initializeAuthorization()`, from
-`injectGlobalAutoImports()` — the one place every entry point comes through, so
+`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.
 
@@ -518,17 +525,17 @@ traits: {
 - New personal and delegated access tokens are opaque 40-byte hex bearers hashed at rest. Legacy `jwt:encryptedId` bearers remain readable during migration.
 - Token validation hashes the bearer directly. Do not parse or expose token contents, and never log plaintext bearer values.
 - Bearer tokens come from the `Authorization: Bearer <token>` header
-- `Auth.user()` internally calls `getBearerToken()` and resolves the bearer through a hashed token lookup
-- RBAC has an internal cache (`userRoles`, `userPermissions`, `rolePermissions`) — call `Rbac.flushCache()` after direct DB changes
+- Auth resolves the parsed bearer first and falls back to the configured token cookie; request user state is scoped rather than shared globally
+- 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
+- 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
+- RBAC lazily creates its SQL store. `Rbac.setStore()` is the optional override for a custom store; apply the role/permission model migrations before using it
 - Password reset tokens expire after 60 minutes by default
-- Default token abilities are `['*']` — wildcard access
-- Token expiry defaults to 30 days
+- Default token abilities are `['*']` - wildcard access
+- Token expiry defaults to one hour; inspect config/auth.ts and browserSession before choosing a lifetime
 - Session auth uses timing-safe bcrypt comparison even for failed lookups (dummy hash prevents timing attacks)
 
 ## Build
@@ -536,3 +543,29 @@ traits: {
 ```bash
 cd storage/framework/core/auth && bun build.ts
 ```
+
+
+## Native account workflows
+
+Read [ACCOUNT-WORKFLOWS.md](ACCOUNT-WORKFLOWS.md) when implementing magic links,
+completed two-factor login, active teams, social account linking, role seeding,
+referrals, cookie authentication or session idle/fingerprint policy. These are
+native APIs with complete workflows, beyond the low-level TOTP/passkey helpers.
+
+## Provider and entrypoint boundaries
+
+Default auth routes require the selected auth route bundle. `feature('auth')`
+controls account-family model loading and does not itself mount login/register.
+Opaque access tokens, OAuth grants, token cookies and database session IDs are
+different credentials with different issuance and expiry rules.
+`Auth.guard()` currently returns Auth rather than providing independent
+guard implementations. `viaRemember()` is a compatibility false result;
+browserSession's remember choice is the actual cookie lifetime policy.
+
+Session and token user state are bound to the current request. Entry points
+install that scope; application code must not cache a user globally for later
+requests. Revocation-sensitive reads use the primary DB path. Retained evidence:
+`auth/tests/auth-middleware-entrypoints.test.ts`,
+`request-token.test.ts`, `session-read-routing.test.ts`,
+`rbac-default-store.test.ts` and `browser-session-policy.test.ts` under
+`storage/framework/core/`.

package/ai/skills/stacks-auto-imports/SKILL.md

@@ -1,145 +1,87 @@
 ---
 name: stacks-auto-imports
-description: Use when working with the Stacks auto-import system - understanding how browser and server auto-imports work, configuring auto-imported functions/models/composables, the auto-import manifests, type generation, or how globals are injected. Covers the auto-import pipeline at storage/framework/auto-imports/.
+description: Use when checking browser/server binding delivery, model globals, registry generation, or the difference between ambient declarations and runtime imports. Covers Stacks auto-imports, stx client delivery, server boot and generated registries (107 models).
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
 ---
 
-# Stacks Auto-Import System
-
-Automatically makes functions, models, composables, and utilities available globally without explicit imports.
-
-## Key Paths
-- Auto-import functions: `storage/framework/auto-imports/functions.ts`
-- Auto-import models: `storage/framework/auto-imports/models.ts`
-- Auto-import index: `storage/framework/auto-imports/index.ts`
-- Auto-import globals: `storage/framework/auto-imports/globals.ts`
-- Global type declarations: `storage/framework/auto-imports/globals.d.ts`
-- Browser manifest: `storage/framework/browser-auto-imports.json`
-- Server manifest: `storage/framework/server-auto-imports.json`
-- Browser type declarations: `storage/framework/types/browser-auto-imports.d.ts` (~80KB)
-- Server type declarations: `storage/framework/types/server-auto-imports.d.ts`
-- General auto-import types: `storage/framework/types/auto-imports.d.ts`
-
-## How Auto-Imports Work
-
-### Browser Context (STX Templates)
-1. `storage/framework/browser-auto-imports.json` defines available imports (200+ entries)
-2. Types are declared in `storage/framework/types/browser-auto-imports.d.ts`
-3. STX plugin (`bun-plugin-stx`) resolves imports at build time
-4. Available in STX `<script>` tags without explicit `import` statements
-
-Browser auto-import injection applies to the STX script entry being compiled.
-TypeScript modules imported by that script do not inherit its lexical bindings.
-Every imported module must explicitly import the functions, stores, and types it
-uses. A generated ambient declaration proves an identifier is available to an
-STX entry; it does not make that identifier global inside bundled dependencies.
-
-### Server Context (Routes, Actions, Jobs)
-1. `storage/framework/server-auto-imports.json` defines server-side imports (100+ entries)
-2. Types are declared in `storage/framework/types/server-auto-imports.d.ts`
-3. All 60+ ORM models are auto-imported as globals
-4. Available in any server-side TypeScript file
-
-### Runtime Injection
-`storage/framework/auto-imports/globals.ts` injects functions into `globalThis`:
-```typescript
-// Makes these available globally without imports:
-globalThis.increment = increment
-globalThis.count = count
-globalThis.isDark = isDark
-globalThis.toggleDark = toggleDark
-// ... geo functions, GPX functions, etc.
-```
-
-## What Gets Auto-Imported
-
-### Browser Auto-Imports (200+)
-- **Composables**: useStorage, useLocalStorage, useFetch, useToggle, useCounter, useDark, useNow, etc.
-- **Utilities**: debounce, throttle, retry, sleep, wait, delay, lazy, clamp, rand
-- **Authentication**: useAuth, authGuard, auth
-- **Formatting**: formatCurrency, formatDate, formatNumber, formatDuration
-- **Browser Query Builder**: browserQuery, BrowserQueryBuilder, browserAuth, createBrowserModel
-- **Payment**: confirmCardPayment, confirmPayment, createPaymentMethod, loadCardElement, loadPaymentElement
-- **Stripe**: stripe instance
-- **Custom Functions**: From `resources/functions/` (counter, dark mode, GPX, geo utilities)
-
-### Server Auto-Imports (100+)
-- **All ORM Models**: User, Post, Author, Product, Order, Payment, Customer, etc. (107 models)
-- **Request Models**: UserRequest, PostRequest, OrderRequest, etc.
-- **Actions**: Action types and helpers
-- **Schema**: validation schema builder
-- **Router**: route, response helpers
-- **String Utilities**: slug, camelCase, pascalCase, snakeCase, kebabCase, titleCase
-- **Core**: path, storage, log, handleError, Auth, register
-
-## Auto-Import Type Declarations
-
-### auto-imports.d.ts (general)
-```typescript
-declare global {
-  const Action: typeof import('@stacksjs/actions').Action
-  const response: typeof import('@stacksjs/router').response
-  const route: typeof import('@stacksjs/router').route
-  const schema: typeof import('@stacksjs/validation').schema
-  const slug: typeof import('@stacksjs/strings').slug
-  // ... all auto-imported identifiers
-}
-```
-
-### Adding Custom Auto-Imports
-
-1. Create function in `resources/functions/`:
-```typescript
-// resources/functions/myUtils.ts
-export function myHelper() { return 'hello' }
-```
-
-2. Export from `storage/framework/auto-imports/functions.ts`:
-```typescript
-export { myHelper } from '../../resources/functions/myUtils'
-```
-
-3. Declare types in `storage/framework/auto-imports/globals.d.ts`:
-```typescript
-declare function myHelper(): string
-```
-
-4. Inject at runtime in `storage/framework/auto-imports/globals.ts`:
-```typescript
-globalThis.myHelper = myHelper
-```
-
-## Generation Commands
-
-```bash
-buddy generate                  # regenerate all auto-imports
-buddy generate --types          # regenerate type declarations
-buddy generate --ide-helpers    # regenerate IDE helpers
-buddy generate:component-meta   # regenerate component metadata
-```
-
-The `build:reset` script also regenerates auto-imports.
-
-## Server Auto-Import Initialization
-
-```typescript
-import { initiateImports, generateAutoImportFiles, injectGlobalAutoImports } from '@stacksjs/server'
-
-initiateImports()              // initialize auto-import plugin
-generateAutoImportFiles()      // generate runtime auto-import files
-injectGlobalAutoImports()      // inject models/functions globally
-```
-
-## Gotchas
-- Browser auto-imports are resolved at BUILD TIME by bun-plugin-stx — not runtime
-- Imported browser modules must declare their own imports; STX entry auto-imports do not leak into module scope
-- Server auto-imports are injected into globalThis at RUNTIME
-- The browser-auto-imports.d.ts file is ~80KB — it's auto-generated, don't edit manually
-- Custom functions must be exported from both the function file AND the auto-imports barrel
-- Type declarations must match the runtime globals for IDE support
-- All 60+ ORM models are auto-imported on the server — available as `User.find(1)` etc.
-- Request models (e.g., `UserRequest`) are also auto-imported for validated request access
-- Auto-imports are regenerated during `buddy generate` and `build:reset`
-- The discovered-packages.json file at `storage/framework/discovered-packages.json` is part of this system
+# Auto-imports and runtime delivery
+
+A declaration, a delivered client binding, and an initialized server global are
+three different facts. Inspect the relevant runtime rather than inferring all
+three from an ambient type file.
+
+## Browser paths
+
+STX client scripts receive eager runtime bindings, compiler-provided bindings,
+and demand-inline composables emitted for supported authored calls. The eager
+bare-window alias list in AGENTS.md and stacks-composables is checked against
+getCachedSignalsRuntime. That list is one delivery path, not the entire API.
+
+Current STX also supplies useMediaQuery/usePreferredReducedMotion through
+runtime/compiler bindings, and useForm/useIntersectionObserver/useScroll/
+useMouse/useParallax through demand delivery. Read
+[BROWSER.md](../stacks-composables/BROWSER.md) for exact signatures, supported
+installation versions, signal adapters and cleanup. Imported Stacks composables
+can have different Ref contracts from the same-name bare client helpers.
+
+storage/framework/browser-auto-imports.json feeds ambient declarations; it
+is not a complete inventory of executable browser bindings. Utilities,
+provider SDK helpers, stores and custom modules need explicit imports unless
+the installed runtime/compiler/demand implementation actually supplies them.
+
+Bindings injected into a script entry do not leak into an imported TypeScript
+module. Every module declares its own functions, stores and type dependencies.
+Component tag discovery is yet another pipeline; use resources/components or
+explicitly opted-in package component roots.
+
+## Server paths
+
+Server boot resolves model, job, controller and function registries and injects
+eligible values into globalThis. Model definitions exist on disk, but optional
+features and initialization decide the loaded surface. Explicit app-model
+imports preserve inference from the model actually customized by the app.
+
+Only runtime model values are globals. ModelRow<typeof Model> and other type
+utilities are imported types; UserRequest/UserRequestModel are not generated
+runtime model variants. Names colliding with built-ins, such as Error/Request,
+need explicit imports and safe local aliases.
+
+Import Action, route, response, schema, path, storage, logging and Auth from their
+packages. An ambient helper declaration alone does not establish its global
+runtime initialization. Follow the built-in action's import pattern.
+
+## Generation and project overrides
+
+The auto-import barrels under storage/framework/auto-imports are generated from
+app definitions, framework defaults and discovered package resources.
+app/ definitions override defaults at the relevant resolver boundary. Models
+also support additive extendModel rather than a complete copied override.
+
+Use buddy generate and its documented type-generation variants. Do not hand-
+maintain a second list of Action paths, middleware aliases or runtime model
+names. The registry types derive from resolver maps; stale maps can reject a
+new real file, while a typo in a fresh map is a real missing reference.
+
+Application helpers belong in resources/functions and their normal exports.
+Inspect the current generation/discovery pipeline before modifying a generated
+barrel by hand. Components contributed by a package require explicit opt-in;
+views/models/jobs/migrations have their own discovery conventions.
+
+## Verification and gotchas
+
+- Check client delivery in the installed STX, not only with buddy typecheck.
+- Check server globals after boot or model readiness, not during a cyclic import.
+- Distinguish function values from type-only exports and unavailable feature models.
+- Keep imported browser modules self-contained and clean up observers/timers.
+- Use request snapshots for stx server rendering; an API AsyncLocalStorage scope
+  does not automatically span every render callback.
+- Generated declarations and registries are artifacts. Regenerate and inspect
+  differences rather than inventing globals to silence an error.
+
+Source: core/server/src/imports.ts, core/orm/src/index.ts,
+core/config/src/discovered-resources.ts, generated resolver barrels and installed
+STX client/runtime/demand modules. Retained evidence includes
+core/server/tests/generated-declarations.test.ts, ORM auto-import contracts,
+composables/skill-runtime-globals.test.ts and STX delivery tests.