prototype(tui): throwaway TUI information-architecture prototype (ticket #3)

Three structurally different variants (Panes / Pages / Ledger), switchable live, plus a six-state scenario rotator (steady, warming up, habit changed, stale, no baseline, paused) driving the ADR-0002 section-13 contract and the four separate ADR-0003 section-8 service facts. Pause/resume/collect suspend the TUI and run a polkit stand-in on the real terminal to validate tty passthrough. Headless smoke test + SVG screenshots included.
2026-08-31 16:30:28 +05:30
parent 26a6703152
commit a0e4690703
23 changed files with 3818 additions and 0 deletions
@@ -0,0 +1,46 @@
+# Fenris TUI information-architecture PROTOTYPE (throwaway)
+
+**This is throwaway code answering [ticket #3](https://git.bongbetic.com/xavierk/Fenris/issues/3).** It is not the redesign, reads nothing real, and never ships. Branch: `prototype/tui-information-architecture`.
+
+## Question
+
+What screen hierarchy, navigation, and action model makes Fenris's projection contract (ADR 0002 §13), the four separate service facts (ADR 0003 §8), warming-up, unexplained gaps, and changing habits understandable in a keyboard-first terminal?
+
+## Run (one command)
+
+```sh
+./run
+```
+
+(creates `.venv` and installs `textual` on first use)
+
+## What to flip through
+
+**Variants (← / →)** — three structurally different answers, not restylings:
+
+| Key | Variant | Idea |
+|-----|---------|------|
+| A | **Panes** | everything on one dense screen, btop-style; no navigation, panes are zones |
+| B | **Pages** | persistent three-fact header (lifespan · confidence · freshness) + pages 1–5 |
+| C | **Ledger** | one scrolling document in reading order, headline sentence first |
+
+**States (s)** — same variants, six shapes of the contract:
+
+1. steady · Supported (with one unexplained 3-hour gap)
+2. warming up · Limited (11 of 14 days)
+3. habit changed · Limited (regime 6 days old, scenario spread visible)
+4. stale · Supported→Limited (last collect FAILED, 61 h old)
+5. no baseline · Unavailable (wear too coarse to imply endurance)
+6. paused · Limited (period closed by deliberate disable)
+
+**Actions** — `p` pause (asks confirmation) · `r` resume (doesn't) · `c` collect now (synchronous outcome). Each suspends the TUI and runs `polkit_stub.py` on the real terminal: this validates the tty passthrough ADR 0003 requires for the polkit prompt. Results land in the tty log (variant B service page; every variant's log is the same list).
+
+## What to react to
+
+- Which variant's hierarchy matches how you think about the drive? (Mixing — "header from B, density of A" — is a valid answer and the point.)
+- Are the four service facts separable at a glance?
+- Do confidence states + contributing facts read as evidence, not as a percentage?
+- Is the pause confirmation the right amount of friction?
+- Did the polkit tty stub actually prompt in your terminal? (That's the mechanism check.)
+
+`screenshots/` holds headless captures (`smoke_test.py`) of each variant at 80×24 and 140×40.