pi-usereq 0.4.0 → 0.5.0

package/{req → pi-usereq}/docs/REFERENCES.md

@@ -1658,7 +1658,7 @@ import { makeRelativeIfContainsProject } from "./utils.js";
 
 ---
 
-# extension-status.ts | TypeScript | 660L | 30 symbols | 4 imports | 30 comments
+# extension-status.ts | TypeScript | 686L | 32 symbols | 5 imports | 32 comments
 > Path: `src/core/extension-status.ts`
 - @brief Tracks pi-usereq extension status state and renders status-bar telemetry.
 - @details Centralizes hook interception, context-usage snapshots, run timing,
@@ -1669,10 +1669,11 @@ scheduling through exported controller helpers.
 
 ## Imports
 ```
+import path from "node:path";
 import type {
 import type { UseReqConfig } from "./config.js";
+import { normalizePathSlashes } from "./path-context.js";
 import { formatPiNotifyBeepStatus } from "./pi-notify.js";
-import { formatAbsoluteGitPath, formatBasePathRelativeToGitPath, resolveRuntimeGitPath } from "./runtime-project-paths.js";
 ```
 
 ## Definitions
@@ -1768,19 +1769,19 @@ runtime. Runtime is O(1). Side effect: mutates `state.contextUsage`.
 - @return {void} No return value.
 - @satisfies REQ-118, REQ-119
 
-### fn `function countFilledContextCells(` (L275-283)
-- @brief Counts the filled cells rendered by the 5-cell context bar.
+### fn `function countFilledContextCells(` (L277-285)
+- @brief Counts the filled cells rendered by the 10-cell context bar.
 - @details Uses ceiling semantics for positive percentages so any non-zero
 usage occupies at least one cell and zero usage occupies none. Runtime is
 O(1). No external state is mutated.
 - @param[in] contextUsage {ContextUsage | undefined} Normalized context snapshot.
-- @return {number} Filled-cell count in the inclusive range `[0, 5]`.
+- @return {number} Filled-cell count in the inclusive range `[0, 10]`.
 - @satisfies REQ-122
 
-### fn `function resolveContextUsageOverlay(` (L295-314)
+### fn `function resolveContextUsageOverlay(` (L297-316)
 - @brief Resolves the threshold-specific context-bar overlay when required.
-- @details Returns the empty-state `CLEAR` overlay when normalized context
-usage is unavailable or non-positive and returns the high-water `FULL!`
+- @details Returns the empty-state `◀ CLEAR ▶ ` overlay when normalized context
+usage is unavailable or non-positive and returns the centered ` ◀ FULL ▶ `
 overlay with the active theme `error` token when usage exceeds 90 percent.
 Runtime is O(1). No external state is mutated.
 - @param[in] contextUsage {ContextUsage | undefined} Normalized context snapshot.
@@ -1798,8 +1799,8 @@ width. No external state is mutated.
 - @return {string} Rendered overlay text.
 - @satisfies REQ-127, REQ-128
 
-### fn `function formatContextUsageBar(` (L349-361)
-- @brief Formats one 5-cell context-usage bar.
+### fn `function formatContextUsageBar(` (L351-363)
+- @brief Formats one 10-cell context-usage bar.
 - @details Renders threshold-specific overlays for empty and high-water states;
 otherwise renders filled cells with the theme `warning` token on an
 accent-derived background and unfilled cells in `dim` on the same background
@@ -1807,10 +1808,10 @@ to preserve constant bar width. Runtime is O(1). No external state is
 mutated.
 - @param[in] theme {StatusThemeAdapter} Normalized status theme.
 - @param[in] contextUsage {ContextUsage | undefined} Normalized context snapshot.
-- @return {string} Rendered 5-cell bar or overlay.
+- @return {string} Rendered 10-cell bar or overlay.
 - @satisfies REQ-121, REQ-122, REQ-126, REQ-127, REQ-128
 
-### fn `function formatStatusDuration(durationMs: number): string` (L372-377)
+### fn `function formatStatusDuration(durationMs: number): string` (L374-379)
 - @brief Formats one elapsed-duration value as `M:SS`.
 - @details Floors the input to whole seconds, keeps minutes unbounded above 59,
 and zero-pads seconds to two digits. Runtime is O(1). No external state is
@@ -1819,7 +1820,27 @@ mutated.
 - @return {string} Duration rendered as `M:SS`.
 - @satisfies REQ-125
 
-### fn `function formatStatusField(` (L388-394)
+### fn `function formatCompletedStatusDuration(` (L390-394)
+- @brief Formats one optional completed-duration value.
+- @details Returns the canonical unset placeholder `--:--` until the supplied
+timer receives a normally completed prompt duration, then delegates to
+`formatStatusDuration(...)`. Runtime is O(1). No external state is mutated.
+- @param[in] durationMs {number | undefined} Optional completed-duration value.
+- @return {string} Rendered duration or unset placeholder.
+- @satisfies REQ-124
+
+### fn `function formatElapsedStatusValue(` (L407-417)
+- @brief Formats the consolidated `elapsed` status-bar value.
+- @details Emits the active prompt segment `⏱︎ <active>`, the latest normally
+completed segment `⚑ <last>`, and the accumulated successful-runtime segment
+`⌛︎ <total>` with fixed spacing. Runtime is O(1). No external state is
+mutated.
+- @param[in] state {PiUsereqStatusState} Mutable status state snapshot.
+- @param[in] nowMs {number} Current wall-clock time in milliseconds.
+- @return {string} Consolidated `elapsed` field value.
+- @satisfies REQ-123, REQ-124, REQ-125, REQ-159
+
+### fn `function formatStatusField(` (L428-434)
 - @brief Formats one standard status-bar field.
 - @details Renders the field label in accent color and the value in warning
 color. Runtime is O(n) in combined text length. No external state is mutated.
@@ -1847,17 +1868,18 @@ Runtime is O(n) in message count. No external state is mutated.
 - @return {boolean} `true` when the run ended in aborted state.
 - @satisfies REQ-125
 
-### fn `function buildPiUsereqStatusText(` (L444-481)
+### fn `function buildPiUsereqStatusText(` (L485-507)
 - @brief Builds the full single-line pi-usereq status-bar payload.
-- @details Renders git, base, docs, tests, src, tools, context, elapsed, last, beep, and sound fields in the canonical order with dim bullet separators and threshold-specific context-bar overlays. Runtime is O(s) in configured source-path count plus runtime git probing. No external state is mutated.
-- @param[in] cwd {string} Runtime working directory used for git/base path derivation.
+- @details Renders base, context, elapsed, beep, and sound fields in the
+canonical order with dim bullet separators and threshold-specific context-bar
+overlays. Runtime is O(1). No external state is mutated.
+- @param[in] cwd {string} Runtime working directory used for base-path derivation.
 - @param[in] config {UseReqConfig} Effective project configuration.
-- @param[in] activeTools {readonly string[]} Active runtime tool names.
 - @param[in] theme {StatusThemeAdapter} Normalized status theme.
 - @param[in] state {PiUsereqStatusState} Mutable status state snapshot.
 - @param[in] nowMs {number} Current wall-clock time in milliseconds.
 - @return {string} Single-line status-bar text.
-- @satisfies REQ-109, REQ-112, REQ-120, REQ-121, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-135, REQ-136, REQ-147, REQ-148, REQ-156
+- @satisfies REQ-109, REQ-112, REQ-120, REQ-121, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-135, REQ-136, REQ-148, REQ-156, REQ-159
 
 ### fn `function stopStatusTicker(controller: PiUsereqStatusController): void` (L491-496)
 - @brief Stops the live elapsed-time ticker when it is active.
@@ -1948,15 +1970,17 @@ limited to interval disposal and in-memory state mutation.
 |`backgroundize`|fn||203-219|const backgroundize = (color: StatusForegroundColor, text...|
 |`normalizeContextUsage`|fn||230-247|function normalizeContextUsage(|
 |`refreshContextUsage`|fn||259-264|function refreshContextUsage(|
-|`countFilledContextCells`|fn||275-283|function countFilledContextCells(|
-|`resolveContextUsageOverlay`|fn||295-314|function resolveContextUsageOverlay(|
-|`formatContextUsageOverlay`|fn||327-335|function formatContextUsageOverlay(|
-|`formatContextUsageBar`|fn||349-361|function formatContextUsageBar(|
-|`formatStatusDuration`|fn||372-377|function formatStatusDuration(durationMs: number): string|
-|`formatStatusField`|fn||388-394|function formatStatusField(|
-|`formatRenderedStatusField`|fn||406-412|function formatRenderedStatusField(|
-|`didAgentEndAbort`|fn||423-430|function didAgentEndAbort(messages: AgentEndEvent["messag...|
-|`buildPiUsereqStatusText`|fn||444-481|function buildPiUsereqStatusText(|
+|`countFilledContextCells`|fn||277-285|function countFilledContextCells(|
+|`resolveContextUsageOverlay`|fn||297-316|function resolveContextUsageOverlay(|
+|`formatContextUsageOverlay`|fn||329-337|function formatContextUsageOverlay(|
+|`formatContextUsageBar`|fn||351-363|function formatContextUsageBar(|
+|`formatStatusDuration`|fn||374-379|function formatStatusDuration(durationMs: number): string|
+|`formatCompletedStatusDuration`|fn||390-394|function formatCompletedStatusDuration(|
+|`formatElapsedStatusValue`|fn||407-417|function formatElapsedStatusValue(|
+|`formatStatusField`|fn||428-434|function formatStatusField(|
+|`formatRenderedStatusField`|fn||446-452|function formatRenderedStatusField(|
+|`didAgentEndAbort`|fn||463-470|function didAgentEndAbort(messages: AgentEndEvent["messag...|
+|`buildPiUsereqStatusText`|fn||485-507|function buildPiUsereqStatusText(|
 |`stopStatusTicker`|fn||491-496|function stopStatusTicker(controller: PiUsereqStatusContr...|
 |`syncPiUsereqStatusTicker`|fn||508-524|function syncPiUsereqStatusTicker(|
 |`createPiUsereqStatusController`|fn||535-549|export function createPiUsereqStatusController(|
@@ -3008,17 +3032,17 @@ import { getInstallationPath, RESOURCE_ROOT_DIRNAME } from "./path-context.js";
 
 ---
 
-# runtime-project-paths.ts | TypeScript | 99L | 6 symbols | 4 imports | 7 comments
+# runtime-project-paths.ts | TypeScript | 70L | 4 symbols | 4 imports | 5 comments
 > Path: `src/core/runtime-project-paths.ts`
-- @brief Derives runtime-only repository and base-path facts.
-- @details Centralizes git-repository probing, repository-root resolution, and base-path-to-git-path formatting for extension status, tool execution, and CLI flows. Runtime is dominated by git subprocess execution plus path normalization. Side effects are limited to subprocess spawning.
+- @brief Derives runtime-only repository facts.
+- @details Centralizes git-repository probing and repository-root resolution for extension status, tool execution, and CLI flows. Runtime is dominated by git subprocess execution plus path normalization. Side effects are limited to subprocess spawning.
 
 ## Imports
 ```
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { ReqError } from "./errors.js";
-import { isSameOrAncestorPath, normalizePathSlashes } from "./path-context.js";
+import { isSameOrAncestorPath } from "./path-context.js";
 ```
 
 ## Definitions
@@ -3052,21 +3076,6 @@ import { isSameOrAncestorPath, normalizePathSlashes } from "./path-context.js";
 - @return {string | undefined} Absolute repository-root path or `undefined` when unavailable.
 - @satisfies REQ-105, REQ-145
 
-### fn `export function formatBasePathRelativeToGitPath(basePath: string, gitPath: string | undefined): string` (L78-88)
-- @brief Formats the runtime `base-path` relative to the runtime `git-path`.
-- @details Returns `.` when the repository root is unavailable or identical to the base path. Otherwise returns the slash-normalized relative path from `git-path` to `base-path`. Runtime is O(p) in path length. No external state is mutated.
-- @param[in] basePath {string} Runtime base path.
-- @param[in] gitPath {string | undefined} Runtime repository root.
-- @return {string} Relative base-path token for status rendering.
-- @satisfies REQ-148
-
-### fn `export function formatAbsoluteGitPath(gitPath: string | undefined): string` (L97-99)
-- @brief Formats the runtime git path for status rendering.
-- @details Returns a slash-normalized absolute path or an empty string when no repository root is available. Runtime is O(p) in path length. No external state is mutated.
-- @param[in] gitPath {string | undefined} Runtime repository root.
-- @return {string} Absolute repository path or an empty string.
-- @satisfies REQ-147
-
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
 |---|---|---|---|---|
@@ -3074,13 +3083,11 @@ import { isSameOrAncestorPath, normalizePathSlashes } from "./path-context.js";
 |`isInsideGitRepo`|fn||33-36|export function isInsideGitRepo(targetPath: string): boolean|
 |`resolveGitRoot`|fn||46-52|export function resolveGitRoot(targetPath: string): string|
 |`resolveRuntimeGitPath`|fn||61-68|export function resolveRuntimeGitPath(executionPath: stri...|
-|`formatBasePathRelativeToGitPath`|fn||78-88|export function formatBasePathRelativeToGitPath(basePath:...|
-|`formatAbsoluteGitPath`|fn||97-99|export function formatAbsoluteGitPath(gitPath: string | u...|
 
 
 ---
 
-# settings-menu.ts | TypeScript | 233L | 11 symbols | 2 imports | 12 comments
+# settings-menu.ts | TypeScript | 238L | 11 symbols | 2 imports | 12 comments
 > Path: `src/core/settings-menu.ts`
 - @brief Renders pi-usereq configuration menus with the shared pi.dev settings style.
 - @details Wraps `SettingsList` in one extension-command helper that exposes right-aligned current values, built-in circular scrolling, bottom-line descriptions, and a deterministic bridge for offline test harnesses. Runtime is O(n) in visible choice count plus user interaction cost. Side effects are limited to transient custom-UI rendering.
@@ -3093,9 +3100,9 @@ import { Container, SettingsList, Text, type Component, type SettingItem, type S
 
 ## Definitions
 
-### iface `export interface PiUsereqSettingsMenuChoice` (L14-19)
+### iface `export interface PiUsereqSettingsMenuChoice` (L14-20)
 - @brief Describes one selectable pi-usereq settings-menu choice.
-- @details Stores the stable action identifier, left-column label, right-column current value, and bottom-line description consumed by the shared settings-menu renderer. The interface is compile-time only and introduces no runtime cost.
+- @details Stores the stable action identifier, left-column label, right-column current value, optional value-tone override, and bottom-line description consumed by the shared settings-menu renderer. The interface is compile-time only and introduces no runtime cost.
 
 ### iface `export interface PiUsereqSettingsMenuBridge` (L25-30)
 - @brief Describes the offline bridge exposed by shared settings-menu components.
@@ -3155,9 +3162,10 @@ Runtime is O(n) in title length. No external state is mutated.
 - @param[in] done {(value?: string) => void} Outer custom-UI completion callback.
 - @return {Component} Immediate-completion submenu component.
 
-### fn `function buildSettingItems(` (L156-167)
+### fn `function buildSettingItems(` (L158-172)
 - @brief Builds `SettingsList` items from one menu-choice vector.
-- @details Copies labels, current values, and descriptions into `SettingItem` records and attaches a submenu that resolves the outer custom UI with the selected choice identifier. Runtime is O(n) in choice count. No external state is mutated.
+- @details Copies labels, current values, value-tone overrides, and descriptions into `SettingItem` records and attaches a submenu that resolves the outer custom UI with the selected choice identifier. Runtime is O(n) in choice count. No external state is mutated.
+- @param[in] theme {PiUsereqSettingsTheme} Callback-local pi theme adapter.
 - @param[in] choices {PiUsereqSettingsMenuChoice[]} Ordered menu-choice vector.
 - @param[in] done {(value?: string) => void} Outer custom-UI completion callback.
 - @return {SettingItem[]} `SettingsList` item vector.
@@ -3174,7 +3182,7 @@ Runtime is O(n) in title length. No external state is mutated.
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
 |---|---|---|---|---|
-|`PiUsereqSettingsMenuChoice`|iface||14-19|export interface PiUsereqSettingsMenuChoice|
+|`PiUsereqSettingsMenuChoice`|iface||14-20|export interface PiUsereqSettingsMenuChoice|
 |`PiUsereqSettingsMenuBridge`|iface||25-30|export interface PiUsereqSettingsMenuBridge|
 |`PiUsereqSettingsMenuComponent`|iface||36-38|export interface PiUsereqSettingsMenuComponent extends Co...|
 |`PiUsereqSettingsThemeColor`|type||46||
@@ -3183,8 +3191,8 @@ Runtime is O(n) in title length. No external state is mutated.
 |`buildPiUsereqSettingsListTheme`|fn||95-109|function buildPiUsereqSettingsListTheme(|
 |`formatPiUsereqSettingsMenuTitle`|fn||121-126|function formatPiUsereqSettingsMenuTitle(|
 |`createImmediateSelectionComponent`|fn||135-147|function createImmediateSelectionComponent(choiceId: stri...|
-|`buildSettingItems`|fn||156-167|function buildSettingItems(|
-|`showPiUsereqSettingsMenu`|fn||178-233|export async function showPiUsereqSettingsMenu(|
+|`buildSettingItems`|fn||158-172|function buildSettingItems(|
+|`showPiUsereqSettingsMenu`|fn||183-238|export async function showPiUsereqSettingsMenu(|
 
 
 ---
@@ -3332,10 +3340,10 @@ import { formatDoxygenFieldsAsMarkdown, parseDoxygenComment } from "./doxygen-pa
 
 ---
 
-# static-check.ts | TypeScript | 674L | 18 symbols | 7 imports | 34 comments
+# static-check.ts | TypeScript | 538L | 16 symbols | 7 imports | 29 comments
 > Path: `src/core/static-check.ts`
 - @brief Defines static-check language mappings and checker dispatch implementations.
-- @details Parses static-check configuration syntax, resolves file targets, and runs built-in or command-based analyzers such as Pylance and Ruff. Runtime is linear in file count plus external tool cost. Side effects include filesystem reads, PATH probing, process spawning, and console output.
+- @details Parses Command-only user static-check specifications, preserves debug `Dummy` config handling, resolves file targets, and runs modular dummy or command-based analyzers. Runtime is linear in file count plus external tool cost. Side effects include filesystem reads, PATH probing, process spawning, and console output.
 
 ## Imports
 ```
@@ -3350,39 +3358,44 @@ import { ReqError } from "./errors.js";
 
 ## Definitions
 
-### iface `export interface StaticCheckLanguageSupport` (L85-88)
+### iface `export interface StaticCheckLanguageSupport` (L91-94)
 - @brief Describes supported extensions for one canonical static-check language.
 - @details The interface is used for UI rendering and capability reporting only. It is compile-time only and adds no runtime cost.
 
-### fn `export function getSupportedStaticCheckLanguages(): string[]` (L106-108)
+### fn `export function getSupportedStaticCheckLanguages(): string[]` (L109-111)
 - @brief Returns the sorted list of canonical languages with extension support.
 - @details Deduplicates the extension map values and sorts them alphabetically for stable UI and error messages. Runtime is O(n log n). No side effects occur.
 - @return {string[]} Sorted canonical language names.
 
-### fn `export function getSupportedStaticCheckLanguageSupport(): StaticCheckLanguageSupport[]` (L115-126)
+### fn `export function getSupportedStaticCheckLanguageSupport(): StaticCheckLanguageSupport[]` (L118-129)
 - @brief Returns supported languages paired with their known file extensions.
 - @details Groups extensions by canonical language and emits alphabetically sorted extension lists. Runtime is O(n log n). No external state is mutated.
 - @return {StaticCheckLanguageSupport[]} Sorted language-support descriptors.
 
-### fn `function formatStaticCheckModules(): string` (L133-135)
-- @brief Formats the supported module list for diagnostics.
-- @details Joins `STATIC_CHECK_MODULES` with commas for direct insertion into error strings. Time complexity is O(n). No side effects occur.
-- @return {string} Comma-delimited module names.
+### fn `function formatStaticCheckModules(): string` (L136-138)
+- @brief Formats the user-configurable module list for diagnostics.
+- @details Joins `STATIC_CHECK_MODULES` with commas for direct insertion into user-facing error strings. Time complexity is O(n). No side effects occur.
+- @return {string} Comma-delimited user-configurable module names.
+
+### fn `function formatDispatchStaticCheckModules(): string` (L145-147)
+- @brief Formats the persisted or debug-capable module list for dispatch diagnostics.
+- @details Joins `STATIC_CHECK_PERSISTED_MODULES` with commas for error strings emitted while executing existing config entries or debug-driver requests. Time complexity is O(n). No side effects occur.
+- @return {string} Comma-delimited persisted module names.
 
-### fn `function splitCsvLikeTokens(specRhs: string): string[]` (L143-165)
+### fn `function splitCsvLikeTokens(specRhs: string): string[]` (L155-177)
 - @brief Splits a comma-delimited static-check specification while honoring quotes.
 - @details Performs a single pass over the right-hand side of `LANG=...`, preserving commas inside quoted segments. Runtime is O(n). No side effects occur.
 - @param[in] specRhs {string} Right-hand side of the enable-static-check specification.
 - @return {string[]} Parsed tokens with surrounding whitespace trimmed.
 
-### fn `export function parseEnableStaticCheck(spec: string): [string, StaticCheckEntry]` (L174-222)
-- @brief Parses one `LANG=MODULE[,CMD[,PARAM...]]` static-check specification.
-- @details Validates the language alias, canonicalizes the module name, enforces module-specific argument requirements, and returns a config entry ready for persistence. Runtime is O(n) in specification length. No external state is mutated.
+### fn `export function parseEnableStaticCheck(spec: string): [string, StaticCheckEntry]` (L186-234)
+- @brief Parses one `LANG=Command,CMD[,PARAM...]` static-check specification.
+- @details Validates the language alias, canonicalizes the Command module name, enforces the required executable argument, and returns a config entry ready for persistence. Runtime is O(n) in specification length. No external state is mutated.
 - @param[in] spec {string} Raw static-check specification string.
 - @return {[string, StaticCheckEntry]} Tuple of canonical language name and normalized checker configuration.
-- @throws {ReqError} Throws for missing separators, unknown languages, unknown modules, or missing required command arguments.
+- @throws {ReqError} Throws for missing separators, unknown languages, non-Command modules, or missing required command arguments.
 
-### fn `export function buildStaticCheckEntryIdentity(language: string, entry: StaticCheckEntry): string` (L232-237)
+### fn `export function buildStaticCheckEntryIdentity(language: string, entry: StaticCheckEntry): string` (L244-249)
 - @brief Builds the duplicate-identity token for one static-check entry.
 - @details Canonicalizes the language key, module name, command name, and parameter list into a stable JSON tuple used for merge deduplication. Runtime is O(p) in parameter count. No side effects occur.
 - @param[in] language {string} Canonical or alias language name associated with the entry.
@@ -3390,7 +3403,7 @@ import { ReqError } from "./errors.js";
 - @return {string} Stable identity token suitable for equality comparison.
 - @satisfies REQ-036
 
-### fn `export function validateStaticCheckEntry(entry: StaticCheckEntry): void` (L247-258)
+### fn `export function validateStaticCheckEntry(entry: StaticCheckEntry): void` (L259-270)
 - @brief Validates pre-persistence invariants for one static-check entry.
 - @details Rejects `Command` entries whose executable cannot be resolved before config writes while leaving non-command modules untouched. Runtime is O(p) in PATH entry count. Side effects are limited to filesystem reads.
 - @param[in] entry {StaticCheckEntry} Static-check configuration entry to validate.
@@ -3398,32 +3411,18 @@ import { ReqError } from "./errors.js";
 - @throws {ReqError} Throws when a `Command` entry omits `cmd` or resolves to a non-executable program.
 - @satisfies REQ-037
 
-### fn `function resolveFiles(inputs: string[]): string[]` (L266-290)
+### fn `function resolveFiles(inputs: string[]): string[]` (L278-302)
 - @brief Resolves explicit files, directories, and glob patterns into absolute file paths.
 - @details Expands glob inputs with `fast-glob`, enumerates direct children for directory inputs, accepts regular files, and warns for invalid entries. Runtime is O(n + m) where m is the total matched path count. Side effects are filesystem reads and warning output to stderr.
 - @param[in] inputs {string[]} Raw file, directory, or glob inputs.
 - @return {string[]} Unique absolute file paths.
 
-### class `export class StaticCheckBase` (L296-370)
-- @brief Provides the base implementation for file-oriented static checks.
-- @details Resolves input files once, emits standardized headers, and defines overridable `checkFile` and `emitLine` hooks used by concrete analyzers. Runtime is O(f) plus subclass checker cost. Side effects include console output.
+### class `export class StaticCheckBase` (L308-382)
+- @brief Provides the shared and debug-capable base implementation for file-oriented static checks.
+- @details Resolves input files once, emits standardized headers, implements the debug `Dummy` checker behavior, and defines overridable `checkFile` plus `emitLine` hooks used by concrete analyzers. Runtime is O(f) plus subclass checker cost. Side effects include console output.
 
-### fn `function detectPythonExecutable(projectBase?: string): string` (L378-398)
-- @brief Resolves the preferred Python executable for Python-based checkers.
-- @details Checks the project virtual environment first, then `PI_USEREQ_PYTHON`, then `python3`, then `python`, and finally falls back to the literal `python3` string. Runtime is O(c) in candidate count. Side effects are filesystem reads and PATH probing.
-- @param[in] projectBase {string | undefined} Optional project root used to probe `.venv/bin/python`.
-- @return {string} Executable path or command name.
-
-### class `export class StaticCheckPylance extends StaticCheckBase` : StaticCheckBase (L404-455)
-- @brief Runs Pyright/Pylance checks through the selected Python interpreter.
-- @details Invokes `python -m pyright` for each resolved file and emits standardized OK/FAIL records. Runtime is dominated by external checker execution. Side effects include process spawning and console output.
-
-### class `export class StaticCheckRuff extends StaticCheckBase` : StaticCheckBase (L461-509)
-- @brief Runs Ruff checks through the selected Python interpreter.
-- @details Invokes `python -m ruff check` for each resolved file and emits standardized OK/FAIL records. Runtime is dominated by external checker execution. Side effects include process spawning and console output.
-
-### class `export class StaticCheckCommand extends StaticCheckBase` : StaticCheckBase (L515-564)
-- @brief Runs an arbitrary external command as a static checker.
+### class `export class StaticCheckCommand extends StaticCheckBase` : StaticCheckBase (L388-437)
+- @brief Runs the user-facing external-command static checker.
 - @brief Initializes a command-backed checker instance.
 - @details Validates command availability on PATH during construction, then invokes the command with configured extra arguments plus one target file at a time. Runtime is dominated by external command execution. Side effects include PATH probing, process spawning, and console output.
 - @details Validates that the executable exists on PATH before delegating file resolution to the base class and recording the command label. Runtime is O(p + f) where p is PATH entry count and f is resolved input count. Side effects are filesystem reads.
@@ -3433,30 +3432,30 @@ import { ReqError } from "./errors.js";
 - @param[in] failOnly {boolean} When `true`, suppress successful-file output.
 - @throws {ReqError} Throws when the executable cannot be found on PATH.
 
-### fn `function isExecutableFile(candidate: string): boolean` (L572-582)
+### fn `function isExecutableFile(candidate: string): boolean` (L445-455)
 - @brief Tests whether one filesystem path is executable.
 - @details Requires the candidate to exist, be a regular file, and pass `X_OK` access checks. Runtime is O(1). Side effects are limited to filesystem reads.
 - @param[in] candidate {string} Absolute or relative path to inspect.
 - @return {boolean} `true` when the candidate is executable by the current process.
 
-### fn `function findExecutable(cmd: string): string | undefined` (L590-601)
+### fn `function findExecutable(cmd: string): string | undefined` (L463-474)
 - @brief Locates an executable by scanning the current PATH.
 - @details Checks each PATH directory for an executable file named exactly as the requested command. Runtime is O(p) in PATH entry count. Side effects are filesystem reads.
 - @param[in] cmd {string} Executable name to locate.
 - @return {string | undefined} Absolute executable path, or `undefined` when not found.
 
-### fn `export function dispatchStaticCheckForFile(` (L612-615)
+### fn `export function dispatchStaticCheckForFile(` (L485-488)
 - @brief Dispatches one configured static checker for a single file.
-- @details Selects the checker implementation by module name, normalizes parameter arrays, and runs exactly one checker instance against the target file. Runtime is dominated by the selected checker. Side effects include console output and possible process spawning.
+- @details Selects the debug `Dummy` or user-facing `Command` implementation by module name, normalizes parameter arrays, and runs exactly one checker instance against the target file. Runtime is dominated by the selected checker. Side effects include console output and possible process spawning.
 - @param[in] filePath {string} Absolute or relative file path to check.
 - @param[in] langConfig {StaticCheckEntry} Normalized static-check configuration entry.
 - @param[in] options {{ failOnly?: boolean; projectBase?: string }} Optional execution controls.
 - @return {number} Checker exit status where `0` means success and non-zero means failure.
 - @throws {ReqError} Throws when configuration is incomplete or names an unknown module.
 
-### fn `export function runStaticCheck(argv: string[]): number` (L649-674)
+### fn `export function runStaticCheck(argv: string[]): number` (L517-538)
 - @brief Runs the standalone static-check test driver.
-- @details Dispatches subcommands to the built-in checker implementations without consulting project configuration. Runtime is O(n) in argument count plus checker cost. Side effects include console output and external process spawning.
+- @details Dispatches debug `dummy` or user-facing `command` subcommands without consulting project configuration. Runtime is O(n) in argument count plus checker cost. Side effects include console output and external process spawning.
 - @param[in] argv {string[]} Raw static-check subcommand arguments.
 - @return {number} Checker exit status where `0` means success.
 - @throws {ReqError} Throws when no subcommand is provided, the subcommand is unknown, or required arguments are missing.
@@ -3464,24 +3463,22 @@ import { ReqError } from "./errors.js";
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
 |---|---|---|---|---|
-|`StaticCheckLanguageSupport`|iface||85-88|export interface StaticCheckLanguageSupport|
-|`getSupportedStaticCheckLanguages`|fn||106-108|export function getSupportedStaticCheckLanguages(): string[]|
-|`getSupportedStaticCheckLanguageSupport`|fn||115-126|export function getSupportedStaticCheckLanguageSupport():...|
-|`formatStaticCheckModules`|fn||133-135|function formatStaticCheckModules(): string|
-|`splitCsvLikeTokens`|fn||143-165|function splitCsvLikeTokens(specRhs: string): string[]|
-|`parseEnableStaticCheck`|fn||174-222|export function parseEnableStaticCheck(spec: string): [st...|
-|`buildStaticCheckEntryIdentity`|fn||232-237|export function buildStaticCheckEntryIdentity(language: s...|
-|`validateStaticCheckEntry`|fn||247-258|export function validateStaticCheckEntry(entry: StaticChe...|
-|`resolveFiles`|fn||266-290|function resolveFiles(inputs: string[]): string[]|
-|`StaticCheckBase`|class||296-370|export class StaticCheckBase|
-|`detectPythonExecutable`|fn||378-398|function detectPythonExecutable(projectBase?: string): st...|
-|`StaticCheckPylance`|class||404-455|export class StaticCheckPylance extends StaticCheckBase|
-|`StaticCheckRuff`|class||461-509|export class StaticCheckRuff extends StaticCheckBase|
-|`StaticCheckCommand`|class||515-564|export class StaticCheckCommand extends StaticCheckBase|
-|`isExecutableFile`|fn||572-582|function isExecutableFile(candidate: string): boolean|
-|`findExecutable`|fn||590-601|function findExecutable(cmd: string): string | undefined|
-|`dispatchStaticCheckForFile`|fn||612-615|export function dispatchStaticCheckForFile(|
-|`runStaticCheck`|fn||649-674|export function runStaticCheck(argv: string[]): number|
+|`StaticCheckLanguageSupport`|iface||91-94|export interface StaticCheckLanguageSupport|
+|`getSupportedStaticCheckLanguages`|fn||109-111|export function getSupportedStaticCheckLanguages(): string[]|
+|`getSupportedStaticCheckLanguageSupport`|fn||118-129|export function getSupportedStaticCheckLanguageSupport():...|
+|`formatStaticCheckModules`|fn||136-138|function formatStaticCheckModules(): string|
+|`formatDispatchStaticCheckModules`|fn||145-147|function formatDispatchStaticCheckModules(): string|
+|`splitCsvLikeTokens`|fn||155-177|function splitCsvLikeTokens(specRhs: string): string[]|
+|`parseEnableStaticCheck`|fn||186-234|export function parseEnableStaticCheck(spec: string): [st...|
+|`buildStaticCheckEntryIdentity`|fn||244-249|export function buildStaticCheckEntryIdentity(language: s...|
+|`validateStaticCheckEntry`|fn||259-270|export function validateStaticCheckEntry(entry: StaticChe...|
+|`resolveFiles`|fn||278-302|function resolveFiles(inputs: string[]): string[]|
+|`StaticCheckBase`|class||308-382|export class StaticCheckBase|
+|`StaticCheckCommand`|class||388-437|export class StaticCheckCommand extends StaticCheckBase|
+|`isExecutableFile`|fn||445-455|function isExecutableFile(candidate: string): boolean|
+|`findExecutable`|fn||463-474|function findExecutable(cmd: string): string | undefined|
+|`dispatchStaticCheckForFile`|fn||485-488|export function dispatchStaticCheckForFile(|
+|`runStaticCheck`|fn||517-538|export function runStaticCheck(argv: string[]): number|
 
 
 ---
@@ -4099,7 +4096,7 @@ import path from "node:path";
 
 ---
 
-# index.ts | TypeScript | 2209L | 50 symbols | 21 imports | 53 comments
+# index.ts | TypeScript | 2212L | 50 symbols | 21 imports | 53 comments
 > Path: `src/index.ts`
 - @brief Registers the pi-usereq extension commands, tools, and configuration UI.
 - @details Bridges the standalone tool-runner layer into the pi extension API by registering prompt commands, agent tools, and interactive configuration menus. Runtime at module load is O(1); later behavior depends on the selected command or tool. Side effects include extension registration, UI updates, filesystem reads/writes, and delegated tool execution.
@@ -4159,7 +4156,7 @@ cost.
 - @return {UseReqConfig} Effective project configuration.
 - @satisfies REQ-030, REQ-145, REQ-146
 
-### fn `function saveProjectConfig(cwd: string, config: UseReqConfig): void` (L191-194)
+### fn `function saveProjectConfig(cwd: string, config: UseReqConfig): void` (L196-199)
 - @brief Persists project configuration from the extension runtime.
 - @details Resolves the project base, normalizes configured directory paths into project-relative form, and delegates persistence to `saveConfig` without serializing runtime-derived path metadata. Runtime is O(n) in config size. Side effects include config-file writes.
 - @param[in] cwd {string} Current working directory.
@@ -4167,7 +4164,16 @@ cost.
 - @return {void} No return value.
 - @satisfies REQ-146
 
-### fn `function collectProjectStaticCheckSelection(` (L203-234)
+### fn `function formatProjectConfigPathForMenu(cwd: string): string` (L210-212)
+- @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.
+- @param[in] cwd {string} Current working directory.
+- @return {string} User-home-relative or absolute config path display value.
+- @satisfies REQ-162
+
+### fn `function collectProjectStaticCheckSelection(` (L221-252)
 - @brief Collects the project-scoped static-check selection used by the agent tool.
 - @details Resolves configured source plus test directories, reuses the same fixture-root exclusions as `runProjectStaticCheck`, and returns canonical relative file paths for structured payload emission. Runtime is O(F) plus project file-discovery cost. Side effects are limited to filesystem reads and git subprocesses delegated through `collectSourceFiles`.
 - @param[in] projectBase {string} Resolved project base path.
@@ -4403,51 +4409,46 @@ updates.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {string} Compact summary string or `(none)`.
 
-### fn `function renderStaticCheckReference(config: UseReqConfig): string` (L1728-1749)
+### fn `function renderStaticCheckReference(config: UseReqConfig): string` (L1728-1756)
 - @brief Renders the static-check configuration reference view.
-- @details Produces a markdown-like summary containing configured entries, supported languages, supported modules, and example specifications. Runtime is O(l log l). No side effects occur.
+- @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.
 
-### fn `function buildStaticCheckMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L1758-1793)
+### fn `function buildStaticCheckMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L1765-1800)
 - @brief Builds the shared settings-menu choices for static-check management.
-- @details Serializes static-check actions into right-valued menu rows consumed by the shared settings-menu renderer. Runtime is O(1). No external state is mutated.
+- @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.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered static-check menu choices.
-- @satisfies REQ-008, REQ-151, REQ-152, REQ-153, REQ-154
+- @satisfies REQ-008, REQ-160, REQ-161, REQ-151, REQ-152, REQ-153, REQ-154
 
-### fn `function buildSupportedStaticCheckLanguageChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L1801-1820)
+### fn `function buildSupportedStaticCheckLanguageChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L1808-1827)
 - @brief Builds the shared settings-menu choices for supported static-check languages.
-- @details Exposes every supported language as one row whose right-side value reports extensions plus the current configured checker count. Runtime is O(l log l). No external state is mutated.
+- @details Exposes every supported language as one row whose right-side value reports extensions plus the current configured checker count for Command-oriented configuration flows. Runtime is O(l log l). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered language-choice vector.
 
-### fn `function buildStaticCheckModuleChoices(language: string): PiUsereqSettingsMenuChoice[]` (L1828-1845)
-- @brief Builds the shared settings-menu choices for static-check modules.
-- @details Exposes every supported static-check module as one selectable row with a concise execution description. Runtime is O(m) in module count. No external state is mutated.
-- @param[in] language {string} Canonical selected language.
-- @return {PiUsereqSettingsMenuChoice[]} Ordered module-choice vector.
-
-### fn `function buildConfiguredStaticCheckLanguageChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L1853-1870)
+### fn `function buildConfiguredStaticCheckLanguageChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L1835-1852)
 - @brief Builds the shared settings-menu choices for configured static-check languages.
 - @details Exposes only languages that currently have at least one configured checker so removal remains deterministic. Runtime is O(l log l). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered configured-language vector.
 
-### fn `async function configureStaticCheckMenu(ctx: ExtensionCommandContext, config: UseReqConfig): Promise<void>` (L1880-1953)
+### fn `async function configureStaticCheckMenu(ctx: ExtensionCommandContext, config: UseReqConfig): Promise<void>` (L1862-1928)
 - @brief Runs the interactive static-check configuration menu.
-- @details Lets the user inspect support, add 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 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.
 - @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-151, REQ-152, REQ-153, REQ-154
+- @satisfies REQ-008, REQ-160, REQ-161, REQ-151, REQ-152, REQ-153, REQ-154
 
-### fn `function buildPiUsereqMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L1962-2019)
+### fn `function buildPiUsereqMenuChoices(` (L1956-2017)
 - @brief Builds the shared settings-menu choices for the top-level pi-usereq configuration UI.
-- @details Serializes primary configuration actions into right-valued menu rows consumed by the shared settings-menu renderer. Runtime is O(s) in source-directory count. No external state is mutated.
+- @details Serializes primary configuration actions into right-valued menu rows consumed by the shared settings-menu renderer, including the display-only config path beside `show-config`. Runtime is O(s) in source-directory count. No external state is mutated.
+- @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
+- @satisfies REQ-006, REQ-031, REQ-137, REQ-150, REQ-151, REQ-152, REQ-162
 
 ### fn `function buildSrcDirMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L2028-2049)
 - @brief Builds the shared settings-menu choices for source-directory management.
@@ -4463,14 +4464,14 @@ updates.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered removable source-directory choices.
 - @satisfies REQ-006, REQ-151, REQ-152, REQ-153, REQ-154
 
-### fn `async function configurePiUsereq(` (L2084-2165)
+### fn `async function configurePiUsereq(` (L2082-2167)
 - @brief Runs the top-level pi-usereq configuration menu.
-- @details Loads project config, exposes docs/test/source/static-check/startup-tool/notification actions through the shared settings-menu renderer, persists changes on exit, and refreshes the single-line status bar. Runtime depends on user interaction count. Side effects include UI updates, config writes, and active-tool changes.
+- @details Loads project config, exposes docs/test/source/static-check/startup-tool/notification actions through the shared settings-menu renderer, persists changes on exit, and refreshes the single-line status bar. Runtime depends on user interaction count. Side effects include UI updates, config writes, active-tool changes, and editor text updates.
 - @param[in] pi {ExtensionAPI} Active extension API instance.
 - @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
+- @satisfies REQ-006, REQ-031, REQ-137, REQ-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-162
 
 ### fn `const ensureSaved = () => saveProjectConfig(ctx.cwd, config)` (L2092-2096)
 
@@ -4490,13 +4491,14 @@ updates.
 configuration commands plus agent tools, registers the configurable
 successful-run sound shortcut when the runtime supports shortcuts, and
 installs shared wrappers for all supported pi lifecycle hooks so status
-telemetry, context usage, prompt timing, and pi-notify effects remain
-synchronized with runtime events. Runtime is O(h) in hook count during
-registration. Side effects include filesystem reads, command/tool/shortcut
-registration, UI updates, active-tool changes, and timer scheduling.
+telemetry, context usage, prompt timing, cumulative runtime, and pi-notify
+effects remain synchronized with runtime events. Runtime is O(h) in hook
+count during registration. Side effects include filesystem reads,
+command/tool/shortcut registration, UI updates, active-tool changes, and
+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-110, 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
+- @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
 
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
@@ -4505,8 +4507,9 @@ registration, UI updates, active-tool changes, and timer scheduling.
 |`getProjectBase`|fn||153-155|function getProjectBase(cwd: string): string|
 |`buildSharedRuntimePathFacts`|fn||165-169|function buildSharedRuntimePathFacts(cwd: string, config:...|
 |`loadProjectConfig`|fn||178-181|function loadProjectConfig(cwd: string): UseReqConfig|
-|`saveProjectConfig`|fn||191-194|function saveProjectConfig(cwd: string, config: UseReqCon...|
-|`collectProjectStaticCheckSelection`|fn||203-234|function collectProjectStaticCheckSelection(|
+|`saveProjectConfig`|fn||196-199|function saveProjectConfig(cwd: string, config: UseReqCon...|
+|`formatProjectConfigPathForMenu`|fn||210-212|function formatProjectConfigPathForMenu(cwd: string): st...|
+|`collectProjectStaticCheckSelection`|fn||221-252|function collectProjectStaticCheckSelection(|
 |`buildTokenToolExecutionStderr`|fn||242-248|function buildTokenToolExecutionStderr(payload: TokenTool...|
 |`buildTokenToolExecuteResult`|fn||257-274|function buildTokenToolExecuteResult(|
 |`buildReferenceToolExecuteResult`|fn||283-300|function buildReferenceToolExecuteResult(|
@@ -4537,18 +4540,52 @@ registration, UI updates, active-tool changes, and timer scheduling.
 |`configurePiUsereqToolsMenu`|fn||1641-1692|async function configurePiUsereqToolsMenu(pi: ExtensionAP...|
 |`formatStaticCheckEntry`|fn||1700-1706|function formatStaticCheckEntry(entry: StaticCheckEntry):...|
 |`formatStaticCheckLanguagesSummary`|fn||1714-1720|function formatStaticCheckLanguagesSummary(config: UseReq...|
-|`renderStaticCheckReference`|fn||1728-1749|function renderStaticCheckReference(config: UseReqConfig)...|
-|`buildStaticCheckMenuChoices`|fn||1758-1793|function buildStaticCheckMenuChoices(config: UseReqConfig...|
-|`buildSupportedStaticCheckLanguageChoices`|fn||1801-1820|function buildSupportedStaticCheckLanguageChoices(config:...|
-|`buildStaticCheckModuleChoices`|fn||1828-1845|function buildStaticCheckModuleChoices(language: string):...|
-|`buildConfiguredStaticCheckLanguageChoices`|fn||1853-1870|function buildConfiguredStaticCheckLanguageChoices(config...|
-|`configureStaticCheckMenu`|fn||1880-1953|async function configureStaticCheckMenu(ctx: ExtensionCom...|
-|`buildPiUsereqMenuChoices`|fn||1962-2019|function buildPiUsereqMenuChoices(config: UseReqConfig): ...|
+|`renderStaticCheckReference`|fn||1728-1756|function renderStaticCheckReference(config: UseReqConfig)...|
+|`buildStaticCheckMenuChoices`|fn||1765-1800|function buildStaticCheckMenuChoices(config: UseReqConfig...|
+|`buildSupportedStaticCheckLanguageChoices`|fn||1808-1827|function buildSupportedStaticCheckLanguageChoices(config:...|
+|`buildConfiguredStaticCheckLanguageChoices`|fn||1835-1852|function buildConfiguredStaticCheckLanguageChoices(config...|
+|`configureStaticCheckMenu`|fn||1862-1928|async function configureStaticCheckMenu(ctx: ExtensionCom...|
+|`buildPiUsereqMenuChoices`|fn||1956-2017|function buildPiUsereqMenuChoices(|
 |`buildSrcDirMenuChoices`|fn||2028-2049|function buildSrcDirMenuChoices(config: UseReqConfig): Pi...|
 |`buildSrcDirRemovalChoices`|fn||2058-2073|function buildSrcDirRemovalChoices(config: UseReqConfig):...|
-|`configurePiUsereq`|fn||2084-2165|async function configurePiUsereq(|
+|`configurePiUsereq`|fn||2082-2167|async function configurePiUsereq(|
 |`ensureSaved`|fn||2092-2096|const ensureSaved = () => saveProjectConfig(ctx.cwd, config)|
 |`refreshStatus`|fn||2093-2096|const refreshStatus = () =>|
-|`registerConfigCommands`|fn||2175-2185|function registerConfigCommands(|
-|`piUsereqExtension`|fn||2201-2209|export default function piUsereqExtension(pi: ExtensionAP...|
+|`registerConfigCommands`|fn||2177-2187|function registerConfigCommands(|
+|`piUsereqExtension`|fn||2204-2212|export default function piUsereqExtension(pi: ExtensionAP...|
+
+## Delta Update 2026-04-19
+
+### Updated File: `src/core/config.ts`
+- `UseReqConfig` [`src/core/config.ts`]: persisted Pushover fields `notify-pushover-global-disable`, `notify-pushover-on-success`, `notify-pushover-user-key`, `notify-pushover-api-token`, and `notify-pushover-priority` extend the project configuration schema (lines 44-63).
+- `getDefaultConfig(...)` [`src/core/config.ts`]: default Pushover values are `false`, `false`, `""`, `""`, and `0` (lines 98-119).
+- `loadConfig(...)` [`src/core/config.ts`]: persisted Pushover fields are normalized during config load (lines 129-189).
+- `buildPersistedConfig(...)` [`src/core/config.ts`]: Pushover fields are serialized together with existing notification settings (lines 198-228).
+
+### Updated File: `src/core/extension-status.ts`
+- `PiUsereqPromptRequest` [`src/core/extension-status.ts`]: prompt command name and raw `%%ARGS%%` payload tracked across command delivery and runtime execution (lines 120-123).
+- `PiUsereqStatusState` [`src/core/extension-status.ts`]: pending and active prompt-request state extends timer telemetry (lines 129-136).
+- `buildPiUsereqStatusText(...)` [`src/core/extension-status.ts`]: status bar now renders `pushover` after `sound` (lines 490-514).
+- `updateExtensionStatus(...)` [`src/core/extension-status.ts`]: `agent_start` promotes pending prompt metadata into the active run, and shutdown clears prompt-request state (lines 645-680).
+
+### Updated File: `src/core/pi-notify.ts`
+- `PiNotifyPushoverPriority` [`src/core/pi-notify.ts`]: canonical `0|1` Pushover priority type (line 75).
+- `PiNotifyPushoverRequest` [`src/core/pi-notify.ts`]: successful prompt payload for Pushover delivery (lines 81-86).
+- `PiNotifyConfigFields` [`src/core/pi-notify.ts`]: notification config surface now includes Pushover flags, credentials, and priority (line 92).
+- `normalizePiNotifyPushoverCredential(...)` [`src/core/pi-notify.ts`]: credential normalization for user key and API token (lines 160-162).
+- `normalizePiNotifyPushoverPriority(...)` [`src/core/pi-notify.ts`]: priority normalization for persisted `0|1` values (lines 171-173).
+- `formatPiNotifyPushoverStatus(...)` [`src/core/pi-notify.ts`]: footer serialization for the dedicated Pushover enable flag (lines 203-205).
+- `setPiNotifyHttpsRequestForTests(...)` [`src/core/pi-notify.ts`]: deterministic HTTPS transport override for unit tests (lines 505-507).
+- `runPiNotifyEffects(...)` [`src/core/pi-notify.ts`]: successful-run routing now includes optional native Pushover delivery after sound execution (lines 590-617).
+
+### Updated File: `src/index.ts`
+- `handleExtensionStatusEvent(...)` [`src/index.ts`]: `agent_end` builds prompt-specific Pushover request metadata and dispatches it through `runPiNotifyEffects(...)` (lines 578-614).
+- `formatPiNotifyPushoverPriority(...)` [`src/index.ts`]: menu-value formatter for `0=Normal` and `1=High Priority` (lines 722-724).
+- `buildPiNotifyPushoverMenuChoices(...)` [`src/index.ts`]: nested Pushover menu rows for global disable, enable, credentials, and priority (lines 733-772).
+- `selectPiNotifyPushoverPriority(...)` [`src/index.ts`]: shared selector for Pushover priority (lines 782-804).
+- `configurePiNotifyPushoverMenu(...)` [`src/index.ts`]: interactive nested Pushover configuration menu (lines 814-863).
+- `buildPiNotifyMenuChoices(...)` [`src/index.ts`]: notifications menu now exposes the `Pushover notifications` submenu after the sound-command rows (lines 872-935).
+- `configurePiNotifyMenu(...)` [`src/index.ts`]: notifications menu routes the nested Pushover editor (lines 986-1055).
+- `registerPromptCommands(...)` [`src/index.ts`]: each bundled prompt command stores pending prompt metadata before rendering and dispatch (lines 1100-1120).
+- `piUsereqExtension(...)` [`src/index.ts`]: prompt registration now receives the shared status controller so successful prompt metadata survives until `agent_end` (lines 2396-2404).