@warlock.js/core 5.24.0 → 5.25.0

package/skills/test-service/SKILL.md

@@ -11,13 +11,13 @@ For unit tests, you import the thing under test and call it directly. No HTTP, n
 
 ⚠ **Corrected in 4.14.0 — `setupTest` is CALLED once per TEST FILE, not once per worker.** Every version of this skill through 4.13.0 said "per worker", the generated `src/test-setup.ts` carries a `Per-Worker Test Setup` comment saying the same thing, and **both were wrong.** Vitest runs `setupFiles` before **each test file**, and the setup module's registry is rebuilt every time — measured across all four `pool` × `isolate` combinations.
 
-⛔ **If your project was generated before 4.14.0, fix BOTH the comment and the call.** The comment is false, **and** the generated `setupTest({ connectors: true })` is now an *explicit* value that overrides your `src/config/tests.ts`. **Bare `setupTest()` is the correct call.**
+⛔ **If your project was generated before 4.14.0, fix BOTH the comment and the call.** The comment is false, **and** the generated `setupTest({ connectors: true })` is now an _explicit_ value that overrides your `src/config/tests.ts`. **Bare `setupTest()` is the correct call.**
 
 **The lifetime is FILE-SCOPED, on purpose.** Your setup file bootstraps the framework and its `afterAll(teardownTest)` closes it, once per test file. **One owner, one pairing — correct under every pool, every isolation setting, and watch mode.**
 
-⚠ **A worker-scoped lifetime is possible and is deliberately not shipped yet.** Lifecycle state now lives in the worker runtime, so leaving the framework running would let every file in a worker share one bootstrap. Two things block claiming it: under `pool: "threads"` we cannot observe whether Node reclaims a torn-down thread's sockets and pools, and **in watch mode Vitest reuses workers between reruns, so there is no recycle and no cleanup owner.** It gets taken when the real cost is measured and the integration is chosen, not inherited. See *Lifecycle and repeated calls* below.
+⚠ **A worker-scoped lifetime is possible and is deliberately not shipped yet.** Lifecycle state now lives in the worker runtime, so leaving the framework running would let every file in a worker share one bootstrap. Two things block claiming it: under `pool: "threads"` we cannot observe whether Node reclaims a torn-down thread's sockets and pools, and **in watch mode Vitest reuses workers between reruns, so there is no recycle and no cleanup owner.** It gets taken when the real cost is measured and the integration is chosen, not inherited. See _Lifecycle and repeated calls_ below.
 
-⚠ **Changed in 4.13.0 — the import is a subpath now.** `setupTest` used to be re-exported from the package root; it is not any more, because that put the test helpers into every application's production module graph. `import { setupTest } from "@warlock.js/core"` now fails with *"has no exported member"* — **add `/tests` to the specifier and nothing else changes.**
+⚠ **Changed in 4.13.0 — the import is a subpath now.** `setupTest` used to be re-exported from the package root; it is not any more, because that put the test helpers into every application's production module graph. `import { setupTest } from "@warlock.js/core"` now fails with _"has no exported member"_ — **add `/tests` to the specifier and nothing else changes.**
 
 ## The shape
 
@@ -34,7 +34,7 @@ describe("registerUserService", () => {
     });
 
     expect(user.get("email")).toBe("test@example.com");
-    expect(user.get("password")).not.toBe("secret");  // hashed by useHashedPassword()
+    expect(user.get("password")).not.toBe("secret"); // hashed by useHashedPassword()
 
     const found = await usersRepository.first({ email: "test@example.com" });
     expect(found).toBeDefined();
@@ -59,18 +59,18 @@ What it does (in order):
 3. Runs `bootstrap()` — env, app, prestart hooks.
 4. Initializes the `filesOrchestrator` (module/route/config discovery, no file watching).
 5. Loads all `src/config/*.ts` files.
-6. Resolves the connector selection — **an explicit parameter wins, then `tests.connectors` from config, then the `true` default.** See *Selecting connectors* below.
+6. Resolves the connector selection — **an explicit parameter wins, then `tests.connectors` from config, then the `true` default.** See _Selecting connectors_ below.
 7. Starts the chosen connectors — but **never `http`** when you pass a boolean. HTTP is the global-setup's job.
 
 The result: DB/cache/logger/storage connections your code can use. Models save, repositories query, services run. Same code as production, just isolated to the test process.
 
 ### The `connectors` parameter
 
-| Value                  | Boots                                                            | Use when                                              |
-| ---------------------- | ---------------------------------------------------------------- | ----------------------------------------------------- |
-| `true` *(default)*     | Every connector except `http` — via `startWithout(["http"])` (db, cache, logger, storage, and socket if configured) | Most service / repository / model tests.              |
-| `false`                | None                                                             | Pure logic tests with no DB / cache touches (parsers, validators, util functions). |
-| `["database", "cache"]` | Just those, in that order                                        | A test that only needs DB but not, say, the storage driver. |
+| Value                   | Boots                                                                                                               | Use when                                                                           |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `true` _(default)_      | Every connector except `http` — via `startWithout(["http"])` (db, cache, logger, storage, and socket if configured) | Most service / repository / model tests.                                           |
+| `false`                 | None                                                                                                                | Pure logic tests with no DB / cache touches (parsers, validators, util functions). |
+| `["database", "cache"]` | Just those, in that order                                                                                           | A test that only needs DB but not, say, the storage driver.                        |
 
 The default `true` is the sane choice. Reach for `false` when the unit you're testing genuinely doesn't talk to any framework subsystem — pulling up a DB connection **for every file** just to test a string parser is wasted setup time.
 
@@ -86,25 +86,25 @@ export default testsConfigurations;
 
 ⚠ **BREAKING in 4.14.0 — the precedence flipped.**
 
-| | Order |
-|---|---|
-| **4.13.0 and earlier** | `tests.connectors` config **>** `setupTest({ connectors })` parameter **>** `true` |
-| **4.14.0 onward** | **explicit `setupTest({ connectors })` parameter** **>** `tests.connectors` config **>** `true` |
+|                        | Order                                                                                           |
+| ---------------------- | ----------------------------------------------------------------------------------------------- |
+| **4.13.0 and earlier** | `tests.connectors` config **>** `setupTest({ connectors })` parameter **>** `true`              |
+| **4.14.0 onward**      | **explicit `setupTest({ connectors })` parameter** **>** `tests.connectors` config **>** `true` |
 
-**An explicit call-site value now beats project config.** If your project sets `tests.connectors` *and* some test file passes `connectors` explicitly, **that file will start a different connector set after upgrading.** Search for `setupTest({` across your tests before you upgrade — a call passing `connectors` was previously ignored and is now honoured.
+**An explicit call-site value now beats project config.** If your project sets `tests.connectors` _and_ some test file passes `connectors` explicitly, **that file will start a different connector set after upgrading.** Search for `setupTest({` across your tests before you upgrade — a call passing `connectors` was previously ignored and is now honoured.
 
 **"Explicit" means you supplied a non-`undefined` value.** Both of these fall through to config:
 
 ```ts
-await setupTest();                       // → tests.connectors, else true
-await setupTest({});                     // → tests.connectors, else true
+await setupTest(); // → tests.connectors, else true
+await setupTest({}); // → tests.connectors, else true
 await setupTest({ connectors: undefined }); // → tests.connectors, else true — NOT "start none"
 ```
 
 The `undefined` rule is deliberate: an optional variable that happens to be `undefined` must not silently erase your project config.
 
 ```ts
-await setupTest({ connectors: false });        // → none, even if config says otherwise
+await setupTest({ connectors: false }); // → none, even if config says otherwise
 await setupTest({ connectors: ["database"] }); // → exactly that, even if config differs
 ```
 
@@ -131,7 +131,7 @@ afterAll(teardownTest);
 ⛔ **Three things changed here in 4.14.0. If you generated this file earlier, replace all three — it is not a comment fix.**
 
 1. **`afterAll(teardownTest)` is new and mandatory.** Nothing else closes the framework your tests started. This is what makes the lifetime file-scoped and owned rather than left running.
-2. **The call is now bare `setupTest()`, not `setupTest({ connectors: true })`.** Under the flipped precedence, passing `true` is an *explicit* value and would override `tests.connectors` for **every file in the project.** Bare means "whatever this project configured, else the default".
+2. **The call is now bare `setupTest()`, not `setupTest({ connectors: true })`.** Under the flipped precedence, passing `true` is an _explicit_ value and would override `tests.connectors` for **every file in the project.** Bare means "whatever this project configured, else the default".
 3. **The comment used to say `Per-Worker Test Setup` / "Runs in EACH Vitest worker thread".** False — see the top of this skill.
 
 ```ts title="vite.config.ts"
@@ -142,8 +142,8 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
   plugins: [lowerStage3Decorators(), mongezVite()],
   test: {
-    globalSetup: "./src/test-global-setup.ts",  // ← HTTP server (see test-http skill)
-    setupFiles: ["./src/test-setup.ts"],         // ← runs setupTest before EACH test file
+    globalSetup: "./src/test-global-setup.ts", // ← HTTP server (see test-http skill)
+    setupFiles: ["./src/test-setup.ts"], // ← runs setupTest before EACH test file
     environment: "node",
     globals: false,
     include: ["src/app/**/*.test.ts"],
@@ -153,6 +153,17 @@ export default defineConfig({
 
 The `mongezVite()` plugin handles TypeScript path resolution and the framework's module shape. Without it, your imports break the moment vitest tries to load a Warlock module. `lowerStage3Decorators()` goes **first** — it lets decorated Cascade models (`@RegisterModel`, …) load under Vitest 4 / Vite 8; see [`@warlock.js/core/lower-stage3-decorators/SKILL.md`](@warlock.js/core/lower-stage3-decorators/SKILL.md).
 
+### Keep Vitest setup out of development
+
+`warlock dev` (and `warlock build`) load your app's `vite.config.ts`. Anything you put there for tests runs in development too. Guard vitest-only setup:
+
+```ts
+// vite.config.ts
+if (process.env.VITEST) {
+  Object.assign(process.env, testEnv); // test database, test keys...
+}
+```
+
 Tests live colocated with the module: `src/app/<module>/tests/*.test.ts`. The `include` pattern picks them up.
 
 ## Patterns
@@ -178,9 +189,9 @@ describe("createProductService", () => {
   it("rejects duplicate names", async () => {
     await Product.create({ name: "Existing", price: 10 });
 
-    await expect(
-      createProductService({ name: "Existing", price: 20 }),
-    ).rejects.toThrow(/already exists/i);
+    await expect(createProductService({ name: "Existing", price: 20 })).rejects.toThrow(
+      /already exists/i,
+    );
   });
 });
 ```
@@ -250,7 +261,7 @@ afterEach(async () => {
 
 Vitest runs the tests within one file sequentially, so an `afterEach` truncate gives each test a clean slate.
 
-⚠ **Cross-*file* isolation is not solved by this.** Separate workers get separate **connections**, not separate **rows** — two files pointed at the same database see each other's committed data regardless of pool or worker count. **Truncate what your file wrote; don't assume the worker boundary did it for you.** Real data isolation (DB-per-worker, transaction-per-test) is a separate piece of work and is not in this release.
+⚠ **Cross-_file_ isolation is not solved by this.** Separate workers get separate **connections**, not separate **rows** — two files pointed at the same database see each other's committed data regardless of pool or worker count. **Truncate what your file wrote; don't assume the worker boundary did it for you.** Real data isolation (DB-per-worker, transaction-per-test) is a separate piece of work and is not in this release.
 
 ### Skipping connectors for pure logic tests
 
@@ -260,7 +271,7 @@ import { setupTest } from "@warlock.js/core/tests";
 import { slugify } from "../utils/slugify";
 
 beforeAll(async () => {
-  await setupTest({ connectors: false });  // starts no connectors at all
+  await setupTest({ connectors: false }); // starts no connectors at all
 });
 
 describe("slugify", () => {
@@ -287,7 +298,7 @@ beforeAll(async () => {
 });
 
 afterAll(async () => {
-  await teardownTest();      // ← REQUIRED, see below
+  await teardownTest(); // ← REQUIRED, see below
 });
 ```
 
@@ -308,16 +319,16 @@ afterAll(async () => {
 
 `setupTest` / `teardownTest` are a pair. **The harness that calls one owns calling the other in the same context.**
 
-| Call | Behaviour |
-|---|---|
-| `setupTest(x)` while idle | bootstraps |
-| `setupTest(x)` while already ready with the **same** effective options | no-op |
-| `setupTest(y)` while ready or starting with **different** effective options | ⛔ **rejects**, naming active vs requested |
-| two concurrent `setupTest(x)` calls | share one startup |
-| `setupTest` after a failed setup | allowed — a failed setup unwinds and returns to idle |
-| `teardownTest()` while idle | no-op |
-| two concurrent `teardownTest()` calls | share one shutdown |
-| `setupTest(y)` after a **successful** teardown | allowed, different options fine |
+| Call                                                                        | Behaviour                                            |
+| --------------------------------------------------------------------------- | ---------------------------------------------------- |
+| `setupTest(x)` while idle                                                   | bootstraps                                           |
+| `setupTest(x)` while already ready with the **same** effective options      | no-op                                                |
+| `setupTest(y)` while ready or starting with **different** effective options | ⛔ **rejects**, naming active vs requested           |
+| two concurrent `setupTest(x)` calls                                         | share one startup                                    |
+| `setupTest` after a failed setup                                            | allowed — a failed setup unwinds and returns to idle |
+| `teardownTest()` while idle                                                 | no-op                                                |
+| two concurrent `teardownTest()` calls                                       | share one shutdown                                   |
+| `setupTest(y)` after a **successful** teardown                              | allowed, different options fine                      |
 
 **"Same options" is compared by meaning, not by literal value** — connector arrays are deduplicated and compared as sets, so `["cache", "database"]` and `["database", "cache", "cache"]` are the same selection.
 
@@ -332,7 +343,7 @@ afterAll(async () => {
 ```ts title="src/config/tests.ts"
 const testsConfigurations = {
   connectors: ["database", "logger"],
-  setupTimeout: 120000,   // milliseconds — this is the default
+  setupTimeout: 120000, // milliseconds — this is the default
 };
 
 export default testsConfigurations;
@@ -351,9 +362,9 @@ in `src/config/tests.ts` — milliseconds, default 120000.
 1. **It bounds the setup ATTEMPT, not teardown separately.** `teardownTest()` awaits the same attempt, so it inherits the bound — **one timer, not two.** A second teardown-side deadline was tried and rejected: it re-introduced the unbounded re-entry this whole guard exists to remove.
 2. **Expiry poisons the lifecycle**, it does not return to `idle`. The attempt may have started connectors nobody can now account for, so pretending the runtime is clean would be worse than refusing.
 3. **⛔ An invalid `setupTimeout` throws, naming the bad value.** Zero, negative and non-numeric all fail loudly rather than falling back to the default — a silent fallback would hide a typo behind a working suite.
-4. **The bound is measured from when the attempt started**, not from when config was read. `tests.setupTimeout` is only readable after `loadConfigFiles()`, which happens *inside* the window being bounded; re-arming naively would give you the default plus your configured value.
+4. **The bound is measured from when the attempt started**, not from when config was read. `tests.setupTimeout` is only readable after `loadConfigFiles()`, which happens _inside_ the window being bounded; re-arming naively would give you the default plus your configured value.
 
-⚠ **What is proven and what is not.** The nine guards above were each seen to fail under their own mutation. **But every spec injects its scheduler**, so the default *value* is tested while the production timer — and whether its `unref` actually releases the worker — is not. **And no spec observes a real hang**: the stuck attempt is a mock gate, not a socket that never returns. These prove what the lifecycle *decides*, not what a genuinely wedged connector does.
+⚠ **What is proven and what is not.** The nine guards above were each seen to fail under their own mutation. **But every spec injects its scheduler**, so the default _value_ is tested while the production timer — and whether its `unref` actually releases the worker — is not. **And no spec observes a real hang**: the stuck attempt is a mock gate, not a socket that never returns. These prove what the lifecycle _decides_, not what a genuinely wedged connector does.
 
 ### State is per worker runtime, not per module
 
@@ -383,3 +394,13 @@ In both cases the guard's scope matches the resource's scope, which is the point
 - [`test-http/SKILL.md`](../test-http/SKILL.md) — integration tests via the real HTTP server (`startHttpTestServer` + `testGet` / `testPost` / `expectJson`).
 - [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — where tests live in a module (`tests/*.test.ts`).
 - [`write-cli-command/SKILL.md`](../write-cli-command/SKILL.md) — `warlock add test` for the initial scaffold.
+
+## App modules and `importModule`
+
+Under Vitest, test files run through vite-node while Warlock's own native `import()` of app modules (config, routes, events) does not, so app classes such as `User` can exist twice in one worker and `instanceof` fails. Pass `importModule` to `setupTest` so Warlock loads app modules through the test's own module graph:
+
+```ts
+setupTest({ importModule: (file) => import(file) });
+```
+
+The generated `src/test-setup.ts` already does this. Without it, `setupTest()` under Vitest warns once.

package/skills/warlock-conventions/SKILL.md

@@ -13,6 +13,9 @@ This skill is the foundation. Every other warlock skill (`register-route`, `crea
 2. **Several files are auto-loaded — never `import` them.** The dev-server file watcher and the production builder categorize these as "special" and load them on boot.
    - `src/app/<module>/routes.ts` — route declarations
    - `src/app/<module>/main.ts` — per-module one-time setup
+   - `src/app/<module>/worker.ts` — worker-only setup (queue job definitions,
+     `scheduler.addJob(...)`, `scheduler.start()`); loaded only for the
+     `worker` role, and always loaded by `warlock dev`
    - `src/app/main.ts` — **project-level** one-time application setup (global hooks and other app initialization; connector instances belong in `warlock.config.ts > connectors`)
    - `src/app/<module>/events/*.ts(x)` — **any** `.ts(x)` file inside the `events/` folder (the `*.event.ts` suffix is convention, not a framework requirement)
    - `src/app/<module>/utils/locales.ts` — module translations via `groupedTranslations(...)`
@@ -33,7 +36,7 @@ This skill is the foundation. Every other warlock skill (`register-route`, `crea
    ```ts title="src/app/<module>/schema/create-<thing>.schema.ts"
    import { v, type Infer } from "@warlock.js/seal";
 
-   export const createThingSchema = v.object({ /* … */ });
+   export const createThingSchema = v.object({/* … */});
    export type CreateThingSchema = Infer<typeof createThingSchema>;
    ```
 
@@ -42,13 +45,17 @@ This skill is the foundation. Every other warlock skill (`register-route`, `crea
    import { type CreateThingSchema, createThingSchema } from "../schema/create-thing.schema";
    import { createThingService } from "../services/create-thing.service";
 
-   export const createThingController: GuardedRequestHandler<CreateThingSchema> = async ({ request, response }) => {
+   export const createThingController: GuardedRequestHandler<CreateThingSchema> = async ({
+     request,
+     response,
+   }) => {
      const thing = await createThingService(request.validated());
      return response.success({ thing });
    };
 
    createThingController.validation = { schema: createThingSchema };
    ```
+
 8. **Model getters beat `.get<T>("field")`.** Add a typed getter on the model rather than scattering `.get<string>("name")` casts across call sites.
 
 ## Module layout (the standard subfolders)
@@ -67,26 +74,27 @@ src/app/<module>/
   seeds/                    seed data for `warlock seed`
   routes.ts                 ← auto-loaded
   main.ts                   ← auto-loaded once, one-time setup
+  worker.ts                 ← auto-loaded for the worker role only
 ```
 
 Some older modules still have a `validation/` folder instead of `schema/` — historical drift. The framework treats them as plain folders either way; the generator emits to `schema/`.
 
 ## File naming (project-wide)
 
-| Suffix              | Role                                  | Example                             |
-| ------------------- | ------------------------------------- | ----------------------------------- |
-| `.controller.ts`    | HTTP handler                          | `create-product.controller.ts`      |
-| `.service.ts`       | Stateless business logic              | `create-product.service.ts`         |
-| `.usecase.ts`       | `useCase()` pipeline                  | `login.usecase.ts`                  |
-| `.model.ts`         | Cascade model class                   | `product.model.ts`                  |
-| `.repository.ts`    | `RepositoryManager` subclass          | `products.repository.ts`            |
-| `.resource.ts`      | `Resource` subclass                   | `product.resource.ts`               |
-| `.schema.ts`        | seal validation schema + its inferred `<Name>Schema` type from the same file | `create-product.schema.ts`          |
-| `.type.ts`          | data shape (TypeScript `type`)        | `cart-state.type.ts`                |
-| `.contract.ts`      | interface (TypeScript `interface`)    | `model.contract.ts`                 |
-| `.event.ts`         | event listener registrations (any `.ts(x)` inside `events/` works; the suffix is convention) | `audit.event.ts`                    |
-| `.migration.ts`     | Cascade migration                     | `2026_05_22_120000_product.migration.ts` |
-| `.seed.ts`          | seed data                             | `products.seed.ts`                  |
+| Suffix           | Role                                                                                         | Example                                  |
+| ---------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| `.controller.ts` | HTTP handler                                                                                 | `create-product.controller.ts`           |
+| `.service.ts`    | Stateless business logic                                                                     | `create-product.service.ts`              |
+| `.usecase.ts`    | `useCase()` pipeline                                                                         | `login.usecase.ts`                       |
+| `.model.ts`      | Cascade model class                                                                          | `product.model.ts`                       |
+| `.repository.ts` | `RepositoryManager` subclass                                                                 | `products.repository.ts`                 |
+| `.resource.ts`   | `Resource` subclass                                                                          | `product.resource.ts`                    |
+| `.schema.ts`     | seal validation schema + its inferred `<Name>Schema` type from the same file                 | `create-product.schema.ts`               |
+| `.type.ts`       | data shape (TypeScript `type`)                                                               | `cart-state.type.ts`                     |
+| `.contract.ts`   | interface (TypeScript `interface`)                                                           | `model.contract.ts`                      |
+| `.event.ts`      | event listener registrations (any `.ts(x)` inside `events/` works; the suffix is convention) | `audit.event.ts`                         |
+| `.migration.ts`  | Cascade migration                                                                            | `2026_05_22_120000_product.migration.ts` |
+| `.seed.ts`       | seed data                                                                                    | `products.seed.ts`                       |
 
 Filenames are kebab-case. Class names are PascalCase. Function names are camelCase. Table/collection names are snake_case (plural).
 
@@ -97,8 +105,8 @@ The scaffolded `tsconfig.json` defines:
 ```jsonc
 {
   "paths": {
-    "app/*": ["./src/app/*"]
-  }
+    "app/*": ["./src/app/*"],
+  },
 }
 ```
 

package/skills/write-cli-command/SKILL.md

@@ -43,16 +43,16 @@ Run it: `npx warlock users.promote --email=hasan@example.com` (or `npx warlock u
 
 ## `CLICommandOptions` — the factory input
 
-| Field         | Type                          | Required | Notes                                                                                          |
-| ------------- | ----------------------------- | -------- | ---------------------------------------------------------------------------------------------- |
-| `name`        | `string`                      | yes      | Dot notation OK (`db.seed`, `jwt.generate`). May include positional placeholders (`name <arg>`). |
-| `description` | `string`                      |          | Shown in `warlock --help` and `warlock <cmd> --help`.                                          |
-| `alias`       | `string`                      |          | Short name (`m` for `migrate`).                                                                |
-| `action`      | `(data) => void \| Promise`   | yes      | Runs after preloaders. `data` is `{ args, options }`.                                          |
-| `preAction`   | `(data) => void \| Promise`   |          | Runs **before** preloaders — banner, input validation.                                         |
-| `preload`     | `CLICommandPreload`           |          | What to load before `action` runs. See below.                                                  |
-| `persistent`  | `boolean`                     |          | `true` for long-running commands (dev server). Skips the auto-exit.                            |
-| `options`     | `CLICommandOption[]`          |          | Flag definitions. See below.                                                                   |
+| Field         | Type                        | Required | Notes                                                                                            |
+| ------------- | --------------------------- | -------- | ------------------------------------------------------------------------------------------------ |
+| `name`        | `string`                    | yes      | Dot notation OK (`db.seed`, `jwt.generate`). May include positional placeholders (`name <arg>`). |
+| `description` | `string`                    |          | Shown in `warlock --help` and `warlock <cmd> --help`.                                            |
+| `alias`       | `string`                    |          | Short name (`m` for `migrate`).                                                                  |
+| `action`      | `(data) => void \| Promise` | yes      | Runs after preloaders. `data` is `{ args, options }`.                                            |
+| `preAction`   | `(data) => void \| Promise` |          | Runs **before** preloaders — banner, input validation.                                           |
+| `preload`     | `CLICommandPreload`         |          | What to load before `action` runs. See below.                                                    |
+| `persistent`  | `boolean`                   |          | `true` for long-running commands (dev server). Skips the auto-exit.                              |
+| `options`     | `CLICommandOption[]`        |          | Flag definitions. See below.                                                                     |
 
 ## Options — flag shape
 
@@ -154,29 +154,29 @@ The framework ships a fixed set of commands you call but don't author. Knowing t
 
 ### Database + migrations
 
-| Command  | Flags / args                                    | Preloads                       |
-| -------- | ----------------------------------------------- | ------------------------------ |
-| `warlock migrate` | `--list` / `-l` (executed **and** pending), `--pending` (pending only, sets an exit code), `--fresh` / `-f` (drop tables first) | database, logger          |
-| `warlock seed` | `--name <pattern>` (run seeds matching the pattern) | full bootstrap (env, configs, app modules) |
-| `warlock create-database <name>` | bare positional `<name>`        | database                       |
-| `warlock drop.tables` | `--force, -f` (skip confirmation prompt) | database, logger          |
-| `warlock db.indexes` | builds DB indexes for every registered model    | database                  |
+| Command                          | Flags / args                                                                                                                    | Preloads                                   |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| `warlock migrate`                | `--list` / `-l` (executed **and** pending), `--pending` (pending only, sets an exit code), `--fresh` / `-f` (drop tables first) | database, logger                           |
+| `warlock seed`                   | `--name <pattern>` (run seeds matching the pattern)                                                                             | full bootstrap (env, configs, app modules) |
+| `warlock create-database <name>` | bare positional `<name>`                                                                                                        | database                                   |
+| `warlock drop.tables`            | `--force, -f` (skip confirmation prompt)                                                                                        | database, logger                           |
+| `warlock db.indexes`             | builds DB indexes for every registered model                                                                                    | database                                   |
 
 **Asking what will run next.** `warlock migrate --list` prints executed migrations and then the pending ones **in execution order**. Do not derive the pending set by differencing `--all` against `--list`: `--all` globs `src/app` only, while `--list` reads the migrations table, which also holds migrations that packages register through `database.migrations` (`@warlock.js/auth` contributes two). The difference under-counts pending, in the direction that says "safe to proceed".
 
 `--list` is a report and always exits `0`. `--pending` is a gate, and its exit code is its whole API:
 
-| Exit | Meaning |
-| ---- | ------- |
+| Exit | Meaning                   |
+| ---- | ------------------------- |
 | `0`  | computed, nothing pending |
-| `1`  | computed, N pending |
+| `1`  | computed, N pending       |
 | `2`  | **could not be computed** |
 
 ```bash
 warlock migrate --pending && ./deploy.sh
 ```
 
-`2` is separate from `1` on purpose — a script must be able to tell a backlog from an unknown, because one means *run them* and the other means *stop*. When the migration files cannot be loaded, both commands print `Pending: unavailable — <reason>` beneath a complete executed listing rather than reporting `0`.
+`2` is separate from `1` on purpose — a script must be able to tell a backlog from an unknown, because one means _run them_ and the other means _stop_. When the migration files cannot be loaded, both commands print `Pending: unavailable — <reason>` beneath a complete executed listing rather than reporting `0`.
 
 **If you are writing a command that reports on pending migrations:** register migrations first. `listPendingMigrations()` filters the runner's registry, so a caller that has not loaded anything gets `[]` — which reads as "nothing pending" and is not the same claim.
 
@@ -202,36 +202,41 @@ warlock generate                         (alias: g)      — interactive picker
 
 `warlock add <features...>` installs framework-adjacent features through a curated registry — bundles npm dependencies + scaffold files + tsconfig patches + package.json scripts in one call. Featured names (from `add-command.action.ts`):
 
-| Feature       | Installs                                                                                            |
-| ------------- | --------------------------------------------------------------------------------------------------- |
-| `react-email` | `react-email` + `@react-email/components` + `@react-email/render` + `@react-email/tailwind`; drops a `welcome-email.tsx` sample; patches `tsconfig.json` |
-| `web`         | Warlock Web + React stack; scaffolds the application page, localization, contact endpoint, and Web configuration                         |
-| `react`       | `react` + `react-dom` + types                                                                       |
+| Feature       | Installs                                                                                                                                                                               |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `react-email` | `react-email` + `@react-email/components` + `@react-email/render` + `@react-email/tailwind`; drops a `welcome-email.tsx` sample; patches `tsconfig.json`                               |
+| `web`         | Warlock Web + React stack; scaffolds the application page, localization, contact endpoint, and Web configuration                                                                       |
+| `react`       | `react` + `react-dom` + types                                                                                                                                                          |
 | `bull-board`  | `@bull-board/api` + `@bull-board/fastify`; writes a `dashboard` block to `src/config/queue.ts`. `requires: ["queue"]` — adds the `queue` feature first automatically when it's missing |
-| `image`       | `sharp` (for the `Image` class)                                                                     |
-| `mail`        | `nodemailer` + types                                                                                |
-| `ses`         | `@aws-sdk/client-sesv2`                                                                             |
-| `mongodb`     | `mongodb` driver                                                                                    |
-| `postgres`    | `pg`                                                                                                |
-| `mysql`       | `mysql2`                                                                                            |
-| `redis`       | `redis`                                                                                             |
-| `s3`          | `@aws-sdk/client-s3` + `@aws-sdk/lib-storage` + `@aws-sdk/s3-request-presigner`                     |
-| `scheduler`   | `@warlock.js/scheduler`                                                                             |
-| `swagger`     | `@warlock.js/swagger`                                                                               |
-| `postman`     | `@warlock.js/postman`                                                                               |
-| `herald`      | `@warlock.js/herald` + `amqplib` + types; ejects `src/config/communicator.ts`                       |
-| `test`        | `vitest` + `@mongez/vite` + coverage; drops `test-global-setup.ts` / `test-setup.ts` / `vite.config.ts` |
+| `image`       | `sharp` (for the `Image` class)                                                                                                                                                        |
+| `mail`        | `nodemailer` + types                                                                                                                                                                   |
+| `ses`         | `@aws-sdk/client-sesv2`                                                                                                                                                                |
+| `mongodb`     | `mongodb` driver                                                                                                                                                                       |
+| `postgres`    | `pg`                                                                                                                                                                                   |
+| `mysql`       | `mysql2`                                                                                                                                                                               |
+| `redis`       | `redis`                                                                                                                                                                                |
+| `s3`          | `@aws-sdk/client-s3` + `@aws-sdk/lib-storage` + `@aws-sdk/s3-request-presigner`                                                                                                        |
+| `scheduler`   | `@warlock.js/scheduler`                                                                                                                                                                |
+| `swagger`     | `@warlock.js/swagger`                                                                                                                                                                  |
+| `postman`     | `@warlock.js/postman`                                                                                                                                                                  |
+| `herald`      | `@warlock.js/herald` + `amqplib` + types; ejects `src/config/communicator.ts`                                                                                                          |
+| `test`        | `vitest` + `@mongez/vite` + coverage; drops `test-global-setup.ts` / `test-setup.ts` / `vite.config.ts`                                                                                |
+| `devtools`    | `@warlock.js/devtools` as a dev dependency; `warlock dev` auto-loads its development dashboard at `/__warlock`                                                                         |
 
 Run `warlock add --list` to see what's currently registered. Pass `--packageManager <yarn\|pnpm\|npm>` to override auto-detection (defaults to whichever lockfile is present).
 
+`warlock add devtools` never adds anything to `warlock.config.ts`. The package
+is loaded automatically by `warlock dev` when installed, and is omitted from a
+production install with dev dependencies excluded.
+
 The Web starter keeps the page's universal non-component setup in `src/web/index.register.ts`, while `src/web/index.page.tsx` re-exports `register`. Warlock still discovers and runs the hook from the page namespace in both SSR and the browser, but editing the page component remains inside React's Fast Refresh boundary. Do not move the `register()` declaration inline beside the component: React Refresh treats that non-component export as incompatible and reloads the page, losing component state.
 
 ### Misc
 
-| Command  | Purpose                                                     |
-| -------- | ----------------------------------------------------------- |
-| `warlock storage.put <localPath> [destination]` | Upload a local file to the default storage disk |
-| `warlock jwt.generate` | Generate a JWT secret in `.env` (from `@warlock.js/auth`)            |
+| Command                                         | Purpose                                                   |
+| ----------------------------------------------- | --------------------------------------------------------- |
+| `warlock storage.put <localPath> [destination]` | Upload a local file to the default storage disk           |
+| `warlock jwt.generate`                          | Generate a JWT secret in `.env` (from `@warlock.js/auth`) |
 
 ## Common patterns
 
@@ -293,7 +298,7 @@ export default command({
 });
 ```
 
-`preAction` runs *before* preloaders — cheap way to bail out without spinning up the database.
+`preAction` runs _before_ preloaders — cheap way to bail out without spinning up the database.
 
 ## Gotchas
 
@@ -301,7 +306,7 @@ export default command({
 - **Don't put logic at module top level.** The file gets imported during the commands scan (`warlock --warm-cache`). Anything outside `action` runs at scan time, possibly before any config or env is loaded.
 - **Required options block execution.** If `required: true` and the user omits the flag, the framework prints `Missing required options:` and exits `1` before `action` runs.
 - **Connectors are not free.** `connectors: true` boots the database, cache, storage, etc. For a print-version-and-exit command, leave `preload` undefined.
-- **`name` field with positional slots** (`name: "storage.put <localPath>"`) — the *registered* name is still `storage.put` (the first whitespace-separated token), so look up + alias work normally. Slots are only documentation/help-output.
+- **`name` field with positional slots** (`name: "storage.put <localPath>"`) — the _registered_ name is still `storage.put` (the first whitespace-separated token), so look up + alias work normally. Slots are only documentation/help-output.
 - **Aliases must be unique across plugin + framework + project.** The first registration wins; later collisions silently overwrite the map entry.
 
 ## See also