MVP alpha.11: TUI polish and performance improvements

[ZebulonRouseFrantzich]

This pull request introduces a new deterministic TUI snapshot review workflow for cmd/runecode-tui, restructures how the command palette is built, and removes the footer help bar in favor of a more discoverable leader overlay. It also updates documentation and CI configuration to reflect these changes and to guide contributors on the new visual review process.

TUI Snapshot Review Workflow and Documentation:

• Adds .claude/skills/tui-snapshot-review/SKILL.md, a comprehensive guide for using deterministic TUI snapshots for UI/UX audits, including principles, commands, environment controls, and audit workflows. This enables structured, reproducible visual reviews and CI validation for cmd/runecode-tui.
• Updates README.md and AGENTS.md to document the new TUI snapshot review recipes and instruct contributors to use the tui-snapshot-review skill for visual changes. [1] [2]

Command Palette Refactor:

• Refactors the construction of the command palette in command_surface.go by splitting it into modular functions: buildPaletteCommandEntries, buildActionCenterPaletteEntries, buildActiveSurfacePaletteEntries, and buildPaletteDiscoverabilityEntries. This clarifies intent and improves maintainability.
• Updates how Action Center palette entries are generated to use the new snapshot().Families structure and more accurate field names (Reason, EvidenceCue). [1] [2]

Help Bar and Overlay Improvements:

• Removes the footer help bar from the TUI (help.go), reclaiming vertical space and shifting help/discoverability to the leader overlay, which is more context-aware and avoids clutter.
• Updates tests to verify that help is now shown in the leader overlay and that the footer remains compact, ensuring discoverability is preserved without occupying extra space. [1] [2]

CI and Portability:

• Updates the CI workflow to use the ci-portability-unix target for macOS builds, aligning naming with other portability checks.

---

References:
[1] [2] [3] [4] [5] [6] [7] [8] [9] [10]

[Copilot]

Pull request overview

This PR advances cmd/runecode-tui “alpha.11” polish/performance work by adding a deterministic snapshot workflow for visual review, refactoring/expanding command palette + leader help discoverability, and tightening TUI chrome/layout to reclaim vertical space (footer help bar removal, calmer bottom strip, improved overlays). It also updates contributor-facing docs and CI portability naming.

Changes:

• Add a deterministic TUI snapshot generation/review workflow (build-tag gated) with local helper tooling and updated contributor docs.
• Refactor palette/leader/help/discoverability to be more modular and context-aware; add caching/async refresh paths to reduce synchronous UI work.
• Reduce chrome (footer help removal, smaller bottom strip), improve overlay framing, and update route UIs to use new state-card/product-card primitives.

Reviewed changes

Copilot reviewed 133 out of 135 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tools/tui_snapshot_local.sh	Local helper to generate snapshots and optionally open/review artifacts.
runner/package-lock.json	Bumps fast-uri dependency version.
runecontext/changes/CHG-2026-060-c1a4-beta-readiness-hardening-product-polish/status.yaml	Updates verification status metadata.
runecontext/changes/CHG-2026-060-c1a4-beta-readiness-hardening-product-polish/proposal.md	Expands proposal text around TUI latency/polish/CI performance expectations.
README.md	Documents new just tui-* dev and snapshot review recipes.
cmd/runecode-tui/theme.go	Adjusts key hint normalization and badge wording.
cmd/runecode-tui/snapshot_watch_helpers.go	Adds snapshot-only watch-state fixtures/helpers (build-tag gated).
cmd/runecode-tui/snapshot_scenario_catalog.go	Catalogs snapshot scenarios and bundles (build-tag gated).
cmd/runecode-tui/snapshot_paths.go	Canonicalizes and constrains snapshot output paths (build-tag gated).
cmd/runecode-tui/snapshot_enabled.go	Adds snapshot CLI flags/config (build-tag gated).
cmd/runecode-tui/snapshot_disabled.go	Stub snapshot support when build tag is absent.
cmd/runecode-tui/snapshot_disabled_test.go	Tests snapshot flags are rejected without build tag and errors are graceful.
cmd/runecode-tui/snapshot_bundles.go	Defines snapshot bundles + coverage metadata (build-tag gated).
cmd/runecode-tui/snapshot_bundle_specs.go	Specifies scenario membership per snapshot bundle (build-tag gated).
cmd/runecode-tui/shell_workspace.go	Invalidates palette cache when sessions refresh.
cmd/runecode-tui/shell_watch_transport.go	Invalidates palette cache when watch transport updates.
cmd/runecode-tui/shell_watch_projection.go	Updates sync/activity badge wording.
cmd/runecode-tui/shell_update.go	Adds overlay frame caching invalidation + async palette refresh message handling.
cmd/runecode-tui/shell_sidebar.go	Switches sidebar session row rendering to a new “sidebar line” formatter.
cmd/runecode-tui/shell_shortcuts_test.go	Updates help/leader overlay expectations and palette async refresh behavior tests.
cmd/runecode-tui/shell_services.go	Removes workbench persistence/store implementation from this file (moved elsewhere).
cmd/runecode-tui/shell_services_test.go	Updates overlay bounds tests for new framing/padding expectations.
cmd/runecode-tui/shell_persistence.go	Adds persistence bounds/limits and flush hooks for workbench state.
cmd/runecode-tui/shell_overlay_render.go	Reworks centered modal overlay framing, titles, and content bounds.
cmd/runecode-tui/shell_overlay_behavior_test.go	Adds test for cached frame reuse while typing in overlays.
cmd/runecode-tui/shell_object_index.go	Adds discoverability index cloning; invalidates palette cache on index refresh.
cmd/runecode-tui/shell_modes_quit_test.go	Updates bottom-strip expectations for calmer two-line footer.
cmd/runecode-tui/shell_layout.go	Reduces chrome reserved heights (breadcrumbs/history/footer), adjusts pane budgeting.
cmd/runecode-tui/shell_layout_test.go	Updates layout budgeting tests for new chrome heights.
cmd/runecode-tui/shell_input.go	Adds leader-binding signature caching and palette open async entries refresh.
cmd/runecode-tui/shell_footer_view.go	Replaces dense footer help with compact two-line bottom strip + command line.
cmd/runecode-tui/shell_focus_overlay.go	Uses a focused traversal layout plan for focus normalization/restore.
cmd/runecode-tui/shell_contracts.go	Expands route load states (waiting/blocked/degraded/completed/approval required).
cmd/runecode-tui/shell_compositor.go	Treats panes with whitespace-only bodies as empty.
cmd/runecode-tui/shell_commands.go	Uses focused traversal layout plan; palette open uses “immediate entries” helper.
cmd/runecode-tui/shell_command_mode.go	Tweaks command prompt rendering on errors; adds draft reveal rules.
cmd/runecode-tui/shell_chrome_test.go	Adds tests asserting removed dense chrome text and calmer summary cues.
cmd/runecode-tui/shell_activity_summary.go	Adds human-friendly focus/activity summary helpers.
cmd/runecode-tui/shell_action_metadata_test.go	Ensures leader overlay uses compact descriptions rather than long help text.
cmd/runecode-tui/shared_visual.go	Adds product card/accent rail + clipping/right-align helpers.
cmd/runecode-tui/shared_state_card.go	Adds richer state-card rendering (reason/next/cues/evidence) + tone logic.
cmd/runecode-tui/shared_components.go	Adds windowed bounded list renderer; routes state cards through new shared state-card.
cmd/runecode-tui/shared_components_test.go	Adds state-card and windowed list rendering tests; updates existing expectations.
cmd/runecode-tui/session_workspace.go	Optimizes session switcher search with cached normalized text; adds sidebar session row formatter.
cmd/runecode-tui/session_workspace_test.go	Updates session directory/switcher tests and adds normalized-search cache test.
cmd/runecode-tui/safety_ux.go	Improves safety strip wording to be more user-facing and less debug-like.
cmd/runecode-tui/routes.go	Updates route descriptions.
cmd/runecode-tui/routes_model.go	Improves compactLines handling for multi-line blocks.
cmd/runecode-tui/route_tests_provider_helpers_test.go	Adds missing broker client methods for test helper client.
cmd/runecode-tui/route_tests_project_substrate_helpers_test.go	Adds missing project substrate methods for test helper client.
cmd/runecode-tui/route_runs.go	Updates Runs route UI to use state cards and calmer key hints.
cmd/runecode-tui/route_runs_render.go	Adds run directory rendering + run overview/state-card/cue helpers.
cmd/runecode-tui/route_runs_evidence.go	Adds run evidence helpers and attestation truthfulness cues.
cmd/runecode-tui/route_provider_setup.go	Updates provider setup UI to use state cards + guided summaries.
cmd/runecode-tui/route_provider_setup_test.go	Updates provider setup route test expectations for new UI copy.
cmd/runecode-tui/route_git_setup.go	Refactors Git Setup route into guided summaries/state card and safer wording.
cmd/runecode-tui/route_git_setup_test.go	Adds tests for new Git Setup guided UI behavior/copy.
cmd/runecode-tui/route_git_remote_mutation_test.go	Updates Git Remote Mutation tests for new UI copy.
cmd/runecode-tui/route_dashboard.go	Reworks dashboard into product-card sections; updates bottom keys region.
cmd/runecode-tui/route_dashboard_watch_helpers.go	Adds helpers to summarize/render watch family events.
cmd/runecode-tui/route_dashboard_metrics.go	Adds dashboard metric helpers (counts, posture reasoning).
cmd/runecode-tui/route_contract_usage_test.go	Updates expected contract usage for routes.
cmd/runecode-tui/route_chat.go	Updates Chat route to load/track run detail + substrate posture, and uses state cards.
cmd/runecode-tui/route_chat_rendering.go	Reworks session directory item language and adds active session summary block.
cmd/runecode-tui/route_chat_inspector.go	Avoids unnecessary transcript recomputation; enriches inspector status/badges/actions.
cmd/runecode-tui/route_chat_execution_state_helpers.go	Adds execution/run/posture helper functions for chat state cards and guidance.
cmd/runecode-tui/route_chat_execution_helpers_test.go	Adds tests for new chat execution state card semantics and session row wording.
cmd/runecode-tui/route_audit.go	Reworks audit view summary structure and calmer key hints; strengthens status comparisons.
cmd/runecode-tui/route_audit_workbench_helpers.go	Adds audit workbench “next action” and anchoring line helpers.
cmd/runecode-tui/route_audit_timeline_labels.go	Adds audit timeline directory labeling helpers.
cmd/runecode-tui/route_audit_status_test.go	Updates audit/status route tests for new UI copy and inspector expectations.
cmd/runecode-tui/route_audit_anchor_action.go	Improves anchoring messaging and sanitizes some preflight reason codes.
cmd/runecode-tui/route_artifacts.go	Reworks artifacts main UI sections; enriches artifact head with run ID from list fallback.
cmd/runecode-tui/route_approvals.go	Reworks approvals UI, status text, resolve-unavailable messaging, and key hints.
cmd/runecode-tui/route_approvals_validation_test.go	Expands resolve validation tests (hash binding, schema checks, denied handling).
cmd/runecode-tui/route_approvals_state_helpers.go	Adds approval state/badge/reason helpers for guided UI.
cmd/runecode-tui/route_approval_fixture_test.go	Adds signed approval request/decision fixtures for resolve validation tests.
cmd/runecode-tui/route_action_center_blocked_helpers.go	Adds helpers to model “blocked impact” action-center items.
cmd/runecode-tui/palette_test.go	Updates query delete API name and adds cached normalized filtering + incremental filtering tests.
cmd/runecode-tui/main.go	Refactors main into runMain, adds snapshot mode execution, adds help parsing, and flushes workbench store on exit.
cmd/runecode-tui/main_test.go	Adds tests for combined help flags and workbench flush-on-exit behavior.
cmd/runecode-tui/local_rpc_integration_linux_test.go	Refactors route assertion helpers and updates UI expectations in integration test.
cmd/runecode-tui/help.go	Removes footer help rendering (now empty).
cmd/runecode-tui/help_test.go	Updates tests to assert help moved to leader overlay and footer help is gone.
cmd/runecode-tui/command_surface.go	Splits palette construction into modular builders; updates Action Center entry source fields.
AGENTS.md	Adds instruction to use tui-snapshot-review workflow for TUI visual changes.
.gitignore	Ignores Python caches and .tui-snapshots/ artifacts.
.github/workflows/ci.yml	Switches macOS portability job to ci-portability-unix target.

Files not reviewed (1)

• runner/package-lock.json: Language not supported

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.