@warlock.js/scheduler 5.34.1 → 5.34.3

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to `@warlock.js/scheduler` 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.34.3 - 2026-10-20
+
+### Changed
+
+- Condensed the package agent skill description to at most 450 characters, with API names and package routing guidance.
+
+## 5.34.2 - 2026-10-19
+
+### Fixed
+
+- Merge package orientation into the grouped skill index and remove the duplicate overview topic; preserve that orientation in generated LLM projections.
+
 ## 5.32.0 - 2026-10-18
 
 ### Changed

package/llms-full.txt

@@ -4,7 +4,61 @@
 
 > Generated artifact. Concatenates every SKILL.md and reference file under `@warlock.js/scheduler/skills/`. Re-run `node scripts/generate-llms.mjs` after any change.
 
-## configure-retry-and-overlap  `@warlock.js/scheduler/configure-retry-and-overlap/SKILL.md`
+## Package orientation
+
+---
+description: 'In-process cron and fluent scheduling: `Scheduler`, `scheduler`, `Job`, `job`, `CronParser` and `parseCron`. Use for "run every day at 3am", "schedule weekdays", "retry a failing job", "prevent overlap", choose a timezone or observe job failures. Not this package → @warlock.js/queue for durable background workers; @warlock.js/cache for locks across instances; @warlock.js/herald for broker messaging.'
+---
+
+# @warlock.js/scheduler
+
+Build a `job(name, fn)`, describe when it runs with the fluent API (`.daily().at("03:00")`) or `.cron("...")`, add it to a `Scheduler`, then `start()`. Events (`job:error` and others) provide observability; `shutdown()` stops gracefully.
+
+## The 80% path
+
+1. Start with `scheduler-basics.md`.
+2. Define the schedule fluently: `schedule-fluently.md`, or by cron: `schedule-with-cron.md`.
+3. Make it resilient: `configure-retry-and-overlap.md`.
+4. Fix wall-clock semantics: `pin-schedule-timezone.md`.
+5. Watch it run: `observe-scheduler.md`.
+
+## Conventions and pitfalls
+
+- It is in-memory and per-process: each app instance runs its own copy. With multiple instances, guard jobs with a lock (for example `@warlock.js/cache`) or run the scheduler in one instance only.
+- Missed runs while the process was down are not replayed.
+- Set a timezone explicitly for jobs tied to business hours; otherwise UTC applies.
+- Call `scheduler.shutdown()` on SIGTERM so running jobs finish.
+- Use `preventOverlap()` for jobs that can outlast their interval.
+
+## Server-only package
+
+`@warlock.js/scheduler`'s entire runtime surface is server-only — its `package.json` declares `"warlock": { "environment": "server" }`. This is build-boundary metadata read by `@warlock.js/web`'s Gate A (import resolution) and Gate C (emitted-bundle verification), not application behavior. App code that reaches the client bundle (including page and layout modules) must not value-import `@warlock.js/scheduler` — Gate A refuses the build. A type-only import (`import type { ... }`) is allowed. Server loaders, controllers, and modules may import it freely.
+
+## When to reach for it
+
+- You have **recurring work** in a Node service (cleanups, reports, syncs, polling) and want it scheduled inside the app process — no external cron, no docker-cron sidecar.
+- You'd reach for **node-cron** or **agenda** but want a typed fluent API, retry-with-backoff, overlap prevention, and a working observability story built in — without bringing Redis (agenda) or hand-rolling retry yourself (node-cron).
+- You're inside a `@warlock.js/*` project — the framework already uses this for built-in maintenance jobs (token cleanup, etc.).
+
+Skip if you need a **distributed** job queue with persistence, retries across processes, and worker pools — reach for **BullMQ** or **Temporal**. This package runs jobs **in-process**; if the process dies before the next tick, the schedule resumes from now, not from the missed fire time.
+
+## The mental model in one paragraph
+
+Define a job with `job("name", async () => { ... })`. Attach a schedule via the fluent API (`.daily().at("03:00")`) or a cron string (`.cron("0 3 * * *")`). Optionally pin a timezone (`.inTimezone("America/New_York")`), prevent concurrent runs (`.preventOverlap()`), and configure retries (`.retry(3, 1000)`). Register the job with `scheduler.addJob(job)`, call `scheduler.start()`, and listen on the seven lifecycle events (`job:start` / `complete` / `error` / `skip`, `scheduler:started` / `stopped` / `tick`) for logging, metrics, and alerting. `scheduler.shutdown()` drains in-flight jobs before exit.
+
+## What this package deliberately doesn't do
+
+- **Distributed scheduling across processes.** Jobs run in the calling process. For multi-instance deployments, either run the scheduler on one instance (with a leader election) or reach for BullMQ / Temporal.
+- **Persistent job state across restarts.** A missed fire while the process was down is missed — it doesn't catch up. For exactly-once-eventually semantics, use a queue.
+- **Job priority queues or fan-out.** One job = one function. For fan-out, your job dispatches to a queue.
+- **Cron-syntax extensions** beyond the standard 5-field form (no `@daily` macros, no seconds field). Use the fluent API for human-readable schedules instead.
+
+## See also
+
+- The `warlock-js-core` skill index — the parent framework that scheduled jobs typically run alongside.
+
+
+## configure-retry-and-overlap  `@warlock.js/scheduler/skills/configure-retry-and-overlap/SKILL.md`
 
 ---
 name: configure-retry-and-overlap
@@ -150,7 +204,7 @@ job("sync", sync).everyMinutes(5).onOneServer({ lockTtl: "10m", key: "sync-v2" }
 - Throws at call time if the job has no name/key.
 
 
-## observe-scheduler  `@warlock.js/scheduler/observe-scheduler/SKILL.md`
+## observe-scheduler  `@warlock.js/scheduler/skills/observe-scheduler/SKILL.md`
 
 ---
 name: observe-scheduler
@@ -308,113 +362,7 @@ job.cronExpression; // string | null
 - The `schedule-fluently` topic — the methods that mutate the state these getters expose
 
 
-## overview  `@warlock.js/scheduler/overview/SKILL.md`
-
----
-name: overview
-description: "@warlock.js/scheduler overview for orientation and choosing the focused skill for the task."
----
-
-# `@warlock.js/scheduler` — overview
-
-Production-ready job scheduler with a cron engine, fluent schedule builder, retry-with-backoff, overlap prevention, IANA timezone pinning, and seven typed lifecycle events. Two primitives — `job(name, fn)` and the `scheduler` singleton — that compose into everything else.
-
-## Server-only package
-
-`@warlock.js/scheduler`'s entire runtime surface is server-only — its `package.json` declares `"warlock": { "environment": "server" }`. This is build-boundary metadata read by `@warlock.js/web`'s Gate A (import resolution) and Gate C (emitted-bundle verification), not application behavior. App code that reaches the client bundle (including page and layout modules) must not value-import `@warlock.js/scheduler` — Gate A refuses the build. A type-only import (`import type { ... }`) is allowed. Server loaders, controllers, and modules may import it freely.
-
-## When to reach for it
-
-- You have **recurring work** in a Node service (cleanups, reports, syncs, polling) and want it scheduled inside the app process — no external cron, no docker-cron sidecar.
-- You'd reach for **node-cron** or **agenda** but want a typed fluent API, retry-with-backoff, overlap prevention, and a working observability story built in — without bringing Redis (agenda) or hand-rolling retry yourself (node-cron).
-- You're inside a `@warlock.js/*` project — the framework already uses this for built-in maintenance jobs (token cleanup, etc.).
-
-Skip if you need a **distributed** job queue with persistence, retries across processes, and worker pools — reach for **BullMQ** or **Temporal**. This package runs jobs **in-process**; if the process dies before the next tick, the schedule resumes from now, not from the missed fire time.
-
-## The mental model in one paragraph
-
-Define a job with `job("name", async () => { ... })`. Attach a schedule via the fluent API (`.daily().at("03:00")`) or a cron string (`.cron("0 3 * * *")`). Optionally pin a timezone (`.inTimezone("America/New_York")`), prevent concurrent runs (`.preventOverlap()`), and configure retries (`.retry(3, 1000)`). Register the job with `scheduler.addJob(job)`, call `scheduler.start()`, and listen on the seven lifecycle events (`job:start` / `complete` / `error` / `skip`, `scheduler:started` / `stopped` / `tick`) for logging, metrics, and alerting. `scheduler.shutdown()` drains in-flight jobs before exit.
-
-## Skills index
-
-Six task skills cover the full surface. Most callers only need `scheduler-basics` + `schedule-fluently` + `observe-scheduler`.
-
-### Foundations
-
-#### `scheduler-basics`
-
-Start here. The `job(name, fn)` factory, the `scheduler` singleton, the 2-primitive surface, UTC default, why the API is factory-first.
-
-### Scheduling
-
-#### `schedule-fluently`
-
-Build schedules without writing cron: `.everyMinutes(N)`, `.daily().at("03:00")`, `.weekly().on("monday")`, `.monthly()`, `.beginOf("month")`, `.endOf("year")`, and friends. Reach for this 80% of the time.
-
-#### `schedule-with-cron`
-
-Drop down to `.cron("0 9 * * 1-5")` when the fluent API can't express it (Vixie OR semantics for DOM/DOW, complex multi-value lists). Includes `parseCron()` for previewing next-run times before deploy.
-
-### Production concerns
-
-#### `configure-retry-and-overlap`
-
-`.retry(maxRetries, delay?, backoffMultiplier?)` for fixed or exponential backoff; `.preventOverlap()` so a slow run never collides with the next tick. Reach for both anytime a job calls external services.
-
-#### `pin-schedule-timezone`
-
-`.inTimezone("America/New_York")` pins wall-clock fire times across DST and across servers. The default is UTC — if your job description includes "9 AM," you almost certainly want this skill.
-
-### Observability + shutdown
-
-#### `observe-scheduler`
-
-The seven typed `SchedulerEvents` (`job:start` / `complete` / `error` / `skip`, `scheduler:started` / `stopped` / `tick`), the `JobResult` payload, `start()` / `stop()` / `shutdown()`. Wire this for logging, metrics, alerting, and graceful SIGTERM handling.
-
-## Quick taste
-
-```ts
-import { Scheduler, job } from "@warlock.js/scheduler";
-
-const scheduler = new Scheduler();
-
-scheduler.on("job:error", (name, error) => {
-  console.error(`${name} failed:`, error);
-});
-
-scheduler.addJob(
-  job("cleanup", async () => {
-    await cleanupExpiredTokens();
-  })
-    .daily()
-    .at("03:00")
-    .inTimezone("America/New_York")
-    .preventOverlap()
-    .retry(3, 1000),
-);
-
-scheduler.addJob(
-  job("reports", sendReports).cron("0 9 * * 1-5"), // 9 AM weekdays
-);
-
-scheduler.start();
-process.on("SIGTERM", () => scheduler.shutdown());
-```
-
-## What this package deliberately doesn't do
-
-- **Distributed scheduling across processes.** Jobs run in the calling process. For multi-instance deployments, either run the scheduler on one instance (with a leader election) or reach for BullMQ / Temporal.
-- **Persistent job state across restarts.** A missed fire while the process was down is missed — it doesn't catch up. For exactly-once-eventually semantics, use a queue.
-- **Job priority queues or fan-out.** One job = one function. For fan-out, your job dispatches to a queue.
-- **Cron-syntax extensions** beyond the standard 5-field form (no `@daily` macros, no seconds field). Use the fluent API for human-readable schedules instead.
-
-## See also
-
-- The `overview` topic of the `warlock-js-core` skill — the parent framework that scheduled jobs typically run alongside.
-- `mongez-agent-kit-authoring-skills` (load via agent-kit sync) — how this `overview` topic becomes the front-door skill in `.claude/skills/warlock-js-scheduler-overview/`. Every cross-link above names the topic (and the owning skill, across packages) instead of a file path so it survives that flattening.
-
-
-## pin-schedule-timezone  `@warlock.js/scheduler/pin-schedule-timezone/SKILL.md`
+## pin-schedule-timezone  `@warlock.js/scheduler/skills/pin-schedule-timezone/SKILL.md`
 
 ---
 name: pin-schedule-timezone
@@ -523,7 +471,7 @@ Node ships full ICU on most platforms, so all IANA zones work out of the box. If
 - The `observe-scheduler` topic — `job.nextRun.toISOString()` always renders in UTC; format with `.tz(zone)` to see local time
 
 
-## schedule-fluently  `@warlock.js/scheduler/schedule-fluently/SKILL.md`
+## schedule-fluently  `@warlock.js/scheduler/skills/schedule-fluently/SKILL.md`
 
 ---
 name: schedule-fluently
@@ -665,7 +613,7 @@ j?.cronExpression; // null if using fluent API
 - The `pin-schedule-timezone` topic — `.inTimezone()`
 
 
-## schedule-with-cron  `@warlock.js/scheduler/schedule-with-cron/SKILL.md`
+## schedule-with-cron  `@warlock.js/scheduler/skills/schedule-with-cron/SKILL.md`
 
 ---
 name: schedule-with-cron
@@ -792,7 +740,7 @@ If the job has `.inTimezone(tz)`, the cron parser receives a timezone-aware `day
 - The `pin-schedule-timezone` topic — pinning a cron schedule to a wall-clock timezone
 
 
-## scheduler-basics  `@warlock.js/scheduler/scheduler-basics/SKILL.md`
+## scheduler-basics  `@warlock.js/scheduler/skills/scheduler-basics/SKILL.md`
 
 ---
 name: scheduler-basics

package/llms.txt

@@ -6,10 +6,10 @@
 
 ## Skills
 
-- [configure-retry-and-overlap](@warlock.js/scheduler/configure-retry-and-overlap/SKILL.md): Configure `.retry(maxRetries, delay?, backoffMultiplier?)` for fixed / exponential backoff and `.preventOverlap()` for external-invocation safety. Triggers: `.retry`, `.preventOverlap`, `maxRetries`, `backoffMultiplier`, `JobResult.retries`, `job:error`, `job:skip`; "how do I retry a failed job", "exponential backoff for scheduled job", "prevent concurrent job runs", "stop firing after N consecutive failures"; typical import `import { job, scheduler } from "@warlock.js/scheduler"`. Skip: events / shutdown — the `observe-scheduler` topic; building the schedule itself — the `schedule-fluently` topic; competing libs `p-retry`, `async-retry`, `bullmq`.
-- [observe-scheduler](@warlock.js/scheduler/observe-scheduler/SKILL.md): Subscribe to scheduler lifecycle and job events for logging / metrics / alerting / graceful shutdown — seven typed `SchedulerEvents`, `JobResult` payload, `start()` / `stop()` / `shutdown()`. Triggers: `scheduler.on`, `scheduler.shutdown`, `JobResult`, `job:complete`, `job:error`, `scheduler:started`, `scheduler.getJob`; "graceful SIGTERM shutdown", "did this job run", "scheduler metrics and alerts", "subscribe to job events"; typical import `import { scheduler, type JobResult } from "@warlock.js/scheduler"`. Skip: retry / overlap — the `configure-retry-and-overlap` topic; building schedules — the `schedule-fluently` topic; native `EventEmitter`, `process.on`.
-- [overview](@warlock.js/scheduler/overview/SKILL.md): @warlock.js/scheduler overview for orientation and choosing the focused skill for the task.
-- [pin-schedule-timezone](@warlock.js/scheduler/pin-schedule-timezone/SKILL.md): Pin a job to a specific IANA timezone via `.inTimezone(zone)` so its wall-clock fire time stays correct regardless of server location / DST. Triggers: `.inTimezone`, `America/New_York`, `Europe/Berlin`, `Asia/Tokyo`, `NODE_ICU_DATA`; "schedule job in a timezone", "DST drift on non-UTC server", "multi-region fan-out scheduling", "fire at 9am ET regardless of server"; typical import `import { job, scheduler } from "@warlock.js/scheduler"`. Skip: fluent interval methods — the `schedule-fluently` topic; cron syntax — the `schedule-with-cron` topic; competing libs `dayjs-timezone`, `luxon`, `date-fns-tz`.
-- [schedule-fluently](@warlock.js/scheduler/schedule-fluently/SKILL.md): Build a job schedule via `every*` / `daily` / `weekly` / `monthly` / `at` / `on` / `beginOf` / `endOf`. Triggers: `.everyMinutes`, `.daily`, `.weekly`, `.monthly`, `.at`, `.on`, `.every`, `.beginOf`, `.endOf`, `.twiceDaily`, `scheduler.newJob`; "run every 5 minutes", "daily at 3am", "monday standup", "first of every month", "last day of month"; typical import `import { job, scheduler } from "@warlock.js/scheduler"`. Skip: cron — the `schedule-with-cron` topic; timezone — the `pin-schedule-timezone` topic; retry — the `configure-retry-and-overlap` topic; competing `node-cron`, `node-schedule`, `agenda`; native `setInterval`.
-- [schedule-with-cron](@warlock.js/scheduler/schedule-with-cron/SKILL.md): Write `.cron('…')` expressions — 5-field syntax, operators (`*` `,` `-` `/`), Vixie OR semantics for DOM / DOW, `parseCron()` preview utility. Triggers: `.cron`, `parseCron`, `CronParser`, `*/5 * * * *`, `0 9 * * 1-5`; "write a cron expression", "every weekday at 9am cron", "preview next cron run", "migrate crontab(5) entry"; typical import `import { parseCron } from "@warlock.js/scheduler"`. Skip: human-readable schedules — the `schedule-fluently` topic; timezone — the `pin-schedule-timezone` topic; competing libs `node-cron`, `cron`, `croner`, `cronstrue`.
-- [scheduler-basics](@warlock.js/scheduler/scheduler-basics/SKILL.md): Start here for @warlock.js/scheduler recurring jobs, schedules, worker configuration, and job lifecycle.
+- [Package orientation](@warlock.js/scheduler/skills/index.md): In-process cron and fluent scheduling: `Scheduler`, `scheduler`, `Job`, `job`, `CronParser` and `parseCron`. Use for "run every day at 3am", "schedule weekdays", "retry a failing job", "prevent overlap", choose a timezone or observe job failures. Not this package → @warlock.js/queue for durable background workers; @warlock.js/cache for locks across instances; @warlock.js/herald for broker messaging.
+- [configure-retry-and-overlap](@warlock.js/scheduler/skills/configure-retry-and-overlap/SKILL.md): Configure `.retry(maxRetries, delay?, backoffMultiplier?)` for fixed / exponential backoff and `.preventOverlap()` for external-invocation safety. Triggers: `.retry`, `.preventOverlap`, `maxRetries`, `backoffMultiplier`, `JobResult.retries`, `job:error`, `job:skip`; "how do I retry a failed job", "exponential backoff for scheduled job", "prevent concurrent job runs", "stop firing after N consecutive failures"; typical import `import { job, scheduler } from "@warlock.js/scheduler"`. Skip: events / shutdown — the `observe-scheduler` topic; building the schedule itself — the `schedule-fluently` topic; competing libs `p-retry`, `async-retry`, `bullmq`.
+- [observe-scheduler](@warlock.js/scheduler/skills/observe-scheduler/SKILL.md): Subscribe to scheduler lifecycle and job events for logging / metrics / alerting / graceful shutdown — seven typed `SchedulerEvents`, `JobResult` payload, `start()` / `stop()` / `shutdown()`. Triggers: `scheduler.on`, `scheduler.shutdown`, `JobResult`, `job:complete`, `job:error`, `scheduler:started`, `scheduler.getJob`; "graceful SIGTERM shutdown", "did this job run", "scheduler metrics and alerts", "subscribe to job events"; typical import `import { scheduler, type JobResult } from "@warlock.js/scheduler"`. Skip: retry / overlap — the `configure-retry-and-overlap` topic; building schedules — the `schedule-fluently` topic; native `EventEmitter`, `process.on`.
+- [pin-schedule-timezone](@warlock.js/scheduler/skills/pin-schedule-timezone/SKILL.md): Pin a job to a specific IANA timezone via `.inTimezone(zone)` so its wall-clock fire time stays correct regardless of server location / DST. Triggers: `.inTimezone`, `America/New_York`, `Europe/Berlin`, `Asia/Tokyo`, `NODE_ICU_DATA`; "schedule job in a timezone", "DST drift on non-UTC server", "multi-region fan-out scheduling", "fire at 9am ET regardless of server"; typical import `import { job, scheduler } from "@warlock.js/scheduler"`. Skip: fluent interval methods — the `schedule-fluently` topic; cron syntax — the `schedule-with-cron` topic; competing libs `dayjs-timezone`, `luxon`, `date-fns-tz`.
+- [schedule-fluently](@warlock.js/scheduler/skills/schedule-fluently/SKILL.md): Build a job schedule via `every*` / `daily` / `weekly` / `monthly` / `at` / `on` / `beginOf` / `endOf`. Triggers: `.everyMinutes`, `.daily`, `.weekly`, `.monthly`, `.at`, `.on`, `.every`, `.beginOf`, `.endOf`, `.twiceDaily`, `scheduler.newJob`; "run every 5 minutes", "daily at 3am", "monday standup", "first of every month", "last day of month"; typical import `import { job, scheduler } from "@warlock.js/scheduler"`. Skip: cron — the `schedule-with-cron` topic; timezone — the `pin-schedule-timezone` topic; retry — the `configure-retry-and-overlap` topic; competing `node-cron`, `node-schedule`, `agenda`; native `setInterval`.
+- [schedule-with-cron](@warlock.js/scheduler/skills/schedule-with-cron/SKILL.md): Write `.cron('…')` expressions — 5-field syntax, operators (`*` `,` `-` `/`), Vixie OR semantics for DOM / DOW, `parseCron()` preview utility. Triggers: `.cron`, `parseCron`, `CronParser`, `*/5 * * * *`, `0 9 * * 1-5`; "write a cron expression", "every weekday at 9am cron", "preview next cron run", "migrate crontab(5) entry"; typical import `import { parseCron } from "@warlock.js/scheduler"`. Skip: human-readable schedules — the `schedule-fluently` topic; timezone — the `pin-schedule-timezone` topic; competing libs `node-cron`, `cron`, `croner`, `cronstrue`.
+- [scheduler-basics](@warlock.js/scheduler/skills/scheduler-basics/SKILL.md): Start here for @warlock.js/scheduler recurring jobs, schedules, worker configuration, and job lifecycle.

package/package.json

@@ -8,7 +8,7 @@
     "dayjs": "^1.11.19"
   },
   "peerDependencies": {
-    "@warlock.js/cache": "5.34.1"
+    "@warlock.js/cache": "5.34.3"
   },
   "peerDependenciesMeta": {
     "@warlock.js/cache": {
@@ -34,7 +34,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.34.1",
+  "version": "5.34.3",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/index.md

@@ -1,5 +1,5 @@
 ---
-description: 'In-process job scheduler for Warlock.js with fluent and cron scheduling, retries, overlap prevention and timezones. Exports `Scheduler`, `scheduler`, `Job`, `job`, `CronParser`, `parseCron`, plus types `RetryConfig`, `JobResult`, `SchedulerEvents`. Use for: "run this every day at 3am", "run a cron expression on weekdays", "retry a failing job 3 times", "stop a job overlapping itself", "run in New York time", "log job failures". Not this package: durable queues and background workers are not scheduling; per-run locking across instances uses @warlock.js/cache.'
+description: 'In-process cron and fluent scheduling: `Scheduler`, `scheduler`, `Job`, `job`, `CronParser` and `parseCron`. Use for "run every day at 3am", "schedule weekdays", "retry a failing job", "prevent overlap", choose a timezone or observe job failures. Not this package → @warlock.js/queue for durable background workers; @warlock.js/cache for locks across instances; @warlock.js/herald for broker messaging.'
 ---
 
 # @warlock.js/scheduler
@@ -8,7 +8,7 @@ Build a `job(name, fn)`, describe when it runs with the fluent API (`.daily().at
 
 ## The 80% path
 
-1. Orient: `overview.md`, `scheduler-basics.md`.
+1. Start with `scheduler-basics.md`.
 2. Define the schedule fluently: `schedule-fluently.md`, or by cron: `schedule-with-cron.md`.
 3. Make it resilient: `configure-retry-and-overlap.md`.
 4. Fix wall-clock semantics: `pin-schedule-timezone.md`.
@@ -18,6 +18,33 @@ Build a `job(name, fn)`, describe when it runs with the fluent API (`.daily().at
 
 - It is in-memory and per-process: each app instance runs its own copy. With multiple instances, guard jobs with a lock (for example `@warlock.js/cache`) or run the scheduler in one instance only.
 - Missed runs while the process was down are not replayed.
-- Set a timezone explicitly for jobs tied to business hours; otherwise the host's applies.
+- Set a timezone explicitly for jobs tied to business hours; otherwise UTC applies.
 - Call `scheduler.shutdown()` on SIGTERM so running jobs finish.
 - Use `preventOverlap()` for jobs that can outlast their interval.
+
+## Server-only package
+
+`@warlock.js/scheduler`'s entire runtime surface is server-only — its `package.json` declares `"warlock": { "environment": "server" }`. This is build-boundary metadata read by `@warlock.js/web`'s Gate A (import resolution) and Gate C (emitted-bundle verification), not application behavior. App code that reaches the client bundle (including page and layout modules) must not value-import `@warlock.js/scheduler` — Gate A refuses the build. A type-only import (`import type { ... }`) is allowed. Server loaders, controllers, and modules may import it freely.
+
+## When to reach for it
+
+- You have **recurring work** in a Node service (cleanups, reports, syncs, polling) and want it scheduled inside the app process — no external cron, no docker-cron sidecar.
+- You'd reach for **node-cron** or **agenda** but want a typed fluent API, retry-with-backoff, overlap prevention, and a working observability story built in — without bringing Redis (agenda) or hand-rolling retry yourself (node-cron).
+- You're inside a `@warlock.js/*` project — the framework already uses this for built-in maintenance jobs (token cleanup, etc.).
+
+Skip if you need a **distributed** job queue with persistence, retries across processes, and worker pools — reach for **BullMQ** or **Temporal**. This package runs jobs **in-process**; if the process dies before the next tick, the schedule resumes from now, not from the missed fire time.
+
+## The mental model in one paragraph
+
+Define a job with `job("name", async () => { ... })`. Attach a schedule via the fluent API (`.daily().at("03:00")`) or a cron string (`.cron("0 3 * * *")`). Optionally pin a timezone (`.inTimezone("America/New_York")`), prevent concurrent runs (`.preventOverlap()`), and configure retries (`.retry(3, 1000)`). Register the job with `scheduler.addJob(job)`, call `scheduler.start()`, and listen on the seven lifecycle events (`job:start` / `complete` / `error` / `skip`, `scheduler:started` / `stopped` / `tick`) for logging, metrics, and alerting. `scheduler.shutdown()` drains in-flight jobs before exit.
+
+## What this package deliberately doesn't do
+
+- **Distributed scheduling across processes.** Jobs run in the calling process. For multi-instance deployments, either run the scheduler on one instance (with a leader election) or reach for BullMQ / Temporal.
+- **Persistent job state across restarts.** A missed fire while the process was down is missed — it doesn't catch up. For exactly-once-eventually semantics, use a queue.
+- **Job priority queues or fan-out.** One job = one function. For fan-out, your job dispatches to a queue.
+- **Cron-syntax extensions** beyond the standard 5-field form (no `@daily` macros, no seconds field). Use the fluent API for human-readable schedules instead.
+
+## See also
+
+- The `warlock-js-core` skill index — the parent framework that scheduled jobs typically run alongside.

package/skills/overview/SKILL.md

@@ -1,102 +0,0 @@
----
-name: overview
-description: "@warlock.js/scheduler overview for orientation and choosing the focused skill for the task."
----
-
-# `@warlock.js/scheduler` — overview
-
-Production-ready job scheduler with a cron engine, fluent schedule builder, retry-with-backoff, overlap prevention, IANA timezone pinning, and seven typed lifecycle events. Two primitives — `job(name, fn)` and the `scheduler` singleton — that compose into everything else.
-
-## Server-only package
-
-`@warlock.js/scheduler`'s entire runtime surface is server-only — its `package.json` declares `"warlock": { "environment": "server" }`. This is build-boundary metadata read by `@warlock.js/web`'s Gate A (import resolution) and Gate C (emitted-bundle verification), not application behavior. App code that reaches the client bundle (including page and layout modules) must not value-import `@warlock.js/scheduler` — Gate A refuses the build. A type-only import (`import type { ... }`) is allowed. Server loaders, controllers, and modules may import it freely.
-
-## When to reach for it
-
-- You have **recurring work** in a Node service (cleanups, reports, syncs, polling) and want it scheduled inside the app process — no external cron, no docker-cron sidecar.
-- You'd reach for **node-cron** or **agenda** but want a typed fluent API, retry-with-backoff, overlap prevention, and a working observability story built in — without bringing Redis (agenda) or hand-rolling retry yourself (node-cron).
-- You're inside a `@warlock.js/*` project — the framework already uses this for built-in maintenance jobs (token cleanup, etc.).
-
-Skip if you need a **distributed** job queue with persistence, retries across processes, and worker pools — reach for **BullMQ** or **Temporal**. This package runs jobs **in-process**; if the process dies before the next tick, the schedule resumes from now, not from the missed fire time.
-
-## The mental model in one paragraph
-
-Define a job with `job("name", async () => { ... })`. Attach a schedule via the fluent API (`.daily().at("03:00")`) or a cron string (`.cron("0 3 * * *")`). Optionally pin a timezone (`.inTimezone("America/New_York")`), prevent concurrent runs (`.preventOverlap()`), and configure retries (`.retry(3, 1000)`). Register the job with `scheduler.addJob(job)`, call `scheduler.start()`, and listen on the seven lifecycle events (`job:start` / `complete` / `error` / `skip`, `scheduler:started` / `stopped` / `tick`) for logging, metrics, and alerting. `scheduler.shutdown()` drains in-flight jobs before exit.
-
-## Skills index
-
-Six task skills cover the full surface. Most callers only need `scheduler-basics` + `schedule-fluently` + `observe-scheduler`.
-
-### Foundations
-
-#### `scheduler-basics`
-
-Start here. The `job(name, fn)` factory, the `scheduler` singleton, the 2-primitive surface, UTC default, why the API is factory-first.
-
-### Scheduling
-
-#### `schedule-fluently`
-
-Build schedules without writing cron: `.everyMinutes(N)`, `.daily().at("03:00")`, `.weekly().on("monday")`, `.monthly()`, `.beginOf("month")`, `.endOf("year")`, and friends. Reach for this 80% of the time.
-
-#### `schedule-with-cron`
-
-Drop down to `.cron("0 9 * * 1-5")` when the fluent API can't express it (Vixie OR semantics for DOM/DOW, complex multi-value lists). Includes `parseCron()` for previewing next-run times before deploy.
-
-### Production concerns
-
-#### `configure-retry-and-overlap`
-
-`.retry(maxRetries, delay?, backoffMultiplier?)` for fixed or exponential backoff; `.preventOverlap()` so a slow run never collides with the next tick. Reach for both anytime a job calls external services.
-
-#### `pin-schedule-timezone`
-
-`.inTimezone("America/New_York")` pins wall-clock fire times across DST and across servers. The default is UTC — if your job description includes "9 AM," you almost certainly want this skill.
-
-### Observability + shutdown
-
-#### `observe-scheduler`
-
-The seven typed `SchedulerEvents` (`job:start` / `complete` / `error` / `skip`, `scheduler:started` / `stopped` / `tick`), the `JobResult` payload, `start()` / `stop()` / `shutdown()`. Wire this for logging, metrics, alerting, and graceful SIGTERM handling.
-
-## Quick taste
-
-```ts
-import { Scheduler, job } from "@warlock.js/scheduler";
-
-const scheduler = new Scheduler();
-
-scheduler.on("job:error", (name, error) => {
-  console.error(`${name} failed:`, error);
-});
-
-scheduler.addJob(
-  job("cleanup", async () => {
-    await cleanupExpiredTokens();
-  })
-    .daily()
-    .at("03:00")
-    .inTimezone("America/New_York")
-    .preventOverlap()
-    .retry(3, 1000),
-);
-
-scheduler.addJob(
-  job("reports", sendReports).cron("0 9 * * 1-5"), // 9 AM weekdays
-);
-
-scheduler.start();
-process.on("SIGTERM", () => scheduler.shutdown());
-```
-
-## What this package deliberately doesn't do
-
-- **Distributed scheduling across processes.** Jobs run in the calling process. For multi-instance deployments, either run the scheduler on one instance (with a leader election) or reach for BullMQ / Temporal.
-- **Persistent job state across restarts.** A missed fire while the process was down is missed — it doesn't catch up. For exactly-once-eventually semantics, use a queue.
-- **Job priority queues or fan-out.** One job = one function. For fan-out, your job dispatches to a queue.
-- **Cron-syntax extensions** beyond the standard 5-field form (no `@daily` macros, no seconds field). Use the fluent API for human-readable schedules instead.
-
-## See also
-
-- The `overview` topic of the `warlock-js-core` skill — the parent framework that scheduled jobs typically run alongside.
-- `mongez-agent-kit-authoring-skills` (load via agent-kit sync) — how this `overview` topic becomes the front-door skill in `.claude/skills/warlock-js-scheduler-overview/`. Every cross-link above names the topic (and the owning skill, across packages) instead of a file path so it survives that flattening.