@warlock.js/queue 5.19.1 → 5.20.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to `@warlock.js/queue` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.20.0 - 2026-09-24
+
+### Changed
+
+- Added a package-level skill index and clearer discovery descriptions for grouped agent guidance.
+
 ## 5.19.0 - 2026-09-23
 
 ### Changed

package/llms-full.txt

@@ -6,192 +6,192 @@
 
 ## configure-queue  `@warlock.js/queue/configure-queue/SKILL.md`
 
----
-name: configure-queue
-description: "Configure the queue in @warlock.js/queue; use when you need to configure queue."
----
-
-# Configure the queue
-
-Redis is required. The config is declarative; the connector applies it.
-
-```ts title="src/config/queue.ts"
-import type { QueueConfig } from "@warlock.js/queue";
-
-const queueConfig: QueueConfig = {
-  connection: { host: "127.0.0.1", port: 6379 }, // any BullMQ connection option, or { url }
-  prefix: "my-app", // Redis key prefix, default "warlock"
-  defaultJobOptions: { attempts: 3, backoff: { type: "exponential", delay: 1000 } },
-  workers: {
-    enabled: true, // default true
-    concurrency: 5, // jobs in parallel per queue, default 1
-    shutdownTimeout: 30_000, // ms to wait for active jobs, default 30000
-  },
-};
-
-export default queueConfig;
-```
-
-```ts title="warlock.config.ts"
-import { defineConfig } from "@warlock.js/core";
-import { queueConnector } from "@warlock.js/queue";
-
-export default defineConfig({
-  connectors: [queueConnector()],
-});
-```
-
-## What the connector does
-
-- Starts in the **late** phase — after app code is imported — so every `defineJob` has registered. One worker per queue that has a job.
-- No `queue` config → logs a warning and does nothing.
-- On SIGINT/SIGTERM: workers stop taking jobs, active jobs get up to `shutdownTimeout` ms, then Redis connections close. A job still running after that is retried by another worker once its lock expires.
-
-## Dispatch-only process
-
-Set `workers.enabled: false`. `dispatch()` still works; nothing is processed in that process. Run the workers elsewhere with the same job definitions:
-
-```ts
-import { setQueueConfig, startWorkers, closeQueue } from "@warlock.js/queue";
-import "./jobs"; // modules that call defineJob
-
-setQueueConfig({ connection: { host: "127.0.0.1", port: 6379 } });
-await startWorkers();
-process.on("SIGTERM", () => closeQueue());
-```
-
-Every process must use the same `prefix`, or they will not see each other's jobs.
-
-## Dashboard
-
-`QueueConfig` also takes a `dashboard: { enabled, path, middleware }` block — see [`manage-failed-jobs`](../manage-failed-jobs/SKILL.md#dashboard-optional) for the `warlock add bull-board` setup and the production guard (`QueueDashboardUnguardedError`).
+---
+name: configure-queue
+description: 'Configure `@warlock.js/queue`: the declarative `src/config/queue.ts` (`QueueConfig` — `connection`, `prefix`, `defaultQueue`, `defaultJobOptions`, `workers: { enabled, concurrency, shutdownTimeout }`), registering `queueConnector()` in `warlock.config.ts > connectors`, running a dispatch-only process, and graceful shutdown. Programmatic `setQueueConfig` / `startWorkers` / `closeQueue` for scripts and tests. Triggers: `QueueConfig`, `queueConnector`, `setQueueConfig`, `startWorkers`, `closeQueue`, `workers.enabled`, `shutdownTimeout`; "configure the queue", "connect BullMQ to Redis", "disable workers in the web process", "graceful shutdown of jobs". Skip: writing jobs — `@warlock.js/queue/define-jobs/SKILL.md`.'
+---
+
+# Configure the queue
+
+Redis is required. The config is declarative; the connector applies it.
+
+```ts title="src/config/queue.ts"
+import type { QueueConfig } from "@warlock.js/queue";
+
+const queueConfig: QueueConfig = {
+  connection: { host: "127.0.0.1", port: 6379 }, // any BullMQ connection option, or { url }
+  prefix: "my-app", // Redis key prefix, default "warlock"
+  defaultJobOptions: { attempts: 3, backoff: { type: "exponential", delay: 1000 } },
+  workers: {
+    enabled: true, // default true
+    concurrency: 5, // jobs in parallel per queue, default 1
+    shutdownTimeout: 30_000, // ms to wait for active jobs, default 30000
+  },
+};
+
+export default queueConfig;
+```
+
+```ts title="warlock.config.ts"
+import { defineConfig } from "@warlock.js/core";
+import { queueConnector } from "@warlock.js/queue";
+
+export default defineConfig({
+  connectors: [queueConnector()],
+});
+```
+
+## What the connector does
+
+- Starts in the **late** phase — after app code is imported — so every `defineJob` has registered. One worker per queue that has a job.
+- No `queue` config → logs a warning and does nothing.
+- On SIGINT/SIGTERM: workers stop taking jobs, active jobs get up to `shutdownTimeout` ms, then Redis connections close. A job still running after that is retried by another worker once its lock expires.
+
+## Dispatch-only process
+
+Set `workers.enabled: false`. `dispatch()` still works; nothing is processed in that process. Run the workers elsewhere with the same job definitions:
+
+```ts
+import { setQueueConfig, startWorkers, closeQueue } from "@warlock.js/queue";
+import "./jobs"; // modules that call defineJob
+
+setQueueConfig({ connection: { host: "127.0.0.1", port: 6379 } });
+await startWorkers();
+process.on("SIGTERM", () => closeQueue());
+```
+
+Every process must use the same `prefix`, or they will not see each other's jobs.
+
+## Dashboard
+
+`QueueConfig` also takes a `dashboard: { enabled, path, middleware }` block — see [`manage-failed-jobs`](../manage-failed-jobs/SKILL.md#dashboard-optional) for the `warlock add bull-board` setup and the production guard (`QueueDashboardUnguardedError`).
 
 
 ## define-jobs  `@warlock.js/queue/define-jobs/SKILL.md`
 
----
-name: define-jobs
-description: "Define and dispatch jobs in @warlock.js/queue; use when you need to define jobs."
----
-
-# Define and dispatch jobs
-
-```ts title="src/app/invoices/jobs/send-invoice.job.ts"
-import { defineJob } from "@warlock.js/queue";
-
-export const sendInvoice = defineJob({
-  name: "invoices.send", // unique across the app
-  attempts: 5, // total tries, default 1
-  backoff: { type: "exponential", delay: 2000 }, // or a number = fixed ms
-  async handle(payload: { invoiceId: string }, ctx) {
-    await ctx.log(`attempt ${ctx.attempt} of ${ctx.maxAttempts}`);
-    await ctx.progress(50);
-    // throw to fail this attempt; it is retried until attempts run out
-    return { sent: true }; // stored as the job result
-  },
-});
-```
-
-The job module must be imported by the process that runs workers — in a Warlock app, anything under `src/app` that is loaded at boot.
-
-## Dispatch
-
-```ts
-const { id } = await sendInvoice.dispatch({ invoiceId: "42" });
-
-await sendInvoice.dispatch({ invoiceId: "43" }, {
-  delay: "10m", // ms number or "500ms" | "30s" | "10m" | "2h" | "1d"
-  priority: 1, // 1 runs first; larger numbers later
-  jobId: "invoice:43", // a second dispatch with a live id is ignored
-});
-```
-
-Option precedence: dispatch options > `defineJob` > `queue.defaultJobOptions`.
-
-## Read a job
-
-```ts
-const job = await sendInvoice.find(id);
-// { id, name, queue, state, payload, progress, attemptsMade, result, failedReason, createdAt, finishedAt }
-```
-
-## Rules
-
-- A job name with no handler in the worker process fails at once, without retries.
-- Payloads are stored as JSON: pass ids, not model instances.
-- Defining the same name again replaces the handler (this is what keeps dev reloads working), so keep names unique.
+---
+name: define-jobs
+description: 'Define and dispatch background jobs with `@warlock.js/queue`: `defineJob({ name, queue?, attempts?, backoff?, removeOnComplete?, removeOnFail?, handle(payload, ctx) })` returns a typed job; `job.dispatch(payload, { delay, priority, jobId, attempts, backoff })`; the handler context (`id`, `attempt`, `maxAttempts`, `progress()`, `log()`); reading a job with `job.find(id)`. Triggers: `defineJob`, `.dispatch(`, `ctx.progress`, `JobContext`, `DispatchOptions`, `backoff`, `attempts`, `priority`, `jobId`; "run this in the background", "retry with backoff", "delay a job", "job progress", "idempotent dispatch". Skip: config and workers — `@warlock.js/queue/configure-queue/SKILL.md`; failed jobs — `@warlock.js/queue/manage-failed-jobs/SKILL.md`.'
+---
+
+# Define and dispatch jobs
+
+```ts title="src/app/invoices/jobs/send-invoice.job.ts"
+import { defineJob } from "@warlock.js/queue";
+
+export const sendInvoice = defineJob({
+  name: "invoices.send", // unique across the app
+  attempts: 5, // total tries, default 1
+  backoff: { type: "exponential", delay: 2000 }, // or a number = fixed ms
+  async handle(payload: { invoiceId: string }, ctx) {
+    await ctx.log(`attempt ${ctx.attempt} of ${ctx.maxAttempts}`);
+    await ctx.progress(50);
+    // throw to fail this attempt; it is retried until attempts run out
+    return { sent: true }; // stored as the job result
+  },
+});
+```
+
+The job module must be imported by the process that runs workers — in a Warlock app, anything under `src/app` that is loaded at boot.
+
+## Dispatch
+
+```ts
+const { id } = await sendInvoice.dispatch({ invoiceId: "42" });
+
+await sendInvoice.dispatch({ invoiceId: "43" }, {
+  delay: "10m", // ms number or "500ms" | "30s" | "10m" | "2h" | "1d"
+  priority: 1, // 1 runs first; larger numbers later
+  jobId: "invoice:43", // a second dispatch with a live id is ignored
+});
+```
+
+Option precedence: dispatch options > `defineJob` > `queue.defaultJobOptions`.
+
+## Read a job
+
+```ts
+const job = await sendInvoice.find(id);
+// { id, name, queue, state, payload, progress, attemptsMade, result, failedReason, createdAt, finishedAt }
+```
+
+## Rules
+
+- A job name with no handler in the worker process fails at once, without retries.
+- Payloads are stored as JSON: pass ids, not model instances.
+- Defining the same name again replaces the handler (this is what keeps dev reloads working), so keep names unique.
 
 
 ## manage-failed-jobs  `@warlock.js/queue/manage-failed-jobs/SKILL.md`
 
----
-name: manage-failed-jobs
-description: "Failed jobs in @warlock.js/queue; use when you need to manage failed jobs."
----
-
-# Failed jobs
-
-A job is failed once it has used every attempt, or failed in a way that cannot be retried (for example, no handler for its name). Failed jobs are kept unless you set `removeOnFail`.
-
-```ts
-import { failedJobs, retryFailedJob } from "@warlock.js/queue";
-
-const failed = await failedJobs({ queue: "default", start: 0, end: 49 }); // newest first
-
-for (const job of failed) {
-  console.log(job.name, job.failedReason, job.attemptsMade);
-}
-
-await failed[0]?.retry(); // back to waiting
-await retryFailedJob("invoice:43"); // by id; throws FailedJobNotFoundError if not failed
-```
-
-## Dashboard (optional)
-
-```sh
-warlock add bull-board
-```
-
-This installs `@bull-board/api` + `@bull-board/fastify` and writes a `dashboard` block to `src/config/queue.ts`. It `requires: ["queue"]`, so it adds the `queue` feature first automatically when it isn't installed yet — no need to run `warlock add queue` yourself first:
-
-```ts title="src/config/queue.ts"
-import type { QueueConfig } from "@warlock.js/queue";
-import { middleware } from "@warlock.js/core";
-import { authMiddleware } from "@warlock.js/auth";
-
-const queueConfig: QueueConfig = {
-  connection: { host: "127.0.0.1", port: 6379 },
-  dashboard: {
-    enabled: true,
-    path: "/admin/queues", // default
-    middleware: [authMiddleware("admin")], // guards every dashboard route
-  },
-};
-
-export default queueConfig;
-```
-
-- The dashboard can retry and delete jobs, so it must be guarded. In production, an empty `middleware` list throws `QueueDashboardUnguardedError` at boot instead of mounting exposed. Outside production it logs a warning and mounts anyway.
-- `queueConnector()` mounts the dashboard at boot from this config — no extra wiring needed.
-
-### Advanced: manual `queueDashboard()`
-
-For mounting outside the config-driven path (a custom server, a non-standard boot sequence), call `queueDashboard` yourself:
-
-```ts
-import { getHttpServer } from "@warlock.js/core";
-import { queueDashboard } from "@warlock.js/queue";
-import { authMiddleware } from "@warlock.js/auth";
-
-await queueDashboard(getHttpServer(), {
-  basePath: "/admin/queues",
-  middleware: [authMiddleware("admin")],
-});
-```
-
-- Call it before the HTTP server starts listening.
-- Shows every queue that has a job, plus the default queue, unless you pass `queues`.
-- It has no authentication of its own — pass `middleware` yourself; this path does not enforce the production guard that the `dashboard` config does.
+---
+name: manage-failed-jobs
+description: 'Inspect and retry failed `@warlock.js/queue` jobs: `failedJobs({ queue, start, end })` returns `FailedJob[]` (`id`, `name`, `payload`, `attemptsMade`, `failedReason`, `stacktrace`, `failedAt`, `retry()`), `retryFailedJob(id, { queue })` (throws `FailedJobNotFoundError`), and the bull-board UI — `warlock add bull-board` (requires: ["queue"], so it installs queue first when missing) writes a `dashboard: { enabled, path, middleware }` block to `src/config/queue.ts`; a guard middleware is required in production or boot throws `QueueDashboardUnguardedError`. Manual `queueDashboard(server, { basePath, queues, middleware })` also available — needs `@bull-board/api` + `@bull-board/fastify`, loaded only on call, missing ones throw `QueueDashboardDependencyError`. Triggers: `failedJobs`, `retryFailedJob`, `queueDashboard`, `bull-board`, `dashboard.enabled`, `QueueDashboardUnguardedError`; "list failed jobs", "retry a failed job", "queue dashboard", "job admin UI". Skip: defining retries — `@warlock.js/queue/define-jobs/SKILL.md`.'
+---
+
+# Failed jobs
+
+A job is failed once it has used every attempt, or failed in a way that cannot be retried (for example, no handler for its name). Failed jobs are kept unless you set `removeOnFail`.
+
+```ts
+import { failedJobs, retryFailedJob } from "@warlock.js/queue";
+
+const failed = await failedJobs({ queue: "default", start: 0, end: 49 }); // newest first
+
+for (const job of failed) {
+  console.log(job.name, job.failedReason, job.attemptsMade);
+}
+
+await failed[0]?.retry(); // back to waiting
+await retryFailedJob("invoice:43"); // by id; throws FailedJobNotFoundError if not failed
+```
+
+## Dashboard (optional)
+
+```sh
+warlock add bull-board
+```
+
+This installs `@bull-board/api` + `@bull-board/fastify` and writes a `dashboard` block to `src/config/queue.ts`. It `requires: ["queue"]`, so it adds the `queue` feature first automatically when it isn't installed yet — no need to run `warlock add queue` yourself first:
+
+```ts title="src/config/queue.ts"
+import type { QueueConfig } from "@warlock.js/queue";
+import { middleware } from "@warlock.js/core";
+import { authMiddleware } from "@warlock.js/auth";
+
+const queueConfig: QueueConfig = {
+  connection: { host: "127.0.0.1", port: 6379 },
+  dashboard: {
+    enabled: true,
+    path: "/admin/queues", // default
+    middleware: [authMiddleware("admin")], // guards every dashboard route
+  },
+};
+
+export default queueConfig;
+```
+
+- The dashboard can retry and delete jobs, so it must be guarded. In production, an empty `middleware` list throws `QueueDashboardUnguardedError` at boot instead of mounting exposed. Outside production it logs a warning and mounts anyway.
+- `queueConnector()` mounts the dashboard at boot from this config — no extra wiring needed.
+
+### Advanced: manual `queueDashboard()`
+
+For mounting outside the config-driven path (a custom server, a non-standard boot sequence), call `queueDashboard` yourself:
+
+```ts
+import { getHttpServer } from "@warlock.js/core";
+import { queueDashboard } from "@warlock.js/queue";
+import { authMiddleware } from "@warlock.js/auth";
+
+await queueDashboard(getHttpServer(), {
+  basePath: "/admin/queues",
+  middleware: [authMiddleware("admin")],
+});
+```
+
+- Call it before the HTTP server starts listening.
+- Shows every queue that has a job, plus the default queue, unless you pass `queues`.
+- It has no authentication of its own — pass `middleware` yourself; this path does not enforce the production guard that the `dashboard` config does.
 
 
 ## overview  `@warlock.js/queue/overview/SKILL.md`
@@ -226,40 +226,40 @@ Durable background jobs. Jobs are stored in **Redis** (required), retried on fai
 
 ## queue-notifications  `@warlock.js/queue/queue-notifications/SKILL.md`
 
----
-name: queue-notifications
-description: "Queue notifications with BullMQ in @warlock.js/queue; use when you need to queue notifications."
----
-
-# Queue notifications with BullMQ
-
-```ts title="src/config/notifications.ts"
-import { type NotificationConfig, bullmqQueue, mailChannel } from "@warlock.js/notifications";
-
-const config: NotificationConfig = {
-  channels: { mail: mailChannel() },
-  queue: bullmqQueue({ attempts: 3, backoff: { type: "exponential", delay: 5000 } }),
-};
-
-export default config;
-```
-
-`bullmqQueue` ships inside `@warlock.js/notifications` itself and lazy-loads `@warlock.js/queue` (an OPTIONAL peer) the first time `.queue()` runs — install it with `warlock add queue` if it isn't there yet, otherwise the first `.queue()` throws `QueuePackageNotInstalledError`.
-
-Also configure the queue itself (`configure-queue`). No separate notifications worker is needed: the delivery is an ordinary job, run by the queue workers.
-
-```ts
-await orderShipped.queue(user, { order }); // enqueued, delivered by a worker
-await orderShipped.queue(user, { order }, { delay: "10m" }); // delivered in 10 minutes
-```
-
-## Behaviour
-
-- The job carries the rendered payload and resolved route; the worker looks the channel up by name in its own notifications config and calls `channel.send`.
-- `delay`: a number is seconds (notifications' convention); a string is a duration.
-- `channel.send` throws → retried per `attempts` / `backoff`, then listed by `failedJobs()`.
-- Channel not configured in the worker → fails at once, no retries.
-- Deliveries run under the job name `warlock.notifications.deliver`.
-
+---
+name: queue-notifications
+description: 'Send `@warlock.js/notifications` `.queue()` deliveries through BullMQ with `bullmqQueue({ queue?, attempts?, backoff? })` from `@warlock.js/notifications` — put it in the `queue` slot of `src/config/notifications.ts`; the queue workers deliver. Honours `SendOptions.delay` (number = seconds, or "10m"), retries a failing `channel.send`, and fails at once for a channel missing from the worker config. Triggers: `bullmqQueue`, `NotificationConfig.queue`, `QueuePackageNotInstalledError`; "queue notifications with BullMQ", "retry notification delivery", "delayed notification". Skip: the herald backend — `@warlock.js/notifications/queue-notifications/SKILL.md`.'
+---
+
+# Queue notifications with BullMQ
+
+```ts title="src/config/notifications.ts"
+import { type NotificationConfig, bullmqQueue, mailChannel } from "@warlock.js/notifications";
+
+const config: NotificationConfig = {
+  channels: { mail: mailChannel() },
+  queue: bullmqQueue({ attempts: 3, backoff: { type: "exponential", delay: 5000 } }),
+};
+
+export default config;
+```
+
+`bullmqQueue` ships inside `@warlock.js/notifications` itself and lazy-loads `@warlock.js/queue` (an OPTIONAL peer) the first time `.queue()` runs — install it with `warlock add queue` if it isn't there yet, otherwise the first `.queue()` throws `QueuePackageNotInstalledError`.
+
+Also configure the queue itself (`configure-queue`). No separate notifications worker is needed: the delivery is an ordinary job, run by the queue workers.
+
+```ts
+await orderShipped.queue(user, { order }); // enqueued, delivered by a worker
+await orderShipped.queue(user, { order }, { delay: "10m" }); // delivered in 10 minutes
+```
+
+## Behaviour
+
+- The job carries the rendered payload and resolved route; the worker looks the channel up by name in its own notifications config and calls `channel.send`.
+- `delay`: a number is seconds (notifications' convention); a string is a duration.
+- `channel.send` throws → retried per `attempts` / `backoff`, then listed by `failedJobs()`.
+- Channel not configured in the worker → fails at once, no retries.
+- Deliveries run under the job name `warlock.notifications.deliver`.
+
 
 

package/llms.txt

@@ -6,8 +6,8 @@
 
 ## Skills
 
-- [configure-queue](@warlock.js/queue/configure-queue/SKILL.md): Configure the queue in @warlock.js/queue; use when you need to configure queue.
-- [define-jobs](@warlock.js/queue/define-jobs/SKILL.md): Define and dispatch jobs in @warlock.js/queue; use when you need to define jobs.
-- [manage-failed-jobs](@warlock.js/queue/manage-failed-jobs/SKILL.md): Failed jobs in @warlock.js/queue; use when you need to manage failed jobs.
+- [configure-queue](@warlock.js/queue/configure-queue/SKILL.md): (no description)
+- [define-jobs](@warlock.js/queue/define-jobs/SKILL.md): (no description)
+- [manage-failed-jobs](@warlock.js/queue/manage-failed-jobs/SKILL.md): (no description)
 - [overview](@warlock.js/queue/overview/SKILL.md): @warlock.js/queue overview for orientation and choosing the focused skill for the task.
-- [queue-notifications](@warlock.js/queue/queue-notifications/SKILL.md): Queue notifications with BullMQ in @warlock.js/queue; use when you need to queue notifications.
+- [queue-notifications](@warlock.js/queue/queue-notifications/SKILL.md): (no description)

package/package.json

@@ -11,8 +11,8 @@
   "peerDependencies": {
     "@bull-board/api": "^9.0.0",
     "@bull-board/fastify": "^9.0.0",
-    "@warlock.js/core": "5.19.1",
-    "@warlock.js/logger": "5.19.1"
+    "@warlock.js/core": "5.20.0",
+    "@warlock.js/logger": "5.20.0"
   },
   "peerDependenciesMeta": {
     "@bull-board/api": {
@@ -37,7 +37,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.19.1",
+  "version": "5.20.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/configure-queue/SKILL.md

@@ -1,59 +1,59 @@
----
-name: configure-queue
-description: "Configure the queue in @warlock.js/queue; use when you need to configure queue."
----
-
-# Configure the queue
-
-Redis is required. The config is declarative; the connector applies it.
-
-```ts title="src/config/queue.ts"
-import type { QueueConfig } from "@warlock.js/queue";
-
-const queueConfig: QueueConfig = {
-  connection: { host: "127.0.0.1", port: 6379 }, // any BullMQ connection option, or { url }
-  prefix: "my-app", // Redis key prefix, default "warlock"
-  defaultJobOptions: { attempts: 3, backoff: { type: "exponential", delay: 1000 } },
-  workers: {
-    enabled: true, // default true
-    concurrency: 5, // jobs in parallel per queue, default 1
-    shutdownTimeout: 30_000, // ms to wait for active jobs, default 30000
-  },
-};
-
-export default queueConfig;
-```
-
-```ts title="warlock.config.ts"
-import { defineConfig } from "@warlock.js/core";
-import { queueConnector } from "@warlock.js/queue";
-
-export default defineConfig({
-  connectors: [queueConnector()],
-});
-```
-
-## What the connector does
-
-- Starts in the **late** phase — after app code is imported — so every `defineJob` has registered. One worker per queue that has a job.
-- No `queue` config → logs a warning and does nothing.
-- On SIGINT/SIGTERM: workers stop taking jobs, active jobs get up to `shutdownTimeout` ms, then Redis connections close. A job still running after that is retried by another worker once its lock expires.
-
-## Dispatch-only process
-
-Set `workers.enabled: false`. `dispatch()` still works; nothing is processed in that process. Run the workers elsewhere with the same job definitions:
-
-```ts
-import { setQueueConfig, startWorkers, closeQueue } from "@warlock.js/queue";
-import "./jobs"; // modules that call defineJob
-
-setQueueConfig({ connection: { host: "127.0.0.1", port: 6379 } });
-await startWorkers();
-process.on("SIGTERM", () => closeQueue());
-```
-
-Every process must use the same `prefix`, or they will not see each other's jobs.
-
-## Dashboard
-
-`QueueConfig` also takes a `dashboard: { enabled, path, middleware }` block — see [`manage-failed-jobs`](../manage-failed-jobs/SKILL.md#dashboard-optional) for the `warlock add bull-board` setup and the production guard (`QueueDashboardUnguardedError`).
+---
+name: configure-queue
+description: 'Configure `@warlock.js/queue`: the declarative `src/config/queue.ts` (`QueueConfig` — `connection`, `prefix`, `defaultQueue`, `defaultJobOptions`, `workers: { enabled, concurrency, shutdownTimeout }`), registering `queueConnector()` in `warlock.config.ts > connectors`, running a dispatch-only process, and graceful shutdown. Programmatic `setQueueConfig` / `startWorkers` / `closeQueue` for scripts and tests. Triggers: `QueueConfig`, `queueConnector`, `setQueueConfig`, `startWorkers`, `closeQueue`, `workers.enabled`, `shutdownTimeout`; "configure the queue", "connect BullMQ to Redis", "disable workers in the web process", "graceful shutdown of jobs". Skip: writing jobs — `@warlock.js/queue/define-jobs/SKILL.md`.'
+---
+
+# Configure the queue
+
+Redis is required. The config is declarative; the connector applies it.
+
+```ts title="src/config/queue.ts"
+import type { QueueConfig } from "@warlock.js/queue";
+
+const queueConfig: QueueConfig = {
+  connection: { host: "127.0.0.1", port: 6379 }, // any BullMQ connection option, or { url }
+  prefix: "my-app", // Redis key prefix, default "warlock"
+  defaultJobOptions: { attempts: 3, backoff: { type: "exponential", delay: 1000 } },
+  workers: {
+    enabled: true, // default true
+    concurrency: 5, // jobs in parallel per queue, default 1
+    shutdownTimeout: 30_000, // ms to wait for active jobs, default 30000
+  },
+};
+
+export default queueConfig;
+```
+
+```ts title="warlock.config.ts"
+import { defineConfig } from "@warlock.js/core";
+import { queueConnector } from "@warlock.js/queue";
+
+export default defineConfig({
+  connectors: [queueConnector()],
+});
+```
+
+## What the connector does
+
+- Starts in the **late** phase — after app code is imported — so every `defineJob` has registered. One worker per queue that has a job.
+- No `queue` config → logs a warning and does nothing.
+- On SIGINT/SIGTERM: workers stop taking jobs, active jobs get up to `shutdownTimeout` ms, then Redis connections close. A job still running after that is retried by another worker once its lock expires.
+
+## Dispatch-only process
+
+Set `workers.enabled: false`. `dispatch()` still works; nothing is processed in that process. Run the workers elsewhere with the same job definitions:
+
+```ts
+import { setQueueConfig, startWorkers, closeQueue } from "@warlock.js/queue";
+import "./jobs"; // modules that call defineJob
+
+setQueueConfig({ connection: { host: "127.0.0.1", port: 6379 } });
+await startWorkers();
+process.on("SIGTERM", () => closeQueue());
+```
+
+Every process must use the same `prefix`, or they will not see each other's jobs.
+
+## Dashboard
+
+`QueueConfig` also takes a `dashboard: { enabled, path, middleware }` block — see [`manage-failed-jobs`](../manage-failed-jobs/SKILL.md#dashboard-optional) for the `warlock add bull-board` setup and the production guard (`QueueDashboardUnguardedError`).

package/skills/define-jobs/SKILL.md

@@ -1,51 +1,51 @@
----
-name: define-jobs
-description: "Define and dispatch jobs in @warlock.js/queue; use when you need to define jobs."
----
-
-# Define and dispatch jobs
-
-```ts title="src/app/invoices/jobs/send-invoice.job.ts"
-import { defineJob } from "@warlock.js/queue";
-
-export const sendInvoice = defineJob({
-  name: "invoices.send", // unique across the app
-  attempts: 5, // total tries, default 1
-  backoff: { type: "exponential", delay: 2000 }, // or a number = fixed ms
-  async handle(payload: { invoiceId: string }, ctx) {
-    await ctx.log(`attempt ${ctx.attempt} of ${ctx.maxAttempts}`);
-    await ctx.progress(50);
-    // throw to fail this attempt; it is retried until attempts run out
-    return { sent: true }; // stored as the job result
-  },
-});
-```
-
-The job module must be imported by the process that runs workers — in a Warlock app, anything under `src/app` that is loaded at boot.
-
-## Dispatch
-
-```ts
-const { id } = await sendInvoice.dispatch({ invoiceId: "42" });
-
-await sendInvoice.dispatch({ invoiceId: "43" }, {
-  delay: "10m", // ms number or "500ms" | "30s" | "10m" | "2h" | "1d"
-  priority: 1, // 1 runs first; larger numbers later
-  jobId: "invoice:43", // a second dispatch with a live id is ignored
-});
-```
-
-Option precedence: dispatch options > `defineJob` > `queue.defaultJobOptions`.
-
-## Read a job
-
-```ts
-const job = await sendInvoice.find(id);
-// { id, name, queue, state, payload, progress, attemptsMade, result, failedReason, createdAt, finishedAt }
-```
-
-## Rules
-
-- A job name with no handler in the worker process fails at once, without retries.
-- Payloads are stored as JSON: pass ids, not model instances.
-- Defining the same name again replaces the handler (this is what keeps dev reloads working), so keep names unique.
+---
+name: define-jobs
+description: 'Define and dispatch background jobs with `@warlock.js/queue`: `defineJob({ name, queue?, attempts?, backoff?, removeOnComplete?, removeOnFail?, handle(payload, ctx) })` returns a typed job; `job.dispatch(payload, { delay, priority, jobId, attempts, backoff })`; the handler context (`id`, `attempt`, `maxAttempts`, `progress()`, `log()`); reading a job with `job.find(id)`. Triggers: `defineJob`, `.dispatch(`, `ctx.progress`, `JobContext`, `DispatchOptions`, `backoff`, `attempts`, `priority`, `jobId`; "run this in the background", "retry with backoff", "delay a job", "job progress", "idempotent dispatch". Skip: config and workers — `@warlock.js/queue/configure-queue/SKILL.md`; failed jobs — `@warlock.js/queue/manage-failed-jobs/SKILL.md`.'
+---
+
+# Define and dispatch jobs
+
+```ts title="src/app/invoices/jobs/send-invoice.job.ts"
+import { defineJob } from "@warlock.js/queue";
+
+export const sendInvoice = defineJob({
+  name: "invoices.send", // unique across the app
+  attempts: 5, // total tries, default 1
+  backoff: { type: "exponential", delay: 2000 }, // or a number = fixed ms
+  async handle(payload: { invoiceId: string }, ctx) {
+    await ctx.log(`attempt ${ctx.attempt} of ${ctx.maxAttempts}`);
+    await ctx.progress(50);
+    // throw to fail this attempt; it is retried until attempts run out
+    return { sent: true }; // stored as the job result
+  },
+});
+```
+
+The job module must be imported by the process that runs workers — in a Warlock app, anything under `src/app` that is loaded at boot.
+
+## Dispatch
+
+```ts
+const { id } = await sendInvoice.dispatch({ invoiceId: "42" });
+
+await sendInvoice.dispatch({ invoiceId: "43" }, {
+  delay: "10m", // ms number or "500ms" | "30s" | "10m" | "2h" | "1d"
+  priority: 1, // 1 runs first; larger numbers later
+  jobId: "invoice:43", // a second dispatch with a live id is ignored
+});
+```
+
+Option precedence: dispatch options > `defineJob` > `queue.defaultJobOptions`.
+
+## Read a job
+
+```ts
+const job = await sendInvoice.find(id);
+// { id, name, queue, state, payload, progress, attemptsMade, result, failedReason, createdAt, finishedAt }
+```
+
+## Rules
+
+- A job name with no handler in the worker process fails at once, without retries.
+- Payloads are stored as JSON: pass ids, not model instances.
+- Defining the same name again replaces the handler (this is what keeps dev reloads working), so keep names unique.

package/skills/index.md

@@ -0,0 +1,21 @@
+---
+description: "Durable background jobs on BullMQ + Redis: retries, delays, priorities, workers, failed-job recovery. Exports `defineJob`, `queueConnector`, `startWorkers`, `closeQueue`, `getQueue`, `failedJobs`, `retryFailedJob`, `mountQueueDashboard`, `QueueConfig`, `QueueJob`. Use for: \"run this in the background\", \"retry a failed job\", \"delay a job\", \"survive restarts\", \"job dashboard\". Not this package: cron or recurring schedules → @warlock.js/scheduler; broker pub/sub messaging → @warlock.js/herald; core `Queue` is an in-memory batcher."
+---
+# @warlock.js/queue
+
+Jobs are stored in Redis (required; not bundled), retried on failure, and run by workers, in the app process by default. `defineJob({ name, handle })` registers a handler and returns a typed job; `job.dispatch(payload, options)` enqueues it. Any process with the same definition and a worker can run it. Server-only.
+
+## The 80% path
+1. Orient with `overview.md`.
+2. Configure `src/config/queue.ts` and register `queueConnector()`: `configure-queue.md`.
+3. Define and dispatch jobs (attempts, backoff, delay, priority, progress): `define-jobs.md`.
+4. Inspect and recover failures, optionally the bull-board dashboard: `manage-failed-jobs.md`.
+5. Back `@warlock.js/notifications` `.queue()` with BullMQ: `queue-notifications.md`.
+
+## Conventions and pitfalls
+- Job names are the routing key; a job with no matching `defineJob` in the worker process cannot run.
+- Handlers must be idempotent: retries re-run them.
+- Shutdown lets active jobs finish up to `workers.shutdownTimeout`, then closes connections.
+- Guard the dashboard with middleware; an unguarded one is refused on purpose.
+- Core `Queue` is an in-memory batcher, lost on exit; use this package when work must survive.
+- Do not value-import from client code.

package/skills/manage-failed-jobs/SKILL.md

@@ -1,68 +1,68 @@
----
-name: manage-failed-jobs
-description: "Failed jobs in @warlock.js/queue; use when you need to manage failed jobs."
----
-
-# Failed jobs
-
-A job is failed once it has used every attempt, or failed in a way that cannot be retried (for example, no handler for its name). Failed jobs are kept unless you set `removeOnFail`.
-
-```ts
-import { failedJobs, retryFailedJob } from "@warlock.js/queue";
-
-const failed = await failedJobs({ queue: "default", start: 0, end: 49 }); // newest first
-
-for (const job of failed) {
-  console.log(job.name, job.failedReason, job.attemptsMade);
-}
-
-await failed[0]?.retry(); // back to waiting
-await retryFailedJob("invoice:43"); // by id; throws FailedJobNotFoundError if not failed
-```
-
-## Dashboard (optional)
-
-```sh
-warlock add bull-board
-```
-
-This installs `@bull-board/api` + `@bull-board/fastify` and writes a `dashboard` block to `src/config/queue.ts`. It `requires: ["queue"]`, so it adds the `queue` feature first automatically when it isn't installed yet — no need to run `warlock add queue` yourself first:
-
-```ts title="src/config/queue.ts"
-import type { QueueConfig } from "@warlock.js/queue";
-import { middleware } from "@warlock.js/core";
-import { authMiddleware } from "@warlock.js/auth";
-
-const queueConfig: QueueConfig = {
-  connection: { host: "127.0.0.1", port: 6379 },
-  dashboard: {
-    enabled: true,
-    path: "/admin/queues", // default
-    middleware: [authMiddleware("admin")], // guards every dashboard route
-  },
-};
-
-export default queueConfig;
-```
-
-- The dashboard can retry and delete jobs, so it must be guarded. In production, an empty `middleware` list throws `QueueDashboardUnguardedError` at boot instead of mounting exposed. Outside production it logs a warning and mounts anyway.
-- `queueConnector()` mounts the dashboard at boot from this config — no extra wiring needed.
-
-### Advanced: manual `queueDashboard()`
-
-For mounting outside the config-driven path (a custom server, a non-standard boot sequence), call `queueDashboard` yourself:
-
-```ts
-import { getHttpServer } from "@warlock.js/core";
-import { queueDashboard } from "@warlock.js/queue";
-import { authMiddleware } from "@warlock.js/auth";
-
-await queueDashboard(getHttpServer(), {
-  basePath: "/admin/queues",
-  middleware: [authMiddleware("admin")],
-});
-```
-
-- Call it before the HTTP server starts listening.
-- Shows every queue that has a job, plus the default queue, unless you pass `queues`.
-- It has no authentication of its own — pass `middleware` yourself; this path does not enforce the production guard that the `dashboard` config does.
+---
+name: manage-failed-jobs
+description: 'Inspect and retry failed `@warlock.js/queue` jobs: `failedJobs({ queue, start, end })` returns `FailedJob[]` (`id`, `name`, `payload`, `attemptsMade`, `failedReason`, `stacktrace`, `failedAt`, `retry()`), `retryFailedJob(id, { queue })` (throws `FailedJobNotFoundError`), and the bull-board UI — `warlock add bull-board` (requires: ["queue"], so it installs queue first when missing) writes a `dashboard: { enabled, path, middleware }` block to `src/config/queue.ts`; a guard middleware is required in production or boot throws `QueueDashboardUnguardedError`. Manual `queueDashboard(server, { basePath, queues, middleware })` also available — needs `@bull-board/api` + `@bull-board/fastify`, loaded only on call, missing ones throw `QueueDashboardDependencyError`. Triggers: `failedJobs`, `retryFailedJob`, `queueDashboard`, `bull-board`, `dashboard.enabled`, `QueueDashboardUnguardedError`; "list failed jobs", "retry a failed job", "queue dashboard", "job admin UI". Skip: defining retries — `@warlock.js/queue/define-jobs/SKILL.md`.'
+---
+
+# Failed jobs
+
+A job is failed once it has used every attempt, or failed in a way that cannot be retried (for example, no handler for its name). Failed jobs are kept unless you set `removeOnFail`.
+
+```ts
+import { failedJobs, retryFailedJob } from "@warlock.js/queue";
+
+const failed = await failedJobs({ queue: "default", start: 0, end: 49 }); // newest first
+
+for (const job of failed) {
+  console.log(job.name, job.failedReason, job.attemptsMade);
+}
+
+await failed[0]?.retry(); // back to waiting
+await retryFailedJob("invoice:43"); // by id; throws FailedJobNotFoundError if not failed
+```
+
+## Dashboard (optional)
+
+```sh
+warlock add bull-board
+```
+
+This installs `@bull-board/api` + `@bull-board/fastify` and writes a `dashboard` block to `src/config/queue.ts`. It `requires: ["queue"]`, so it adds the `queue` feature first automatically when it isn't installed yet — no need to run `warlock add queue` yourself first:
+
+```ts title="src/config/queue.ts"
+import type { QueueConfig } from "@warlock.js/queue";
+import { middleware } from "@warlock.js/core";
+import { authMiddleware } from "@warlock.js/auth";
+
+const queueConfig: QueueConfig = {
+  connection: { host: "127.0.0.1", port: 6379 },
+  dashboard: {
+    enabled: true,
+    path: "/admin/queues", // default
+    middleware: [authMiddleware("admin")], // guards every dashboard route
+  },
+};
+
+export default queueConfig;
+```
+
+- The dashboard can retry and delete jobs, so it must be guarded. In production, an empty `middleware` list throws `QueueDashboardUnguardedError` at boot instead of mounting exposed. Outside production it logs a warning and mounts anyway.
+- `queueConnector()` mounts the dashboard at boot from this config — no extra wiring needed.
+
+### Advanced: manual `queueDashboard()`
+
+For mounting outside the config-driven path (a custom server, a non-standard boot sequence), call `queueDashboard` yourself:
+
+```ts
+import { getHttpServer } from "@warlock.js/core";
+import { queueDashboard } from "@warlock.js/queue";
+import { authMiddleware } from "@warlock.js/auth";
+
+await queueDashboard(getHttpServer(), {
+  basePath: "/admin/queues",
+  middleware: [authMiddleware("admin")],
+});
+```
+
+- Call it before the HTTP server starts listening.
+- Shows every queue that has a job, plus the default queue, unless you pass `queues`.
+- It has no authentication of its own — pass `middleware` yourself; this path does not enforce the production guard that the `dashboard` config does.

package/skills/queue-notifications/SKILL.md

@@ -1,35 +1,35 @@
----
-name: queue-notifications
-description: "Queue notifications with BullMQ in @warlock.js/queue; use when you need to queue notifications."
----
-
-# Queue notifications with BullMQ
-
-```ts title="src/config/notifications.ts"
-import { type NotificationConfig, bullmqQueue, mailChannel } from "@warlock.js/notifications";
-
-const config: NotificationConfig = {
-  channels: { mail: mailChannel() },
-  queue: bullmqQueue({ attempts: 3, backoff: { type: "exponential", delay: 5000 } }),
-};
-
-export default config;
-```
-
-`bullmqQueue` ships inside `@warlock.js/notifications` itself and lazy-loads `@warlock.js/queue` (an OPTIONAL peer) the first time `.queue()` runs — install it with `warlock add queue` if it isn't there yet, otherwise the first `.queue()` throws `QueuePackageNotInstalledError`.
-
-Also configure the queue itself (`configure-queue`). No separate notifications worker is needed: the delivery is an ordinary job, run by the queue workers.
-
-```ts
-await orderShipped.queue(user, { order }); // enqueued, delivered by a worker
-await orderShipped.queue(user, { order }, { delay: "10m" }); // delivered in 10 minutes
-```
-
-## Behaviour
-
-- The job carries the rendered payload and resolved route; the worker looks the channel up by name in its own notifications config and calls `channel.send`.
-- `delay`: a number is seconds (notifications' convention); a string is a duration.
-- `channel.send` throws → retried per `attempts` / `backoff`, then listed by `failedJobs()`.
-- Channel not configured in the worker → fails at once, no retries.
-- Deliveries run under the job name `warlock.notifications.deliver`.
-
+---
+name: queue-notifications
+description: 'Send `@warlock.js/notifications` `.queue()` deliveries through BullMQ with `bullmqQueue({ queue?, attempts?, backoff? })` from `@warlock.js/notifications` — put it in the `queue` slot of `src/config/notifications.ts`; the queue workers deliver. Honours `SendOptions.delay` (number = seconds, or "10m"), retries a failing `channel.send`, and fails at once for a channel missing from the worker config. Triggers: `bullmqQueue`, `NotificationConfig.queue`, `QueuePackageNotInstalledError`; "queue notifications with BullMQ", "retry notification delivery", "delayed notification". Skip: the herald backend — `@warlock.js/notifications/queue-notifications/SKILL.md`.'
+---
+
+# Queue notifications with BullMQ
+
+```ts title="src/config/notifications.ts"
+import { type NotificationConfig, bullmqQueue, mailChannel } from "@warlock.js/notifications";
+
+const config: NotificationConfig = {
+  channels: { mail: mailChannel() },
+  queue: bullmqQueue({ attempts: 3, backoff: { type: "exponential", delay: 5000 } }),
+};
+
+export default config;
+```
+
+`bullmqQueue` ships inside `@warlock.js/notifications` itself and lazy-loads `@warlock.js/queue` (an OPTIONAL peer) the first time `.queue()` runs — install it with `warlock add queue` if it isn't there yet, otherwise the first `.queue()` throws `QueuePackageNotInstalledError`.
+
+Also configure the queue itself (`configure-queue`). No separate notifications worker is needed: the delivery is an ordinary job, run by the queue workers.
+
+```ts
+await orderShipped.queue(user, { order }); // enqueued, delivered by a worker
+await orderShipped.queue(user, { order }, { delay: "10m" }); // delivered in 10 minutes
+```
+
+## Behaviour
+
+- The job carries the rendered payload and resolved route; the worker looks the channel up by name in its own notifications config and calls `channel.send`.
+- `delay`: a number is seconds (notifications' convention); a string is a duration.
+- `channel.send` throws → retried per `attempts` / `backoff`, then listed by `failedJobs()`.
+- Channel not configured in the worker → fails at once, no retries.
+- Deliveries run under the job name `warlock.notifications.deliver`.
+