@stacksjs/defaults 0.75.71 → 0.75.73

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

@@ -21,7 +21,7 @@ ai/src/
 │   ├── anthropic.ts      # Claude driver
 │   ├── openai.ts         # GPT + DALL-E + Whisper + TTS
 │   ├── ollama.ts         # Local LLM driver
-│   └── bedrock.ts        # AWS Bedrock utilities
+│   └── bedrock/          # Amazon Bedrock, through the Converse API
 ├── image.ts              # Image generation & vision
 ├── speech.ts             # Provider-neutral text-to-speech & speech-to-text
 ├── search.ts             # RAG, embeddings, vector index
@@ -30,7 +30,7 @@ ai/src/
 ├── buddy.ts              # AI coding assistant
 ├── claude-agent.ts       # Claude CLI agent (local & EC2)
 ├── claude-agent-sdk.ts   # Claude Agent SDK driver
-└── text.ts               # Bedrock text summarization
+└── text.ts               # ask() / summarize(), on the Bedrock driver
 ```
 
 ## Anthropic Driver
@@ -38,7 +38,7 @@ ai/src/
 ```typescript
 import { anthropic } from '@stacksjs/ai'
 
-anthropic.configure({ apiKey: '...', model: 'claude-sonnet-4-20250514', maxTokens: 4096 })
+anthropic.configure({ apiKey: '...', model: 'claude-sonnet-5-5', maxTokens: 4096 })
 const result = await anthropic.chat([{ role: 'user', content: 'Hello' }])
 const stream = await anthropic.streamChat(messages, options)
 const response = await anthropic.prompt('Summarize this text...')
@@ -59,10 +59,34 @@ const transcription = await openai.transcribe(audioFile)
 const speech = await openai.textToSpeech('Hello world')
 ```
 
+## Bedrock Driver
+
+```typescript
+import { bedrock } from '@stacksjs/ai'
+
+bedrock.configure({ model: 'global.anthropic.claude-sonnet-5-5', region: 'us-east-1' })
+const result = await bedrock.chat([{ role: 'user', content: 'Hello' }], { system: 'Be brief.' })
+```
+
+- Every request goes through Bedrock's Converse API, so one shape serves Nova,
+  Claude and Llama; the model is configuration. No streaming yet.
+- Credentials come from the AWS credential chain, never config. Region:
+  `drivers.bedrock.region`, `AWS_REGION`, `AWS_DEFAULT_REGION`, us-east-1.
+- Default model `amazon.nova-lite-v1:0`: on demand, no profile, no agreement.
+- Claude and the newer Nova/Llama models are invoked by **inference profile**
+  id (`global.anthropic.claude-sonnet-5-5`, `us.meta.llama4-...`). The bare
+  `anthropic.claude-...` id is refused by Bedrock. `bedrockModels` in
+  `@stacksjs/types` lists the ids Bedrock serves, each in invocable form.
+- `buddy ai:access` (or `requestModelAccess()`) makes the models in
+  `config/ai.ts` invocable and reports each one.
+
 ## Provider-Neutral Client
 
 Use the config-driven client for application features that can run against
-Anthropic, OpenAI, or Ollama. Configuration inspection is safe to return from a
+Anthropic, OpenAI, Ollama, or Bedrock. `default` is a provider name or a model
+id that implies one: `claude-...` Anthropic, `gpt-...` OpenAI, any Bedrock
+model or profile id (`amazon.nova-lite-v1:0`, `global.anthropic.claude-...`)
+Bedrock. Configuration inspection is safe to return from a
 status endpoint because it never includes credentials.
 
 ```typescript
@@ -216,7 +240,7 @@ const sentiment = await analyzeSentiment('I love this product!')
 const classification = await classifyText('Fix the login bug', ['bug', 'feature', 'question'])
 // { label: 'bug', confidence: 0.92, allLabels: [...] }
 
-const summary = await summarize(longText, { maxLength: 100, style: 'bullet' })
+const summary = await summarize(longText, { maxTokenCount: 100 })
 
 const profile = createProfile('user-123', ['tech', 'gaming'])
 recordInteraction(profile, { type: 'view', itemId: 'article-1', weight: 1.0 })
@@ -229,7 +253,7 @@ const interests = await extractUserInterests(profile, items)
 ```typescript
 import { processCommand, buddyProcessStreaming, buddyStreamSimple, getAvailableDrivers } from '@stacksjs/ai'
 
-const drivers = getAvailableDrivers()  // ['anthropic', 'openai', 'ollama']
+const drivers = getAvailableDrivers()  // ['claude-cli-local', 'claude-cli-ec2', 'claude', 'claude-sdk', 'openai', 'ollama', 'mock']
 const context = await getRepoContext('/path/to/repo')
 await processCommand('Add error handling to auth.ts', 'anthropic')
 // Streaming
@@ -298,9 +322,13 @@ await driver.resumeSession(sessionId, 'Add validation')
 
 ```typescript
 {
-  default: 'meta.llama2-70b-chat-v1',
-  models: ['meta.llama2-70b-chat-v1', ...],  // AWS Bedrock models
-  deploy: true
+  default: 'anthropic',                       // or 'openai', 'ollama', 'bedrock', a model id
+  models: ['amazon.nova-lite-v1:0'],          // Bedrock models `buddy ai:access` enables
+  deploy: false,
+  drivers: {
+    anthropic: { model: 'claude-sonnet-5-5' },
+    bedrock: { model: 'global.anthropic.claude-sonnet-5-5' },
+  },
 }
 ```
 
@@ -314,5 +342,5 @@ await driver.resumeSession(sessionId, 'Add validation')
 - MCP supports stdio (subprocess), SSE, and HTTP transports
 - The buddy assistant has git integration (commit, push, apply changes)
 - Claude Agent SDK wraps the Claude Code CLI for agentic workflows
-- Bedrock utilities are for AWS-hosted model invocation
+- A Bedrock id as `default` selects the Bedrock driver; it never reaches api.anthropic.com
 - Sentiment/classification use AI models — they're not rule-based

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

@@ -426,14 +426,14 @@ buddy cloud --diff             # show infrastructure changes (local vs deployed
 buddy cloud --invalidate-cache # invalidate CloudFront CDN cache
   --paths [paths]              # specific paths to invalidate (default: /*)
 
-buddy cloud:add --jump-box     # add jump box EC2 instance
+buddy cloud:add --jump-box     # check for the jump box infrastructure.jumpBox declares (buddy deploy creates it)
 buddy cloud:remove             # remove cloud infrastructure (aliases: cloud:destroy, cloud:rm, undeploy)
-  --jump-box                   # remove just the jump-box
+  --jump-box                   # check for the jump box, say how to drop it from the stack
   --force                      # force deletion
   --yes                        # skip confirmation
-buddy cloud:optimize-cost      # remove optional resources (jump-box)
+buddy cloud:optimize-cost      # check optional resources (jump-box) that can be dropped
 buddy cloud:cleanup            # clean up retained resources after stack deletion
-# Cleans: jump-boxes, S3 buckets, Lambda functions, CloudWatch logs,
+# Cleans: S3 buckets, Lambda functions, CloudWatch logs,
 # Parameter Store, VPCs, Subnets, CDK remnants, IAM users
 buddy cloud:invalidate-cache   # invalidate CloudFront cache
   --paths [paths]              # paths to invalidate

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

@@ -43,7 +43,13 @@ await sendToDiscord(webhookUrl, content, options?)
 await sendToTeams(webhookUrl, text)
 ```
 
-Configure functions:
+Settings come from `config/services.ts` by default, read on each send after the
+app's config has loaded: `SLACK_WEBHOOK_URL` / `SLACK_BOT_TOKEN`,
+`DISCORD_WEBHOOK_URL` / `DISCORD_BOT_TOKEN`, `TEAMS_WEBHOOK_URL`, and each
+driver's `*_MAX_RETRIES` / `*_RETRY_TIMEOUT`. A webhook URL from config passes
+the same HTTPS and host checks as one given to `configure*()`.
+
+The configure functions override config, for an app that keeps these elsewhere:
 ```typescript
 import { configureSlack, configureDiscord, configureTeams } from '@stacksjs/chat'
 configureSlack({ webhookUrl: '...', botToken: '...' })
@@ -324,9 +330,9 @@ interface TeamsMessage {
 ### Teams Sending
 
 - Uses `config.webhookUrl` or falls back to `message.to` as the webhook URL
-- Validates URL contains `webhook.office.com`
-- Simple messages (no subject/template): sends `{ type: 'message', text: content }`
-- Rich messages (with subject or template): builds an Adaptive Card v1.4 with:
+- Validates the URL as a Teams Workflows (Power Automate) webhook on https: `*.environment.api.powerplatform.com`, `*.api.powerautomate.com`, `flow.microsoft.com` or `*.logic.azure.com` (`.us` / `.cn` too). An Office 365 connector URL (`*.webhook.office.com`) is refused with a migration message - Microsoft retired those connectors in May 2026
+- Every message is an Adaptive Card in `attachments`, which the Workflows webhook template requires; a plain message is a card holding its text
+- Rich messages (with subject or template): the Adaptive Card v1.4 has:
   - Title as `TextBlock` (size: Large, weight: Bolder)
   - Content as `TextBlock` (wrap: true)
   - Timestamp as `TextBlock` (size: Small, color: Dark)
@@ -436,7 +442,7 @@ All three drivers implement `sendWithRetry()`:
 - Slack bot token mode uses `https://slack.com/api/chat.postMessage`, not a webhook
 - Discord webhook returns `204` on success with no body -- this is handled as success
 - Discord bot token mode uses `message.to` as the channel ID
-- Teams validates that the webhook URL contains `webhook.office.com`
+- Teams accepts only Workflows webhook URLs; the retired `webhook.office.com` connectors are refused
 - Teams uses `message.to` as fallback webhook URL if `config.webhookUrl` is not set
 - All drivers set `mrkdwn: true` or equivalent by default
 - Block Kit blocks are only built when `message.template` is set (Slack) or when `message.subject`/`message.template` is set (Discord/Teams)

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

@@ -157,15 +157,15 @@ await purchaseDomain('example.com', { years: 1, privacy: true, autoRenew: true }
 
 // Infrastructure queries
 const sgId = await getSecurityGroupId('my-sg')
-const jumpBoxId = await getJumpBoxInstanceId('stack-name')
+const jumpBoxId = await getJumpBoxInstanceId() // the deployed stack's JumpBoxInstanceId output
 const deployed = await hasBeenDeployed()
 const firstDeploy = await isFirstDeployment()
 const failed = await isFailedState()
 
-// Resource management
-await addJumpBox('stack-name')
-await deleteJumpBox('stack-name')
-await deleteEc2Instance(instanceId, 'stack-name')
+// The jump box is declared by infrastructure.jumpBox and created by `buddy deploy`;
+// these report the stack's state and what to change, never create or terminate.
+await addJumpBox()
+await deleteJumpBox()
 
 // Cleanup
 await deleteStacksBuckets()
@@ -236,7 +236,7 @@ buddy server:setup                    # adopt and bootstrap an ssh host
 buddy cloud --diff                    # show infrastructure changes (aws)
 buddy cloud --ssh                     # SSH into cloud
 buddy cloud --invalidate-cache        # invalidate CDN
-buddy cloud:add --jump-box            # add jump box instance
+buddy cloud:add --jump-box            # check for the jump box (declare infrastructure.jumpBox + buddy deploy)
 buddy cloud:remove --force            # destroy cloud resources
 buddy cloud:cleanup                   # clean retained resources
 buddy cloud:optimize-cost             # remove optional resources
@@ -292,7 +292,10 @@ Stack naming: `{slugified-app-name}-cloud`
 - Server mode uses EC2 + ALB; serverless uses Lambda + API Gateway + CloudFront
 - Origin failover only retries GET, HEAD and OPTIONS on a cache miss; it does not protect writes,
   and the failover replica outlives `buddy cloud:remove`
-- Jump boxes are optional, used for SSH access to private instances
+- Jump boxes are optional, used for SSH access to private instances. They are stack resources:
+  `infrastructure.jumpBox` in config/cloud.ts plus `buddy deploy`, found by the stack's
+  `JumpBoxInstanceId` output. The stack is `stacksCloudName()` (`<project.name>-cloud`) in
+  `stacksCloudRegion()` (AWS_REGION, else the configured region)
 - `cloud:remove` with `--force` skips confirmation and is destructive
 - CDK toolkit stack is named `stacks-toolkit`
 - Environment mapping: `local` → `development`, others preserved

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

@@ -164,9 +164,11 @@ await deleteEmail('chris', messageId)
 - Configurable domain and endpoint
 
 ### Mailtrap Driver
-- Inbox-aware sending
-- Sandbox and production modes
-- Host default: `sandbox.api.mailtrap.io`
+- `MAILTRAP_INBOX_ID` picks the API: set, mail is captured in that sandbox
+  inbox (`sandbox.api.mailtrap.io/api/send/<inbox>`); unset, it is delivered
+  through the Sending API (`send.api.mailtrap.io/api/send`)
+- `MAILTRAP_HOST` overrides the host for either; blank means Mailtrap's own
+- A 4xx other than 429 is not retried
 
 ### SMTP Driver
 - Raw TCP/TLS socket connection

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

@@ -296,7 +296,10 @@ buddy seed --include-defaults    # framework built-ins too
 
 A model with no `useSeeder` trait is never seeded. Auth and OAuth models are
 skipped on a non-fresh database so re-seeding cannot invalidate live sessions -
-pass `--allow-protected` to override.
+pass `--allow-protected` to override. A `belongsTo` to `User`, `Team` or `Customer` is
+filled only from accounts the same run seeded (never a pre-existing, possibly real one);
+`--attach-accounts` lifts that on a scratch database. Composite `unique: true` indexes are
+honoured: fewer rows are seeded rather than a duplicate combination.
 
 ## Built-in models by category
 

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

@@ -21,7 +21,7 @@ no longer a way to configure this driver and there is no fallback to it.
 ## Source Files
 ```
 push/src/
-├── index.ts              # send(), configureFCM(), PushNotification type
+├── index.ts              # send(), configureFCM(), configureExpo(), PushNotification type
 └── drivers/
     ├── index.ts          # re-exports expo and fcm
     ├── expo.ts           # Expo Push Service driver
@@ -204,6 +204,8 @@ interface FCMMessage {
 function configure(options: FCMConfig): void
 ```
 Sets module-level config. Called by `configureFCM()` from the main index.
+Optional: anything it does not set is read from `config/services.ts` on each
+send (see Configuration), and anything it does set wins.
 
 #### send()
 ```typescript
@@ -273,10 +275,30 @@ unsubscribing; that asymmetry is the API's.
 
 ## Configuration
 
+Set the env vars `config/services.ts` reads and both drivers pick them up on the
+next send. No code is needed:
+
+```bash
+FCM_PROJECT_ID=my-firebase-project
+FCM_CLIENT_EMAIL=firebase@project.iam.gserviceaccount.com
+# Paste the key from the service account JSON as-is: its literal \n escapes
+# are turned back into newlines.
+FCM_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
+
+# Only needed once "enhanced push security" is on for the Expo project:
+# Expo then rejects every send and receipt request without it.
+EXPO_ACCESS_TOKEN=...
+```
+
+The values are read lazily, after the app's config has loaded, never at
+import - a value captured at import would be the framework default.
+
+`configureFCM()` / `configureExpo()` override config, for an app that keeps
+credentials somewhere else:
+
 ```typescript
-import { configureFCM } from '@stacksjs/push'
+import { configureExpo, configureFCM } from '@stacksjs/push'
 
-// FCM v1 API: the only FCM configuration there is
 configureFCM({
   projectId: 'my-firebase-project',
   serviceAccount: {
@@ -285,10 +307,13 @@ configureFCM({
   }
 })
 
-
-// Expo requires no configuration
+configureExpo({ accessToken: '...' })
 ```
 
+FCM access tokens are cached per service account until a minute before they
+expire, so a multicast exchanges one token, not one per device.
+`fcm.resetConfiguration()` drops both the configured credentials and the cache.
+
 ## Usage Examples
 
 ```typescript

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

@@ -101,7 +101,7 @@ The `job()` helper loads job modules from `app/Jobs/{name}.ts` via `runJob()`.
 
 ### runJob(name, options)
 Dynamically imports `app/Jobs/{name}.ts` and executes:
-1. `jobConfig.handle(payload)` if handle is a function
+1. `jobConfig.handle(payload, context)` if handle is a function (`context` is what `.withContext()` attached, on every driver)
 2. `runAction(jobConfig.action)` if action is a string
 3. `jobConfig.action()` if action is a function
 4. `jobConfig(payload, context)` if default export is a function

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

@@ -22,7 +22,8 @@ realtime/src/
   emit.ts             # emit(), emitToUser(), emitToUsers()
   channel.ts          # Channel class + channel() factory
   broadcast.ts        # Broadcast class + runBroadcast() + broadcast()
-  ws.ts               # WebSocket request handler (legacy, kept for backward compat)
+  ws.ts               # setWsAuthenticator() - gates upgrades on the broadcast server
+  replay-buffer.ts    # setReplayBuffer() / replaySince() - per-channel replay with seq numbers
   server-instance.ts  # server lifecycle (createServer/getServer/setServer/stopServer)
 ```
 
@@ -43,7 +44,9 @@ export type { EmitOptions } from './emit'
 export { channel as createChannel, Channel as StacksChannel } from './channel'
 export { broadcast as dispatchBroadcast, runBroadcast, Broadcast as LegacyBroadcast } from './broadcast'
 export type { BroadcastInstance } from './broadcast'
-export { setBunSocket, handleWebSocketRequest, storeWebSocketEvent } from './ws'
+export { debugSnapshot, getReplayBuffer, pruneExpired, recordBroadcast, replaySince, setReplayBuffer } from './replay-buffer'
+export { storeWebSocketEvent, setWsAuthenticator, getWsAuthenticator } from './ws'
+export type { WsAuthenticator, WsAuthResult } from './ws'
 ```
 
 Note the renamed exports:
@@ -72,9 +75,9 @@ emit('orders', 'updated', { status: 'shipped' }, { private: true })
 // Broadcast to a presence channel (auto-prefixes 'presence-')
 emit('room-1', 'user-joined', { userId: 42 }, { presence: true })
 
-// Exclude specific socket(s) from receiving
-// NOTE: BroadcastServer only supports single socket exclusion;
-//       if array is passed, only the first element is used
+// Exclude specific socket(s) from receiving - socket IDs (the `socket_id`
+// a client gets in `connection_established`), not user IDs. Every ID in an
+// array is excluded.
 emit('chat', 'typing', data, { exclude: 'socket-id-1' })
 emit('chat', 'typing', data, { exclude: ['socket-id-1', 'socket-id-2'] })
 ```
@@ -85,7 +88,7 @@ emit('chat', 'typing', data, { exclude: ['socket-id-1', 'socket-id-2'] })
 interface EmitOptions {
   private?: boolean     // prefix channel with 'private-'
   presence?: boolean    // prefix channel with 'presence-'
-  exclude?: string | string[]  // socket IDs to exclude (only first used)
+  exclude?: string | string[]  // socket IDs to exclude (all of them)
   driver?: string       // broadcast driver override
 }
 ```
@@ -185,7 +188,53 @@ setServer(server)
 await stopServer()
 ```
 
-`createServer()` dynamically imports `ts-broadcasting`, instantiates `BroadcastServer`, calls `start()`, stores the instance via `setServer()`, and returns it.
+`createServer()` dynamically imports `ts-broadcasting`, instantiates `BroadcastServer`, calls `start()`, stores the instance via `setServer()`, and returns it. That server is the WebSocket endpoint (`/app` and `/ws` on its own host/port); there is no upgrade handler for the app's HTTP server.
+
+### Connection auth
+
+```typescript
+import { setWsAuthenticator } from '@stacksjs/realtime'
+
+// Read on every upgrade, so it applies whether installed before or after createServer().
+setWsAuthenticator(async (req) => {
+  const token = new URL(req.url).searchParams.get('token')
+  const user = token ? await verify(token) : null
+  if (!user) return { ok: false, status: 401, message: 'Unauthorized' }
+  // user -> socket.data.user, data -> socket.data.data (what channel authorizers read)
+  return { ok: true, user: { id: user.id }, data: { team: user.team } }
+})
+```
+
+A refusal answers the upgrade with its status; a throw refuses with a 500 and is logged, not sent. An `authorizeConnection` in the `createServer()` config still runs after it. Per-channel access is still `Broadcast.channel('private-orders.{id}', (socket, params) => ...)`.
+
+`/stats` and `/metrics` are off unless `createServer({ endpoints: { stats: true, metrics: true, token } })`.
+
+### Dead sockets and slow consumers
+
+Bun's own WebSocket options, passed through `createServer()`:
+
+```typescript
+await createServer({
+  host: '0.0.0.0',
+  port: 6001,
+  websocket: {
+    idleTimeout: 60,                 // Bun pings idle sockets; no pong within this -> closed (rounded up to 4s steps)
+    sendPings: true,
+    backpressureLimit: 1024 * 1024,
+    closeOnBackpressureLimit: true,  // drop a consumer that falls 1 MB behind
+  },
+})
+```
+
+### Replay buffer
+
+```typescript
+import { replaySince, setReplayBuffer } from '@stacksjs/realtime'
+
+setReplayBuffer({ channels: ['orders.*'], maxPerChannel: 100, ttlMs: 5 * 60_000 })
+```
+
+Every broadcast on a matching channel, from any API, is recorded and reaches clients as `{ event, channel, data, seq }`. Patterns match with or without the `private-`/`presence-` prefix (`orders.*` covers `private-orders.1`); `replaySince()` takes the full name. The client keeps the last `seq` per channel and sends it back after reconnecting (through a route of the app's), which answers with `replaySince('private-orders.1', seq)`. The buffer and its numbering are per process.
 
 ---
 
@@ -270,13 +319,10 @@ class Broadcast {
 }
 ```
 
-### WebSocket handler (ws.ts)
+### ws.ts
 
 ```typescript
-// Deprecated - handled by ts-broadcasting internally
-setBunSocket(server: BroadcastServer | null): void      // calls setServer()
-storeWebSocketEvent(type, socket, details): Promise<void> // no-op
-handleWebSocketRequest(req, server): Promise<Response | undefined>  // delegates to server.upgrade()
+storeWebSocketEvent(type, socket, details): Promise<void> // no-op, kept for compatibility
 ```
 
 ---
@@ -430,11 +476,11 @@ export default {
 - Private channels auto-prefix `private-` -- don't add it yourself (the code checks `channel.startsWith('private-')`)
 - Presence channels auto-prefix `presence-` -- same logic applies
 - `emitToUser()` sends to `private-user.{userId}` -- users must subscribe to this channel pattern
-- When using `emit()` with `exclude`, only the first socket ID in an array is used (BroadcastServer limitation)
+- `emit()`'s `exclude` takes socket IDs, not user IDs; every ID in an array is excluded
 - Broadcast files are dynamically imported from `app/Broadcasts/` using `bun.globSync`
 - The `Broadcast` class is legacy -- new code should use `emit()` and `channel()` directly
-- `handleWebSocketRequest()` and `storeWebSocketEvent()` are deprecated -- ws events are tracked internally by ts-broadcasting
-- `setBunSocket()` is deprecated -- use `setServer()` instead
+- There is no `handleWebSocketRequest()`: sockets upgraded on the app's own server were never part of the broadcast server, so they could not join channels. Clients connect to the broadcast server's `/ws`
+- There is no Stacks heartbeat or backpressure guard; use `createServer({ websocket: { idleTimeout, sendPings, backpressureLimit, closeOnBackpressureLimit } })`
 - Serverless mode uses API Gateway WebSocket for AWS Lambda with DynamoDB for connection management
 - Rate limiting defaults: 100 connections per IP, 50 messages/second, 64KB max payload, 300s ban duration
 - Redis adapter enables horizontal scaling across multiple server instances

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

@@ -89,11 +89,11 @@ Each sets an internal cron pattern. Once a timing method is called, the schedule
 setTimeZone(timezone: Timezone): this
 withErrorHandler(handler: CatchCallbackFn): this
 withMaxRuns(runs: number): this
-withProtection(callback?: (job: ScheduledJob) => void): this
+withProtection(callback?: (job: ScheduledJob) => void): this  // skip a tick while the last run is still going (this process); callback hears each skip
 withName(name: string): this
-withContext(context: any): this
-withInterval(seconds: number): this
-between(startAt: string | Date, stopAt: string | Date): this
+withContext(context: any): this          // passed to the task on each run: the callback's argument, or the job's `context`
+withInterval(seconds: number): this      // at least this many seconds between runs; sooner ticks are skipped
+between(startAt: string | Date, stopAt: string | Date): this  // only run inside the window; stops for good once it closes
 withoutOverlapping(expiresAfterMinutes?: number): this
 onOneServer(): this
 runInBackground(): this
@@ -132,7 +132,7 @@ When `withoutOverlapping()` or `onOneServer()` is called:
 
 ### Background Execution
 
-When `runInBackground()` is called, the task is spawned as a detached child process via `node:child_process.spawn`. The child is `unref()`'d so it does not keep the parent alive.
+When `runInBackground()` is called, each run starts `buddy schedule:run-one <name> --in-process` as a detached child in the project directory. That process registers the app's schedule the way `schedule:run` does and runs the one task there, taking any `withoutOverlapping()` / `onOneServer()` lock itself. The child is `unref()`'d so it does not keep the parent alive, and a non-zero exit is logged under the task's name. The task needs a name (`schedule.job/action/command` have one; a callback needs `.withName()`), or registration fails.
 
 ## Helper Functions
 
@@ -351,7 +351,7 @@ export default {
 - The `Queue` class in `schedule.ts` is just an empty subclass of `Schedule` (`export class Queue extends Schedule {}`) -- it adds no functionality
 - `withoutOverlapping()` uses file-based locks in `storage/framework/locks/` -- this only prevents overlap within a single machine, not across a cluster
 - `onOneServer()` also uses file-based locks (same as `withoutOverlapping`), so it does not actually coordinate across multiple servers
-- `runInBackground()` spawns a detached child process with `spawn(process.execPath, ['-e', ...])` -- the task function is `.toString()`'d and eval'd, so closures over external variables will not work
+- `runInBackground()` runs the task by name in a `buddy schedule:run-one <name> --in-process` child, so the task must be registered under that name by the app's scheduler file, and an unnamed callback is refused
 - There are TWO scheduler systems: `@stacksjs/scheduler` (fluent API in `schedule.ts`) and the queue-level scheduler in `@stacksjs/queue` (`queue/src/scheduler.ts`). The former runs tasks in-process; the latter dispatches to the queue
 - `sendAt()` throws on invalid cron expressions (it delegates to `parse()` which throws)
 - `timeout()` returns `-1` (not `0` or `Infinity`) when there is no upcoming run

package/app/Actions/Auth/RefreshTokenAction.ts

@@ -20,10 +20,9 @@ export default new Action({
     })
 
     try {
-      const result = await refreshToken(refreshTokenValue, {
-        expiresInMinutes: 60, // 1 hour access token
-        refreshExpiresInDays: 30, // 30 day refresh token
-      })
+      // The lifetimes config/auth.ts sets (tokenExpiry, refreshTokenExpiry).
+      // Hard-coding an hour and 30 days here overrode them on every refresh.
+      const result = await refreshToken(refreshTokenValue)
 
       // Rotation invalidates the token the cookie was carrying, so a cookie
       // left untouched here would go stale at the exact moment the session was

package/app/Actions/Dashboard/Buddy/BuddyChatAction.ts

@@ -5,7 +5,7 @@ import { buddyState, createAIClient } from '@stacksjs/ai'
 import { config } from '@stacksjs/config'
 import { response } from '@stacksjs/router'
 import { dashboardOperationalError } from '../dashboard-response'
-import { buddySystemPrompt, isBuddyProviderConfigured, publicBuddyHistory, resolveBuddyProvider } from './buddy-chat'
+import { buddyProviderStatus, buddySystemPrompt, publicBuddyHistory } from './buddy-chat'
 
 export default new Action({
   name: 'BuddyChatAction',
@@ -21,12 +21,9 @@ export default new Action({
       return response.json({ message: 'Question must be 4,000 characters or fewer.' }, 422)
 
     const aiConfig = (config.ai || {}) as ConfiguredAIOptions
-    const provider = resolveBuddyProvider(aiConfig)
-    if (!isBuddyProviderConfigured(provider, aiConfig, process.env)) {
-      return response.json({
-        message: `${provider === 'openai' ? 'OPENAI_API_KEY' : 'ANTHROPIC_API_KEY'} is not configured.`,
-      }, 503)
-    }
+    const { provider, configured, problem } = buddyProviderStatus(aiConfig)
+    if (!provider || !configured)
+      return response.json({ message: problem }, 503)
 
     try {
       const history = publicBuddyHistory(buddyState.getState().conversationHistory, 20)

package/app/Actions/Dashboard/Buddy/BuddyChatStateAction.ts

@@ -2,7 +2,7 @@ import type { ConfiguredAIOptions } from '@stacksjs/ai'
 import { Action } from '@stacksjs/actions/runtime'
 import { buddyState } from '@stacksjs/ai'
 import { config } from '@stacksjs/config'
-import { publicBuddyHistory, isBuddyProviderConfigured, resolveBuddyProvider } from './buddy-chat'
+import { buddyProviderStatus, publicBuddyHistory } from './buddy-chat'
 
 export default new Action({
   name: 'BuddyChatStateAction',
@@ -12,12 +12,10 @@ export default new Action({
 
   async handle() {
     const aiConfig = (config.ai || {}) as ConfiguredAIOptions
-    const provider = resolveBuddyProvider(aiConfig)
     const state = buddyState.getState()
 
     return {
-      provider,
-      configured: isBuddyProviderConfigured(provider, aiConfig, process.env),
+      ...buddyProviderStatus(aiConfig),
       history: publicBuddyHistory(state.conversationHistory),
       repository: state.repo
         ? {

package/app/Actions/Dashboard/Buddy/buddy-chat.test.ts

@@ -1,17 +1,32 @@
 import { describe, expect, test } from 'bun:test'
-import { buddySystemPrompt, isBuddyProviderConfigured, publicBuddyHistory, resolveBuddyProvider } from './buddy-chat'
+import { buddyProviderStatus, buddySystemPrompt, publicBuddyHistory } from './buddy-chat'
 
 describe('dashboard Buddy chat', () => {
-  test('normalizes the configured provider', () => {
-    expect(resolveBuddyProvider({ default: 'anthropic.claude-sonnet' })).toBe('anthropic')
-    expect(resolveBuddyProvider({ default: 'ollama' })).toBe('ollama')
-    expect(resolveBuddyProvider({ default: 'gpt-5' })).toBe('openai')
+  test('resolves the provider the way createAIClient() does', () => {
+    expect(buddyProviderStatus({ default: 'claude-sonnet-5-5' }, { ANTHROPIC_API_KEY: 'k' }).provider).toBe('anthropic')
+    expect(buddyProviderStatus({ default: 'ollama' }, {}).provider).toBe('ollama')
+    expect(buddyProviderStatus({ default: 'gpt-5' }, { OPENAI_API_KEY: 'k' }).provider).toBe('openai')
+    expect(buddyProviderStatus({}, { OPENAI_API_KEY: 'k' }).provider).toBe('openai')
+    // A Bedrock id is Bedrock, not the first-party Anthropic API, and not
+    // OpenAI, which is where Buddy's own copy of this sent it.
+    expect(buddyProviderStatus({ default: 'global.anthropic.claude-sonnet-5-5' }, {}).provider).toBe('bedrock')
+    expect(buddyProviderStatus({ default: 'bedrock' }, {})).toEqual({ provider: 'bedrock', configured: true, problem: null, missingKey: null })
   })
 
   test('reports provider readiness without exposing keys', () => {
-    expect(isBuddyProviderConfigured('openai', {}, { OPENAI_API_KEY: 'configured' })).toBe(true)
-    expect(isBuddyProviderConfigured('anthropic', {}, {})).toBe(false)
-    expect(isBuddyProviderConfigured('ollama', {}, {})).toBe(true)
+    expect(buddyProviderStatus({ default: 'openai' }, { OPENAI_API_KEY: 'configured' }).configured).toBe(true)
+    expect(buddyProviderStatus({ default: 'anthropic' }, {}))
+      .toEqual({ provider: 'anthropic', configured: false, problem: 'ANTHROPIC_API_KEY is not configured.', missingKey: 'ANTHROPIC_API_KEY' })
+    expect(buddyProviderStatus({ default: 'ollama' }, {}).configured).toBe(true)
+    // A provider reached through a base URL needs no key.
+    expect(buddyProviderStatus({ default: 'openai', drivers: { openai: { baseUrl: 'http://localhost:1234/v1' } } }, {}).configured).toBe(true)
+  })
+
+  test('names an unsupported default instead of answering with OpenAI', () => {
+    const status = buddyProviderStatus({ default: 'mistral-large' }, { OPENAI_API_KEY: 'k' })
+    expect(status.provider).toBeNull()
+    expect(status.configured).toBe(false)
+    expect(status.problem).toContain('Unsupported configured AI driver: mistral-large')
   })
 
   test('only returns public text history', () => {