projmux 0.6.4 → 0.6.6

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/hooks.md

@@ -206,7 +206,11 @@ desktop sender and receives positional arguments
 `summary body urgency app-name tag group icon-path`. That `urgency` value is
 the OS notification urgency, not the notify-queue severity. AI approval,
 input, selection, and confirmation rows can stay critical in the queue and UI
-while the desktop notification hook receives `normal`.
+while the desktop notification hook receives `normal`. Live AI status badges
+are a third surface: permission/input-required panes use the action-required
+amber-orange status role, response-complete panes use success green, and
+in-progress panes use progress yellow. They do not inherit the critical queue
+severity, and permission/input status badges do not use red.
 
 ## Codex Hooks Engine
 

package/docs/keybindings.md

@@ -12,8 +12,7 @@ supported fallback guidance.
 The recommended path when a key does not fire:
 
 1. Try the key inside `projmux shell`.
-2. Open Settings > Keybindings > Diagnostic, or run `projmux setup` outside
-   tmux, to see which bytes reach the process.
+2. Run `projmux setup` outside tmux to see which bytes reach the process.
 3. For supported terminals, preview `projmux init [terminal]`; add `--apply`
    only after reviewing the merge.
 4. For unsupported terminals, configure plain Meta bytes or add a tmux alias in
@@ -47,6 +46,12 @@ keymap actions, pane switching, window switching, and rename actions remain
 visible. Transport-dependent rows show the default transport key separately
 from editable plain aliases.
 
+The Settings flow is intentionally simple: the root is one action list with
+current key summaries, and each action detail shows the action, current
+keybinding/aliases, `Add alias`, and reset. 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 aliases can be added for actions such as:
 
 | Canonical action | Meaning |
@@ -67,19 +72,20 @@ without storing or replacing the transport default. Rename actions no longer
 have a built-in terminal fallback; use tmux's prefix rename flow or configure
 an explicit safe alias where the action is editable.
 
-## Roadmap Requirements
+## Product Requirements
 
-Follow-up Phase 2 keeps Settings > Keybindings as a discovery surface. It must
-continue to expose launch toggles, sidebar keymap actions, picker-local actions,
-pane switching, window switching, and rename actions. Transport-dependent rows
-should explain the default transport key and offer only additive safe plain
-aliases; diagnostic-only rows should explain why they are not editable.
+Settings > Keybindings stays a discovery surface. It must continue to expose
+launch toggles, sidebar keymap actions, picker-local actions, pane switching,
+window switching, and rename actions. The primary Settings flow is not the
+terminal remediation surface: replace-primary, disable-default, typed fallback,
+terminal mapping preview/apply, and init execution rows stay out of the action
+detail.
 
-Follow-up Phase 3 removes the `UserN` / `CSI-u` route from the product model.
-Windows Terminal and Ghostty-centered replacements should use plain
-Meta/control chords or xterm modifier sequences where possible. If a key cannot
-be represented that way, leave it as a non-editable unsupported or diagnostic
-row instead of preserving a User-key or CSI-u fallback.
+The product model does not support `UserN` or `CSI-u` as fallback guidance.
+Windows Terminal and Ghostty adapters use built-in plain Meta/control bytes or
+xterm modifier sequences where possible. If a key cannot be represented that
+way, leave it as a non-editable unsupported or diagnostic row instead of
+preserving a User-key or CSI-u fallback.
 
 ## Picker Actions
 
@@ -131,8 +137,8 @@ names: `ProjectSidebarToggle`, `NotifySidebarToggle`, `SessionPopupToggle`,
 ## Diagnose: `projmux setup`
 
 Run `projmux setup` outside tmux to find out which projmux keys reach the raw
-terminal. The same diagnostic is available in-app at Settings > Keybindings >
-Diagnostic.
+terminal. Settings > Keybindings remains the action/alias editor; setup is the
+terminal delivery diagnostic.
 
 | Status | Meaning |
 | --- | --- |

package/docs/native-picker-parity.md

@@ -46,8 +46,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; 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`; `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 with neutral titlebar background, rule fill, and a divider above search/content, and the native Alt-1 project sidebar opts into `Projects`; `TestRendererRenderFrameWithTitleKeepsDefaultWhenTitleEmpty`; `TestRendererRenderFrameWithTitleUsesTitlebarRow`; `TestRendererContentLayoutWithTitleReservesTitlebarRow`; `TestNativeInteractiveRendersOptionalTitlebar`; `TestSwitchCommandNativeSidebarSetsTitle` |
+| 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` |
 | 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
@@ -72,9 +73,11 @@ native picker engine and is not a public dependency-policy change.
 ## Frame Chrome ANSI
 
 Native picker frame chrome is normalized in `internal/ui/projmuxpicker`.
-Titlebars restore the titlebar style after embedded ANSI resets, 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
+Titlebar text, title dividers, and chip-strip gaps inherit the frame
+background/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
 inherit it. This phase does not add popup modes or change the `popup-toggle`
 contract; native popups still rely on the existing borderless tmux popup path.
 

package/docs/npm-distribution.md

@@ -31,13 +31,15 @@ make npm-pack
 or:
 
 ```bash
-scripts/package-npm.sh --version 0.4.0 --out /tmp/projmux-npm --pack
+scripts/package-npm.sh --version 1.2.3 --out /tmp/projmux-npm --pack
 ```
 
 The script stages package directories under `dist/npm` by default. It builds
 the Go binary for each supported platform, copies package metadata and docs,
-updates package versions in the staged copies, then runs `npm pack --dry-run`
-when `--pack` is set.
+updates package versions in the staged copies, generates root
+`optionalDependencies` for the supported platform packages using the same
+version, verifies the staged metadata is internally consistent, then runs
+`npm pack --dry-run` when `--pack` is set.
 
 ## Publish Order
 

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

@@ -15,13 +15,21 @@ view-first layout:
   actions live inside that view.
 - `Settings > Project Picker > Project Root` shows effective and saved values
   first, then the edit actions, then the explanatory hints.
-- `Settings > Keybindings` is the single entry point for keybinding work. The
-  page is split into four chips: `Bindings`, `Diagnostic`, `Probe`, and `Init`.
-- `Settings > Keybindings > Bindings` is a keybinding discovery surface, not
-  only a launch-toggle editor. It must show `Toggle Project Sidebar` with the
+- `Settings > Keybindings` is a single action list plus a simple action detail.
+  It does not expose `Bindings`, `Diagnostic`, `Probe`, or `Init` as first-class
+  chips/tabs in the Settings root flow.
+- `Settings > Keybindings` is a keybinding discovery surface, not only a
+  launch-toggle editor. It must show `Toggle Project Sidebar` with the
   guaranteed `Alt-1` / `M-1` default, plus sidebar-local commands, picker-local
   commands, `Pane navigation`, `Window navigation`, and `Rename` groups or
   equivalent searchable rows.
+- `Settings > Keybindings > Action` keeps the user-facing edit path small:
+  action, current keybinding/aliases, `Add alias`, and reset. It does not offer
+  replace-primary, disable-default, typed-fallback, terminal mapping preview, or
+  terminal mapping apply rows.
+- Terminal delivery remediation lives outside Settings primary flow. The
+  supported order is `projmux shell` first, then `projmux setup`, then
+  `projmux init` for supported terminal adapters.
 - Rows that cannot safely be edited still stay visible. Mark diagnostic-only
   rows with the delivery path and reason instead of hiding them or turning them
   into unsupported editable aliases. Transport-dependent rows stay visible with
@@ -55,8 +63,8 @@ view-first layout:
   `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/ai-hook-actions.json`. It does not
   edit catalog `install` values or run agent install/remove commands.
 - `Settings > Labs` keeps experimental toggles, but keybindings no longer have a
-  visible Labs row. The hidden compatibility action still redirects to the
-  unified Keybindings page.
+  visible Labs row. The hidden compatibility action redirects to the
+  `Settings > Keybindings` action list, not to a diagnostic default.
 - `Settings > Labs > Project Hooks` is overview-first. The Labs root opens the
   overview, and the on/off mutation rows live one level deeper.
 - `Settings > AI Settings` is view-first. The root contains `Default split
@@ -71,6 +79,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

@@ -33,6 +33,25 @@ row 1  [#S]  #{pane_current_path}  ⎈ <ctx>/<ns>  <git>   %H:%M
   clicks on tmux 3.4+, so a `run-shell` handler can't recover the
   target after the fact — the Go dispatcher's
   `isWindowListRangeToken` fallback is now defense-in-depth only.
+  Each window tab reserves a one-cell live pane attention prefix from
+  `projmux attention window #{window_id}` before the index. AI panes use the
+  semantic `@projmux_ai_badge_kind` first: approval/input-required panes use
+  the action-required amber-orange role, response-complete panes use the
+  non-critical success green role, and in-progress panes use the progress
+  yellow role. Red/critical is reserved for error, failure, and risk chrome;
+  permission or input-required status badges do not use it.
+  Legacy busy/reply title and attention-state markers remain the fallback, and
+  no-state windows render a blank placeholder so title alignment and click range
+  width stay stable. This live window-list badge is independent from the row-0
+  notify queue segment and from notify queue severity or desktop notification
+  urgency. For example, an approval request may remain a critical queued
+  notification while its live status badge renders action-required amber-orange.
+  Window-list badges and app pane-border badges use the same semantic priority,
+  with display style controlled by Settings > Appearance > AI badge style and persisted in
+  `~/.config/projmux/ai-badge-style`. The default is `dot`; `emoji` renders
+  `⏳` for approval/input-required, `✅` for response-complete, and `🔄` for
+  in-progress. `off` (also accepted as `minimal` when read from disk) preserves
+  the same spacing without drawing a marker.
   The session, pwd, kube, and git segments on this row are wrapped
   in `#[range=user|<id>]` ranges and dispatched through the projmux
   handler. The standalone config also wraps the right-side `projmux`
@@ -86,13 +105,19 @@ 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
 while badges and the `+N` count stay visible when possible. Very narrow widths
-fall back to the severity-colored dot plus clipped text and count; the final
+fall back to dotless clipped text plus the `+N` count when it fits; the final
 hard-truncate path still closes with `#[default]` so later status segments do
-not inherit notification styling.
+not inherit notification styling. That dotless narrow fallback applies only to
+the queued notify segment, not to the separate window-list live attention badge.
 `usage` opens a native-framed detail HUD for the compact usage bar. It reads
 the cached usage state in-process, keeps the existing `projmux usage` CLI
 output shape unchanged for external consumers, aligns model/window rows with
@@ -186,6 +211,9 @@ updates the matching live tmux option
 (`@projmux_statusbar_decoration_cwd`, `_git`, or `_notify`) when run inside
 tmux. The legacy `~/.config/projmux/statusbar-decoration` and
 `@projmux_statusbar_decoration` remain fallback defaults for older configs.
+Appearance also shows the effective desired theme font. This is a status row,
+not a font editor: tmux status strings and ANSI output cannot force terminal
+font family or size, so unsupported environments report `not applied`.
 
 To add a new clickable segment:
 

package/docs/testing.md

@@ -54,3 +54,125 @@ desktop shell, or OS integration:
 
 Keep those checks as manual or host-run smoke validation until a dedicated
 host harness exists.
+
+Use this smoke checklist when a change touches terminal delivery, host desktop
+notifications, or reviewer confidence around those boundaries. If the change
+does not touch those areas, copy the PR-note block below and mark the relevant
+rows `not run`.
+
+### Terminal Key Delivery
+
+Run the raw key probe outside tmux, in the terminal emulator being claimed:
+
+```sh
+projmux setup --timeout 10s
+```
+
+Observe:
+
+- `Alt-1` through `Alt-5` report `OK plain`. These are the guaranteed
+  zero-config launch defaults.
+- If a guaranteed key reports `MISS timeout`, preview a supported terminal
+  mapping with `projmux init ghostty` or `projmux init windows-terminal`,
+  apply it with the same command plus `--apply`, restart that terminal if
+  required, and rerun `projmux setup --timeout 10s`.
+- Optional direct aliases and transport-dependent chords may be reported by
+  the probe, but they are not part of the guaranteed host smoke unless the PR
+  explicitly changes them.
+
+Then run the app in the same terminal:
+
+```sh
+projmux shell
+```
+
+Observe:
+
+- `Alt-1` opens the project sidebar.
+- `Alt-2` opens the notification sidebar.
+- `Alt-3` opens the existing-session picker.
+- `Alt-4` opens the AI split picker.
+- `Alt-5` opens Settings.
+- Pressing the same launch key again closes the popup instead of typing escape
+  bytes into the shell or picker input.
+
+### WSL Toast
+
+Run this from WSL with Windows Terminal available. The detached tmux server is
+intentional: `projmux focus` falls back to the product desktop notification
+path when there is no attached client to switch.
+
+```sh
+sock="${TMPDIR:-/tmp}/projmux-host-smoke.sock"
+tmux -S "$sock" kill-server 2>/dev/null || true
+tmux -S "$sock" new-session -d -s projmux-host-smoke 'sleep 600'
+PROJMUX_DESKTOP_NOTIFY_MODE=notify \
+  projmux focus --socket "$sock" --target projmux-host-smoke --json
+tmux -S "$sock" kill-server
+```
+
+Observe:
+
+- The JSON includes `"ok":true`, `"dispatch":"notify-only"`, and
+  `"reason":"no-attached-client"`.
+- Windows shows a short projmux toast with `session ready:
+  projmux-host-smoke`.
+- No visible PowerShell or console window remains open after the toast.
+
+If the PR changes click-to-focus behavior, repeat with
+`PROJMUX_DESKTOP_NOTIFY_MODE=raise`, click the toast, and record whether the
+host terminal returns to the target. Otherwise leave click callbacks marked as
+manual/not run.
+
+### macOS GUI Notification
+
+The built-in desktop sender is Linux/WSL-oriented. On macOS, smoke the
+documented `PROJMUX_NOTIFY_HOOK` escape hatch with an `osascript` sender:
+
+```sh
+hook="${TMPDIR:-/tmp}/projmux-macos-notify.sh"
+cat >"$hook" <<'SH'
+#!/bin/sh
+title=${1:-projmux}
+body=${2:-}
+osascript \
+  -e 'on run argv' \
+  -e 'display notification (item 2 of argv) with title (item 1 of argv)' \
+  -e 'end run' \
+  "$title" "$body"
+SH
+chmod 0755 "$hook"
+
+sock="${TMPDIR:-/tmp}/projmux-host-smoke.sock"
+tmux -S "$sock" kill-server 2>/dev/null || true
+tmux -S "$sock" new-session -d -s projmux-host-smoke 'sleep 600'
+PROJMUX_NOTIFY_HOOK="$hook" \
+  projmux focus --socket "$sock" --target projmux-host-smoke --json
+tmux -S "$sock" kill-server
+```
+
+Observe:
+
+- The JSON includes `"ok":true`, `"dispatch":"notify-only"`, and
+  `"reason":"no-attached-client"`.
+- macOS shows a Notification Center banner with `session ready:
+  projmux-host-smoke`.
+- If macOS prompts for notification permission, record that state in the PR
+  instead of treating the product command as verified.
+
+### PR Note Template
+
+```markdown
+Host-only smoke validation:
+
+- Docker-covered checks: `make test-integration`, `make test-install-smoke`,
+  and `make test-e2e` cover portable Linux tmux/config/notify behavior only.
+- Terminal key delivery: not run / run on <terminal>; `projmux setup --timeout
+  10s` showed <result>; `Alt-1..5` app popup smoke <passed/failed/not run>.
+- WSL toast: not run / run on <Windows + WSL distro>; detached-focus smoke
+  produced `dispatch=notify-only`; observed <toast/no toast/notes>.
+- macOS GUI notification: not run / run on <macOS version>; hook smoke
+  produced `dispatch=notify-only`; observed <banner/permission prompt/notes>.
+- Desktop notification click callbacks: not run unless this PR changes
+  click-to-focus behavior; result <notes>.
+```