Fenris/docs/spec/dashboard-clarity.md

Fenris dashboard clarity specification

Status: decision-complete. Assembled by Assemble the dashboard clarity specification and close the map from the closed tickets of the Wayfinder map Chart Fenris dashboard clarity. This document is normative for the follow-up execution effort; nothing here is implemented by the map.

Canonical roles. The redesign specification (frozen) and ADRs 0001–0007 remain authoritative and untouched — this is a companion spec covering five dashboard clarity additions plus the changelog-driven release-notes mechanism. The criteria register carries the testable statements: DC-1–DC-8, appended by this assembly, with TUI-4's binding list amended (§4). Terminology follows the glossary in CONTEXT.md, including Deliberate disable and Release.

Binding language. Must, exactly, and never are normative.

How to read this document

Five screen additions (§1–§5), one release-notes mechanism (§6), the verbatim string register (§7), and the README section to add at execution (§8). Each section cites its criteria. Source strings are lowercase; the TUI may render uppercase via styling only. Typography, governing every string: em-dash — separates a title from its qualifier; middle dot · joins facts within a line; UTF-8 is assumed. CI parity sweeps compare lowercase source strings — rendering case is styling, not wording.

1. Header bar and Bongbetic credit — DC-1

Visual base is treatment A, quiet integration: the existing Panes information architecture is preserved.

• The header bar reads Fenris — NVMe endurance monitor.
• The credit by Bongbetic renders dimmed, inline with service facts in the bottom service strip — never in the action row.
• Both are TUI-only identity surfaces: fenris status never renders them.

2. Continuity line — DC-2

A labelled CONTINUITY row in the service strip (treatment B), mirrored by fenris status — the TUI/CLI parity anchor. The row is keyed to the boot fact as-is, independently of run state (Deliberate disable runs systemctl disable --now, so paused implies boot-disabled; the row still reports the fact):

• Active + boot enabled: monitoring: active in background · persists across reboots
• Boot disabled: monitoring: does not start on next boot

Identical lowercase source strings in the TUI service strip and fenris status, including while paused.

3. Paused state block — DC-3

Treatment C, strong state blocks: when monitoring is paused, a full-width, high-contrast banner clearly identifying Deliberate disable:

• Title: monitoring: paused — deliberate disable
• Subline: paused time is excluded from your usage habit · resume: fenris monitor resume

fenris status prints the same two lines with identical wording (state line + consequence line). The resume hint uses the CLI form only; the footer owns key hints — no duplication.

4. Quit rail — DC-4 (amends TUI-4)

Treatment B, labelled rails: a prominent bordered q QUIT TUI rail, visually separate from the monitoring-state block and the paused banner. The footer becomes p pause · r resume · c collect · d disclosures — the rail owns quit; the footer carries no quit entry. Quitting the TUI never alters monitoring state. The register's TUI-4 binding parenthetical is amended accordingly by this assembly.

5. Launch auth banner — DC-5

A quiet informational line (treatment A) that never competes with drive state:

• Text: privileged actions will prompt for authentication (polkit)
• Full-width under the header at TUI launch; clears on the first refresh tick; never reappears in the session.
• TUI-only; fenris status never shows it.
• Elevation wording is polkit-accurate everywhere: no user-facing string uses "sudo" (sudo belongs to install/upgrade docs).
• Evidence class A: a Textual pilot drives refresh ticks headlessly.

6. Changelog and release notes — DC-6, DC-7, DC-8

Implements the existing glossary term Release (tag + packages + change notes together). No new glossary terms; no ADR (reversible mechanism).

6.1 CHANGELOG.md (source of truth, repo root)

• Keep a Changelog 1.1 shape. ## [Unreleased] is always present at top, even empty. Version headings are ## [X.Y.Z] - YYYY-MM-DD — bracketed bare semver, strict ISO date.
• Categories are ### Added, ### Changed, ### Fixed only; security fixes fold into Fixed.
• Entries are single - bullets, imperative mood, user-facing phrasing; no commit hashes or issue numbers.

6.2 Extraction (release.yml, tag time)

• scripts/extract_changelog.py (checked in, unit-tested): takes the changelog path and a version; slices that version's section verbatim; never reads [Unreleased]. Fails closed — ::error:: plus nonzero exit — when the section is missing or empty or the date is malformed.
• Guard: the workflow fails when the pushed tag ≠ v{version from pyproject.toml} (guard skipped on workflow_dispatch).

6.3 Release body

• Body = extracted version section verbatim + standing footer from packaging/release-footer.md (channel install one-liners, sha256sum -c SHA256SUMS.asc verify, rollback pointer). The footer is standing text; only the changelog section varies.
• Re-run against an existing release: PATCH the body (changelog re-sync is a feature); uploaded assets/packages keep their current idempotent-skip.

6.4 Discipline

• All entries land in [Unreleased] as part of the fixing change — no notes-later step.
• One release commit bumps the pyproject version, renames [Unreleased] → the version heading, and restores an empty [Unreleased]; the tag points at that commit (tag ↔ pyproject ↔ changelog triple-match, enforced fail-closed by DC-7).
• No backfill: per-release notes begin with the release shipping this mechanism; CHANGELOG.md starts with empty [Unreleased].

7. String register (verbatim)

TUI-only strings (launch/identity surfaces)

Surface	String
Header bar	Fenris — NVMe endurance monitor
Credit (dimmed, inline with service facts)	by Bongbetic
Auth banner (full-width under header at launch, clears on first refresh tick, never reappears)	privileged actions will prompt for authentication (polkit)
Quit rail (bordered, labelled)	q QUIT TUI
Footer (owns key hints; no quit entry)	p pause · r resume · c collect · d disclosures

Parity strings (TUI and fenris status identical — CI-2)

Surface	String
Continuity, active + boot enabled	monitoring: active in background · persists across reboots
Continuity, boot disabled	monitoring: does not start on next boot
Paused state line	monitoring: paused — deliberate disable
Paused consequence line	paused time is excluded from your usage habit · resume: fenris monitor resume

fenris status prints the paused state line + consequence line when paused, identical wording to the banner title + subline.

8. README section (add at execution)

The README gains a "Reading the dashboard" section after the CLI reference. Verbatim text:

## Reading the dashboard

`fenris` opens the TUI dashboard. Three things it tells you:

- **Continuity** — the service strip's continuity line (and `fenris status`) reports whether monitoring survives reboots: `monitoring: active in background · persists across reboots`, or `monitoring: does not start on next boot`.
- **Paused vs. quit** — a full-width `monitoring: paused — deliberate disable` block means collection is stopped (`fenris monitor pause`); resume with `fenris monitor resume`. Pressing `q` only leaves the screen — monitoring keeps running in the background.
- **Auth banner** — at launch, `privileged actions will prompt for authentication (polkit)` shows once and clears on the first refresh. Privileged actions elevate via polkit; Fenris never asks for sudo.

Per-release notes live on the [releases page](https://git.bongbetic.com/xavierk/Fenris/releases): each entry is the version's `CHANGELOG.md` section — what was added, changed, and fixed — plus standing install and verification instructions.

This resolves the map's README-wording fog: the wording is decided here; the actual README edit is execution.

9. Out of scope

Executing any of this — code, tests, releases — and any TUI layout or information-architecture redesign beyond the five additions named above. Execution is a fresh effort after handoff.