docs: add mockup-aligned tui v2 refresh execution plan

docs/README.md

@@ -35,6 +35,7 @@ This directory contains SeedPass project documentation.
 - `tui_v2_parity_checklist.md`
 - `tui_v2_parity_backlog.md`
 - `tui_v2_legacy_parity_matrix.md`
+- `tui_v2_ui_refresh_plan.md`
 - `tui_v2_cutover_decision.md`
 - `tui_v2_large_vault_validation.md`
 - `security.md`

docs/dev_control_center.md

@@ -29,6 +29,7 @@ Use these docs as inputs, but treat this file as the decision layer:
 - TUI parity backlog: `docs/tui_v2_parity_backlog.md`
 - TUI parity checklist: `docs/tui_v2_parity_checklist.md`
 - TUI legacy parity matrix: `docs/tui_v2_legacy_parity_matrix.md`
+- TUI v2 UI refresh plan (mockup-aligned): `docs/tui_v2_ui_refresh_plan.md`
 - Cutover memo: `docs/tui_v2_cutover_decision.md`
 - Security readiness: `docs/security_readiness_checklist.md`
 - Supply-chain integrity: `docs/supply_chain_release_integrity.md`

docs/tui_v2_parity_backlog.md

@@ -9,6 +9,7 @@ Linked plans:
 - `docs/tui_v2_plan.md`
 - `docs/tui_v2_parity_checklist.md`
 - `docs/tui_v2_cutover_decision.md`
+- `docs/tui_v2_ui_refresh_plan.md`
 
 ## What We Learned
 

docs/tui_v2_ui_refresh_plan.md

@@ -0,0 +1,332 @@
+# TUI v2 UI Refresh Plan (Mockup-Aligned)
+
+Status: Active (2026-03-02)  
+Branch target: `beta`  
+Primary references: `UI_mockups/PNG/*.png`, `UI_mockups/SeedPass_UI-Board.pdf`
+
+## 1) Purpose
+
+Translate the mockup direction into an implementation-ready, multi-session plan for Textual TUI v2 while preserving SeedPass's green visual identity.
+
+This plan is intentionally detailed so future sessions can continue implementation without re-discovery.
+
+## 2) Design Direction We Are Targeting
+
+From the mockups, the desired direction is:
+
+1. Table-first operations with high information density.
+2. Persistent left "seed/account tree" navigation column.
+3. Large, contextual lower "inspector board" that changes by selected entry kind.
+4. Persistent bottom action strip for discoverability.
+5. Strong framed layout (hard borders, segmented panels, explicit labels).
+6. Black/neutral structure language, but with SeedPass green theme colors.
+
+## 3) Visual System Contract (Keep Green Theme)
+
+Use the existing TUI v2 palette as baseline (already present in `src/seedpass/tui_v2/app.py`):
+
+- Base background: `#080a0c`
+- Panel background: `#0d1114`
+- Header/footer background: `#0b0f13`
+- Primary text: `#daf2e5`
+- Secondary text: `#97b8a6`
+- Border default: `#1a3024`
+- Border emphasis: `#274533`
+- Accent/action: `#2abf75`
+- Focus highlight: `#58f29d`
+
+Rules:
+
+1. Keep semantic role colors stable (focus, warning, success, muted).
+2. Use contrast through brightness and border weight, not unrelated hues.
+3. Keep monochrome mockup geometry and spacing, but render in green palette.
+
+## 4) Information Architecture (Target Layout)
+
+Target screen structure:
+
+1. Top status ribbon:
+- fingerprint
+- managed users count
+- entries count
+- active kind/filter
+- last sync timestamp
+
+2. Main split:
+- Left: seed/account tree + context summary.
+- Right:
+  - Top: search + filter controls + dense entry table/grid.
+  - Bottom: contextual inspector board for selected entry.
+
+3. Bottom action strip:
+- Global shortcuts always visible.
+- Context shortcuts appended for selected kind and mode.
+
+## 5) Interaction Model Contract
+
+Primary modes:
+
+1. Browse Mode:
+- Grid-focused.
+- Fast navigation/search/filter/sort.
+
+2. Inspect Mode:
+- Inspector board-focused.
+- Entry-specific actions (reveal/copy/export/edit/link).
+
+3. Edit Mode:
+- Existing document editor/entry mutation mode.
+
+Behavior rules:
+
+1. Selected row always drives inspector board content.
+2. Locked vault state must be visible in status ribbon and action strip.
+3. Sensitive actions reflect state chips:
+- `HIDDEN`, `REVEALED`, `COPIED`, `LOCKED`
+4. If no selection exists, inspector shows onboarding or "select entry" guidance.
+
+## 6) Component-Level Spec
+
+### 6.1 Left Navigation Tree
+
+Goal: match mockup's persistent profile/seed hierarchy.
+
+Requirements:
+
+1. Always visible.
+2. Shows active profile + managed-account context.
+3. Supports keyboard traversal and selection.
+4. Selection changes filter context for center grid.
+
+Initial fallback (if full tree data unavailable):
+
+1. Render static grouped sections from currently available services.
+2. Keep widget contract stable so backing data can be enriched later.
+
+### 6.2 Top Entry Grid
+
+Goal: table-like view similar to mockups.
+
+Columns (target):
+
+1. Index num
+2. Entry num
+3. Title
+4. Kind
+5. Tags (truncated)
+6. Date modified
+7. Archive/blacklist status
+
+Rules:
+
+1. Compact row density by default.
+2. Overflow truncation with consistent ellipsis behavior.
+3. Sort indicators shown in header (even if only one active sort initially).
+4. Keyboard row selection must stay smooth on large datasets.
+
+### 6.3 Inspector Board (Lower Panel)
+
+Goal: board-style details by entry kind, matching mockup families.
+
+Common board header:
+
+1. Entry label + kind.
+2. Modified timestamp.
+3. Archive/blacklist status.
+4. Index/entry IDs.
+5. Right-side primary action button area (`Edit`, etc).
+
+Common board body:
+
+1. Field blocks with labels.
+2. Copy/export/reveal controls as command hints/buttons.
+3. Notes area.
+4. Tags panel (right rail when space permits).
+
+### 6.4 Bottom Action Strip
+
+Goal: persistent discoverability.
+
+Global segment examples:
+
+1. `[S]ettings`
+2. `[A]dd Entry`
+3. `[C]reate Seed`
+4. `[R]emove Seed`
+5. `[H]ide/Reveal Sensitive`
+6. `[E]xport`
+7. `[I]mport`
+8. `[B]ackup`
+
+Context segment examples:
+
+1. Password: copy password, copy username, reveal, qr.
+2. 2FA: copy code, refresh code, show qr.
+3. SSH/PGP: copy public/private, export key.
+4. Nostr: copy npub/nsec, show public/private qr.
+
+## 7) Entry-Type Board Templates (Implementation Contract)
+
+Each entry kind gets a formatter/template function returning a structured board text payload.
+
+Template priority order:
+
+1. `password` / `stored_password`
+2. `note` / `document`
+3. `seed` / `managed_account`
+4. `totp`
+5. `ssh`
+6. `pgp`
+7. `nostr`
+8. `key_value`
+9. fallback generic JSON board
+
+Per-kind minimum fields:
+
+1. Password/stored password:
+- password (masked by default), username, url, tags, notes
+
+2. Note/document:
+- content preview, tags, notes, file type (document)
+
+3. Seed/managed account:
+- seed phrase hidden/reveal state, derivation/index metadata where available, tags, notes
+
+4. TOTP:
+- current code, period, digits, secret hidden/reveal, qr support
+
+5. SSH:
+- public key, private key hidden/reveal, export hints
+
+6. PGP:
+- fingerprint, public key, private key hidden/reveal, export hints
+
+7. Nostr:
+- npub, nsec hidden/reveal, public/private qr modes
+
+## 8) Keyboard and Command Mapping Plan
+
+Keep existing keybinds; add stronger discoverability and zone consistency.
+
+Add/confirm mappings:
+
+1. Zone focus:
+- `1` left tree
+- `2` top grid
+- `3` inspector board
+
+2. Mode emphasis:
+- `Tab` optional focus advance
+- `Shift+Tab` reverse focus (if Textual behavior allows cleanly)
+
+3. Inspector actions:
+- keep `v` reveal and `g` qr globally
+- add board-level shortcuts to status/action strip text
+
+4. Palette aliases:
+- add board/action aliases where needed to mirror strip labels.
+
+## 9) Delivery Plan (Phased Slices)
+
+## Phase 1: Shell Restructure (Layout only)
+
+Deliver:
+
+1. Split right pane into top grid + lower inspector board.
+2. Add top status ribbon and bottom action strip scaffolding.
+3. Keep existing data behavior unchanged.
+
+Exit criteria:
+
+1. Layout visually resembles mockup structure.
+2. Existing interaction tests still pass.
+3. No regression in reveal/qr/session behavior.
+
+## Phase 2: Grid Modernization
+
+Deliver:
+
+1. Table-style header row and compact rows.
+2. Column alignment/truncation rules.
+3. Sort indicator placeholders and active filter badges.
+
+Exit criteria:
+
+1. Large-list navigation remains performant.
+2. Paging/search/filter actions remain deterministic.
+
+## Phase 3: Inspector Board Templates (Core Kinds)
+
+Deliver:
+
+1. Board templates for password, note/document, seed, totp.
+2. Sensitive-state chips + action hints.
+3. Context-aware action strip additions.
+
+Exit criteria:
+
+1. Selected entry shows board instead of raw JSON for covered kinds.
+2. Reveal/qr flows are explicit and test-covered.
+
+## Phase 4: Inspector Board Templates (Advanced Kinds)
+
+Deliver:
+
+1. SSH/PGP/Nostr/key_value boards.
+2. Copy/export affordance text and command parity hints.
+3. Managed-account board treatment.
+
+Exit criteria:
+
+1. All major kinds render purpose-built boards.
+2. No loss of existing palette command capability.
+
+## Phase 5: Tree Navigation and Polish
+
+Deliver:
+
+1. Left tree visual and keyboard behavior.
+2. Compact vs expanded density mode.
+3. Final visual polish against mockups (in green theme).
+
+Exit criteria:
+
+1. Tree + grid + board flow is coherent end-to-end.
+2. User walkthrough of top daily workflows feels parity+ with legacy.
+
+## 10) Testing and Quality Gates Per Slice
+
+Mandatory per slice:
+
+1. Update/extend Textual interaction tests in:
+- `src/tests/test_tui_v2_textual_interactions.py`
+- `src/tests/test_tui_v2_action_matrix.py`
+
+2. Run:
+- `poetry run pytest -q src/tests/test_tui_v2_textual_interactions.py src/tests/test_tui_v2_action_matrix.py`
+
+3. If app logic paths changed meaningfully, run:
+- `scripts/tui2_coverage_gate.sh`
+
+4. Update docs:
+- this file
+- `docs/tui_v2_legacy_parity_matrix.md`
+- `docs/dev_control_center.md` (if priorities shift)
+
+## 11) Non-Goals (for this refresh)
+
+1. Replacing Textual runtime stack.
+2. Reworking core service/data model APIs for cosmetic UI concerns.
+3. Introducing non-deterministic behavior in entry rendering.
+4. Removing legacy TUI fallback before explicit cutover decision.
+
+## 12) Session Handoff Checklist
+
+Before ending any session touching this refresh:
+
+1. Mark phase/slice progress in this document.
+2. Record what was implemented and what remains.
+3. Add test evidence and known regressions.
+4. Append summary to `memory-update.md`.
+
+Current next slice (recommended): **Phase 1 - Shell Restructure**.

memory-update.md

@@ -884,3 +884,20 @@
 - Planning docs updated:
   - `docs/tui_v2_legacy_parity_matrix.md` now marks onboarding parity as implemented and clears active medium/high parity gaps.
   - `docs/dev_control_center.md` now reflects that the tracked onboarding/stats/session UX gaps are landed.
+
+## 2026-03-02 UI direction capture slice: mockup-aligned TUI v2 refresh plan
+- Added a detailed multi-session implementation spec:
+  - `docs/tui_v2_ui_refresh_plan.md`
+- Plan captures:
+  - visual contract preserving existing green palette
+  - target information architecture (left tree, top grid, bottom inspector board, bottom action strip)
+  - component requirements and per-entry-kind board template contracts
+  - keyboard/command discoverability expectations
+  - phased delivery plan with explicit exit criteria
+  - required test gates and handoff checklist for session continuity
+- Linked the plan from control/index docs:
+  - `docs/dev_control_center.md`
+  - `docs/README.md`
+  - `docs/tui_v2_parity_backlog.md`
+- Recommended next implementation slice documented as:
+  - Phase 1: shell restructure (layout scaffolding only, no behavior regressions).