projmux 0.7.0 → 0.7.1

package/docs/agent-workflow.md

@@ -29,7 +29,7 @@
 - `make fmt`: repository formatting for Go, shell snippets, and generated docs where applicable.
 - `make fix`: safe automatic fixes such as `go fix` and repository-approved cleanup steps.
 - `make npm-pack`: local npm binary package staging and `npm pack --dry-run` for the root package plus platform packages.
-- `make test`: fast unit coverage for app-layer AI split native agent launch/selective popup-toggle/settings/status/notification parity including AI pane option metadata, watcher metadata bootstrap for existing panes, capture-backed reply detection, missing-pane watcher shutdown, armed focus-only reply badge clearing, busy attention preservation on focus clear, manual AI topic preservation while watcher status still updates, agent-labeled desktop notification message context with pane-title-first body text, global/project-local lifecycle hook dispatch for post-create/pre-create/post-attach/send-noti with project hook and `.projmux/config.toml` trust-store hashing plus env/settings kill-switch gating, declarative startup command and hook run coverage, `send-noti` stdin JSON delivery plus `PROJMUX_NOTIFY_*` env payload, notify queue write success/failure/depth-guard dispatch rules, notify/statusbar/sidebar origin-client focus routing, project config env/kube session environment application, Settings project config env/kube/startup form writes with trust-store refresh and preserved hook commands, startup command send-keys orchestration plus startup pane replay markers, pre-create abort behavior, and shared projmux notification icon paths, and scoped even row/column resizing after shell and agent splits, status-bar git/kube segment parity including muted git branch block styling and compact dirty/staged/ahead/behind state colors, statusbar pwd display-only native-framed path popup with shared popup-wait-key/no-extra-payload-line command coverage, no clipboard or tmux buffer copy, and popup-wait-key cursor/raw-mode restore coverage, statusbar usage native HUD popup alignment/height-budget/threshold palette/muted sync-staleness/fallback coverage without raw CLI popup or popup-toggle stacking, statusbar settings click popup fallback and settings chip right-edge rendering without default trailing space, popup-toggle stale marker recovery, isolated `projmux shell` tmux app launch/config generation including home fallback plus project-context default session targeting from `PROJMUX_CWD` or nearest project marker, app-owned project-name statusbar layout, distinct project badge color, and quiet debounced session-state autosave command/app-config trigger, shell-entry welcome release prompt and inline update handling, shell update skip-by-latest-tag behavior plus best-effort stale-cache refresh, pane/window keybindings, keymap.toml tmux override rendering/stale unbinds including retired direct/UserKey cleanup, Settings Keybindings root/list/detail capture flows including parse-error rows, unsafe raw capture and timeout guards, disable/reset writes, app config regeneration, live tmux source-file reload, and no-live-tmux save behavior, window rename bindings, pane rename helper/binding, pane-exit rebalance command/hooks, hook-pane and after-select-pane based attention focus hooks, attention badge toggle/clear/list/window rendering, attach/current/kill/pin/preview/prune/sessions/session-popup/settings commands, switch, tag, tmux helper commands, update status/check/apply cache and installer detection including GitHub Release binary asset selection/extraction/replacement, doctor install-missing command selection, AI notify integration diagnostics, and Session State resume metadata diagnostics, Settings AI notify integration diagnostics read-only status/conflict/CLI guidance, and Settings About update status/check action wiring, untitled standalone popup-toggle marker close/config install, direct popup minimum sizing, AI picker minimum width and height, sidebar minimum width and compact badge spacing, preview select writes, popup render output after cycling, switch picker pin action behavior without inline settings rows, nested settings hub sections for AI defaults, project picker filesystem scan/pin actions, Project Root settings source/shadowing/set/current/clear flows, app/keybinding info including Ctrl-M rename forwarding, and About version/source rendering, switch picker focused-session kill, switch picker launcher-key abort bindings, switch explicit project-root, unconfigured-root, and weak managed-root heuristic parity, switch popup hiding new-session candidates while sidebar keeps create-capable rows, switch row project-name display with `~` pinned to the top and live-session-first sorting, pretty-path, preview-context including kube context/namespace, switch settings subcommand flows including add-current-pin, interactive add-pin picker, and settings label/preview polish including Phase 2 Settings/hookmaker/project-startup/trust/quit destructive row color regression strings, native preview wiring, baseline picker surface parity including prompt/footer/header fallback without app-name filler and search-key scoped card matching, sidebar compact action-only key footer, sidebar preview-window/start-position behavior without focus-time session switching, sidebar row/window ANSI styling with pane-aggregated attention badge state and AI topic labels, Alt+2/Alt+3 legacy popup row, preview-window, pane metadata, and pane-snapshot parity, switch read0 card rows with active/inactive title styling, right-side status badges, combined directory/git metadata with muted inactive branch styling, statusbar-matched block window tabs with window attention badges, read0 expect-key action parsing, restored pin/tag card badges, and restrained selected-row marker styling, switch preview metadata without duplicated directory/git rows, preview metadata rendering, popup pane display names for AI agents, AI topics, and shell commands, switch preview cycle bindings, sessions picker preview/cycle/open/kill wiring including attached-session fallback behavior, sessions picker launcher-key abort bindings, popup/switch preview summary formatting, popup sessions tmux entry helpers, switch/popup/session rendering, session identity, session-state Claude/Codex/Antigravity resume and declarative startup replay, session snapshot capture/autosave recipe classification including save/autosave pre-capture resume metadata refresh from live AI session ids including Antigravity conversation ids, Claude transcript paths, and Codex rollout log cwd matching/ambiguity skips, candidate discovery, config path derivation, popup preview read-models, and pure state rules including preview, tag, and lifecycle stores.
+- `make test`: fast unit coverage for app-layer AI split native agent launch/selective popup-toggle/settings/status/notification parity including AI pane option metadata, watcher metadata bootstrap for existing panes, capture-backed reply detection, missing-pane watcher shutdown, armed focus-only reply badge clearing, busy attention preservation on focus clear, manual AI topic preservation while watcher status still updates, agent-labeled desktop notification message context with pane-title-first body text, global/project-local lifecycle hook dispatch for post-create/pre-create/post-attach/send-noti with project hook and `.projmux/config.toml` trust-store hashing plus env/settings kill-switch gating, declarative startup command and hook run coverage, `send-noti` stdin JSON delivery plus `PROJMUX_NOTIFY_*` env payload, notify queue write success/failure/depth-guard dispatch rules, notify/statusbar/sidebar origin-client focus routing, project config env/kube session environment application, Settings project config env/kube/startup form writes with trust-store refresh and preserved hook commands, startup command send-keys orchestration plus startup pane replay markers, pre-create abort behavior, and shared projmux notification icon paths, and scoped even row/column resizing after shell and agent splits, status-bar git/kube segment parity including muted git branch block styling and compact dirty/staged/ahead/behind state colors, statusbar pwd display-only native-framed path popup with shared popup-wait-key/no-extra-payload-line command coverage, no clipboard or tmux buffer copy, and popup-wait-key cursor/raw-mode restore coverage, statusbar usage native HUD popup alignment/height-budget/threshold palette/muted sync-staleness/fallback coverage without raw CLI popup or popup-toggle stacking, statusbar settings click popup fallback and settings chip right-edge rendering without default trailing space, popup-toggle stale marker recovery, isolated `projmux shell` tmux app launch/config generation including home fallback plus project-context default session targeting from `PROJMUX_CWD` or nearest project marker, app-owned project-name statusbar layout, distinct project badge color, and quiet debounced session-state autosave command/app-config trigger, shell-entry welcome release prompt and inline update handling, shell update skip-by-latest-tag behavior plus best-effort stale-cache refresh, pane/window keybindings, keymap.toml tmux override rendering/stale unbinds including retired direct/UserKey cleanup, Settings Keybindings root/list/detail capture flows including parse-error rows, unsafe raw capture and timeout guards, disable/reset writes, app config regeneration, live tmux source-file reload, no-live-tmux save behavior, and stage-by-stage apply recovery copy, window rename bindings, pane rename helper/binding, pane-exit rebalance command/hooks, hook-pane and after-select-pane based attention focus hooks, attention badge toggle/clear/list/window rendering, attach/current/kill/pin/preview/prune/sessions/session-popup/settings commands, switch, tag, tmux helper commands, update status/check/apply cache and installer detection including GitHub Release binary asset selection/extraction/replacement, doctor install-missing command selection, AI notify integration diagnostics, and Session State resume metadata diagnostics, Settings AI notify integration diagnostics read-only status/conflict/CLI guidance, and Settings About update status/check action wiring, untitled standalone popup-toggle marker close/config install, direct popup minimum sizing, AI picker minimum width and height, sidebar minimum width and compact badge spacing, preview select writes, popup render output after cycling, switch picker pin action behavior without inline settings rows, nested settings hub sections for AI defaults, project picker filesystem scan/pin actions, Project Root settings source/shadowing/set/current/clear flows, app/keybinding info including Ctrl-M rename forwarding, and About version/source rendering, switch picker focused-session kill, switch picker launcher-key abort bindings, switch explicit project-root, unconfigured-root, and weak managed-root heuristic parity, switch popup hiding new-session candidates while sidebar keeps create-capable rows, switch row project-name display with `~` pinned to the top and live-session-first sorting, pretty-path, preview-context including kube context/namespace, switch settings subcommand flows including add-current-pin, interactive add-pin picker, and settings label/preview polish including Phase 2 Settings/hookmaker/project-startup/trust/quit destructive row color regression strings, native preview wiring, baseline picker surface parity including prompt/footer/header fallback without app-name filler and search-key scoped card matching, sidebar compact action-only key footer, sidebar preview-window/start-position behavior without focus-time session switching, sidebar row/window ANSI styling with pane-aggregated attention badge state and AI topic labels, Alt+2/Alt+3 legacy popup row, preview-window, pane metadata, and pane-snapshot parity, switch read0 card rows with active/inactive title styling, right-side status badges, combined directory/git metadata with muted inactive branch styling, statusbar-matched block window tabs with window attention badges, read0 expect-key action parsing, restored pin/tag card badges, and restrained selected-row marker styling, switch preview metadata without duplicated directory/git rows, preview metadata rendering, popup pane display names for AI agents, AI topics, and shell commands, switch preview cycle bindings, sessions picker preview/cycle/open/kill wiring including attached-session fallback behavior, sessions picker launcher-key abort bindings, popup/switch preview summary formatting, popup sessions tmux entry helpers, switch/popup/session rendering, session identity, session-state Claude/Codex/Antigravity resume and declarative startup replay, session snapshot capture/autosave recipe classification including save/autosave pre-capture resume metadata refresh from live AI session ids including Antigravity conversation ids, Claude transcript paths, and Codex rollout log cwd matching/ambiguity skips, candidate discovery, config path derivation, popup preview read-models, and pure state rules including preview, tag, and lifecycle stores.
 - `make test` also covers Settings > AI Settings > Enabled agents Phase 0 config behavior: missing config enables Claude, Codex, and Antigravity, unknown saved provider names are ignored without disabling known providers, Settings toggles persist Claude/Codex/Antigravity only, shell/selective are absent from enabled-agent rows, and a saved default split mode warns when its provider is disabled.
 - `make test` also covers native Alt-1 sidebar `Sidebar:KillSession` mutable refresh: the action kills through the focused-session safety path, keeps the native picker session open, refreshes rows and preview with `picker.Action.Mutate`/`DeferredUpdate`, and preserves the previous-live-session guard.
 - `make test` also covers Notify sidebar pane-grouped read-model rows and interactions: collapsed pane inbox group construction, fixed three-line group cards with stable project/provider, topic/context, aggregate metadata, and latest-preview slots including topic-with-project cases, child-count badges that match expandable child rows without rendering `+0`, childless group headers without strong fold affordance, selected/expanded marker-only row shape changes, duplicate label/preview reduction, worst-severity aggregation, inactive/gone group display and child-count rendering, pane-less fallback grouping, compact newest-first child event rows with warn/critical severity preservation, Right/Left fold mutation plus childless Right no-op refresh, folded and expanded live group Enter focus+ack with mixed-severity critical rows, inactive-but-routable group Enter focus+ack, gone group Enter cleanup without focus including critical rows, target-gone race cleanup, transient focus-failure no-ack refresh, child Enter focus/ack preservation, explicit group acknowledgement including mixed-severity critical rows, and grouped deferred refresh output with expanded-state pruning.
@@ -37,7 +37,7 @@
 - `make test` also covers usage HUD/all-model filtering from Settings > AI Settings > Enabled agents: ambient `status usage` and `usage --model all` scope collection/rendering to enabled Claude/Codex providers, all-disabled all-model output shows a Settings fallback without refreshing adapters, disabled cached rows/backoff do not leak into ambient output, and explicit `usage --model claude|codex` still collects/renders the requested provider even when disabled.
 - `make test` also covers AI semantic badge renderer aggregation for window-list, sidebar rows, switch window tabs, popup pane summaries, and pane-border topic badges using prompt-required > response-complete > in-progress priority while preserving blank no-state lanes, response-complete live badge consume on attention clear without idling action-required/progress badges, plus Settings > Appearance AI badge style selection for dot/emoji/off pane-border, Alt-1 sidebar window/preview tabs, and tmux window-status compatibility with dot as the persisted/config fallback.
 - `make test` also covers AI semantic badge Phase 3 theme-role hardening: `@projmux_ai_badge_kind` storage values and aggregate priority stay unchanged, `minimal` remains a read-time alias for the `off` badge style, progress/success/action-required badge roles stay distinct, permission/input status badges do not use critical red, and critical notify queue severity does not drive live AI status badge colors or desktop notification urgency.
-- `make test` also covers keybinding surface tier catalog rules, action-centered `keymap.toml` `keys = [...]` multi-alias parsing/writing, quoted internal `Surface:Action` tables, legacy popup action ID aliases, canonical popup toggle names, AI split popup-vs-direct action labels, generated tmux config multi-alias rendering, global/direct conflict detection, surface-scoped native picker command conflict detection, Settings Keybindings list/search/detail surface-aware picker-local labels, compact action-list state copy, flat Keys list/action detail rows, key detail remove/test rows, Add key default press-key flow with Advanced typed entry, collapsed Troubleshooting entry copy, Labs compatibility redirect to the Keybindings root, capture/add-key flows, unsafe raw capture, reset behavior, stale guide docs guards, and welcome/runtime footer copy that avoids hardcoded launch-key guides.
+- `make test` also covers keybinding surface tier catalog rules, action-centered `keymap.toml` `keys = [...]` multi-alias parsing/writing, quoted internal `Surface:Action` tables, legacy popup action ID aliases, canonical popup toggle names, AI split popup-vs-direct action labels, generated tmux config multi-alias rendering, global/direct conflict detection, surface-scoped native picker command conflict detection, Settings Keybindings list/search/detail surface-aware picker-local labels, compact action-list state copy, flat Keys list/action detail rows, key detail remove/test rows, Add key default press-key flow with Advanced typed entry, collapsed Troubleshooting entry copy, Settings delivery diagnostics that split logical key/raw bytes/tmux received key while distinguishing missing, ambiguous, adapter-needed, and delivered states, safe direct key pool and risky/reserved diagnostic-only copy, Projmux-owned Ghostty/Windows Terminal advanced delivery copy, raw escape/CSI-u/xterm modified/UserKey/UserSequence rejection from primary keymap storage, Labs compatibility redirect to the Keybindings root, capture/add-key flows, unsafe raw capture, reset behavior, stale guide docs guards, and welcome/runtime footer copy that avoids hardcoded launch-key guides.
 - `make test` also covers welcome revisit policy: legacy welcome state remains readable without suppressing shell entry, Enter continues without storing release skip, `s` stores an update skip for the current latest tag when an update is available, source installs show disabled Upgrade guidance, stale update cache refresh is best-effort, Settings > About > Welcome opens a Settings-native viewer without pending state, and shell prompt display does not schedule a redundant attach popup.
 - `make test` also covers transport-dependent app tmux defaults for pane/window navigation (`M-Left`/`M-Right`/`M-Up`/`M-Down` and `M-S-Left`/`M-S-Right`) while keeping visible default chords, allowing additive safe plain aliases that do not store or remove the transport defaults, and no UserKey/CSI-u generated fallback.
 - `make test` also covers direct `projmux ai split --agent <claude|codex|antigravity|shell|selective>` launches, enabled-agent gating for disabled direct launches and disabled saved defaults, `--force-agent` as an explicit direct CLI-only override, selective picker filtering with all-disabled shell fallback guidance, config-default preservation, extra args appended to resolved agent executables, managed pane metadata, title watcher startup, layout application, plain shell split behavior, selective picker delegation, invalid direct-agent usage errors, and regressions that direct concrete-agent and saved-default splits create a new pane without probing existing AI pane metadata or selecting an existing pane, including when launched from the current AI pane.
@@ -65,9 +65,9 @@
 - `make test` also covers `projmux ai ingest log` tail/path rendering and bounded JSONL log trimming for ingest diagnostics.
 - `make test` also covers welcome revisit policy: legacy `skip_version` readability without shell suppression, `s` Skip until next vs Enter continue, Settings > About > Welcome native viewer, best-effort shell update cache refresh, and attach-popup no-duplicate/no-op behavior.
 - `make test` also covers `projmux quit` action-picker rows, cancel/close no-op behavior, explicit quit of only app-owned mux runtimes marked by `@projmux_app=1` on the selected `tmux`/`psmux -L projmux` backend, missing/default runtime no-ops, dispatcher wiring, and `Settings > About > Quit projmux` routing through the same picker before any shutdown side effect.
-- `make test` also covers the built-in semantic palette foundation: non-empty fallback truecolor/tmux tokens, distinct action/attention/AI/progress/danger roles, native picker chip/current/titlebar render strings including titlebar frame background/foreground inheritance without separate overlay ANSI, statusbar git/notify/usage/settings palette regressions, attention/pane-border/popup/switch progress color guards, renderer-only lead-mode topic prefix styling, settings/trust/destructive row color guards, Theme settings Phase 0/1 resolver behavior for project/global/fallback source labels, preset fill, explicit token override, invalid-layer warnings, and truecolor-to-tmux mapping, Phase 2 fallback render parity and project/global color isolation for native picker and tmux status/window background adapters, native popup-toggle `display-popup -s` body style propagation from the effective theme without touching global popup/shell/status styles, Phase 3 desired font config save/resolve plus unsupported `not applied` status without breaking no-adapter fallback rendering, and Phase 4 Settings theme editing boundaries for project/global resets, project inherit-vs-override labels, effective source labels, and project config theme values feeding the native project popup render path.
+- `make test` also covers the built-in semantic palette foundation: non-empty fallback truecolor/tmux tokens, distinct action/attention/AI/progress/danger roles, native picker chip/current/titlebar render strings including titlebar frame `surface` / `chrome_foreground` inheritance without separate overlay ANSI, statusbar git/notify/usage/settings palette regressions, attention/pane-border/popup/switch progress color guards, renderer-only lead-mode topic prefix styling, settings/trust/destructive row color guards, global-only theme resolver behavior for `global`/`fallback` source labels (project `[theme]` is not a source), preset fill, explicit token override, unknown-preset/invalid-color warnings that ignore only the global layer, and truecolor-to-tmux mapping with generated `xterm*:RGB` terminal feature support, semantic role map (`RenderRoles`/`ANSIRoles`) fallback byte-identity for non-background historical palette literals plus explicit-theme repaint of Tier A/B chrome/state roles while Tier C renderer-only literals stay fixed, split foreground behavior where legacy `foreground` fills `text_primary` and `chrome_foreground` but `text_primary` does not repaint frame/title/search/border/status chrome, Phase 6 public token (`progress`/`success`/`action_required`/`pane_active_bg`/`focus`) repaint of the tmux and ANSI roles with `action_required` kept independent of `critical`, default `projmux` background tokens pinned to terminal default without separate terminal preset variants, Phase 6b pane-body-vs-popup/status background separation where an explicit `background` repaints the inactive pane body, an explicit `surface` repaints popups/native frames, and an explicit `status_background` repaints only the bottom status bar, native popup-toggle `display-popup -s` body style propagation from the effective theme without touching global popup/shell/status styles, and Settings global theme editing with the merged Global/Effective view, directly selectable prefixed theme token rows, no legacy `foreground` row, no project theme editor, and no font keys.
 - `make test` also covers Recent Windows Phase 0 state/model behavior: server-scoped file paths, missing/corrupt state policy with corrupt-file backup, MRU newest-first recording, same-window dedupe and promotion, default queue limiting, current-window exclusion, cross-session candidate retention, gone-window pruning against live window inventory, and label fallback rules that keep win/pane ids as debug fallback instead of the primary row label.
-- `make test` also covers Recent Windows Phase 1 native picker behavior: `projmux window recent` empty-state messaging, cross-session candidate picker rows with descriptive project/session/window/pane command age metadata, window-only switching without pane restoration, switch-failure refresh/prune handling, and gone-window pruning before picker selection.
+- `make test` also covers Recent Windows Phase 1 native picker behavior: `projmux window recent` empty-state messaging, cross-session candidate picker rows with descriptive project/session/window/pane command age metadata, pane summaries mirroring visible pane labels with AI topic and known-shell command precedence, four visible pane cells before compact `+N` overflow, window-only switching without pane restoration, switch-failure refresh/prune handling, and gone-window pruning before picker selection.
 - `make test` also covers Recent Windows Phase 2/3/4 keybinding, popup, and runtime recorder integration: `RecentWindows:Open` owns the guaranteed `M-3` launch default, generated tmux config uses client-scoped `tmux popup-toggle recent-windows`, the popup body runs `projmux window recent`, generated tmux config installs background `window record` hooks for window and client-session changes plus first-use population without `session-window-changed`, `window record` snapshots current tmux socket/session/window/active-pane metadata into the socket-scoped store with escaped field parsing, repeated same-window record fires dedupe instead of growing entries, the queue remains bounded by `recentwindows.DefaultLimit`, Settings > Keybindings shows Recent Windows with the `M-3` default, setup probe text names Recent Windows, `SessionPopupToggle` no longer owns the guaranteed `M-3` default, and escaped tmux field separators are parsed for current/list window metadata.
 - Current focused unit coverage also includes strict notify SOT behavior
   (TTL does not remove rows, focus success and target-gone clicks ack,

package/docs/cli.md

@@ -658,9 +658,13 @@ accepted by `popup-toggle` mirror the historical sessionizer surface:
 `session-popup`, `sessionizer`, `sessionizer-sidebar`,
 `notify-sidebar`, `recent-windows`, `ai-split-picker-right`,
 `ai-split-picker-down`, `ai-split-settings`.
-`apply` reloads the live `-L projmux` server's config without restarting
-it; `make install` and `projmux upgrade` invoke it after replacing the
-binary.
+`apply` regenerates the app tmux config and reloads the live `-L projmux`
+server without restarting it. `make install` and `projmux upgrade` invoke it
+after replacing the binary. Settings > Keybindings normally runs the same
+save/config/reload flow automatically; use `projmux tmux apply` as the CLI
+recovery or sync path after hand-editing `keymap.toml`, after saving Settings
+outside tmux, or after resolving a reported config-generation or live-reload
+failure.
 
 ## update
 
@@ -775,7 +779,10 @@ flags with the top-level `switch` UX:
   switcher's saved workdirs list, Labs (experimental), Settings > Keybindings,
   and About/Update status. The keybinding flow is a single
   `Settings > Keybindings` action list with simplified action details for
-  aliases and reset. Terminal diagnostics and terminal mapping application stay
+  aliases and reset. Key save/reset automatically writes the key list,
+  regenerates the app config, and reloads the running tmux session when
+  possible; skipped or failed stages show `projmux tmux apply` as the recovery
+  or sync command. Terminal diagnostics and terminal mapping application stay
   in the `projmux shell` -> `projmux setup` -> `projmux init` remediation path.
   The About section includes the `Welcome` entry. In Project
   Picker, `Project Root` manages the saved

package/docs/configuration.md

@@ -169,30 +169,66 @@ configured key opens and closes the popup.
 
 ## Theme Resolver Foundation
 
-Theme settings are resolved against the same project/global axes as
-declarative hooks and project recipe fields:
+Theme is a global user preference. The effective theme resolves from the global
+user theme plus a built-in fallback only:
 
 ```text
-<project>/.projmux/config.toml
 ~/.config/projmux/config.toml
+built-in fallback preset
 ```
 
-Settings can edit the global `[theme]` in `~/.config/projmux/config.toml` and
-the current project override in `<project>/.projmux/config.toml`. The Effective
-theme view shows the final project > global > built-in fallback value for each
-field with source labels: `project`, `global`, or `fallback`.
+Settings edits the global `[theme]` in `~/.config/projmux/config.toml`. The
+Effective theme view shows the final global > built-in fallback value for each
+field with source labels: `global` or `fallback`. Saving or resetting a theme
+value live-applies it: projmux regenerates the generated tmux config and, when
+Settings runs inside tmux, `tmux source-file`-reloads it so a running server
+repaints immediately. Outside tmux the save still succeeds and the report
+prints `Next: run \`projmux tmux apply\`` to sync a running server.
+
+The `background`, `surface`, `status_background`, `surface_active`, and
+`pane_active_bg` tokens additionally accept the value `default` ("Terminal
+default" in Settings) to keep that role at the terminal background. Priority is
+**explicit `default` > preset fill > unset (fallback)**, so picking a preset and
+then setting (for example) `background = "default"` keeps every other token
+preset-filled while the pane body stays at the terminal default (`window-style
+"bg=default"`). Set `surface = "default"` separately when popup/native frame
+backgrounds should inherit the terminal background, set
+`status_background = "default"` when the bottom status line should do the same,
+and set `pane_active_bg = "default"` when the active pane should not be tinted.
+`default` is only valid on these background-like tokens. See
+`docs/theme-palette.md` for the full sentinel contract.
+
+Project `.projmux/config.toml` `[theme]` is **deprecated and ignored**: it is no
+longer an effective theme source and does not influence the native picker,
+statusbar, popup, or any tmux chrome. Settings has no Project theme tab, project
+override editor, project theme reset action, or `project` source label — both
+the global theme editor and the effective theme view live under the Global tab.
+See `docs/upgrading.md` for the migration note for existing project `[theme]`
+users.
 
 Renderer adapters can apply an already resolved `EffectiveTheme` to native
-picker frame background/foreground SGR and tmux status/window `colourN`
-background tokens. Settings and native project picker surfaces load global and
-project `[theme]` values through the shared effective-theme source. Native
-picker frames also apply the built-in fallback `background`/`foreground` tokens
-so picker-owned padding, empty rows, footer rows, and preview gaps do not
-inherit the terminal default background.
+picker frame `surface` / `chrome_foreground` SGR, tmux window background tokens,
+and the bottom status bar `status_background` token. Settings and native project
+picker surfaces load global `[theme]` values through the shared effective-theme
+source. Native picker frames also apply the built-in fallback `surface` /
+`chrome_foreground` tokens so picker-owned padding, empty rows, footer rows, and
+preview gaps do not inherit the terminal default background.
+
+Active pane focus is part of the theme app chrome. The active pane is marked by
+an active border (`pane-active-border-style`, fallback cyan `colour51`, the
+public `focus` token) and a subtle dark background tint (`window-active-style`,
+fallback `colour234`, the public `pane_active_bg` token); inactive panes follow
+the public `background` token (tmux `window-style`, unset keeps `bg=default`).
+tmux draws a single shared border between adjacent panes, so a full active-pane
+rectangle is not guaranteed; focus is reinforced by the tint plus the
+`pane-border-status top` topic line. This chrome preserves `pane-border-status
+top`, pane topics, AI badges, and visible pane labels.
 
 Native picker popups launched through `projmux tmux popup-toggle` also pass a
 per-popup tmux 3.4 `display-popup -s` body style using the effective theme
-`background`/`foreground` tmux tokens. This styles only the tmux popup body
+`surface` / `chrome_foreground` tmux tokens (popup/native backgrounds follow
+`surface`, while the bottom status bar follows `status_background`). This styles
+only the tmux popup body
 before the native renderer draws. It does not set global `popup-style` or
 `popup-border-style`, and it does not change shell pane backgrounds,
 `default-style`, `window-style`, OSC terminal backgrounds, or the general
@@ -202,33 +238,59 @@ Resolver schema shape:
 
 ```toml
 [theme]
-preset = "projmux-dark"
-background = "#182226"
-surface = "#182226"
+preset = "projmux"
+background = "default"
+surface = "default"
+status_background = "#182226"
 surface_active = "#2c383d"
-foreground = "#d8e0e4"
+chrome_foreground = "#d8e0e4"
+text_primary = "#d8e0e4"
 muted = "#75848c"
 accent = "#7ac7ad"
 critical = "#ff6b6b"
 warning = "#ffcc66"
-font_family = "Cascadia Mono"
-font_size = 12
+progress = "#ffcc66"
+success = "#5faf87"
+action_required = "#ffaf00"
+pane_active_bg = "default"
+focus = "#00ffff"
 ```
 
-Supported presets are `projmux-dark`, `midnight`, `forest`, `rose`, and
-`high-contrast`. A preset fills missing color tokens in its own layer, and
-explicit color tokens override preset values. Missing or `inherit` values fall
-through to the next layer.
-
-Unknown presets and invalid color/font values invalidate only their own theme
-layer and produce resolver warnings; the next source still resolves normally.
+`text_primary` controls primary content text in native terminal-rendered UI.
+`chrome_foreground` controls frame, title, search, status, border-adjacent, and
+other app chrome foreground roles. The older `foreground` key is still accepted
+as a legacy alias/fill value: when present, it fills `text_primary` and
+`chrome_foreground` unless either new key is explicitly set. New configs should
+prefer the split keys, and Settings presents the split names rather than
+encouraging writes to `foreground`.
+
+`progress`, `success`, and `action_required` are the AI/status colors (progress
+yellow, success green, action-required amber-orange). `action_required` is the
+AI "needs input/approval" badge color and is intentionally independent of
+`critical` — repainting `critical` never changes it. `pane_active_bg` is the
+active-pane background tint, and `focus` is the active-pane border color. Each
+of these is a public token: leave it unset to keep the historical built-in
+color, or set it to repaint the matching chrome.
+
+Supported presets are `projmux`, `high-contrast`, `blue-hour`, `carbon-violet`,
+`ember`, `forest`, and `rose`. A preset fills
+missing color tokens, and explicit color tokens override preset values. Tokens
+the global theme leaves unset fall through to the built-in fallback preset.
+Terminal-default backgrounds are configured per token with the `default`
+sentinel rather than through separate terminal preset variants.
+
+Unknown presets and invalid color values invalidate only the global theme
+source and produce resolver warnings; the built-in fallback still resolves
+normally.
 Colors are `#RRGGBB`. Settings edits colors through a preset selector, swatch
-rows, and a hex input page. Truecolor renderers use exact RGB SGR tokens, and
-tmux surfaces use the stored or nearest xterm 256-color `colourN` mapping. Font
-values are desired terminal profile hints, not universal tmux or ANSI renderer
-tokens. Without a supported terminal font adapter, Settings reports the
-effective desired font as `not applied`; projmux does not create or modify
-terminal profiles in this phase.
+rows, and a hex input page. Native truecolor renderers and tmux style roles use
+the exact hex value; 256-color mappings are retained only for renderer paths
+that explicitly require xterm `colourN`/ANSI-256 colors. Generated tmux config
+adds `xterm*:RGB` to `terminal-features` so capable terminals render exact
+theme hex values instead of tmux downsampling them to the nearest 256-color
+entry. The theme has no font keys: `font_family` and `font_size` were removed in
+Phase 1b because tmux/ANSI rendering cannot force a terminal font. Leftover font
+keys in an existing config are accepted but ignored. See `docs/upgrading.md`.
 
 ## UI Locale
 

package/docs/keybindings.md

@@ -18,10 +18,23 @@ The recommended path when a key does not fire:
 4. For unsupported terminals, configure plain Meta bytes or add a custom key in
    Settings > Keybindings.
 
-Settings saves safe tmux plain chords for actions. Successful saves use simple
-confirmation copy; if saving, runtime config update, or active tmux reload
-fails, the error names the failed stage. Raw escape payloads, Windows Terminal
-`sendInput` strings, and tmux User keys are rejected as action keys.
+Settings saves safe tmux plain chords for actions and automatically applies the
+change to the app config and the running tmux session when Settings is opened
+from inside tmux. After each save/reset it shows the three outcomes together:
+saved, prepared, and running session. Successful in-tmux saves keep those labels
+user-facing; failure and skipped states include diagnostic terms such as
+`keymap.toml`, generated tmux config, or live tmux reload so the broken stage is
+clear. If Settings is run outside tmux, the running-session stage is skipped and
+the recovery/sync action is `projmux tmux apply`. Raw escape payloads, Windows
+Terminal `sendInput` strings, and tmux User keys are rejected as action keys.
+Settings capture diagnostics split the observed result into logical key, raw
+bytes, and the tmux key name that can be saved. Diagnostic states distinguish
+keys that did not arrive, ambiguous bytes such as Enter/Ctrl-M, and keys that
+need a supported terminal adapter. Safe direct keys are logical tmux names such
+as `M-a`, `M-1`, `C-r`, `C-Space`, function/navigation names, or printable
+keys. Raw escape bytes, CSI-u, xterm modified-key payloads, and tmux
+UserKey/UserSequence names stay diagnostic-only and are not promoted into
+`keymap.toml`.
 
 ## Quick Start
 
@@ -55,10 +68,14 @@ Custom, Available, and Unbound. Each action detail shows the action label,
 state, a flat Keys list with `+ Add key`, Options, and a collapsed
 Troubleshooting row with Test key delivery and Advanced... entry points. Key
 rows open key detail for Remove key and Test key. Add key opens Press a key by
-default; Enter key name and raw diagnostics live under Advanced. Options covers
-unbinding the action and reset/use-default flows. Diagnostic/probe/init
-workflows are not first-class Settings tabs; use `projmux setup` and
-`projmux init` from the terminal when key delivery needs remediation.
+default; Enter key name, the safe direct key pool, risky/reserved key copy, and
+raw diagnostics live under Advanced. Advanced delivery is still owned by the
+selected Projmux action: supported Ghostty and Windows Terminal mappings are
+previewed/applied through `projmux init`, not by storing raw sequences in the
+primary keymap. Options covers unbinding the action and reset/use-default
+flows. Diagnostic/probe/init workflows are not first-class Settings tabs; use
+`projmux setup` and `projmux init` from the terminal when key delivery needs
+remediation.
 
 Optional direct keys can be added for actions such as:
 
@@ -128,6 +145,23 @@ uppercase `A`, distinct from `NotifySidebar:Ack` on lowercase `a`.
 Runtime picker footers render key guides from the merged keymap, using the
 first active key as the representative key.
 
+In Settings > Keybindings, **Add key** appends a key to the selected action's
+`keys = [...]` list. For catalog popup toggle actions, those keys are used both
+by generated tmux open bindings and by popup-internal close bindings, so the
+same key can close the corresponding already-open popup. This same-key close
+behavior is only for actions cataloged as popup toggles, such as
+`ProjectSidebarToggle`, `NotifySidebarToggle`, `RecentWindows:Open`,
+`AISplitPickerToggle`, `SettingsToggle`, `ProjectSwitcherToggle`, and
+`SessionPopupToggle`. Direct command actions such as `new-window`, pane/window
+navigation, and direct AI split actions remain command bindings and are not
+treated as popup close keys.
+
+Settings is the default apply path for key edits: it writes the key list,
+refreshes the generated config, and reloads the running tmux session when
+possible. Use `projmux tmux apply` as a CLI recovery/sync command after editing
+the keymap file by hand, after an outside-tmux Settings save, or after resolving
+a reported generated-config or live-reload failure.
+
 ## Keymap File
 
 Settings writes the action-centered multi-alias schema:
@@ -172,6 +206,16 @@ terminal delivery diagnostic.
 | `MISS timeout` | No bytes arrived because the terminal swallowed the key. |
 | `MISS unknown` | Bytes arrived, but they do not match the expected plain sequence. |
 
+Settings capture uses the same underlying probe but reports a read model with
+separate fields:
+
+| Field | Meaning |
+| --- | --- |
+| Logical key | The key the user intended to press, such as `Alt-1`. |
+| Raw bytes | The bytes captured from the terminal, shown escaped. |
+| tmux received key | The logical tmux key name that can be saved, or a diagnostic placeholder when none is safe. |
+| Delivery status | `delivered`, `key-did-not-arrive`, `ambiguous-key`, or `adapter-needed`. |
+
 Useful flags:
 
 ```sh

package/docs/native-picker-parity.md

@@ -47,9 +47,9 @@ native picker engine and is not a public dependency-policy change.
 | fzf navigation keys | interactive selection in searchable lists | Covered | native maps modified-key `Ctrl-J` plus `Ctrl-N` to down and `Ctrl-P`/`Ctrl-K` to up when not claimed by a custom action; up/down-family movement is safe on empty lists; raw LF remains Enter for PTY compatibility; `TestNativeInteractiveSupportsFZFNavigationKeys`; `TestNativeInteractiveNavigationKeysAreNoopForEmptyList` |
 | alternate-screen lifecycle | fzf fullscreen picker screen restore | Covered | native frame updates and screen exit return to column 0 before terminal control sequences, screen exit resets styles plus clears the alternate buffer from the home cursor before restore, and real TTY restores get a short settle window before caller handoff; `nativeScreenEnter`; `TestNativeInteractiveUsesAlternateScreen`; `TestRenderFullFrameUpdateAlwaysHomesAndWritesFrame` |
 | frame content width | fzf border inner width | Covered | `ContentLayout` uses the frame inner width so separators and rows reach the right border; `TestRendererContentLayoutUsesFrameInnerWidth` |
-| picker-owned app background | native picker frame interior | Covered for renderer-owned cells | `ThemeFromEffective` applies built-in fallback and explicit effective background/foreground SGR to the native frame, and frame rows resume the app style after embedded resets so content padding, empty no-footer rows, footer rows, scrollbars, and preview gaps do not leak terminal default background; `TestThemeFromEffectiveFallbackPaintsFrameBackground`; `TestRendererFrameBackgroundResumesAfterContentResetBeforePadding`; `TestNativeInteractiveNoFooterBlankRowsUseThemeBackground`; `TestNativeInteractiveSplitPreviewGapsUseThemeBackground`; `TestNativeInteractiveSettingsAIBadgeStyleLongPreviewClampsFrameRows` |
-| tmux popup frame interaction | native picker popups launched through `popup-toggle` | Covered for native backend popups | `popup-toggle` passes tmux `display-popup -B` when `PROJMUX_PICKER_BACKEND=native`, so the native picker owns the visible frame instead of double-drawing with the tmux popup border; tmux 3.4 per-command `display-popup -s` is used for the popup body style, setting `bg`/`fg` from the same effective theme tmux background/foreground tokens so tmux's blank/pre-draw popup body matches the native picker surface before the app renderer paints; no global `popup-style`, `popup-border-style`, shell pane background, `default-style`, `window-style`, OSC background, or status/window palette options are changed; native Alt-1 uses a compact native-only minimum while fzf keeps the previous project sidebar minimum; Alt-1/Alt-2 sidebar heights reserve two bottom statusbar rows; Alt-2 notify sidebar keeps the fzf-like `24%` / min `64` baseline; `TestAppRunTmuxPopupToggleUsesBorderlessPopupForNativeBackend`; `TestAppRunTmuxPopupToggleUsesNativePopupBodyStyleFromEffectiveTheme`; `TestBuildPopupToggleWithPickerBackendStylesNativeOnly`; `TestBuildDisplayPopupArgsAddsBodyStyle`; `TestSessionizerSidebarWidthKeepsFZFMinimum`; `TestSidebarPopupHeightLeavesStatusbarRows`; `TestNotifySidebarWidthMatchesFZFBaseline`; `TestAppRunTmuxPopupToggleKeepsNotifySidebarFZFSizingForNative` |
-| optional native titlebar | native picker popup frame | Covered for empty-title compatibility and opt-in titles | `picker.Options.Title`; `RenderFrameWithTitle`; `ContentLayoutWithTitle`; empty titles keep the prior frame unchanged, non-empty titles render in a picker-owned section below the top border, titlebar text/divider/chip gaps inherit the frame background/foreground instead of a separate titlebar overlay ANSI layer, and the native Alt-1 project sidebar opts into `Projects`; `TestRendererRenderFrameWithTitleKeepsDefaultWhenTitleEmpty`; `TestRendererRenderFrameWithTitleUsesTitlebarRow`; `TestRendererContentLayoutWithTitleReservesTitlebarRow`; `TestNativeInteractiveRendersOptionalTitlebar`; `TestSwitchCommandNativeSidebarSetsTitle` |
+| picker-owned app background | native picker frame interior | Covered for renderer-owned cells | `ThemeFromEffective` applies built-in fallback and explicit effective `surface` / `chrome_foreground` SGR to the native frame, and frame rows resume the app style after embedded resets so content padding, empty no-footer rows, footer rows, scrollbars, and preview gaps do not leak terminal default background; `TestThemeFromEffectiveFallbackPaintsFrameBackground`; `TestRendererFrameBackgroundResumesAfterContentResetBeforePadding`; `TestNativeInteractiveNoFooterBlankRowsUseThemeBackground`; `TestNativeInteractiveSplitPreviewGapsUseThemeBackground`; `TestNativeInteractiveSettingsAIBadgeStyleLongPreviewClampsFrameRows` |
+| tmux popup frame interaction | native picker popups launched through `popup-toggle` | Covered for native backend popups | `popup-toggle` passes tmux `display-popup -B` when `PROJMUX_PICKER_BACKEND=native`, so the native picker owns the visible frame instead of double-drawing with the tmux popup border; tmux 3.4 per-command `display-popup -s` is used for the popup body style, setting `bg` from `surface` and `fg` from `chrome_foreground` so tmux's blank/pre-draw popup body matches the native picker surface before the app renderer paints; no global `popup-style`, `popup-border-style`, shell pane background, `default-style`, `window-style`, OSC background, or status/window palette options are changed; native Alt-1 uses a compact native-only minimum while fzf keeps the previous project sidebar minimum; Alt-1/Alt-2 sidebar heights reserve two bottom statusbar rows; Alt-2 notify sidebar keeps the fzf-like `24%` / min `64` baseline; `TestAppRunTmuxPopupToggleUsesBorderlessPopupForNativeBackend`; `TestAppRunTmuxPopupToggleUsesNativePopupBodyStyleFromEffectiveTheme`; `TestBuildPopupToggleWithPickerBackendStylesNativeOnly`; `TestBuildDisplayPopupArgsAddsBodyStyle`; `TestSessionizerSidebarWidthKeepsFZFMinimum`; `TestSidebarPopupHeightLeavesStatusbarRows`; `TestNotifySidebarWidthMatchesFZFBaseline`; `TestAppRunTmuxPopupToggleKeepsNotifySidebarFZFSizingForNative` |
+| optional native titlebar | native picker popup frame | Covered for empty-title compatibility and opt-in titles | `picker.Options.Title`; `RenderFrameWithTitle`; `ContentLayoutWithTitle`; empty titles keep the prior frame unchanged, non-empty titles render in a picker-owned section below the top border, titlebar text/divider/chip gaps inherit the frame `surface` / `chrome_foreground` instead of a separate titlebar overlay ANSI layer, and the native Alt-1 project sidebar opts into `Projects`; `TestRendererRenderFrameWithTitleKeepsDefaultWhenTitleEmpty`; `TestRendererRenderFrameWithTitleUsesTitlebarRow`; `TestRendererContentLayoutWithTitleReservesTitlebarRow`; `TestNativeInteractiveRendersOptionalTitlebar`; `TestSwitchCommandNativeSidebarSetsTitle` |
 | redraw flicker/top clipping | keyboard navigation in exact-height tmux popup | Partially covered | native redraws use synchronized updates plus coalesced row diffs after the first frame, skip unchanged frames, render frame diffs before sidebar focus commands, frame rendering avoids trailing bottom-border CRLF, and screen exit clears the alternate buffer before restore; `TestNativeInteractiveWrapsRedrawsInSynchronizedUpdates`; `TestFrameUpdateRendererSkipsUnchangedFrame`; `TestFrameUpdateRendererCoalescesEachFrameUpdate`; `TestRendererRenderFrameUsesCRLFRowsForRawTTY`; `TestNativeInteractiveUsesAlternateScreen` |
 
 ## Native Surface Architecture
@@ -75,7 +75,7 @@ native picker engine and is not a public dependency-policy change.
 
 Native picker frame chrome is normalized in `internal/ui/projmuxpicker`.
 Titlebar text, title dividers, and chip-strip gaps inherit the frame
-background/foreground instead of applying a second titlebar overlay ANSI layer;
+`surface` / `chrome_foreground` instead of applying a second titlebar overlay ANSI layer;
 chip bodies can still carry active/inactive/disabled tones. Search prompt and
 footer separators fill the available frame width, and header, row, footer, and
 preview lines close any active SGR style before padding or frame borders can

package/docs/settings-ia.md

@@ -48,6 +48,13 @@ view-first layout:
   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 > Theme` (Global) is the single theme view. There is no separate
+  `Effective theme` item: the Global theme view shows each color token's value
+  inline. A token set globally (explicit value or via a global preset) shows its
+  set/override/preset summary; an UNSET token shows the resolved fallback value
+  with a dim swatch, a `(fallback)` label, and a `fallback` source. Resolver
+  warnings render as dim info rows after the token rows. Project `.projmux`
+  `[theme]` is never resolved or shown here.
 - `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
@@ -88,10 +95,6 @@ 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

package/docs/theme-palette.md

@@ -1,28 +1,34 @@
 # 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`.
+This document records the implemented theme contract and the built-in
+fallback palette that native projmux UI surfaces use when no global user theme
+is configured. The source of truth for current fallback values in code is
+`internal/theme/palette.go`, and the source of truth for the resolver and the
+semantic role map is `internal/theme/resolve.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`.
+The fallback palette is a semantic token layer. The effective theme is a global
+user theme resolved from `~/.config/projmux/config.toml`, followed by the
+built-in fallback values from `internal/theme/palette.go`. The resolver derives
+a semantic role map (`RenderRoles` for tmux chrome, `ANSIRoles` for native ANSI
+surfaces) from the effective theme, and renderers consume those roles instead of
+bare palette literals.
 
 - 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.
+Renderer adapters apply resolver-backed background and `chrome_foreground`
+colors to native picker frame chrome and to tmux status/window background tokens
+when an `EffectiveTheme` is supplied by the caller. Fallback-sourced foreground,
+status, and state fields still render through their historical constants, while
+pane and popup backgrounds may intentionally inherit the terminal default.
+Project `.projmux/config.toml` `[theme]` is deprecated and ignored: it is not an
+effective theme source, and the resolver and Settings treat any leftover project
+`[theme]` keys as inert migration data. Theme
+marketplace/import/export and Visual palette reselection remain out of scope.
 
 ## Resolver Token Inventory
 
@@ -32,22 +38,38 @@ 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 |
+| `background` | inactive pane body background | tmux inactive panes via `window-style` |
+| `surface` | popup/native frame base background | tmux popup body, native picker rows, frame titlebar/rule, settings popup |
+| `status_background` | bottom status bar background | tmux `status-style` background |
 | `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 |
+| `chrome_foreground` | app chrome readable text | native picker frame/title/search chrome, tmux status/window foregrounds, popup body style |
+| `text_primary` | primary content text | settings/info rows and native terminal-rendered content text |
+| `foreground` | legacy alias/fill for split foreground tokens | accepted in config for compatibility; Settings uses `text_primary` / `chrome_foreground` |
 | `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 |
-
-AI semantic status badges use renderer-only state roles layered on top of that
-inventory: `progress`, `success`, and `action_required`. The fallback contract
-is progress yellow, success green, action-required amber-orange. These roles are
-separate from notify queue severity and desktop notification urgency; an AI
-approval row can be `critical` in the notify queue while the live status badge
-uses `action_required`, not red. `critical` remains reserved for error, failure,
-destructive, over-limit, or risk states.
+| `progress` | in-progress / working state color | AI progress badge, statusbar progress, state.progress |
+| `success` | completed / success state color | AI success badge, state.success |
+| `action_required` | AI needs-input/approval badge color | AI action-required badge (independent of `critical`) |
+| `pane_active_bg` | active-pane background tint | active-pane window-active-style tint (tmux pane chrome) |
+| `focus` | active-pane border color | active-pane border (tmux pane chrome) |
+
+`text_primary` and `chrome_foreground` split the old broad foreground behavior:
+changing primary content text no longer repaints frame/title/search/border/status
+chrome as a side effect. The legacy `foreground` key remains readable; it fills
+both split fields unless either split field is explicitly set.
+
+`progress`, `success`, and `action_required` are public `[theme]` keys, no
+longer renderer-only candidates. The fallback contract is progress yellow,
+success green, action-required amber-orange. These roles are separate from
+notify queue severity and desktop notification urgency; an AI approval row can
+be `critical` in the notify queue while the live status badge uses
+`action_required`, not red. `action_required` is independent of `critical`:
+repainting `critical` never changes it. `critical` remains reserved for error,
+failure, destructive, over-limit, or risk states. `pane_active_bg` and `focus`
+are also public keys driving the active-pane tint and border (tmux-only pane
+chrome, with no ANSI/native role).
 
 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
@@ -56,28 +78,31 @@ 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.
+Font is not part of this token inventory. The earlier `font_family` and
+`font_size` theme keys were removed in Phase 1b: tmux/ANSI rendering cannot
+force a font family or size across terminal emulators, so the values never
+applied to the terminal. Leftover font keys in an existing config are accepted
+but ignored. See `docs/upgrading.md`.
 
 ## 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.
+accept tmux style color specs. The resolver therefore carries exact hex plus a
+256-color approximation for renderer paths that still need it.
 
 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.
+- Tmux style roles use exact `#RRGGBB` for explicit theme/preset colors and
+  keep historical `colourN` strings only for fallback literals. Generated tmux
+  config declares `xterm*:RGB` in `terminal-features` so capable terminals render
+  those exact colors instead of tmux downsampling them to xterm-256 colors.
+- The built-in `projmux` fallback keeps text/accent/state tokens from the
+  established palette while pane and popup backgrounds ride the terminal
+  default.
+- Explicit `#RRGGBB` overrides also retain the closest xterm 256-color
+  `colourN` token for 256-color-only renderer roles.
 - 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
@@ -88,32 +113,63 @@ Rules:
 
 ## Resolver Contract
 
-Theme resolution is field-by-field after validating each layer:
+The effective theme resolves theme fields from:
 
-1. Project `.projmux/config.toml`
-2. Global `~/.config/projmux/config.toml`
-3. Built-in fallback preset `projmux-dark`
+1. Global `~/.config/projmux/config.toml`
+2. Built-in fallback preset `projmux`
 
 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.
+- A preset fills missing color tokens in the global layer.
+- Explicit global color tokens override preset colors.
+- Legacy `foreground` fills `text_primary` and `chrome_foreground` unless either
+  split key is explicitly set.
+- An unknown preset invalidates only the global layer.
+- An invalid color invalidates only the global layer.
+- Every effective field reports `global` or `fallback` as its source label.
+
+### Terminal default sentinel
+
+The `background`, `surface`, `status_background`, `surface_active`, and
+`pane_active_bg` tokens accept the special value `default` ("Terminal default"
+in Settings). It pins that surface to the terminal background instead of a
+concrete color, even when a preset is selected:
+
+- Priority is **explicit `default` > preset fill > unset (fallback)**. Setting a
+  token to `default` overrides the preset's color for that token while leaving
+  every other token preset-filled.
+- On the tmux side the derived roles emit `bg=default` (for example
+  `window-style "bg=default"` from `background`, popup body style from
+  `surface`, `window-active-style "bg=default"` from `pane_active_bg`, and
+  `status-style bg=default` from `status_background`).
+- On the ANSI side the corresponding surface emits no background sequence (no
+  `48;2;…` / `48;5;…`), so the terminal background shows through.
+- `default` is only valid on `background` / `surface` / `status_background` /
+  `surface_active` / `pane_active_bg`. On any other token it is treated as an
+  invalid hex color and invalidates the global layer (same as any other invalid
+  color).
+
+Historical project `[theme]` values in `.projmux/config.toml` are migration
+data only. They are not a current or target source in this contract.
 
 Built-in preset config values are:
 
-- `projmux-dark`
-- `midnight`
+- `projmux`
+- `high-contrast`
+- `blue-hour`
+- `carbon-violet`
+- `ember`
 - `forest`
 - `rose`
-- `high-contrast`
+- `blue-hour` — dark theme tuned around a terminal blue accent; it uses a dark
+  blue-tinted inactive pane body, black popup surface, deep navy status bar,
+  and a deep indigo active pane tint.
+- `carbon-violet` — charcoal/violet dark theme with darker popup/status
+  surfaces and a black active pane tint.
+- `high-contrast` — black surfaces, white text, a dark blue active surface,
+  near-black active pane tint, vivid cyan focus, and bright
+  cyan/yellow/red/green state colors.
 
 ## Fallback Inventory
 
@@ -122,7 +178,7 @@ 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` |
+| `surface.raised` | terminal-default background with `216;224;228` text | popup/native frame surface |
 | `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 |
@@ -155,6 +211,25 @@ Surface-specific tokens:
 | 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 |
 
+Active-pane focus: tmux draws a single shared border between adjacent panes, so
+a full active-pane rectangle (e.g. tinting the whole active pane edge-to-edge)
+is not guaranteed. Active focus is instead reinforced by the `pane-border-status
+top` topic line, an active-pane border (`pane-active-border-style`, fallback
+cyan `colour51`, the public `focus` token), and a subtle dark background tint
+applied via `window-active-style` (fallback `colour234` — one tone darker than
+the base `colour235` so the active pane visibly sinks; the public `pane_active_bg`
+token). Inactive panes keep the terminal default background via `window-style
+"bg=default"` unless the public `background` token is set.
+
+Pane body vs popup vs status background: the general pane body, popup/native
+frame background, and bottom status bar are derived from separate public tokens.
+The pane body follows `background` (tmux `window-style`; unset keeps
+`bg=default`), popup/native frames follow `surface`, and the bottom status bar
+follows `status_background` (tmux `status-style`; unset keeps `colour235`).
+Built-in presets fill `status_background` from their surface color to preserve
+the old look, but an explicit `surface` override no longer repaints the bottom
+status line.
+
 ## Current Literal Inventory
 
 After the Phase 3 token pass, raw color values intentionally remain in:

package/docs/upgrading.md

@@ -30,6 +30,83 @@ the current latest release tag in `update-skip.json`; the prompt appears again
 when the cached latest tag changes. For `source` and unknown installer sources,
 Upgrade prints guidance and continues shell entry without applying anything.
 
+## Behavior Changes
+
+### Theme is now global-only
+
+Theme is a global user preference. The effective theme resolves from the global
+`[theme]` in `~/.config/projmux/config.toml` plus a built-in fallback preset.
+
+If you previously set a `[theme]` section in a project's `.projmux/config.toml`,
+it is now **deprecated and ignored** — it no longer overrides the global theme
+and does not affect the native picker, statusbar, popups, or any tmux chrome.
+The project `[theme]` keys are left in the file untouched (no warning, no
+removal); they simply have no effect.
+
+To restore your previous look, copy the values into the global
+`~/.config/projmux/config.toml` `[theme]` section, or edit them through
+Settings > Theme. Settings no longer exposes a Project theme editor, and the
+separate Effective theme view has been merged into the Global theme view: each
+token row now shows its resolved value inline, with unset tokens shown as their
+dimmed `(fallback)` value.
+
+### Foreground split
+
+The old broad `foreground` theme key is now split into two clearer public keys:
+`text_primary` for primary native content text, and `chrome_foreground` for
+frame/title/search/status/window chrome foreground roles. Existing global
+`foreground` values still work as a legacy alias/fill and will feed both split
+roles unless either new key is set explicitly. Settings shows and writes the new
+split names instead of encouraging new `foreground` writes.
+
+If your previous `foreground` override made both content and chrome change
+together, you do not need to migrate immediately. To tune them separately, copy
+the value into `text_primary` and/or `chrome_foreground`, then remove
+`foreground` when you no longer need the compatibility fill.
+
+### New public theme keys
+
+Seven new public `[theme]` keys are now available: `text_primary`,
+`chrome_foreground`, `progress`, `success`, `action_required` (AI/status
+colors), `pane_active_bg` (active-pane tint), and `focus` (active-pane border).
+Leaving a key unset keeps the historical built-in color; setting it repaints the
+matching role. `action_required` is independent of `critical` — repainting
+`critical` never changes it. The full public token set is documented in
+`docs/configuration.md` and `docs/theme-palette.md`.
+
+The active-pane tint (`pane_active_bg`) defaults to the terminal background in
+the built-in `projmux` preset; set it to a concrete color when the active pane
+should visibly sink. The active-pane border (`focus`) defaults to cyan
+`colour51`. Both apply only to tmux pane chrome.
+
+Built-in presets are intentionally small: `projmux`, `high-contrast`,
+`blue-hour`, `carbon-violet`, `ember`, `forest`, and `rose`. Terminal-default
+backgrounds are configured per token with the `default` sentinel rather than
+through separate terminal preset variants.
+
+### Pane body vs popup backgrounds
+
+The general (pane) background and the popup/chrome background are now driven by
+separate public tokens. The pane body follows `background` (unset keeps the
+terminal default), while the status bar, native popup bodies, and the
+settings/notify/recent/picker frames follow `surface`. Because the `surface`
+fallback equals `background`, leaving both unset looks exactly as before; set
+them to different values to make popups read as a distinct surface from the pane
+body.
+
+### Theme font keys removed
+
+The `[theme]` `font_family` and `font_size` keys were removed. They never
+applied to the terminal — tmux/ANSI rendering cannot force a font family or
+size across terminal emulators — so they only stored and displayed a desired
+value that was always reported as `not applied`.
+
+Leftover `font_family` / `font_size` keys in a global or project
+`config.toml` are accepted but ignored: they no longer parse into the theme,
+appear in Settings, or affect any surface. You can delete them at your
+convenience. Set your terminal font through your terminal emulator's own
+profile settings instead.
+
 ## npm Installs
 
 The recommended install path is:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projmux",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "tmux project session manager",
   "license": "MIT",
   "homepage": "https://github.com/crevissepartners/projmux#readme",
@@ -28,9 +28,9 @@
     "package:npm:pack": "scripts/package-npm.sh --pack"
   },
   "optionalDependencies": {
-    "@projmux/linux-x64": "0.7.0",
-    "@projmux/linux-arm64": "0.7.0",
-    "@projmux/darwin-x64": "0.7.0",
-    "@projmux/darwin-arm64": "0.7.0"
+    "@projmux/linux-x64": "0.7.1",
+    "@projmux/linux-arm64": "0.7.1",
+    "@projmux/darwin-x64": "0.7.1",
+    "@projmux/darwin-arm64": "0.7.1"
   }
 }