From 346e19b9296846dec86be8ee8327cd077619119b Mon Sep 17 00:00:00 2001 From: Chris Phillipson Date: Thu, 6 Aug 2026 02:33:20 -0700 Subject: [PATCH] docs: sync local-source pill docs with the tabbar relocation (#121) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit #121 relocated the local-source health indicator from text chips inside the Usage panel to branded icon pills in the dashboard's persistent tabbar, but shipped with no doc updates — three spots still described the old design (text chips, "above every Usage view", colored-outline styling), which would mislead anyone reading them after the fact rather than looking at the code. * USAGE-SCORECARD-METRICS.md: describes the new tabbar placement, the branded-icon-over-text-label design, and the icon-vs-status tooltip split (icon hover = what it monitors, status hover = full per-field detail). * TROUBLESHOOTING.md: "Inspect the local-source chips at the top of the dashboard Usage area" -> "Inspect the branded host-icon pills in the dashboard's tabbar (top of every view, right-aligned)". * ADR-0023 §7: rewritten for the pill/tabbar design; added a paragraph documenting the icon choice (reused verbatim from the Observability Live view's hostIcon()) and the size/contrast iteration that got there — two smaller, badge-less passes proved illegible against live screenshots before landing on the Live view's own 32px badge/20px glyph scale. Update note extended to cover this revision. One stray "chip" -> "pill" in Consequences. Verified: doc-citations test still passes (no file:line citations moved), markdown lint clean, `pnpm run check` green. --- docs/TROUBLESHOOTING.md | 2 +- docs/USAGE-SCORECARD-METRICS.md | 15 +++++-- ...sed-operations-and-explicit-degradation.md | 40 ++++++++++++++----- 3 files changed, 41 insertions(+), 16 deletions(-) diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index e7c76189..7ab37a98 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -45,7 +45,7 @@ ak sync # apply it | Observability is empty or has no ruflo/AQE nodes | Live mode tails Claude/Codex records by default, while ruflo/AQE stores are not auto-discovered | open Observability before producing activity; switch to History for retained sessions; register a trusted JSONL file with repeatable `--live-source 'surface=path'`; see [Observability](OBSERVABILITY.md) | | `status` shows `ruvnet-brain … not installed` | The RuvNet Brain (offline KB + `search_ruvnet` MCP) isn't on disk | `ak sync` (or `ak setup`) runs the installer; `npx ruvnet-brain --doctor` health-checks it | | A heal says `degraded` while the tool is still usable | The native repair failed and a fallback or older artifact remains available; exit status is authoritative | Use the reported repair command/error. The operation will not render green or advance a version stamp until a later repair exits successfully | -| Usage suddenly shows no data for one host, or a lower total than expected | Any of the four local sources (Claude/Codex transcript roots, OpenCode's SQLite store, the Codex thread ledger) can go absent, busy, corrupt, or query-incompatible; none of these are collapsed into an ordinary empty result | Inspect the local-source chips at the top of the dashboard Usage area (or `sourceHealth` in usage-index JSON) — one chip per host; the Codex chip folds its transcript-root and thread-ledger statuses together (worse status leads, both shown in its detail text). A degraded OpenCode scan retains in-window last-good cached sessions; repair the named source before treating zero as observed truth | +| Usage suddenly shows no data for one host, or a lower total than expected | Any of the four local sources (Claude/Codex transcript roots, OpenCode's SQLite store, the Codex thread ledger) can go absent, busy, corrupt, or query-incompatible; none of these are collapsed into an ordinary empty result | Inspect the branded host-icon pills in the dashboard's tabbar (top of every view, right-aligned — or `sourceHealth` in usage-index JSON) — one pill per host; the Codex pill folds its transcript-root and thread-ledger statuses together (worse status leads, both shown in the status side's tooltip). A degraded OpenCode scan retains in-window last-good cached sessions; repair the named source before treating zero as observed truth | | Observability does not show a live host process | Runtime discovery uses the numeric UID running the dashboard and is macOS/Linux-only; `sudo`, a service account, Windows, a private container PID namespace, missing `ps`/`lsof`, or restricted `/proc` changes what is visible | Run `ak dashboard` as the same ordinary OS account as the host CLI. Do not use `sudo`; use retained History on Windows and inspect OS/container process permissions when runtime presence is degraded. If the UID matches and none of the above applies, set `AK_RUNTIME_DEBUG=1` for one reproduction — stage-level evidence (survey row count, host classification per PID, nested-child exclusions, cwd resolution) goes to `$XDG_STATE_HOME/agentic-kit/runtime-debug.log` (mode 0600, bounded at 64 KiB; `AK_RUNTIME_DEBUG_FILE` to redirect it), then unset debug | | Don't want the RuvNet Brain (the ~2 GB KB download) | It's on by default | `ak setup --no-ruvnet-brain`, or set `ruvnetBrain: false` in `~/.config/agentic-kit/kit.json` | | Don't want the security surface managed | Also on by default | `ak setup --no-security` (persists `security:false`; status shows an info row and sync stops healing it) | diff --git a/docs/USAGE-SCORECARD-METRICS.md b/docs/USAGE-SCORECARD-METRICS.md index a8acf068..fb24edf2 100644 --- a/docs/USAGE-SCORECARD-METRICS.md +++ b/docs/USAGE-SCORECARD-METRICS.md @@ -81,10 +81,17 @@ secondary/corrective reads layered on top of them (`opencode`'s SQLite store, degraded OpenCode read retains in-window last-good cached sessions rather than turning an unreadable database into an observed zero. Source health is diagnostic evidence; it is not added to token or cost totals. The dashboard -renders these states as local-source chips above every Usage view, one per -HOST rather than one per field — `codex` and `codexLedger` are both Codex-only -evidence, so they fold into a single "Codex" chip carrying both sub-statuses — -so a degraded, absent, or deliberately unread source cannot be mistaken for +renders these states as branded host-icon pills in the sticky tabbar — +right-aligned, one per HOST rather than one per field. `codex` and +`codexLedger` are both Codex-only evidence, so they fold into a single Codex +pill (worse status leads; both sub-statuses live in the status side's +tooltip) rather than reading as a fourth, confusingly duplicate entry. Each +pill's icon reuses the same brand mark as the Observability Live view's +session list, so a host reads as the same glyph everywhere in the dashboard; +hovering the icon shows what it monitors, hovering the status word shows the +full detail. This placement — outside the Usage panel, in the persistent +tabbar — means a degraded, absent, or deliberately unread source stays +visible regardless of which tab is active, and cannot be mistaken for healthy empty data. See [ADR-0023 §7](adr/0023-fail-closed-operations-and-explicit-degradation.md) for why the four fields are tracked to different degrees of external documentation. diff --git a/docs/adr/0023-fail-closed-operations-and-explicit-degradation.md b/docs/adr/0023-fail-closed-operations-and-explicit-degradation.md index ab6b5df9..5a9fedf7 100644 --- a/docs/adr/0023-fail-closed-operations-and-explicit-degradation.md +++ b/docs/adr/0023-fail-closed-operations-and-explicit-degradation.md @@ -10,6 +10,10 @@ store, Codex's thread ledger) and never the primary Claude/Codex transcript roots, so a missing or unreadable `~/.claude/projects` or `~/.codex/sessions` still silently read as zero — the exact failure class this ADR exists to close, just left open on the two sources most people depend on. + Relocated the resulting indicator out of the Usage panel into the dashboard's persistent tabbar + (right-aligned, visible on every view) and replaced its host text labels with the same branded + icons the Observability Live view already uses, after the original chip design proved illegible + and was redesigned through several rounds against live screenshots. - **Deciders:** agentic-kit maintainers - **Related:** [issue #111](https://github.com/pacphi/agentic-kit/issues/111), [ADR-0008](0008-guidance-target-scope-split.md), @@ -114,10 +118,11 @@ its sandbox and approval policy. ### 7. Usage source degradation is visible in the dashboard, for all four local sources -The Usage API's `sourceHealth` field is rendered as persistent local-source chips across Usage -views. `ok`, `absent`, `degraded`, and `not-read` remain distinct, and bounded reasons such as -`busy`, `corrupt`, `query`, `schema`, `sandboxed-roots`, or an fs error code (`ENOENT`, `EACCES`, -`ENOTDIR`) are visible without entering raw JSON. +The Usage API's `sourceHealth` field is rendered as persistent local-source pills in the +dashboard's sticky tabbar (right-aligned, visible on every view once Usage data has loaded once — +not confined to the Usage panel). `ok`, `absent`, `degraded`, and `not-read` remain distinct, and +bounded reasons such as `busy`, `corrupt`, `query`, `schema`, `sandboxed-roots`, or an fs error code +(`ENOENT`, `EACCES`, `ENOTDIR`) are visible without entering raw JSON. `sourceHealth` originally covered only the two sources with a *secondary, corrective* read layered on top of a primary parse — OpenCode's SQLite store and Codex's own thread ledger — because those @@ -141,12 +146,25 @@ fabricated; `rootHealth()` performs a real `readdirSync` against a real path exa existing checks, just one level up the trust stack from the two sources already wired. `sourceHealth` now reports `claude`, `codex`, `opencode`, and `codexLedger`. The dashboard renders -this by HOST, not by field: three chips for the three supported hosts (Claude, Codex, OpenCode), not -four. `codex` and `codexLedger` are both Codex-only evidence, so they fold into one "Codex" chip — -its status is the worse of the two, and both sub-statuses stay visible in the chip's detail text -(e.g. `Codex: degraded — transcripts: ok · ledger: corrupt`). No evidence is dropped; the API keeps -four independently-diagnosable fields, the UI just groups by the thing the operator actually cares -about (which host needs attention), matching how Claude and OpenCode already render as one chip each. +this by HOST, not by field: three pills for the three supported hosts (Claude, Codex, OpenCode), not +four. `codex` and `codexLedger` are both Codex-only evidence, so they fold into one Codex pill — its +status is the worse of the two, and both sub-statuses stay reachable via the status side's tooltip +(e.g. hovering "degraded" shows `Codex: transcripts: ok · ledger: corrupt`). No evidence is dropped; +the API keeps four independently-diagnosable fields, the UI just groups by the thing the operator +actually cares about (which host needs attention), matching how Claude and OpenCode already render +as one pill each. + +Each pill leads with a branded host icon rather than a text label — the same mark +`live/client.mjs`'s `hostIcon()` uses in the Observability Live view's session list (Anthropic's +asterisk, OpenAI's Blossom, OpenCode's square), reused verbatim so a host reads as the same glyph +everywhere in the dashboard. The icon sits in a circular badge (`var(--bg)` fill, 1px border) at +32px/20px glyph — matching the Live view's own proven scale — after two smaller, badge-less passes +proved illegible against live screenshots: a floating icon with nothing to contrast against, and +Codex's multi-lobed Blossom geometry specifically, both need real size and a defined edge to resolve. +Hovering the icon shows what it monitors (its transcript path or store); hovering the status word +shows the full per-field detail. The pill itself uses a solid `var(--panel-2)` background matching +the segmented tab control's own look — no border, state shown via status-text color/weight — rather +than the colored-outline chip style originally shipped. ### 8. Clean-machine proof is isolated at every mutable boundary @@ -168,7 +186,7 @@ setup on `macos-latest` with all global packages and user/project files under `r - Some formerly best-effort writes now fail. This is deliberate: when ak promises a backup, mutation without one is a correctness failure. - An unreadable `~/.claude/projects` or `~/.codex/sessions` (permissions, a corrupt filesystem entry, - the path replaced by a non-directory) now renders as a degraded local-source chip instead of a + the path replaced by a non-directory) now renders as a degraded local-source pill instead of a quietly empty Usage scorecard; all four local sources share one status vocabulary. ## References