pi-usereq 0.6.0 → 0.7.0

package/src/index.ts

@@ -8,7 +8,7 @@
  * @brief Declares the extension version string.
  * @details The value is exported for external inspection and packaging metadata alignment. Access complexity is O(1).
  */
-export const VERSION = "0.6.0"
+export const VERSION = "0.7.0"
 
 import path from "node:path";
 import type {
@@ -52,6 +52,7 @@ import {
   type FindToolScope,
 } from "./core/find-payload.js";
 import {
+  DEFAULT_SRC_DIRS,
   getDefaultConfig,
   getProjectConfigPath,
   loadConfig,
@@ -61,14 +62,22 @@ import {
   type UseReqConfig,
 } from "./core/config.js";
 import {
+  DEFAULT_PI_NOTIFY_CMD,
+  DEFAULT_PI_NOTIFY_PUSHOVER_TEXT,
+  DEFAULT_PI_NOTIFY_PUSHOVER_TITLE,
+  DEFAULT_PI_NOTIFY_SOUND_HIGH_CMD,
+  DEFAULT_PI_NOTIFY_SOUND_LOW_CMD,
+  DEFAULT_PI_NOTIFY_SOUND_MID_CMD,
   cyclePiNotifySoundLevel,
-  formatPiNotifyBeepStatus,
   formatPiNotifyPushoverStatus,
+  formatPiNotifyStatus,
+  normalizePiNotifyCommand,
   normalizePiNotifyPushoverCredential,
   normalizePiNotifyPushoverPriority,
+  normalizePiNotifyTemplateValue,
   runPiNotifyEffects,
+  type PiNotifyEventRequest,
   type PiNotifyPushoverPriority,
-  type PiNotifyPushoverRequest,
   type PiNotifySoundLevel,
 } from "./core/pi-notify.js";
 import { formatRuntimePathForDisplay } from "./core/path-context.js";
@@ -104,9 +113,7 @@ import {
 } from "./core/tool-runner.js";
 import { LANGUAGE_TAGS } from "./core/find-constructs.js";
 import {
-  STATIC_CHECK_MODULES,
   getSupportedStaticCheckLanguageSupport,
-  parseEnableStaticCheck,
 } from "./core/static-check.js";
 import { makeRelativeIfContainsProject, shellSplit } from "./core/utils.js";
 
@@ -187,15 +194,17 @@ function saveProjectConfig(cwd: string, config: UseReqConfig): void {
 
 /**
  * @brief Formats the current project config path for top-level menu display.
- * @details Resolves `<base-path>/.pi-usereq/config.json` from the cwd-derived
- * project base and formats it relative to the user home when possible. Runtime
- * is O(p) in path length. No external state is mutated.
+ * @details Resolves `<base-path>/.pi-usereq/config.json` from the cwd-derived project base, reuses the shared runtime-path formatter, and rewrites a leading POSIX `$HOME` token to `~` for the `Show configuration` row only. Runtime is O(p) in path length. No external state is mutated.
  * @param[in] cwd {string} Current working directory.
- * @return {string} User-home-relative or absolute config path display value.
+ * @return {string} `~`-relative or absolute config path display value.
  * @satisfies REQ-162
  */
 function formatProjectConfigPathForMenu(cwd: string): string {
-  return formatRuntimePathForDisplay(getProjectConfigPath(getProjectBase(cwd)));
+  const displayPath = formatRuntimePathForDisplay(getProjectConfigPath(getProjectBase(cwd)));
+  if (displayPath === "$HOME") {
+    return "~";
+  }
+  return displayPath.startsWith("$HOME/") ? `~/${displayPath.slice("$HOME/".length)}` : displayPath;
 }
 
 /**
@@ -278,6 +287,43 @@ function buildTokenToolExecuteResult(
   return buildStructuredToolExecuteResult(details);
 }
 
+/**
+ * @brief Builds the fallback execute result returned when token counting fails before payload construction.
+ * @details Normalizes one thrown `ReqError` into the stable token-tool response shape so missing runtime dependencies or other pre-count failures do not abort extension tool execution. Runtime is O(1). No external state is mutated.
+ * @param[in] error {unknown} Thrown token-tool failure.
+ * @return {{ content: Array<{ type: "text"; text: string }>; details: TokenToolPayload & { execution: { code: number; stderr: string } } }} Structured token-tool failure result.
+ */
+function buildFailedTokenToolExecuteResult(
+  error: unknown,
+): {
+  content: Array<{ type: "text"; text: string }>;
+  details: TokenToolPayload & { execution: { code: number; stderr: string } };
+} {
+  const result = normalizeToolFailure(error);
+  const details = {
+    summary: {
+      processable_file_count: 0,
+      counted_file_count: 0,
+      error_file_count: 0,
+      skipped_file_count: 0,
+      total_token_count: 0,
+      total_character_count: 0,
+      total_byte_count: 0,
+      total_line_count: 0,
+      average_token_count_per_counted_file: 0,
+      average_character_count_per_counted_file: 0,
+      average_byte_count_per_counted_file: 0,
+      average_line_count_per_counted_file: 0,
+    },
+    files: [],
+    execution: {
+      code: result.code,
+      stderr: result.stderr,
+    },
+  };
+  return buildStructuredToolExecuteResult(details);
+}
+
 /**
  * @brief Builds the agent-oriented execute result returned by references tools.
  * @details Mirrors the structured references payload into both the text `content` channel and the machine-readable `details` channel while isolating execution metadata under `execution`. Runtime is O(n) in payload size. No side effects occur.
@@ -494,19 +540,6 @@ function getConfiguredEnabledPiUsereqTools(config: UseReqConfig): string[] {
   return enabledTools;
 }
 
-/**
- * @brief Classifies one configurable tool as embedded or extension-owned.
- * @details Uses the runtime `sourceInfo.source` field plus the supported embedded-name subset to produce one stable UI label. Runtime is O(1). No external state is mutated.
- * @param[in] tool {ToolInfo} Runtime tool descriptor.
- * @return {"builtin" | "extension"} Stable tool-kind label.
- */
-function getPiUsereqToolKind(tool: ToolInfo): "builtin" | "extension" {
-  if (tool.sourceInfo?.source === "builtin" && isPiUsereqEmbeddedToolName(tool.name)) {
-    return "builtin";
-  }
-  return "extension";
-}
-
 /**
  * @brief Applies the configured active-tool enablement to the current session.
  * @details Preserves non-configurable active tools, removes every configurable tool from the active set, then re-adds only configured tools that exist in the current runtime inventory. Runtime is O(t). Side effects include `pi.setActiveTools(...)`.
@@ -539,20 +572,19 @@ function applyConfiguredPiUsereqTools(pi: ExtensionAPI, config: UseReqConfig): v
  * @details Applies session-start-specific resource validation, project-config
  * refresh, and startup-tool enablement before forwarding the originating hook
  * name and payload into the shared `updateExtensionStatus(...)` pipeline.
- * On `agent_end`, also dispatches configured pi-notify beep, sound, and
+ * On `agent_end`, also dispatches configured command-notify, sound, and
  * prompt-specific Pushover effects when the current run originates from a
  * bundled prompt command. Runtime is dominated by configuration loading during
  * `session_start`; all other hooks are O(1). Side effects include resource
  * checks, active-tool mutation, status updates, live-ticker disposal on
- * shutdown, stdout writes, optional child-process spawning, and outbound
- * HTTPS requests.
+ * shutdown, optional child-process spawning, and outbound HTTPS requests.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @param[in] hookName {PiUsereqStatusHookName} Intercepted hook name.
  * @param[in] event {unknown} Hook payload forwarded by pi.
  * @param[in] ctx {ExtensionContext} Active extension context.
  * @return {Promise<void>} Promise resolved when hook processing completes.
- * @satisfies REQ-117, REQ-118, REQ-119, REQ-129, REQ-130, REQ-131, REQ-132, REQ-133, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172
+ * @satisfies REQ-117, REQ-118, REQ-119, REQ-131, REQ-132, REQ-133, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-176, REQ-178, REQ-184, REQ-185, REQ-186, REQ-187
  */
 async function handleExtensionStatusEvent(
   pi: ExtensionAPI,
@@ -561,6 +593,16 @@ async function handleExtensionStatusEvent(
   event: unknown,
   ctx: ExtensionContext,
 ): Promise<void> {
+  const notifyRequest: PiNotifyEventRequest | undefined = hookName === "agent_end"
+    && statusController.state.activePromptRequest !== undefined
+    && statusController.state.runStartTimeMs !== undefined
+    ? {
+        promptName: statusController.state.activePromptRequest.promptName,
+        promptArgs: statusController.state.activePromptRequest.promptArgs,
+        basePath: path.resolve(ctx.cwd),
+        completionTimeMs: Math.max(0, Date.now() - statusController.state.runStartTimeMs),
+      }
+    : undefined;
   if (hookName === "session_start") {
     ensureBundledResourcesAccessible();
     const config = loadProjectConfig(ctx.cwd);
@@ -570,19 +612,10 @@ async function handleExtensionStatusEvent(
   updateExtensionStatus(statusController, hookName, event, ctx);
   if (hookName === "agent_end") {
     if (statusController.config) {
-      const pushoverRequest: PiNotifyPushoverRequest | undefined = statusController.state.activePromptRequest
-        && statusController.state.lastRunDurationMs !== undefined
-        ? {
-            promptName: statusController.state.activePromptRequest.promptName,
-            promptArgs: statusController.state.activePromptRequest.promptArgs,
-            basePath: path.resolve(ctx.cwd),
-            completionTimeMs: statusController.state.lastRunDurationMs,
-          }
-        : undefined;
       runPiNotifyEffects(
         statusController.config,
         event as { messages: AgentEndEvent["messages"] },
-        pushoverRequest,
+        notifyRequest,
       );
     }
     statusController.state.activePromptRequest = undefined;
@@ -632,131 +665,397 @@ function setConfiguredPiUsereqTools(pi: ExtensionAPI, config: UseReqConfig, enab
 }
 
 /**
- * @brief Renders a textual reference for configurable-tool configuration and runtime state.
- * @details Lists every configurable tool with configured enablement, runtime activation, builtin-versus-extension classification, source metadata, and optional descriptions. Runtime is O(t). No side effects occur.
- * @param[in] pi {ExtensionAPI} Active extension API instance.
- * @param[in] config {UseReqConfig} Effective project configuration.
- * @return {string} Multiline tool-status report.
+ * @brief Represents one persisted boolean notification-setting key.
+ * @details Restricts menu toggles to the global enable flags and completed/interrupted/failed event toggles used by command-notify, sound, and Pushover configuration. Compile-time only and introduces no runtime cost.
  */
-function renderPiUsereqToolsReference(pi: ExtensionAPI, config: UseReqConfig): string {
-  const tools = getPiUsereqStartupTools(pi);
-  const enabledTools = new Set(getConfiguredEnabledPiUsereqTools(config));
-  const activeTools = new Set(pi.getActiveTools());
-  const lines = [
-    "# configurable active tools",
-    "",
-    `Configured enabled tools: ${enabledTools.size}/${tools.length}`,
-    `Currently active tools: ${tools.filter((tool) => activeTools.has(tool.name)).length}/${tools.length}`,
-    "",
-    "Tools:",
-  ];
+type PiNotifyBooleanConfigKey =
+  | "notify-enabled"
+  | "notify-on-completed"
+  | "notify-on-interrupted"
+  | "notify-on-failed"
+  | "notify-sound-on-completed"
+  | "notify-sound-on-interrupted"
+  | "notify-sound-on-failed"
+  | "notify-pushover-enabled"
+  | "notify-pushover-on-completed"
+  | "notify-pushover-on-interrupted"
+  | "notify-pushover-on-failed";
 
-  for (const tool of tools) {
-    const configured = enabledTools.has(tool.name) ? "enabled" : "disabled";
-    const active = activeTools.has(tool.name) ? "active" : "inactive";
-    const source = tool.sourceInfo ? `${tool.sourceInfo.source}:${tool.sourceInfo.path}` : "unknown";
-    lines.push(`- ${tool.name}`);
-    lines.push(`  kind: ${getPiUsereqToolKind(tool)}`);
-    lines.push(`  configured: ${configured}`);
-    lines.push(`  runtime: ${active}`);
-    lines.push(`  source: ${source}`);
-    if (tool.description) {
-      lines.push(`  description: ${tool.description}`);
-    }
-  }
+/**
+ * @brief Represents one persisted boolean notification event-toggle key.
+ * @details Restricts shared event-submenu mutation helpers to completed/interrupted/failed toggles and excludes global enable flags. Compile-time only and introduces no runtime cost.
+ */
+type PiNotifyEventBooleanConfigKey = Exclude<
+  PiNotifyBooleanConfigKey,
+  "notify-enabled" | "notify-pushover-enabled"
+>;
+
+/**
+ * @brief Represents one shared prompt-end event identifier used by notification menus.
+ * @details Restricts event-submenu rendering to the canonical completed/interrupted/failed domain shared by command-notify, sound, and Pushover routing. Compile-time only and introduces no runtime cost.
+ */
+type PiNotifyEventId = "completed" | "interrupted" | "failed";
 
-  return `${lines.join("\n")}\n`;
+/**
+ * @brief Describes one shared prompt-end event row rendered inside notification event submenus.
+ * @details Binds one canonical event identifier to the human-readable label and terminal-outcome description reused across command-notify, sound, and Pushover event menus. The interface is compile-time only and introduces no runtime cost.
+ */
+interface PiNotifyEventRowDefinition {
+  eventId: PiNotifyEventId;
+  label: string;
+  description: string;
 }
 
 /**
- * @brief Represents one persisted pi-notify beep flag key.
- * @details Restricts menu toggles to the three independent prompt-end beep
- * flags stored in project configuration. Compile-time only and introduces no
- * runtime cost.
+ * @brief Describes one notification-system event submenu contract.
+ * @details Binds the top-level launcher row, submenu title, toast prefix, and completed/interrupted/failed config keys for one notification transport. The interface is compile-time only and introduces no runtime cost.
  */
-type PiNotifyBeepConfigKey =
-  | "notify-beep-on-end"
-  | "notify-beep-on-esc"
-  | "notify-beep-on-error";
+interface PiNotifyEventMenuDefinition {
+  topLevelId: string;
+  topLevelLabel: string;
+  submenuTitle: string;
+  systemLabel: string;
+  keys: Record<PiNotifyEventId, PiNotifyEventBooleanConfigKey>;
+}
 
 /**
- * @brief Flips one persisted pi-notify beep flag.
- * @details Negates the selected prompt-end beep flag in place and returns the resulting boolean value so callers can emit deterministic UI feedback. Runtime is O(1). Side effect: mutates `config`.
+ * @brief Flips one persisted boolean notification setting.
+ * @details Negates the selected configuration flag in place and returns the resulting boolean value so callers can emit deterministic UI feedback. Runtime is O(1). Side effect: mutates `config`.
  * @param[in,out] config {UseReqConfig} Mutable configuration object.
- * @param[in] key {PiNotifyBeepConfigKey} Beep flag key to toggle.
+ * @param[in] key {PiNotifyBooleanConfigKey} Boolean configuration key to toggle.
  * @return {boolean} Next enabled state.
  */
-function togglePiNotifyBeepFlag(config: UseReqConfig, key: PiNotifyBeepConfigKey): boolean {
+function togglePiNotifyFlag(config: UseReqConfig, key: PiNotifyBooleanConfigKey): boolean {
   config[key] = !config[key];
   return config[key];
 }
 
+/**
+ * @brief Restores notification-related settings to their documented defaults.
+ * @details Copies the command-notify, sound, and Pushover configuration subtree from a fresh default config into the supplied mutable project config. Runtime is O(1). Side effect: mutates `config`.
+ * @param[in,out] config {UseReqConfig} Mutable configuration object.
+ * @return {void} No return value.
+ * @satisfies REQ-174, REQ-178, REQ-184, REQ-195, REQ-196
+ */
+function resetPiNotifyConfigToDefaults(config: UseReqConfig): void {
+  const defaults = getDefaultConfig("");
+  config["notify-enabled"] = defaults["notify-enabled"];
+  config["notify-on-completed"] = defaults["notify-on-completed"];
+  config["notify-on-interrupted"] = defaults["notify-on-interrupted"];
+  config["notify-on-failed"] = defaults["notify-on-failed"];
+  config["notify-sound"] = defaults["notify-sound"];
+  config["notify-sound-on-completed"] = defaults["notify-sound-on-completed"];
+  config["notify-sound-on-interrupted"] = defaults["notify-sound-on-interrupted"];
+  config["notify-sound-on-failed"] = defaults["notify-sound-on-failed"];
+  config["notify-sound-toggle-shortcut"] = defaults["notify-sound-toggle-shortcut"];
+  config["notify-pushover-enabled"] = defaults["notify-pushover-enabled"];
+  config["notify-pushover-on-completed"] = defaults["notify-pushover-on-completed"];
+  config["notify-pushover-on-interrupted"] = defaults["notify-pushover-on-interrupted"];
+  config["notify-pushover-on-failed"] = defaults["notify-pushover-on-failed"];
+  config["notify-pushover-user-key"] = defaults["notify-pushover-user-key"];
+  config["notify-pushover-api-token"] = defaults["notify-pushover-api-token"];
+  config["notify-pushover-priority"] = defaults["notify-pushover-priority"];
+  config["notify-pushover-title"] = defaults["notify-pushover-title"];
+  config["notify-pushover-text"] = defaults["notify-pushover-text"];
+  config.PI_NOTIFY_CMD = defaults.PI_NOTIFY_CMD;
+  config.PI_NOTIFY_SOUND_LOW_CMD = defaults.PI_NOTIFY_SOUND_LOW_CMD;
+  config.PI_NOTIFY_SOUND_MID_CMD = defaults.PI_NOTIFY_SOUND_MID_CMD;
+  config.PI_NOTIFY_SOUND_HIGH_CMD = defaults.PI_NOTIFY_SOUND_HIGH_CMD;
+}
+
 /**
  * @brief Formats one persisted Pushover priority for menu display.
- * @details Maps the canonical `0|1` priority domain to deterministic menu text reused by the Pushover configuration UI. Runtime is O(1). No external state is mutated.
+ * @details Maps the canonical `0|1` priority domain to deterministic `Normal|High` labels reused by the Pushover configuration UI. Runtime is O(1). No external state is mutated.
  * @param[in] priority {PiNotifyPushoverPriority} Persisted Pushover priority.
  * @return {string} Menu-display label.
- * @satisfies REQ-165
+ * @satisfies REQ-172
  */
 function formatPiNotifyPushoverPriority(priority: PiNotifyPushoverPriority): string {
-  return priority === 1 ? "1=High Priority" : "0=Normal";
+  return priority === 1 ? "High" : "Normal";
 }
 
 /**
- * @brief Builds the shared settings-menu choices for Pushover configuration.
- * @details Serializes the Pushover global-disable flag, successful-completion enable flag, credential strings, and priority value into right-valued menu rows consumed by the shared settings-menu renderer. Runtime is O(1). No external state is mutated.
+ * @brief Defines the shared prompt-end event rows reused across notification submenus.
+ * @details Encodes the human-readable completed/interrupted/failed labels and terminal-state descriptions required by the command-notify, sound, and Pushover event menus. Access complexity is O(1).
+ * @satisfies REQ-188, REQ-198
+ */
+const PI_NOTIFY_EVENT_ROW_DEFINITIONS: PiNotifyEventRowDefinition[] = [
+  {
+    eventId: "completed",
+    label: "Prompt completed",
+    description: "Toggle delivery when the prompt finishes without interruption or failure.",
+  },
+  {
+    eventId: "interrupted",
+    label: "Prompt interrupted",
+    description: "Toggle delivery when the prompt finishes with assistant stopReason `aborted`.",
+  },
+  {
+    eventId: "failed",
+    label: "Prompt failed",
+    description: "Toggle delivery when the prompt finishes with assistant stopReason `error`.",
+  },
+];
+
+/**
+ * @brief Defines the shared event-submenu contracts for command-notify, sound, and Pushover.
+ * @details Binds each notification transport to its top-level launcher row, submenu title, toast prefix, and completed/interrupted/failed config-key set. Access complexity is O(1).
+ * @satisfies REQ-174, REQ-178, REQ-184, REQ-198
+ */
+const PI_NOTIFY_EVENT_MENU_DEFINITIONS: Record<
+  "notification" | "sound" | "pushover",
+  PiNotifyEventMenuDefinition
+> = {
+  notification: {
+    topLevelId: "notification-events",
+    topLevelLabel: "Notification events",
+    submenuTitle: "Notification events",
+    systemLabel: "Notification",
+    keys: {
+      completed: "notify-on-completed",
+      interrupted: "notify-on-interrupted",
+      failed: "notify-on-failed",
+    },
+  },
+  sound: {
+    topLevelId: "sound-events",
+    topLevelLabel: "Sound events",
+    submenuTitle: "Sound events",
+    systemLabel: "Sound",
+    keys: {
+      completed: "notify-sound-on-completed",
+      interrupted: "notify-sound-on-interrupted",
+      failed: "notify-sound-on-failed",
+    },
+  },
+  pushover: {
+    topLevelId: "pushover-events",
+    topLevelLabel: "Pushover events",
+    submenuTitle: "Pushover events",
+    systemLabel: "Pushover",
+    keys: {
+      completed: "notify-pushover-on-completed",
+      interrupted: "notify-pushover-on-interrupted",
+      failed: "notify-pushover-on-failed",
+    },
+  },
+};
+
+/**
+ * @brief Formats the top-level summary value for one notification event submenu.
+ * @details Counts enabled completed/interrupted/failed toggles for the selected transport and renders the result as `n/3 on` for right-aligned menu display. Runtime is O(1). No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
- * @return {PiUsereqSettingsMenuChoice[]} Ordered Pushover-menu choice vector.
- * @satisfies REQ-163, REQ-165, REQ-166, REQ-172
+ * @param[in] eventMenu {PiNotifyEventMenuDefinition} Notification-system event submenu contract.
+ * @return {string} Compact enabled-toggle summary.
+ * @satisfies REQ-198
  */
-function buildPiNotifyPushoverMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
+function formatPiNotifyEventMenuSummary(
+  config: UseReqConfig,
+  eventMenu: PiNotifyEventMenuDefinition,
+): string {
+  const enabledCount = PI_NOTIFY_EVENT_ROW_DEFINITIONS.filter(
+    (row) => config[eventMenu.keys[row.eventId]] === true,
+  ).length;
+  return `${enabledCount}/3 on`;
+}
+
+/**
+ * @brief Builds the top-level launcher row for one notification event submenu.
+ * @details Reuses the shared completed/interrupted/failed summary renderer so the `Notifications` menu can expose dedicated event editors for command-notify, sound, and Pushover in a uniform shape. Runtime is O(1). No external state is mutated.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @param[in] eventMenu {PiNotifyEventMenuDefinition} Notification-system event submenu contract.
+ * @return {PiUsereqSettingsMenuChoice} Launcher row for the selected event submenu.
+ * @satisfies REQ-181, REQ-183, REQ-165, REQ-198
+ */
+function buildPiNotifyEventLauncherChoice(
+  config: UseReqConfig,
+  eventMenu: PiNotifyEventMenuDefinition,
+): PiUsereqSettingsMenuChoice {
+  return {
+    id: eventMenu.topLevelId,
+    label: eventMenu.topLevelLabel,
+    value: formatPiNotifyEventMenuSummary(config, eventMenu),
+    description: `Open the ${eventMenu.submenuTitle} submenu for shared prompt-end delivery events.`,
+  };
+}
+
+/**
+ * @brief Builds the shared settings-menu choices for one notification event submenu.
+ * @details Serializes completed/interrupted/failed rows with right-aligned `on|off` values, then appends `Reset defaults` and `Save and close` for submenu-scoped mutation control. Runtime is O(1). No external state is mutated.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @param[in] eventMenu {PiNotifyEventMenuDefinition} Notification-system event submenu contract.
+ * @return {PiUsereqSettingsMenuChoice[]} Ordered event-submenu choice vector.
+ * @satisfies REQ-188, REQ-193, REQ-198
+ */
+function buildPiNotifyEventMenuChoices(
+  config: UseReqConfig,
+  eventMenu: PiNotifyEventMenuDefinition,
+): PiUsereqSettingsMenuChoice[] {
   return [
+    ...PI_NOTIFY_EVENT_ROW_DEFINITIONS.map((row) => ({
+      id: eventMenu.keys[row.eventId],
+      label: row.label,
+      value: config[eventMenu.keys[row.eventId]] ? "on" : "off",
+      description: `${eventMenu.systemLabel}: ${row.description}`,
+    })),
+    {
+      id: "reset-defaults",
+      label: "Reset defaults",
+      value: "",
+      description: `Restore the documented default ${eventMenu.systemLabel.toLowerCase()} event toggles.`,
+    },
     {
-      id: "pushover-global-disable",
-      label: "Global disable",
-      value: config["notify-pushover-global-disable"] ? "on" : "off",
-      description: "Suppress all Pushover delivery without changing the successful-prompt enable flag.",
+      id: "save-and-close",
+      label: "Save and close",
+      value: "",
+      description: "Return to the notifications menu.",
     },
+  ];
+}
+
+/**
+ * @brief Restores one notification event submenu to its documented defaults.
+ * @details Copies only the completed/interrupted/failed toggles referenced by the supplied submenu contract from a fresh default config into the mutable project config. Runtime is O(1). Side effect: mutates `config`.
+ * @param[in,out] config {UseReqConfig} Mutable configuration object.
+ * @param[in] eventMenu {PiNotifyEventMenuDefinition} Notification-system event submenu contract.
+ * @return {void} No return value.
+ * @satisfies REQ-174, REQ-178, REQ-184, REQ-195
+ */
+function resetPiNotifyEventMenuToDefaults(
+  config: UseReqConfig,
+  eventMenu: PiNotifyEventMenuDefinition,
+): void {
+  const defaults = getDefaultConfig("");
+  for (const key of Object.values(eventMenu.keys) as PiNotifyEventBooleanConfigKey[]) {
+    config[key] = defaults[key];
+  }
+}
+
+/**
+ * @brief Resolves the human-readable event label for one event-toggle config key.
+ * @details Matches the supplied config key against the submenu contract and returns the corresponding completed/interrupted/failed menu label for deterministic notification toasts. Runtime is O(1). No external state is mutated.
+ * @param[in] key {PiNotifyEventBooleanConfigKey} Event-toggle configuration key.
+ * @param[in] eventMenu {PiNotifyEventMenuDefinition} Notification-system event submenu contract.
+ * @return {string} Human-readable event label.
+ * @satisfies REQ-188, REQ-198
+ */
+function resolvePiNotifyEventLabel(
+  key: PiNotifyEventBooleanConfigKey,
+  eventMenu: PiNotifyEventMenuDefinition,
+): string {
+  return PI_NOTIFY_EVENT_ROW_DEFINITIONS.find(
+    (row) => eventMenu.keys[row.eventId] === key,
+  )?.label ?? key;
+}
+
+/**
+ * @brief Runs one dedicated notification event submenu.
+ * @details Reuses the shared settings-menu renderer to toggle completed/interrupted/failed delivery flags, preserve row focus, and apply submenu-scoped reset semantics for command-notify, sound, or Pushover events. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
+ * @param[in] ctx {ExtensionCommandContext} Active command context.
+ * @param[in,out] config {UseReqConfig} Mutable configuration object.
+ * @param[in] eventMenu {PiNotifyEventMenuDefinition} Notification-system event submenu contract.
+ * @return {Promise<void>} Promise resolved when the submenu closes.
+ * @satisfies REQ-188, REQ-192, REQ-193, REQ-195, REQ-198
+ */
+async function configurePiNotifyEventMenu(
+  ctx: ExtensionCommandContext,
+  config: UseReqConfig,
+  eventMenu: PiNotifyEventMenuDefinition,
+): Promise<void> {
+  let focusedChoiceId: string | undefined;
+  while (true) {
+    const choice = await showPiUsereqSettingsMenu(
+      ctx,
+      eventMenu.submenuTitle,
+      buildPiNotifyEventMenuChoices(config, eventMenu),
+      { initialSelectedId: focusedChoiceId },
+    );
+    if (!choice || choice === "save-and-close") {
+      return;
+    }
+    focusedChoiceId = choice;
+    if (choice === "reset-defaults") {
+      resetPiNotifyEventMenuToDefaults(config, eventMenu);
+      ctx.ui.notify(
+        `Restored default ${eventMenu.systemLabel.toLowerCase()} events`,
+        "info",
+      );
+      continue;
+    }
+    const enabled = togglePiNotifyFlag(
+      config,
+      choice as PiNotifyEventBooleanConfigKey,
+    );
+    const eventLabel = resolvePiNotifyEventLabel(
+      choice as PiNotifyEventBooleanConfigKey,
+      eventMenu,
+    );
+    ctx.ui.notify(
+      `${eventMenu.systemLabel} ${eventLabel} ${enabled ? "enabled" : "disabled"}`,
+      "info",
+    );
+  }
+}
+
+/**
+ * @brief Builds the direct Pushover rows rendered inside `Notifications`.
+ * @details Serializes the global enable flag, shared-event submenu launcher, priority, title, text, and credential rows into right-valued menu items appended after the sound-command rows. Runtime is O(1). No external state is mutated.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @return {PiUsereqSettingsMenuChoice[]} Ordered direct Pushover rows.
+ * @satisfies REQ-163, REQ-165, REQ-172, REQ-184, REQ-185, REQ-198
+ */
+function buildPiNotifyPushoverRows(config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
+  return [
     {
-      id: "pushover-on-success",
-      label: "Notify on success",
+      id: "notify-pushover-enabled",
+      label: "Enable pushover",
       value: formatPiNotifyPushoverStatus(config),
-      description: "Toggle Pushover delivery after successful prompt completion only.",
+      description: "Enable or disable all Pushover delivery globally.",
     },
+    buildPiNotifyEventLauncherChoice(
+      config,
+      PI_NOTIFY_EVENT_MENU_DEFINITIONS.pushover,
+    ),
     {
-      id: "pushover-user-key",
-      label: "User Key/Delivery Group Key",
-      value: config["notify-pushover-user-key"] || "(empty)",
-      description: "Edit the Pushover user key or delivery group key sent with successful prompt notifications.",
+      id: "notify-pushover-priority",
+      label: "Pushover priority",
+      value: formatPiNotifyPushoverPriority(config["notify-pushover-priority"]),
+      description: "Select whether outbound Pushover messages use Normal or High priority.",
     },
     {
-      id: "pushover-api-token",
-      label: "Token/API Token Key",
-      value: config["notify-pushover-api-token"] || "(empty)",
-      description: "Edit the Pushover application token used for successful prompt notifications.",
+      id: "notify-pushover-title",
+      label: "Pushover title",
+      value: config["notify-pushover-title"],
+      description: "Edit the title template used for outbound Pushover messages.",
     },
     {
-      id: "pushover-priority",
-      label: "Priority",
-      value: formatPiNotifyPushoverPriority(config["notify-pushover-priority"]),
-      description: "Select whether successful prompt notifications use normal or high Pushover priority.",
+      id: "notify-pushover-text",
+      label: "Pushover text",
+      value: config["notify-pushover-text"],
+      description: "Edit the text template used for outbound Pushover messages.",
     },
     {
-      id: "back",
-      label: "Back",
-      value: "",
-      description: "Return to the notifications menu.",
+      id: "notify-pushover-user-key",
+      label: "Pushover User Key/Delivery Group Key",
+      value: config["notify-pushover-user-key"] || "(empty)",
+      description: "Edit the Pushover user key or delivery group key used for outbound requests.",
+    },
+    {
+      id: "notify-pushover-api-token",
+      label: "Pushover Token/API Token Key",
+      value: config["notify-pushover-api-token"] || "(empty)",
+      description: "Edit the Pushover application token used for outbound requests.",
     },
   ];
 }
 
 /**
  * @brief Opens the shared settings-menu selector for Pushover priority.
- * @details Reuses the pi-usereq settings-menu renderer so Pushover priority selection remains stylistically aligned with the existing notification menus and returns the chosen priority or `undefined` on cancel. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
+ * @details Reuses the pi-usereq settings-menu renderer so Pushover priority selection remains stylistically aligned with the notification menus and returns the chosen priority or `undefined` on cancel. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in] currentPriority {PiNotifyPushoverPriority} Persisted priority value.
  * @return {Promise<PiNotifyPushoverPriority | undefined>} Selected priority or `undefined` when cancelled.
- * @satisfies REQ-165
+ * @satisfies REQ-172, REQ-192
  */
 async function selectPiNotifyPushoverPriority(
   ctx: ExtensionCommandContext,
@@ -765,148 +1064,92 @@ async function selectPiNotifyPushoverPriority(
   const choice = await showPiUsereqSettingsMenu(ctx, "Pushover priority", [
     {
       id: "0",
-      label: "0=Normal",
+      label: "Normal",
       value: currentPriority === 0 ? "selected" : "",
-      description: "Send successful prompt notifications with normal Pushover priority.",
+      description: "Send outbound Pushover messages with normal priority `0`.",
     },
     {
       id: "1",
-      label: "1=High Priority",
+      label: "High",
       value: currentPriority === 1 ? "selected" : "",
-      description: "Send successful prompt notifications with high Pushover priority.",
+      description: "Send outbound Pushover messages with high priority `1`.",
     },
-  ]);
+  ], { initialSelectedId: String(currentPriority) });
   if (!choice) {
     return undefined;
   }
   return normalizePiNotifyPushoverPriority(choice);
 }
 
-/**
- * @brief Runs the interactive Pushover-configuration menu.
- * @details Exposes the Pushover global-disable flag, successful-completion enable flag, user key, API token, and priority selector through the shared settings-menu renderer. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
- * @param[in] ctx {ExtensionCommandContext} Active command context.
- * @param[in,out] config {UseReqConfig} Mutable configuration object.
- * @return {Promise<void>} Promise resolved when the menu closes.
- * @satisfies REQ-163, REQ-165, REQ-166, REQ-172
- */
-async function configurePiNotifyPushoverMenu(
-  ctx: ExtensionCommandContext,
-  config: UseReqConfig,
-): Promise<void> {
-  while (true) {
-    const choice = await showPiUsereqSettingsMenu(ctx, "Pushover notifications", buildPiNotifyPushoverMenuChoices(config));
-    if (!choice || choice === "back") {
-      return;
-    }
-    if (choice === "pushover-global-disable") {
-      config["notify-pushover-global-disable"] = !config["notify-pushover-global-disable"];
-      ctx.ui.notify(`Pushover global disable ${config["notify-pushover-global-disable"] ? "enabled" : "disabled"}`, "info");
-      continue;
-    }
-    if (choice === "pushover-on-success") {
-      config["notify-pushover-on-success"] = !config["notify-pushover-on-success"];
-      ctx.ui.notify(`Pushover on success ${config["notify-pushover-on-success"] ? "enabled" : "disabled"}`, "info");
-      continue;
-    }
-    if (choice === "pushover-user-key") {
-      const value = await ctx.ui.input(
-        "User Key/Delivery Group Key",
-        config["notify-pushover-user-key"] || "gzfjjvp1xxmhibqwzh9m7i1zwvf83j",
-      );
-      if (value !== undefined) {
-        config["notify-pushover-user-key"] = normalizePiNotifyPushoverCredential(value);
-        ctx.ui.notify("Updated Pushover user key", "info");
-      }
-      continue;
-    }
-    if (choice === "pushover-api-token") {
-      const value = await ctx.ui.input(
-        "Token/API Token Key",
-        config["notify-pushover-api-token"] || "ah6bf5u2sj63mcvou6qamiabeoubbe",
-      );
-      if (value !== undefined) {
-        config["notify-pushover-api-token"] = normalizePiNotifyPushoverCredential(value);
-        ctx.ui.notify("Updated Pushover API token", "info");
-      }
-      continue;
-    }
-    if (choice === "pushover-priority") {
-      const nextPriority = await selectPiNotifyPushoverPriority(ctx, config["notify-pushover-priority"]);
-      if (nextPriority !== undefined) {
-        config["notify-pushover-priority"] = nextPriority;
-        ctx.ui.notify(`Pushover priority set to ${formatPiNotifyPushoverPriority(nextPriority)}`, "info");
-      }
-    }
-  }
-}
-
 /**
  * @brief Builds the shared settings-menu choices for notification configuration.
- * @details Serializes the current beep flags, selected notify command, hotkey bind, per-level notify commands, and the Pushover submenu entry into right-valued menu rows consumed by the shared settings-menu renderer. Runtime is O(1) plus command-length formatting. No external state is mutated.
+ * @details Serializes command-notify, sound, and Pushover blocks with dedicated shared-event submenu launchers so the settings-menu renderer can expose one unified but modular configuration surface. Runtime is O(1) plus command-length formatting. No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered notification-menu choice vector.
- * @satisfies REQ-137, REQ-149, REQ-150, REQ-151, REQ-152, REQ-163, REQ-164, REQ-165, REQ-166, REQ-172
+ * @satisfies REQ-137, REQ-149, REQ-150, REQ-151, REQ-152, REQ-163, REQ-164, REQ-165, REQ-172, REQ-179, REQ-181, REQ-183, REQ-188, REQ-193, REQ-198
  */
 function buildPiNotifyMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
   return [
     {
-      id: "toggle-beep-on-success",
-      label: "Toggle beep on success",
-      value: config["notify-beep-on-end"] ? "on" : "off",
-      description: "Toggle terminal beep delivery for successful prompt completion.",
-    },
-    {
-      id: "toggle-beep-on-escape",
-      label: "Toggle beep on escape",
-      value: config["notify-beep-on-esc"] ? "on" : "off",
-      description: "Toggle terminal beep delivery for escape-triggered prompt abortion.",
+      id: "notify-enabled",
+      label: "Enable notification",
+      value: formatPiNotifyStatus(config),
+      description: "Enable or disable command-notify delivery globally.",
     },
+    buildPiNotifyEventLauncherChoice(
+      config,
+      PI_NOTIFY_EVENT_MENU_DEFINITIONS.notification,
+    ),
     {
-      id: "toggle-beep-on-error",
-      label: "Toggle beep on error",
-      value: config["notify-beep-on-error"] ? "on" : "off",
-      description: "Toggle terminal beep delivery for error-terminated prompt completion.",
+      id: "notify-command",
+      label: "Notify command",
+      value: config.PI_NOTIFY_CMD,
+      description: "Edit the shell command used for command-notify delivery.",
     },
     {
-      id: "selected-notify-command",
-      label: "Selected notify command",
+      id: "selected-sound-command",
+      label: "Enable sound",
       value: config["notify-sound"],
-      description: "Select which notify command runs after successful prompt completion.",
+      description: "Select which sound command level is currently active.",
     },
+    buildPiNotifyEventLauncherChoice(
+      config,
+      PI_NOTIFY_EVENT_MENU_DEFINITIONS.sound,
+    ),
     {
       id: "sound-toggle-hotkey-bind",
       label: "Sound toggle hotkey bind",
       value: config["notify-sound-toggle-shortcut"],
-      description: "Edit the keyboard shortcut that cycles the selected notify command.",
+      description: "Edit the keyboard shortcut that cycles the selected sound command.",
     },
     {
-      id: "notify-command-low",
-      label: "Notify command (low vol.)",
+      id: "sound-command-low",
+      label: "Sound command (low vol.)",
       value: config.PI_NOTIFY_SOUND_LOW_CMD,
-      description: "Edit the shell command used when the selected notify command is `low`.",
+      description: "Edit the shell command used when the selected sound command is `low`.",
     },
     {
-      id: "notify-command-mid",
-      label: "Notify command (mid vol.)",
+      id: "sound-command-mid",
+      label: "Sound command (mid vol.)",
       value: config.PI_NOTIFY_SOUND_MID_CMD,
-      description: "Edit the shell command used when the selected notify command is `mid`.",
+      description: "Edit the shell command used when the selected sound command is `mid`.",
     },
     {
-      id: "notify-command-high",
-      label: "Notify command (high vol.)",
+      id: "sound-command-high",
+      label: "Sound command (high vol.)",
       value: config.PI_NOTIFY_SOUND_HIGH_CMD,
-      description: "Edit the shell command used when the selected notify command is `high`.",
+      description: "Edit the shell command used when the selected sound command is `high`.",
     },
+    ...buildPiNotifyPushoverRows(config),
     {
-      id: "pushover-notifications",
-      label: "Pushover notifications",
-      value: formatPiNotifyPushoverStatus(config),
-      description: "Open the Pushover submenu for successful-completion delivery, credentials, priority, and global disable.",
+      id: "reset-defaults",
+      label: "Reset defaults",
+      value: "",
+      description: "Restore the documented notification defaults for command-notify, sound, and Pushover settings.",
     },
     {
-      id: "back",
-      label: "Back",
+      id: "save-and-close",
+      label: "Save and close",
       value: "",
       description: "Return to the parent configuration menu.",
     },
@@ -914,127 +1157,229 @@ function buildPiNotifyMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuCho
 }
 
 /**
- * @brief Opens the shared settings-menu selector for the selected notify command.
- * @details Reuses the pi-usereq settings-menu renderer so notify-command selection remains stylistically aligned with the main configuration UI and returns the chosen sound level or `undefined` on cancel. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
+ * @brief Opens the shared settings-menu selector for the active sound level.
+ * @details Reuses the pi-usereq settings-menu renderer so sound-level selection remains stylistically aligned with the notification menu and returns the chosen sound level or `undefined` on cancel. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
- * @param[in] currentLevel {PiNotifySoundLevel} Currently selected notify command.
+ * @param[in] currentLevel {PiNotifySoundLevel} Currently selected sound level.
  * @return {Promise<PiNotifySoundLevel | undefined>} Selected sound level or `undefined` when cancelled.
- * @satisfies REQ-131, REQ-137, REQ-149, REQ-151, REQ-152, REQ-153, REQ-154
+ * @satisfies REQ-131, REQ-179, REQ-192
  */
 async function selectPiNotifySoundLevel(
   ctx: ExtensionCommandContext,
   currentLevel: PiNotifySoundLevel,
 ): Promise<PiNotifySoundLevel | undefined> {
-  const choice = await showPiUsereqSettingsMenu(ctx, "Selected notify command", [
+  const choice = await showPiUsereqSettingsMenu(ctx, "Enable sound", [
     {
       id: "none",
       label: "none",
       value: currentLevel === "none" ? "selected" : "",
-      description: "Disable external notify-command execution.",
+      description: "Disable sound-command delivery while preserving per-event sound toggles.",
     },
     {
       id: "low",
       label: "low",
       value: currentLevel === "low" ? "selected" : "",
-      description: "Run the low-volume notify command after successful completion.",
+      description: "Use the low-volume sound command when sound delivery is enabled for the current event.",
     },
     {
       id: "mid",
       label: "mid",
       value: currentLevel === "mid" ? "selected" : "",
-      description: "Run the mid-volume notify command after successful completion.",
+      description: "Use the mid-volume sound command when sound delivery is enabled for the current event.",
     },
     {
       id: "high",
       label: "high",
       value: currentLevel === "high" ? "selected" : "",
-      description: "Run the high-volume notify command after successful completion.",
+      description: "Use the high-volume sound command when sound delivery is enabled for the current event.",
     },
-  ]);
+  ], { initialSelectedId: currentLevel });
   return choice ? choice as PiNotifySoundLevel : undefined;
 }
 
 /**
  * @brief Runs the interactive notification-configuration menu.
- * @details Exposes prompt-end beep toggles, selected notify-command selection, hotkey-bind editing, per-level notify-command editors, and the nested Pushover submenu through the shared settings-menu renderer. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
+ * @details Exposes command-notify, sound, and Pushover controls through the shared settings-menu renderer, delegates completed/interrupted/failed toggles to dedicated event submenus, and preserves row focus across menu re-renders. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in,out] config {UseReqConfig} Mutable configuration object.
  * @return {Promise<boolean>} `true` when the sound-toggle shortcut changed.
- * @satisfies REQ-129, REQ-131, REQ-133, REQ-134, REQ-137, REQ-149, REQ-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-163, REQ-164, REQ-165, REQ-166, REQ-172
+ * @satisfies REQ-131, REQ-133, REQ-134, REQ-137, REQ-163, REQ-164, REQ-165, REQ-172, REQ-179, REQ-181, REQ-183, REQ-184, REQ-188, REQ-192, REQ-193, REQ-195, REQ-196, REQ-198
  */
 async function configurePiNotifyMenu(
   ctx: ExtensionCommandContext,
   config: UseReqConfig,
 ): Promise<boolean> {
   const originalShortcut = config["notify-sound-toggle-shortcut"];
+  let focusedChoiceId: string | undefined;
   while (true) {
-    const choice = await showPiUsereqSettingsMenu(ctx, "notifications", buildPiNotifyMenuChoices(config));
-    if (!choice || choice === "back") {
+    const choice = await showPiUsereqSettingsMenu(
+      ctx,
+      "Notifications",
+      buildPiNotifyMenuChoices(config),
+      { initialSelectedId: focusedChoiceId },
+    );
+    if (!choice || choice === "save-and-close") {
       return config["notify-sound-toggle-shortcut"] !== originalShortcut;
     }
-    if (choice === "toggle-beep-on-success") {
-      const enabled = togglePiNotifyBeepFlag(config, "notify-beep-on-end");
-      ctx.ui.notify(`Beep on success ${enabled ? "enabled" : "disabled"}`, "info");
+    focusedChoiceId = choice;
+    if (choice === "notify-enabled" || choice === "notify-pushover-enabled") {
+      const enabled = togglePiNotifyFlag(config, choice as PiNotifyBooleanConfigKey);
+      const labelMap: Record<string, string> = {
+        "notify-enabled": "Notification",
+        "notify-pushover-enabled": "Pushover",
+      };
+      ctx.ui.notify(`${labelMap[choice]} ${enabled ? "enabled" : "disabled"}`, "info");
+      continue;
+    }
+    if (choice === PI_NOTIFY_EVENT_MENU_DEFINITIONS.notification.topLevelId) {
+      await configurePiNotifyEventMenu(
+        ctx,
+        config,
+        PI_NOTIFY_EVENT_MENU_DEFINITIONS.notification,
+      );
       continue;
     }
-    if (choice === "toggle-beep-on-escape") {
-      const enabled = togglePiNotifyBeepFlag(config, "notify-beep-on-esc");
-      ctx.ui.notify(`Beep on escape ${enabled ? "enabled" : "disabled"}`, "info");
+    if (choice === PI_NOTIFY_EVENT_MENU_DEFINITIONS.sound.topLevelId) {
+      await configurePiNotifyEventMenu(
+        ctx,
+        config,
+        PI_NOTIFY_EVENT_MENU_DEFINITIONS.sound,
+      );
+      continue;
+    }
+    if (choice === PI_NOTIFY_EVENT_MENU_DEFINITIONS.pushover.topLevelId) {
+      await configurePiNotifyEventMenu(
+        ctx,
+        config,
+        PI_NOTIFY_EVENT_MENU_DEFINITIONS.pushover,
+      );
       continue;
     }
-    if (choice === "toggle-beep-on-error") {
-      const enabled = togglePiNotifyBeepFlag(config, "notify-beep-on-error");
-      ctx.ui.notify(`Beep on error ${enabled ? "enabled" : "disabled"}`, "info");
+    if (choice === "notify-command") {
+      const value = await ctx.ui.input("Notify command", config.PI_NOTIFY_CMD);
+      if (value !== undefined) {
+        config.PI_NOTIFY_CMD = normalizePiNotifyCommand(value, DEFAULT_PI_NOTIFY_CMD);
+        ctx.ui.notify("Updated notify command", "info");
+      }
       continue;
     }
-    if (choice === "selected-notify-command") {
+    if (choice === "selected-sound-command") {
       const nextLevel = await selectPiNotifySoundLevel(ctx, config["notify-sound"]);
-      if (nextLevel) {
+      if (nextLevel !== undefined) {
         config["notify-sound"] = nextLevel;
-        ctx.ui.notify(`Selected notify command set to ${nextLevel}`, "info");
+        ctx.ui.notify(`Enable sound set to ${nextLevel}`, "info");
       }
       continue;
     }
     if (choice === "sound-toggle-hotkey-bind") {
-      const value = await ctx.ui.input("Sound toggle hotkey bind", config["notify-sound-toggle-shortcut"]);
+      const value = await ctx.ui.input(
+        "Sound toggle hotkey bind",
+        config["notify-sound-toggle-shortcut"],
+      );
       if (value?.trim()) {
         config["notify-sound-toggle-shortcut"] = value.trim();
-        ctx.ui.notify(`Sound toggle hotkey bind set to ${config["notify-sound-toggle-shortcut"]}`, "info");
+        ctx.ui.notify(
+          `Sound toggle hotkey bind set to ${config["notify-sound-toggle-shortcut"]}`,
+          "info",
+        );
       }
       continue;
     }
-    if (choice === "notify-command-low") {
-      const value = await ctx.ui.input("Notify command (low vol.)", config.PI_NOTIFY_SOUND_LOW_CMD);
-      if (value?.trim()) {
-        config.PI_NOTIFY_SOUND_LOW_CMD = value.trim();
-        ctx.ui.notify("Updated notify command (low vol.)", "info");
+    if (choice === "sound-command-low") {
+      const value = await ctx.ui.input("Sound command (low vol.)", config.PI_NOTIFY_SOUND_LOW_CMD);
+      if (value !== undefined) {
+        config.PI_NOTIFY_SOUND_LOW_CMD = normalizePiNotifyCommand(
+          value,
+          DEFAULT_PI_NOTIFY_SOUND_LOW_CMD,
+        );
+        ctx.ui.notify("Updated sound command (low vol.)", "info");
       }
       continue;
     }
-    if (choice === "notify-command-mid") {
-      const value = await ctx.ui.input("Notify command (mid vol.)", config.PI_NOTIFY_SOUND_MID_CMD);
-      if (value?.trim()) {
-        config.PI_NOTIFY_SOUND_MID_CMD = value.trim();
-        ctx.ui.notify("Updated notify command (mid vol.)", "info");
+    if (choice === "sound-command-mid") {
+      const value = await ctx.ui.input("Sound command (mid vol.)", config.PI_NOTIFY_SOUND_MID_CMD);
+      if (value !== undefined) {
+        config.PI_NOTIFY_SOUND_MID_CMD = normalizePiNotifyCommand(
+          value,
+          DEFAULT_PI_NOTIFY_SOUND_MID_CMD,
+        );
+        ctx.ui.notify("Updated sound command (mid vol.)", "info");
       }
       continue;
     }
-    if (choice === "notify-command-high") {
-      const value = await ctx.ui.input("Notify command (high vol.)", config.PI_NOTIFY_SOUND_HIGH_CMD);
-      if (value?.trim()) {
-        config.PI_NOTIFY_SOUND_HIGH_CMD = value.trim();
-        ctx.ui.notify("Updated notify command (high vol.)", "info");
+    if (choice === "sound-command-high") {
+      const value = await ctx.ui.input("Sound command (high vol.)", config.PI_NOTIFY_SOUND_HIGH_CMD);
+      if (value !== undefined) {
+        config.PI_NOTIFY_SOUND_HIGH_CMD = normalizePiNotifyCommand(
+          value,
+          DEFAULT_PI_NOTIFY_SOUND_HIGH_CMD,
+        );
+        ctx.ui.notify("Updated sound command (high vol.)", "info");
       }
       continue;
     }
-    if (choice === "pushover-notifications") {
-      await configurePiNotifyPushoverMenu(ctx, config);
+    if (choice === "notify-pushover-priority") {
+      const nextPriority = await selectPiNotifyPushoverPriority(ctx, config["notify-pushover-priority"]);
+      if (nextPriority !== undefined) {
+        config["notify-pushover-priority"] = nextPriority;
+        ctx.ui.notify(`Pushover priority set to ${formatPiNotifyPushoverPriority(nextPriority)}`, "info");
+      }
+      continue;
+    }
+    if (choice === "notify-pushover-title") {
+      const value = await ctx.ui.input("Pushover title", config["notify-pushover-title"]);
+      if (value !== undefined) {
+        config["notify-pushover-title"] = normalizePiNotifyTemplateValue(
+          value,
+          DEFAULT_PI_NOTIFY_PUSHOVER_TITLE,
+        );
+        ctx.ui.notify("Updated Pushover title", "info");
+      }
+      continue;
+    }
+    if (choice === "notify-pushover-text") {
+      const value = await ctx.ui.input("Pushover text", config["notify-pushover-text"]);
+      if (value !== undefined) {
+        config["notify-pushover-text"] = normalizePiNotifyTemplateValue(
+          value,
+          DEFAULT_PI_NOTIFY_PUSHOVER_TEXT,
+        );
+        ctx.ui.notify("Updated Pushover text", "info");
+      }
+      continue;
+    }
+    if (choice === "notify-pushover-user-key") {
+      const value = await ctx.ui.input(
+        "Pushover User Key/Delivery Group Key",
+        config["notify-pushover-user-key"],
+      );
+      if (value !== undefined) {
+        config["notify-pushover-user-key"] = normalizePiNotifyPushoverCredential(value);
+        ctx.ui.notify("Updated Pushover user key", "info");
+      }
+      continue;
+    }
+    if (choice === "notify-pushover-api-token") {
+      const value = await ctx.ui.input(
+        "Pushover Token/API Token Key",
+        config["notify-pushover-api-token"],
+      );
+      if (value !== undefined) {
+        config["notify-pushover-api-token"] = normalizePiNotifyPushoverCredential(value);
+        ctx.ui.notify("Updated Pushover API token", "info");
+      }
+      continue;
+    }
+    if (choice === "reset-defaults") {
+      resetPiNotifyConfigToDefaults(config);
+      ctx.ui.notify("Restored notification defaults", "info");
+      continue;
     }
   }
 }
 
 /**
- * @brief Registers the configurable successful-run sound shortcut when supported.
+ * @brief Registers the configurable notification-sound shortcut when supported.
  * @details Loads the current project config, registers one raw pi shortcut when
  * the runtime exposes `registerShortcut(...)`, cycles persisted sound state on
  * invocation, saves the config, refreshes the status bar, and emits one info
@@ -1044,7 +1389,7 @@ async function configurePiNotifyMenu(
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @return {void} No return value.
- * @satisfies REQ-131, REQ-134, REQ-136
+ * @satisfies REQ-131, REQ-134, REQ-180
  */
 function registerPiNotifyShortcut(
   pi: ExtensionAPI,
@@ -1056,7 +1401,7 @@ function registerPiNotifyShortcut(
   }
   const config = loadProjectConfig(process.cwd());
   shortcutRegistrar.registerShortcut(config["notify-sound-toggle-shortcut"], {
-    description: "Cycle pi-usereq prompt-success sound level",
+    description: "Cycle pi-usereq notification sound level",
     handler: async (ctx) => {
       const nextConfig = loadProjectConfig(ctx.cwd);
       nextConfig["notify-sound"] = cyclePiNotifySoundLevel(nextConfig["notify-sound"]);
@@ -1221,14 +1566,18 @@ function registerAgentTools(pi: ExtensionAPI): void {
     ],
     parameters: filesTokensSchema,
     async execute(_toolCallId, params) {
-      const payload = buildTokenToolPayload({
-        toolName: "files-tokens",
-        scope: "explicit-files",
-        baseDir: process.cwd(),
-        requestedPaths: params.files,
-        encodingName: TOKEN_COUNTER_ENCODING,
-      });
-      return buildTokenToolExecuteResult(payload);
+      try {
+        const payload = buildTokenToolPayload({
+          toolName: "files-tokens",
+          scope: "explicit-files",
+          baseDir: process.cwd(),
+          requestedPaths: params.files,
+          encodingName: TOKEN_COUNTER_ENCODING,
+        });
+        return buildTokenToolExecuteResult(payload);
+      } catch (error) {
+        return buildFailedTokenToolExecuteResult(error);
+      }
     },
   });
 
@@ -1453,20 +1802,24 @@ function registerAgentTools(pi: ExtensionAPI): void {
     ],
     parameters: tokensSchema,
     async execute() {
-      const projectBase = getProjectBase(process.cwd());
-      const config = loadProjectConfig(process.cwd());
-      const docsDir = config["docs-dir"].replace(/[/\\]+$/, "");
-      const canonicalDocNames = ["REQUIREMENTS.md", "WORKFLOW.md", "REFERENCES.md"];
-      const payload = buildTokenToolPayload({
-        toolName: "tokens",
-        scope: "canonical-docs",
-        baseDir: projectBase,
-        requestedPaths: canonicalDocNames.map((name) => path.join(docsDir, name)),
-        docsDir,
-        canonicalDocNames,
-        encodingName: TOKEN_COUNTER_ENCODING,
-      });
-      return buildTokenToolExecuteResult(payload);
+      try {
+        const projectBase = getProjectBase(process.cwd());
+        const config = loadProjectConfig(process.cwd());
+        const docsDir = config["docs-dir"].replace(/[/\\]+$/, "");
+        const canonicalDocNames = ["REQUIREMENTS.md", "WORKFLOW.md", "REFERENCES.md"];
+        const payload = buildTokenToolPayload({
+          toolName: "tokens",
+          scope: "canonical-docs",
+          baseDir: projectBase,
+          requestedPaths: canonicalDocNames.map((name) => path.join(docsDir, name)),
+          docsDir,
+          canonicalDocNames,
+          encodingName: TOKEN_COUNTER_ENCODING,
+        });
+        return buildTokenToolExecuteResult(payload);
+      } catch (error) {
+        return buildFailedTokenToolExecuteResult(error);
+      }
     },
   });
 
@@ -1728,26 +2081,20 @@ function registerAgentTools(pi: ExtensionAPI): void {
 
 /**
  * @brief Builds the shared settings-menu choices for startup-tool management.
- * @details Serializes startup-tool actions into right-valued menu rows consumed by the shared settings-menu renderer. Runtime is O(t) in configurable-tool count. No external state is mutated.
+ * @details Serializes startup-tool actions into right-valued menu rows consumed by the shared settings-menu renderer while omitting the removed status-reference action. Runtime is O(t) in configurable-tool count. No external state is mutated.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered startup-tool menu choices.
- * @satisfies REQ-007, REQ-151, REQ-152, REQ-153, REQ-154
+ * @satisfies REQ-007, REQ-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-193
  */
 function buildPiUsereqToolsMenuChoices(pi: ExtensionAPI, config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
   const tools = getPiUsereqStartupTools(pi);
   return [
     {
-      id: "show-tool-status",
-      label: "Show tool status",
-      value: `${getConfiguredEnabledPiUsereqTools(config).length}/${tools.length} enabled`,
-      description: "Open the full startup-tool reference report in the editor.",
-    },
-    {
-      id: "toggle-tool",
-      label: "Toggle tool",
+      id: "enable-tools",
+      label: "Enable tools",
       value: `${getConfiguredEnabledPiUsereqTools(config).length} enabled`,
-      description: "Open the per-tool toggle menu for configurable startup tools.",
+      description: "Open the per-tool enablement menu for configurable startup tools.",
     },
     {
       id: "enable-all-tools",
@@ -1762,14 +2109,14 @@ function buildPiUsereqToolsMenuChoices(pi: ExtensionAPI, config: UseReqConfig):
       description: "Disable every configurable startup tool for future session starts.",
     },
     {
-      id: "reset-tool-defaults",
-      label: "Reset configurable-tool defaults",
+      id: "reset-defaults",
+      label: "Reset defaults",
       value: `${normalizeEnabledPiUsereqTools(undefined).length} defaults`,
       description: "Restore the documented default startup-tool selection.",
     },
     {
-      id: "back",
-      label: "Back",
+      id: "save-and-close",
+      label: "Save and close",
       value: "",
       description: "Return to the parent configuration menu.",
     },
@@ -1797,7 +2144,7 @@ function buildPiUsereqToolToggleChoices(pi: ExtensionAPI, config: UseReqConfig):
       id: "back",
       label: "Back",
       value: "",
-      description: "Return to the startup-tools menu.",
+      description: "Return to the Enable tools menu.",
     },
   ];
 }
@@ -1809,23 +2156,22 @@ function buildPiUsereqToolToggleChoices(pi: ExtensionAPI, config: UseReqConfig):
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in,out] config {UseReqConfig} Mutable configuration object.
  * @return {Promise<void>} Promise resolved when the menu closes.
- * @satisfies REQ-007, REQ-063, REQ-064, REQ-151, REQ-152, REQ-153, REQ-154
+ * @satisfies REQ-007, REQ-063, REQ-064, REQ-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-193
  */
 async function configurePiUsereqToolsMenu(pi: ExtensionAPI, ctx: ExtensionCommandContext, config: UseReqConfig): Promise<void> {
   applyConfiguredPiUsereqTools(pi, config);
+  let focusedChoiceId: string | undefined;
   while (true) {
     const tools = getPiUsereqStartupTools(pi);
     const enabledTools = new Set(getConfiguredEnabledPiUsereqTools(config));
-    const choice = await showPiUsereqSettingsMenu(ctx, "startup tools", buildPiUsereqToolsMenuChoices(pi, config));
+    const choice = await showPiUsereqSettingsMenu(ctx, "Enable tools", buildPiUsereqToolsMenuChoices(pi, config), {
+      initialSelectedId: focusedChoiceId,
+    });
 
-    if (!choice || choice === "back") {
+    if (!choice || choice === "save-and-close") {
       return;
     }
-
-    if (choice === "show-tool-status") {
-      ctx.ui.setEditorText(renderPiUsereqToolsReference(pi, config));
-      continue;
-    }
+    focusedChoiceId = choice;
 
     if (choice === "enable-all-tools") {
       setConfiguredPiUsereqTools(pi, config, tools.map((tool) => tool.name));
@@ -1839,14 +2185,14 @@ async function configurePiUsereqToolsMenu(pi: ExtensionAPI, ctx: ExtensionComman
       continue;
     }
 
-    if (choice === "reset-tool-defaults") {
+    if (choice === "reset-defaults") {
       setConfiguredPiUsereqTools(pi, config, normalizeEnabledPiUsereqTools(undefined));
       ctx.ui.notify("Restored default configurable active tools", "info");
       continue;
     }
 
-    if (choice === "toggle-tool") {
-      const selectedToolName = await showPiUsereqSettingsMenu(ctx, "toggle startup tool", buildPiUsereqToolToggleChoices(pi, config));
+    if (choice === "enable-tools") {
+      const selectedToolName = await showPiUsereqSettingsMenu(ctx, "Enable tools", buildPiUsereqToolToggleChoices(pi, config));
       if (!selectedToolName || selectedToolName === "back") {
         continue;
       }
@@ -1864,20 +2210,6 @@ async function configurePiUsereqToolsMenu(pi: ExtensionAPI, ctx: ExtensionComman
   }
 }
 
-/**
- * @brief Formats one static-check configuration entry for UI display.
- * @details Renders command-backed entries as `Command(cmd args...)` and all other modules as `Module(args...)`. Runtime is O(n) in parameter count. No side effects occur.
- * @param[in] entry {StaticCheckEntry} Static-check configuration entry.
- * @return {string} Human-readable entry summary.
- */
-function formatStaticCheckEntry(entry: StaticCheckEntry): string {
-  const params = Array.isArray(entry.params) && entry.params.length > 0 ? ` ${entry.params.join(" ")}` : "";
-  if (entry.module === "Command") {
-    return `${entry.module}(${entry.cmd ?? "?"}${params})`;
-  }
-  return `${entry.module}${params ? `(${entry.params!.join(" ")})` : ""}`;
-}
-
 /**
  * @brief Summarizes configured static-check languages.
  * @details Keeps only languages with at least one configured checker, sorts them, and emits a compact `Language (count)` list. Runtime is O(l log l). No side effects occur.
@@ -1892,80 +2224,38 @@ function formatStaticCheckLanguagesSummary(config: UseReqConfig): string {
   return languages.join(", ") || "(none)";
 }
 
-/**
- * @brief Renders the static-check configuration reference view.
- * @details Produces a markdown-like summary containing configured entries, supported languages, the Command-only user module surface, and canonical example specifications. Runtime is O(l log l). No side effects occur.
- * @param[in] config {UseReqConfig} Effective project configuration.
- * @return {string} Reference text for the editor view.
- */
-function renderStaticCheckReference(config: UseReqConfig): string {
-  const lines = ["# Static-check configuration", "", `Configured languages: ${formatStaticCheckLanguagesSummary(config)}`, ""];
-  const configuredLanguages = Object.entries(config["static-check"])
-    .filter(([, entries]) => Array.isArray(entries) && entries.length > 0)
-    .sort(([left], [right]) => left.localeCompare(right));
-
-  if (configuredLanguages.length === 0) {
-    lines.push("Configured entries: (none)");
-  } else {
-    lines.push("Configured entries:");
-    for (const [language, entries] of configuredLanguages) {
-      lines.push(`- ${language}: ${(entries as StaticCheckEntry[]).map(formatStaticCheckEntry).join(", ")}`);
-    }
-  }
-
-  lines.push("", "Supported languages:");
-  for (const { language, extensions } of getSupportedStaticCheckLanguageSupport()) {
-    lines.push(`- ${language}: ${extensions.join(", ")}`);
-  }
-  lines.push(
-    "",
-    `Supported modules: ${STATIC_CHECK_MODULES.join(", ")}`,
-    "",
-    "Examples:",
-    "- Python=Command,mypy,--strict",
-    "- TypeScript=Command,eslint,--max-warnings,0",
-  );
-  return `${lines.join("\n")}\n`;
-}
-
 /**
  * @brief Builds the shared settings-menu choices for static-check management.
- * @details Serializes Command-oriented static-check actions into right-valued menu rows consumed by the shared settings-menu renderer while omitting user-facing module selection. Runtime is O(1). No external state is mutated.
+ * @details Serializes guided Command-oriented static-check actions into right-valued menu rows consumed by the shared settings-menu renderer while omitting raw-spec and reference-only actions. Runtime is O(1). No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered static-check menu choices.
- * @satisfies REQ-008, REQ-160, REQ-161, REQ-151, REQ-152, REQ-153, REQ-154
+ * @satisfies REQ-008, REQ-150, REQ-160, REQ-161, REQ-151, REQ-152, REQ-153, REQ-154, REQ-193
  */
 function buildStaticCheckMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
   const supportedLanguageCount = getSupportedStaticCheckLanguageSupport().length;
   const configuredLanguageCount = Object.values(config["static-check"]).filter((entries) => entries.length > 0).length;
   return [
     {
-      id: "add-entry-supported-language",
-      label: "Add entry for supported language",
+      id: "add-static-check-entry",
+      label: "Add static code checker",
       value: `${supportedLanguageCount} languages`,
-      description: "Select a supported language, then configure the Command static-check executable.",
-    },
-    {
-      id: "add-entry-raw-spec",
-      label: "Add entry from LANG=MODULE[,CMD[,PARAM...]]",
-      value: "raw spec",
-      description: "Enter one raw Command-based static-check specification string in canonical CLI format.",
+      description: "Select a supported language, then configure one Command static-check executable.",
     },
     {
-      id: "remove-language-entry",
-      label: "Remove language entry",
+      id: "remove-static-check-entry",
+      label: "Remove static code checker",
       value: configuredLanguageCount > 0 ? `${configuredLanguageCount} configured` : "(none)",
       description: "Remove every configured static-check entry for one language.",
     },
     {
-      id: "show-supported-languages",
-      label: "Show supported languages",
-      value: `${supportedLanguageCount} languages`,
-      description: "Open the static-check reference report in the editor.",
+      id: "reset-defaults",
+      label: "Reset defaults",
+      value: configuredLanguageCount > 0 ? `${configuredLanguageCount} configured` : "(none)",
+      description: "Remove every configured static-check entry and restore the default empty static-check configuration.",
     },
     {
-      id: "back",
-      label: "Back",
+      id: "save-and-close",
+      label: "Save and close",
       value: "",
       description: "Return to the parent configuration menu.",
     },
@@ -1994,7 +2284,7 @@ function buildSupportedStaticCheckLanguageChoices(config: UseReqConfig): PiUsere
       id: "back",
       label: "Back",
       value: "",
-      description: "Return to the static-check menu.",
+      description: "Return to the Language static code checkers menu.",
     },
   ];
 }
@@ -2019,33 +2309,32 @@ function buildConfiguredStaticCheckLanguageChoices(config: UseReqConfig): PiUser
       id: "back",
       label: "Back",
       value: "",
-      description: "Return to the static-check menu.",
+      description: "Return to the Language static code checkers menu.",
     },
   ];
 }
 
 /**
  * @brief Runs the interactive static-check configuration menu.
- * @details Lets the user inspect support, add Command entries by guided prompts or raw spec strings, and remove configured language entries through the shared settings-menu renderer until the user exits. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
+ * @details Lets the user add Command entries by guided prompts, remove configured language entries, and reset the static-check configuration through the shared settings-menu renderer until the user exits. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in,out] config {UseReqConfig} Mutable configuration object.
  * @return {Promise<void>} Promise resolved when the menu closes.
- * @satisfies REQ-008, REQ-160, REQ-161, REQ-151, REQ-152, REQ-153, REQ-154
+ * @satisfies REQ-008, REQ-150, REQ-160, REQ-161, REQ-151, REQ-152, REQ-153, REQ-154, REQ-193, REQ-195
  */
 async function configureStaticCheckMenu(ctx: ExtensionCommandContext, config: UseReqConfig): Promise<void> {
+  let focusedChoiceId: string | undefined;
   while (true) {
-    const staticChoice = await showPiUsereqSettingsMenu(ctx, "static-check", buildStaticCheckMenuChoices(config));
+    const staticChoice = await showPiUsereqSettingsMenu(ctx, "Language static code checkers", buildStaticCheckMenuChoices(config), {
+      initialSelectedId: focusedChoiceId,
+    });
 
-    if (!staticChoice || staticChoice === "back") {
+    if (!staticChoice || staticChoice === "save-and-close") {
       return;
     }
+    focusedChoiceId = staticChoice;
 
-    if (staticChoice === "show-supported-languages") {
-      ctx.ui.setEditorText(renderStaticCheckReference(config));
-      continue;
-    }
-
-    if (staticChoice === "add-entry-supported-language") {
+    if (staticChoice === "add-static-check-entry") {
       const selectedLanguage = await showPiUsereqSettingsMenu(ctx, "static-check language", buildSupportedStaticCheckLanguageChoices(config));
       if (!selectedLanguage || selectedLanguage === "back") {
         continue;
@@ -2073,29 +2362,18 @@ async function configureStaticCheckMenu(ctx: ExtensionCommandContext, config: Us
       continue;
     }
 
-    if (staticChoice === "add-entry-raw-spec") {
-      const spec = await ctx.ui.input("Static-check spec", "Python=Command,true");
-      if (!spec?.trim()) {
-        continue;
-      }
-      try {
-        const [canonicalLang, entry] = parseEnableStaticCheck(spec.trim());
-        config["static-check"][canonicalLang] ??= [];
-        config["static-check"][canonicalLang]!.push(entry);
-        ctx.ui.notify(`Added ${entry.module} checker for ${canonicalLang}`, "info");
-      } catch (error) {
-        ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
-      }
-      continue;
-    }
-
-    if (staticChoice === "remove-language-entry") {
-      const configuredLanguage = await showPiUsereqSettingsMenu(ctx, "remove static-check language", buildConfiguredStaticCheckLanguageChoices(config));
+    if (staticChoice === "remove-static-check-entry") {
+      const configuredLanguage = await showPiUsereqSettingsMenu(ctx, "Remove static code checker", buildConfiguredStaticCheckLanguageChoices(config));
       if (!configuredLanguage || configuredLanguage === "back") {
         continue;
       }
       delete config["static-check"][configuredLanguage];
       ctx.ui.notify(`Removed static-check entries for ${configuredLanguage}`, "info");
+      continue;
+    }
+    if (staticChoice === "reset-defaults") {
+      config["static-check"] = {};
+      ctx.ui.notify("Restored default static code checker configuration", "info");
     }
   }
 }
@@ -2106,7 +2384,7 @@ async function configureStaticCheckMenu(ctx: ExtensionCommandContext, config: Us
  * @param[in] cwd {string} Current working directory.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered top-level menu choices.
- * @satisfies REQ-006, REQ-031, REQ-137, REQ-150, REQ-151, REQ-152, REQ-162
+ * @satisfies REQ-006, REQ-031, REQ-137, REQ-150, REQ-151, REQ-152, REQ-162, REQ-190, REQ-191, REQ-197
  */
 function buildPiUsereqMenuChoices(
   cwd: string,
@@ -2115,43 +2393,43 @@ function buildPiUsereqMenuChoices(
   return [
     {
       id: "docs-dir",
-      label: "docs-dir",
+      label: "Document directory",
       value: config["docs-dir"],
       description: "Edit the repository-relative directory that stores REQUIREMENTS, WORKFLOW, and REFERENCES documents.",
     },
-    {
-      id: "tests-dir",
-      label: "tests-dir",
-      value: config["tests-dir"],
-      description: "Edit the repository-relative directory used for project test assets and static-check selection.",
-    },
     {
       id: "src-dir",
-      label: "src-dir",
+      label: "Source-code directories",
       value: config["src-dir"].join(", "),
       description: "Manage the repository-relative source directories scanned by project-scope tools.",
     },
+    {
+      id: "tests-dir",
+      label: "Unit tests directory",
+      value: config["tests-dir"],
+      description: "Edit the repository-relative directory used for project test assets and static-check selection.",
+    },
     {
       id: "static-check",
-      label: "static-check",
+      label: "Language static code checkers",
       value: formatStaticCheckLanguagesSummary(config),
-      description: "Manage configured static-check entries and inspect supported languages and modules.",
+      description: "Manage guided Command static-check entries by language.",
     },
     {
       id: "startup-tools",
-      label: "startup tools",
+      label: "Enable tools",
       value: `${getConfiguredEnabledPiUsereqTools(config).length} enabled`,
       description: "Manage which configurable tools become active during session_start.",
     },
     {
       id: "notifications",
-      label: "notifications",
-      value: `beep:${formatPiNotifyBeepStatus(config)} • sound:${config["notify-sound"]}`,
-      description: "Manage terminal beep flags, selected notify command, hotkey bind, per-level notify commands, and the nested Pushover submenu.",
+      label: "Notifications",
+      value: `notification:${formatPiNotifyStatus(config)} • sound:${config["notify-sound"]} • pushover:${formatPiNotifyPushoverStatus(config)}`,
+      description: "Manage command-notify, sound, and Pushover settings with dedicated event submenus.",
     },
     {
       id: "show-config",
-      label: "show-config",
+      label: "Show configuration",
       value: formatProjectConfigPathForMenu(cwd),
       valueTone: "dim",
       description: "Write the current project configuration JSON into the editor without saving additional changes.",
@@ -2176,25 +2454,31 @@ function buildPiUsereqMenuChoices(
  * @details Exposes add and remove actions for `src-dir` entries through right-valued menu rows consumed by the shared settings-menu renderer. Runtime is O(s) in source-directory count. No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered source-directory management choices.
- * @satisfies REQ-006, REQ-151, REQ-152, REQ-153, REQ-154
+ * @satisfies REQ-006, REQ-151, REQ-152, REQ-153, REQ-154, REQ-193
  */
 function buildSrcDirMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
   return [
     {
       id: "add-src-dir-entry",
-      label: "Add src-dir entry",
+      label: "Add source-code directory",
       value: `${config["src-dir"].length} configured`,
       description: "Append one repository-relative source directory to the current configuration.",
     },
     {
       id: "remove-src-dir-entry",
-      label: "Remove src-dir entry",
+      label: "Remove source-code directory",
       value: config["src-dir"].join(", "),
       description: "Select one configured source directory to remove from the current configuration.",
     },
     {
-      id: "back",
-      label: "Back",
+      id: "reset-defaults",
+      label: "Reset defaults",
+      value: `${DEFAULT_SRC_DIRS.join(", ")}`,
+      description: "Restore the documented default source-directory configuration.",
+    },
+    {
+      id: "save-and-close",
+      label: "Save and close",
       value: "",
       description: "Return to the parent configuration menu.",
     },
@@ -2232,7 +2516,7 @@ function buildSrcDirRemovalChoices(config: UseReqConfig): PiUsereqSettingsMenuCh
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @return {Promise<void>} Promise resolved when configuration is saved and the menu closes.
- * @satisfies REQ-006, REQ-031, REQ-137, REQ-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-162
+ * @satisfies REQ-006, REQ-031, REQ-137, REQ-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-162, REQ-190, REQ-191, REQ-192, REQ-194, REQ-195
  */
 async function configurePiUsereq(
   pi: ExtensionAPI,
@@ -2248,11 +2532,13 @@ async function configurePiUsereq(
     renderPiUsereqStatus(statusController, ctx);
   };
 
+  let focusedChoiceId: string | undefined;
   while (true) {
     const choice = await showPiUsereqSettingsMenu(
       ctx,
       "pi-usereq",
       buildPiUsereqMenuChoices(ctx.cwd, config),
+      { initialSelectedId: focusedChoiceId },
     );
     if (!choice || choice === "save-and-close") {
       ensureSaved();
@@ -2262,37 +2548,47 @@ async function configurePiUsereq(
       }
       return;
     }
+    focusedChoiceId = choice;
     if (choice === "docs-dir") {
-      const value = await ctx.ui.input("docs-dir", config["docs-dir"]);
+      const value = await ctx.ui.input("Document directory", config["docs-dir"]);
       if (value?.trim()) config["docs-dir"] = value.trim();
       continue;
     }
     if (choice === "tests-dir") {
-      const value = await ctx.ui.input("tests-dir", config["tests-dir"]);
+      const value = await ctx.ui.input("Unit tests directory", config["tests-dir"]);
       if (value?.trim()) config["tests-dir"] = value.trim();
       continue;
     }
     if (choice === "src-dir") {
+      let srcFocusedChoiceId: string | undefined;
       while (true) {
-        const srcAction = await showPiUsereqSettingsMenu(ctx, "src-dir", buildSrcDirMenuChoices(config));
-        if (!srcAction || srcAction === "back") {
+        const srcAction = await showPiUsereqSettingsMenu(ctx, "Source-code directories", buildSrcDirMenuChoices(config), {
+          initialSelectedId: srcFocusedChoiceId,
+        });
+        if (!srcAction || srcAction === "save-and-close") {
           break;
         }
+        srcFocusedChoiceId = srcAction;
         if (srcAction === "add-src-dir-entry") {
-          const value = await ctx.ui.input("New src-dir entry", "src");
+          const value = await ctx.ui.input("New source-code directory", "src");
           if (value?.trim()) {
             config["src-dir"] = [...config["src-dir"], value.trim()];
           }
           continue;
         }
         if (srcAction === "remove-src-dir-entry") {
-          const toRemove = await showPiUsereqSettingsMenu(ctx, "remove src-dir entry", buildSrcDirRemovalChoices(config));
+          const toRemove = await showPiUsereqSettingsMenu(ctx, "Remove source-code directory", buildSrcDirRemovalChoices(config));
           if (toRemove && toRemove !== "back") {
             config["src-dir"] = config["src-dir"].filter((entry) => entry !== toRemove);
             if (config["src-dir"].length === 0) {
               config["src-dir"] = ["src"];
             }
           }
+          continue;
+        }
+        if (srcAction === "reset-defaults") {
+          config["src-dir"] = [...DEFAULT_SRC_DIRS];
+          ctx.ui.notify("Restored default source-code directories", "info");
         }
       }
       continue;
@@ -2312,6 +2608,7 @@ async function configurePiUsereq(
     if (choice === "reset-defaults") {
       config = getDefaultConfig(projectBase);
       applyConfiguredPiUsereqTools(pi, config);
+      ctx.ui.notify("Restored all default configuration values", "info");
       continue;
     }
     if (choice === "show-config") {
@@ -2345,7 +2642,7 @@ function registerConfigCommands(
  * @brief Registers the complete pi-usereq extension.
  * @details Validates installation-owned bundled resources, registers prompt and
  * configuration commands plus agent tools, registers the configurable
- * successful-run sound shortcut when the runtime supports shortcuts, and
+ * notification-sound shortcut when the runtime supports shortcuts, and
  * installs shared wrappers for all supported pi lifecycle hooks so status
  * telemetry, context usage, prompt timing, cumulative runtime, prompt-specific
  * Pushover metadata, and pi-notify effects remain synchronized with runtime
@@ -2355,7 +2652,7 @@ function registerConfigCommands(
  * timer scheduling.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @return {void} No return value.
- * @satisfies DES-002, REQ-004, REQ-005, REQ-009, REQ-044, REQ-045, REQ-067, REQ-068, REQ-109, REQ-111, REQ-112, REQ-113, REQ-114, REQ-115, REQ-116, REQ-117, REQ-118, REQ-119, REQ-120, REQ-121, REQ-122, REQ-123, REQ-124, REQ-125, REQ-126, REQ-129, REQ-130, REQ-131, REQ-132, REQ-133, REQ-134, REQ-135, REQ-136, REQ-137, REQ-148, REQ-159, REQ-163, REQ-164, REQ-165, REQ-166, REQ-167, REQ-168, REQ-169, REQ-170, REQ-171, REQ-172
+ * @satisfies DES-002, REQ-004, REQ-005, REQ-009, REQ-044, REQ-045, REQ-067, REQ-068, REQ-109, REQ-111, REQ-112, REQ-113, REQ-114, REQ-115, REQ-116, REQ-117, REQ-118, REQ-119, REQ-120, REQ-121, REQ-122, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-131, REQ-132, REQ-133, REQ-134, REQ-137, REQ-148, REQ-159, REQ-163, REQ-164, REQ-165, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-174, REQ-179, REQ-180, REQ-184, REQ-188, REQ-190, REQ-191, REQ-192, REQ-193, REQ-194, REQ-195, REQ-196, REQ-197
  */
 export default function piUsereqExtension(pi: ExtensionAPI): void {
   const statusController = createPiUsereqStatusController();