# Assistive Surfaces Reference — box.muse-dev.online

> **Box is the main surface.** All operator work goes through Box (`box.muse-dev.online`). The web UI, `box` CLI, and agents share the same API endpoints. No UI-only powers.

This guide provides autonomous agents and operators with detailed maps of the visual DOM, interactive controls, API backends, and assistive interaction recipes for `box.muse-dev.online`.

---

## 1. Global Layout & Authentication

* **Production URL**: `https://box.muse-dev.online/`
* **Google Cloud VM**: `34.139.37.135`
* **Authoritative Compute Host**: `bl` (`100.123.153.75`)
* **Operator PIN**: `3128` (establishes `ops_session` cookie via `POST /api/ops/login`)
* **Agent Authentication**: Header `Authorization: Bearer <operator-token>` or SSH-keygen signature.

### Layout Wireframe
```text
+----------------------------------------------------------------------------------+
| [BOX] Fleet Console   box.muse-dev.online  ● [pulse]    [</> API]  [◐ theme]    |
+----------------------------------------------------------------------------------+
| [Fleet Pulse]   [DMs & Work Orders (N)]   [Timers & Jobs]   [Loop & Strategy (N)]|
+----------------------------------------------------------------------------------+
|                                                                                  |
|  <Active Pane Content: Cards / Tables / Modals / Curldrawer>                     |
|                                                                                  |
+----------------------------------------------------------------------------------+
```

---

## 2. Views & Navigation Map

### 2.1 Fleet Pulse (`#tab-dashboard`)
* **Tab Button**: `.tab-btn[data-tab="dashboard"]`
* **Key Selectors**:
  - `#fleet-grid`: Grid container for node cards.
  - `.node-card`: Card representing an agent (`muse`, `pip`, `646`, `opm`).
  - `.node-badge`: Status badge (`UP`, `WARN`, `DOWN`).
  - `#fleet-pulse`: Global heartbeat animation.
* **REST API**:
  - `GET /api/box/fleet`
  - Returns array of `{ node, netns, peer_ip, cdp_port, proc_alive, title, latency_ms }`.

### 2.2 DMs & Work Orders (`#tab-dms`)
* **Tab Button**: `.tab-btn[data-tab="dms"]`
* **Key Selectors**:
  - `#dms-table`: Log stream table.
  - `#dms-tbody`: Dynamic row container.
  - `#filter-search`: Search text filter input.
  - `.filter-agent-chip`: Filter by agent (`all`, `super`, `muse`, `pip`, `646`, `opm`).
  - `.filter-kind-chip`: Filter by message kind (`all`, `workorder`, `ack`, `chat`).
* **REST API**:
  - `GET /api/box/dm/log?limit=50`
  - `POST /api/box/dm/send`

### 2.3 Timers & Scheduled Jobs (`#tab-jobs`)
* **Tab Button**: `.tab-btn[data-tab="jobs"]`
* **Key Selectors**:
  - `#jobs-table`: Systemd user timer table.
  - `.btn-trigger`: Direct hot-trigger button (`▶ Run`).
  - `.badge-active`: Active/inactive state indicator.
* **REST API**:
  - `GET /api/box/timers`
  - `POST /api/box/jobs/{name}/trigger` (Returns `202 Accepted` immediately).

### 2.4 Loop & Strategy Matrix (`#tab-loops`)
* **Tab Button**: `.tab-btn[data-tab="loops"]`
* **Key Selectors**:
  - `#loop-health-badge`: Real-time health verdict (e.g. `HEALTHY (89%)`).
  - `#loops-grid`: Cards for active open loops and deadlines.
  - `#strat-table`: Table of strategy escalation rules.
  - `#vars-table`: Interactive table of runtime variables with inline edit buttons.
* **REST API**:
  - `GET /api/box/loop/health`
  - `GET /api/box/loop/status`
  - `GET /api/box/loop/vars`
  - `POST /api/box/loop/vars`

---

## 3. Assistive Interaction Recipes

### Recipe A: Querying Fleet Health via CLI
```bash
# High level overview
box fleet
# Directly query docs database for surface selectors
box docs surfaces dashboard
```

### Recipe B: Hot-Triggering a Job via API
```bash
# Asynchronously trigger job
curl -sk -X POST https://box.muse-dev.online/api/box/jobs/box-http-health/trigger
```

### Recipe C: Resolving a Blocked Modal Dialog
```bash
# Check if any agent is held on an approval dialog
box approvals check
# Inspect dialog details
box approvals inspect pip
# Approve request
box approvals allow pip
```