Sync docs from wheels@cfe1bc3

github-actions[bot] · github-actions[bot] · commit be7e14b3f405 · 2026-03-12T17:11:55.000Z
diff --git a/docs/3.1.0/guides/SUMMARY.md b/docs/3.1.0/guides/SUMMARY.md
@@ -99,6 +99,12 @@
     * [wheels plugin init](command-line-tools/commands/plugins/plugins-init.md)
   * Asset Management
     * [asset management commands](command-line-tools/commands/assets-cache-management.md)
+  * Job Commands
+    * [wheels jobs work](command-line-tools/commands/jobs/jobs-work.md)
+    * [wheels jobs status](command-line-tools/commands/jobs/jobs-status.md)
+    * [wheels jobs retry](command-line-tools/commands/jobs/jobs-retry.md)
+    * [wheels jobs purge](command-line-tools/commands/jobs/jobs-purge.md)
+    * [wheels jobs monitor](command-line-tools/commands/jobs/jobs-monitor.md)
 * CLI Development Guides
   * [Configuration Management](command-line-tools/configuration.md)
   * [Creating Commands](command-line-tools/cli-guides/creating-commands.md)
@@ -120,6 +126,7 @@
 * [Contributing to Wheels Windows Installer](working-with-wheels/contributing-to-wheels-windows-installer.md)
 * [Contributing to Wheels macOS Installer](working-with-wheels/contributing-to-wheels-macos-installer.md)
 * [Background Jobs](working-with-wheels/background-jobs.md)
+* [Dependency Injection](working-with-wheels/dependency-injection.md)
 * [Submitting Pull Requests](working-with-wheels/submitting-pull-requests.md)
 * [Documenting your Code](working-with-wheels/documenting-your-code.md)
 
diff --git a/docs/3.1.0/guides/command-line-tools/commands/jobs/jobs-monitor.md b/docs/3.1.0/guides/command-line-tools/commands/jobs/jobs-monitor.md
@@ -0,0 +1,54 @@
+---
+description: Live monitoring dashboard for the job queue.
+---
+
+# wheels jobs monitor
+
+Display a continuously refreshing dashboard showing queue statistics, throughput metrics, error rates, and recent job activity.
+
+## Usage
+
+```bash
+wheels jobs monitor [options]
+```
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--interval` | `3` | Refresh interval in seconds |
+| `--queue` | _(all)_ | Filter by queue name |
+
+## Examples
+
+```bash
+# Watch the dashboard with default settings
+wheels jobs monitor
+
+# Slower refresh rate
+wheels jobs monitor --interval=10
+
+# Monitor a specific queue
+wheels jobs monitor --queue=mailers
+```
+
+## Dashboard Sections
+
+### Queue Summary
+Pending, processing, completed, and failed counts across all queues.
+
+### Throughput (last 60 minutes)
+- Completed and failed job counts
+- Error rate percentage
+
+### Recent Jobs
+The 5 most recently updated jobs with status, class, queue, and timestamp.
+
+### Timeout Recovery
+If any processing jobs have exceeded their timeout, they are automatically recovered and reported.
+
+## Behavior
+
+- Each refresh cycle calls the Wheels bridge to fetch fresh statistics
+- Timed-out jobs (stuck in `processing` longer than 300 seconds) are automatically recovered
+- Press `Ctrl+C` to stop monitoring
diff --git a/docs/3.1.0/guides/command-line-tools/commands/jobs/jobs-purge.md b/docs/3.1.0/guides/command-line-tools/commands/jobs/jobs-purge.md
@@ -0,0 +1,46 @@
+---
+description: Purge old completed or failed jobs from the queue table.
+---
+
+# wheels jobs purge
+
+Delete old jobs from the `wheels_jobs` table to prevent table bloat. By default, purges completed jobs older than 7 days.
+
+## Usage
+
+```bash
+wheels jobs purge [options]
+```
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--completed` | `true` | Purge completed jobs |
+| `--failed` | `false` | Purge failed jobs |
+| `--older-than` | `7` | Delete jobs older than this many days |
+| `--queue` | _(all)_ | Filter by queue name |
+| `--force` | `false` | Skip confirmation prompt |
+
+## Examples
+
+```bash
+# Purge completed jobs older than 7 days (default)
+wheels jobs purge
+
+# Purge both completed and failed jobs older than 30 days
+wheels jobs purge --completed --failed --older-than=30
+
+# Purge only from a specific queue
+wheels jobs purge --queue=reports --older-than=14
+
+# Purge failed jobs only
+wheels jobs purge --completed=false --failed --older-than=3
+```
+
+## Behavior
+
+- Completed jobs are matched by `completedAt` date
+- Failed jobs are matched by `failedAt` date
+- Pending and processing jobs are never purged
+- When both `--completed` and `--failed` are specified, each is purged separately and totals are reported
diff --git a/docs/3.1.0/guides/command-line-tools/commands/jobs/jobs-retry.md b/docs/3.1.0/guides/command-line-tools/commands/jobs/jobs-retry.md
@@ -0,0 +1,41 @@
+---
+description: Retry failed jobs by resetting them to pending status.
+---
+
+# wheels jobs retry
+
+Reset failed jobs back to `pending` status so they will be picked up by the next worker cycle. Resets the attempt counter and clears the error state.
+
+## Usage
+
+```bash
+wheels jobs retry [options]
+```
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--queue` | _(all)_ | Filter by queue name |
+| `--limit` | `0` | Maximum number of jobs to retry (0 = all) |
+
+## Examples
+
+```bash
+# Retry all failed jobs across all queues
+wheels jobs retry
+
+# Retry only failed mailer jobs
+wheels jobs retry --queue=mailers
+
+# Retry at most 10 failed jobs (oldest first)
+wheels jobs retry --limit=10
+```
+
+## Behavior
+
+- Sets `status` back to `pending`
+- Resets `attempts` to `0`
+- Clears `lastError` and `failedAt`
+- Sets `runAt` to now (immediate processing)
+- When `--limit` is specified, retries the oldest failed jobs first
diff --git a/docs/3.1.0/guides/command-line-tools/commands/jobs/jobs-status.md b/docs/3.1.0/guides/command-line-tools/commands/jobs/jobs-status.md
@@ -0,0 +1,45 @@
+---
+description: Display job queue statistics with per-queue breakdown.
+---
+
+# wheels jobs status
+
+Show the current state of the job queue, broken down by queue name and status.
+
+## Usage
+
+```bash
+wheels jobs status [options]
+```
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--queue` | _(all)_ | Filter by queue name |
+| `--format` | `table` | Output format: `table` or `json` |
+
+## Examples
+
+```bash
+# Show all queues in table format
+wheels jobs status
+
+# Filter to a specific queue
+wheels jobs status --queue=mailers
+
+# JSON output for scripting
+wheels jobs status --format=json
+```
+
+## Output
+
+The table displays per-queue counts for each status (pending, processing, completed, failed) with a totals row:
+
+```
+| Queue       | Pending | Processing | Completed | Failed | Total |
+|-------------|---------|------------|-----------|--------|-------|
+| default     | 5       | 1          | 230       | 2      | 238   |
+| mailers     | 12      | 0          | 89        | 0      | 101   |
+| TOTAL       | 17      | 1          | 319       | 2      | 339   |
+```
diff --git a/docs/3.1.0/guides/command-line-tools/commands/jobs/jobs-work.md b/docs/3.1.0/guides/command-line-tools/commands/jobs/jobs-work.md
@@ -0,0 +1,59 @@
+---
+description: Start a persistent job worker daemon that polls for and processes background jobs.
+---
+
+# wheels jobs work
+
+Start a job worker that continuously polls the job queue and processes pending jobs. The worker claims jobs using optimistic locking, making it safe to run multiple workers concurrently.
+
+## Usage
+
+```bash
+wheels jobs work [options]
+```
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--queue` | _(all)_ | Comma-delimited queue names to process |
+| `--interval` | `5` | Seconds between poll cycles |
+| `--max-jobs` | `0` | Stop after processing this many jobs (0 = unlimited) |
+| `--timeout` | `300` | Job execution timeout in seconds |
+| `--quiet` | `false` | Suppress per-job output, only show errors |
+
+## Examples
+
+```bash
+# Process all queues with defaults
+wheels jobs work
+
+# Process only mailer and notification queues
+wheels jobs work --queue=mailers,notifications
+
+# Fast polling with a job limit
+wheels jobs work --interval=2 --max-jobs=500
+
+# Quiet mode for production
+wheels jobs work --queue=default --quiet
+```
+
+## Concurrency
+
+Run multiple worker processes for parallelism. Each worker independently claims jobs via optimistic locking (`UPDATE WHERE status='pending' AND id=:id`), so no job is processed twice.
+
+```bash
+# Terminal 1
+wheels jobs work --queue=mailers
+
+# Terminal 2
+wheels jobs work --queue=default,reports
+```
+
+## Behavior
+
+1. Each poll cycle, the worker calls the Wheels bridge to claim the next pending job
+2. If a job is found, it's marked as `processing` and executed
+3. On success, the job is marked `completed`; on failure, it's retried with exponential backoff or marked `failed`
+4. If no jobs are available, the worker sleeps for `--interval` seconds
+5. When a job completes successfully, the worker immediately checks for more work before sleeping
diff --git a/docs/3.1.0/guides/working-with-wheels/background-jobs.md b/docs/3.1.0/guides/working-with-wheels/background-jobs.md
diff --git a/docs/3.1.0/guides/working-with-wheels/dependency-injection.md b/docs/3.1.0/guides/working-with-wheels/dependency-injection.md
