docs: comprehensive documentation overhaul

.gitignore

@@ -98,4 +98,8 @@ mission-control/public/ci-verify-input.json
 docs/proposals/
 docs/roadmap/
 
+# ── Ad-hoc Scripts (personal utilities, not project-relevant) ─────
+scripts/generate_icons.py
+scripts/rebuild.sh
+
 

docs/CONFIGURATION.md

@@ -37,7 +37,7 @@ Defines the machine running the Docker Compose stack.
 | `ports.litellm` | int | ✅ | — | LiteLLM proxy port. |
 | `ports.triage` | int | ❌ | `8001` | Triage vLLM port. |
 | `ports.daemon` | int | ✅ | — | Daemon API port. |
-| `ports.dashboard` | int | ✅ | — | Mission Control dashboard port. |
+| `ports.dashboard` | int | ❌ | `9321` | Mission Control dashboard port. |
 
 ```yaml
 control_plane:
@@ -177,7 +177,7 @@ Controls the coordination paradigm used for multi-agent tasks.
 | Field | Type | Required | Default | Description |
 |:---|:---|:---|:---|:---|
 | `variant` | string | ✅ | — | Active variant: `traditional`, `patchboard`, or `stigmergic`. |
-| `blackboard_v2` | bool | ❌ | `true` | Enables the v2 board substrate (entries + events). |
+| `blackboard_v2` | bool | ❌ | `false` | Enables the v2 board substrate (entries + events). |
 | `view_budget_tokens` | int | ❌ | `12000` | Full-board token budget; budgeted view mode above this. |
 | `round_execution` | string | ❌ | `concurrent` | `concurrent` (parallel agents) or `sequential` (paper-exact). |
 

docs/QUICKSTART.md

@@ -57,7 +57,7 @@ Fill in your secrets:
 REDIS_PASSWORD=your-secure-password
 LITELLM_MASTER_KEY=sk-your-litellm-key
 GEMINI_API_KEY=your-gemini-key
-BMAS_NODE_KEY=your-node-auth-token    # For agent ingest auth
+BMAS_NODE_KEY=                        # Generate with: openssl rand -hex 32
 ```
 
 ## 3. Start the Swarm

docs/README.md

@@ -0,0 +1,19 @@
+# Documentation
+
+[← Back to Project](../README.md)
+
+## Guides
+
+| Document | Description |
+|:---|:---|
+| [Quick Start](QUICKSTART.md) | Get running in 5 minutes |
+| [Configuration](CONFIGURATION.md) | Full `bmas.yaml` reference |
+| [Node Setup](NODE_SETUP.md) | Provisioning edge nodes with inference + agents |
+| [Hermes API](HERMES_API.md) | Hermes Dashboard & Gateway API reference |
+
+## Reference
+
+| Document | Description |
+|:---|:---|
+| [Architecture](architecture/README.md) | System architecture & component deep-dive |
+| [Design System](design/DESIGN.md) | Mission Control UI specification |

docs/architecture/README.md

@@ -157,7 +157,7 @@ daemon/src/
 
 | Aspect | Detail |
 |:---|:---|
-| **Image** | `redis:7-alpine` |
+| **Image** | `redis:8-alpine` |
 | **Port** | 6379 |
 | **Memory** | 1 GB `maxmemory` (2 GB container limit) |
 | **Persistence** | RDB snapshots every 60s if ≥100 keys changed |
@@ -536,7 +536,7 @@ The Dashboard proxies hardware metrics from [Beszel Hub](https://github.com/henr
 |:---|:---|:---|:---|
 | **Orchestrator** | Python + FastAPI + Uvicorn | 3.13+ | Task lifecycle, API, dispatch |
 | **Persistence** | SQLite (aiosqlite) | v2 schema | Permanent task history (12 tables) |
-| **Blackboard** | Redis | 7-alpine | Real-time state, Pub/Sub, Streams, locks |
+| **Blackboard** | Redis | 8-alpine | Real-time state, Pub/Sub, Streams, locks |
 | **Model Gateway** | LiteLLM | latest | Unified model routing + cost tracking |
 | **Triage** | vLLM + Qwen3-1.7B | latest | Complexity classification |
 | **Agent Runtime** | Hermes CLI / Runs API | — | LLM agent execution on edge nodes |
@@ -557,4 +557,5 @@ The Dashboard proxies hardware metrics from [Beszel Hub](https://github.com/henr
 ## References
 
 - **Han, B. & Zhang, S. (2025).** *Exploring Advanced LLM Multi-Agent Systems Based on Blackboard Architecture.* [arXiv:2507.01701](https://arxiv.org/abs/2507.01701) — The foundational paper for the bMAS architecture.
+- **Zhang, S., Shi, W. & Wang, H. (2026).** *PatchBoard: Schema-Grounded State Mutation for Reliable and Auditable LLM Multi-Agent Collaboration.* [arXiv:2605.29313](https://arxiv.org/abs/2605.29313) — The PatchBoard coordination variant.
 - [Stigmergy (Wikipedia)](https://en.wikipedia.org/wiki/Stigmergy) — The coordination mechanism this system is named after.

docs/design/DESIGN.md

@@ -1,8 +1,8 @@
-[🏠 Index](../README.md) | [📋 Context](../examples/stigmergic/CONTEXT.md)
+[🏠 Index](../README.md) | [📋 Context](../../examples/stigmergic/CONTEXT.md)
 
 # Mission Control — Design System
 
-> [!ABSTRACT] Purpose
+> [!NOTE] Purpose
 > This document is the **single source of truth** for Mission Control's visual language. Every component, every screen, every interaction should reference this spec to maintain enterprise-grade consistency. This is not a component library — it is the design contract that any implementation (human or AI) must follow.
 >
 > **Inspiration benchmarks:** Notion (information density + clean hierarchy), Airbnb (typography + whitespace mastery), Linear (real-time ops dashboard), Vercel (dark-mode polish).
@@ -192,7 +192,7 @@ Shadows are used **sparingly** — only for floating elements (modals, popovers,
 
 ## 5. Component Patterns
 
-These are the **reusable primitives** that every feature component must be composed from. Building feature components directly from raw HTML/Tailwind (without using these primitives) violates the design contract.
+These are the **reusable primitives** that every feature component must be composed from. Building feature components directly from raw HTML/CSS (without using these primitives) violates the design contract.
 
 ### 5.1 Panel
 
@@ -240,9 +240,9 @@ Wrapper for the xterm.js terminal instances. Gives each terminal an identity.
 - **Body:** xterm.js fills remaining height. Border: 1px `--border-default`. Border radius bottom: `--radius-xl`.
 - **Border-top accent:** 2px solid line in the agent's identity color across the full width.
 
-### 5.5 DebateList
+### 5.5 DebateThread
 
-Used by the Blackboard/Debate tab. Chronological list of debate entries from the agent deliberation process. Replaces the old SplitView (Public/Private Redis split).
+Used by the Blackboard/Mission tab. Chronological list of debate entries from the agent deliberation process.
 
 - **Layout:** Vertical list of debate entries, newest at the bottom. Each entry shows: agent role identity (colored dot + name), content (text/markdown), timestamp.
 - **Agent identity:** 8px circle dot in the agent's `--agent-{role}` color + role name in `--text-sm`.
@@ -307,10 +307,10 @@ Mission Control uses a **task-centric architecture** — the sidebar shows task
 │ ✓ task-b │                                       │
 │ ✗ task-c │  B) Task Detail (route: /task/[id])    │
 │──────────│     ┌─ Header: label, status, cost ─┐ │
-│ YESTERDAY│     │ [Overview][DAG][Logs][Board][$$]│ │
+│ YESTERDAY│     │ [Overview][Board][Graph][Logs] │ │
 │ ✓ task-d │     ├─────────────────────────────────┤ │
 │──────────│     │  Tab content fills this area    │ │
-│ ─System─ │     │  (DAG, Logs, Blackboard, Cost)  │ │
+│ ─System─ │     │  (Board, Graph, Logs, Artifacts)│ │
 │ 📡 Infra │     └─────────────────────────────────┘ │
 │ ✨ Skills│                                       │
 │──────────│                                       │
@@ -342,16 +342,16 @@ Replaced from feature-navigation to **task-history sidebar**.
 
 The main area renders Next.js App Router pages based on the URL:
 
-| Route | Content |
-|:---|:---|
-| `/` | Landing page — conversational task input with auto-resize textarea, inline send button, and recent task history cards |
-| `/task/[taskId]` | Task overview — result display, sub-task progress, live phase indicator |
-| `/task/[taskId]/dag` | DAG visualization — React Flow canvas showing task decomposition graph |
-| `/task/[taskId]/logs` | Log terminals — 3-column (or tabbed on mobile) xterm.js terminals filtered by agent role |
-| `/task/[taskId]/blackboard` | Debate history — chronological list of agent debate entries with typing indicators |
-| `/task/[taskId]/cost` | Cost breakdown — per-phase and per-model cost tables with MetricCard heroes |
-| `/infra` | Infrastructure telemetry — Beszel Hub metrics for all nodes |
-| `/skills` | Skills explorer — per-agent skill lists with view/delete actions |
+| Route | Tab Label | Content |
+|:---|:---|:---|
+| `/` | — | Landing page — conversational task input with auto-resize textarea, inline send button, and recent task history cards |
+| `/task/[taskId]` | Overview | Task overview — result display (rendered markdown), sub-task progress, convergence strip, and live phase indicator |
+| `/task/[taskId]/mission` | Blackboard | Mission cockpit — 4-panel live layout with blackboard board (timeline/threads/graph views), agent minds, budget gauge, convergence meter, and HITL controls |
+| `/task/[taskId]/dag` | Graph | Execution graph — React Flow canvas with swimlane visualization of agent turns grouped by round |
+| `/task/[taskId]/logs` | Logs | Distributed log stream — unified chronological log across all agents with per-role filtering and structured detail drawer |
+| `/task/[taskId]/artifacts` | Artifacts | Artifact browser — file tree + downloads for agent-produced output files |
+| `/infra` | — | Infrastructure telemetry — Beszel Hub metrics for all nodes |
+| `/skills` | — | Skills explorer — per-agent skill lists with view/delete actions |
 
 All `/task/[taskId]/*` pages share a **task detail layout** (`task/[taskId]/layout.tsx`) that renders the task header + tab navigation and hosts the `TaskStreamContext.Provider` for SSE data distribution. Tab switches are instantaneous DOM swaps — the SSE connection persists in the layout.
 
@@ -456,11 +456,12 @@ src/
 │   ├── task/
 │   │   └── [taskId]/
 │   │       ├── layout.tsx            # Task detail layout: header + tabs + TaskStreamContext.Provider
+│   │       ├── TaskStreamContext.tsx  # Distributes SSE data from useTaskStream to tab pages
 │   │       ├── page.tsx              # Overview tab (default)
-│   │       ├── dag/page.tsx          # DAG visualization
-│   │       ├── logs/page.tsx         # Log terminals (3 columns)
-│   │       ├── blackboard/page.tsx   # Debate history
-│   │       └── cost/page.tsx         # Cost breakdown
+│   │       ├── mission/page.tsx      # Blackboard — 4-panel live cockpit
+│   │       ├── dag/page.tsx          # Graph — execution graph (React Flow)
+│   │       ├── logs/page.tsx         # Logs — distributed log stream
+│   │       └── artifacts/page.tsx    # Artifacts — file tree + downloads
 │   ├── infra/page.tsx                # Infrastructure telemetry
 │   └── skills/page.tsx               # Skills explorer
 ├── components/
@@ -469,17 +470,40 @@ src/
 │   │   ├── StatusBadge.tsx
 │   │   ├── MetricCard.tsx
 │   │   ├── TerminalPane.tsx
+│   │   ├── TaskSidebar.tsx           # Task history sidebar + system nav
 │   │   ├── ActionButton.tsx
 │   │   ├── Skeleton.tsx
 │   │   ├── EmptyState.tsx
+│   │   ├── InfoTooltip.tsx
+│   │   ├── RichContent.tsx
 │   │   └── Toast.tsx
-│   ├── TopBar.tsx                    # "use client" — daemon status, cost ticker
-│   ├── TaskSidebar.tsx               # "use client" — task history, system nav
-│   ├── DAGVisualizer.tsx             # Feature: React Flow canvas
-│   ├── LogTerminal.tsx               # Feature: xterm.js + TerminalPane
-│   └── DebateList.tsx                # Feature: debate entries + typing indicator
+│   ├── layout/
+│   │   └── TopBar.tsx                # "use client" — daemon status, cost ticker
+│   └── features/                     # Feature components composed from ui/ primitives
+│       ├── TurnGraph.tsx             # Execution graph — React Flow swimlane canvas
+│       ├── DistributedLogStream.tsx  # Log stream — TanStack Virtual with detail drawer
+│       ├── BlackboardBoard.tsx       # Board — timeline/threads/graph views
+│       ├── BlackboardGraph.tsx       # Board graph — visual entry relationships
+│       ├── BudgetGauge.tsx           # Cost tracking gauge
+│       ├── ConsensusMeter.tsx        # Convergence progress meter
+│       ├── ConvergenceStrip.tsx      # Round-by-round convergence indicator
+│       ├── AgentTrace.tsx            # Agent trace inspector
+│       ├── AgentMindCard.tsx         # Agent model/contribution card
+│       ├── ArtifactBrowser.tsx       # Artifact file tree + downloads
+│       ├── AttachmentRail.tsx        # File attachment display
+│       ├── SkillsExplorer.tsx        # Per-agent skill lists
+│       ├── Telemetry.tsx             # Hardware telemetry gauges
+│       ├── VariantSelect.tsx         # Coordination variant selector
+│       ├── TurnInspector.tsx         # Turn detail drawer
+│       ├── WorkerLane.tsx            # Per-worker execution lane
+│       ├── GlobalFirehose.tsx        # Cross-task log stream
+│       ├── ReplayScrubber.tsx        # Temporal replay controls
+│       ├── ToolCallCard.tsx          # Tool call detail card
+│       └── board/
+│           ├── BoardEntryCard.tsx    # Individual board entry card
+│           ├── BoardEntryDetail.tsx  # Expanded entry view
+│           └── DebateThread.tsx      # Threaded debate entries
 ├── contexts/
-│   ├── TaskStreamContext.tsx          # Distributes SSE data from useTaskStream to tab pages
 │   └── PendingTaskContext.tsx         # Optimistic UI: ephemeral submitted-text context
 ├── hooks/
 │   ├── useTaskStream.ts              # SSE hook for /api/stream/task/[taskId] (logs, phase, debate, etc.)
@@ -493,7 +517,7 @@ src/
 > Feature components (DAG, Logs, Debate, etc.) must **not** directly use raw CSS for layout, backgrounds, or spacing. They compose from the `ui/` primitives, which themselves use the token system. This creates one layer of indirection that makes future redesigns possible without touching feature logic.
 
 > [!IMPORTANT] SSE Data Flow
-> The `useTaskStream` hook is called **once** in `task/[taskId]/layout.tsx` and distributed via `TaskStreamContext.Provider`. Individual tab pages consume data via `useTaskData()` — they never create their own `EventSource` connections. This prevents the "tab switch tear" where SSE reconnects cause 200-500ms flickers.
+> The `useTaskStream` hook is called **once** in `task/[taskId]/layout.tsx` and distributed via `TaskStreamContext.Provider` (co-located at `task/[taskId]/TaskStreamContext.tsx`). Individual tab pages consume data via `useTaskData()` — they never create their own `EventSource` connections. This prevents the "tab switch tear" where SSE reconnects cause 200-500ms flickers.
 
 ---
 

mission-control/src/app/layout.tsx

@@ -35,7 +35,7 @@ export async function generateMetadata(): Promise<Metadata> {
     keywords: [
       "bMAS",
       "Multi-Agent Swarm",
-      "Biomimetic AI",
+      "Blackboard AI",
       "Stigmergy",
       "Decentralized AI Swarm",
       "Autonomous Agents",

mission-control/src/app/manifest.ts

@@ -2,7 +2,7 @@ import type { MetadataRoute } from "next";
 
 export default function manifest(): MetadataRoute.Manifest {
   return {
-    name: "Biomimetic Multi-Agent Swarm (bMAS)",
+    name: "Blackboard Multi-Agent Swarm (bMAS)",
     short_name: "bMAS",
     description: "A decentralized swarm of autonomous agents collaborating to execute tasks based on stigmergy and local interactions.",
     start_url: "/",