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

| User intent | Use instead |

|---|---|

| "What pods / workloads / nodes / namespaces exist?" (object inventory) | olares-cluster |

| "Install / start / stop an Olares app" | olares-market |

| "Configure my user settings" | olares-settings |

| "Browse files / drives" | olares-files |

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

| Parent command | Sections |

|---|---|

| dashboard overview | physical / user / ranking |

| dashboard overview disk | main / partitions |

| dashboard overview fan | live / curve |

| dashboard overview gpu | graphics / tasks |

{
  "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__integration | Integration absent (e.g. HAMI vGPU not installed) |

| HTTP 200, empty body | true | no__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:

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

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 --help.

| Verb | Purpose | --help first, then... |

|---|---|---|

| applications (alias apps) | Workload-grain application table (mirrors SPA Applications page) | olares-cli dashboard applications --help |

| overview (no subverb) | Default sections envelope (physical + user + ranking) | references/olares-dashboard-overview.md |

| overview