projmux 0.6.4 → 0.6.5

package/docs/agent-workflow.md

@@ -48,11 +48,16 @@
 - `make test` also covers `projmux ai ingest claude-hook` core and extra Claude Code hook ingest for event parsing, transcript fallback, cataloged hook notification body formatting, permission summary formatting, UserPromptSubmit busy/no-queue behavior, Notification severity/text mapping, StopFailure/TeammateIdle text/severity/metadata mapping, SubagentStop quiet/no-notify diagnostics, unknown future-event quiet fallback, hook-active pane marking, topic preservation without hook candidate writes, mutable resume metadata writes for `@projmux_ai_resume_id`, source, and updated-at, and Claude transcript path preservation.
 - `make test` also covers the Globalization Phase 0 English baseline for AI desktop notification summaries/bodies and hook-ingest queue text while preserving agent names, tool names, commands, paths, and provider payload values as literals/data.
 - `make test` also covers the Globalization Phase 1 message catalog foundation: locale resolver priority and normalization, `ko-KR` to `en-US` fallback, missing fallback-key errors, `en-US` completeness for foundation keys, and plain-text versus ANSI/tmux-styled fragment API separation.
+- `make test` also covers the Globalization Phase 2 formatter foundation: compact/full relative age and duration formatting, locale-specific just-now text, notification count plural/count preservation, list joins that preserve payload items, status token and target label localization, terminal cell-width measurement/truncation, and ANSI/tmux style wrappers treated as zero-width.
+- `make test` also covers the Globalization Phase 3 notify runtime migration: AI notify category rendering for `en-US`/`ko-KR`, Codex/Claude hook literal preservation for agent names, tool names, commands, paths, URLs, provider messages, subagent and teammate payloads, desktop notification and in-app queue display parity, notify sidebar/statusbar locale formatter output, and raw queue storage schema preservation.
+- `make test` also covers the Globalization Phase 4 Settings and popup guidance migration: `en-US`/`ko-KR` Settings root title/chips/rows/footer rendering, native picker search/empty/footer rendering without overflow, Settings row padding by terminal cell width, shell welcome guide catalog rendering, and long Korean ANSI/tmux-styled guide truncation safety while preserving key/command/path literals.
+- `make test` also covers the Globalization Phase 5 locale settings surface: `PROJMUX_LOCALE` > global `[ui].locale` > `LC_ALL` > `LC_MESSAGES` > `LANG` > `en-US` priority, Settings > Appearance > Language / Locale row/detail visibility, `auto` current-locale/source display, unsupported locale fallback warnings, global config writes, and preserved command/config/env/path literals.
+- `make test` also covers the Globalization Phase 6 governance guard: Go string-literal audit classification for hardcoded Korean candidates, English user-facing candidates, and ignored literal/data/debug examples; no unapproved runtime Korean literals outside catalog/formatter/test fixtures; `en-US` coverage for every embedded default catalog key; and required `ko-KR` coverage for migrated notify, Settings, picker, welcome, update, and help surfaces.
 - `make test` also covers `projmux ai integrate tmux-bell` dry-run/install/remove tmux command planning, managed `alert-bell` hook append/idempotence/removal, preservation of unmanaged bell hooks, and `projmux ai ingest bell --pane` queue push/metadata/dedupe behavior for non-AI-managed panes.
 - `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: shell `skip_version` gating, `s` skip vs Enter one-run continue, Settings > About > Welcome native viewer, 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, statusbar git/notify/usage/settings palette regressions, attention/pane-border/popup/switch progress color guards, renderer-only lead-mode topic prefix styling, and settings/trust/destructive row color guards.
+- `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, 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, 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.
 - Current focused unit coverage also includes strict notify SOT behavior
   (TTL does not remove rows, focus success and target-gone clicks ack,
   reconcile reports stale rows), `notify list --live` queue/live explanations, notify sidebar

package/docs/configuration.md

@@ -158,6 +158,96 @@ chord and the replacement before binding the merged action. Popup and floating
 UI actions still route through `tmux popup-toggle`, so pressing the same
 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:
+
+```text
+<project>/.projmux/config.toml
+~/.config/projmux/config.toml
+```
+
+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`.
+
+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. Fallback
+renderer output intentionally keeps the existing palette constants byte for
+byte.
+
+Resolver schema shape:
+
+```toml
+[theme]
+preset = "projmux-dark"
+background = "#182226"
+surface = "#182226"
+surface_active = "#2c383d"
+foreground = "#d8e0e4"
+muted = "#75848c"
+accent = "#7ac7ad"
+critical = "#ff6b6b"
+warning = "#ffcc66"
+font_family = "Cascadia Mono"
+font_size = 12
+```
+
+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.
+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.
+
+## UI Locale
+
+The UI locale can be pinned globally or left on automatic detection.
+
+Preferred interactive path:
+
+- `Settings > Appearance > Language / Locale`
+
+Global config path:
+
+```text
+~/.config/projmux/config.toml
+```
+
+Schema:
+
+```toml
+[ui]
+locale = "auto" # auto | en-US | ko-KR
+```
+
+Resolution priority is:
+
+1. `PROJMUX_LOCALE`
+2. global/user `[ui] locale`
+3. auto-detected environment: `LC_ALL`, then `LC_MESSAGES`, then `LANG`
+4. built-in fallback `en-US`
+
+`auto` means detect from the environment. In Settings, the `auto` detail shows
+the currently detected locale and source. Supported UI locales are `en-US` and
+`ko-KR`; unsupported tags fall back to `en-US` and the Settings detail shows a
+warning with the unsupported value and source.
+
+Project-local locale override is not part of the runtime policy. Locale is a
+user/global preference in this release.
+
 ## Environment Variables
 
 | Variable | Purpose |
@@ -165,6 +255,7 @@ configured key opens and closes the popup.
 | `PROJMUX_PROJDIR` | Explicit primary project root. Accepts an OS-native PATH-style multi-value: the first non-empty entry is the primary root and later entries are prepended to managed-root discovery. The primary value is memoized to `~/.config/projmux/projdir`. |
 | `PROJMUX_MANAGED_ROOTS` | Search-root override. Uses the OS-native path-list separator and takes priority over the saved workdirs file and default weak probes. |
 | `TMUX_SESSIONIZER_ROOTS` | Legacy alias still honored at runtime for managed roots. |
+| `PROJMUX_LOCALE` | UI locale override. `auto` resumes detection; `en-US` and `ko-KR` pin supported locales. Unsupported tags fall back to `en-US` and surface a Settings warning. |
 | `PROJMUX_NOTIFY_HOOK` | External executable that receives AI desktop notifications instead of the built-in Linux/WSL sender. Separate from declarative `[hooks.send-noti]`. |
 | `PROJMUX_NOTIFY_HOOK_DEPTH` | Internal recursion guard for `send-noti` hooks. Depth `>= 1` suppresses nested hook dispatch while still allowing the queue write itself. |
 | `PROJMUX_NOTIFY_EXPIRE_MS` | AI desktop notification expiration in milliseconds. Defaults to `5000`; unset, zero, negative, and non-numeric values fall back to the default. |

package/docs/globalization.md

@@ -1,9 +1,9 @@
 # Globalization Contract
 
 This document is the inventory and contract for globalization. Phase 0 defined
-the user-facing text boundary and literal preservation rules. Phase 1 adds the
-message catalog foundation, locale resolver, fallback policy, and contribution
-rules for future runtime surface migrations.
+the user-facing text boundary and literal preservation rules. Later phases add
+the message catalog, locale formatters, runtime surface migration, and the
+Phase 5 user locale override surface.
 
 ## Phase 0 Scope
 
@@ -210,13 +210,16 @@ Catalog policy:
 
 Locale resolution:
 
-- Precedence is explicit override/API, then `LC_ALL`, then `LC_MESSAGES`, then
-  `LANG`, then `en-US`.
+- Precedence is explicit override/API, then `PROJMUX_LOCALE`, then global
+  `[ui] locale`, then `LC_ALL`, then `LC_MESSAGES`, then `LANG`, then `en-US`.
 - Common POSIX forms normalize into catalog tags: `ko`, `ko_KR.UTF-8`, and
   `ko-KR` become `ko-KR`; `en` and `en_US` become `en-US`.
 - `C` and `POSIX` locales are skipped as non-user-language values.
-- Phase 1 does not add Settings language UI, persisted config/env locale
-  schema, or runtime surface migration.
+- Supported UI locales are currently `en-US` and `ko-KR`. Unsupported locale
+  tags fall back to `en-US` and keep their source attached so Settings can show
+  a warning.
+- `auto` is a setting value, not a catalog locale. It means "use the
+  auto-detected environment rung".
 
 API convention:
 
@@ -242,3 +245,205 @@ Contribution convention:
 - Runtime migrations should be narrow by surface. Move a string family behind
   the catalog only when its tests can show literal preservation and fallback
   behavior for that surface.
+
+## Phase 2 Formatter Foundation
+
+Package:
+
+- `internal/i18n`
+
+Formatter policy:
+
+- Formatter functions localize grammar, units, and labels. They do not translate
+  caller-owned payload values such as product names, commands, paths, provider
+  text, tmux targets, or enum/source data inserted as arguments.
+- Formatter functions accept a `FormatVariant`. `i18n.FormatFull` is for
+  prose-friendly labels and `i18n.FormatCompact` is for dense terminal surfaces.
+- Unsupported or empty locales fall back to `en-US`. Korean locale forms
+  normalized by `ResolveLocale` use the Korean formatter rules.
+- Relative age has a pinned just-now window of less than five seconds:
+  `just now` for `en-US`, `방금 전` for `ko-KR`.
+
+Formatter API:
+
+- `i18n.FormatRelativeAge(age, locale, variant)` renders elapsed age, for
+  example `3m ago` in compact `en-US` and `36초 전` in compact `ko-KR`.
+- `i18n.FormatDuration(duration, locale, variant)` renders the largest whole
+  unit in seconds, minutes, hours, or days.
+- `i18n.FormatCount(count, subject, locale, variant)` applies locale-specific
+  count grammar for owned subjects such as `i18n.CountNotifications` while
+  preserving the numeric value.
+- `i18n.FormatList(items, locale, variant)` joins caller-owned item strings
+  using locale-specific separators without translating item payloads.
+- `i18n.FormatStatusToken(token, locale, variant)` renders shared terminal
+  status labels for known `i18n.StatusToken` values.
+- `i18n.FormatTargetLabel(kind, number, locale, variant)` localizes the target
+  label, such as window or pane, while preserving the target number.
+
+Width-safe rendering:
+
+- Use `i18n.TerminalCellWidth(value)` when terminal layout depends on visible
+  width. It measures terminal cells, not bytes or runes.
+- Use `i18n.TruncateTerminalCells(value, maxCells)` before placing
+  locale-specific output into fixed-width terminal columns.
+- ANSI escape sequences and tmux style wrappers such as `#[fg=red]` are
+  zero-width for measurement and truncation. Truncation preserves those wrappers
+  in the returned string while clipping only visible content.
+- Width clipping is a rendering concern. Keep translated format strings and
+  caller-owned payload arguments separate until the final render step.
+
+## Phase 3 Notify Runtime Migration
+
+Runtime surfaces migrated:
+
+- AI desktop notification summaries for Codex and Claude hook payloads.
+- In-app notify queue table/sidebar/statusbar display text for AI entries.
+- Notify live explanation text for `projmux notify list --live`.
+- Sidebar/table/statusbar age formatting and sidebar stale/gone/target labels.
+
+Storage and dispatch policy:
+
+- Queue storage remains schema-compatible. Stored `notify.Notification.Text`,
+  metadata keys, severity/source enum values, targets, and timestamps are not
+  localized before persistence.
+- OS notification click/focus routing is unchanged. Locale formatting only
+  changes the summary/body strings sent to the configured notifier.
+- JSON queue payloads keep raw queue entries. Localized live-row explanation
+  and row display text may appear in `notify list --live` row fields because
+  those fields are render/report output, not stored queue schema.
+
+Literal preservation and parity rules:
+
+- Translate only catalog-owned category labels such as `Response complete`,
+  `Approval required`, `Input required`, `Error`, `Subagent stopped`, and
+  `Teammate waiting`.
+- Preserve provider-owned payloads verbatim: `Codex`, `Claude`, tool names,
+  commands, paths, URLs, query strings, transcript excerpts, teammate IDs, and
+  subagent IDs.
+- Desktop notification summaries and in-app queue display text must use the
+  same rendered category labels for the same locale while preserving the same
+  literal payload body.
+- The response-complete fallback body `Ready` is treated as provider state and
+  suppressed in display detail; it is not translated or persisted differently.
+
+## Phase 4 Settings And Popup Guidance
+
+Runtime surfaces migrated:
+
+- Settings root title, scope chips, root row labels/descriptions, common row
+  labels/previews/disabled reasons, and shared Settings footer guidance.
+- Native picker search label, empty-list row, and line-mode close prompt.
+- Shell welcome/update guide text and Settings > About > Welcome viewer body.
+
+Literal preservation:
+
+- Key names such as `Enter`, `Esc`, `Ctrl-b d`, and `s` remain literal inside
+  localized guide sentences.
+- Commands, env/config names, and paths such as `projmux shell`,
+  `tmux -L projmux kill-server`, `PROJMUX_PROJDIR`, and
+  `~/.config/projmux/projdir` remain literal payload text.
+- Project names, paths, provider payloads, enum values, and hook/action IDs are
+  not translated.
+
+Width policy:
+
+- Settings row padding now uses terminal cell width instead of byte length so
+  Korean labels align with the existing ANSI row chrome.
+- Native picker prompt, empty row, and footer render through existing frame
+  truncation/padding helpers; focused tests cover `en-US`/`ko-KR` output and
+  long Korean styled guidance.
+
+## Phase 5 Locale Settings And Docs
+
+User override surface:
+
+- Environment override: `PROJMUX_LOCALE=auto|en-US|ko-KR`.
+- Global config override: `~/.config/projmux/config.toml`:
+
+  ```toml
+  [ui]
+  locale = "auto" # auto | en-US | ko-KR
+  ```
+
+- Settings surface: `Settings > Appearance > Language / Locale`.
+
+Resolution policy:
+
+1. API/explicit override used by tests and internal callers.
+2. `PROJMUX_LOCALE` when set to a non-empty value other than `auto`.
+3. Global/user `[ui] locale` when set to a non-empty value other than `auto`.
+4. Auto-detected environment, in order: `LC_ALL`, `LC_MESSAGES`, `LANG`.
+5. Built-in fallback `en-US`.
+
+`auto` in either `PROJMUX_LOCALE` or `[ui] locale` does not pin the UI to a
+literal `auto` locale. It re-enters the auto-detection path and Settings shows
+the currently detected locale and source, such as `ko-KR from LC_MESSAGES env`.
+
+Fallback and warning policy:
+
+- `en-US` and `ko-KR` are the only supported UI locales in Phase 5.
+- Unsupported locale tags such as `ja-JP` or `fr-FR` fall back to `en-US`.
+- Settings displays the unsupported tag, its source (`PROJMUX_LOCALE`,
+  `~/.config/projmux/config.toml`, `LC_ALL`, `LC_MESSAGES`, or `LANG`), and
+  the effective `en-US` fallback.
+- Project-local locale override is intentionally out of scope. Any parser
+  support for `[ui] locale` exists only because global and project config share
+  the same TOML implementation; runtime locale resolution consumes only the
+  global/user config path.
+
+Literal preservation remains unchanged:
+
+- Config keys and env vars such as `[ui].locale`, `PROJMUX_LOCALE`,
+  `LC_MESSAGES`, and `~/.config/projmux/config.toml` remain literal.
+- Locale enum values such as `auto`, `en-US`, and `ko-KR` remain literal.
+- Commands, paths, provider payloads, tmux format strings, and key names remain
+  caller-owned payload text and are not translated.
+
+## Phase 6 Governance
+
+Phase 6 prevents new user-facing strings from bypassing the catalog while
+keeping the existing literal/data/debug boundary explicit.
+
+Governance checks:
+
+- `internal/i18n` owns the Go string-literal audit helper.
+- `go test ./internal/i18n` includes synthetic audit coverage for Korean
+  candidates, English user-facing candidates, and ignored literal/data/debug
+  examples.
+- The current repo guard scans runtime Go files for new Korean string literals
+  outside the catalog, formatter locale fragments, tests, `testdata`, and
+  comments.
+- The catalog completeness tests require `en-US` fallback coverage for every
+  embedded default catalog key and required `ko-KR` coverage for migrated
+  `notify.ai.`, `notify.live.`, `settings.`, `picker.`, `welcome.`, `update.`,
+  and `help.` surfaces.
+
+Contributor rule:
+
+- New normal UX copy must be added as a stable catalog key with an `en-US`
+  fallback entry and focused test coverage.
+- If the string is intentionally not translated, classify it in review notes as
+  `literal`, `data`, or `debug-only` and preserve it verbatim.
+- Korean product UI strings must not be hardcoded in runtime Go. Add or extend
+  the catalog entry instead.
+- Do not translate provider payloads, commands, config keys, paths, env vars,
+  locale enum values, product names, or tmux/ANSI syntax.
+
+Debug/log/internal error classification:
+
+- Catalog text when it is normal UX, shown in a picker/sidebar/statusbar,
+  desktop notification, user-actionable CLI output, or other expected product
+  surface.
+- Do not catalog debug logs, trace strings, diagnostics, or wrapped internal Go
+  errors unless that exact text is promoted into normal UX.
+- If a diagnostic is surfaced as normal UX, split it: catalog the user-facing
+  explanation or action hint, and keep raw error details, paths, commands, and
+  provider payload as preserved data.
+
+Audit operation:
+
+- Run `GOCACHE=/tmp/projmux-go-cache go test ./internal/i18n` after changing
+  i18n helpers, catalog data, migrated UI strings, or locale policy.
+- For broader validation, continue to run the standard repo gates in order:
+  `make fmt`, `make fix`, `make test`, `make test-integration`, and
+  `make test-e2e` where applicable.

package/docs/pr-guideline.md

@@ -69,6 +69,11 @@ Use this template:
 - [ ] make fmt-check
 - [ ] make test
 - [ ] manual verification step (if relevant)
+
+## Globalization
+- [ ] No user-facing string changes.
+- [ ] User-facing strings are behind `internal/i18n` catalog keys with tests.
+- [ ] Non-translated strings are classified as literal/data/debug-only.
 ```
 
 Notes:
@@ -76,6 +81,11 @@ Notes:
 - **Why** matters more than **what**. Diff already shows the what.
 - Reference issues with `Closes #<n>` so they auto-close on merge.
 - Mention follow-ups explicitly when scope was deliberately deferred.
+- For any new or changed user-facing text, check exactly one Globalization
+  item. Normal UX copy needs a catalog key and test coverage. Commands, paths,
+  config keys, env vars, provider payloads, locale enum values, product names,
+  debug logs, and internal diagnostics may stay out of the catalog only when
+  explicitly classified in the PR body.
 
 ## Branch protection in effect
 

package/docs/settings-ia.md

@@ -71,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:
 

package/docs/statusbar.md

@@ -86,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
@@ -186,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/theme-palette.md

@@ -6,31 +6,70 @@ truth in code is `internal/theme/palette.go`.
 
 ## Scope
 
-The fallback palette is a semantic token layer, not a user configuration
-schema. It gives current renderers shared names for the colors stabilized by
-the Visual palette baseline work:
+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.
 
-Future Theme settings should resolve project/global values into this token
-shape, then keep the built-in values as the final fallback. This phase does not
-add `config.toml` fields, a resolver, a Settings editor, presets, import, or
-export.
+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 fallback therefore stores both forms when a
-role crosses surfaces.
+must use tmux color specs. The resolver therefore carries both forms for each
+color token.
 
 Rules:
 
-- Truecolor tokens keep exact SGR strings for native picker chrome and
-  Settings rows.
+- 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
@@ -39,6 +78,35 @@ Rules:
 - 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:
@@ -90,6 +158,7 @@ After the Phase 3 token pass, raw color values intentionally remain in:
 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`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projmux",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "description": "tmux project session manager",
   "license": "MIT",
   "homepage": "https://github.com/crevissepartners/projmux#readme",
@@ -24,10 +24,10 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@projmux/darwin-arm64": "0.6.4",
-    "@projmux/darwin-x64": "0.6.4",
-    "@projmux/linux-arm64": "0.6.4",
-    "@projmux/linux-x64": "0.6.4"
+    "@projmux/darwin-arm64": "0.6.5",
+    "@projmux/darwin-x64": "0.6.5",
+    "@projmux/linux-arm64": "0.6.5",
+    "@projmux/linux-x64": "0.6.5"
   },
   "scripts": {
     "package:npm": "scripts/package-npm.sh",