@stacksjs/defaults 0.75.109 → 0.75.111

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

@@ -70,7 +70,7 @@ route.group({ prefix: '/api/v1', middleware: ['auth', 'throttle'] }, () => {
 ```
 
 ### Handler Types
-- Function: `(req) => …` — return a `Response`, or any value `formatResult`
+- Function: `(req) => ...` - return a `Response`, or any value `formatResult`
   handles: an object/array becomes JSON, a string becomes text, `null` becomes
   204, a `ReadableStream` streams. `req.params` is narrowed to the path's own
   placeholders, so `req.params.slugTypo` is a compile error rather than
@@ -186,6 +186,34 @@ export default {
 } satisfies Record<string, string | RouteDefinition>
 ```
 
+The registry is optional; `appRouteRegistry()` falls back to the API file
+mounted at `/api`. App registrations precede default bundles and the first
+duplicate method/path wins. Default bundles are selected explicitly or through
+their feature gates; see `stacks-routes` for `STACKS_DEFAULT_ROUTES` and prefix
+rules. Do not hard-code an assumption that every built-in route is mounted.
+
+## Binding, signed access, and request lifecycle
+
+`defineRouteModelBinding(param, resolver)` resolves a raw path value for policy
+middleware. Explicit bindings take precedence over the optional fallback.
+Unclaimed parameters stay raw; a claimed missing model is different from an
+unclaimed parameter. Binding does not remove the need to validate a path key.
+
+`signedUrl`, `signUrl`, `verifySignedUrl`, and `verifySignedUrlMiddleware`
+support temporary signed access. Signing requires `APP_KEY` or the dedicated
+secret. Verify method/URL/expiry according to the helper contract; changing a
+signed URL is not equivalent to authorizing a row. Storage signatures are a
+separate provider/delivery contract.
+
+Native request context carries typed model/user data, query tracking, trace
+IDs, route params, and hooks. `safePathParam`/`sanitizePathParam` protect path
+segments, while numeric IDs need numeric validation as well. `stream` preserves
+backpressure; do not eagerly collect a stream merely to attach JSON metadata.
+
+Read `health`, `signed-url`, `route-model-binding`, `precognition`,
+`request-context`, `after-response`, and `stream-backpressure` tests before
+depending on the corresponding lifecycle behavior.
+
 ## Enhanced Request (Laravel-style)
 
 ### Input Methods
@@ -299,7 +327,10 @@ clearTrackedQueries()
 clearMiddlewareCache()
 ```
 
-## Default API Routes (routes/api.ts)
+## Default API route families
+
+These are examples of available bundles. The app's registry, selected default
+bundles, and feature gates decide the mounted surface; inspect `buddy route:list`.
 
 ### Auth
 - `POST /login`, `POST /register`, `POST /auth/refresh`, `POST /auth/token`

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

@@ -25,6 +25,18 @@ export default {
 } satisfies Record<string, string | RouteDefinition>
 ```
 
+`app/Routes.ts` is optional. Without a usable registry, `appRouteRegistry()`
+falls back to `{ api: 'api' }`. Keys supply the default prefix; `web` is
+root-mounted, and an explicit empty prefix mounts a route file at the root.
+Route files define paths relative to that prefix, so `/api` should not be
+repeated inside `routes/api.ts`.
+
+App route files load before framework bundles. Duplicate method/path
+registrations keep the first one, allowing an app route to override a default.
+Discovered packages can contribute route files and other resource roots;
+their registration does not automatically make components globally available.
+See `stacks-config` for package discovery.
+
 ## Creating a Route File
 
 ```typescript
@@ -50,7 +62,13 @@ route.group({ prefix: '/admin', middleware: ['auth'] }, () => {
 route.health()
 ```
 
-## Default API Routes (routes/api.ts)
+## Default route bundles
+
+Default bundles are selected by `STACKS_DEFAULT_ROUTES`, the route loader,
+and the relevant feature gates. The following endpoint families are discovery
+examples, not a guarantee they are mounted in every app. In particular,
+enabling auth models is separate from exposing the default authentication
+routes. Use `buddy route:list` to inspect this application's actual surface.
 
 ### Authentication
 - `POST /login` → LoginAction
@@ -97,9 +115,14 @@ route.get('/ping', (req) => Response.json({ pong: true }))
 - `buddy route:list` — list all registered routes
 
 ## Gotchas
-- Route files must be registered in `app/Routes.ts` to be loaded
+- Additional route files need registration; the optional manifest's fallback
+  already mounts `routes/api.ts` at `/api`.
 - String handlers (Actions/X) are dynamically imported at request time
 - Route order matters — first match wins
 - Use groups for shared middleware instead of repeating on each route
 - The `health()` helper registers `GET /health` automatically
 - For the router API (request helpers, middleware, responses), see the `stacks-router` skill
+
+Source: `core/router/src/route-loader.ts`, `appRouteRegistry`, and
+`app-route-registry`, `route-bundles-mounted`, `default-route-bundles`,
+`duplicate-route-registration`, and package-discovery tests.

package/ai/skills/stacks-scaffold-exercises/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ai/skills/stacks-scaffold-exercises/NOTICE.md

@@ -0,0 +1,10 @@
+# Source and license
+
+The upstream MIT notice is preserved in [LICENSE](LICENSE).
+
+## scaffold-exercises
+
+Source: [skills/misc/scaffold-exercises/SKILL.md](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/misc/scaffold-exercises/SKILL.md),
+revision `49dd158d1076134a641b33efb035946536778336`.
+
+Ported with Stacks skill names, canonical guidance, local-tracker fallback, TypeScript/Bun tooling, and conditional external actions.

package/ai/skills/stacks-scaffold-exercises/PLAYBOOK.md

@@ -0,0 +1,106 @@
+> Adapted playbook. Read [the Stacks rules](../stacks-flow/ENGINEERING.md) first. Commit, push, publish, and tracker mutations are conditional on the user's authorization.
+
+
+# Scaffold Exercises
+
+Create exercise directory structures that pass `./buddy lint`. Commit only when asked.
+
+## Directory naming
+
+- **Sections**: `XX-section-name/` inside `exercises/` (e.g., `01-retrieval-skill-building`)
+- **Exercises**: `XX.YY-exercise-name/` inside a section (e.g., `01.03-retrieval-with-bm25`)
+- Section number = `XX`, exercise number = `XX.YY`
+- Names are dash-case (lowercase, hyphens)
+
+## Exercise variants
+
+Each exercise needs at least one of these subfolders:
+
+- `problem/` - student workspace with TODOs
+- `solution/` - reference implementation
+- `explainer/` - conceptual material, no TODOs
+
+When stubbing, default to `explainer/` unless the plan specifies otherwise.
+
+## Required files
+
+Each subfolder (`problem/`, `solution/`, `explainer/`) needs a `readme.md` that:
+
+- Is **not empty** (must have real content, even a single title line works)
+- Has no broken links
+
+When stubbing, create a minimal readme with a title and a description:
+
+```md
+# Exercise Title
+
+Description here
+```
+
+If the subfolder has code, it also needs a `main.ts` (>1 line). But for stubs, a readme-only exercise is fine.
+
+## Workflow
+
+1. **Parse the plan** - extract section names, exercise names, and variant types
+2. **Create directories** - `mkdir -p` for each path
+3. **Create stub readmes** - one `readme.md` per variant folder with a title
+4. **Run lint** - `./buddy lint` to validate
+5. **Fix any errors** - iterate until lint passes
+
+## Exercise layout checks
+
+`./buddy lint` checks source style. Verify the following exercise layout rules
+with a TypeScript/Bun filesystem check or direct inspection. They are not
+built-in buddy lint rules:
+
+- Each exercise has subfolders (`problem/`, `solution/`, `explainer/`)
+- At least one of `problem/`, `explainer/`, or `explainer.1/` exists
+- `readme.md` exists and is non-empty in the primary subfolder
+- No `.gitkeep` files
+- No `speaker-notes.md` files
+- No broken links in readmes
+- No `pnpm run exercise` commands in readmes
+- `main.ts` required per subfolder unless it's readme-only
+
+## Moving/renaming exercises
+
+When renumbering or moving exercises:
+
+1. Use `git mv` (not `mv`) to rename directories - preserves git history
+2. Update the numeric prefix to maintain order
+3. Re-run lint after moves
+
+Example:
+
+```bash
+git mv exercises/01-retrieval/01.03-embeddings exercises/01-retrieval/01.04-embeddings
+```
+
+## Example: stubbing from a plan
+
+Given a plan like:
+
+```
+Section 05: Memory Skill Building
+- 05.01 Introduction to Memory
+- 05.02 Short-term Memory (explainer + problem + solution)
+- 05.03 Long-term Memory
+```
+
+Create:
+
+```bash
+mkdir -p exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer
+mkdir -p exercises/05-memory-skill-building/05.02-short-term-memory/{explainer,problem,solution}
+mkdir -p exercises/05-memory-skill-building/05.03-long-term-memory/explainer
+```
+
+Then create readme stubs:
+
+```
+exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer/readme.md -> "# Introduction to Memory"
+exercises/05-memory-skill-building/05.02-short-term-memory/explainer/readme.md -> "# Short-term Memory"
+exercises/05-memory-skill-building/05.02-short-term-memory/problem/readme.md -> "# Short-term Memory"
+exercises/05-memory-skill-building/05.02-short-term-memory/solution/readme.md -> "# Short-term Memory"
+exercises/05-memory-skill-building/05.03-long-term-memory/explainer/readme.md -> "# Long-term Memory"
+```

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

@@ -0,0 +1,23 @@
+---
+name: stacks-scaffold-exercises
+description: Use when scaffolding exercises, problem/solution variants, explainers, or a course section with TypeScript examples. Covers exercise layouts and Bun/pickier verification.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Scaffold Exercises
+
+Read [the Stacks adaptation rules](../stacks-flow/ENGINEERING.md), then
+[PLAYBOOK.md](PLAYBOOK.md). The playbook preserves this workflow's decision
+criteria; the Stacks rules govern APIs, tooling, tracking, and authorization.
+
+Credit: adapted from Matt Pocock's `scaffold-exercises` skill, MIT licensed.
+See [NOTICE.md](NOTICE.md) and [LICENSE](LICENSE).
+
+## Completion
+
+Produce the requested behavior or reviewable artifact and satisfy the
+playbook's completion criteria. Preserve existing decisions and user edits.
+Use the native Stacks skills for implementation and verification, and carry
+existing authorization through the workflow.

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

@@ -15,6 +15,12 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 ## CLI Make Commands
 
+Use `buddy list` and the selected command's `--help` for the current generator
+surface. Model, action, job, middleware, policy, resource, command and mail
+generators are available as well as the examples below. A new model belongs in
+`app/Models`; schema changes normally use `generate:migrations`, not a
+handwritten `make:migration`. Read `stacks-new-feature` for that tracer bullet.
+
 ```bash
 buddy make:component <name>     # Create a new STX component
 buddy make:function <name>      # Create a new function/composable
@@ -35,6 +41,11 @@ import { createProject, addComponent, addPage, addStore, addLayout } from '@stac
 
 ### Create Project
 
+This is the standalone STX generator contract. For a Stacks application prefer
+Buddy scaffolding and its existing Bun/better-dx/STX/Crosswind setup. The legacy
+tailwind option adds a separate Tailwind dependency and is not the Stacks
+styling workflow.
+
 ```typescript
 async function createProject(name: string, options?: CreateProjectOptions): Promise<ScaffoldResult>
 
@@ -137,7 +148,7 @@ interface ScaffoldResult {
 | Language files | `locales/` |
 | Layouts | `resources/layouts/` |
 | Pages | `resources/views/` |
-| Stores | `storage/framework/defaults/stores/` |
+| Stores | Check the selected STX generator's configured store directory |
 | Partials | `resources/partials/` |
 
 Browser-extension scaffolding also follows this resource layout: popup pages
@@ -148,15 +159,20 @@ container app alongside the web-extension starter.
 ## Default Templates
 
 Templates for generated code are in `storage/framework/defaults/`:
-- `defaults/components/` — component templates
-- `defaults/models/` — model templates
-- `defaults/app/Middleware/` — middleware templates
-- `defaults/layouts/` — layout templates
-- `defaults/views/` — view templates
+- `defaults/components/` - component templates
+- `defaults/models/` - model templates
+- `defaults/app/Middleware/` - middleware templates
+- `defaults/layouts/` - layout templates
+- `defaults/views/` - view templates
 
 ## Gotchas
-- **Always use make commands** — ensures consistent file structure and naming
-- **Templates are customizable** — modify files in `storage/framework/defaults/` to change scaffolding output
-- **Run pickier after generating** — `bunx --bun pickier . --fix` to format generated code
-- **`force` flag overwrites** — without it, existing files are not overwritten
-- **STX scaffolding vs buddy make** — `addComponent()` is the programmatic API, `buddy make:component` is the CLI equivalent
+- **Always use make commands** - ensures consistent file structure and naming
+- **Framework templates are reference defaults** - keep application-owned
+  overrides in application paths; editing a bundled framework template affects
+  the framework distribution and is not a durable per-app customization.
+- **Run pickier after generating** - `bunx --bun pickier . --fix` to format generated code
+- **`force` flag overwrites** - without it, existing files are not overwritten
+- **STX scaffolding and buddy make differ** - STX project scaffolding targets a
+  standalone STX layout, while Buddy generators target Stacks application paths.
+  Verify generated destinations/options rather than assuming one is a wrapper
+  around the other. Keep components/layouts/views under resources in a Stacks app.

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

@@ -26,17 +26,17 @@ The `@stacksjs/scheduler` package provides fluent, chainable task scheduling for
 scheduler/src/
 ├── index.ts       # Re-exports everything from run, schedule, types
 ├── schedule.ts    # Schedule class, Queue alias, sendAt(), timeout()
-├── run.ts         # runScheduler() — loads Jobs/*.ts + app/Scheduler.ts
+├── run.ts         # runScheduler() - loads Jobs/*.ts + app/Scheduler.ts
 └── types.ts       # Timezone union, ScheduledJob, UntimedSchedule, TimedSchedule, BaseSchedule
 
 cron/src/
-├── index.ts       # parse(), register(), remove() — delegates to Bun.cron or parseCron
-├── parser.ts      # parseCron() — native 5-field cron parser with POSIX OR logic
+├── index.ts       # parse(), register(), remove() - delegates to Bun.cron or parseCron
+├── parser.ts      # parseCron() - native 5-field cron parser with POSIX OR logic
 ├── types.ts       # CatchCallbackFn, ProtectCallbackFn, IntRange
 └── bun-cron.d.ts  # Bun.cron type declarations
 
 queue/src/
-└── scheduler.ts   # startScheduler(), stopScheduler(), getSchedulerStatus() — queue-level scheduler
+└── scheduler.ts   # startScheduler(), stopScheduler(), getSchedulerStatus() - queue-level scheduler
 ```
 
 ## Schedule Class (schedule.ts)
@@ -46,12 +46,12 @@ The `Schedule` class is the core scheduling API. The lowercase `schedule` export
 ```typescript
 import { schedule } from '@stacksjs/scheduler'
 
-// Static factory methods — each returns UntimedSchedule
+// Static factory methods - each returns UntimedSchedule
 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()
 
-// Graceful shutdown — stops all tracked jobs
+// Graceful shutdown - stops all tracked jobs
 schedule.gracefulShutdown(): Promise<void>
 ```
 
@@ -61,7 +61,8 @@ schedule.gracefulShutdown(): Promise<void>
 new Schedule(task: () => void)
 ```
 
-The constructor accepts a task function and auto-starts the schedule via `setTimeout(() => this.start(), 0)` after all chained methods have been called in the current tick.
+The constructor accepts a task function and auto-starts through queueMicrotask
+after the synchronous chain completes. Keep configuration in that same chain.
 
 ### Timing Methods (returns TimedSchedule)
 
@@ -116,19 +117,20 @@ The `Timezone` type is a string union of ~70 IANA timezone identifiers (e.g., `'
 
 - **Sub-minute** (`everySecond`): Uses `setInterval` with the configured `intervalMs`.
 - **Minute+**: Uses `parse()` from `@stacksjs/cron` to compute the next run time, then `setTimeout` to fire at the right moment. When the delay exceeds `2^31-1 ms` (~24.8 days), it chains shorter timeouts.
-- **Timezone-aware**: Converts "now" to the configured timezone via `toLocaleString()`, parses the cron pattern from that local time, then computes the real-world delay.
+- **Timezone-aware**: passes the configured IANA timezone to the cron parser through nextCronTime(). The returned Date is a UTC instant; local DST windows can still skip or repeat a scheduled local hour. Use idempotency when a task must have one effect in that window.
 - **maxRuns**: Tracks `runCount` and calls `stop()` when the limit is reached.
 - **Error handling**: If `options.catch` is set, errors are caught and passed to the handler instead of propagating.
 
+
 ### Overlap Prevention and Locking
 
-When `withoutOverlapping()` or `onOneServer()` is called:
-1. Lock files are created in `storage/framework/locks/{taskName}.lock`
-2. The lock directory is created automatically if missing
-3. Lock files use exclusive write (`flag: 'wx'`) for atomicity
-4. Stale locks expire after `overlapExpiresAfterMinutes` (default: 1440 = 24 hours)
-5. Lock age is checked via file `mtime`
-6. Locks are released in a `finally` block (or `.finally()` for async tasks)
+`withoutOverlapping()` uses a local exclusive file lock, with a stale-lock
+expiry. `onOneServer()` also requests a dedicated PostgreSQL/MySQL advisory
+lock through `scheduler-lock.ts`, alongside the local file lock. DB locks
+release when their connection disconnects. SQLite/Turso use only the host's file
+lock, and a DB-unavailable fallback warns rather than promising cluster
+coordination. Use the same task name on all participating hosts. Names are
+sanitized and hashed for lock paths.
 
 ### Background Execution
 
@@ -156,10 +158,10 @@ timeout(cronExpression: string | Date): number
 ```typescript
 import { parse } from '@stacksjs/cron'
 
-parse(expression: string, relativeDate?: Date | number): Date | null
+parse(expression: string, relativeDate?: Date | number, options?: { tz?: string }): Date | null
 ```
 
-- Uses `Bun.cron.parse()` when available (native Bun cron support), otherwise falls back to the built-in `parseCron()` implementation.
+- Uses `Bun.cron.parse()` when available and no timezone is supplied. With tz, or without native support, it uses the built-in parseCron implementation.
 - Returns the next matching UTC `Date`, or `null` if no match within ~4 years.
 - Throws on invalid expressions (wrong field count, out-of-range values).
 
@@ -217,11 +219,11 @@ Every.Year           // '0 0 1 1 *'
 
 The entry point for starting the scheduler process:
 
-1. Globs `app/Jobs/*.ts` for job files
-2. For each job with a `rate` property, maps the rate to a schedule method via `executeJobRate()` (switch on `Every.*` values)
-3. Job names are derived from `job.name` or the filename, then `snakeCase()`'d
-4. Imports and calls the default export from `app/Scheduler.ts`
-5. Returns `Ok<string>` on success
+1. Globs `app/Jobs/*.ts` and loads app/Scheduler.ts first.
+2. Preserves each job filename's case as its schedulable name.
+3. Skips a rate when the file or declared job name already has an explicit schedule.
+4. Schedules remaining rate strings through schedule.job(name).cron(rate), including supported sub-minute intervals.
+5. Logs individual import/rate failures and returns Ok on successful scheduler registration.
 
 ```typescript
 import { runScheduler } from '@stacksjs/scheduler'
@@ -345,12 +347,12 @@ export default {
 ```
 
 ## Gotchas
-- The `Schedule` constructor auto-starts via `setTimeout(0)` -- all chained methods must be called synchronously in the same tick, or the schedule starts with incomplete configuration
+- The Schedule constructor starts through a microtask after the synchronous chain; asynchronous configuration arrives too late
 - Default timezone is `'America/Los_Angeles'`, not UTC
 - `everySecond()` uses `setInterval`, not cron -- it sets `intervalMs = 1000` and bypasses the cron parser entirely
 - 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
+- `withoutOverlapping()` provides local file locking. `onOneServer()` adds PostgreSQL/MySQL advisory coordination where available
+- SQLite/Turso and DB-unavailable fallback cannot provide cluster-wide scheduler coordination; read scheduler-lock.ts and its warning
 - `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)
@@ -361,3 +363,28 @@ export default {
 - The cron parser uses POSIX OR logic when both day-of-month and day-of-week are specified (neither `*`) -- this means `0 0 15 * FRI` matches the 15th OR every Friday, not only Fridays that fall on the 15th
 - Lock files are written with `{ flag: 'wx' }` for atomic creation, but this is not NFS-safe
 - `parse()` returns `null` for impossible patterns (e.g., `0 0 30 2 *` -- Feb 30 never exists) rather than throwing
+
+
+## Additional native scheduling operations
+
+`cron(expression)` accepts five-field cron and deliberately restricted
+six-field forms: all-wildcard intervals in seconds dividing 60, or leading zero
+seconds with a five-field schedule. Unsupported specific-second forms throw.
+`dailyAt(time)`, `weekdays()` and `onQueue(name)` are native methods.
+`sendOutputTo(path)` and `appendOutputTo(path)` capture supported command
+output. `runMissed({ since, max? })` performs bounded catch-up; read its
+window/overlap behavior before using it for non-idempotent tasks.
+
+`schedule.notification(recipient, payload, channels?, options?)` schedules
+native notify fan-out and fails the task if any channel result failed.
+Use `.withName()` for a stable operational name. `Schedule.listJobs()`,
+`runNow(name, { inProcess? })`, `setEnabled/isEnabled/isScheduled` and
+`listLocks()` expose registered process state, not an inventory of every host.
+CLI: schedule:list/status/run-one/enable/disable. Read each command's help for
+persistence scope and flags; schedule:run starts a long-running scheduler.
+
+Source: `storage/framework/core/scheduler/src/schedule.ts` and
+`scheduler-lock.ts`, `core/buddy/src/commands/schedule.ts`. Tests:
+`cron-expression.test.ts`, `schedule-options.test.ts`,
+`scheduler-lock.test.ts`, `run-missed.test.ts`,
+`notification.test.ts` under `core/scheduler/tests/`.

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

@@ -28,10 +28,10 @@ import {
 } from '@stacksjs/search-engine'
 
 const search = useSearchEngine()       // default driver
-const algolia = useAlgolia()            // Algolia client
-const meili = useMeilisearch()          // Meilisearch client
-const openSearch = useOpensearch()       // OpenSearch driver
-const typesense = useTypesense()         // Typesense driver
+const algolia = await useAlgolia()            // Algolia client
+const meili = await useMeilisearch()          // Meilisearch client
+const openSearch = await useOpensearch()       // OpenSearch driver
+const typesense = await useTypesense()         // Typesense driver
 ```
 
 ## Document Operations
@@ -96,7 +96,7 @@ buddy search-engine:settings --model Product  # settings for specific model
 |---------|-------------|---------|-----------|------------|
 | Self-hosted | Yes | No | Yes | Yes |
 | Managed option | Yes | Yes | Yes | Yes |
-| Model lifecycle indexing | Yes | Yes | Yes | Driver must implement the full contract |
+| Model lifecycle indexing | Yes | Yes | Yes | Yes |
 
 ## config/search-engine.ts
 
@@ -107,7 +107,7 @@ buddy search-engine:settings --model Product  # settings for specific model
 Environment variables: `MEILISEARCH_HOST`, `MEILISEARCH_KEY`, `SEARCH_ENGINE_DRIVER`
 
 ## Gotchas
-- Default driver is `opensearch` — configure in config or env
+- Default driver is `opensearch` - configure in config or env
 - A selected driver must implement the complete `SearchEngineDriver` surface; never satisfy the type with an empty cast
 - `useSearch` trait determines which model fields are indexed
 - `displayable` controls which fields appear in search results
@@ -117,4 +117,25 @@ Environment variables: `MEILISEARCH_HOST`, `MEILISEARCH_KEY`, `SEARCH_ENGINE_DRI
 - Use `buddy search-engine:update --flush` for full re-index
 - Meilisearch requires a running Meilisearch server
 - Algolia requires API keys from your Algolia dashboard
-- Settings updates don't re-index — run `search-engine:update` after changes
+- Settings updates don't re-index - run `search-engine:update` after changes
+
+
+## Readiness and driver boundaries
+
+`useSearchEngine()` returns a synchronous deferred proxy whose async methods
+wait for configuration and driver loading. The provider factories return promises
+and require await. Use `await searchEngineReady()` before reading synchronous
+client/resetClient members. This avoids capturing framework default config before
+overridesReady settles.
+
+Every driver implements SearchEngineDriver, but setting/collection schemas differ.
+Typesense needs explicit schema handling for model field types and settings;
+read its driver/schema tests before translating Meilisearch filters unchanged.
+Lifecycle indexing errors are surfaced through the framework's search handling;
+an external index is not a transactional substitute for the model database.
+Read the source path used by your write before assuming bulk raw SQL auto-indexes.
+
+Source: `storage/framework/core/search-engine/src/index.ts`,
+`documents.ts` and `drivers/`. Retained tests:
+`early-proxy.test.ts`, `driver-contract.test.ts`,
+`document-errors.test.ts` and `typesense-schema.test.ts`.

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

@@ -27,7 +27,7 @@ security/src/
 ```typescript
 import { generateAppKey } from '@stacksjs/security'
 
-const key = generateAppKey()  // 32-character random string
+const key = generateAppKey()  // base64: followed by 32 random bytes encoded as base64
 // Run via CLI: buddy key:generate
 ```
 
@@ -74,9 +74,8 @@ const algo = detectAlgorithm(hash)  // 'bcrypt' | 'argon2' | 'argon2id' | ...
 ### Algorithm-Specific Functions
 ```typescript
 bcryptEncode(value, rounds?)     // bcrypt hash
-bcryptVerify(value, hash)        // bcrypt verify
 argon2Encode(value, options?)    // argon2 hash
-argon2Verify(value, hash)        // argon2 verify
+check(value, hash)               // verifies supported bcrypt/argon2 hashes
 base64Encode(value)               // base64
 ```
 
@@ -144,12 +143,29 @@ import { eraseSubject, exportSubjectData, pruneRetainedData } from '@stacksjs/or
   `log`, which writes to disk in production.
 
 ## Gotchas
-- Default hashing is bcrypt with 12 rounds — sufficient for most applications
-- `needsRehash()` compares current hash options against provided options — useful after config changes
-- APP_KEY is used for `encrypt()`/`decrypt()` — generate via `buddy key:generate`
+- Default hashing is bcrypt with 12 rounds - sufficient for most applications
+- `needsRehash()` compares current hash options against provided options - useful after config changes
+- APP_KEY is used for `encrypt()`/`decrypt()` - generate via `buddy key:generate`
 - APP_KEY format is colon-separated (validated during deployment)
 - Argon2 requires more memory/time but is more resistant to GPU attacks
 - Base64 is encoding, not hashing. Never use `base64Encode()` for credentials.
 - MD5 and base64 password verification are intentionally absent from the main security API.
 - The firewall config is used by cloud deployment for WAF rules
 - Rate limiting is per-minute per-IP (500 default)
+
+
+## Encryption and webhook contracts
+
+New `encrypt()` ciphertext uses the versioned AES-256-GCM envelope and
+PBKDF2-SHA-256 derivation in `core/security/src/crypt.ts`; decrypt retains
+legacy formats for upgrades. The base64: APP_KEY prefix is normalized by that
+implementation. Encryption/hashing/encoding are distinct APIs; use the exported
+webhook helpers from `core/security/src/webhook.ts` for signed callback
+validation rather than inventing a string comparison.
+
+Generated model API exposure and ownership live under `config/security.ts`
+api settings. Read `stacks-models`/`stacks-router` before opening generated
+endpoints; a cloud WAF setting does not implement model row authorization.
+Capability/config validation and credential recovery have separate tests and
+failure contracts; propagate their real errors rather than interpreting an
+awaited call as proof that a security state transition persisted.