PSA/ee/docs/plans/2026-05-18-keyboard-shortcuts-shared-system/PRD.md

PRD — Shared Keyboard Shortcuts System

• Slug: 2026-05-18-keyboard-shortcuts-shared-system
• Date: 2026-05-18
• Status: Draft
• Source: .ai/keyboard-shortcuts-shared-system-plan.md

Summary

Introduce a shared, client-side keyboard shortcut system for the MSP app. Features register stable semantic actions (e.g. page.save, global.search) rather than component-specific key handlers; the system resolves which key combination invokes which action, with scope/priority arbitration, user customization, a settings UI, a discoverable help dialog, and visible kbd hints. The system is correct and identical on macOS and Windows/Linux, including for a user who configures shortcuts on one OS and signs in from another. All user-facing text is internationalized in the app's eight production locales plus pseudo-locales.

Delivery covers all six phases of the source plan: engine, global migration, panels/drawers/record nav, editors/designers, user customization, and discoverability/accessibility — including the g-then-key sequence engine and visible hints.

Problem

Keyboard handling is scattered across ad hoc window/document listeners:

• DefaultLayout.tsx (mod+l, mod+ArrowUp), SearchPalette.tsx (mod+k), AssetDashboardClient.tsx (mod+k — collides with global search), two DrawerContext files (Escape, Alt+Arrow), TicketNavigation.tsx (Alt+Arrow), useDesignerShortcuts.ts.
• Conflicts are accidental (mod+k today). Editable-target filtering is inconsistent. There is no scope/priority model, no user customization, no central list of shortcuts. Alt+Arrow collides with browser Back/Forward on Windows/Linux. No matcher correctness across OS/keyboard layouts.

Goals

• One shared registry + single delegated dispatcher under packages/ui.
• Stable action IDs; bindings configurable and decoupled from handlers.
• Scope (global/shell/page/panel/dialog/editor) + priority + active region arbitration; drawer/dialog/editor win over page over global.
• Cross-platform correctness: dual matching (event.code for physical keys, event.key for character keys), mod resolved per device, per-platform defaults, international-layout safety.
• Single-chord and multi-key sequence bindings (g then t).
• User customization persisted as platform-neutral deltas via useUserPreference; localStorage + debounced server sync; validated per target platform on load.
• Settings UI consistent with the rest of the app (settings tab shell, shared Card/Table/Switch/Button/ConfirmationDialog, react-hot-toast, handleError, LoadingIndicator).
• Discoverable help dialog + aria-keyshortcuts + visible kbd hints.
• Fully internationalized in en, fr, es, de, nl, it, pl, pt (+ xx/yy pseudo); passes validate-translations.cjs.
• All existing AI/search/drawer/ticket/designer shortcuts keep working after migration.

Non-goals

• Auth and client-portal screens (MSP /msp only for v1).
• Tenant-level shortcut defaults / admin lock (kept as future open question).
• Export/import of user override sets.
• Replacing browser-owned combos we explicitly choose not to own (mod+r/reload, mod+f/find, mod+p/print, mod+w/mod+t/mod+n).
• Migrating component-local widget key handling (DatePicker, SearchableSelect, TagInput, comboboxes, Radix internals) — these keep their local handlers; the system must not steal their keys.
• Server-side keyboard logic (system is client-only).

Users and Primary Flows

Personas: Internal MSP technician (power user, keyboard-driven); occasional MSP user (discovers shortcuts via help/hints); accessibility user (screen reader

• aria-keyshortcuts); cross-device user (configures on Mac laptop, uses Windows desktop).

Primary flows:

1. Use a default shortcut. User presses mod+k; global search focuses. The resolved combo shows in the help dialog and as a kbd hint on the control.
2. Discover shortcuts. User presses ? (or opens it from a menu) → read-only help dialog lists active shortcuts grouped by group/scope, resolved for the current OS, custom bindings flagged.
3. Sequence navigation. User presses g then t in a non-editable page region → routes to Tickets; the chord buffer times out if the second key is late.
4. Customize. Settings → Keyboard Shortcuts tab: list of actions with action label, group, current effective binding, default; user rebinds via key capture, clears a custom binding, disables an action, resets one, resets all. Conflicts are detected (platform-aware) before save.
5. Scope arbitration. A detail drawer is open over a ticket list; [/] move between adjacent records (drawer/panel scope), not list rows; Escape closes the drawer and integrates with Radix, not a competing listener.
6. Cross-device. User rebinds global.search to mod+j on macOS; signs in on Windows; it resolves to Ctrl+J automatically (neutral mod+j delta). A binding hostile on the new OS surfaces a non-blocking advisory.

UX / UI Notes

Settings panel lives as a new tab in the existing settings shell (server/src/components/settings/SettingsPage.tsx), added to baseTabContent with { id: 'keyboard-shortcuts', label: t(...), icon: KeyboardIcon, content }, wrapped in the standard Card/CardHeader/CardContent. Component: server/src/components/settings/general/KeyboardShortcutsSettings.tsx.

• Layout mirrors existing list-settings panels (e.g. ExperimentalFeaturesSettings.tsx, GeneralSettings.tsx): a Table (@alga-psa/ui/components/Table) grouped by action group, columns: Action (label + description), Scope, Default, Effective binding, Enabled (Switch), Reset (Button variant="ghost" size="sm" with RotateCcw).
• Rebind uses a capture affordance (button → "press keys" inline capture) that records event.code for code-kind and event.key for char-kind, matching the matcher. Conflicts shown inline before commit; replacing an existing binding requires explicit confirm (ConfirmationDialog).
• "Reset all" uses ConfirmationDialog (destructive intent).
• Buttons use standard variants (default primary, outline secondary, ghost icon, destructive reset-all). Every interactive element has an id.
• Feedback: react-hot-toast success + handleError(error, t(...)) on failure, consistent with other settings panels. LoadingIndicator while loading.
• Saving model: immediate, debounced via useUserPreference (no explicit Save button), consistent with preference-backed panels; UnsavedChangesProvider not required since there is no staged form.

Help dialog uses the shared Dialog (@alga-psa/ui/components/Dialog), read-only, grouped sections, bindings rendered via a shared <Kbd> component that displays platform glyphs (⌘/⌥/⇧/⌃ on macOS; Ctrl/Alt/Shift on others), resolved after mount to avoid hydration mismatch.

Visible hints: a shared <Kbd> / ShortcutHint component renders next to key actions (e.g. search field, primary buttons, menu items) and in tooltips; controls also get aria-keyshortcuts with a value derived from the effective binding via a dedicated mapping (its format differs from the internal syntax).

i18n: new namespace msp/keyboard-shortcuts for action labels, group names, help dialog, and settings panel chrome; settings-tab label added to msp/settings. All keys added to en first, then fr/es/de/nl/it/pl/pt; pseudo xx/yy regenerated; ROUTE_NAMESPACES updated so the namespace preloads for /msp. No raw user-facing strings; action labels are i18n keys passed at registration (labelKey/groupKey).

Requirements

Functional Requirements

Engine (Phase 1)

• FR1. parseBinding(str) parses modifiers + a key token, classifying the token as code (letters/digits/named keys/brackets) or char (glyphs like ?). Supports literal ctrl/meta (not remapped) plus mod.
• FR2. parseSequence(str) parses space-separated chords into an ordered sequence (e.g. "g t"), each element a single chord from FR1.
• FR3. matchEvent(event, descriptor, platform) dual matches: code-kind → event.code + exact modifier set; char-kind → event.key produced char (Shift implied by glyph), with mod/alt still required if specified.
• FR4. mod resolves to Meta on macOS, Ctrl elsewhere, at runtime per device. Platform detected client-only (post-mount), never during SSR.
• FR5. Provider installs exactly one capture-phase keydown listener on document. Registration hooks only mutate the registry.
• FR6. useShortcutAction(def) registers/unregisters an action on mount/unmount; def carries id, labelKey, groupKey, defaultBindings: { mac, other }, scope, priority, enabled, allowInEditable, handler, optional sequence flag.
• FR7. useShortcutScope(scope) pushes/pops a ref-counted active scope; cleared on route change.
• FR8. Dispatch: skip if event.defaultPrevented; match enabled actions; filter by active scopes, editable-target rule, and active-region rule for selection/single-key actions; pick highest priority; tie → most-local active scope; still tied → report conflict (dev/settings), never silent registration order. preventDefault() only when an enabled action actually handles it.
• FR9. Editable-target suppression for input/textarea/select/ contenteditable/role=textbox/role=combobox/editor roots unless allowInEditable.
• FR10. Active-region: selection.* actions fire only when a registered roving-focus region is active. Single-letter page actions (page.create/global.quickCreate) are not region-gated — they fire whenever their page scope is active and the target is non-editable, so the affordance works on page load without first focusing the list.
• FR11. Sequence dispatch: a chord buffer accumulates keys; resolves a matching sequence; resets on timeout (configurable, default ~1s), on a non-matching key, on scope/route change, or in editable targets.
• FR12. Radix Escape integration: dialog.cancel/panel.close coordinate with Radix onEscapeKeyDown + ModalityContext/InsideDialogContext; no competing global Escape listener while a Radix modal owns Escape.

Migrations (Phases 2–4)

• FR13. Provider mounted in MspLayoutClient.tsx wrapping DefaultLayout and AlgaDeskMspShell; not on auth/client-portal.
• FR14. global.search migrated from SearchPalette.tsx; global.toggleChat and ai.quickAsk from DefaultLayout.tsx (preserving aiAssistantAvailable gating); new global.openShortcuts (help) and global.quickCreate (QuickCreateDialog).
• FR15. mod+k resolution: stays global search; asset palette becomes page-scoped assets.commandPalette with a distinct default binding; AssetDashboardClient.tsx window listener removed.
• FR16. Both DrawerContext files migrated together; panel.close (Escape, Radix-integrated), drawer.historyBack/Forward.
• FR17. TicketNavigation.tsx adjacent-record nav migrated to record.previous/record.next defaulting to [/] (Alt+Arrow only as an opt-in alternate); drawer/panel scope wins over ticket page scope.
• FR18. Invoice designer (useDesignerShortcuts.ts), workflow designer, and rich-text local shortcuts migrated/wrapped into editor scope (high priority, per-platform redo, careful allowInEditable); BlockNote retains its own internal undo/redo.

Customization (Phase 5)

• FR19. Overrides persisted via useUserPreference under key keyboard_shortcuts_v1: delta-only, platform-neutral syntax, versioned, with a disabled list; localStorage + debounced server sync.
• FR20. Resolution = userOverride[id] ?? platformDefault(id, platform); a user-set value equal to the current platform default is dropped, not frozen.
• FR21. On load, overrides validated against the current platform; hostile/ reserved combos surface a non-blocking advisory; never silently rewritten.
• FR22. Versioned blob with a migration function (v1 → vN).
• FR23. Settings panel: list actions grouped by group; show label, description, scope, default, effective binding (resolved for device); rebind via key capture; clear custom; disable; reset one; reset all (confirm); inline platform-aware conflict detection before commit.

Discoverability / Accessibility (Phase 6)

• FR24. Help dialog opened by global.openShortcuts: read-only, active shortcuts only, grouped by group/scope, custom flagged, disabled hidden, bindings resolved per device.
• FR25. <Kbd>/ShortcutHint shared component renders platform glyphs; visible hints added to key controls (search field, primary action buttons, relevant menu items) and tooltips.
• FR26. aria-keyshortcuts set on instrumented controls via a mapping layer that converts the effective binding to the ARIA value format.

i18n (cross-cutting)

• FR27. New msp/keyboard-shortcuts namespace; settings-tab label in msp/settings. Action labelKey/groupKey are i18n keys from Phase 1.
• FR28. English keys authored first; fr/es/de/nl/it/pl/pt translated; pseudo xx/yy regenerated; validate-translations.cjs passes; ROUTE_NAMESPACES updated so the namespace preloads for /msp.
• FR29. Platform glyph labels (⌘/Ctrl etc.) and ARIA shortcut text are localized/handled per locale; no hardcoded user-facing strings anywhere in the system, settings, or help.

Architecture boundary (dependency direction)

• FR30. The engine in packages/ui/src/keyboard-shortcuts persists only through a ShortcutStorage adapter interface and must not import @alga-psa/user-composition or any feature package (@alga-psa/tickets|billing|assets|projects|clients|scheduling|...). The useUserPreference-backed adapter is implemented in the MSP wrapper (server/user-composition layer) and injected into the provider. A CI-runnable dependency-boundary guard enforces no forbidden imports and no new circular dependency vs .github/known-cycles.json (consistent with .github/workflows/circular-deps.yml and eslint-plugin-custom-rules).

Page-scoped create/save (commitGroup page-actions)

• FR31. page.create is a page-scoped action defaulting to c (non-editable; fires on page scope, not active-region gated). mod+n is offered only as a user-configurable alternate with a documented caveat: Ctrl/⌘+N is a browser "new window" accelerator and is not reliably interceptable (especially Chrome on Windows), so c is the working default. Each page with a Create/New control registers page.create (via a usePageCreateShortcut helper) wired to that page's create dialog; global.quickCreate has its own distinct default binding n (the shared c default caused a silent unresolved dispatch conflict) and opens the multi-type QuickCreateDialog; it is the create affordance on pages with no page.create registered and coexists with page.create (c) elsewhere. page.save (mod+s, preventDefault browser save) is registered by pages with a primary Save. Both are suppressed in editable targets and when a dialog/drawer owns scope.

Create-dialog keyboard usability (commitGroup dialog-a11y)

• FR32. Every page's create dialog is fully operable without a mouse: focus the first field on open and restore focus to the invoker on close; a focus trap; mod+Enter submit (textarea/BlockNote-safe); Escape cancel (Radix-integrated); all controls (selects, pickers, comboboxes, toggles) keyboard-reachable; correct role=dialog/aria-modal/aria-labelledby.

Command palette / Spotlight (commitGroup command-palette)

• FR33. A keyboard-driven command palette opened by mod+k (this resolves and supersedes the prior open decision — mod+k no longer just focuses the sidebar search; the palette's default free-text mode includes record search so existing behavior is preserved/enhanced; the asset palette stays rescoped to mod+shift+k). Results merge navigation destinations (menuConfig), runnable registered shortcut actions, and record search, ranked with recents/frequency. The query grammar follows the TeamCity search model (see Appendix). The parser is a pure, UI-decoupled, unit-tested module obeying the FR30 boundary. Fully accessible (combobox/listbox roles, aria-activedescendant, live result count), i18n in all 8 locales + pseudo, with in-palette syntax help linked from the global help dialog.

End-to-end customization wiring (commitGroup customization-wiring)

• FR34. The persistence/override layer must be functionally connected, not only unit-tested in isolation. The provider is the single source of preference state: MspLayoutClient injects the useUserPreference-backed ShortcutStorage; the provider loads PersistedShortcuts, dispatch resolves bindings via resolveActionBindings (override → platform default), merges the persisted disabled list, and exposes resolved bindings + mutators via context; display.tsx hints/aria-keyshortcuts and the settings panel all read from that one source. An integration test is required asserting: rebind in settings → the new combo dispatches, the old default stops, the settings "Effective" column, ShortcutHint, and aria-keyshortcuts all reflect it; disable stops dispatch and hides from help; reset live-updates. Unit/contract green on isolated pieces is not sufficient to mark FR19/FR20/FR23/FR26 or F043/F140 done.

Gap-analysis remediation (commitGroup gap-hardening)

These three requirements came out of a post-implementation review of the branch. They are distinct from FR34 (which covers only the persistence/dispatch wiring) and address structural issues that let the review-discovered bugs ship "green".

• FR35. Catalog is the single source of truth for action metadata. scope, priority, defaultBindings, labelKey, groupKey, sequence, and allowInEditable live only in catalog.ts. Registration sites build actions through a catalog-derived factory (e.g. createShortcutAction(id, handler, { enabled? }) / useCatalogShortcut) supplying only id + handler (+ optional runtime enabled); hand-authored metadata literals are removed from SearchPalette, DefaultLayout, both DrawerContext files, TicketNavigation, AssetDashboardClient, and useDesignerShortcuts. A guard (unit + the boundary script) fails when a registered/used action id is absent from the catalog or its scope/priority/sequence/bindings diverge from the catalog entry. This resolves the current divergence where useDesignerShortcuts hardcodes priority: 60 while every other site omits priority (runtime 0), contradicting catalog.ts DEFAULT_PRIORITY — so the priorities the settings UI/help show are not the priorities dispatch uses.

• FR36. Active-region gating is enforced, not nominal. DefaultLayout must not call useShortcutActiveRegion(true) unconditionally. An active region is registered only by genuine roving-focus list/selection containers (via a shared region wrapper/hook applied to the real list views). As a result selection.* actions (j/k/Enter) are inert on arbitrary non-editable focus anywhere in /msp and fire only when such a region is focused/active. Single-letter page actions (page.create c, global.quickCreate n) are not region-gated: they are page-wide affordances guarded by scope eligibility and editable-target suppression only, so they work on page load without first focusing the list (the earlier active-region requirement made c/n dead until the list was clicked into — rejected as a UX regression). This turns FR10 from documented intent into enforced behavior.

• FR37. Behavioral test coverage replaces source greps. The readFileSync + toContain *.contract.test.ts suites (global-migration, panels-drawers, editors, persistence-bridge, settings-ui, regression, i18n) are replaced/augmented with tests that assert observable dispatch/registration/resolution behavior rather than source-string presence; a thin source-presence smoke is kept only where the behavior genuinely cannot be simulated. A meta test-guard flags any new *.contract.test.ts that only greps source without a behavioral assertion, so "green CI" cannot again mean "the feature was never exercised".

Non-functional Requirements

• One global listener; O(registered actions) match per keydown; no measurable input latency.
• No SSR/hydration mismatch (platform + bindings resolved post-mount).
• packages/ui keeps the engine dependency-light; preference wiring lives in the MSP wrapper/user-composition layer.
• No regression to component-local widget key handling.
• Accessibility: screen readers announce shortcuts via aria-keyshortcuts.

Shortcuts UI redesign + Profile placement (commitGroup shortcuts-ui-redesign)

These requirements supersede the original list-Table settings panel (KeyboardShortcutsSettings.tsx, now deleted) with the design-handoff visual keyboard cheatsheet, and correct its placement so users can actually reach it. Sourced from ~/Downloads/design_handoff_keyboard_shortcuts/ (variation-c) and manual-test feedback that the prior tab never appeared in the sidebar.

• FR38. Placement: Profile, not Settings. The keyboard-shortcuts pane is a CustomTabs sub-tab under /msp/profile (UserProfile.tsx tabContent), matching the per-user-preference convention (Profile / Security / SSO / API Keys / Notifications). The old SettingsPage.tsx baseTabContent entry and KeyboardShortcutsSettings.tsx are removed. keyboard-shortcuts is added to BASE_PROFILE_TABS in packages/integrations/src/lib/calendarAvailability.ts so /msp/profile?tab=keyboard-shortcuts deep-links work. The Sidebar settings-mode menu is unaffected (the pane is not a Settings tab).

• FR39. Visual keyboard panel. KeyboardShortcutsPanel.tsx recreates the design handoff (variation-c) using product CSS variables and Radix primitives, driven by the real catalog + provider single source (no parallel data): full keyboard grid (KB_ROWS), layer toggle (Plain / ⌘ Mod / ⇧ Shift / ⌘⇧) with per-layer counts, category-tinted bound keys with conflict dots, hover/selection KeyDetail strip (action name + scope chip + Modified badge + description + BindingDisplay + Rebind/Cancel + Enabled switch + per-action Reset), right-rail chord list with search and Reset all to {profile} footer, real keydown capture wired through useKeyboardShortcutPreferences, Copy cheatsheet (print window), ConfirmationDialog for reset-all and the prompt-to-reassign conflict UX (the new binding takes over, the previous owner is left unbound), react-hot-toast + handleError parity, every interactive element has an id. Bindings whose key isn't on the keyboard (?, Escape, Delete, sequences) route to the chord rail rather than silently disappearing (improvement over the prototype).

• FR40. Profile presets in the engine single source. PersistedShortcuts gains profile: string (schema v2, with a v1→v2 migration that defaults to 'default' and preserves a valid stored profile). SHORTCUT_PROFILES ships default, vim, emacs with parser-valid neutral single-chord deltas keyed by real catalog ids — multi-chord Emacs sequences are deliberately not assigned to non-sequence actions (they would silently never dispatch). Resolution order is user override → active-profile delta → platform default, applied inside resolveActionBindings so dispatch, hints, ARIA, and the panel all read the same effective binding. setActionBindingsDelta drops an override equal to the profile baseline (not raw factory), so per-action reset returns to the active profile's baseline. The provider exposes profile + setProfile. Override scope stays per-account only (useUserPreference); the prototype's per-device split is intentionally deferred. Vim/Emacs delta maps are best-guess pending team confirmation.

Data / API / Integrations

• Persistence: engine exposes a ShortcutStorage adapter interface; the concrete adapter is useUserPreference-backed (packages/user-composition/src/hooks/useUserPreference.ts), key keyboard_shortcuts_v1, localStorage + debounced server sync, unauthenticated path supported. The adapter and its @alga-psa/user-composition import live in the MSP wrapper (server), injected into the provider — never imported into packages/ui. No new tables/endpoints (reuses existing user_preferences).
• Stored shape: { "version": 1, "bindings": { "<id>": ["<neutral-binding>"...] }, "disabled": ["<id>"...] } storing only deltas in neutral syntax (mod, logical tokens).
• i18n integration: useTranslation('msp/keyboard-shortcuts') (@alga-psa/ui/lib/i18n/client); locale files under server/public/locales/{lang}/msp/keyboard-shortcuts.json; namespace added to ROUTE_NAMESPACES in packages/core/src/lib/i18n/config.ts.
• Settings shell: server/src/components/settings/SettingsPage.tsx baseTabContent; product-tab allowlist (settingsProductTabs.ts) reviewed (no change expected for MSP-only).

Security / Permissions

• No new privileged operations. Shortcuts only invoke handlers the user can already trigger via UI; enabled honors existing gating (e.g. aiAssistantAvailable). Preference reads/writes are user-scoped via existing useUserPreference server actions.

Observability

• None beyond dev-time conflict reporting in the registry/settings UI (no new metrics/logging per scope philosophy).

Rollout / Migration

• Phased per source plan: P1 engine → P2 global → P3 panels/drawers/record → P4 editors → P5 customization → P6 discoverability/a11y.
• Each migrated handler is removed only after its action is registered and regression-verified, so behavior is preserved at every step.
• mod+k decision is settled (global search; asset palette rescoped) and is a hard prerequisite for P2 completion.
• Preference blob is versioned with a migration function for forward changes.

Open Questions

• Tenant-level defaults / admin lock (deferred; not in scope).
• Export/import of overrides (deferred).
• Whether client portal adopts the system later (deferred).
• Final default binding for assets.commandPalette after rescoping (implemented: mod+shift+k).
• (Resolved) mod+k = the command palette / Spotlight (FR33), not just sidebar search; record search lives inside the palette.
• $ magic-keyword set and the exact field-alias list are finalized during command-palette implementation (Appendix is the starting spec).

Acceptance Criteria (Definition of Done)

• All handlers from the inventory are registered through the shared system; one delegated capture listener; component-local widget handlers untouched.
• Matching correct on macOS and Windows/Linux incl. alt+letter, international layouts, mod resolution; respects event.defaultPrevented.
• Single-chord and g-sequence bindings work; sequence buffer times out/resets correctly and is suppressed in editable targets.
• Scope/priority/active-region prevent global/page/panel/dialog/editor conflicts; drawer wins over page; Escape integrates with Radix.
• mod+k conflict removed; asset palette rescoped and functional.
• packages/ui/src/keyboard-shortcuts has zero imports of @alga-psa/user-composition or feature packages; persistence flows through the injected ShortcutStorage adapter; npx nx graph shows no new cycle vs .github/known-cycles.json; the dependency-boundary guard passes.
• Existing AI/search/drawer/ticket/designer shortcuts preserved post-migration (regression + Playwright verified).
• User can rebind/clear/disable/reset; overrides persist as neutral deltas locally and sync to server; Mac→Windows cross-device resolves correctly with advisories for hostile combos.
• Settings UI is visually/structurally consistent with existing settings panels (shared components, variants, toast/error handling, ids, loading state).
• Help dialog lists active shortcuts resolved per device; aria-keyshortcuts and visible kbd hints present on instrumented controls.
• All user-facing strings internationalized in 8 locales + pseudo; validate-translations.cjs passes; namespace preloads via ROUTE_NAMESPACES.
• No SSR/hydration mismatch.
• page.create (c) opens the current page's create dialog on every page with a Create control; page.save (mod+s) saves on pages with a Save; both suppressed while typing / when a dialog owns scope.
• Every page's create dialog is completable end-to-end with the keyboard only.
• mod+k opens the command palette; field-scoped syntax + operators per the Appendix work; results span nav + actions + records; fully keyboard/SR accessible; palette module passes the FR30 dependency-boundary guard.
• Customization is wired end-to-end: a rebind/disable/reset made in settings immediately changes what the dispatcher fires and what hints/aria show, from a single provider-owned source; the FR34 integration test passes.

Appendix: Command Palette Syntax (TeamCity-derived)

Adapted from JetBrains TeamCity search (https://www.jetbrains.com/help/teamcity/search.html).

• Field-scoped: field:value with short aliases. Initial registry: ticket:/t:, client:/c:, contact:, project:/p:, asset:/a:, user:/u: (and @name), nav: (and /path), action: (and >cmd). Record-id sigil #1234. Final alias list confirmed in implementation.
• Operators: double-quoted phrases (status:"in progress"); - / NOT exclusion; * and ? wildcards (no leading *); fuzzy term~; prefix-match by default; OR is the default between unscoped terms; AND only within the same field scope (tag:a AND tag:b).
• Magic keywords: $-prefixed, abbreviable to first syllable ($mine/$m, $recent/$rec, $open) — mirrors TeamCity $pinned/$p.
• Sigils (leading): > run action/command, # open by record id, @ people, / navigation.
• No field given: free-text fuzzy/prefix across nav + actions + records, ranked with recents/frequency.