dashboard (overview + applications, AI-agent first)

CRITICAL — before doing anything, MUST use the Read tool to read ../olares-shared/SKILL.md for profile selection, login, automatic token refresh, and the auth-error recovery table.

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.

Routing

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.

Sibling-skill routing:

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

{
  "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:

{
  "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.

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:

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:

{
  "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 HAMI failure AND a soft advisory apply, meta.note is "<advisory> | <hami-explanation>".

Agent decision tree (recommended)

inspect meta.empty + meta.empty_reason + meta.note →
  not_olares_one        → skip the fan subtree on this device
  no_*_integration      → upstream component absent (HAMI / capi system fan)
  vgpu_unavailable      → transient: retry; check meta.http_status / meta.error
  no_*_detected         → integration up but hardware empty
  (none) + meta.note    → data is present but the SPA would have hidden the entry; surface the note to the user
  (none) + (no note)    → items[] populated, proceed normally

Verb index

For flags & examples, always start with olares-cli dashboard <verb> --help.

For --watch, --since / --start/--end, --user, --timezone, and the NDJSON contract, see references/olares-dashboard-watch.md.

Global flags (cross-cutting)

These are bound on the dashboard root and inherited by every leaf. Defaults are sensible — don't pass them unless the user explicitly asks for the non-default.

Exit codes & error semantics

• Exit 0 for every gated / advisory / empty path — these are predictable states, not failures.
• Exit non-zero only on:
  • Auth-class errors (ErrTokenInvalidated / ErrNotLoggedIn) — propagated immediately
  • 3 consecutive iteration failures inside a --watch loop
  • A real upstream meta.error on a one-shot invocation
• Stderr carries one human-readable line in non-JSON modes. JSON / NDJSON modes stay silent on stderr — agents read stdout exclusively.

Common errors

For the full auth-error matrix see ../olares-shared/SKILL.md.