npm - @yemi33/minions - Versions diffs - 0.1.1884 → 0.1.1886 - Mend

@yemi33/minions 0.1.1884 → 0.1.1886

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

package/README.md +78 -64
package/docs/README.md +36 -0
package/docs/archive/distribution.md +97 -0
package/docs/auto-discovery.md +21 -8
package/docs/completion-reports.md +215 -0
package/docs/distribution.md +8 -24
package/docs/engine-restart.md +2 -0
package/docs/index.html +33 -45
package/docs/kb-sweep.md +173 -0
package/docs/onboarding.md +246 -0
package/docs/runtime-adapters.md +213 -0
package/docs/team-memory.md +116 -0
package/docs/teams-production.md +3 -1
package/docs/watches.md +201 -0
package/package.json +1 -1
package/playbooks/docs.md +1 -1
package/playbooks/fix.md +1 -12
package/playbooks/implement-shared.md +1 -12
package/playbooks/implement.md +2 -2
package/playbooks/plan-to-prd.md +3 -3
package/playbooks/review.md +1 -1
package/playbooks/shared-rules.md +1 -3
package/playbooks/verify.md +1 -1
package/prompts/cc-system.md +10 -2

package/docs/index.html CHANGED Viewed

@@ -3,8 +3,8 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>Minions &mdash; Multi-Agent AI Dev Team</title>
-<meta name="description" content="Five autonomous coding agents, one engine, and one dashboard. Minions orchestrates Claude or GitHub Copilot agents to plan, implement, review, verify, and ship code.">
+<title>Minions — Multi-Agent AI Dev Team</title>
+<meta name="description" content="5 autonomous AI agents, one engine, one dashboard. Minions orchestrates Claude-powered agents to plan, implement, review, and ship code autonomously.">
 <style>
   :root { --bg: #0d1117; --surface: #161b22; --border: #30363d; --text: #c9d1d9; --muted: #8b949e; --blue: #58a6ff; --green: #3fb950; --yellow: #d29922; --red: #f85149; --purple: #bc8cff; }
   * { margin: 0; padding: 0; box-sizing: border-box; }
@@ -83,15 +83,15 @@
 <!-- Hero -->
 <div class="hero">
   <h1>Minions <span>Mission Control</span></h1>
-  <p class="tagline">Five autonomous coding agents, one engine, one dashboard. Plan, implement, review, verify, and ship code with human control at every gate.</p>
+  <p class="tagline">5 autonomous AI agents, one engine, one dashboard. Plan, implement, review, and ship code &mdash; hands-free.</p>
   <div class="hero-badges">
-    <span class="hero-badge green">Node.js 18+</span>
-    <span class="hero-badge blue">Claude or Copilot</span>
+    <span class="hero-badge green">Zero Dependencies</span>
+    <span class="hero-badge blue">Claude-Powered</span>
     <span class="hero-badge yellow">Multi-Project</span>
-    <span class="hero-badge purple">Dashboard + CLI</span>
+    <span class="hero-badge purple">Self-Improving</span>
   </div>
   <div class="cta">
-    <a href="https://www.npmjs.com/package/@yemi33/minions" class="cta-primary">Install from npm</a>
+    <a href="https://github.com/yemi33/minions" class="cta-primary">View on GitHub</a>
     <a href="#quickstart" class="cta-secondary">Quick Start</a>
   </div>
 </div>
@@ -108,25 +108,24 @@
 <!-- Features -->
 <div class="container">
 <div class="features">
-  <div class="feature"><h3>Autonomous Dispatch</h3><p>Engine discovers work from plans, PRs, schedules, pipelines, and queues &mdash; then routes to the right agent by role, skill, and availability.</p></div>
-  <div class="feature"><h3>Plan Lifecycle</h3><p>Plan &rarr; Approve &rarr; PRD &rarr; Execute &rarr; Review &rarr; Verify. Completed plans stay available until you manually archive them.</p></div>
+  <div class="feature"><h3>Autonomous Dispatch</h3><p>Engine discovers work from plans, PRs, pipelines, and queues &mdash; routes to the right agent based on skills and availability.</p></div>
+  <div class="feature"><h3>Plan Lifecycle</h3><p>Plan &rarr; Approve &rarr; PRD &rarr; Execute &rarr; Review &rarr; Verify. Human-in-the-loop at every gate.</p></div>
   <div class="feature"><h3>Team Meetings</h3><p>Multi-agent meetings with investigate, debate, and conclude rounds. Agents research, discuss, and produce actionable conclusions.</p></div>
   <div class="feature"><h3>Multi-Stage Pipelines</h3><p>Chain tasks, meetings, plans, and more into automated workflows. Cron triggers or manual. Artifacts flow between stages.</p></div>
-  <div class="feature"><h3>Review / Fix Loop</h3><p>After implementation, Minions can dispatch reviews, react to human PR comments, and send fixes back to the original author agent.</p></div>
+  <div class="feature"><h3>Eval Loop</h3><p>After implementation, auto-dispatches review &rarr; fix cycles. Configurable iterations and cost ceiling per work item.</p></div>
   <div class="feature"><h3>Git Worktree Isolation</h3><p>Each agent works in its own worktree. No conflicts, no cross-contamination, safe parallel execution.</p></div>
-  <div class="feature"><h3>Knowledge Consolidation</h3><p>Agent findings, quick notes, pinned notes, and feedback consolidate into team notes and a categorized knowledge base.</p></div>
-  <div class="feature"><h3>PR Integration</h3><p>Tracks Azure DevOps and GitHub PRs, including review votes, build status, merge status, human comments, and context-only links.</p></div>
-  <div class="feature"><h3>Scheduled Tasks &amp; Watches</h3><p>Cron-style recurring work plus watches for PRs, work items, dispatches, meetings, pipelines, agents, and status changes.</p></div>
-  <div class="feature"><h3>Command Center &amp; Doc Chat</h3><p>Natural language orchestration, persistent CC tabs, document Q&amp;A/editing, issue filing, routing updates, and local API actions.</p></div>
-  <div class="feature"><h3>Pluggable Runtimes</h3><p>Run agents through Claude Code or GitHub Copilot CLI, with runtime-specific models, effort, session resume, and permission handling.</p></div>
-  <div class="feature"><h3>Live Dashboard</h3><p>Real-time mission control on port 7331 with paginated views, optimistic updates, live streams, metrics, and settings.</p></div>
-  <div class="feature"><h3>One-Command Updates</h3><p><code>minions update</code> pulls the latest npm package, reapplies files, and restarts while preserving config and customizations.</p></div>
+  <div class="feature"><h3>Knowledge Consolidation</h3><p>Agent findings auto-consolidate into team notes and a searchable knowledge base. The team learns as it works.</p></div>
+  <div class="feature"><h3>PR Integration</h3><p>Auto-syncs PRs from Azure DevOps and GitHub. Detects review feedback, build failures, and human comments.</p></div>
+  <div class="feature"><h3>Scheduled Tasks</h3><p>Cron-style recurring work: nightly tests, weekly audits, daily standups. Visual cron builder in the dashboard.</p></div>
+  <div class="feature"><h3>Command Center</h3><p>Natural language interface for delegating work to agents. CC orchestrates &mdash; agents implement.</p></div>
+  <div class="feature"><h3>Live Dashboard</h3><p>Real-time mission control on port 7331. Paginated views, optimistic updates, and visibility-aware polling.</p></div>
+  <div class="feature"><h3>One-Command Updates</h3><p><code>minions update</code> pulls latest from npm and applies. Config and charters preserved automatically.</p></div>
 </div>
 <!-- Demo scenarios -->
 <div class="scenario">
   <div class="scenario-header"><div class="scenario-num">1</div><h2>Dashboard Overview</h2></div>
-  <p>Home page with agent status cards, project bar, setup guidance, and engine state. All agents visible at a glance.</p>
+  <p>Home page with agent status cards, project bar, and setup guidance. All agents visible at a glance.</p>
   <div class="demo-frame">
     <img src="demo/01-dashboard-overview.png" alt="Dashboard overview with agent cards">
     <div class="demo-caption">Home page showing Minions Members, project bar, and engine status badge</div>
@@ -135,7 +134,7 @@
 <div class="scenario">
   <div class="scenario-header"><div class="scenario-num">2</div><h2>Work Items</h2></div>
-  <p>Paginated table with status, type, priority, agent, dependencies, artifacts, and linked PRs. <span class="badge badge-yellow">PENDING</span> <span class="badge badge-blue">DISPATCHED</span> <span class="badge badge-green">DONE</span> <span class="badge badge-red">FAILED</span>. Retry, delete, archive, and add feedback with optimistic updates.</p>
+  <p>Paginated table with status, type, priority, agent, and linked PRs. <span class="badge badge-yellow">PENDING</span> <span class="badge badge-blue">DISPATCHED</span> <span class="badge badge-green">DONE</span> <span class="badge badge-red">FAILED</span>. Retry, delete, and archive with optimistic updates.</p>
   <div class="demo-frame">
     <img src="demo/02-work-items.png" alt="Work items table">
     <div class="demo-caption">Work items page &mdash; 20 per page with create, edit, retry, and delete actions</div>
@@ -144,7 +143,7 @@
 <div class="scenario">
   <div class="scenario-header"><div class="scenario-num">3</div><h2>Plans &amp; PRD</h2></div>
-  <p>Plan cards with Approve / Discuss &amp; Revise / Reject. PRD dependency graph with per-item retry, reopening, verification, and manual archive.</p>
+  <p>Plan cards with Approve / Discuss &amp; Revise / Reject. PRD dependency graph with per-item retry. Archive completed plans.</p>
   <div class="demo-frame">
     <img src="demo/03-plans-prd.png" alt="Plans and PRD progress">
     <div class="demo-caption">Plans page with status-colored cards, PRD dependency graph, and action buttons</div>
@@ -153,7 +152,7 @@
 <div class="scenario">
   <div class="scenario-header"><div class="scenario-num">4</div><h2>Pull Requests</h2></div>
-  <p>PR tracker sorted by date, with review, build, merge, conflict, and human-comment status. Linked to work items and PRD items. Manual PR linking and context-only observation supported.</p>
+  <p>PR tracker sorted by date, with review, build, and merge status. Linked to work items and PRD items. Manual PR linking supported.</p>
   <div class="demo-frame">
     <img src="demo/04-pull-requests.png" alt="Pull requests tracker">
     <div class="demo-caption">PRs sorted newest-first with build status, review status, and agent attribution</div>
@@ -171,7 +170,7 @@
 <div class="scenario">
   <div class="scenario-header"><div class="scenario-num">6</div><h2>Pipelines</h2></div>
-  <p>Multi-stage workflows chaining tasks, meetings, plans, tests, docs, and more. Cron triggers or manual runs. Artifact tracking between stages.</p>
+  <p>Multi-stage workflows chaining tasks, meetings, plans, and more. Cron triggers or manual. Artifact tracking between stages.</p>
   <div class="demo-frame">
     <img src="demo/06-pipelines.png" alt="Pipelines page">
     <div class="demo-caption">Pipeline cards with stage flow visualization, run history, and progress bars</div>
@@ -180,7 +179,7 @@
 <div class="scenario">
   <div class="scenario-header"><div class="scenario-num">7</div><h2>Notes &amp; Knowledge Base</h2></div>
-  <p>Inbox for agent findings, quick notes, pinned notes, consolidated team notes, and categorized knowledge base. Inline Q&amp;A/editing on documents.</p>
+  <p>Inbox for agent findings, consolidated team notes, and categorized knowledge base. Inline Q&amp;A on any document.</p>
   <div class="demo-frame">
     <img src="demo/07-notes-kb.png" alt="Notes and knowledge base">
     <div class="demo-caption">Notes inbox, team notes, and knowledge base with category tabs and pagination</div>
@@ -189,7 +188,7 @@
 <div class="scenario">
   <div class="scenario-header"><div class="scenario-num">8</div><h2>Scheduled Tasks</h2></div>
-  <p>Cron-style recurring work with a visual builder. Schedule work items, tests, docs, plans, asks, meetings, and recurring maintenance.</p>
+  <p>Cron-style recurring work with visual builder. Natural language parsing &mdash; type "every weekday at 9am" and it generates the cron.</p>
   <div class="demo-frame">
     <img src="demo/08-schedules.png" alt="Schedules page">
     <div class="demo-caption">Schedule list with cron expressions, last-run times, and enable/disable toggles</div>
@@ -198,7 +197,7 @@
 <div class="scenario">
   <div class="scenario-header"><div class="scenario-num">9</div><h2>Engine &amp; Metrics</h2></div>
-  <p>Dispatch queue, engine log, agent metrics, token usage, runtime/model data, quality signals, and context pressure. All paginated.</p>
+  <p>Dispatch queue, engine log, agent metrics, token usage, and context pressure. All paginated.</p>
   <div class="demo-frame">
     <img src="demo/09-engine.png" alt="Engine page">
     <div class="demo-caption">Active/pending dispatches, completed history, engine log, and per-agent quality metrics</div>
@@ -207,7 +206,7 @@
 <div class="scenario">
   <div class="scenario-header"><div class="scenario-num">10</div><h2>Command Center</h2></div>
-  <p>Natural language delegation. CC orchestrates &mdash; agents implement. Sessions persist across refreshes and tabs; actions can create work, notes, plans, watches, PR links, and issues.</p>
+  <p>Natural language delegation. CC orchestrates &mdash; agents implement. Session persists across refreshes. Actions auto-execute.</p>
   <div class="demo-frame">
     <img src="demo/10-command-center.png" alt="Command Center panel">
     <div class="demo-caption">Command Center side panel with conversation history, action execution, and session indicator</div>
@@ -217,27 +216,17 @@
 <!-- Quick Start -->
 <div class="quickstart" id="quickstart">
   <h2>Quick Start</h2>
-  <pre><span class="comment"># Prerequisites: Node.js 18+, Git, and at least one agent runtime</span>
-<span class="comment"># Install Claude Code or GitHub Copilot CLI separately, then install Minions</span>
+  <pre><span class="comment"># Install</span>
 npm install -g @yemi33/minions
-<span class="comment"># Bootstrap ~/.minions/ and scan/link repositories</span>
+<span class="comment"># Initialize &mdash; prompts for project locations, starts engine + dashboard</span>
 minions init
-<span class="comment"># Or add a specific project later</span>
-minions add ~/my-project
-<span class="comment"># Start engine + dashboard, then open http://localhost:7331</span>
-minions restart --open
-minions dash
 <span class="comment"># Give your first task</span>
 minions work "Explore the codebase and document the architecture"
-<span class="comment"># Useful operations</span>
-minions status
-minions doctor
-minions config set-cli copilot --model gpt-5.4
+<span class="comment"># Open dashboard at http://localhost:7331</span>
+minions dash
 <span class="comment"># Update to latest</span>
 minions update</pre>
@@ -252,7 +241,7 @@ minions update</pre>
   │                                                     │
   │   engine.js ──── 60s tick loop ────┐                │
   │       │                            │                │
-  │   discover work    spawn agents    poll PRs/comments │
+  │   discover work    spawn agents    poll PRs          │
   │       │                │              │             │
   │   ┌───┴───┐    ┌──────┴──────┐   ┌──┴───┐         │
   │   │ Plans │    │  Worktrees  │   │ ADO  │         │
@@ -261,11 +250,10 @@ minions update</pre>
   │   └───────┘    └─────────────┘   └──────┘         │
   │                                                     │
   │   dashboard.js ── port 7331 ── mission control      │
-  │   runtimes/ ── Claude Code or GitHub Copilot CLI    │
   │   meetings/ ── multi-agent discussions              │
   │   pipelines/ ── multi-stage workflows               │
-  │   schedules + watches ── recurring/conditional work │
-  │   notes.md + knowledge/ ── team memory and KB       │
+  │   notes.md ── consolidated team knowledge           │
+  │   knowledge/ ── searchable KB by category           │
   └─────────────────────────────────────────────────────┘
   </pre>
 </div>
@@ -273,7 +261,7 @@ minions update</pre>
 </div>
 <footer>
-  <p>Minions &mdash; <a href="https://www.npmjs.com/package/@yemi33/minions">npm</a> &mdash; <a href="https://yemi33.github.io/minions/">Public site</a> &mdash; MIT License &mdash; Claude Code or GitHub Copilot CLI runtime</p>
+  <p>Minions &mdash; built by <a href="https://github.com/yemi33">yemi33</a> &mdash; <a href="https://github.com/yemi33/minions">GitHub</a> &mdash; <a href="https://www.npmjs.com/package/@yemi33/minions">npm</a> &mdash; MIT License</p>
 </footer>
 </body>

package/docs/kb-sweep.md ADDED Viewed

@@ -0,0 +1,173 @@
+# Knowledge Base Sweep
+How the `knowledge/` directory stays curated, deduplicated, and small enough to keep injecting into agent prompts.
+## What the Sweep Does
+The KB sweep is a 3-pass cycle implemented in [`engine/kb-sweep.js`](../engine/kb-sweep.js) that prunes duplicate, stale, and oversized entries from `knowledge/`. It runs asynchronously, archives (rather than deletes) what it removes, and writes a `_swept` frontmatter flag so the expensive rewrite pass is idempotent.
+```
+Entries in knowledge/<category>/*.md
+  → Pass 1: Hash dedup       (cheap, no LLM)
+  → Pass 2: LLM batch sweep  (Haiku, batches of 30)
+  → Pass 3: Per-entry rewrite (Haiku, concurrency 5)
+  → Prune _swept/ archive    (>30 days)
+  → Invalidate KB cache, write engine/kb-swept.json
+```
+## The 3-Pass Cycle
+### Pass 1 — Hash Dedup
+Cheap, deterministic. No LLM call.
+For every entry, compute `sha256(normalize(content).slice(0,500) + ':' + content.length)` (source: [`engine/kb-sweep.js:29`](../engine/kb-sweep.js#L29)). Group by hash. When two or more entries collide, keep the most recent (by `date:` frontmatter, then mtime) and archive the rest into `knowledge/_swept/` with a `<!-- swept: ... | reason: hash-duplicate of ... -->` header (source: [`engine/kb-sweep.js:84-105`](../engine/kb-sweep.js#L84)).
+This catches near-identical re-postings across batches that the LLM pass might miss because they land in different batches.
+### Pass 2 — LLM Batch Sweep
+The remaining survivors are sent to Claude Haiku in batches of `LLM_BATCH_SIZE = 30` (source: [`engine/kb-sweep.js:25`](../engine/kb-sweep.js#L25)). Each batch prompt asks for three lists in JSON:
+| Field | What the LLM looks for |
+|-------|------------------------|
+| `duplicates` | Entries with substantially the same content. Returned as `{keep, remove[], reason}`. |
+| `reclassify` | Entries in the wrong category. Returned as `{index, from, to, reason}`. |
+| `remove`     | Stale or empty entries (boilerplate, "no changes needed", bail-out notes). Returned as `{index, reason}`. |
+Each action archives the file via the same `_archiveKbFile()` helper used by Pass 1; reclassification rewrites the `category:` frontmatter line and moves the file into the new category directory (source: [`engine/kb-sweep.js:243-279`](../engine/kb-sweep.js#L243)).
+Reclassification targets are validated against `shared.KB_CATEGORIES` (`architecture`, `conventions`, `project-notes`, `build-reports`, `reviews` — source: [`engine/shared.js:1012`](../engine/shared.js#L1012)); unknown categories are silently dropped.
+If a batch returns invalid JSON or the runtime is unavailable, that batch is skipped with a warning and the rest of the sweep continues (source: [`engine/kb-sweep.js:139-151`](../engine/kb-sweep.js#L139)).
+### Pass 3 — Per-Entry Rewrite
+Survivors of Passes 1 and 2 that are still on disk get rewritten one entry at a time, with up to `NORMALIZE_CONCURRENCY = 5` parallel workers (source: [`engine/kb-sweep.js:26`](../engine/kb-sweep.js#L26)). Each entry is sent to Haiku with a fixed template prompt that:
+- Caps output at ~800 words.
+- Forces the structure `## Summary` → `## Key Findings` → `## Action Items` (omit if none) → `## References` (omit if none).
+- Preserves all `file:line` references and code snippets.
+- Drops boilerplate (full dates, agent IDs in the body, narrative scaffolding).
+After a successful rewrite, the entry's frontmatter gains a `_swept: <ISO timestamp>` key (source: [`engine/kb-sweep.js:229`](../engine/kb-sweep.js#L229)).
+## The `_swept` Frontmatter Flag
+`_swept` makes Pass 3 idempotent across runs. Semantics:
+- **Set** to `new Date().toISOString()` whenever the rewrite pass successfully rewrites the body (source: [`engine/kb-sweep.js:229`](../engine/kb-sweep.js#L229)).
+- **Skipped** by Pass 3 on subsequent sweeps as long as the file's `mtimeMs` is `<= sweptAt + 1000` ms (1 s grace for FS timestamp jitter — source: [`engine/kb-sweep.js:196-202`](../engine/kb-sweep.js#L196)).
+- **Re-processed** if the file is edited after the sweep flag was set (mtime exceeds the grace window).
+Hash dedup (Pass 1) and the LLM sweep (Pass 2) ignore `_swept` — those passes act on metadata and similarity, not on whether the entry was previously rewritten.
+The flag key is exported as `SWEPT_FLAG_KEY` for tests (source: [`engine/kb-sweep.js:27,429`](../engine/kb-sweep.js#L27)).
+## 30-Day Archive Retention
+Archived entries land in `knowledge/_swept/` with their original filename (deduped via `shared.uniquePath()` if it collides). They're not deleted immediately — `_pruneOldSwept()` runs at the end of every sweep and removes any file whose `mtimeMs` is older than `SWEPT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000` (30 days — source: [`engine/kb-sweep.js:23,69-81`](../engine/kb-sweep.js#L23)).
+This gives humans a recovery window: if a sweep archives something useful, you have ~30 days to copy it back out of `_swept/` before it's permanently pruned.
+## Manual Trigger
+The dashboard exposes two endpoints:
+| Method | Path | Purpose |
+|--------|------|---------|
+| `POST` | `/api/knowledge/sweep` | Start a sweep in the background. Returns `202 { ok: true, started: true }` (source: [`dashboard.js:7351`](../dashboard.js#L7351), [`dashboard.js:4285`](../dashboard.js#L4285)). |
+| `GET`  | `/api/knowledge/sweep/status` | Poll `{ inFlight, startedAt, lastResult, lastCompletedAt }` (source: [`dashboard.js:7352`](../dashboard.js#L7352), [`dashboard.js:4335`](../dashboard.js#L4335)). |
+POST body is optional. Pass `{ "pinnedKeys": ["knowledge/conventions/foo.md", ...] }` to add request-level pins on top of `pinned.md`. Pinned entries are excluded from every pass (source: [`engine/kb-sweep.js:345-356`](../engine/kb-sweep.js#L345)).
+```bash
+# Trigger a sweep
+curl -X POST http://localhost:7331/api/knowledge/sweep \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+# Poll status
+curl http://localhost:7331/api/knowledge/sweep/status
+```
+### Concurrency Guard
+Only one sweep runs at a time. The POST handler refuses to start a second sweep with `{ ok: true, alreadyRunning: true, startedAt }` while one is in flight (source: [`dashboard.js:4306-4311`](../dashboard.js#L4306)).
+The guard auto-releases when the sweep has been running longer than `staleGuardMs(entryCount)` — `max(30 min, 1 s × entryCount)` — which protects against a dashboard process that died mid-sweep leaving the flag stuck (source: [`engine/kb-sweep.js:413-417`](../engine/kb-sweep.js#L413), [`dashboard.js:4286-4305`](../dashboard.js#L4286)).
+### Persistent State
+Sweep state is mirrored to `engine/kb-sweep-state.json` so the dashboard can recover the in-flight indicator across restarts:
+```jsonc
+// While running
+{ "status": "in-flight", "startedAt": 1715472000000, "startedAtIso": "2026-05-12T..." }
+// On success
+{ "status": "completed", "startedAt": ..., "completedAt": ..., "durationMs": ..., "summary": "...", "lastResult": { ... } }
+// On failure
+{ "status": "failed", "startedAt": ..., "completedAt": ..., "error": "..." }
+```
+Memory still wins when present; the disk file is a fallback (source: [`engine/kb-sweep.js:298-320`](../engine/kb-sweep.js#L298), [`dashboard.js:4296-4354`](../dashboard.js#L4296)). A separate `engine/kb-swept.json` is written after each successful sweep with the human-readable summary line shown by the dashboard's "swept N days ago" badge (source: [`engine/kb-sweep.js:407`](../engine/kb-sweep.js#L407)).
+## Dashboard UI
+The KB page surfaces sweep state in two places:
+1. **Trigger button** (`kbSweep()` in [`dashboard/js/render-kb.js:166`](../dashboard/js/render-kb.js#L166)) posts to `/api/knowledge/sweep` with the user's pinned keys and shows an immediate "queued" toast. If the response says `alreadyRunning`, the toast switches to "already running (Xm elapsed) — let it finish first".
+2. **`#kb-swept-time` indicator** renders `swept N days ago · now sweeping (Xm)` (source: [`dashboard/js/render-kb.js:72-82`](../dashboard/js/render-kb.js#L72)). The `sweepInFlight` and `sweepStartedAt` fields come from `GET /api/knowledge` (source: [`dashboard.js:4262-4267`](../dashboard.js#L4262)).
+### Polling
+The KB page is refreshed by the dashboard's main refresh loop **every third tick (~12 s)** in [`dashboard/js/refresh.js:121`](../dashboard/js/refresh.js#L121). There is no separate sweep-status polling timer and no auto-stop — the in-flight badge keeps refreshing for as long as the user has the dashboard open and the sweep is running. Sweeps can take many minutes for a large KB; the persistent `engine/kb-sweep-state.json` flag plus the indefinite refresh loop are what let the indicator survive dashboard restarts and arbitrarily long sweeps.
+## Result Summary
+`runKbSweep()` returns (and persists in `engine/kb-swept.json`):
+```js
+{
+  ok: true,
+  entriesBefore, entriesAfter,
+  bytesBefore,  bytesAfter,
+  hashDuplicatesArchived,  // Pass 1
+  llmDuplicatesArchived,   // Pass 2 (within-batch dupes)
+  staleRemoved,            // Pass 2 (LLM-flagged removals)
+  reclassified,            // Pass 2 (category moves)
+  rewritten,               // Pass 3
+  rewriteBytesBefore, rewriteBytesAfter,
+  sweptArchivePruned,      // Files purged from _swept/ (>30 days)
+  durationMs,
+  summary: '<n> hash-dup, <n> llm-dup, <n> stale, <n> reclassified, <n> rewritten (<bytes> saved)',
+}
+```
+After a non-dry-run sweep, `queries.invalidateKnowledgeBaseCache()` is called so the next `/api/knowledge` read sees the new state (source: [`engine/kb-sweep.js:408`](../engine/kb-sweep.js#L408)).
+## What NOT to Do
+> **Never write to `knowledge/` directly.** The sweep is the only writer. Every other code path — agents, dashboard handlers, scripts — should write findings to `notes/inbox/<agent>-<id>-<date>.md` and let the consolidation engine classify them into `knowledge/<category>/`.
+Why this matters:
+- Direct writes bypass the hash-dedup, classification, and `_swept` rewrite passes, so future sweeps see a "fresh" entry and may immediately rewrite or archive it.
+- Editing an entry resets its `mtime`, which makes the `_swept` flag stale (re-rewrite on next sweep) and silently changes the entry the next consolidation pass diffs against.
+- Manual edits collide with the LLM rewrite pass — your edit can be replaced wholesale by the next sweep.
+- Per the team-wide rule injected into every dispatched playbook: **"Never delete, move, or overwrite files in `knowledge/`."**
+If you spot an incorrect KB entry, write a note to `notes/inbox/` describing the issue. The next sweep will reclassify, merge, or remove it; humans can also pin entries (via `pinned.md` or the dashboard) to keep them out of the sweep entirely.
+The archive directory `knowledge/_swept/` is also off-limits to manual edits — touching it interferes with the 30-day retention timestamp.
+## Related Files
+- [`engine/kb-sweep.js`](../engine/kb-sweep.js) — implementation
+- [`engine/queries.js`](../engine/queries.js) — `getKnowledgeBaseEntries()`, `invalidateKnowledgeBaseCache()`
+- [`dashboard.js`](../dashboard.js) — `handleKnowledgeSweep`, `handleKnowledgeSweepStatus`, `handleKnowledgeList`
+- [`dashboard/js/render-kb.js`](../dashboard/js/render-kb.js) — UI trigger and indicator
+- [`dashboard/js/refresh.js`](../dashboard/js/refresh.js) — refresh cadence (every 3rd tick)
+- [`engine/shared.js`](../engine/shared.js) — `KB_CATEGORIES`, `getPinnedItems()`, `uniquePath()`

package/docs/onboarding.md ADDED Viewed

@@ -0,0 +1,246 @@
+# 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.
+> **Prerequisites:** Node.js 18+, 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.
+> **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.
+---
+## 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); engine itself has zero deps
+```
+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.
+```bash
+minions doctor
+```
+A healthy Mac/Linux run looks roughly like:
+```
+  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 writable
+    ✓ engine/ writable
+  All checks passed.
+```
+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.
+---
+## 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.
+```bash
+minions init
+```
+After init you will have (under `~/.minions/`):
+- `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
+`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`.
+---
+## Step 4 — Link your first project with `minions add`
+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.
+```bash
+minions add ~/code/your-repo
+```
+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").
+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.
+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.
+```bash
+minions restart
+```
+You should see logs like `Engine started (pid=…)` and `Dashboard listening on http://localhost:7331`. Open the dashboard:
+```bash
+minions dash    # opens http://localhost:7331 in your default browser
+```
+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 60 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
+The fastest way to give Minions a task is the Command Center (CC).
+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.
+Within one tick (≤60 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
+```
+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:
+- [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.
+Welcome to the team.