@mediadatafusion/pi-workflow-suite 0.0.19 → 0.0.20

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable public releases will be documented in this file.
 
+## [0.0.20] - 2026-06-12
+
+### Improved
+
+- Added platform-aware Workflow Suite shortcuts so macOS keeps the existing `Ctrl+Shift` shortcuts while Windows and Linux use function-key shortcuts for Standard, Plan, Mission, widget, and preset controls.
+- Updated inline shortcut hints, widget documentation, and package README output so Windows and Linux users see shortcuts that match the active platform profile.
+
+### Hardened
+
+- Added regression coverage that keeps shortcut registration, inline hints, README examples, and fallback commands aligned with the centralized shortcut registry.
+
 ## [0.0.19] - 2026-06-10
 
 ### Improved

package/README.md

@@ -4,7 +4,7 @@
 
 [![Install](https://cdn.jsdelivr.net/npm/@mediadatafusion/pi-workflow-suite@0.0.12/docs/assets/readme-link-install.svg)](#installation) [![Quick Start](https://cdn.jsdelivr.net/npm/@mediadatafusion/pi-workflow-suite@0.0.12/docs/assets/readme-link-quick-start.svg)](#quick-start) [![Commands](https://cdn.jsdelivr.net/npm/@mediadatafusion/pi-workflow-suite@0.0.12/docs/assets/readme-link-commands.svg)](#core-commands) [![Settings](https://cdn.jsdelivr.net/npm/@mediadatafusion/pi-workflow-suite@0.0.12/docs/assets/readme-link-settings.svg)](#settings-reference)
 
-**Workflow Suite Version:** `v0.0.19`
+**Workflow Suite Version:** `v0.0.20`
 
 ## Overview
 
@@ -123,7 +123,7 @@ Pi Workflow Suite turns Pi into a guided workflow environment:
 | Token Budgets | Optional per-mode token and runtime caps (`maxTokens`, `maxRuntimeHours`) for Plan, Mission, and Standard Mode. Off by default (unlimited). When enabled, Workflow Suite tracks cumulative usage and blocks further agent turns when the budget is exceeded. |
 | Workflow Roles | Planner, Executor, Reviewer, Validator, Mission, and compaction responsibilities are separated by phase so each job has clear boundaries and can be matched to the right model. |
 | Model Selection | Configure which provider/model and thinking level powers each workflow role, with shared defaults plus Standard-specific and Mission-specific overrides for simpler or higher-rigor setups. |
-| Presets | Built-in and custom workflow profiles with selector commands and Ctrl+Shift+U cycling while active modes are running. |
+| Presets | Built-in and custom workflow profiles with selector commands and platform-aware cycling shortcuts while active modes are running: macOS `Ctrl+Shift+U`, Windows/Linux `F4`. |
 | Settings | Interactive grouped settings UI plus direct commands for Standard, Plan, Mission, model selection, sub-agents, widgets, compaction, themes, and safety. |
 | Sub-agents And Skills | Bundled workflow agents and skills for discovery, planning, safe execution, validation, git-safe summaries, and project-rule audits, with clear capability boundaries. |
 | Widgets And Status | Mode-aware top/bottom widgets, editor hints, shortcut controls, progress display, runtime summaries, and current-setting visibility. |
@@ -132,9 +132,9 @@ Pi Workflow Suite turns Pi into a guided workflow environment:
 ## Feature Overview
 
 - Idle Mode as the default management state when no Standard, Plan, or Mission workflow is active.
-- Standard Mode through `/standard` and `Ctrl+Shift+S` for direct active work with optional dynamic To Do tracking.
-- Plan Mode through `/p` and `/plan` for approval-gated planned execution.
-- Mission Mode through `/mission`, `/m`, and `Ctrl+Shift+M` for durable milestone workflows.
+- Standard Mode through `/standard` and the platform shortcut: macOS `Ctrl+Shift+S`, Windows/Linux `F6`.
+- Plan Mode through `/p`, `/plan`, and the platform shortcut: macOS `Ctrl+Shift+L`, Windows/Linux `F7`.
+- Mission Mode through `/mission`, `/m`, and the platform shortcut: macOS `Ctrl+Shift+M`, Windows/Linux `F8`.
 - Configurable clarification in Standard Mode, plus dynamic clarification in Plan Mode and Mission Mode.
 - Review, execution, validation, repair, retry, checkpoint, and final-validation controls where the selected mode supports them.
 - Plan history, mission checkpoint history, Standard runtime tracking, and Mission runtime tracking.
@@ -214,7 +214,7 @@ Configurable clarification:
 
 Core behavior:
 
-- `/standard` or `Ctrl+Shift+S` enters Standard Mode.
+- `/standard` enters Standard Mode. The platform shortcut is macOS `Ctrl+Shift+S`, Windows/Linux `F6`.
 - `/standard <task>` enters Standard Mode and starts that task.
 - `/standard status` shows active Standard settings, latest auto-check decisions, and To Do progress.
 - `/standard todo` shows dynamic To Do tracking.
@@ -598,7 +598,8 @@ Quick access:
 
 ```text
 /workflow presets              # open preset selector
-Ctrl+Shift+U                   # cycle presets while Standard/Plan/Mission Mode is active
+macOS: Ctrl+Shift+U            # cycle presets while Standard/Plan/Mission Mode is active
+Windows/Linux: F4              # cycle presets while Standard/Plan/Mission Mode is active
 /workflow presets list
 /workflow presets apply <name>
 /workflow presets next
@@ -610,7 +611,9 @@ Ctrl+Shift+U                   # cycle presets while Standard/Plan/Mission Mode
 /workflow presets delete <name>
 ```
 
-The inline editor hints stay mode-specific and avoid idle clutter. By default, active workflows display compact, human-readable shortcuts and the other workflow mode:
+The inline editor hints stay mode-specific and avoid idle clutter. By default, active workflows display compact, human-readable shortcuts for the active platform.
+
+macOS examples:
 
 ```text
 Idle:     Standard:Ctrl+Shift+S Plan:Ctrl+Shift+L Mission:Ctrl+Shift+M
@@ -619,7 +622,16 @@ Standard: Widgets:Ctrl+Shift+T/B Preset:deep Ctrl+Shift+U Plan:Ctrl+Shift+L Miss
 Mission:  Widgets:Ctrl+Shift+T/B Preset:deep Ctrl+Shift+U Standard:Ctrl+Shift+S Plan:Ctrl+Shift+L
 ```
 
-Cross-switching is enabled by default (`Ctrl+Shift+S` toggles Standard Mode, `Ctrl+Shift+M` from Plan Mode enters Mission Mode, and `Ctrl+Shift+L` from Mission Mode enters Plan Mode).
+Windows and Linux examples:
+
+```text
+Idle:     Standard:F6 Plan:F7 Mission:F8
+Plan:     Widgets:F2/F3 Preset:deep F4 Standard:F6 Mission:F8
+Standard: Widgets:F2/F3 Preset:deep F4 Plan:F7 Mission:F8
+Mission:  Widgets:F2/F3 Preset:deep F4 Standard:F6 Plan:F7
+```
+
+Cross-switching is enabled by default. On macOS, `Ctrl+Shift+S` toggles Standard Mode, `Ctrl+Shift+M` from Plan Mode enters Mission Mode, and `Ctrl+Shift+L` from Mission Mode enters Plan Mode. On Windows and Linux, the matching shortcuts are `F6`, `F8`, and `F7`.
 
 Human-friendly names are normalized for command use. For example, creating `Joe simple preset` saves it as `joe-simple-preset`, then lists the exact command to apply it. Custom presets can include Standard Mode To Do/clarification settings as well as shared Plan, Mission, sub-agent, workflow, and UI settings.
 
@@ -650,13 +662,18 @@ Depending on the active mode and settings, widgets can show:
 - active preset and shortcut hints,
 - sub-agent activity when worker orchestration is active.
 
-Widget shortcuts:
+Workflow shortcuts are platform-aware. The macOS shortcuts preserve the original Workflow Suite behavior. Windows and Linux use function-key shortcuts because common terminal hosts may not reliably deliver `Ctrl+Shift+letter` chords to Pi.
 
-```text
-Ctrl+Shift+T  toggle the active workflow top widget
-Ctrl+Shift+B  toggle the active workflow bottom widget
-Ctrl+Shift+U  cycle workflow presets while Standard, Plan, or Mission Mode is active
-```
+| Action | macOS | Windows | Linux / WSL | Fallback command |
+|---|---:|---:|---:|---|
+| Toggle Standard Mode | `Ctrl+Shift+S` | `F6` | `F6` | `/standard` |
+| Enter Plan Mode | `Ctrl+Shift+L` | `F7` | `F7` | `/plan` |
+| Toggle Mission Mode | `Ctrl+Shift+M` | `F8` | `F8` | `/mission` |
+| Toggle active workflow top widget | `Ctrl+Shift+T` | `F2` | `F2` | `/workflow widgets toggle top` |
+| Toggle active workflow bottom widget | `Ctrl+Shift+B` | `F3` | `F3` | `/workflow widgets toggle bottom` |
+| Cycle workflow presets while Standard, Plan, or Mission Mode is active | `Ctrl+Shift+U` | `F4` | `F4` | `/workflow presets next` |
+
+The inline editor hints use the active platform profile. A Windows or Linux user should not see macOS-only `Ctrl+Shift+letter` hints for Workflow Suite actions.
 
 Widget commands:
 
@@ -1038,8 +1055,8 @@ pi install -l npm:@mediadatafusion/pi-workflow-suite
 ### Installing specific versions
 
 ```bash
-pi install npm:@mediadatafusion/pi-workflow-suite@0.0.19
-pi install -l npm:@mediadatafusion/pi-workflow-suite@0.0.19
+pi install npm:@mediadatafusion/pi-workflow-suite@0.0.20
+pi install -l npm:@mediadatafusion/pi-workflow-suite@0.0.20
 ```
 
 An unversioned install follows normal update behavior: `pi update` and `pi update --extensions` will pick up new package releases. A versioned install pins the package to that version. Pinned package specs are intentionally skipped by Pi's normal package update commands. To move a pinned install to a newer version, reinstall with the desired version. To switch back to latest tracking, use the unversioned install command without `@<version>`.
@@ -1245,10 +1262,10 @@ See `docs/TROUBLESHOOTING.md` for detailed diagnostics.
 
 ## Versioning
 
-The current preparation version is `v0.0.19`. Version information is intentionally aligned across:
+The current preparation version is `v0.0.20`. Version information is intentionally aligned across:
 
-- `VERSION` (`v0.0.19`),
-- `package.json` (`0.0.19`),
+- `VERSION` (`v0.0.20`),
+- `package.json` (`0.0.20`),
 - `package-lock.json`,
 - this README,
 - Workflow Suite settings/about output.

package/VERSION

@@ -1 +1 @@
-v0.0.19
+v0.0.20

package/extensions/workflow-model-router.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getAgentDir, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { workflowPresetCycleShortcutLabel } from "./workflow-shortcuts.js";
 
 export type WorkflowRole = "planner" | "executor" | "validator" | "reviewer";
 export type MissionModelRole = WorkflowRole;
@@ -1224,7 +1225,7 @@ export function renderWorkflowPresets(settings: WorkflowSettings = loadGlobalSet
   const active = settings.presets?.activePreset ?? WORKFLOW_CUSTOM_PRESET_MARKER;
   const names = workflowPresetNames(settings);
   const cards = [renderWorkflowPresetCard(WORKFLOW_CUSTOM_PRESET_MARKER, undefined, active === WORKFLOW_CUSTOM_PRESET_MARKER), ...names.map((name) => renderWorkflowPresetCard(name, catalog[name], name === active))];
-  return `# Workflow Presets\n\nActive Preset: ${activeWorkflowPresetLabel(settings)}\nShortcut: Ctrl+Shift+U cycles saved presets while Plan/Mission/Standard Mode is active\nSelector: /workflow presets\n\n${cards.join("\n\n") || "No presets available."}\n\nQuick commands:\n- /workflow presets list\n- /workflow presets apply <name>\n- /workflow presets next\n- /workflow presets prev\n- /workflow presets save <name>\n- /workflow presets create <name> from simple|standard|deep|maximum\n- /workflow presets edit <name>\n- /workflow presets rename <old> to <new>\n- /workflow presets delete <name>\n\nBuilt-in presets are package-defined and sync with the extension. User-named custom presets are saved entries in workflow-settings.json and stay in hotkey cycling. The reserved custom marker only means no built-in or user-named preset is active. Extension updates preserve workflow-settings.json and do not overwrite custom presets. Presets adjust workflow behavior only and preserve model/provider choices, API keys, auth/session files, runtime workflow state, and shared compaction settings.`;
+  return `# Workflow Presets\n\nActive Preset: ${activeWorkflowPresetLabel(settings)}\nShortcut: ${workflowPresetCycleShortcutLabel()} cycles saved presets while Plan/Mission/Standard Mode is active\nSelector: /workflow presets\n\n${cards.join("\n\n") || "No presets available."}\n\nQuick commands:\n- /workflow presets list\n- /workflow presets apply <name>\n- /workflow presets next\n- /workflow presets prev\n- /workflow presets save <name>\n- /workflow presets create <name> from simple|standard|deep|maximum\n- /workflow presets edit <name>\n- /workflow presets rename <old> to <new>\n- /workflow presets delete <name>\n\nBuilt-in presets are package-defined and sync with the extension. User-named custom presets are saved entries in workflow-settings.json and stay in hotkey cycling. The reserved custom marker only means no built-in or user-named preset is active. Extension updates preserve workflow-settings.json and do not overwrite custom presets. Presets adjust workflow behavior only and preserve model/provider choices, API keys, auth/session files, runtime workflow state, and shared compaction settings.`;
 }
 
 export function applyWorkflowPreset(cwd: string, requestedScope: WorkflowSettingsScope | undefined, name: string): SettingsWriteResult {

package/extensions/workflow-modes.ts

@@ -13,6 +13,7 @@ import { renderHandoffProjectContext, renderWorkflowStatus, renderWorkflowSummar
 import { BASE_EXECUTE_TOOLS, EXECUTE_TOOLS, PLAN_TOOLS, REVIEW_TOOLS, WORKFLOW_DIAGRAM_TOOL, WORKFLOW_PLAN_RESULT_TOOL, WORKFLOW_REVIEW_RESULT_TOOL, WORKFLOW_EXECUTION_RESULT_TOOL, WORKFLOW_VALIDATION_RESULT_TOOL, WORKFLOW_REPAIR_RESULT_TOOL, WORKFLOW_PROGRESS_TOOL, MISSION_PLAN_RESULT_TOOL, MISSION_MILESTONE_RESULT_TOOL, STANDARD_HANDOFF_RESULT_TOOL, isBlockedExecuteCommand, registerToolGuard, standardSafeReadOnlyBash, VALIDATOR_TOOLS } from "./workflow-tool-guard.js";
 import { refreshRuntimeWebTools, registerWorkflowWebTools, runtimeWebResearchGuidance, webSafePlanTools, withRuntimeWebTools } from "./workflow-web-tools.js";
 import { addMissionCheckpoint, applyPlanRuntimeAccounting, applyStandardRuntimeAccounting, clearOldMissionStates, clearOldWorkflowPlans, compact, createMissionState, createStandardRuntimeId, createWorkflowPlanId, emptyState, extractVerdict, isMissionRuntimeActiveStatus, isPlanRuntimeActiveMode, listMissionStates, listWorkflowPlans, loadMissionState, loadState, loadWorkflowPlan, missionActiveRuntimeMs, missionRuntimeCounterState, missionWallClockAgeMs, planActiveRuntimeMs, planRuntimeCounterState, planWallClockAgeMs, saveMissionState, saveState, saveWorkflowPlan, standardActiveRuntimeMs, standardRuntimeCounterState, standardWallClockAgeMs, PLAN_HISTORY_DIR, MISSION_HISTORY_DIR, type ClarificationAnswer, type ClarificationQuestion, type MissionAutonomy, type MissionMilestone, type MissionState, type PlanProgressState, type PlanStepStatus, type PlanValidationStatus, type SavedWorkflowPlan, type StandardTodoItemStatus, type StandardTodoState, type WorkflowState, type WorkflowTypedHandoffType } from "./workflow-state.js";
+import { WORKFLOW_SHORTCUTS, workflowEntryShortcutLabel as workflowRegistryEntryShortcutLabel, workflowPresetCycleShortcutLabel, workflowSettingsShortcutLines, workflowShortcutKey, workflowWidgetShortcutLabel, type WorkflowShortcutActionId } from "./workflow-shortcuts.js";
 import { cleanupOrphanProcesses, clearSubagentResultCache, runWorkflowSubagents, workflowSubagentResultOutput, type WorkflowSubagentResult, type WorkflowSubagentTask } from "./subagent/runner.js";
 import { parseScope, parseBool, parsePlanningDepth, parseClarificationMode, parseStandardTodoTriggerMode, parseStandardClarificationMode, parseStandardModelRole, parseWorkflowAgentScope, parseClarificationTiming, parseSubagentPolicy, parseSubagentPlanningPolicy, parseEditConcurrencyMode, parsePlanningOrchestrationPolicy, parseCompactionMode, parseWorkflowCompactionCheckMode, parseMissionAutonomy, parseValidationRetryMode, parsePositiveInt, updatedMessage, parseClarifyingQuestions, parseShorthandAnswers, formatAnswersForPlanner, planValidationStatusForVerdict } from "./workflow-parsers.js";
 import { classifyValidationFailure, normalizeValidationVerdict, validationReportHasRepairableIssue } from "./workflow-validation-classifier.js";
@@ -2561,13 +2562,13 @@ Themes:
 - /workflow-settings theme brand base minimal|workflow_duo|mission_control|diagnostic_center|data_stream|neural_grid
 
 Workflow entry shortcuts:
-- Ctrl+Shift+S toggles Standard Mode
-- Ctrl+Shift+L enters Plan Mode
-- Ctrl+Shift+M enters Mission Mode
-- In the opposite active mode, Ctrl+Shift+L/M switches directly to that mode
+- ${workflowEntryShortcutLabel("standard").replace(/^Standard:/, "")} toggles Standard Mode
+- ${workflowEntryShortcutLabel("plan").replace(/^Plan:/, "")} enters Plan Mode
+- ${workflowEntryShortcutLabel("mission").replace(/^Mission:/, "")} enters Mission Mode
+- In the opposite active mode, ${workflowEntryShortcutLabel("plan").replace(/^Plan:/, "")}/${workflowEntryShortcutLabel("mission").replace(/^Mission:/, "")} switches directly to that mode
 
 Presets:
-- Ctrl+Shift+U cycles workflow presets from the active Plan/Mission/Standard footer/status line
+- ${workflowPresetCycleShortcutLabel()} cycles workflow presets from the active Plan/Mission/Standard footer/status line
 - /workflow presets opens the preset selector
 - /workflow presets list
 - /workflow presets apply <name>
@@ -3708,11 +3709,7 @@ Startup On Session Start: ${settings.ui.startupVisualOnSessionStart === true ? "
 Custom Brand: ${settings.ui.customBrandEnabled === true ? "enabled" : "disabled"}
 Custom Brand Text: ${sanitizeCustomBrandText(settings.ui.customBrandText) || "(empty)"}
 Custom Brand Base Template: ${customBrandBaseVisualOrDefault(settings)}
-Standard Shortcut: Ctrl+Shift+S toggles Standard Mode
-Plan Shortcut: Ctrl+Shift+L enters Plan Mode
-Mission Shortcut: Ctrl+Shift+M enters Mission Mode
-Widget Shortcuts: Ctrl+Shift+T/B while Plan/Mission/Standard Mode is active
-Preset Cycle Shortcut: Ctrl+Shift+U while Plan/Mission/Standard Mode is active
+${workflowSettingsShortcutLines().join("\n")}
 Footer Line: idle displays Plan/Mission entry hints only; active workflows display compact widget/preset hints and workflow switch hints by default
 Fallback Commands: /workflow widgets status, /workflow presets, /standard, /plan, /mission
 
@@ -5032,15 +5029,10 @@ function planProgressWidget(state: WorkflowState, settings: ReturnType<typeof lo
   return lines;
 }
 
-const STANDARD_MODE_SHORTCUT = "Ctrl+Shift+S";
-const PLAN_MODE_SHORTCUT = "Ctrl+Shift+L";
-const MISSION_MODE_SHORTCUT = "Ctrl+Shift+M";
-
 type WorkflowEntryMode = "standard" | "plan" | "mission";
 
 function workflowEntryShortcutLabel(mode: WorkflowEntryMode): string {
-  if (mode === "standard") return `Standard:${STANDARD_MODE_SHORTCUT}`;
-  return mode === "plan" ? `Plan:${PLAN_MODE_SHORTCUT}` : `Mission:${MISSION_MODE_SHORTCUT}`;
+  return workflowRegistryEntryShortcutLabel(mode);
 }
 
 function workflowFooterShortcutsEnabled(): boolean {
@@ -5053,10 +5045,10 @@ function workflowActiveShortcutSummary(mode: WorkflowEntryMode, state: WorkflowS
   const parts: string[] = [];
   if (shortcuts && ui.showWidgetShortcutHint !== false) {
     const bottomRelevant = mode === "plan" ? planBottomRelevant(state) : mode === "mission" ? missionBottomRelevant(state, activeMissionForUi(state)) : Boolean(state.standardTodo?.items.length);
-    parts.push(bottomRelevant ? "Widgets:Ctrl+Shift+T/B" : "Widget:Ctrl+Shift+T");
+    parts.push(workflowWidgetShortcutLabel(bottomRelevant));
   }
   if (ui.showPresetShortcutHint !== false) {
-    parts.push(`Preset:${activeWorkflowPresetLabel(settings)}${shortcuts ? " Ctrl+Shift+U" : ""}`);
+    parts.push(`Preset:${activeWorkflowPresetLabel(settings)}${shortcuts ? ` ${workflowPresetCycleShortcutLabel()}` : ""}`);
   }
   if (ui.showActiveWorkflowSwitchHint !== false) {
     const switchHints = (["standard", "plan", "mission"] as WorkflowEntryMode[])
@@ -5416,7 +5408,7 @@ function renderWorkflowThemePreview(settings: ReturnType<typeof loadWorkflowSett
 }
 
 function renderWorkflowFooterThemePreview(settings: ReturnType<typeof loadWorkflowSettings>): string {
-  const suffix = ` ${workflowShortcutStatusText(settings, "Widgets:Ctrl+Shift+T/B Preset:simple Mission:Ctrl+Shift+M")}`;
+  const suffix = ` ${workflowShortcutStatusText(settings, `${workflowWidgetShortcutLabel(true)} Preset:simple ${workflowPresetCycleShortcutLabel()} ${workflowEntryShortcutLabel("mission")}`)}`;
   return [
     `${workflowWidgetRgb(settings, "title", "workflow:")}${workflowWidgetRgb(settings, "emphasis", "planning")}${suffix}`,
     `${workflowWidgetRgb(settings, "title", "workflow:")}${workflowWidgetRgb(settings, "progress", "executing")}${suffix}`,
@@ -7179,7 +7171,7 @@ function renderSavedPlan(plan: SavedWorkflowPlan): string {
 }
 
 function missionHelp(): string {
-  return `# Mission Mode Help\n\nMission Mode is a persistent milestone workflow for longer-running work. It runs alongside Plan Mode and does not replace /p.\n\nCommands:\n- /mission enters Mission Mode and waits for a goal\n- /mission help\n- /mission start <goal>\n- /mission <goal>\n- /mission clarify\n- /mission clarify answer 1A 2C\n- /mission clarify skip 1\n- /mission plan\n- /mission review\n- /mission approve\n- /mission run\n- /mission continue\n- /mission next\n- /mission pause\n- /mission resume\n- /mission retry\n- /mission repair\n- /mission revalidate\n- /mission set autonomy manual|approval_gated|supervised_auto|full_auto\n- /mission sync-settings\n- /mission status\n- /mission checkpoints\n- /mission stop\n- /mission list\n- /mission latest\n- /mission cleanup [limit]\n\nShortcuts:\n- Ctrl+Shift+M enters Mission Mode\n- Ctrl+Shift+L switches from Mission Mode to Plan Mode\n\nSafety:\n- Mission plans require approval before /mission run.\n- full_auto never runs unless missions.allowFullAuto=true.\n- Destructive actions, push, deploy, database mutation, and secret edits require explicit approval.\n- Mission run uses executor, validator/final-validator, safety, sub-agent, and repair gates and records stop or block reasons.\n- Validation failures attempt safe repair/revalidation within configured retry limits, then block for approval if limits or safety gates are hit.`;
+  return `# Mission Mode Help\n\nMission Mode is a persistent milestone workflow for longer-running work. It runs alongside Plan Mode and does not replace /p.\n\nCommands:\n- /mission enters Mission Mode and waits for a goal\n- /mission help\n- /mission start <goal>\n- /mission <goal>\n- /mission clarify\n- /mission clarify answer 1A 2C\n- /mission clarify skip 1\n- /mission plan\n- /mission review\n- /mission approve\n- /mission run\n- /mission continue\n- /mission next\n- /mission pause\n- /mission resume\n- /mission retry\n- /mission repair\n- /mission revalidate\n- /mission set autonomy manual|approval_gated|supervised_auto|full_auto\n- /mission sync-settings\n- /mission status\n- /mission checkpoints\n- /mission stop\n- /mission list\n- /mission latest\n- /mission cleanup [limit]\n\nShortcuts:\n- ${workflowEntryShortcutLabel("mission").replace(/^Mission:/, "")} enters Mission Mode\n- ${workflowEntryShortcutLabel("plan").replace(/^Plan:/, "")} switches from Mission Mode to Plan Mode\n\nSafety:\n- Mission plans require approval before /mission run.\n- full_auto never runs unless missions.allowFullAuto=true.\n- Destructive actions, push, deploy, database mutation, and secret edits require explicit approval.\n- Mission run uses executor, validator/final-validator, safety, sub-agent, and repair gates and records stop or block reasons.\n- Validation failures attempt safe repair/revalidation within configured retry limits, then block for approval if limits or safety gates are hit.`;
 }
 
 function promptCandidateFiles(name: string): string[] {
@@ -9803,7 +9795,7 @@ export default function workflowModes(pi: ExtensionAPI): void {
     if (isStandardWorkflowMode(state)) {
       return `# Workflow Widgets\n\nStandard Top Widget: ${widgetVisibilityLabel(settings, "standardTop")}\nStandard To Do Widget: ${widgetVisibilityLabel(settings, "standardBottom")}\nStatus Line: ${widgetVisibilityStatus(state, settings) ?? "none"}\n${common}`;
     }
-    return `# Workflow Widgets\n\nNo active Plan/Mission/Standard widget is currently visible.\nStatus Line: ${widgetVisibilityStatus(state, settings) ?? "none"}\n\nEntry Shortcuts:\n- ${workflowEntryShortcutLabel("standard")}\n- ${workflowEntryShortcutLabel("plan")}\n- ${workflowEntryShortcutLabel("mission")}\n\nActive-mode editor hints use compact text such as: Widgets:Ctrl+Shift+T/B Preset:${activeWorkflowPresetLabel(settings)} Ctrl+Shift+U Standard:Ctrl+Shift+S Mission:Ctrl+Shift+M\nWidget toggles and preset cycling are visible only while Plan/Mission/Standard Mode is active.\n\n${common}`;
+    return `# Workflow Widgets\n\nNo active Plan/Mission/Standard widget is currently visible.\nStatus Line: ${widgetVisibilityStatus(state, settings) ?? "none"}\n\nEntry Shortcuts:\n- ${workflowEntryShortcutLabel("standard")}\n- ${workflowEntryShortcutLabel("plan")}\n- ${workflowEntryShortcutLabel("mission")}\n\nActive-mode editor hints use compact text such as: ${workflowWidgetShortcutLabel(true)} Preset:${activeWorkflowPresetLabel(settings)} ${workflowPresetCycleShortcutLabel()} ${workflowEntryShortcutLabel("standard")} ${workflowEntryShortcutLabel("mission")}\nWidget toggles and preset cycling are visible only while Plan/Mission/Standard Mode is active.\n\n${common}`;
   };
 
   const renderEditorHintsSettings = (ctx: ExtensionContext): string => {
@@ -15729,11 +15721,11 @@ ${renderMissionStatus(activeMission ?? paused)}`);
   }
 
   function presetUsage(): string {
-    return "# Workflow Presets\n\nQuick use:\n- /workflow presets opens the selector\n- Ctrl+Shift+U cycles saved presets from the footer only while Plan/Mission/Standard Mode is active\n- /workflow presets list\n- /workflow presets apply <name>\n- /workflow presets next\n- /workflow presets prev\n- /workflow presets save <name>\n- /workflow presets create <name> from simple|standard|deep|maximum\n- /workflow presets edit <name>\n- /workflow presets rename <old> to <new>\n- /workflow presets delete <name>";
+    return `# Workflow Presets\n\nQuick use:\n- /workflow presets opens the selector\n- ${workflowPresetCycleShortcutLabel()} cycles saved presets from the footer only while Plan/Mission/Standard Mode is active\n- /workflow presets list\n- /workflow presets apply <name>\n- /workflow presets next\n- /workflow presets prev\n- /workflow presets save <name>\n- /workflow presets create <name> from simple|standard|deep|maximum\n- /workflow presets edit <name>\n- /workflow presets rename <old> to <new>\n- /workflow presets delete <name>`;
   }
 
   function presetActionMessage(title: string, name: string, resultFile?: string, scope?: string): string {
-    return `# ${title}\n\nPreset: ${name}\n${scope ? `Scope: ${scope}\n` : ""}${resultFile ? `File: ${resultFile}\n` : ""}\nScope note: presets apply across Standard Mode, Plan Mode, Mission Mode, shared sub-agents, and selected UI settings.\nUse selector: /workflow presets\nCycle saved presets: Ctrl+Shift+U while Plan/Mission/Standard Mode is active\nFooter: idle displays Plan/Mission entry shortcuts only; active workflows display compact widget/preset hints and workflow switch hints by default.\n\nModel/provider choices and shared compaction settings are preserved.`;
+    return `# ${title}\n\nPreset: ${name}\n${scope ? `Scope: ${scope}\n` : ""}${resultFile ? `File: ${resultFile}\n` : ""}\nScope note: presets apply across Standard Mode, Plan Mode, Mission Mode, shared sub-agents, and selected UI settings.\nUse selector: /workflow presets\nCycle saved presets: ${workflowPresetCycleShortcutLabel()} while Plan/Mission/Standard Mode is active\nFooter: idle displays Plan/Mission entry shortcuts only; active workflows display compact widget/preset hints and workflow switch hints by default.\n\nModel/provider choices and shared compaction settings are preserved.`;
   }
 
   function parsePresetCreate(rest: string): { name: string; template?: string } {
@@ -15761,7 +15753,7 @@ ${renderMissionStatus(activeMission ?? paused)}`);
     const { names, options } = presetDisplayOptions(settings);
     if (!ctx.hasUI) return show(pi, renderWorkflowPresets(settings));
     if (names.length === 0) return show(pi, "# Workflow Presets\n\nNo presets available.");
-    const choice = await ctx.ui.select(`Workflow Presets — active: ${activeWorkflowPresetLabel(settings)} — Ctrl+Shift+U cycles during Plan/Mission`, options);
+    const choice = await ctx.ui.select(`Workflow Presets — active: ${activeWorkflowPresetLabel(settings)} — ${workflowPresetCycleShortcutLabel()} cycles during Plan/Mission`, options);
     if (!choice) return;
     const selected = names[options.indexOf(choice)];
     if (!selected) return;
@@ -15890,7 +15882,7 @@ ${renderMissionStatus(activeMission ?? paused)}`);
         const r = createWorkflowPreset(ctx.cwd, undefined, parsed.name, parsed.template);
         setWorkflowUi(ctx, state, activeSubagents);
         const safe = normalizeWorkflowPresetName(parsed.name);
-        return show(pi, `# Workflow Preset Created\n\nPreset: ${parsed.name}\nSaved As: ${safe}\n${parsed.template ? `Template: ${parsed.template}\n` : ""}Scope: ${r.scope}\nFile: ${r.file}\n\nThe preset was saved but not applied.\nScope note: presets apply across Standard Mode, Plan Mode, Mission Mode, shared sub-agents, and selected UI settings.\nApply now: /workflow presets apply ${safe}\nOpen selector: /workflow presets\nCycle saved presets: Ctrl+Shift+U while Plan/Mission/Standard Mode is active`);
+        return show(pi, `# Workflow Preset Created\n\nPreset: ${parsed.name}\nSaved As: ${safe}\n${parsed.template ? `Template: ${parsed.template}\n` : ""}Scope: ${r.scope}\nFile: ${r.file}\n\nThe preset was saved but not applied.\nScope note: presets apply across Standard Mode, Plan Mode, Mission Mode, shared sub-agents, and selected UI settings.\nApply now: /workflow presets apply ${safe}\nOpen selector: /workflow presets\nCycle saved presets: ${workflowPresetCycleShortcutLabel()} while Plan/Mission/Standard Mode is active`);
       }
       if (action === "configure" || action === "edit") {
         if (!rest) return show(pi, "# Workflow Presets\n\nUsage: /workflow presets edit <name>");
@@ -16791,48 +16783,55 @@ Pi Version: v${VERSION}
   pi.registerCommand("m retry", { description: "Retry validation repair flow for current mission.", handler: async (_args, ctx) => handleMissionCommand("retry", ctx) });
   pi.registerCommand("m revalidate", { description: "Revalidate current mission milestone.", handler: async (_args, ctx) => handleMissionCommand("revalidate", ctx) });
 
+  const workflowShortcutHandlers: Record<WorkflowShortcutActionId, (ctx: ExtensionContext) => Promise<void> | void> = {
+    "workflow.widget.top.toggle": async (ctx) => {
+      if (workflowWidgetUi(loadGlobalSettings()).enableWidgetShortcuts === false) { workflowEditorHintText = workflowEditorHintTextFor(state, loadWorkflowSettings(ctx.cwd), "Top:disabled"); return; }
+      const slot = activeTopWidgetSlot();
+      if (!slot) { workflowEditorHintText = workflowEditorHintTextFor(state, loadWorkflowSettings(ctx.cwd)); return; }
+      toggleWorkflowWidget(ctx, slot);
+      setWorkflowWidgetShortcutStatus(ctx, slot);
+    },
+    "workflow.widget.bottom.toggle": async (ctx) => {
+      if (workflowWidgetUi(loadGlobalSettings()).enableWidgetShortcuts === false) { workflowEditorHintText = workflowEditorHintTextFor(state, loadWorkflowSettings(ctx.cwd), "Bottom:disabled"); return; }
+      if (isPlanWorkflowUiMode(state) && planBottomRelevant(state)) {
+        toggleWorkflowWidget(ctx, "planBottom");
+        return setWorkflowWidgetShortcutStatus(ctx, "planBottom");
+      }
+      if (isMissionWorkflowMode(state) && missionBottomRelevant(state, activeMissionForUi(state))) {
+        toggleWorkflowWidget(ctx, "missionBottom");
+        return setWorkflowWidgetShortcutStatus(ctx, "missionBottom");
+      }
+      if (isStandardWorkflowMode(state)) {
+        toggleWorkflowWidget(ctx, "standardBottom");
+        return setWorkflowWidgetShortcutStatus(ctx, "standardBottom");
+      }
+      workflowEditorHintText = workflowEditorHintTextFor(state, loadWorkflowSettings(ctx.cwd)); return;
+    },
+    "workflow.presets.cycle": async (ctx) => {
+      if (workflowWidgetUi(loadGlobalSettings()).enableWidgetShortcuts === false) { workflowEditorHintText = workflowEditorHintTextFor(state, loadWorkflowSettings(ctx.cwd), "Preset:disabled"); return; }
+      if (!isPlanWorkflowUiMode(state) && !isMissionWorkflowMode(state) && !isStandardWorkflowMode(state)) { workflowEditorHintText = workflowEditorHintTextFor(state, loadWorkflowSettings(ctx.cwd)); return; }
+      await cycleWorkflowPreset(ctx, 1);
+    },
+    "workflow.standard.toggle": async (ctx) => {
+      if (isStandardWorkflowMode(state)) return exitStandardModeToIdle(ctx);
+      await enterStandardMode(ctx);
+    },
+    "workflow.plan.toggle": async (ctx) => {
+      if (isPlanWorkflowUiMode(state)) return exitPlanModeToIdle(ctx);
+      await enterPlanModeAwaitingInput(ctx);
+    },
+    "workflow.mission.toggle": async (ctx) => {
+      if (isMissionWorkflowMode(state)) return exitMissionModeToIdle(ctx);
+      await enterMissionModeAwaitingInput(ctx);
+    },
+  };
 
-
-  pi.registerShortcut("ctrl+shift+t", { description: "Toggle active Plan/Mission/Standard top workflow widget", handler: async (ctx) => {
-    if (workflowWidgetUi(loadGlobalSettings()).enableWidgetShortcuts === false) { workflowEditorHintText = workflowEditorHintTextFor(state, loadWorkflowSettings(ctx.cwd), "Top:disabled"); return; }
-    const slot = activeTopWidgetSlot();
-    if (!slot) { workflowEditorHintText = workflowEditorHintTextFor(state, loadWorkflowSettings(ctx.cwd)); return; }
-    toggleWorkflowWidget(ctx, slot);
-    setWorkflowWidgetShortcutStatus(ctx, slot);
-  }});
-  pi.registerShortcut("ctrl+shift+b", { description: "Toggle active Plan/Mission/Standard bottom workflow widget", handler: async (ctx) => {
-    if (workflowWidgetUi(loadGlobalSettings()).enableWidgetShortcuts === false) { workflowEditorHintText = workflowEditorHintTextFor(state, loadWorkflowSettings(ctx.cwd), "Bottom:disabled"); return; }
-    if (isPlanWorkflowUiMode(state) && planBottomRelevant(state)) {
-      toggleWorkflowWidget(ctx, "planBottom");
-      return setWorkflowWidgetShortcutStatus(ctx, "planBottom");
-    }
-    if (isMissionWorkflowMode(state) && missionBottomRelevant(state, activeMissionForUi(state))) {
-      toggleWorkflowWidget(ctx, "missionBottom");
-      return setWorkflowWidgetShortcutStatus(ctx, "missionBottom");
-    }
-    if (isStandardWorkflowMode(state)) {
-      toggleWorkflowWidget(ctx, "standardBottom");
-      return setWorkflowWidgetShortcutStatus(ctx, "standardBottom");
-    }
-    workflowEditorHintText = workflowEditorHintTextFor(state, loadWorkflowSettings(ctx.cwd)); return;
-  }});
-  pi.registerShortcut("ctrl+shift+u", { description: "Cycle workflow presets during Plan/Mission/Standard Mode", handler: async (ctx) => {
-    if (workflowWidgetUi(loadGlobalSettings()).enableWidgetShortcuts === false) { workflowEditorHintText = workflowEditorHintTextFor(state, loadWorkflowSettings(ctx.cwd), "Preset:disabled"); return; }
-    if (!isPlanWorkflowUiMode(state) && !isMissionWorkflowMode(state) && !isStandardWorkflowMode(state)) { workflowEditorHintText = workflowEditorHintTextFor(state, loadWorkflowSettings(ctx.cwd)); return; }
-    await cycleWorkflowPreset(ctx, 1);
-  }});
-  pi.registerShortcut("ctrl+shift+s", { description: "Toggle Standard Mode", handler: async (ctx) => {
-    if (isStandardWorkflowMode(state)) return exitStandardModeToIdle(ctx);
-    await enterStandardMode(ctx);
-  }});
-  pi.registerShortcut("ctrl+shift+l", { description: "Enter Plan Mode", handler: async (ctx) => {
-    if (isPlanWorkflowUiMode(state)) return exitPlanModeToIdle(ctx);
-    await enterPlanModeAwaitingInput(ctx);
-  }});
-  pi.registerShortcut("ctrl+shift+m", { description: "Toggle Mission Mode", handler: async (ctx) => {
-    if (isMissionWorkflowMode(state)) return exitMissionModeToIdle(ctx);
-    await enterMissionModeAwaitingInput(ctx);
-  }});
+  for (const shortcut of WORKFLOW_SHORTCUTS) {
+    pi.registerShortcut(workflowShortcutKey(shortcut.id), {
+      description: shortcut.description,
+      handler: workflowShortcutHandlers[shortcut.id],
+    });
+  }
 
   const handleWorkflowPlansCommand = async (args: string, _ctx: ExtensionContext): Promise<void> => {
     const parts = args.trim().split(/\s+/).filter(Boolean);

package/extensions/workflow-shortcuts.ts

@@ -0,0 +1,114 @@
+import type { KeyId } from "@earendil-works/pi-tui";
+
+export type WorkflowShortcutPlatform = "darwin" | "win32" | "linux";
+export type WorkflowShortcutActionId =
+  | "workflow.widget.top.toggle"
+  | "workflow.widget.bottom.toggle"
+  | "workflow.presets.cycle"
+  | "workflow.standard.toggle"
+  | "workflow.plan.toggle"
+  | "workflow.mission.toggle";
+
+export interface WorkflowShortcutDefinition {
+  id: WorkflowShortcutActionId;
+  description: string;
+  fallbackCommand: string;
+  keys: Record<WorkflowShortcutPlatform, KeyId>;
+}
+
+export const WORKFLOW_SHORTCUTS: WorkflowShortcutDefinition[] = [
+  {
+    id: "workflow.widget.top.toggle",
+    description: "Toggle active Plan/Mission/Standard top workflow widget",
+    fallbackCommand: "/workflow widgets toggle top",
+    keys: { darwin: "ctrl+shift+t", win32: "f2", linux: "f2" },
+  },
+  {
+    id: "workflow.widget.bottom.toggle",
+    description: "Toggle active Plan/Mission/Standard bottom workflow widget",
+    fallbackCommand: "/workflow widgets toggle bottom",
+    keys: { darwin: "ctrl+shift+b", win32: "f3", linux: "f3" },
+  },
+  {
+    id: "workflow.presets.cycle",
+    description: "Cycle workflow presets during Plan/Mission/Standard Mode",
+    fallbackCommand: "/workflow presets next",
+    keys: { darwin: "ctrl+shift+u", win32: "f4", linux: "f4" },
+  },
+  {
+    id: "workflow.standard.toggle",
+    description: "Toggle Standard Mode",
+    fallbackCommand: "/standard",
+    keys: { darwin: "ctrl+shift+s", win32: "f6", linux: "f6" },
+  },
+  {
+    id: "workflow.plan.toggle",
+    description: "Enter Plan Mode",
+    fallbackCommand: "/plan",
+    keys: { darwin: "ctrl+shift+l", win32: "f7", linux: "f7" },
+  },
+  {
+    id: "workflow.mission.toggle",
+    description: "Toggle Mission Mode",
+    fallbackCommand: "/mission",
+    keys: { darwin: "ctrl+shift+m", win32: "f8", linux: "f8" },
+  },
+];
+
+const SHORTCUT_BY_ID = new Map(WORKFLOW_SHORTCUTS.map((shortcut) => [shortcut.id, shortcut]));
+
+export function workflowShortcutPlatform(platform = process.platform): WorkflowShortcutPlatform {
+  if (platform === "darwin" || platform === "win32" || platform === "linux") return platform;
+  return "linux";
+}
+
+export function workflowShortcutKey(id: WorkflowShortcutActionId, platform = process.platform): KeyId {
+  return workflowShortcutDefinition(id).keys[workflowShortcutPlatform(platform)];
+}
+
+export function workflowShortcutDefinition(id: WorkflowShortcutActionId): WorkflowShortcutDefinition {
+  const shortcut = SHORTCUT_BY_ID.get(id);
+  if (!shortcut) throw new Error(`Unknown Workflow Suite shortcut: ${id}`);
+  return shortcut;
+}
+
+export function workflowShortcutLabel(id: WorkflowShortcutActionId, platform = process.platform): string {
+  return workflowShortcutKeyLabel(workflowShortcutKey(id, platform));
+}
+
+export function workflowShortcutKeyLabel(key: KeyId): string {
+  return key.split("+").map((part) => {
+    if (/^f\d+$/i.test(part)) return part.toUpperCase();
+    return part.charAt(0).toUpperCase() + part.slice(1).toLowerCase();
+  }).join("+");
+}
+
+export function workflowEntryShortcutLabel(mode: "standard" | "plan" | "mission", platform = process.platform): string {
+  if (mode === "standard") return `Standard:${workflowShortcutLabel("workflow.standard.toggle", platform)}`;
+  if (mode === "plan") return `Plan:${workflowShortcutLabel("workflow.plan.toggle", platform)}`;
+  return `Mission:${workflowShortcutLabel("workflow.mission.toggle", platform)}`;
+}
+
+export function workflowWidgetShortcutLabel(includeBottom: boolean, platform = process.platform): string {
+  const prefix = includeBottom ? "Widgets" : "Widget";
+  if (!includeBottom) return `${prefix}:${workflowShortcutLabel("workflow.widget.top.toggle", platform)}`;
+  const activePlatform = workflowShortcutPlatform(platform);
+  if (activePlatform === "darwin") return `${prefix}:Ctrl+Shift+T/B`;
+  return `${prefix}:${workflowShortcutLabel("workflow.widget.top.toggle", platform)}/${workflowShortcutLabel("workflow.widget.bottom.toggle", platform)}`;
+}
+
+export function workflowPresetCycleShortcutLabel(platform = process.platform): string {
+  return workflowShortcutLabel("workflow.presets.cycle", platform);
+}
+
+export function workflowSettingsShortcutLines(platform = process.platform): string[] {
+  return [
+    `Standard Shortcut: ${workflowShortcutLabel("workflow.standard.toggle", platform)} toggles Standard Mode`,
+    `Plan Shortcut: ${workflowShortcutLabel("workflow.plan.toggle", platform)} enters Plan Mode`,
+    `Mission Shortcut: ${workflowShortcutLabel("workflow.mission.toggle", platform)} enters Mission Mode`,
+    `Widget Shortcuts: ${workflowWidgetShortcutLabel(true, platform).replace(/^Widgets:/, "")} while Plan/Mission/Standard Mode is active`,
+    `Preset Cycle Shortcut: ${workflowPresetCycleShortcutLabel(platform)} while Plan/Mission/Standard Mode is active`,
+  ];
+}
+
+export default function workflowShortcutsNoopExtension(): void {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mediadatafusion/pi-workflow-suite",
-  "version": "0.0.19",
+  "version": "0.0.20",
   "description": "Multi-agent workflow suite for Pi with Idle, Standard, Plan, Mission, approval gates, reviewer/validator roles, sub-agents, model routing, web search/fetch, browser checks, diagrams, compaction, presets, settings, themes, widgets, and Repo Lock.",
   "license": "Apache-2.0",
   "repository": {

package/scripts/verify-live.sh

@@ -68,6 +68,7 @@ warn_unexpected_loadable_extensions() {
 extensions/subagent/index.ts
 extensions/workflow-model-router.ts
 extensions/workflow-modes.ts
+extensions/workflow-shortcuts.ts
 extensions/workflow-parsers.ts
 extensions/workflow-settings-capabilities.ts
 extensions/workflow-state.ts
@@ -96,6 +97,7 @@ require_file "extensions/workflow-state.ts"
 require_file "extensions/workflow-summary.ts"
 require_file "extensions/workflow-tool-guard.ts"
 require_file "extensions/workflow-model-router.ts"
+require_file "extensions/workflow-shortcuts.ts"
 require_file "extensions/subagent/index.ts"
 require_file "extensions/subagent/agents.ts"
 require_file "package.json"