{
  "id": "2026-04-28-ops-studio-33a22db493",
  "scope": "redkey",
  "source_of_truth": "repo",
  "source_path": "docs/specs/2026-04-28-ops-studio.md",
  "source_kind": "markdown",
  "visibility": "internal",
  "renderer_id": "design_doc.dreamborn-forge.generated.v1",
  "design_system": "dreamborn-design-system:forge",
  "generated_at": "2026-05-09T13:00:55.691Z",
  "artifact_type": "design_doc",
  "schema_version": "design_doc.generated.v1",
  "title": "Ops Studio — Design Spec",
  "summary": "Ops Studio — Design Spec Date: 2026 04 28 Status: Approved — pending implementation Replaces: cockpit/index.html (renamed and rebuilt in place) URL: https://cockpit.bezeliq.ai (unchanged) What It Is Ops Studio is the live operations dashboard for the BezelIQ/RedKey platform. It is the single screen that shows Justin (and eventually clients) everything happen...",
  "format_source": "markdown",
  "sections": [
    {
      "title": "Ops Studio — Design Spec",
      "level": 1,
      "body": "**Date:** 2026-04-28\n**Status:** Approved — pending implementation\n**Replaces:** `cockpit/index.html` (renamed and rebuilt in-place)\n**URL:** `https://cockpit.bezeliq.ai` (unchanged)\n\n---"
    },
    {
      "title": "What It Is",
      "level": 2,
      "body": "Ops Studio is the live operations dashboard for the BezelIQ/RedKey platform. It is the single screen that shows Justin (and eventually clients) everything happening in the agent fleet — who is working, what it costs, what just happened, and what is stuck. It is designed to be left open on a second monitor and to impress anyone who sees it.\n\nThe design principles:\n1. **Radical transparency** — cost, time, Anthropic spend, Hedera proof — nothing hidden\n2. **Mission-control aesthetic** — dark, precise, alive. Agents pulse when working.\n3. **Action-first** — blocked items and exec gates surface immediately, not buried\n4. **Real numbers** — every task has a dollar amount. The platform has a P&L.\n\n---"
    },
    {
      "title": "Layout",
      "level": 2,
      "body": "Three-panel shell:\n\n```\n┌──────────────────────────────────────────────────────────────────┐\n│  BezelIQ · Ops Studio          [Fleet | Workflows | Health]   ✉  │\n├────────────────────────────────────────────┬─────────────────────┤\n│                                            │                     │\n│             MAIN PANEL                     │    LIVE FEED        │\n│         (tab-switched)                     │    (always visible) │\n│                                            │                     │\n└────────────────────────────────────────────┴─────────────────────┘\n```\n\n- **Nav bar** — brand + 3 tab buttons (Fleet / Workflows / Health) + inbox badge + live indicator\n- **Main panel** — 75% width, tab-switched between Fleet, Workflows, Health\n- **Live feed** — 25% width, always visible regardless of active tab, real-time event stream\n- Default tab on load: **Fleet**\n\n---"
    },
    {
      "title": "Tab 1 — Agent Fleet",
      "level": 2,
      "body": "The hero view. Every agent as a card, grouped by department."
    },
    {
      "title": "Department groups (in order)",
      "level": 3,
      "body": "`exec` · `ops` · `platform` · `dev` · `design` · `qa` · `crm` · `sales` · `marketing`"
    },
    {
      "title": "Agent Card",
      "level": 3,
      "body": "```\n┌─────────────────────────┐\n│  [avatar]  ● working    │  ← 40px avatar, status orb top-right\n│                         │\n│  Quinn                  │  ← name, 16px semibold\n│  developer              │  ← role, 11px muted mono\n│                         │\n│  $47.20    143 tasks    │  ← equal weight, 20px, side by side\n│                         │\n│  auth middleware refac… │  ← current task title, 11px mono, truncated\n└─────────────────────────┘\n```\n\n**Status orb states:**\n- `working` — green, pulsing animation (`db-pulse`)\n- `idle` — gray, no animation\n- `blocked` — red, card border glows red, reason shown below task title\n\n**Hover state:** reveals `last action` + time ago (e.g. \"completed task 0.0.88 · 4m ago\")\n\n**Click → Agent Detail Drawer** (slides in from right):\n- Full-width avatar header + name + department + model\n- Lifetime stats: total tasks, total cost, avg cost/task, avg duration, first task date\n- Last 20 task events (claim → complete/blocked, with cost, duration, HashScan link)\n- Actions: [Pause daemon] [Resume daemon] [Dispatch task…]\n- Current task detail if working: full brief title + task_id + HashScan link + elapsed time\n\n**Blocked card:**\n- Red border glow\n- `blocker_type` shown as badge (spec_gap / tool_failure / ambiguity etc.)\n- [Unblock] button visible on card — posts `task.available` back to role topic"
    },
    {
      "title": "Cost display",
      "level": 3,
      "body": "Costs come from `agent_tasks.cost_usd` (sum per agent). Two time windows shown on card:\n- This month (default)\n- Toggle to: this week / all time (toggle control above fleet grid)"
    },
    {
      "title": "Avatar images",
      "level": 3,
      "body": "Agent avatars are stored on Cloudflare Images. The URL is stored in `agent_definitions.avatar_url`. All 19 active agents need a generated avatar in a consistent style:\n- AI-generated professional headshots\n- Consistent lighting and framing across all agents\n- Stored at Cloudflare Images, referenced by URL\n- `agent_definitions` table: add `avatar_url text` column\n- Fallback: initials avatar (first letter of name, colored by department) if `avatar_url` is null\n\n---"
    },
    {
      "title": "Live Feed (right rail — always visible)",
      "level": 2,
      "body": "Real-time event stream. Newest at top. Auto-scrolls; pauses on hover."
    },
    {
      "title": "Event types",
      "level": 3,
      "body": "| Event | Indicator | Format |\n|---|---|---|\n| `task.claim` | `●` amber | `Quinn · claimed · 0.0.8807878` |\n| `task.complete` | `✓` green | `Priya · complete · $0.31 · 4m · 0.0.8807879` |\n| `task.blocked` | `✕` red | `Harper · blocked · spec_gap` |\n| `phase.complete` | `◆` green | `Phase 2 complete · 4/4 tasks` |\n| `exec.gate` | `⚑` amber | `Exec gate waiting · 0.0.8807880` |\n\nEach event row:\n- Click → jumps to task in Workflows tab (or opens exec gate in inbox drawer)\n- `task.complete` and `task.blocked` events show HashScan link (testnet icon `↗`)\n- Running cost total at top of feed: **Platform today: $4.82** (updates live)"
    },
    {
      "title": "Feed data source",
      "level": 3,
      "body": "Supabase realtime on `cluster_events` + `agent_tasks` + `agent_state` tables. Same subscription pattern as existing cockpit realtime setup.\n\n---"
    },
    {
      "title": "Tab 2 — Workflows",
      "level": 2,
      "body": "Existing project/stage/phase/task tree, restyled to match Ops Studio aesthetic. No structural changes to the data model.\n\nAdditions over current cockpit:\n- Active tasks show elapsed time + claimed_by agent avatar (16px inline)\n- Task cost shown on complete rows (`$0.31`)\n- Blocked tasks show blocker_type badge + [Unblock] action\n- Phase cards show cost subtotal (`$4.20 · 12 tasks`)\n- HashScan link on every task row (already exists, keep it)\n\n---"
    },
    {
      "title": "Six headline numbers (top row)",
      "level": 3,
      "body": "| Metric | Source |\n|---|---|\n| Tasks completed today | `agent_tasks` where `updated_at >= today` and `status = complete` |\n| Cost today | Sum of `cost_usd` where `updated_at >= today` |\n| Block rate (7d) | blocked tasks / total tasks, last 7 days |\n| Avg task cost (7d) | avg `cost_usd` last 7 days |\n| Avg task duration (7d) | avg `duration_seconds` last 7 days |\n| Queue depth | `agent_tasks` where `status = available` |"
    },
    {
      "title": "Four charts",
      "level": 3,
      "body": "**1. Cost over time — stacked area by agent**\n- X: last 30 days (daily buckets)\n- Y: cost USD\n- Each agent is a color band\n- Hover: tooltip with per-agent breakdown for that day\n- Data: group `agent_tasks` by `claimed_by` + date bucket\n\n**2. Throughput by role — bar chart**\n- X: role slugs (developer, reviewer, ba, etc.)\n- Y: tasks completed last 7 days\n- Color: same role colors as status badges\n\n**3. Block rate trend — line chart**\n- X: last 14 days\n- Y: % of tasks blocked that day\n- Single line, red fill below\n- Annotation line at 10% (target threshold)\n\n**4. Agent utilization heatmap**\n- X: hour of day (0–23)\n- Y: agent name\n- Color intensity: tasks completed in that hour over last 14 days\n- Shows: when the platform is most active, which agents work hardest at what time"
    },
    {
      "title": "Chart library",
      "level": 3,
      "body": "Use **Chart.js** (CDN, same pattern as existing Supabase CDN import). No build step. Dark theme colors from `dreamborn.css` CSS variables.\n\n---"
    },
    {
      "title": "From Agent Card Detail Drawer",
      "level": 3,
      "body": "| Action | Mechanism |\n|---|---|\n| Pause daemon | POST to VPS API `PUT /agents/:slug/pause` → writes flag to `agent_state` |\n| Resume daemon | POST to VPS API `PUT /agents/:slug/resume` |\n| Dispatch task | Form: role + goal + context → calls `dispatchTask()` via HCS post API |"
    },
    {
      "title": "From Workflows tab (task row context)",
      "level": 3,
      "body": "| Action | Mechanism |\n|---|---|\n| Cancel task | POST `task.cancelled` to task HCS topic via `HCS_POST_URL` |\n| Unblock task | POST `task.available` to role topic via `HCS_POST_URL` |"
    },
    {
      "title": "Exec Gate (inbox drawer — unchanged)",
      "level": 3,
      "body": "Approve and Block actions remain in the inbox drawer exactly as built. Exec gate events in the Live Feed are clickable and open the inbox drawer directly to that item.\n\n---"
    }
  ],
  "html_path": "artifacts/2026-04-28-ops-studio-33a22db493.html",
  "json_path": "artifacts/2026-04-28-ops-studio-33a22db493.json"
}