olares-dashboard

# dashboard (overview + applications, AI-agent first)

**CRITICAL — before doing anything, load the `olares-shared` skill first (profile selection, login, token refresh, auth-error recovery). Flag reference: `olares-cli dashboard --help`.**

> **Source of truth for flags is always `olares-cli dashboard --help` (global flags) and `olares-cli dashboard <verb> --help` (per-leaf flags).** This file only carries what `--help` cannot give: the dual-shape JSON envelope contract, three-state empty-data semantics, capability gates, watch / window rules, and the verb index.

## When to use

This subtree is an **AI-agent-first JSON mirror of the Olares Dashboard SPA's Overview and Applications routes**. Use it when:

- The user asks for runtime metrics: CPU / memory / disk / pods / network / fan / GPU.
- The user wants the workload-grain or application-grain resource ranking.
- The user wants the JSON form of what the SPA Overview / Applications pages show.
- The user wants `--watch` for live-tailing one of the above.
- Errors: `fan is only available on Olares One devices`, `gpu data temporarily unavailable`
- Empty-data reasons: `no_<feature>_integration`, `no_<feature>_detected`, `vgpu_unavailable`; windows: `--since` vs `--start`/`--end`

> Anything outside this scope -> see the **Skill suite map** in [`../olares-shared/SKILL.md`](../olares-shared/SKILL.md) (already loaded as the suite prerequisite).

> **Mental model:** dashboard answers *"what's the resource usage and health"*. For inventory and lifecycle, route elsewhere.

## JSON envelope (two shapes, frozen)

Every command emits exactly one of two shapes. The choice is fixed per command. **Agents pin on `kind` and `meta.empty_reason`; the CLI does not change these values across releases.**

### Shape A — leaf items

```json
{
  "kind": "dashboard.<area>.<verb>",
  "meta": {
    "fetched_at": "...",
    "iteration": 0,
    "recommended_poll_seconds": 60,
    "empty": false,
    "empty_reason": "",
    "error": "",
    "http_status": 200
  },
  "items": [
    { "raw": { /* upstream wire shape */ }, "display": { /* table-friendly strings */ } }
  ]
}
```

- `raw` is the canonical machine-friendly shape — numbers as numbers, timestamps as Unix seconds, temperatures as raw Celsius. **Agents pin on `raw`.**
- `display` is human-presentation only, formatted with current `--temp-unit` / `--timezone`. **Agents MUST NOT pin on `display`** — it can change with locale or format fixes.
- `meta.recommended_poll_seconds` — the page-level cadence the SPA uses; respect it when driving `--watch`.
- `meta.iteration` — 1-based, present in every `--watch` payload.

### Shape B — sections envelope

Used by **parent commands that aggregate multiple sub-views**:

| Parent command | Sections |
|---|---|
| `dashboard overview` | `physical` / `user` / `ranking` |
| `dashboard overview disk` | `main` / `partitions` |
| `dashboard overview fan` | `live` / `curve` |
| `dashboard overview gpu` | `graphics` / `tasks` |

```json
{
  "kind": "dashboard.overview",
  "meta": {...},
  "sections": {
    "physical": { "kind": "dashboard.overview.physical", "meta": {...}, "items": [...] },
    "user":     { "kind": "dashboard.overview.user",     "meta": {...}, "items": [...] },
    "ranking":  { "kind": "dashboard.overview.ranking",  "meta": {...}, "items": [...] }
  }
}
```

Sections are fetched **concurrently**. A single failed section degrades to `meta.error="..."` on that section — **the others still return**. Surface partial outputs to the user, don't blackout the whole envelope.

To enumerate every kind live: `olares-cli dashboard schema -o json`.

## Three-state empty data (`meta.empty_reason`)

Optional hardware (GPU / fan) and optional integrations have three legitimate "empty" states. The CLI distinguishes them so agents can branch without parsing prose.

| Upstream | `meta.empty` | `meta.empty_reason` | Meaning |
|---|---|---|---|
| HTTP 404 | `true` | `no_<feature>_integration` | Integration absent (e.g. HAMI vGPU not installed) |
| HTTP 200, empty body | `true` | `no_<feature>_detected` | Integration present but hardware empty |
| HTTP 200, non-empty | `false` | `""` | Normal — items[] populated |
| Any 4xx / 5xx | n/a (envelope `meta.error`) | n/a | Real failure |

**Forbidden**: turning a 404 into an error, or merging the two reasons into a single "empty=true" string. Agents currently key on the reason.

Specific reason values:

| Reason | Where |
|---|---|
| `not_olares_one` | fan default / live / curve (active device's `device_name` is not `Olares One`) |
| `no_fan_integration` | fan live (HTTP 404 fallback) |
| `no_vgpu_integration` | gpu list / tasks / get / task (HTTP 404) |
| `vgpu_unavailable` | gpu list / tasks / get / task (HTTP 5xx); `meta.error` carries the upstream message, `meta.http_status` the original status |
| `no_gpu_detected` | gpu list / tasks / get / task (HTTP 200, empty body) |

## Capability gates

The fan / GPU subtrees mirror SPA gates, but with **two different strengths**.

### Hard gate — fan (Olares One only)

`overview fan *` returns an empty envelope BEFORE any fetch on non-Olares-One hardware:

```json
{
  "kind": "dashboard.overview.fan.live",
  "meta": {
    "empty": true,
    "empty_reason": "not_olares_one",
    "note": "Fan / cooling integration is only available on Olares One devices",
    "device_name": "DIY-PC"
  },
  "items": []
}
```

Exit code is still `0` — this is a predictable state, not a failure.

### Soft gate — GPU (advisory)

The CLI ALWAYS calls HAMI for GPU verbs. The SPA-equivalent "would-have-been-hidden" reason is recorded as `meta.note` and (in table mode) as a one-liner on stderr. The actual `meta.empty` / `empty_reason` are decided by HAMI's response.

Advisories you may see in `meta.note`:

- `GPU sidebar entry is hidden for non-admin profiles in the SPA; HAMI was queried directly`
- `no node carries gpu.bytetrade.io/cuda-supported=true; SPA hides the GPU card. HAMI was queried directly`

When BOTH a HAM