projmux 0.6.3 → 0.6.5

package/docs/session-restore.md

@@ -11,6 +11,16 @@ projmux session-state restore --dry-run [--session <name>]
 projmux session-state delete [--session <name>]
 ```
 
+Snapshots preserve source metadata, not a final display label. Window records
+keep `window_name`; pane records keep `pane_title`, recipe fields, AI topic
+metadata (`@projmux_ai_topic`), and resume metadata when available. There is no
+`display_label` field in the snapshot schema. After restore, pane borders and
+app window tabs are display-time tmux policy: the app config derives both from
+the active pane's visible label expression, while raw shell or terminal titles
+remain metadata that may change independently. Branch names continue to appear
+in the statusbar git segment; branch-based shell title overwrites are not the
+canonical Projmux window naming source.
+
 The primary inspection surface is `Projects > Sessions > State`. It shows a
 read-only overview first: latest snapshot status, named snapshots, window ->
 pane structure, cwd, recipe, and agent resume health. Mutation belongs one
@@ -74,7 +84,16 @@ metadata when available. `Back` returns to the project list without creating,
 replaying, or opening a session. After the startup mode is selected, project
 hook/config trust is evaluated if needed; approval continues the selected path
 and deny/cancel aborts before session create, snapshot replay, or startup
-command. Existing sessions switch directly without a startup picker.
+command. The Alt-1 sidebar does not render trust approve/deny rows inline:
+before trust is requested, projmux snapshots the sidebar query/selection
+context and hands the selected open continuation to a detached tmux job. That
+job closes the sidebar popup state for the client and opens the shared `Trust
+project hooks` popup as a client-scoped decision surface, so no code relies on
+the self-closing sidebar popup process continuing after `display-popup -C`.
+Deny/cancel or trust-popup errors return to the sidebar near the same
+query/selection with a visible status message; only a missing/invalid context
+may fall back to a closed popup plus tmux message. Existing sessions switch
+directly without a startup picker or trust gate.
 
 Default `projmux shell` no longer opens a compatibility startup picker and no
 longer accepts startup selector flags for session-state restore. It always

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
@@ -54,6 +71,17 @@ view-first layout:
   and `Notify icon` details. Each detail shows the current mode plus
   immediately selectable off/symbol/emoji preview rows. There is no separate
   `Change` page for icon decoration.
+- `Settings > Appearance` also shows a read-only `Theme font` status row.
+  `font_family` and `font_size` are desired values from the effective
+  project/global theme, and unsupported terminal paths must say `not applied`
+  instead of implying tmux changed the font.
+- `Settings > Appearance > Language / Locale` is the global/user language
+  detail. The root row shows the saved `[ui].locale` value and the currently
+  effective locale. The detail shows `Current`, `[ui].locale`, optional
+  `PROJMUX_LOCALE` env override, and direct choices for `auto`, `en-US`, and
+  `ko-KR`. When `auto` is active it must show the detected source (`LC_ALL`,
+  `LC_MESSAGES`, `LANG`, or fallback). Unsupported locale tags must remain
+  visible as warnings and fall back to `en-US`.
 
 Hooks remain the reference pattern for this IA:
 
@@ -68,8 +96,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.
@@ -75,6 +86,11 @@ The notify segment renders the newest queued item as a single notification
 block: project, state (`NEED`/`INFO`/`WARN`/`CRIT`), optional agent, text,
 age, and `+N` for older pending entries. Window/pane ids are not shown in the
 compact status segment.
+The compact age text is locale-formatted through `internal/i18n` (`2m ago` in
+`en-US`, `36초 전` in `ko-KR`). AI notify body text uses catalog-owned category
+labels while preserving agent names, commands, paths, URLs, and provider
+payload excerpts. The `+N` older-entry count remains a numeric compact badge so
+it does not expand the status segment.
 When the notify block is wider than its cell budget, clipping shrinks the body
 text first and appends an ellipsis while preserving project, state, agent, age,
 and count metadata. If the segment is still too wide, the age is dropped next
@@ -85,8 +101,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 +115,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,
@@ -174,6 +191,9 @@ updates the matching live tmux option
 (`@projmux_statusbar_decoration_cwd`, `_git`, or `_notify`) when run inside
 tmux. The legacy `~/.config/projmux/statusbar-decoration` and
 `@projmux_statusbar_decoration` remain fallback defaults for older configs.
+Appearance also shows the effective desired theme font. This is a status row,
+not a font editor: tmux status strings and ANSI output cannot force terminal
+font family or size, so unsupported environments report `not applied`.
 
 To add a new clickable segment:
 

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,174 @@
+# 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. Theme settings resolve project
+and global config into the resolver-facing token inventory below, then fall
+back to the built-in values from `internal/theme/palette.go`.
+
+- 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.
+
+Renderer adapters apply resolver-backed background/foreground colors to native
+picker frame chrome and to tmux status/window background tokens when an
+`EffectiveTheme` is supplied by the caller. Fallback-sourced fields still
+render through the historical constants so built-in default output remains
+byte-identical. Settings and native project picker surfaces load `[theme]`
+values from global and project config through the shared effective-theme source.
+Theme marketplace/import/export and Visual palette reselection remain out of
+scope.
+
+## Resolver Token Inventory
+
+The public resolver inventory is intentionally smaller than the current
+renderer literal inventory. Surface-specific renderers map their detailed roles
+onto these stable names:
+
+| Token | Meaning | Shared surfaces |
+| --- | --- | --- |
+| `background` | base popup/sidebar/status surface background | native picker, frame titlebar, notify sidebar, settings popup, statusbar |
+| `surface` | raised or inactive chrome surface | frame titlebar, chips, switch cards, settings popup |
+| `surface_active` | selected/current row or active chip surface | native picker current row, frame chips, statusbar active window |
+| `foreground` | primary readable text | native picker, titlebar, statusbar, notify sidebar, settings popup |
+| `muted` | secondary text, divider, disabled or stale details | picker metadata, titlebar rule, notify age/stale, settings descriptions |
+| `accent` | pointer, primary action, highlight, active affordance | native picker pointer/highlight, settings actions, chips |
+| `critical` | destructive/error/critical state | settings remove/quit, notify critical badge, statusbar critical usage |
+| `warning` | progress, pending, warning, busy state | AI busy/thinking indicators, notify pending title, usage warning |
+
+Renderer-only role names such as `accent.ai`, `state.progress`, `git.branch`,
+and trust colors remain in `internal/theme/palette.go` until Phase 2+ maps each
+surface to the resolver tokens. The key product contract for this phase is that
+native picker, frame titlebar, chips, statusbar, notify sidebar, and settings
+popup all consume a shared effective token set instead of independently
+choosing colors.
+
+Font is not part of this universal token inventory. `font_family` and
+`font_size` are resolved as terminal capability/profile hints: projmux can
+store and display the desired value, but tmux/ANSI rendering cannot force a
+font family or size across terminal emulators. In environments without a
+supported terminal font adapter, projmux reports the desired font as
+`not applied` instead of treating storage as a successful font change.
+
+## Mapping Policy
+
+Native picker rows can emit truecolor SGR, while tmux statusbar/config strings
+must use tmux color specs. The resolver therefore carries both forms for each
+color token.
+
+Rules:
+
+- Truecolor tokens keep exact `#RRGGBB` values and can be converted to
+  foreground/background SGR fragments such as `38;2;R;G;B` or `48;2;R;G;B`.
+- Tmux tokens keep `colourN` strings where tmux owns rendering.
+- The built-in `projmux-dark` fallback uses the established ANSI and tmux
+  tokens from `internal/theme/palette.go` to preserve current output.
+- Explicit `#RRGGBB` overrides keep exact truecolor and derive the closest
+  xterm 256-color `colourN` token for tmux surfaces.
+- 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.
+
+## Resolver Contract
+
+Theme resolution is field-by-field after validating each layer:
+
+1. Project `.projmux/config.toml`
+2. Global `~/.config/projmux/config.toml`
+3. Built-in fallback preset `projmux-dark`
+
+Rules:
+
+- Project values override global values for the same field.
+- Missing or `inherit` project values fall back to global values.
+- Missing global values fall back to built-in values.
+- A preset fills missing color tokens in its own layer.
+- Explicit color tokens in the same layer override preset colors.
+- An unknown preset invalidates only that layer and emits a warning.
+- An invalid color, `font_family`, or `font_size` invalidates only that layer
+  and emits a warning.
+- Every effective field reports `project`, `global`, or `fallback` as its
+  source label.
+
+Built-in preset config values are:
+
+- `projmux-dark`
+- `midnight`
+- `forest`
+- `rose`
+- `high-contrast`
+
+## 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/ui/projmuxpicker/frame.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`