projmux 0.6.3 → 0.6.4

package/docs/settings-ia.md

@@ -17,6 +17,23 @@ view-first layout:
   first, then the edit actions, then the explanatory hints.
 - `Settings > Keybindings` is the single entry point for keybinding work. The
   page is split into four chips: `Bindings`, `Diagnostic`, `Probe`, and `Init`.
+- `Settings > Keybindings > Bindings` is a keybinding discovery surface, not
+  only a launch-toggle editor. It must show `Toggle Project Sidebar` with the
+  guaranteed `Alt-1` / `M-1` default, plus sidebar-local commands, picker-local
+  commands, `Pane navigation`, `Window navigation`, and `Rename` groups or
+  equivalent searchable rows.
+- Rows that cannot safely be edited still stay visible. Mark diagnostic-only
+  rows with the delivery path and reason instead of hiding them or turning them
+  into unsupported editable aliases. Transport-dependent rows stay visible with
+  a separate default transport key and additive plain-alias entry; replacing or
+  disabling the transport default is not exposed.
+- `Alt-1..5` are the only guaranteed zero-config launch defaults. `UserN` and
+  `CSI-u` are legacy/removal/unsupported targets, not supported fallback
+  guidance for Settings, setup, init, or docs.
+- The launcher checkout policy applies in Settings: the project sidebar is a
+  first-class row, action rows use human-readable labels, internal IDs appear
+  only in detail/source/keymap contexts, and runtime footers are status hints,
+  not key discovery.
 - `Settings > Notifications` owns notification delivery IA. Desktop notification
   mode, AI desktop notification dedupe duration, delivery source diagnostics,
   AI hook quiet policy, in-app queue status, and
@@ -68,8 +85,8 @@ Hooks remain the reference pattern for this IA:
 
 Shell bootstrap UX is phase-split:
 
-- Phase 1 is complete in this branch: `projmux welcome`, the About-screen
-  Welcome entry, and `pending_attach_welcome` state make the guide revisit-able.
-- Phase 2 is complete in this branch: the generated projmux shell tmux config
-  runs the low-noise `projmux welcome --popup` attach hook, which claims the
-  pending marker once and displays the welcome guide after attach.
+- `projmux welcome` remains the stdout revisit command.
+- `Settings > About > Welcome` opens a visible native viewer independent of
+  shell skip state.
+- Shell `skip_version` state applies only to the automatic `projmux shell`
+  prompt; it does not hide manual revisit surfaces.

package/docs/statusbar.md

@@ -5,6 +5,10 @@ clickable status bar. The same dispatcher (`projmux statusbar click`)
 handles both mouse clicks and the keyboard chord, so adding a new
 segment only requires one wiring point.
 
+The built-in fallback colors used by the statusbar are semantic tokens in
+`internal/theme/palette.go`; see [theme-palette.md](theme-palette.md) for the
+truecolor to tmux 256-color mapping policy and palette inventory.
+
 ## Layout
 
 ```
@@ -37,10 +41,17 @@ row 1  [#S]  #{pane_current_path}  ⎈ <ctx>/<ns>  <git>   %H:%M
   branch or detached commit,
   then compact state indicators when available: `*` for local changes,
   `+N` for staged entries, and `↑N`/`↓N` for ahead/behind counts. Each
-  state token gets its own compact foreground color while preserving the
-  existing branch block background. Window tab indexes stay left of each tab,
+  state token gets its own compact foreground color on the same muted branch
+  block; the indicators drop bold styling so git state remains readable
+  without dominating the status row. Window tab indexes stay left of each tab,
   and tab titles are centered in a fixed-width trim so long active pane names
   do not resize the status row.
+- The settings chip keeps its label padding inside the `settings` range
+  and inside the chip background. The compact app chip renders `` with
+  the extra right-side icon padding painted by the same background, while
+  the standalone ` projmux` label keeps symmetric one-cell label padding.
+  The chip does not append an extra default-styled trailing space after
+  `#[default]`, so the painted button reaches the status row's right edge.
 - Both HUD segments degrade gracefully when the cell budget is tight; see
   [notify-queue.md](notify-queue.md) and [usage-tracking.md](usage-tracking.md)
   for the per-segment tier ladder.
@@ -85,8 +96,8 @@ not inherit notification styling.
 `usage` opens a native-framed detail HUD for the compact usage bar. It reads
 the cached usage state in-process, keeps the existing `projmux usage` CLI
 output shape unchanged for external consumers, aligns model/window rows with
-right-aligned numeric values, dims unavailable values, and colors rows at the
-same alert thresholds as the popup: amber at 80% and red at 95%.
+right-aligned numeric values, dims unavailable values, keeps stale sync/age
+metadata muted, and colors only threshold values: amber at 80% and red at 95%.
 Session State inspection lives under `Projects > Sessions > State`; global
 Settings > Session State is settings-only and the statusbar no longer exposes a
 duplicate State button.
@@ -99,15 +110,16 @@ popup command prints one quoted payload and waits for a plain Enter read so it
 does not leave terminal key state behind. The usage popup uses the same
 single-payload print and plain Enter-close pattern. It shows the authoritative
 last collect timestamp when present, falls back to the cache file mtime when
-needed, and colors that sync line amber once it is more than 60 seconds old.
-The notification HUD detail surface (`Alt-2` / `User2`) opens the right-side
-notification popup with newest-first rows and an amber title. When notification
-icon decoration is `symbol` or `emoji`, the bell appears before the title text.
-Selecting a row still focuses and acknowledges that notification. Pressing `x`
-bulk-clears non-critical rows without focusing, keeps the popup open, and
-refreshes the remaining rows from the queue. Pressing `a` acknowledges the
-selected row without focusing and preserves the selection position where
-possible.
+needed, and keeps stale sync metadata muted instead of escalating it to a
+warning color.
+The notification HUD detail surface opens the right-side notification popup
+through the notify sidebar action, with newest-first rows and an
+attention-tinted title. When notification icon decoration is `symbol` or
+`emoji`, the bell appears before the title text.
+Selecting a row still focuses and acknowledges that notification. Internal
+notify commands use `NotifySidebar:*` IDs in `keymap.toml`; runtime footers
+render key guides from the merged keymap and prefer the default alias when it
+is still configured.
 
 Empty `#{mouse_status_range}` (a click on whitespace) falls through to
 `select-window -t @<mouse_window>` when `--mouse-window` is non-empty,

package/docs/testing.md

@@ -44,8 +44,9 @@ execution should not need network access after the image is built.
 The Docker suites do not replace checks that depend on a real host terminal,
 desktop shell, or OS integration:
 
-- terminal emulator key delivery and swallowing for `Alt-1..5`, `Ctrl-N`, and
-  CSI-u chords
+- terminal emulator key delivery and swallowing for guaranteed `Alt-1..5`
+  launch keys, optional user-configured direct aliases, and transport-dependent
+  chords
 - Windows Terminal and WSL interop
 - macOS host path, shell, and GUI behavior
 - desktop notification click callbacks

package/docs/theme-palette.md

@@ -0,0 +1,105 @@
+# Theme Palette
+
+This document records the built-in fallback palette that native projmux UI
+surfaces use before project or global theme settings exist. The source of
+truth in code is `internal/theme/palette.go`.
+
+## Scope
+
+The fallback palette is a semantic token layer, not a user configuration
+schema. It gives current renderers shared names for the colors stabilized by
+the Visual palette baseline work:
+
+- Native picker truecolor SGR tokens.
+- Native sidebar and chip-strip 256-color SGR tokens.
+- Tmux statusbar and generated-config color tokens.
+- Settings/action/state/trust/attention helper tokens.
+
+Future Theme settings should resolve project/global values into this token
+shape, then keep the built-in values as the final fallback. This phase does not
+add `config.toml` fields, a resolver, a Settings editor, presets, import, or
+export.
+
+## Mapping Policy
+
+Native picker rows can emit truecolor SGR, while tmux statusbar/config strings
+must use tmux color specs. The fallback therefore stores both forms when a
+role crosses surfaces.
+
+Rules:
+
+- Truecolor tokens keep exact SGR strings for native picker chrome and
+  Settings rows.
+- Tmux tokens keep `colourN` strings where tmux owns rendering.
+- Native chip/sidebar badge tokens use 256-color SGR when they intentionally
+  mirror tmux colors.
+- Output compatibility wins inside this baseline. For example, the kube
+  segment keeps tmux's named `red` and `blue` behind semantic tokens until that
+  segment gets a separate redesign.
+- Renderers should reference semantic names instead of spelling color literals
+  directly. Test fixtures may still pin rendered escape strings.
+
+## Fallback Inventory
+
+Chrome and text:
+
+| Role | Native SGR | Tmux |
+| --- | --- | --- |
+| `surface.active` | `48;2;44;56;61` with selected white text | window active `colour240` / `colour231` |
+| `surface.raised` | `48;2;24;34;38` with `216;224;228` text | window inactive `colour235` / `colour245` |
+| `text.primary` | `216;224;228` | `colour231` or `colour254` for identity text |
+| `text.secondary` | `164;176;182` | `colour245` |
+| `text.muted` | `117;132;140` or ANSI dim | `colour244`, `colour238`, `colour240` for low-signal blocks |
+
+Accents and state:
+
+| Role | Native SGR | Tmux |
+| --- | --- | --- |
+| `accent.identity` | not emitted directly today | `colour60` bg / `colour254` fg |
+| `accent.action` | `141;205;142`, strong `122;199;173` | `colour29` bg / `colour230` fg |
+| `accent.attention` | notify HUD background/project family | `colour53`, project `colour90` |
+| `accent.ai` | notify agent `colour37` family | `colour37` bg / `colour121` fg |
+| `state.progress` | `255;204;102`; switch attention/busy dot and pending notify title/bell/badge `colour220` | `colour220` |
+| `state.warning` | usage/status popup ANSI 256 wrapper | `colour214` |
+| `state.danger` | `255;107;107` | `colour160` |
+| `state.success` | settings/trust green families | `colour72`, `colour151` |
+| `state.ahead` | switch/git metadata and notify age ANSI 256 wrapper | `colour153` |
+| `git.branch` | switch/sidebar branch badge uses the statusbar git branch block colors | `colour30` bg / `colour231` fg |
+
+Surface-specific tokens:
+
+| Surface | Tokens |
+| --- | --- |
+| Native picker | current row, titlebar, rule, pointer, highlight, muted text, chip active/inactive/disabled |
+| Statusbar row 1 | session identity, cwd secondary text, divider, git branch block, git dirty/staged/ahead/behind, settings action chip, clock |
+| Notify HUD/sidebar | line bg/fg, project badge, info/warn/crit/stale/gone badges, AI agent badge, count/age text |
+| Usage HUD/popup | OK/warning/critical/over-limit bars and numbers, empty cells, muted sync age |
+| Settings | add/type/open action, destructive remove/quit, back/cancel, info/read-only, dim description, root action/dim rows, trust trusted/stale/untrusted |
+| Switch picker cards | path metadata, active/inactive git branch badges aligned with statusbar git branch block colors, statusbar-like window tabs, inline attention/progress dots |
+
+## Current Literal Inventory
+
+After the Phase 3 token pass, raw color values intentionally remain in:
+
+- `internal/theme/palette.go`, the fallback palette source of truth.
+- Unit and golden fixtures that assert exact rendered output.
+- `internal/app/welcome.go`, which is outside the Visual palette baseline
+  Phase 3 scope and should move only in welcome/update policy work.
+- Older switch picker test fixtures that pin legacy compatibility output.
+
+The converted implementation paths include:
+
+- `internal/ui/projmuxpicker/ansi.go`
+- `internal/app/tmux.go`
+- `internal/app/status.go`
+- `internal/app/statusbar.go`
+- `internal/app/statusbar_decoration.go`
+- `internal/app/notify.go`
+- `internal/app/settings.go`
+- `internal/app/settings_render.go`
+- `internal/app/trust.go`
+- `internal/app/usage.go`
+- `internal/core/usage/hud.go`
+- `internal/ui/render/switch.go`
+- `internal/ui/render/popup.go`
+- `internal/ui/render/switch_preview.go`