docs(jobs): one concurrency story (work=1, supervisor=2, recommend 2) + doctor cadence (#2796)

Worker-concurrency guidance was three-way inconsistent: guides said 4,
snippets said 2, real defaults are work=1 / supervisor=2. The deployment
guide now states both defaults once with a scale note (why not 1: subagent
starvation per #2782; why not more: DB-connection cost), and every guide
example + the CLI help align to the snippets' --concurrency 2 baseline.

Doctor cadence reconciled explicitly: heartbeat=daily
(operational-disciplines Discipline 4), deep pass=weekly (cron-schedule),
each doc cross-referencing the other. llms bundles regenerated.

Fixes #2796

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/guides/cron-schedule.md

@@ -41,7 +41,9 @@ fixed. You wake up and the brain is smarter than when you went to sleep.
 # Calendar sync — Sundays at 10 AM
 0 10 * * 0 cd /path/to/calendar-sync && node calendar-sync.mjs --start $(date -v-7d +%Y-%m-%d) --end $(date +%Y-%m-%d)
 
-# Brain health — weekly Mondays at 6 AM
+# Brain health — weekly DEEP pass, Mondays at 6 AM (doctor + embed backfill).
+# This complements — does not replace — the DAILY `gbrain doctor` heartbeat
+# from operational-disciplines.md Discipline 4: heartbeat=daily, deep pass=weekly.
 0 6 * * 1 gbrain doctor --json >> /tmp/gbrain-health.log 2>&1 && gbrain embed --stale
 
 # Dream cycle — nightly at 2 AM

docs/guides/minions-deployment.md

@@ -26,11 +26,25 @@ with exponential backoff (1s → 60s cap), emits lifecycle events to an
 audit file, and drains gracefully on SIGTERM (35s worker-drain window
 before SIGKILL). Exit codes are documented so agents can branch on them.
 
+**Concurrency defaults (single source of truth):**
+
+| Command | Default | Flag / env |
+|---|---|---|
+| `gbrain jobs work` | **1** | `--concurrency N` / `GBRAIN_WORKER_CONCURRENCY` |
+| `gbrain jobs supervisor` | **2** | `--concurrency N` (passed through to the worker) |
+
+Every snippet in this guide (systemd, Fly, Procfile) pins `--concurrency 2`
+explicitly — the recommended baseline. Why not 1: at concurrency 1 a job that
+submits and waits on its own subagent job (e.g. an autopilot cycle) can never
+have that subagent claimed — the single slot is already occupied (#2782). Why
+not more: each slot holds a DB connection and can fan out an LLM subagent, so
+scale to 4 only when throughput demands it and your Postgres pool has headroom.
+
 **Typical commands:**
 
 ```bash
 # Start in the foreground (blocks; Ctrl-C to stop).
-gbrain jobs supervisor --concurrency 4
+gbrain jobs supervisor --concurrency 2
 
 # Start detached — returns {"event":"started","supervisor_pid":…} on stdout.
 gbrain jobs supervisor start --detach --json
@@ -66,10 +80,10 @@ isn't:
 ```bash
 # Full concurrency, low priority. Propagates to the spawned worker and its
 # children (shell jobs, subagents) via OS niceness inheritance.
-gbrain jobs supervisor --concurrency 4 --nice 10
+gbrain jobs supervisor --concurrency 2 --nice 10
 
 # Equivalent for a bare worker, or set it durably in the environment.
-GBRAIN_NICE=10 gbrain jobs work --concurrency 4
+GBRAIN_NICE=10 gbrain jobs work --concurrency 2
 ```
 
 `--nice` takes a POSIX value from `-20` (highest priority) to `19`

docs/guides/operational-disciplines.md

@@ -57,6 +57,9 @@ on daily_schedule("09:00"):
     # Checks: database connectivity, embedding health, sync status,
     # page count, stale pages, broken links
     # If doctor reports issues, fix them before doing anything else.
+    # Cadence: this daily heartbeat is intentional alongside the WEEKLY
+    # deep maintenance pass (doctor + embed --stale) in cron-schedule.md —
+    # heartbeat=daily, deep pass=weekly.
 
 # DISCIPLINE 5: Nightly Dream Cycle
 on nightly_schedule("02:00"):

docs/guides/queue-operations-runbook.md

@@ -98,7 +98,9 @@ If the list is empty AND your submissions keep piling up, no worker is
 claiming. Start one:
 
 ```bash
-GBRAIN_ALLOW_SHELL_JOBS=1 gbrain jobs work --concurrency 4
+# Bare default is --concurrency 1, which starves jobs that wait on their own
+# subagent jobs — use 2 (the supervisor's default; see minions-deployment.md).
+GBRAIN_ALLOW_SHELL_JOBS=1 gbrain jobs work --concurrency 2
 ```
 
 ## Follow-ups tracked for v0.20+

llms-full.txt

@@ -2910,7 +2910,9 @@ fixed. You wake up and the brain is smarter than when you went to sleep.
 # Calendar sync — Sundays at 10 AM
 0 10 * * 0 cd /path/to/calendar-sync && node calendar-sync.mjs --start $(date -v-7d +%Y-%m-%d) --end $(date +%Y-%m-%d)
 
-# Brain health — weekly Mondays at 6 AM
+# Brain health — weekly DEEP pass, Mondays at 6 AM (doctor + embed backfill).
+# This complements — does not replace — the DAILY `gbrain doctor` heartbeat
+# from operational-disciplines.md Discipline 4: heartbeat=daily, deep pass=weekly.
 0 6 * * 1 gbrain doctor --json >> /tmp/gbrain-health.log 2>&1 && gbrain embed --stale
 
 # Dream cycle — nightly at 2 AM

src/commands/jobs.ts

@@ -253,7 +253,7 @@ USAGE
       3  PID file unwritable (permission / path error)
 
     EXAMPLES
-      gbrain jobs supervisor --concurrency 4         # foreground (Ctrl-C stops)
+      gbrain jobs supervisor --concurrency 2         # foreground (Ctrl-C stops; 2 is the default)
       gbrain jobs supervisor start --detach --json   # agent-friendly: fork + return JSON
       gbrain jobs supervisor status --json           # machine-readable health check
       gbrain jobs supervisor stop                    # graceful stop