@yemi33/minions 0.1.2364 → 0.1.2365

package/dashboard.js

@@ -15156,13 +15156,17 @@ if (require.main === module) {
   // engine reads, port binding) is captured rather than dying silently.
   _installCrashHandlers();
 
-  // Every copilot the dashboard spawns — Command Center, doc-chat, and the CC
-  // worker pool (`copilot --acp`) — inherits this process's COPILOT_HOME. Point
-  // it at the seeded, MCP-filtered home so those `direct:true` copilot calls
-  // load the filtered config instead of the operator's full `~/.copilot` stack
-  // (which would pop a Microsoft auth window per call). Mirrors the engine's
-  // boot-time set. See shared.ensureAgentCopilotHome. Fail-open.
-  try { process.env.COPILOT_HOME = shared.ensureAgentCopilotHome(MINIONS_DIR, CONFIG?.engine); } catch {}
+  // Deliberately do NOT set process.env.COPILOT_HOME here. Command Center,
+  // doc-chat, and the CC worker pool (`copilot --acp`) all spawn `copilot`
+  // as this process's children, so they should inherit the operator's real
+  // `~/.copilot` home (including their model preference in settings.json)
+  // exactly like an interactive `copilot` CLI session would — that's the
+  // documented CLI contract. An earlier revision forced these onto an
+  // isolated, MCP-filtered home to dodge MCP-server auth popups, but that
+  // broke CC's settings inheritance and reintroduced a staleness/reseed bug;
+  // reverted (W-mre75l6x00024f49). Per-dispatch agent isolation is unaffected
+  // — the engine process still seeds its own COPILOT_HOME at boot and
+  // re-stamps it per spawn via `_applyAgentCopilotHome` (engine.js).
 
   // Kick off first npm check on startup, then re-check every 4 hours.
   // Guarded here so that requiring dashboard as a module (unit tests, _withDashServer)

package/docs/README.md

@@ -7,14 +7,28 @@ A navigable index of every Markdown file under `docs/`. Entries are grouped by a
 Hands-on stories and distribution guides for people running or evaluating Minions.
 
 - [blog-first-successful-dispatch.md](blog-first-successful-dispatch.md) — Narrative walkthrough of the first end-to-end agent dispatch and the seven failed spawn attempts that preceded it.
-- [distribution.md](distribution.md) — How Minions is published (this repo: `@opg-microsoft/minions` to GitHub Packages; paired peer `yemi33/minions` to npm) and the bidirectional sync contract — automated opg → yemi33 backport workflow + manual yemi33 → opg sync PRs.
+- [documentation-audit-2026-07-09.md](documentation-audit-2026-07-09.md) — Verified user-facing documentation audit covering runtime, CLI, storage, routing, and broken-link corrections.
+- [distribution.md](distribution.md) — How Minions is published (this repo: `@opg-microsoft/minions` to GitHub Packages; paired peer `@yemi33/minions` to npm) and the bidirectional sync contract — automated opg → yemi33 backport workflow + manual yemi33 → opg sync PRs.
+- [onboarding.md](onboarding.md) — Condensed first-30-minutes walkthrough for a new operator.
+- [tutorials/README.md](tutorials/README.md) — Progressive tutorial track from installation through advanced automation and operations.
+
+### Tutorial track
+
+- [tutorials/01-install-and-connect.md](tutorials/01-install-and-connect.md) — Install Minions, verify a runtime, link a project, and start the dashboard.
+- [tutorials/02-first-task.md](tutorials/02-first-task.md) — Dispatch and inspect a bounded first task.
+- [tutorials/03-plan-driven-feature.md](tutorials/03-plan-driven-feature.md) — Review, approve, execute, and verify a dependency-aware plan.
+- [tutorials/04-runtimes-and-harness.md](tutorials/04-runtimes-and-harness.md) — Select runtimes and verify project skill, command, and MCP propagation.
+- [tutorials/05-schedules-and-watches.md](tutorials/05-schedules-and-watches.md) — Combine time-based schedules with state-based watches.
+- [tutorials/06-managed-services.md](tutorials/06-managed-services.md) — Leave an engine-owned development service running with health checks.
+- [tutorials/07-cross-repo-plan.md](tutorials/07-cross-repo-plan.md) — Coordinate one plan across multiple linked repositories.
+- [tutorials/08-operations-and-recovery.md](tutorials/08-operations-and-recovery.md) — Diagnose pending, failed, orphaned, and stopped work safely.
 
 ## Contributor-facing
 
 Architecture, design proposals, and lifecycle references for people working on the engine, dashboard, or playbooks.
 
 - [branch-derivation.md](branch-derivation.md) — Engine-side branch fallback (`work/<wi-id>`) vs. agent-authored long form, the structured-vs-loose PR-pointer extractors, and the canonical PR-fix duplication incident.
-- [command-center.md](command-center.md) — Command Center (CC) chat panel: persistent Sonnet sessions, `--resume` semantics, system-prompt invalidation, and per-tab session storage.
+- [command-center.md](command-center.md) — Command Center (CC) chat panel: configured-runtime sessions, resume semantics, system-prompt invalidation, and per-tab session storage.
 - [specs/agent-rename.md](specs/agent-rename.md) — Design spec for **agent rename & name decoupling** — the prerequisite for the Role/Agent Library. Formalizes the stable opaque agent id, makes charters name-agnostic, and adds `POST /api/agents/rename` (display name + emoji). Feature-flagged (`agent-rename`) and fully backward-compatible.
 - [specs/agent-configurability.md](specs/agent-configurability.md) — Design spec for the user-configurable Role / Agent Library, feature-flagged behind `agent-library` and fully backward-compatible. Builds on `agent-rename.md`. Role = the reusable durable charter; agent = a thin instance (identity + variable expertise + role pointer). Phase 0 renames `skills`→`expertise`; Phase 1 exposes/edits role charters + per-agent expertise; Phase 2 adds role/agent CRUD with builtin delete-protection.
 - [completion-reports.md](completion-reports.md) — Canonical schema for the per-spawn completion JSON: trust nonce, `failure_class` enum, `noop` semantics, `retryable` / `needs_rerun` shape, and the artifacts array.
@@ -26,7 +40,7 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [cross-repo-plans.md](cross-repo-plans.md) — Cross-repo plans: a single plan whose work items ship into two or more configured projects — per-item `project` field, per-project work-item fan-out, and one verify work item per touched repo.
 - [dead-code-audit-retractions.md](dead-code-audit-retractions.md) — Retracted dead-code-audit findings (false positives) that future audits MUST read before re-citing.
 - [deprecated-process.md](deprecated-process.md) — Schema for `docs/deprecated.json` and the weekly `cleanup-deprecated` audit walk that retires entries past their removal signal.
-- [design-state-storage.md](design-state-storage.md) — Design proposal evaluating five database options for replacing Minions' file-based JSON state; recommends `node:sqlite` as the medium-term target (accepted; implementation tracked in CHANGELOG.md Phases 0–9).
+- [design-state-storage.md](design-state-storage.md) — Design proposal evaluating five database options for replacing Minions' file-based JSON state; recommends `node:sqlite` (accepted; implementation tracked in CHANGELOG.md Phases 0–10).
 - [harness-mode.md](harness-mode.md) — Tri-Agent Harness Mode (`harness_mode: "tri_agent"` on scheduled tasks): Planner → Generator → Evaluator loop that iterates a shared on-disk artifact until a rubric passes or the iteration cap fires.
 - [harness-propagation.md](harness-propagation.md) — How user-level and project-local harness assets (skills, slash-commands, MCP config, `CLAUDE.md` / `AGENTS.md`) propagate into an agent's worktree via `--add-dir`, the `harnessPropagateProjectLocal` flag, and the project-local-on-main worktree-visibility footgun.
 - [harness-transparency.md](harness-transparency.md) — The `harnessUsed` self-report contract: capture (agent reports the skills / MCPs / commands / docs it used) → ground (engine cross-checks against `_harnessPropagated` and annotates `grounded:true\|false`, never dropping) → surface (PR comment, final agent note, work-item modal).
@@ -54,7 +68,7 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [slim-ux/architecture-suggestions.md](slim-ux/architecture-suggestions.md) — Slim-UX follow-up architecture suggestions paired with `concepts.md`.
 - [team-memory.md](team-memory.md) — Per-agent memory layer (`knowledge/agents/<id>.md`) and the consolidation/routing rules that populate it from `notes/inbox/`.
 - [timeouts-and-liveness.md](timeouts-and-liveness.md) — What kills (or doesn't kill) a live tracked agent: the wall-clock vs steering kill invariants, spawn-phase watchdog gates, steering safety nets, and stale-orphan detection ladder.
-- [watches.md](watches.md) — Persistent monitoring jobs (`engine/watches.json`): target-type registry, conditions, follow-up actions, and the `watches.d/` plugin folder.
+- [watches.md](watches.md) — Persistent monitoring jobs: target-type registry, conditions, follow-up actions, and the `watches.d/` plugin folder.
 - [workspace-manifests.md](workspace-manifests.md) — Declarative per-agent permission scoping: `allowed_tools` / `allowed_repos` / `allowed_external_urls` / `memory_scope`, dispatch-time repo gate, and runtime `--allowedTools` narrowing.
 - [worktree-lifecycle.md](worktree-lifecycle.md) — Worktree pool recycling, the live-dispatch guard that prevents wiping an agent's unpushed work, the dirty/divergent quarantine path, and the Windows EPERM/EBUSY file-lock retry footgun.
 
@@ -62,15 +76,13 @@ Architecture, design proposals, and lifecycle references for people working on t
 
 Operational runbooks for engine operators and fleet maintainers.
 
-- [notes.md](notes.md) — Consolidated team knowledge: patterns, conventions, bugs, and build findings accumulated from agent inbox notes. Read by the engine and injected into agent prompts as shared context.
 - [auto-discovery.md](auto-discovery.md) — Auto-discovery and execution pipeline: the per-tick orchestration loop and the four work-discovery sources.
 - [diagnostics-memory.md](diagnostics-memory.md) — Operator runbook for the in-process memory + perf observability surface: `/api/diagnostics/memory[/history]`, `/api/diagnostics/heap-snapshot` guard-token capture, `MEMORY_BASELINE` log emissions, `--cpu-prof`/`--heap-prof` capture, and the `test/perf/soak.test.js` heap-growth regression gate.
 - [diagnostics-crash-reports.md](diagnostics-crash-reports.md) — Proactive Node crash-diagnostics reports (`--report-on-fatalerror --report-on-signal --diagnostic-dir=...`) for the engine.js process on Windows: where reports land, config/opt-out, and retention.
 - [engine-restart.md](engine-restart.md) — How agents survive an engine restart: state persistence, the 20-minute startup grace period, and orphan reattachment via PID files and `live-output.log`.
 - [human-vs-automated.md](human-vs-automated.md) — Quick reference table of which features humans start, run, decide, and recover, and the two human approval gates.
 - [kb-sweep.md](kb-sweep.md) — Knowledge-base sweep runbook: how `engine/kb-sweep.js` consolidates `notes/inbox/` into `knowledge/` and survives `minions restart`.
-- [onboarding.md](onboarding.md) — First-30-minutes walkthrough for a new operator: install, init, dispatch a first work item, watch it land.
-- [preflight.md](preflight.md) — `minions doctor` and the lighter per-CLI `minions preflight` checks: what each non-self-explanatory row (permission bypass, runtime detection, drive-root, etc.) is asserting.
+- [preflight.md](preflight.md) — `minions doctor` and the internal initialization/startup preflight: what each non-self-explanatory row (permission bypass, runtime detection, drive-root, etc.) is asserting.
 - [security.md](security.md) — Threat model: single-user/loopback deployment assumptions, dashboard Origin gate, data-flow trust boundaries, secret handling, and known residual risks (CSRF sweep, prompt injection, log-redactor audit).
 
 ---

package/docs/command-center.md

@@ -1,8 +1,8 @@
 # Command Center
 
-The Command Center (CC) is the dashboard's conversational chat panel. It opens from the **CC** button in the top-right header and lets you drive the engine — dispatching work items, saving notes, approving plans, and asking questions about minions state — through a persistent Claude/Copilot session with full repo awareness.
+The Command Center (CC) is the dashboard's conversational chat panel. It opens from the **CC** button in the top-right header and lets you drive the engine — dispatching work items, saving notes, approving plans, and asking questions about Minions state — through a persistent session on the configured CC runtime.
 
-CC is intentionally a thin wrapper around the runtime CLI: state changes happen via `Bash`-tool `curl` calls to the dashboard's own REST API, not via parsed delimiter blocks. The end-to-end flow is `dashboard/js/command-center.js` `_ccDoSend()` → `POST /api/command-center` (or `/api/command-center/stream`) in `dashboard.js` (`handleCommandCenter`) → `engine/llm.js` `callLLM({ direct: true })` → claude/copilot CLI session persisted in `engine/cc-sessions.json`. Per-turn API mutations are correlated via the `X-CC-Turn-Id` header and surfaced as standalone `role='action'` chips rendered outside the assistant bubble (`_ccActionResultLine` + `addMsg('action', ...)`).
+CC is intentionally a thin wrapper around the runtime CLI: state changes happen via tool-driven calls to the dashboard's own REST API, not via parsed delimiter blocks. The end-to-end flow is `dashboard/js/command-center.js` `_ccDoSend()` → `POST /api/command-center` (or `/api/command-center/stream`) in `dashboard.js` (`handleCommandCenter`) → `engine/llm.js` `callLLM({ direct: true })` → runtime session persisted in `engine/state.db` (`cc_sessions`; `engine/cc-sessions.json` is a passive mirror). Per-turn API mutations are correlated via the `X-CC-Turn-Id` header and surfaced as standalone `role='action'` chips rendered outside the assistant bubble (`_ccActionResultLine` + `addMsg('action', ...)`).
 
 For canonical detail (system prompt, session lifecycle, turn-ID surfacing pipeline, doc-chat integration, and CC API contract), read [`CLAUDE.md`](../CLAUDE.md) — see the **CC API Contract** and **Sessions** sections — and the source in [`dashboard/js/command-center.js`](../dashboard/js/command-center.js), [`dashboard.js`](../dashboard.js) (`handleCommandCenter`), and [`prompts/cc-system.md`](../prompts/cc-system.md).
 

package/docs/constants.md

@@ -6,7 +6,7 @@ All cross-cutting status / type / condition values are defined in [`engine/share
 WI_STATUS = { PENDING, DISPATCHED, DONE, FAILED, PAUSED, QUEUED, DECOMPOSED, CANCELLED }
 DONE_STATUSES = Set([WI_STATUS.DONE, 'in-pr', 'implemented', 'complete'])  // legacy aliases on read only
 WORK_TYPE = { IMPLEMENT, IMPLEMENT_LARGE, FIX, REVIEW, VERIFY, PLAN, PLAN_TO_PRD,
-              DECOMPOSE, MEETING, EXPLORE, ASK, TEST, DOCS, SETUP }
+              DECOMPOSE, MEETING, EXPLORE, ASK, TEST, DOCS, SETUP, BUILD_FIX_COMPLEX }
 PLAN_STATUS = { ACTIVE, AWAITING_APPROVAL, APPROVED, PAUSED, REJECTED, COMPLETED, REVISION_REQUESTED }
 PRD_ITEM_STATUS = { MISSING, UPDATED, DONE };  PRD_MATERIALIZABLE = Set([MISSING, UPDATED])
 PR_STATUS = { ACTIVE, MERGED, ABANDONED, CLOSED, LINKED };  PR_POLLABLE_STATUSES = Set([ACTIVE, LINKED])

package/docs/documentation-audit-2026-07-09.md

@@ -0,0 +1,43 @@
+# Documentation Audit: 2026-07-09
+
+Scope: `README.md`, `CLAUDE.md`, `docs/**/*.md`, `playbooks/*.md`,
+`agents/*/charter.md`, and `prompts/*.md`.
+
+The audit prioritized user-facing claims that can cause an operator to install
+the wrong runtime, use a nonexistent command, inspect a passive state mirror as
+canonical data, or misunderstand routing and dashboard behavior.
+
+## Corrected findings
+
+| Stale claim | Correction | Source of truth |
+|---|---|---|
+| Node.js 18+ was sufficient | Node.js 22.5+ is required for `node:sqlite` | `package.json:68` |
+| Agent dispatch was described as Claude-only | Copilot is the default fleet runtime; Claude and Codex remain supported | `engine/shared.js:3520`, `engine/runtimes/index.js` |
+| Root and per-project JSON trackers were described as primary state | Migrated runtime state is primary in `engine/state.db`; JSON trackers are passive mirrors | `engine/dispatch-store.js:49-68`, `CLAUDE.md` "State storage" |
+| `minions preflight` was documented as a public command | `minions doctor` is public; lighter checks run internally during initialization and startup | `bin/minions.js:1207-1264`, `engine/cli.js:232-255` |
+| Git repository host default was documented as ADO | The fallback host is GitHub | `engine/projects.js:504`, `engine/projects.js:564` |
+| `WORK_TYPE` documentation omitted complex build fixes | Added `BUILD_FIX_COMPLEX` | `engine/shared.js:4370-4396`, `routing.md:10-28` |
+| Command Center sessions were described as a JSON-file store | Sessions are stored in SQLite; the JSON file is a mirror | `engine/shared.js:1830`, `engine/db/migrations/011-remaining-state.js` |
+| Watches were described as checking every three ticks and persisting to JSON | The default cadence is 18 ticks; persistence routes through the SQL watch store | `engine/shared.js` `watchPollEvery`, `engine/watches-store.js` |
+| Two local documentation links targeted files that are not shipped | Removed the runtime `notes.md` link and the stale managed-spawn plan link | `docs/README.md`, `docs/managed-spawn.md` |
+
+## New tutorial coverage
+
+The tutorial track under [`docs/tutorials/`](tutorials/README.md) now covers:
+
+1. installation and project linking;
+2. a first bounded dispatch;
+3. plan-to-PRD implementation and verification;
+4. runtime and harness configuration;
+5. schedules and watches;
+6. managed development services;
+7. cross-repository plans;
+8. operations and recovery.
+
+## Follow-up policy
+
+Reference docs remain intentionally detailed. Tutorials should link to those
+references rather than duplicate full schemas. Future sweeps should continue to
+verify CLI examples against `bin/minions.js` and `engine/cli.js`, dashboard
+routes against `dashboard.js`, work types against `routing.md`, and state
+storage claims against the SQL store modules.

package/docs/engine-restart.md

@@ -10,8 +10,8 @@ When the engine restarts, it loses its in-memory process handles (`activeProcess
 
 | State | Storage | Survives Restart |
 |-------|---------|-----------------|
-| Dispatch queue (pending/active/completed) | `engine/dispatch.json` | Yes |
-| Agent status (working/idle/error) | Derived from `engine/dispatch.json` | Yes |
+| Dispatch queue (pending/active/completed) | `engine/state.db` (`dispatches`; `engine/dispatch.json` is a passive mirror) | Yes |
+| Agent status (working/idle/error) | Derived from `engine/state.db` | Yes |
 | Agent live output | `agents/*/live-output.log` | Yes (mtime used for orphan cleanup) |
 | Process handles (`ChildProcess`) | In-memory Map | **No** |
 | Cooldown timestamps | In-memory Map | **No** (repopulated from `engine/cooldowns.json`) |

package/docs/managed-spawn.md

@@ -1,7 +1,7 @@
 # Managed-spawn primitive
 
 > Engine-owned long-running services with sidecar declaration, healthcheck-gated dispatch SUCCESS, and dashboard discovery.
-> Plan: [`plans/plan-w-mp7k1r760003b5dd-2026-05-15.md`](../plans/plan-w-mp7k1r760003b5dd-2026-05-15.md) · Module: [`engine/managed-spawn.js`](../engine/managed-spawn.js) · Dashboard panel: `/engine` → "Managed Processes".
+> Module: [`engine/managed-spawn.js`](../engine/managed-spawn.js) · Dashboard panel: `/engine` → "Managed Processes".
 
 ## Why this exists
 

package/docs/onboarding.md

@@ -1,246 +1,124 @@
-# Minions Onboarding — Your First 30 Minutes
+# Minions Onboarding: Your First 30 Minutes
 
-A fast, hands-on walkthrough for new contributors. Follow the eight steps below in order. Each step is independent enough that you can stop, take a break, and resume without losing state.
+This condensed operator walkthrough gets one repository from installation to a
+completed first dispatch. For deeper, progressive exercises, use the
+[full tutorial track](tutorials/README.md).
 
-> **Prerequisites:** Node.js 22.5+ (required by `package.json#engines` for the `node:sqlite` runtime backing the state DB), Git, and a working Claude Code CLI (`npm install -g @anthropic-ai/claude-code`) authenticated against your Anthropic API key or Claude Max subscription. See the top-level [README.md](../README.md#prerequisites) for the full list.
+## Prerequisites
 
-> **Screenshots:** This walkthrough is intentionally text-only on the first pass. If you want annotated dashboard screenshots, run the [`capture-demos`](../README.md#dashboard) skill after Step 5; it drives Playwright over the running dashboard and writes images you can drop alongside each section.
+- Node.js 22.5 or newer
+- Git
+- One supported runtime CLI with working authentication
+- A local Git repository you are comfortable allowing an agent to change
 
----
+Minions defaults to GitHub Copilot CLI. Claude Code and Codex are also
+supported.
 
-## Step 1 — Clone the repo
-
-You only need to clone if you intend to modify Minions itself. End users normally `npm install -g @yemi33/minions` instead, but a checkout is the right starting point for contributors.
-
-```bash
-git clone https://github.com/yemi33/minions.git ~/minions-dev
-cd ~/minions-dev
-npm install     # installs dev tooling (Playwright, ESLint) only; the engine itself has zero runtime deps (Node built-ins)
-```
-
-You should now have:
-
-- `engine.js` — the orchestrator entry point
-- `dashboard.js` — the HTTP/UI server (binds `:7331`)
-- `minions.js` — the CLI shim that maps `minions <cmd>` to the right script
-- `playbooks/`, `agents/`, `prompts/`, `docs/` — content the engine renders into agent prompts
-- `test/` — `unit.test.js`, the integration suite, and Playwright specs
-
-If you cloned to somewhere other than `~/.minions`, the CLI will still work — `minions init` writes runtime state under `~/.minions/` regardless of where the source lives. The `node` scripts under your checkout will use the checkout as the runtime root when invoked directly (e.g. `node ./engine.js start`).
-
----
-
-## Step 2 — Run `minions doctor`
-
-`minions doctor` runs the same preflight checks the engine runs at startup. It is safe to run any time and never mutates state.
+## 1. Install and initialize
 
 ```bash
+npm install -g @yemi33/minions
+minions init
 minions doctor
 ```
 
-A healthy Mac/Linux run looks roughly like:
+Resolve every doctor `FAIL` before continuing. To select another runtime:
 
+```bash
+minions config set-cli claude
+# or: minions config set-cli codex
 ```
-  Runtime:
-
-    ✓ node: v20.11.1 (>= 18 required)
-    ✓ git: git version 2.45.0
-    ✓ claude CLI: 1.0.x found on PATH
-
-  Authentication:
-
-    ✓ ANTHROPIC_API_KEY: set
-    ✓ gh auth: logged in as <you>
 
-  Filesystem:
+`minions init` creates `~/.minions/`. Primary migrated runtime state lives in
+`engine/state.db` (SQLite, WAL mode). Files such as `engine/dispatch.json` and
+`engine/metrics.json` are passive diagnostic mirrors; `engine/control.json`
+remains a live JSON control file.
 
-    ✓ ~/.minions writable
-    ✓ engine/ writable
+## 2. Link a project
 
-  All checks passed.
+```bash
+minions add C:\code\sample-project
+minions list
 ```
 
-What to look for:
-
-- `✓` (green) means OK. `!` is a warning the engine can usually work around. `✗` (critical) will block dispatch — fix it before continuing.
-- The most common failure is `claude CLI: not found` — re-install with `npm install -g @anthropic-ai/claude-code` and re-run.
-- On Windows, runtime resolution prefers native `claude.exe` over the POSIX bash shim; if you see runtime-resolution warnings, `gh auth status` and `where.exe claude` are good first stops.
-
-If `doctor` reports any `✗`, stop and resolve it. The remaining steps assume a clean preflight.
-
----
+Use the corresponding local path on macOS or Linux. Confirm the detected
+repository host, remote, main branch, and project description. Write the
+description as a responsibility, such as "Billing API and webhook ingestion,"
+because agents use it when routing project-agnostic work.
 
-## Step 3 — Bootstrap state with `minions init`
-
-`minions init` scaffolds `~/.minions/` with a default config, five agent charters, default playbooks, an empty knowledge base, and the engine state files.
+## 3. Start the engine and dashboard
 
 ```bash
-minions init
+minions start --open
 ```
 
-After init you will have (under `~/.minions/`):
+`start` is idempotent and starts both services. If the browser does not open:
 
-- `config.json` — projects, agents, schedules
-- `agents/<name>/charter.md` — the personality + boundaries for each of the five default agents (`ripley`, `dallas`, `lambert`, `rebecca`, `ralph`)
-- `engine/dispatch.json`, `engine/control.json`, `engine/metrics.json` — empty queues, ready for first dispatch
-- `pinned.md`, `notes.md` — empty team-memory surfaces
-- `playbooks/`, `prompts/`, `routing.md` — agent prompt scaffolding
+```bash
+minions dash
+```
 
-`init` is safe to re-run; existing customizations to `config.json`, charters, notes, knowledge, and routing are preserved. To force overwrites after a major version bump, use `minions init --force`.
+The dashboard normally binds to port 7331 and records the actual port if it has
+to scan for a free one.
 
----
+The main pages are **Home**, **Work**, **PRs**, **Plans**, **Inbox**, **Tools**,
+**Schedule**, **Watches**, **Pipelines**, **Meetings**, **QA**, and **Engine**.
+Settings are available from the application controls.
 
-## Step 4 — Link your first project with `minions add`
+## 4. Dispatch one bounded task
 
-A "project" tells Minions which repo to discover work for and where to spawn worktrees. The CLI auto-detects host (GitHub/ADO), org, repo name, and main branch from the directory's git remote.
+Use a small task with an obvious result:
 
 ```bash
-minions add ~/code/your-repo
+minions work "Add a Development section to README.md that names the existing test command"
+minions dispatch
+minions queue
 ```
 
-You will be prompted to confirm or override the auto-detected fields, plus a one-line description. The description is **important** — agents read it during routing to decide whether a work item belongs to your repo. Keep it specific (e.g. "Internal billing API and webhook ingestion service") rather than generic ("Backend code").
+For explicit project selection, create the item from **Work** or Command Center
+and choose your project rather than Auto.
 
-After `minions add` returns, `~/.minions/config.json` has a new `projects[]` entry, and `~/.minions/projects/<name>/` holds the per-project `work-items.json` + `pull-requests.json` trackers.
+Watch the assigned agent from **Home**, then open its **Live Output**. A
+mutating dispatch receives an isolated worktree, the matching playbook, project
+context, and the configured runtime.
 
-To link several at once interactively, run `minions scan` (default: scans `~` to depth 3 for git repos and lets you multi-select).
-
----
-
-## Step 5 — Start engine + dashboard with `minions restart`
-
-`minions restart` starts (or restarts) both the engine daemon and the dashboard server. Use `restart` rather than `start` whenever you have edited engine code or playbooks — it ensures the daemon picks up your changes.
+## 5. Inspect completion
 
 ```bash
-minions restart
+minions status
+minions queue
 ```
 
-You should see logs like `Engine started (pid=…)` and `Dashboard listening on http://localhost:7331`. Open the dashboard:
+Open the item on **Work** to inspect its output, branch, artifacts, and linked
+pull request. If the item remains pending, read `_pendingReason`. If it fails,
+inspect the failure class before retrying:
 
 ```bash
-minions dash    # opens http://localhost:7331 in your default browser
+minions wi show <work-item-id>
+minions wi retry <work-item-id>
 ```
 
-A quick tour of the panels you will use most often during onboarding:
-
-| Panel | What it shows | When to use it |
-|---|---|---|
-| **Projects bar** (top) | All linked projects with descriptions | Confirm Step 4 worked |
-| **Minions Members** | Five agent cards with status, current task, last result | Watch dispatches happen in real time |
-| **Live Output** (per agent) | Streaming `live-output.log` | Tail an agent while it runs — refreshes every 3 s |
-| **Command Center** (CC button, top-right) | Conversational chat with Claude over your full Minions state | Ask questions, queue work, draft plans |
-| **Work Items** | Paginated table of all work, filterable by project/status | Inspect / retry / archive |
-| **Plans & PRD** | Plan markdown drafts and approved PRDs | Approve, discuss-and-revise, or reject plans |
-| **Pull Requests** | Cached PR status (build, review, merge) | Track the PRs your agents create |
-| **Engine** | Dispatch queue, engine log, LLM call performance | Diagnose timing / token issues |
-
-The engine ticks every 10 seconds. If the dashboard says "Engine: stopped", run `minions restart` again — the dashboard auto-restarts a dead engine on its next health check, but a manual restart is faster.
-
----
-
-## Step 6 — Your first dispatch via the Command Center
+Correct authentication, configuration, workspace-manifest, or checkout
+failures before retrying.
 
-The fastest way to give Minions a task is the Command Center (CC).
+## 6. Try a plan
 
-1. Click the **CC** button in the top-right of the dashboard.
-2. In the slide-out chat, type a one-line description, e.g.:
-   ```
-   Add a brief comment to README.md explaining what minions doctor does
-   ```
-3. CC will propose an action (usually `POST /api/work-items` or `POST /api/plan`). Confirm.
+In Command Center:
 
-Within one tick (≤10 s), the engine will:
-
-1. Pick an idle agent that matches the work type (per `routing.md`).
-2. Create a git worktree for that agent under `<your-repo>/.worktrees/<work-item-id>/`.
-3. Render the appropriate playbook (`playbooks/implement.md` for an implement task) with your project context, charter, pinned notes, and recent team notes.
-4. Spawn `engine/spawn-agent.js`, which invokes the Claude CLI with the rendered prompt.
-
-Watch the **Minions Members** card for that agent flip to "working", and click into the **Live Output** tab to tail the streaming agent log.
-
-You can do the same thing from the CLI: `minions work "Add a brief comment to README.md…"`.
-
----
-
-## Step 7 — Your first plan via `/plan`
-
-For multi-step work, use a plan instead of a one-shot work item. In the Command Center, type:
-
-```
-/plan Audit our README and propose three concrete improvements with examples
+```text
+/plan Add a health endpoint, tests, and operator documentation to SampleProject.
+Keep the changes as separately testable items with explicit dependencies.
 ```
 
-CC will queue a `plan` work item. The plan agent writes a markdown draft to `~/.minions/plans/<project>-<date>.md`, then chains automatically to a `plan-to-prd` agent that produces a structured PRD JSON in `~/.minions/prd/`. The PRD lands with `status: "awaiting-approval"`.
-
-Open **Plans & PRD** in the dashboard. You will see the new plan with three buttons:
-
-- **Approve** — materializes one work item per PRD entry, with `depends_on` honored.
-- **Discuss & Revise** — opens a doc-chat modal where you can iterate on the plan with Claude.
-- **Reject** — closes the plan with a reason.
-
-After approving, agents start picking up the materialized work items on the next tick. When all PRD items complete, the engine auto-dispatches a `verify` task that builds + tests the changes and writes a manual testing guide. Archiving (after verify) is a manual dashboard action — see [docs/plan-lifecycle.md](plan-lifecycle.md) for the full pipeline.
-
----
-
-## Step 8 — Your first PR review
-
-When an `implement` agent finishes a work item, it pushes a branch and opens a PR. The engine polls PR status every `prPollStatusEvery` ticks (≈12 minutes by default) and dispatches a `review` agent automatically.
-
-To watch the cycle end-to-end on your first task:
-
-1. Open **Pull Requests** in the dashboard. Find the PR your agent just opened.
-2. Wait for the next status poll (or run `minions dispatch` to wake the daemon immediately). The PR's `reviewStatus` will flip from `pending` to `waiting`, then a review agent will spawn.
-3. Click the agent card to watch the live review. The reviewer reads the diff, runs targeted checks, then posts a comment that starts with `VERDICT: APPROVE` or `VERDICT: REQUEST_CHANGES`.
-4. If the verdict is `REQUEST_CHANGES`, the engine queues a `fix` task for the original author with a feedback note. The cycle repeats until approved or capped by the eval-loop config.
-
-You can also trigger reviews manually by commenting on the PR — see [docs/pr-review-fix-loop.md](pr-review-fix-loop.md).
-
-> **Note on self-approval:** Minions agents share a single GitHub identity, so `gh pr review --approve` is blocked by GitHub's self-approval rule. Reviewers post a `VERDICT:` **comment** instead, and the engine treats that comment as authoritative.
-
----
-
-## Debugging — Where to look when something goes wrong
-
-When an agent gets stuck, hangs, or produces unexpected output, these files are your first stops. They live under `~/.minions/` (or wherever your runtime root is).
-
-| File | What it tells you |
-|---|---|
-| `agents/<id>/live-output.log` | Real-time streaming output from the agent's Claude CLI session — same content the dashboard's Live Output tab shows. Tail this with `tail -f ~/.minions/agents/<id>/live-output.log`. |
-| `agents/<id>/last-prompt.txt` | The most recent rendered prompt the agent received (playbook + system prompt + injected context). Inspect this to see exactly what the agent was asked to do, including pinned notes, team notes, charter, and dispatch context. If your install does not surface this file yet, the live equivalents are `engine/tmp/prompt-<dispatch-id>.md` (while the agent is running) and `engine/contexts/<dispatch-id>.md` (when the prompt was sidecarred because it exceeded `maxDispatchPromptBytes`). |
-| `agents/<id>/output.log` | The agent's final output after completion (post-mortem read; `live-output.log` is the during-run read). |
-| `agents/<id>/history.md` | Last 20 tasks for that agent with timestamps, results, projects, and branches. Useful when a single agent is misbehaving over multiple tasks. |
-| `engine/log.json` | Audit trail of engine actions (last 2500 entries, rotated to 2000). Filter with `jq` for a specific agent or work item. |
-| `engine/dispatch.json` | Pending / active / completed dispatch queue. If an agent appears idle on the dashboard but the queue says `active`, the engine likely lost process tracking — try `minions restart`. |
-| `engine/metrics.json` | Per-agent token usage, runtime, error counts. Useful for spotting agents that are silently retrying. |
-| `notes/inbox/` | Raw findings agents drop after each task. Look here for the latest learnings before the consolidator merges them into `notes.md`. |
-| `pinned.md` and `notes.md` | Team memory that gets injected into every agent prompt. If an agent keeps making the same mistake, pin a correction here. |
-
-Other quick debugging knobs:
-
-- `minions status` — text snapshot of agents, projects, dispatch queue, and quality metrics.
-- `minions queue` — focused view of the dispatch queue (pending, active, completed).
-- `minions kill` — kills all active agents and resets their dispatches to `pending`. Use when an agent is wedged.
-- `minions cleanup` — manually run the temp-file / worktree / zombie sweep that normally runs every 10 ticks.
-
-For deeper dives: [docs/engine-restart.md](engine-restart.md), [docs/auto-discovery.md](auto-discovery.md), and [docs/self-improvement.md](self-improvement.md).
-
----
-
-## What's next
-
-You have:
-
-- Linked a project, started the engine, opened the dashboard.
-- Dispatched a one-shot task via Command Center.
-- Authored a plan, approved it, and watched the PRD materialize into work items.
-- Watched an agent open and review a PR.
-- Located the files you need to debug a stuck agent.
-
-From here, sensible next reads are:
+Review the generated PRD on **Plans**. Use **Discuss & Revise** until its
+acceptance criteria and dependencies are concrete, then approve it. Approval
+materializes work items. When all items complete, Minions creates a verification
+item. Archiving remains a manual action after you review the final result.
 
-- [README.md](../README.md) — the full feature catalog and CLI reference.
-- [CLAUDE.md](../CLAUDE.md) — engineering conventions, tick cycle, locking rules. Read this before editing engine code.
-- [docs/plan-lifecycle.md](plan-lifecycle.md) — plan → PRD → implement → verify → archive in detail.
-- [docs/command-center.md](command-center.md) — full CC capabilities, including doc-chat and plan steering.
-- [docs/pr-review-fix-loop.md](pr-review-fix-loop.md) — how the review/fix cycle is bounded and steered.
+## Where to go next
 
-Welcome to the team.
+- [Tutorial 2: Ship Your First Task](tutorials/02-first-task.md)
+- [Tutorial 3: Build a Feature from a Plan](tutorials/03-plan-driven-feature.md)
+- [Tutorial 8: Operate and Recover Minions](tutorials/08-operations-and-recovery.md)
+- [Plan Lifecycle](plan-lifecycle.md)
+- [Command Center](command-center.md)

package/docs/preflight.md

@@ -1,8 +1,9 @@
 # Preflight & Doctor
 
-`minions doctor` (and the lighter `minions preflight` that runs on every CLI
-invocation) inspects the local environment for the conditions Minions needs
-to dispatch agents reliably. Every row is one of: `OK`, `WARN`, `FAIL`.
+`minions doctor` is the user-facing environment check. A lighter internal
+preflight also runs during `minions init` and engine startup. Together they
+inspect the conditions Minions needs to dispatch agents reliably. Every row is
+one of: `OK`, `WARN`, `FAIL`.
 
 This page documents the rows that are not self-explanatory from their message.
 

package/docs/tutorials/01-install-and-connect.md

@@ -0,0 +1,87 @@
+# Tutorial 1: Install and Connect a Project
+
+You will install Minions, verify the default Copilot runtime, link one Git
+repository, and start the engine and dashboard.
+
+## Prerequisites
+
+- Node.js 22.5 or newer
+- Git
+- GitHub Copilot CLI, Claude Code, or Codex CLI with working authentication
+- A local Git repository with an `origin` remote
+
+Minions defaults to GitHub Copilot CLI. Install it if you have not selected a
+different runtime:
+
+```bash
+npm install -g @github/copilot
+```
+
+## 1. Install and initialize
+
+```bash
+npm install -g @yemi33/minions
+minions init
+```
+
+Initialization creates the operator home at `~/.minions/`, including agent
+charters, playbooks, routing, prompts, and the SQLite state database.
+
+## 2. Verify the host
+
+```bash
+minions doctor
+```
+
+Resolve every `FAIL` before dispatching. Warnings are non-blocking but should be
+read: a permission-flag warning can mean that the selected CLI will stop for an
+interactive prompt during a headless dispatch.
+
+To choose another runtime:
+
+```bash
+minions config set-cli claude
+# or
+minions config set-cli codex
+```
+
+Run `minions doctor` again after switching.
+
+## 3. Link a repository
+
+```bash
+minions add C:\code\sample-project
+```
+
+On macOS or Linux, use the corresponding path such as
+`~/code/sample-project`. Confirm the detected host, repository, main branch,
+and description. The description helps agents route project-agnostic work, so
+describe the repository's responsibility rather than its implementation
+language.
+
+Confirm the result:
+
+```bash
+minions list
+```
+
+## 4. Start Minions
+
+```bash
+minions start --open
+```
+
+`start` is idempotent and starts both the engine and dashboard. If browser
+launch is blocked, run `minions dash`.
+
+## Checkpoint
+
+```bash
+minions status
+```
+
+You should see the engine running, your project listed, and no failed
+dispatches. In the dashboard, verify that the project appears in the project
+picker and that the agent cards are idle.
+
+Next: [ship your first task](02-first-task.md).

package/docs/tutorials/02-first-task.md

@@ -0,0 +1,73 @@
+# Tutorial 2: Ship Your First Task
+
+You will queue a small documentation change, observe routing and live output,
+and inspect the resulting work item and pull request.
+
+## 1. Choose a bounded task
+
+Start with a task that has one clear result and a cheap validation step:
+
+```bash
+minions work "Add a short Development section to README.md that names the existing test command"
+```
+
+For precise project selection, use the dashboard's **Work** page or Command
+Center and select the linked project instead of Auto. A project-scoped task is
+better than auto-routing while learning the lifecycle.
+
+## 2. Wake and inspect the queue
+
+The engine checks for work on its normal tick. You can wake it immediately:
+
+```bash
+minions dispatch
+minions queue
+```
+
+The item normally moves from `pending` to `dispatched`. If it remains pending,
+open its detail view and read `_pendingReason`; common reasons are an unmet
+dependency, no available agent, cooldown, or concurrency limits.
+
+## 3. Follow the agent
+
+In the dashboard:
+
+1. Open **Home** and select the working agent.
+2. Watch **Live Output** for repository exploration, edits, and checks.
+3. Open **Work** and select the item to inspect its branch, output, and
+   artifacts.
+
+The engine chooses an agent from `routing.md`, creates an isolated worktree for
+mutating work, renders the work-type playbook, and invokes the configured
+runtime adapter.
+
+## 4. Inspect the outcome
+
+```bash
+minions status
+minions queue
+```
+
+A successful code-changing task should finish with a branch and pull request.
+If the runtime reports success without the required artifact, the work item can
+still be flagged for lifecycle follow-up.
+
+If the item fails, read its failure class and output before retrying:
+
+```bash
+minions wi show <work-item-id>
+minions wi retry <work-item-id>
+```
+
+Do not retry authentication, invalid configuration, or workspace-permission
+failures without correcting the cause first.
+
+## Checkpoint
+
+You have observed the full path:
+
+```text
+work item -> routing -> worktree -> runtime -> checks -> branch/PR -> completion
+```
+
+Next: [build a feature from a plan](03-plan-driven-feature.md).

package/docs/tutorials/03-plan-driven-feature.md

@@ -0,0 +1,73 @@
+# Tutorial 3: Build a Feature from a Plan
+
+Use a plan when the outcome spans several independently verifiable changes.
+You will create a plan, review its PRD, approve it, and follow dependency-aware
+implementation through verification.
+
+## 1. Draft the request
+
+Open Command Center and enter:
+
+```text
+/plan Add a health endpoint to SampleProject, document it, and add automated
+tests. Keep implementation, tests, and documentation as separate items with
+explicit dependencies.
+```
+
+The plan agent writes Markdown under `plans/`. The plan-to-PRD step then creates
+structured items under `prd/` with acceptance criteria and `depends_on`
+relationships.
+
+You can also provide plan text from the CLI:
+
+```bash
+minions plan "Add a health endpoint, tests, and operator documentation" SampleProject
+```
+
+## 2. Review before approval
+
+Open **Plans** and inspect:
+
+- every item has a concrete deliverable;
+- acceptance criteria can be tested;
+- dependencies use item IDs and are acyclic;
+- each item names the correct project;
+- rejected or out-of-scope ideas are explicit.
+
+Use **Discuss & Revise** for corrections. Approval is the human gate that
+materializes work items, so do not approve a vague PRD and expect routing to
+repair it.
+
+## 3. Approve and observe dependency gating
+
+Approve the plan, then inspect **Work**. Independent items can dispatch in
+parallel. Dependent items stay pending until their prerequisites are done.
+
+At spawn time, Minions resolves completed dependencies to their pull-request
+branches and merges those branches into the dependent item's worktree. This
+lets later items build on code that has not reached the main branch yet.
+
+## 4. Follow verification
+
+When all implementation items finish, Minions creates a `verify` work item.
+Verification builds and tests the combined result and must attach a pull
+request when its contract requires one. A completed plan remains visible until
+you archive it manually.
+
+Archive only after reviewing the verify result:
+
+```bash
+minions plans list
+minions plans archive <plan-or-prd-id>
+```
+
+Archived PRDs remain retained in place; the source plan Markdown moves to
+`plans/archive/`.
+
+## Checkpoint
+
+You should have an approved PRD, materialized work items, dependency-aware
+branches, and a final verification result. See
+[Plan Lifecycle](../plan-lifecycle.md) for status and archive details.
+
+Next: [configure runtimes and project tools](04-runtimes-and-harness.md).

package/docs/tutorials/04-runtimes-and-harness.md

@@ -0,0 +1,77 @@
+# Tutorial 4: Choose Runtimes and Propagate Project Tools
+
+Minions can dispatch with Copilot CLI, Claude Code, or Codex. This tutorial
+switches the fleet runtime, separates Command Center from agent settings, and
+checks which skills, commands, and MCP configurations reach a worktree.
+
+## 1. Inspect the current fleet
+
+```bash
+minions status
+minions doctor --harness
+```
+
+The harness report is read-only. It lists runtime asset directories, skill
+roots, slash-command roots, and MCP configuration paths.
+
+## 2. Select a fleet runtime
+
+```bash
+minions config set-cli copilot --model gpt-5.4
+minions restart
+```
+
+Use a model ID supported by your installed CLI. Omit `--model` to let the CLI
+choose its default. To clear a persisted model while switching:
+
+```bash
+minions restart --cli claude --model ""
+```
+
+Fleet resolution is:
+
+```text
+agent.cli -> engine.defaultCli -> copilot
+agent.model -> engine.defaultModel -> runtime default
+```
+
+Command Center has independent `engine.ccCli` and `engine.ccModel` overrides.
+Changing CC does not silently switch dispatched agents.
+
+## 3. Add a project-local skill
+
+In the linked repository's main checkout, create a committed skill under:
+
+```text
+.claude/skills/<skill-name>/SKILL.md
+```
+
+Describe when the skill applies and provide the exact existing project command
+to run. Commit the skill if every worktree should receive it. Uncommitted
+project-local assets can be propagated from the live checkout when
+`engine.harnessPropagateProjectLocal` is enabled, but committed assets are more
+reproducible.
+
+## 4. Verify propagation
+
+```bash
+minions doctor --harness
+```
+
+Dispatch a small task that clearly matches the skill. The completion report's
+`harnessUsed` section distinguishes assets that were available from those the
+agent reports actually using.
+
+For a known-empty execution environment, enable `hermeticHarness` for an agent
+or the fleet. This removes user asset directories and project harness
+propagation; use it for reproducibility tests, not as an MCP process-launch
+control.
+
+## Checkpoint
+
+The selected runtime passes doctor, your project asset appears in the harness
+survey, and a matching dispatch reports whether it used that asset.
+
+Reference: [Runtime Adapters](../runtime-adapters.md),
+[Harness Propagation](../harness-propagation.md), and
+[Harness Transparency](../harness-transparency.md).

package/docs/tutorials/05-schedules-and-watches.md

@@ -0,0 +1,71 @@
+# Tutorial 5: Automate Recurring Work and Follow-Ups
+
+Schedules create work at a time; watches react to state changes. You will create
+one of each and verify them without waiting for the clock.
+
+## 1. Explore the live schemas
+
+```bash
+minions schedule --help
+minions watch --help
+minions watch target-types
+minions watch action-types
+```
+
+Use the dashboard forms for your first records. They validate against the same
+server-side schemas as the CLI JSON commands.
+
+## 2. Create a schedule
+
+Open **Schedule**, create a disabled schedule named `weekly-doc-check`, select
+your sample project, and use a task such as:
+
+```text
+Review README.md for commands that no longer match the CLI. Correct only
+verified stale claims and report the source lines used.
+```
+
+Use the natural-language parser or cron builder to choose a weekly time. Save
+the schedule disabled, then use **Run now** to test it.
+
+From the CLI:
+
+```bash
+minions schedule list
+minions schedule run-now <schedule-id>
+```
+
+Confirm that a work item appears before enabling the recurring schedule.
+
+## 3. Create a watch
+
+Open **Watches** and create a watch for the test work item:
+
+- target type: `work-item`
+- target: the work-item ID
+- condition: `completed`
+- owner: `human`
+- stop after: `0`
+
+For an absolute condition such as `completed`, `stopAfter: 0` means fire once
+and expire. For change conditions, zero means continue indefinitely.
+
+Choose the default inbox notification first. Follow-up actions can dispatch
+work, call a webhook, trigger a pipeline, run a skill, or invoke CC triage, but
+they should be added only after the condition itself is proven.
+
+## 4. Observe the trigger
+
+```bash
+minions watch list
+minions watch show <watch-id>
+```
+
+Watches are evaluated on their polling cadence, not every engine tick. After
+the work item completes, confirm the watch records a trigger and an inbox note.
+
+## Checkpoint
+
+You have tested time-based creation and condition-based reaction independently.
+See [Watches](../watches.md) for predicates, plugins, templating, guards, and
+action chains.

package/docs/tutorials/06-managed-services.md

@@ -0,0 +1,85 @@
+# Tutorial 6: Keep a Development Service Running
+
+Use managed spawn when later agents need a dev server, emulator, or daemon to
+survive the creating agent's exit. The engine owns the process, checks health,
+and exposes it to later dispatches.
+
+## 1. Prove the service manually
+
+In the worktree that will host the service:
+
+1. Install its existing dependencies.
+2. Run the real start command for at least five seconds.
+3. Probe the intended health endpoint and verify the expected status.
+4. Stop the test process.
+
+Do not derive a managed-spawn spec from package names or guessed monorepo
+filters. A command that exits immediately will not become reliable because the
+engine starts it.
+
+## 2. Dispatch a managed-spawn work item
+
+Create a project-scoped work item through the API so the opt-in metadata is
+explicit. Save a temporary `managed-work-item.json`:
+
+```json
+{
+  "title": "Start the sample development service",
+  "description": "Start the existing development service and leave it available for downstream validation.",
+  "project": "SampleProject",
+  "type": "implement",
+  "meta": {
+    "managed_spawn": true,
+    "managed_spawn_ttl_minutes": 120
+  }
+}
+```
+
+Submit it, then delete the temporary file:
+
+```bash
+minions api POST /api/work-items --body-file managed-work-item.json
+```
+
+The rendered playbook tells the agent where to write
+`agents/<id>/managed-spawn.json` and includes the current executable allowlist
+and schema. The declared `cwd` must be an absolute path that exists when the
+agent exits; the agent should derive it from its current worktree.
+
+## 3. Require a healthcheck
+
+For a web service, use an HTTP healthcheck:
+
+```json
+{
+  "type": "http",
+  "url": "http://localhost:3000/health",
+  "expect_status": 200,
+  "interval_s": 1,
+  "timeout_s": 60
+}
+```
+
+For an emulator or non-HTTP daemon, use a command healthcheck that exits zero
+and matches a stable readiness signal.
+
+## 4. Inspect and use the service
+
+Open **Engine** and find **Managed Processes**, or query:
+
+```bash
+minions api GET /api/managed-processes
+```
+
+Confirm the process is healthy, its log path is populated, and its expiration
+time is correct. Dispatch a second work item in the same project and verify
+that the live managed-process context is included in its prompt.
+
+Use `meta.keep_processes` instead when the agent itself must retain an ad-hoc
+child with no health endpoint. Prefer managed spawn for named services.
+
+## Checkpoint
+
+The service remains healthy after the creating agent exits and is visible to a
+later dispatch. Read [Managed Spawn](../managed-spawn.md) for the full sidecar,
+allowlist, restart, log-stream, and partial-failure contracts.

package/docs/tutorials/07-cross-repo-plan.md

@@ -0,0 +1,56 @@
+# Tutorial 7: Coordinate a Cross-Repository Change
+
+Cross-repository plans keep one product outcome together while materializing
+each item into the project that owns its code.
+
+## 1. Link and name both projects
+
+```bash
+minions add C:\code\sample-api
+minions add C:\code\sample-web
+minions list
+```
+
+Give each project a distinct responsibility in its description. Cross-repo
+routing is much easier to review when `sample-api` and `sample-web` do not both
+say only "application code."
+
+## 2. Request a cross-repo plan
+
+In Command Center:
+
+```text
+/plan Add an API capability in sample-api and consume it from sample-web.
+Create separately testable items, assign every item to one project, and make
+the web integration depend on the API contract item.
+```
+
+The plan must declare both target projects, and every PRD item must have a valid
+`project` value matching a configured project name.
+
+## 3. Review the dependency boundary
+
+Before approval, confirm:
+
+- shared contracts are explicit acceptance criteria;
+- each item edits only one repository;
+- cross-repo `depends_on` records sequencing intent;
+- each repository has its own verification responsibility.
+
+Cross-repo dependencies are advisory for merge coordination. They do not make
+separate repositories share a Git history or automatically merge one repo's
+branch into another.
+
+## 4. Approve and observe fan-out
+
+Approval materializes items into each project's work-item store. Minions creates
+one verify work item per touched project after implementation completes.
+Inspect both project filters in **Work** and **Plans** rather than assuming the
+central plan card shows every repository-specific detail.
+
+## Checkpoint
+
+Both projects have correctly scoped work items and independent verification
+results, while the source plan remains one reviewable artifact.
+
+Reference: [Cross-Repo Plans](../cross-repo-plans.md).

package/docs/tutorials/08-operations-and-recovery.md

@@ -0,0 +1,76 @@
+# Tutorial 8: Operate and Recover Minions
+
+This tutorial builds a repeatable triage order for engine, dispatch, runtime,
+and worktree failures.
+
+## 1. Start with supported summaries
+
+```bash
+minions status
+minions queue
+minions sources
+```
+
+Use the dashboard **Engine** page for dispatch logs, metrics, managed processes,
+and worktree state. Read JSON sidecars only as diagnostics; migrated runtime
+state is canonical in `engine/state.db`.
+
+## 2. Classify before acting
+
+For a pending item, inspect `_pendingReason`. For a failed item, inspect its
+failure class and final output. Correct non-retryable causes such as
+authentication, invalid manifests, bad managed-spawn schemas, or dirty live
+checkouts before retrying.
+
+```bash
+minions wi show <work-item-id>
+minions wi retry <work-item-id>
+```
+
+## 3. Restart safely
+
+`minions start` is idempotent. Use `minions restart` after changing engine
+configuration or playbooks:
+
+```bash
+minions restart
+minions status
+```
+
+Agents are independent child processes. A restart loses in-memory process
+handles, so Minions uses persisted dispatch state, PID data, live-output
+activity, and a restart grace period to recover or classify orphans. Do not
+delete worktrees or dispatch rows to force recovery.
+
+## 4. Use targeted recovery commands
+
+```bash
+minions dispatch    # wake the daemon; does not run a second tick loop
+minions cleanup     # run the supported cleanup path
+minions kill        # kill active agents and reset dispatches to pending
+```
+
+Use `kill` only when agents are genuinely wedged. Quiet output is not enough:
+tracked agents are allowed to be silent during long builds and tests.
+
+## 5. Protect against process-level outages
+
+For unattended installations, inspect and optionally install the external
+watchdog:
+
+```bash
+minions watchdog status
+minions watchdog install --interval=5
+```
+
+The watchdog complements the in-process supervisor by probing and recovering
+the engine through the operating system scheduler.
+
+## Checkpoint
+
+You can distinguish pending, failed, orphaned, and stopped states and can choose
+the least destructive supported action for each.
+
+References: [Engine Restart](../engine-restart.md),
+[Timeouts and Liveness](../timeouts-and-liveness.md), and
+[Worktree Lifecycle](../worktree-lifecycle.md).

package/docs/tutorials/README.md

@@ -0,0 +1,29 @@
+# Minions Tutorial Track
+
+These tutorials build on one another. Complete the first two before jumping to
+an advanced topic. Each tutorial ends with an observable result rather than
+only describing configuration.
+
+| Tutorial | Outcome | Time |
+|---|---|---:|
+| [1. Install and connect a project](01-install-and-connect.md) | A healthy engine, dashboard, and linked repository | 15 min |
+| [2. Ship your first task](02-first-task.md) | One scoped work item dispatched and tracked to completion | 15 min |
+| [3. Build a feature from a plan](03-plan-driven-feature.md) | An approved PRD with dependency-aware implementation and verification | 25 min |
+| [4. Choose runtimes and propagate project tools](04-runtimes-and-harness.md) | A configured fleet with verified skills, commands, and MCP visibility | 20 min |
+| [5. Automate recurring work and follow-ups](05-schedules-and-watches.md) | A schedule and a condition-based watch | 25 min |
+| [6. Keep a development service running](06-managed-services.md) | An engine-owned, health-checked development service | 25 min |
+| [7. Coordinate a cross-repository change](07-cross-repo-plan.md) | One plan fanned out safely across multiple projects | 30 min |
+| [8. Operate and recover Minions](08-operations-and-recovery.md) | A practical status, restart, retry, and diagnostics workflow | 20 min |
+
+## How to use the tutorials
+
+- Use a disposable repository for the first task if you do not want an agent to
+  open a real pull request.
+- Keep the dashboard open while following CLI steps. It is the easiest place to
+  see routing, pending reasons, live output, and artifacts together.
+- Treat JSON files under `engine/` and `projects/` as diagnostic mirrors.
+  `engine/state.db` is the primary store for migrated runtime state.
+- Use the linked reference docs when you need the full schema or lifecycle.
+  Tutorials intentionally focus on a successful path.
+
+For a shorter setup-only path, use [the first-30-minutes guide](../onboarding.md).

package/docs/watches.md

@@ -1,10 +1,10 @@
 # Watches
 
-Persistent monitoring jobs that fire inbox notifications and follow-up actions when a target hits a condition. Watches survive engine restarts and are checked every 3 ticks (~3 minutes by default).
+Persistent monitoring jobs that fire inbox notifications and follow-up actions when a target hits a condition. Watches survive engine restarts and are checked every 18 ticks (~3 minutes at the default 10-second tick).
 
 ## What a Watch Is
 
-A watch is a small JSON record persisted to `engine/watches.json`. It binds:
+A watch is a record persisted in `engine/state.db`; `engine/watches.json` is a passive diagnostic mirror. It binds:
 
 | Field        | Purpose                                                                 |
 |--------------|-------------------------------------------------------------------------|
@@ -20,7 +20,7 @@ A watch is a small JSON record persisted to `engine/watches.json`. It binds:
 | `requires`   | Optional guard: array of predicate objects evaluated against `state` / `entity` / `prevState`; trigger is suppressed when any guard fails (false-or-error). Used to gate a watch on "PR is mergeable AND build passing" etc. |
 | `status`     | `WATCH_STATUS.ACTIVE` \| `PAUSED` \| `TRIGGERED` \| `EXPIRED`            |
 
-`createWatch()` allocates a `watch-<uid>` id, defaults the fields above, and persists atomically via `mutateJsonFileLocked` *(source: `engine/watches.js:184-248`)*.
+`createWatch()` allocates a `watch-<uid>` id, defaults the fields above, and persists through the watch store *(source: `engine/watches.js` and `engine/watches-store.js`)*.
 
 ## Lifecycle (`WATCH_STATUS`)
 
@@ -94,7 +94,7 @@ The eight built-ins are registered at module load *(source: `engine/watches.js`
 
 | `targetType`  | Target value                         | Conditions                                                                 | Notes |
 |---------------|--------------------------------------|----------------------------------------------------------------------------|-------|
-| `pr`          | PR number, canonical id, or display id | `merged`, `build-fail`, `build-pass`, `status-change`, `any`, `new-comments`, `vote-change`, `head-commit-change`, `mergeable-flipped`, `ready-for-merge`, `behind-master`, `draft-flipped` | Reads from `pull-requests.json` for any project; `new-comments` watches `humanFeedback.lastProcessedCommentDate`; `behind-master` requires `engine.watchesIncludeBehindBy: true` so the GH poller populates `pr.behindBy` |
+| `pr`          | PR number, canonical id, or display id | `merged`, `build-fail`, `build-pass`, `status-change`, `any`, `new-comments`, `vote-change`, `head-commit-change`, `mergeable-flipped`, `ready-for-merge`, `behind-master`, `draft-flipped` | Reads project PR state; `new-comments` watches `humanFeedback.lastProcessedCommentDate`; `behind-master` requires `engine.watchesIncludeBehindBy: true` so the GH poller populates `pr.behindBy` |
 | `work-item`   | Work item id                         | `completed`, `failed`, `status-change`, `any`, `stalled`, `retry-limit-reached`, `dependency-met` | `completed` matches `DONE_STATUSES`; `failed` matches `WI_STATUS.FAILED`; `stalled` fires after N unchanged captures (default 12 ≈ 60 min); `retry-limit-reached` fires when `_retryCount >= ENGINE_DEFAULTS.maxRetries` |
 | `meeting`     | Meeting id                           | `concluded`, `status-change`, `any`                                        | `concluded` fires on terminal status (`completed`, `archived`) |
 | `plan`        | PRD JSON filename or plan id         | `approved`, `rejected`, `completed`, `status-change`, `any`, `all-items-done`, `item-failed-n-times` | Looked up by `_source` (PRD file), `_sourcePlan` (.md), or `id`; uses `PLAN_STATUS` |
@@ -145,7 +145,7 @@ Resolution is `path.join(shared.MINIONS_DIR, 'watches.d')` so it works in both d
 }
 ```
 
-`checkWatches` walks every active watch and, inside a single `mutateJsonFileLocked` callback *(source: `engine/watches.js:410-561`)*:
+`checkWatches` walks every active watch and persists updates through the watch store:
 
 1. Skips paused/expired watches and any watch checked within its `interval`.
 2. Captures a baseline `_lastState` on first check (so change conditions have something to diff).
@@ -166,7 +166,7 @@ I/O happens **outside the lock**: notifications via `writeToInbox`, follow-up ac
 | Action type            | What it does                                                                                  |
 |------------------------|-----------------------------------------------------------------------------------------------|
 | `notify`               | Explicit inbox write; lets you customize `owner`/`body` instead of the default trigger string |
-| `dispatch-work-item`   | Append a new WI to the project (or central) `work-items.json` with `createdBy: "watch:<id>"`  |
+| `dispatch-work-item`   | Add a new project or central work item with `createdBy: "watch:<id>"`  |
 | `run-skill`            | Wrapper around `dispatch-work-item` that asks the agent to run a specific `.claude` skill     |
 | `webhook`              | `http`/`https` request to an arbitrary URL (10s safety timeout, JSON or string body)          |
 | `minions-api`          | Loopback call to the in-process dashboard at `http://127.0.0.1:${shared.readDashboardPortFile(MINIONS_DIR)?.port \|\| 7331}` (reads the bound-port beacon file, not the `MINIONS_PORT` env, so it still resolves after an `EADDRINUSE` port scan) — `endpoint` must start with `/api/`; sets `X-Minions-Internal: 1`; returns `{ok, status, summary, response}` for chain-step templating |

package/engine/shared.js

@@ -6327,16 +6327,18 @@ function resolveAgentTempBaseDir(project, engine, minionsDir) {
 
 // Seed the agent COPILOT_HOME's mcp-config (copy of `~/.copilot/mcp-config.json`
 // MINUS `engine.copilotAgentDisabledMcpServers`) and return the home path. This
-// is the single source of truth for "what MCP servers may a minions-spawned
-// copilot load." It is applied to EVERY copilot spawn path — agent dispatches
-// (engine), internal `llm.callLLM` calls (engine), and CC / doc-chat / the CC
-// worker pool (dashboard) — by setting `process.env.COPILOT_HOME` at the boot of
-// both processes, so every copilot CHILD inherits the filtered config. copilot
-// SPAWNS every server in its config and authenticates it (`--disable-mcp-server`
-// only hides tools), so any auth-requiring server pops a Microsoft window per
-// spawn — filtering the config is the only effective control. Idempotent: writes
-// only when the content changes (safe under concurrent callers). The operator's
-// real `~/.copilot` (interactive copilot) is never touched. Fail-open.
+// is the source of truth for "what MCP servers may an agent-dispatch copilot
+// load." It is applied to the engine-process copilot spawn paths ONLY — agent
+// dispatches (`_applyAgentCopilotHome`) and the engine process's own internal
+// `llm.callLLM` calls — by setting `process.env.COPILOT_HOME` at engine boot
+// and re-stamping it per dispatch, so those copilot CHILDREN inherit the
+// filtered config. copilot SPAWNS every server in its config and
+// authenticates it (`--disable-mcp-server` only hides tools), so any
+// auth-requiring server pops a Microsoft window per spawn — filtering the
+// config is the only effective control. Idempotent: writes only when the
+// content changes (safe under concurrent callers). The operator's real
+// `~/.copilot` (interactive copilot, and now also Command Center / doc-chat /
+// the CC worker pool, per W-mre75l6x00024f49) is never touched. Fail-open.
 function ensureAgentCopilotHome(minionsDir, engine) {
   const home = resolveAgentCopilotHome(minionsDir);
   try {

package/engine.js

@@ -11811,8 +11811,11 @@ if (require.main === module) {
   // `llm.callLLM` calls (consolidation, classification, meetings, …) — inherits
   // this process's COPILOT_HOME, so point it at the seeded, MCP-filtered home.
   // Without this, those `direct:true` copilot calls load the operator's full
-  // `~/.copilot` stack and pop a Microsoft auth window per call. The dashboard
-  // sets the same at its own boot for CC / doc-chat / the CC worker pool.
+  // `~/.copilot` stack and pop a Microsoft auth window per call. This isolation
+  // is engine-process-only: the dashboard process deliberately does NOT set
+  // COPILOT_HOME at its own boot, so Command Center / doc-chat / the CC worker
+  // pool inherit the operator's real `~/.copilot` home instead (reverted in
+  // W-mre75l6x00024f49; see dashboard.js boot for rationale).
   // See shared.ensureAgentCopilotHome. Fail-open.
   try { process.env.COPILOT_HOME = shared.ensureAgentCopilotHome(MINIONS_DIR, getConfig()?.engine); } catch {}
   const { handleCommand } = require('./engine/cli');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2364",
+  "version": "0.1.2365",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"