# Step 7 Design: Home23 Dashboard

> Approved 2026-04-07. Faithful port of ReginaCosmo dashboard.

**Goal:** A minimal, always-on dashboard that shows what your agents are thinking and doing. Dark theme, interactive tiles, tab navigation between agents, evobrew button for power users.

**Reference:** ReginaCosmo dashboard at `http://192.168.7.131:3508` (cosmo-home_2.3 ecosystem).

---

## Layout

Faithful port of ReginaCosmo's proven design:
- Dark theme (deep navy/black, subtle borders, muted text)
- Header bar with Home23 branding, time display, active status indicator
- Status pills below header (sensor readings, cycle count, last update)
- Tab bar for navigation (Home overview + per-agent tabs + evobrew button)
- Card grid for tiles (responsive, 3-column on desktop)
- Brain Log section at bottom (scrolling thought feed)

## Serving

The dashboard UI is served by the existing engine dashboard server (`engine/src/dashboard/server.js`). No new process — the static HTML/CSS/JS is added to the dashboard's static file serving path. Each agent's dashboard is available at its dashboard port (e.g., `http://localhost:5002`).

**Tech:** Vanilla HTML/CSS/JS. No React, no build step. Same approach as ReginaCosmo. Fetches data from the dashboard API routes that already exist on the same port.

## Tabs

**Home tab** — overview of all agents:
- One status card per agent showing: name, status (online/offline), cycle count, last thought timestamp, brain node count
- Quick-glance health of the entire system

**Per-agent tabs** — full tile view for each agent:
- Shows the 4 default tiles plus any custom tiles
- Tab label is the agent's display name
- Data fetched from that agent's dashboard API

**Evobrew button** — right-aligned in the tab bar:
- Navigates to the evobrew URL (configured in settings)
- Simple link, no animation (polish later)

## Default Tiles

Every agent gets these 4 tiles:

### 1. Thoughts
- Shows the latest inner thought from the cognitive engine
- Displays: thought text (truncated), role (curiosity/analyst/critic), cycle number
- Auto-refreshes on interval
- API: `GET /api/thoughts?limit=1` (existing endpoint)

### 2. Vibe
- AI-generated image seeded from brain thoughts
- Displays: image, descriptive caption
- Generated periodically by the engine's image generation (if configured)
- Placeholder when no image exists yet

### 3. System
- Key metrics at a glance
- Displays: uptime, thought count, cycle count, brain node count, last thought time
- API: `GET /api/state` (existing endpoint)

### 4. Brain Log
- Scrolling feed of recent thoughts (last 20)
- Each entry: timestamp, role, thought text preview
- Auto-refreshes
- API: `GET /api/thoughts?limit=20` (existing endpoint)

## Custom Tiles (deferred)

User-configurable tiles (weather, sauna, custom API endpoints) are deferred to the Settings UI step. The tile system should be extensible — a tile is just an HTML card that fetches data from a URL on an interval.

## Data Flow

```
Dashboard HTML (static, served by dashboard server)
  ├─ fetch('/api/state')      → System tile
  ├─ fetch('/api/thoughts')   → Thoughts tile + Brain Log
  ├─ fetch('/api/memory')     → Brain stats for Home tab
  └─ WebSocket (engine WS port) → live event updates (optional, for real-time thought feed)
```

All API routes already exist on the dashboard server. The frontend just calls them via relative URLs (same origin, no CORS issues).

## Auto-Refresh

- System tile: poll every 30 seconds
- Thoughts tile: poll every 60 seconds (or subscribe to engine WS `thought_generated` events)
- Brain Log: poll every 60 seconds
- Home tab agent cards: poll every 30 seconds

## Multi-Agent on Home Tab

The Home tab needs to show status for all agents. Challenge: each agent's dashboard runs on a different port. The Home tab needs to know about all agents and their ports.

Solution: the dashboard frontend reads a manifest of agents. Two options:
- A small JSON file (`config/agents.json`) generated by the CLI alongside ecosystem.config.cjs
- Or the frontend reads from a known endpoint that lists all agents

The CLI's `agent create` already scans instances — it can write this manifest. The dashboard server serves it as a static file.

## Files

### Created new

| File | Purpose |
|---|---|
| `engine/src/dashboard/home23.html` | Main dashboard page (HTML) |
| `engine/src/dashboard/home23.css` | Dashboard styles (dark theme) |
| `engine/src/dashboard/home23.js` | Dashboard logic (fetch, tiles, tabs, refresh) |
| `config/agents.json` | Agent manifest (name, ports, display name) — generated by CLI |

### Modified

| File | Purpose |
|---|---|
| `engine/src/dashboard/server.js` | Add route to serve home23.html as default page |
| `cli/lib/generate-ecosystem.js` | Also generate config/agents.json |

## Verification

Step 7 is done when:

1. Navigate to `http://localhost:5002` and see the dashboard
2. Home tab shows status cards for all agents
3. Per-agent tab shows 4 tiles with live data
4. Thoughts tile updates with engine's latest thought
5. System tile shows uptime, cycles, brain nodes
6. Brain Log scrolls recent thoughts
7. Evobrew button navigates to evobrew URL
8. Auto-refresh keeps data current without manual reload
9. Dashboard works for both test-agent and cosmo simultaneously

---

## What's Next

Step 8: Evobrew integration — package evobrew with Home23, wire to agent brain, add dashboard-to-evobrew transition.
