feat: unify dashboard observability and provider UX

README.md

@@ -93,7 +93,7 @@ command always works.)
 | **setup** | Installs/updates ruflo + agentic-qe + the **agentdb** CLI globally (handling npm ≥11.17's `allow-scripts` so natives build; agentdb is pinned to ruflo's bundled version so the shared learning store stays coherent), installs the **RuvNet Brain** (an offline knowledge base over the rUv stack, powering the `search_ruvnet` MCP — a ~2 GB one-time download, prompted; skip with `--no-ruvnet-brain`), deploys the token-audit skill, merges the managed guidance blocks into the machine-wide guidance files (`~/.claude/CLAUDE.md`, plus `~/.codex/AGENTS.md` on codex machines), offers one-time MCP registration (user scope, with a tool-family picker), and — inside a repo — initializes the project: sanitized `ruflo init`, absolute memory-path pin, a **verified** store→disk write, statusline footer, and a background daemon with **local-only ($0) workers** (token-spending AI workers stay opt-in behind upstream's machine-wide budget). Project scope triggers on a `.git` directory in the current folder; without one it's skipped with a note. `--project` forces it anyway (e.g. a not-yet-`git init`-ed folder), `--minimal` skips it, `--yes` accepts all prompts (non-interactive), `--no-aqe` / `--no-ruvnet-brain` / `--no-security` disable those subsystems, and `--reconfigure` re-offers MCP registration. `--codex` enables + installs the Codex host during setup (ambidextrous dual-host mode; both hosts then run at once), and `--primary-host claude\|codex` picks which host leads (codex implies `--codex`). |
 | **status** | Per-subsystem ✓/⚠/✗ (versions, the kit's own version, **ruvnet-brain** (present + release drift, or "not installed"), natives (agentdb copies **and** ruflo's own memory runtime — the one `npx ruflo memory` loads — load-tested for a native better-sqlite3, not just the agentdb dirs), **memory-pin** (warns when `CLAUDE_FLOW_DB_PATH` points off the live DB), security, learning, aqe/RVF, **agentdb** (CLI present + coherent with ruflo's bundled version, or a store-skew warning), MCP, **hosts** (claude/codex/opencode version + install method; the Claude/Codex **primary** marked and failed when absent), **providers** (host wiring + aqe fallback chain, or "drifted"/claude-only default), **routing** (the persisted activity host+model policy; only Claude/Codex routes project into AQE), daemons, guidance-file blocks (`~/.claude/CLAUDE.md`, project `AGENTS.md`, and `~/.codex/AGENTS.md` on codex machines), statusline), each drift row naming what `sync` would do about it — plus a **health-history** line that flags regressions since the last sync (learning shrank, native slots dropped, drift/security backslid). |
 | **sync** | The one convergence verb: upgrades first when a new release exists, then re-heals everything an upgrade wipes, then re-checks and reports. Included in that heal: it **installs any enabled frontier host** (claude/codex/opencode) that's entirely absent — never touching an external (mise/brew/native) install — and **re-applies provider wiring** (the `ENABLE_*` host env, OpenCode's native configuration, the aqe fallback chain, and ruflo API providers) whenever it has drifted — and, on a dual-host project, **seeds/heals the Claude/Codex default routing policy** (materializing eligible routes into agentic-qe's `agentOverrides`, e.g. after an aqe upgrade first makes it eligible). It also **installs/repins the standalone `agentdb` CLI** to ruflo's bundled version (keeping the shared cognitive store coherent) and appends a **health-history snapshot** so `status` can flag regressions across syncs. It also **re-runs the RuvNet Brain installer** to pull the latest release when the on-disk KB has drifted (or installs it if absent, when enabled). It also **self-updates the kit**: when a newer `@pacphi/agentic-kit` exists it installs it as the *last* step (the new code applies from the next `ak` run, never mid-sync). Prerelease installs (`4.0.0-alpha.*`) track the `next` npm dist-tag as well as `latest`, so alphas see their successors; stable installs only ever follow `latest`. `--no-upgrade` skips the self-update along with the package upgrades. |
-| **dashboard** | Opens a read-only local web dashboard (`127.0.0.1:7431`, localhost-only, never detaches) with seven tabs: **Overview · Hosts & Routing · Providers · Runtime · Intelligence · Usage · Live**. The first five render `ak status` health and routing; Usage indexes local Claude/Codex/OpenCode transcripts on demand and can display a separately cached OpenRouter account-analytics block. That block never changes local transcript/session/host totals; the dashboard itself never fetches it. Live groups work by project, then host-branded root sessions with nested agent/worker threads and independently evidenced provider/model metadata, and pairs an interactive agent/tool execution canvas with a rich, server-masked transcript stream. Active sessions can be followed live or reviewed with synchronized play/pause/seek; completed sessions remain available for bounded playback. Live contains no chat or control plane. Ruflo and agentic-qe stores are not auto-discovered; register each trusted structured JSONL file with repeatable `--live-source 'surface=path'` (`surface` is `ruflo` or `aqe`). The page is self-contained and offline-first (no internet fetches; local files and loopback subprocesses/endpoints only). A fresh **per-session token** is minted at startup and required by every `/api/*` route (`x-dash-token` header; the launch URL carries it in the `#` fragment, same contract as `ak admin`) — this page serves full transcript text, so it is gated the same way admin already gated GitHub/npm stats. See [Live Sessions](docs/LIVE-SESSIONS.md) for coverage, syntax, and privacy limits. **Auto-opens your browser** (`--no-open` for headless/SSH); `--port N` changes the port; tabs deep-link (`#live`) and persist. Stop with Ctrl-C. (Also available as `ak x dashboard`.) |
+| **dashboard** | Opens an observation-only local web dashboard (`127.0.0.1:7431`, localhost-only, never detaches) with three primary areas: **Overview · Usage · Observability**. One fixed, left-aligned secondary rail exposes Overview's Summary/Hosts & Routing/Providers/Runtime/Intelligence views, Usage's Scorecard/Limits/Findings/Sessions/Transcript views, and Observability's Live/History scopes. Canonical deep links are hierarchical (`#overview/summary`, `#usage/sessions`, `#usage/<session-id>`, `#observability/live`); arrow keys plus Home/End operate focused tab rows. Usage indexes local Claude/Codex/OpenCode transcripts on demand. Observability groups eligible sessions by project and pairs an interactive agent/tool execution canvas with masked transcript or review evidence; its Session Stream can collapse without disconnecting so Agent activity gets more room. Live shows only current roots; History shows only retained non-live roots. A bounded owner-only cache retains safe last-recorded workspace context; no dashboard action mutates agents or repositories. Ruflo and agentic-qe stores are opt-in through repeatable `--live-source 'surface=path'`. The page is self-contained, offline-first, localhost-only, and protected by a per-session token. See the [Dashboard guide](docs/DASHBOARD.md) and [Observability guide](docs/OBSERVABILITY.md). **Auto-opens your browser** (`--no-open` for headless/SSH); `--port N` changes the port. Stop with Ctrl-C. (Also available as `ak x dashboard`.) |
 | **usage** | Reads provider-account analytics from local cache (`ak usage status`) or performs one explicit OpenRouter management-API refresh (`ak usage refresh openrouter`). Refresh requires `OPENROUTER_MANAGEMENT_KEY`, writes a credential-free mode-`0600` cache, and discards endpoint/user/key/session identifiers. `status` and dashboard reads make no network request. OpenRouter account rows have no grounded host/session/project correlation and are never merged into transcript totals. |
 | **admin** | Opens the **maintainer admin** (`127.0.0.1:7432`, localhost-only, foreground) — the project-telemetry sibling of `dashboard`, with the same dark/light visual theme and persisted theme preference: unique repo visitors and cloners (GitHub traffic API, needs a push-access token via `GITHUB_TOKEN`/`GH_TOKEN`/`gh auth token` — panels degrade honestly without one), contributors and watchers, npm download momentum (last 7d vs prior 7d, sparklines — shown as trend only, never an absolute reach number, since mirrors/CI inflate the raw count), latest CI run status and open Dependabot alerts, a **"since you last looked"** delta strip over a local baseline, open issues/PRs from others (oldest first), and external humans ranked by recency (bots excluded). Access is gated by a **per-session token** carried in the URL fragment and sent header-only; the page makes **zero external fetches** (the server proxies GitHub/npm; your credential never reaches the page or the payload). Where `dashboard` is offline-first, `admin` does deliberate GitHub/npm egress — that contract split is why they're siblings, not tabs. `--port N`, `--no-open`; Ctrl-C stops. (Also available as `ak x admin`.) |
 | **run** | **Canonical execution surface.** Executes the template vocabulary through host-neutral supervised adapters. It accepts an explicit OpenCode route (persisted or `--route`) alongside Claude/Codex; `--dry-run` prints the exact static plan (with each worker's escalation ladder); at runtime, successful dependencies pass runtime-only, sanitized handoffs capped at 2 KiB each/8 KiB fan-in, never exposed in public JSON. A handoff may cross hosts/vendors and must exclude secrets, credentials, raw logs, and transcript excerpts. `--escalate` advances a failed worker one rung of its route's ladder per attempt (bounded by the ladder; permission/consent and uncertain results are never escalated). `--timeout` is one absolute readiness→prepare→launch→observe budget per attempt, while separately bounded teardown proves whether resources terminated. An OpenCode worker runs an isolated loopback server with ephemeral basic authentication, returns only normalized observed facts, and aborts instead of approving a permission request. `ak run` does not turn OpenCode into an AQE provider or primary host. |
@@ -238,6 +238,9 @@ Design record: [docs/adr/0017-opencode-host.md](docs/adr/0017-opencode-host.md).
 
 [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) — symptom → `agentic-kit` command.
 
+[docs/DASHBOARD.md](docs/DASHBOARD.md) — dashboard navigation, deep links, keyboard behavior, and
+the meaning of each primary and secondary view.
+
 ## How tools are managed
 
 [docs/MANAGED-TOOLS.md](docs/MANAGED-TOOLS.md) — the consistency contract every
@@ -248,7 +251,7 @@ with the per-tool table and the checklist for adding a new tool.
 ## Domain design
 
 [docs/ddd/](docs/ddd/) defines the shared language, bounded contexts, and invariants behind hosts,
-inference providers, bindings, routing, orchestration, evidence, usage, and Live Sessions. ADRs
+inference providers, bindings, routing, orchestration, evidence, usage, and Observability. ADRs
 explain why decisions were made; the domain documents define what those concepts mean across the
 codebase.
 

docs/DASHBOARD.md

@@ -0,0 +1,127 @@
+# Dashboard
+
+`ak dashboard` opens an observation-only local diagnostic workspace. It binds to loopback, requires
+the per-session dashboard token for every API route, and does not mutate configuration, agents, or
+repositories.
+
+```bash
+ak dashboard
+
+# Do not open a browser automatically.
+ak dashboard --no-open
+```
+
+The dashboard has exactly three stable primary areas: **Overview**, **Usage**, and
+**Observability**. The row directly below them is one fixed, left-aligned secondary navigation rail.
+Its position does not move when the primary area changes; only the choices inside it change.
+
+## Navigation and deep links
+
+| Primary area | Secondary view | Canonical hash | Heading | What it answers |
+|--------------|----------------|----------------|---------|-----------------|
+| Overview | Summary | `#overview/summary` | System overview | Overall readiness, configuration health, and items needing attention |
+| Overview | Hosts & Routing | `#overview/hosts` | Hosts & routing | Enabled execution hosts, activity assignments, primary-host policy, and escalation paths |
+| Overview | Providers | `#overview/providers` | Inference providers | Provider bindings, availability, provenance, and configuration health |
+| Overview | Runtime | `#overview/runtime` | Runtime health | Local services, MCP connections, processes, and operational readiness |
+| Overview | Intelligence | `#overview/intelligence` | Intelligence & learning | Memory, learned patterns, quality feedback, and improvement signals |
+| Usage | Scorecard | `#usage/score` | Usage scorecard | Token consumption, API-equivalent cost, efficiency, and trends |
+| Usage | Limits | `#usage/limits` | Provider limits | Current provider windows, reset timing, and available capacity |
+| Usage | Findings | `#usage/findings` | Usage findings | Actionable anomalies, efficiency opportunities, and evidence-backed recommendations |
+| Usage | Sessions | `#usage/sessions` | Session usage | Retained sessions grouped by project, category, duration, tokens, and cost |
+| Usage | Transcript | `#usage/transcript` | Transcript detail | The selected session's locally retained, server-masked evidence |
+| Observability | Live | `#observability/live` | Observability · Live | Projects and roots with current presence or fresh meaningful activity |
+| Observability | History | `#observability/history` | Observability · History | Retained roots that are not currently Live |
+
+Opening a transcript replaces `transcript` with the URL-encoded session ID:
+`#usage/<session-id>`. These hashes select state inside the one page; they do not create separate
+servers or weaken the dashboard token boundary.
+
+### Keyboard behavior
+
+The primary row and every secondary row are ARIA tab lists with one selected tab in the keyboard
+order.
+
+- `Left Arrow` and `Right Arrow` select and focus the previous or next tab, wrapping at the ends.
+- `Home` selects and focuses the first tab in that row.
+- `End` selects and focuses the last tab in that row.
+- `Tab` moves into or out of the active row normally.
+- `Enter` or `Space` activates ordinary buttons such as expanders, chevrons, and map controls.
+
+Every view supplies its own heading and short description beneath the shared navigation. Badges on
+Overview child views remain scoped to those views, while Summary aggregates the items that need
+attention.
+
+## Overview
+
+Overview keeps status and routing in one health-first area:
+
+- **Summary** presents the overall verdict, attention items, and subsystem map.
+- **Hosts & Routing** presents execution-host health, the primary-host policy, per-activity routes,
+  escalation paths, and routed host models. A configured route is assignment intent, not evidence
+  of which inference provider served a particular session.
+- **Providers** presents inference-provider bindings and their configuration provenance.
+- **Runtime** presents operational services, processes, and MCP readiness.
+- **Intelligence** presents memory, learning, and quality-improvement signals.
+
+## Usage
+
+Usage loads lazily when first opened. Scorecard, Limits, Findings, Sessions, and Transcript share the
+same secondary rail; the 7/14/30-day filters remain aligned to its right.
+
+### Reading a session row
+
+Projects begin collapsed. Expand a project to reveal its session rows. Each row deliberately keeps
+identity axes separate:
+
+- the compact host badge states only the execution host: Claude Code, Codex, or OpenCode;
+- the leading chevron expands an independent detail strip without opening the transcript;
+- the detail strip reports execution host, inference provider, provider provenance, model or models,
+  classification basis, token details, tools, and flags;
+- clicking the rest of the row opens the locally retained masked transcript.
+
+Host, inference provider, provenance, and model are independent facts. The dashboard never derives a
+provider from a host name or model string. Codex `session_meta.model_provider` and equivalent
+`turn_context` evidence are reported as **observed**. Native Claude transcript history does not name
+the serving provider, so a historical row may honestly show **Not recorded**. That is missing
+evidence, not a claim that Claude Code was served by Anthropic or by any provider inferred from its
+model.
+
+Usage transcript masking happens on the server. Redaction is marked, there is no reveal or export
+control, and the original masked value never reaches the browser. See
+[ADR-0009](adr/0009-usage-scorecard-local-transcript-analytics.md) for the full evidence and pricing
+contract.
+
+## Observability
+
+Observability separates navigation scope from playback state:
+
+- **Live** and **History** are mutually exclusive secondary views.
+- **Follow Live** and **Review** describe how one selected session is presented.
+- switching between Live and History clears incompatible project/session selection.
+
+Its workspace contains the project/session browser, the **Agent activity** execution map, and the
+selected **Session stream**. Use the stream header's chevron to collapse or expand that rail. Collapse
+hides the stream body but does not close the selected transcript connection or stop ingestion; it
+widens Agent activity on desktop. The choice is stored locally and restored on the next dashboard
+visit. The compact rail keeps the chevron available. On narrower screens the stream moves below the
+browser and map; when collapsed it becomes a compact full-width restore bar instead of consuming a
+full transcript-height row.
+
+The chevron is a real button. Its `aria-expanded`, accessible label, and tooltip describe the next
+action, and activating it with Enter or Space announces whether the stream was collapsed or expanded.
+This control is presentation-only; **Pause stream** separately controls visual application of live
+updates.
+
+See [Observability](OBSERVABILITY.md) for the map legend, workspace facts, host capability coverage,
+History/Review semantics, privacy limits, and troubleshooting.
+
+## Local state and security
+
+Theme, polling preference, the selected primary/Overview view, and the Session Stream collapse choice
+are stored in browser-local storage. Canonical hashes make views linkable without putting the
+dashboard token in the path or query string.
+
+The launch token initially arrives in the URL fragment and is then stored locally for authenticated
+API requests. The dashboard remains localhost-only and offline-first. Usage and Observability may
+show sensitive local project or transcript information; use them only where that local information
+may be viewed.