@mediadatafusion/pi-workflow-suite 0.0.17 → 0.0.19

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable public releases will be documented in this file.
 
+## [0.0.19] - 2026-06-10
+
+### Improved
+
+- Improved workflow widget and settings UI documentation.
+- Refined editor hint readability controls.
+
+## [0.0.18] - 2026-06-10
+
+### Improved
+
+- Improved package metadata and compaction settings documentation.
+- Refined compaction safeguards for default and custom configuration flows.
+
 ## [0.0.17] - 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.17`
+**Workflow Suite Version:** `v0.0.19`
 
 ## Overview
 
@@ -49,6 +49,7 @@ See Pi Workflow Suite in action: structured workflow modes, settings, runtime st
 - [Workflow Roles And Model Selection](#workflow-roles-and-model-selection)
 - [Workflow Settings UI](#workflow-settings-ui)
 - [Workflow Presets](#workflow-presets)
+- [Workflow Widgets And Editor Hints](#workflow-widgets-and-editor-hints)
 - [Themes And UI](#themes-and-ui)
 - [Sub-Agents And Parallel Work](#sub-agents-and-parallel-work)
 - [Review, Validation, Repair, And Retry](#review-validation-repair-and-retry)
@@ -114,18 +115,18 @@ Pi Workflow Suite turns Pi into a guided workflow environment:
 | Standard Mode | Direct active work with optional dynamic task-specific To Do tracking, configurable clarification, widgets, shared or Standard-specific model roles, presets, safety controls, and sub-agent orchestration. |
 | Plan Mode | Approval-gated planning and execution where Planner, Reviewer, Executor, and Validator can each use the provider/model and thinking level that fits the phase. |
 | Mission Mode | Long-running milestone workflows with approval, checkpoints, Mission-specific model overrides, validation gates, repair/retry, pause/resume, final-validation controls, and continuity tracking. |
-| Themes And Startup UI | Workflow Suite themes, startup visual cards, startup logo modes, custom terminal logo text, custom brand cards, footer/status styling, widgets, and optional input border styling. |
+| Themes And Startup UI | Workflow Suite themes, startup visual cards, startup logo modes, custom terminal logo text, custom brand cards, editor hint/status styling, widgets, and optional input border styling. |
 | Interactive Diagrams | `workflow_diagram` Mermaid support with terminal preview, SVG-first clickable artifacts, PNG/runtime rendering support, dark-mode-friendly styling, and runtime artifact storage. |
 | Web Research & Browser Verification | First-party `workflow_web_search`, `workflow_web_fetch`, and `workflow_browser_check` tools. Search and fetch for public web evidence with source URLs, blocked local/private/internal hosts, and time/size limits. Headless browser verification for runtime web app validation with interactive UI actions (click, type, read, screenshot, evaluate). |
 | Repo Lock | Project-scoped Global Safety control that constrains normal file tools, bash path checks, and sub-agents to the active repository, with protected configuration paths and clear non-sandbox caveats. |
-| Compaction | Pi default, custom model, or disabled Workflow Suite compaction so context summarization can use its own provider/model, proactive threshold checks, idle-boundary execution, custom token tuning, adaptive fitting, status reporting, and safe fallback. |
+| Compaction | Shared compaction controls for Pi default or custom summary model selection, Pi default or custom trigger thresholds, idle-boundary proactive checks, custom token tuning, adaptive fitting, status reporting, and safe fallback. |
 | 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. |
 | 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, footer hints, shortcut controls, progress display, runtime summaries, and current-setting visibility. |
+| Widgets And Status | Mode-aware top/bottom widgets, editor hints, shortcut controls, progress display, runtime summaries, and current-setting visibility. |
 | Safety And Recovery | Phase-specific tool restrictions, destructive-command blocking, validation gates, install backup, live verification, audit, quarantine, sync, resume, and checkpoint tooling. |
 
 ## Feature Overview
@@ -153,7 +154,7 @@ Pi Workflow Suite turns Pi into a guided workflow environment:
 
 Idle Mode is the default no-active-workflow state. It means there is no active Standard task, approved Plan execution, or Mission milestone running, but Workflow Suite still provides its management, inspection, and configuration surfaces.
 
-Idle Mode is a first-class part of the Workflow Suite hierarchy. Users can inspect workflow status, open settings, change themes, preview startup visuals, review widget/footer behavior, inspect Repo Lock status through Global Safety settings, configure compaction, review installed workflow resources, and run safe runtime hygiene/status checks. Idle Mode is also where footer hints expose the primary entry points for Standard, Plan, and Mission.
+Idle Mode is a first-class part of the Workflow Suite hierarchy. Users can inspect workflow status, open settings, change themes, preview startup visuals, review widget and editor hint behavior, inspect Repo Lock status through Global Safety settings, configure compaction, review installed workflow resources, and run safe runtime hygiene/status checks. Idle Mode is also where editor hints expose the primary entry points for Standard, Plan, and Mission.
 
 Idle Mode is not a sandbox and does not imply Pi is unable to run commands. It only means Workflow Suite is not currently inside an active Standard, Plan, or Mission workflow. Repo Lock, tool guards, Pi permissions, and sub-agent configuration still determine what can run.
 
@@ -597,7 +598,7 @@ Quick access:
 
 ```text
 /workflow presets              # open preset selector
-Ctrl+Shift+U                   # cycle presets from the footer/status line while Standard/Plan/Mission Mode is active
+Ctrl+Shift+U                   # cycle presets while Standard/Plan/Mission Mode is active
 /workflow presets list
 /workflow presets apply <name>
 /workflow presets next
@@ -609,7 +610,7 @@ Ctrl+Shift+U                   # cycle presets from the footer/status line while
 /workflow presets delete <name>
 ```
 
-The footer/status line stays mode-specific and avoids idle clutter. By default, active workflows display compact, human-readable hints 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 and the other workflow mode:
 
 ```text
 Idle:     Standard:Ctrl+Shift+S Plan:Ctrl+Shift+L Mission:Ctrl+Shift+M
@@ -631,9 +632,55 @@ Workflow Suite settings are separate from Pi core settings. Workflow Suite setti
 
 Pi core settings use a different file pair: global `~/.pi/agent/settings.json` plus exact-current-directory project settings at `<cwd>/.pi/settings.json`. Pi core project settings do not walk parent directories. Use `./scripts/audit-settings.sh [target-cwd]` to report both scopes without printing secrets.
 
+## Workflow Widgets And Editor Hints
+
+Workflow widgets are one of the core Workflow Suite surfaces. Standard, Plan, and Mission Mode can show active workflow status directly in the terminal through mode-aware top and bottom widgets.
+
+The top and bottom widgets are independent visibility surfaces. Users can show either one or both, and toggling a widget does not change the underlying workflow state. The widgets are designed to keep long-running work readable without requiring users to repeatedly ask for status.
+
+Depending on the active mode and settings, widgets can show:
+
+- active workflow mode and lifecycle state,
+- current and next task, step, or milestone,
+- segmented progress bars,
+- Standard Mode To Do progress,
+- Plan Mode approval, execution, validation, and repair state,
+- Mission Mode milestone, checkpoint, validation, retry, and runtime state,
+- selected model route and thinking level,
+- active preset and shortcut hints,
+- sub-agent activity when worker orchestration is active.
+
+Widget shortcuts:
+
+```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
+```
+
+Widget commands:
+
+```text
+/workflow widgets status
+/workflow widgets list
+/workflow widgets configure
+/workflow widgets toggle top
+/workflow widgets toggle bottom
+/workflow widgets on
+/workflow widgets off
+```
+
+Editor hints are compact inline hints shown in the editor/input area. They can show entry shortcuts while idle and widget, preset, and mode-switch shortcuts while a workflow is active. Editor hints are configurable separately from the widget commands themselves, including visibility and contrast.
+
+The interactive settings path is:
+
+```text
+/workflow settings UI Widgets
+```
+
 ## Themes And UI
 
-Workflow Suite themes control the palette used by Workflow Suite visual surfaces: status/footer text, Standard/Plan/Mission widgets, startup visuals, and optional input-area border styling. They are Workflow Suite settings, separate from Pi core themes.
+Workflow Suite themes control the palette used by Workflow Suite visual surfaces: status text, editor hints, Standard/Plan/Mission widgets, startup visuals, and optional input-area border styling. They are Workflow Suite settings, separate from Pi core themes.
 
 Open the interactive theme menu from the public settings surface:
 
@@ -657,7 +704,7 @@ Workflow Theme
 
 How the pieces fit together:
 
-- **Theme** changes Workflow Suite colors for widgets, footer/status text, startup visuals, and optional input border styling.
+- **Theme** changes Workflow Suite colors for widgets, editor hints, status text, startup visuals, and optional input border styling.
 - **Widget Text Style** controls the text treatment used by active workflow widgets.
 - **Startup Visual** chooses the startup card layout: `none`, `minimal`, `workflow_duo`, `mission_control`, `diagnostic_center`, `data_stream`, `neural_grid`, or `custom_brand`.
 - **Startup Text Style** controls startup visual text independently from active workflow widgets.
@@ -799,27 +846,34 @@ Compaction settings are available through:
 /workflow settings Shared Compaction
 ```
 
-Supported modes:
+The grouped Shared Compaction menu separates trigger behavior from summary model selection. The trigger can use Pi default behavior or an explicit Workflow Suite threshold, while the compaction provider/model controls which model writes compaction summaries when configured.
 
-- **Pi default** — preserve Pi built-in compaction.
-- **Custom model** — route compaction summaries through a configured provider/model when available.
-- **Disabled** — disables Workflow Suite custom compaction and leaves Pi fallback behavior.
-- **Custom agent** — planned-only/backward-compatible mode; current releases keep Pi default fallback behavior instead of running agent-routed compaction.
+Workflow Suite can request proactive compaction when context usage reaches the configured threshold. Actual proactive compaction runs only at a safe after-turn idle agent boundary, so it does not interrupt arbitrary tool execution or queued workflow handoffs. Pi default auto-compaction remains available as a safety fallback near the model limit.
 
-Workflow Suite can request proactive compaction when context usage reaches the configured threshold. For Custom model mode, a configured compaction provider/model with custom compaction enabled arms the threshold trigger even when generic auto-trigger behavior is otherwise off. This lets compaction use a different model than planning, execution, review, or validation, which is useful when context summarization has a different cost, speed, or context-window requirement than active workflow work. Actual proactive compaction runs only at a safe after-turn idle agent boundary, so it does not interrupt arbitrary tool execution or queued workflow handoffs. Pi default auto-compaction remains available as a safety fallback near the model limit.
+The menu controls provider/model preference, auto-trigger behavior, trigger threshold, cooldown, reserve tokens, and keep-recent tokens:
+
+```text
+Shared Compaction Settings
+
+Compaction Provider
+Compaction Model
+Workflow Auto Trigger Enabled
+Workflow Trigger Percent
+Workflow Trigger Cooldown
+Custom Reserve Tokens
+Custom Keep Recent Tokens
+List Current Settings
+Back
+```
 
-The grouped Shared Compaction menu controls auto-compaction, trigger threshold, cooldown, reserve tokens, keep-recent tokens, and custom compaction model behavior.
+Each configurable compaction setting includes a Pi default option. Provider and model choices do not change the trigger threshold. The trigger reports `Pi default` when the native Pi threshold formula is in control and reports `custom, <percent>%` only when an explicit Workflow Suite trigger override is set.
 
 Important behavior:
 
 - **Safe boundary**: proactive compaction runs at a safe after-turn idle agent boundary only.
 - **Cooldown**: the cooldown is the minimum wait between proactive attempts; it is not a delay before compaction starts and does not block manual compaction.
-- **Adaptive fit**: Custom model preparation is fit to the selected compaction model context window using configured reserve and keep-recent token settings.
-- **Fallback**: Custom model compaction falls back to Pi default behavior if required settings are missing, the model cannot be found, authentication or API key checks fail, preparation cannot fit, or the compaction call errors.
-- **Status**: `/workflow settings Show Current Settings` reports the effective trigger state, runtime status, selected custom model, reserve/keep-recent token settings, latest check decision, and `Last Custom Compaction Status`.
-
-The legacy `workflowCompactionCheckMode` setting may still exist for compatibility, but the primary release behavior is safe after-turn idle-boundary compaction. It is not permission to compact in the middle of arbitrary tool execution.
-
+- **Adaptive fit**: Custom summary model preparation is fit to the selected model context window using configured reserve and keep-recent token settings.
+- **Fallback**: Custom summary model compaction falls back to Pi default behavior if required settings are missing, the model cannot be found, authentication or API key checks fail, preparation cannot fit, or the compaction call errors.
 ## Diagram Support
 
 Workflow Suite includes a `workflow_diagram` tool for Mermaid diagrams in workflow explanations, architecture notes, state transitions, data flows, export/share flows, and dependency maps. It is available to Workflow Suite execution and validation surfaces through the shared workflow tool set.
@@ -946,30 +1000,7 @@ Runtime tracking is active-runtime based:
 - Paused, blocked, stopped, completed, failed, draft, planned, and approved states do not accumulate active runtime.
 - `maxRuntimeHours` is enforced against active runtime at mission start/continue/validation/repair gates.
 
-Workflow entry and widget controls are available through `/standard`, `/plan`, `/mission`, and `/workflow widgets`. Keyboard shortcuts keep the footer mode-specific:
-
-```text
-Ctrl+Shift+S  toggle Standard Mode
-Ctrl+Shift+L  enter Plan Mode
-Ctrl+Shift+M  enter Mission Mode
-Ctrl+Shift+T  toggle active Standard/Plan/Mission top widget
-Ctrl+Shift+B  toggle active Standard/Plan/Mission bottom widget
-Ctrl+Shift+U  cycle presets while Standard/Plan/Mission Mode is active
-```
-
-Widget commands:
-
-```text
-/workflow widgets status
-/workflow widgets list
-/workflow widgets configure
-/workflow widgets toggle top
-/workflow widgets toggle bottom
-/workflow widgets on
-/workflow widgets off
-```
-
-Footer hints can be tuned without disabling the actual commands/shortcuts. The interactive path is `/workflow settings UI Widgets` → `Footer Hints`.
+Workflow entry and widget controls are available through `/standard`, `/plan`, `/mission`, and `/workflow widgets`. See [Workflow Widgets And Editor Hints](#workflow-widgets-and-editor-hints) for the top widget, bottom widget, shortcut, and editor hint controls.
 
 Mission heartbeat and stale-status fields are tracked and displayed. Checkpoint interval settings record the preferred cadence for future timed checkpoint automation, while recovery actions remain user-supervised for safety.
 
@@ -1007,8 +1038,8 @@ pi install -l npm:@mediadatafusion/pi-workflow-suite
 ### Installing specific versions
 
 ```bash
-pi install npm:@mediadatafusion/pi-workflow-suite@0.0.17
-pi install -l npm:@mediadatafusion/pi-workflow-suite@0.0.17
+pi install npm:@mediadatafusion/pi-workflow-suite@0.0.19
+pi install -l npm:@mediadatafusion/pi-workflow-suite@0.0.19
 ```
 
 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>`.
@@ -1124,8 +1155,8 @@ Primary settings areas:
 - `standard` — Standard Mode enablement, dynamic To Do tracking, configurable clarification, widgets, model role, Standard sub-agent orchestration, and shared model selection.
 - `missions` — Mission Mode autonomy, runtime, checkpoints, validation, repair, and mission-specific model selection.
 - `subagents` — workflow phase policies, worker targets, activity indicator, parallelism preferences, and edit-concurrency guidance. These settings do not edit arbitrary sub-agent tool permissions.
-- `context` — compaction mode, custom compaction provider/model, proactive trigger percentage, check mode, cooldown, and fallback status.
-- `ui` — widgets, shortcuts, Workflow Suite theme selection, startup visuals, startup logo text styling, footer/status hints, and optional themed input borders.
+- `context` — compaction provider/model, auto-trigger behavior, trigger percentage, cooldown, reserve tokens, and keep-recent tokens.
+- `ui` — widgets, shortcuts, Workflow Suite theme selection, startup visuals, startup logo text styling, editor hints, status text, and optional themed input borders.
 - `safety` — bash/tool guard settings.
 
 Important Standard Mode settings:
@@ -1207,17 +1238,17 @@ See `docs/TROUBLESHOOTING.md` for detailed diagnostics.
 
 ## Operational Notes
 
-- Use Custom model mode for active custom compaction today. Custom agent mode is reserved for agent-routed compaction and keeps Pi fallback behavior in current releases.
+- Configure a compaction provider/model when summaries should use a custom model; trigger behavior remains separate and can stay on Pi default behavior.
 - Mission checkpoints are created at workflow gates and progress saves. The checkpoint interval setting records the preferred cadence for future timed checkpoint automation.
 - Watchdog status can report stale mission activity when enabled. Recovery remains user-supervised so Mission Mode does not resume or mutate work unexpectedly.
 - Parallel file edits are governed separately from parallel sub-agent work. Scoped parallel edit mode requires conflict protection; otherwise the main workflow keeps writes serialized for safety.
 
 ## Versioning
 
-The current preparation version is `v0.0.17`. Version information is intentionally aligned across:
+The current preparation version is `v0.0.19`. Version information is intentionally aligned across:
 
-- `VERSION` (`v0.0.17`),
-- `package.json` (`0.0.17`),
+- `VERSION` (`v0.0.19`),
+- `package.json` (`0.0.19`),
 - `package-lock.json`,
 - this README,
 - Workflow Suite settings/about output.

package/VERSION

@@ -1 +1 @@
-v0.0.17
+v0.0.19

package/config/workflow-settings.example.json

@@ -254,6 +254,7 @@
     "showActiveWorkflowSwitchHint": true,
     "showWidgetShortcutHint": true,
     "showPresetShortcutHint": true,
+    "editorHintContrast": "normal",
     "workflowTheme": "aurora",
     "workflowThemeOverrides": {},
     "startupVisual": "mission_control",

package/extensions/workflow-model-router.ts

@@ -38,6 +38,7 @@ export type WorkflowStartupLogoFont = "block" | "shadow" | "outline" | "wide" |
 export type WorkflowStartupLogoShadowDirection = "down_right" | "down" | "up" | "left" | "right";
 export type WorkflowStartupLogoColorStyle = "theme" | "primary" | "split";
 export type WorkflowWidgetTextPreset = "normal" | "bold" | "light" | "rich" | "italic" | "underline" | "terminal" | "smallcaps" | "typewriter";
+export type WorkflowEditorHintContrast = "subtle" | "normal" | "bright" | "high";
 export type CustomBrandBaseVisual = "minimal" | "diagnostic_center" | "workflow_duo" | "mission_control" | "data_stream" | "neural_grid";
 export type RepairRetryGateName = "review" | "validation" | "missionValidation" | "missionFinalValidation";
 
@@ -239,6 +240,7 @@ export interface WorkflowSettings {
     showActiveWorkflowSwitchHint?: boolean;
     showWidgetShortcutHint?: boolean;
     showPresetShortcutHint?: boolean;
+    editorHintContrast?: WorkflowEditorHintContrast;
     workflowTheme?: string;
     workflowThemeOverrides?: Record<string, string>;
     widgetTextStyle?: WorkflowWidgetTextPreset;
@@ -528,6 +530,7 @@ const BUILTIN_DEFAULT_WORKFLOW_SETTINGS = {
     "showActiveWorkflowSwitchHint": true,
     "showWidgetShortcutHint": true,
     "showPresetShortcutHint": true,
+    "editorHintContrast": "normal",
     "workflowTheme": "aurora",
     "workflowThemeOverrides": {},
     "widgetTextStyle": undefined,
@@ -1434,14 +1437,8 @@ export function workflowSettingsConsistencyDiagnostics(settings: WorkflowSetting
   if (settings.missions.finalValidationEnabled === true && (!settings.models.validator.enabled || !roleIsConfigured(settings.models.validator))) {
     diagnostics.push("mission final validation is enabled but the shared validator model is disabled or unconfigured");
   }
-  if (settings.context.compactionMode === "custom_model" && (!settings.context.compactionModelProvider || !settings.context.compactionModel)) {
-    diagnostics.push("custom compaction model mode is selected but compaction provider/model is incomplete");
-  }
-  if (settings.context.compactionMode === "custom_model" && settings.context.customCompactionEnabled !== true) {
-    diagnostics.push("custom compaction mode is selected but customCompactionEnabled is not set — custom compaction will not activate");
-  }
-  if (settings.context.customCompactionEnabled === true && settings.context.compactionMode !== "custom_model") {
-    diagnostics.push(`customCompactionEnabled=true but compactionMode=${settings.context.compactionMode}`);
+  if ((settings.context.compactionModelProvider || settings.context.compactionModel) && (!settings.context.compactionModelProvider || !settings.context.compactionModel)) {
+    diagnostics.push("custom compaction summary model preference is incomplete");
   }
   if (settings.missions.autoRepairReviewFailures !== false && settings.missions.reviewRetryMode === "off") {
     diagnostics.push("mission review auto-repair is enabled but reviewRetryMode is off — override to safe_only will be applied at runtime; set reviewRetryMode explicitly to avoid confusion");