pi-usereq 0.11.0 → 0.13.0

package/pi-usereq/docs/REFERENCES.md

@@ -23,7 +23,8 @@
     │   ├── prompt-command-runtime.ts
     │   ├── prompt-command-state.ts
     │   ├── prompts.ts
-    │   ├── reference-payload.ts
+    │   ├── req-references-command.ts
+    │   ├── req-reset-command.ts
     │   ├── resources.ts
     │   ├── runtime-project-paths.ts
     │   ├── settings-menu.ts
@@ -580,10 +581,10 @@ import { buildLanguageSpecs } from "./source-analyzer.js";
 
 ---
 
-# config.ts | TypeScript | 780L | 22 symbols | 8 imports | 31 comments
+# config.ts | TypeScript | 1141L | 43 symbols | 8 imports | 52 comments
 > Path: `src/core/config.ts`
-- @brief Loads, normalizes, and persists pi-usereq project configuration.
-- @details Defines the configuration schema, default directory conventions, JSON serialization helpers, and prompt placeholder expansion paths. Runtime is dominated by filesystem reads and writes plus linear normalization over configured entries. Side effects include config-file persistence under `.pi-usereq.json`.
+- @brief Loads, normalizes, merges, and persists pi-usereq configuration.
+- @details Defines the effective configuration schema, split local/global persistence contracts, JSON serialization helpers, and prompt placeholder expansion paths. Runtime is dominated by filesystem reads and writes plus linear normalization over configured entries. Side effects include config-file persistence under `.pi-usereq.json` and `~/.config/pi-usereq/config.json`.
 
 ## Imports
 ```
@@ -599,41 +600,87 @@ import { makeRelativeIfContainsProject } from "./utils.js";
 
 ## Definitions
 
-### iface `export interface StaticCheckEntry` (L54-58)
+### iface `export interface StaticCheckEntry` (L55-59)
 - @brief Describes one static-check module configuration entry.
 - @details Each record identifies the checker module and optional command or parameter list used during per-language static analysis dispatch. The interface is type-only and has no runtime cost.
 
-- type `export type StaticCheckEnabled = "enable" | "disable";` (L64)
+- type `export type StaticCheckEnabled = "enable" | "disable";` (L65)
 - @brief Represents the persisted per-language static-check enable flag.
 - @details Narrows persisted per-language enablement to the documented `enable|disable` domain reused by configuration loading, menu toggles, and static-check dispatch. The alias is compile-time only and introduces no runtime cost.
-### iface `export interface StaticCheckLanguageConfig` (L70-73)
+### iface `export interface StaticCheckLanguageConfig` (L71-74)
 - @brief Describes one persisted per-language static-check configuration object.
 - @details Couples the per-language enable flag with the ordered checker-entry list so menu toggles, config serialization, and execution dispatch can distinguish configured-but-disabled languages from enabled active checker lists. The interface is compile-time only and introduces no runtime cost.
 
-### iface `export interface UseReqConfig` (L79-117)
-- @brief Defines the persisted pi-usereq project configuration schema.
-- @details Captures documentation paths, source/test directory selection, per-language static-check enablement and checker configuration, prompt-command worktree settings, enabled startup tools, and notification settings while excluding runtime-derived path metadata. The interface is compile-time only and introduces no runtime side effects.
+### iface `export interface UseReqConfig` (L80-118)
+- @brief Defines the effective pi-usereq configuration schema.
+- @details Captures the merged runtime view produced from project-local and cross-project persisted scopes, including documentation paths, source/test directory selection, per-language static-check enablement plus checker configuration, prompt-command worktree settings, enabled startup tools, and notification settings while excluding runtime-derived path metadata. The interface is compile-time only and introduces no runtime side effects.
 
-### fn `function cloneStaticCheckEntry(entry: StaticCheckEntry): StaticCheckEntry` (L234-243)
+### iface `interface LocalStaticCheckLanguageConfig` (L124-126)
+- @brief Defines one persisted local static-check language configuration.
+- @details Stores only the project-local enable flag so checker command definitions can live exclusively in global configuration. The interface is compile-time only and introduces no runtime cost.
+
+### iface `interface GlobalStaticCheckLanguageConfig` (L132-134)
+- @brief Defines one persisted global static-check language configuration.
+- @details Stores only the cross-project checker-entry array so project-local files do not duplicate command definitions. The interface is compile-time only and introduces no runtime cost.
+
+### iface `interface UseReqLocalConfig` (L140-152)
+- @brief Defines the persisted local pi-usereq configuration schema.
+- @details Captures project-scoped directory, debug, and static-check enablement fields written to `<base-path>/.pi-usereq.json` while excluding global notification, tool, git, and checker-command settings. The interface is compile-time only and introduces no runtime side effects.
+
+### iface `interface UseReqGlobalConfig` (L158-186)
+- @brief Defines the persisted global pi-usereq configuration schema.
+- @details Captures cross-project static-check checker commands, enabled tool names, git automation fields, and notification settings written to `~/.config/pi-usereq/config.json` while excluding project-local directory and debug fields. The interface is compile-time only and introduces no runtime side effects.
+
+### fn `function cloneStaticCheckEntry(entry: StaticCheckEntry): StaticCheckEntry` (L303-312)
 - @brief Clones one static-check entry into its persisted shape.
 - @details Copies only the stable module, cmd, and params fields so runtime-only or unknown metadata never leaks into persisted configuration payloads. Runtime is O(p) in parameter count. No external state is mutated.
 - @param[in] entry {StaticCheckEntry} Source static-check entry.
 - @return {StaticCheckEntry} Persistable static-check entry clone.
 
-### fn `export function createStaticCheckLanguageConfig(` (L252-261)
+### fn `export function createStaticCheckLanguageConfig(` (L321-330)
 - @brief Builds one per-language static-check configuration object.
 - @details Clones the supplied checker entries, derives `enabled` from the explicit argument or checker-list emptiness, and preserves checker order for menu and dispatch determinism. Runtime is O(c + p). No external state is mutated.
 - @param[in] checkers {StaticCheckEntry[]} Ordered checker entries.
 - @param[in] enabled {StaticCheckEnabled | undefined} Optional explicit enable flag.
 - @return {StaticCheckLanguageConfig} Normalized per-language config object.
 
-### fn `export function getDefaultStaticCheckConfig(): Record<string, StaticCheckLanguageConfig>` (L269-274)
+### fn `function createLocalStaticCheckLanguageConfig(` (L338-342)
+- @brief Builds one persisted local static-check language configuration object.
+- @details Stores only the normalized enable flag so local project files do not duplicate checker command definitions. Runtime is O(1). No external state is mutated.
+- @param[in] enabled {StaticCheckEnabled} Canonical per-language enable flag.
+- @return {LocalStaticCheckLanguageConfig} Persistable local static-check language config.
+
+### fn `function createGlobalStaticCheckLanguageConfig(` (L350-356)
+- @brief Builds one persisted global static-check language configuration object.
+- @details Clones the supplied checker entries so global configuration retains only stable module, command, and parameter fields. Runtime is O(c + p). No external state is mutated.
+- @param[in] checkers {StaticCheckEntry[]} Ordered checker entries.
+- @return {GlobalStaticCheckLanguageConfig} Persistable global static-check language config.
+
+### fn `function getDefaultGlobalStaticCheckConfig(): Record<string, GlobalStaticCheckLanguageConfig>` (L363-368)
+- @brief Returns the documented default global static-check checker map.
+- @details Emits one checker-array object for every supported language, preserving documented Command entries for default-enabled languages and `[]` for every other language. Runtime is O(l + c). No external state is mutated.
+- @return {Record<string, GlobalStaticCheckLanguageConfig>} Fresh default global checker map.
+
+### fn `function getDefaultLocalStaticCheckConfig(` (L376-385)
+- @brief Returns the documented default local static-check enable map.
+- @details Derives each per-language enable flag from the supplied global checker definitions using the rule `enable` when `checkers` is non-empty and `disable` otherwise. Runtime is O(l). No external state is mutated.
+- @param[in] globalStaticCheckConfig {Record<string, GlobalStaticCheckLanguageConfig>} Global checker map used to derive default enablement.
+- @return {Record<string, LocalStaticCheckLanguageConfig>} Fresh default local enable map.
+
+### fn `function mergeStaticCheckConfig(` (L394-413)
+- @brief Merges local enable flags with global checker definitions into the effective static-check map.
+- @details Unifies all language keys present in either persisted scope, applies the default-enable rule when the local scope omits a language, and clones checker entries into the effective runtime config. Runtime is O(l + c + p). No external state is mutated.
+- @param[in] localStaticCheckConfig {Record<string, LocalStaticCheckLanguageConfig>} Persisted local enable map.
+- @param[in] globalStaticCheckConfig {Record<string, GlobalStaticCheckLanguageConfig>} Persisted global checker map.
+- @return {Record<string, StaticCheckLanguageConfig>} Effective per-language static-check config.
+
+### fn `export function getDefaultStaticCheckConfig(): Record<string, StaticCheckLanguageConfig>` (L421-427)
 - @brief Returns the documented default static-check configuration.
-- @details Emits one per-language config object for every supported language, enabling only languages with documented default checker entries and leaving all remaining languages disabled with empty checker lists. Runtime is O(l + c). No external state is mutated.
-- @return {Record<string, StaticCheckLanguageConfig>} Fresh default static-check config.
-- @satisfies REQ-249, REQ-250, REQ-251, REQ-252
+- @details Emits one effective per-language config object for every supported language by merging documented global checker defaults with derived local enable defaults. Runtime is O(l + c). No external state is mutated.
+- @return {Record<string, StaticCheckLanguageConfig>} Fresh default effective static-check config.
+- @satisfies REQ-249, REQ-250, REQ-251, REQ-252, REQ-316
 
-### fn `export function normalizeStaticCheckEnabled(` (L284-289)
+### fn `export function normalizeStaticCheckEnabled(` (L437-442)
 - @brief Normalizes one persisted per-language static-check enable flag.
 - @details Accepts only the documented `enable|disable` values and falls back to the supplied default when the candidate is absent or invalid. Runtime is O(1). No external state is mutated.
 - @param[in] value {unknown} Candidate persisted enable flag.
@@ -641,7 +688,7 @@ import { makeRelativeIfContainsProject } from "./utils.js";
 - @return {StaticCheckEnabled} Canonical per-language enable flag.
 - @satisfies REQ-249
 
-### fn `export function getActiveStaticCheckEntries(` (L299-308)
+### fn `export function getActiveStaticCheckEntries(` (L452-461)
 - @brief Resolves the active checker list for one language.
 - @details Returns the persisted checker list only when the language is enabled; disabled or missing languages yield an empty list without mutating the source config. Runtime is O(c). No external state is mutated.
 - @param[in] staticCheckConfig {Record<string, StaticCheckLanguageConfig>} Effective static-check config.
@@ -649,21 +696,21 @@ import { makeRelativeIfContainsProject } from "./utils.js";
 - @return {StaticCheckEntry[]} Active checker list for the language.
 - @satisfies REQ-019
 
-### fn `export function normalizeAutoGitCommit(value: unknown): "enable" | "disable"` (L323-325)
+### fn `export function normalizeAutoGitCommit(value: unknown): "enable" | "disable"` (L476-478)
 - @brief Normalizes one persisted automatic git-commit mode value.
 - @details Accepts only the documented `enable|disable` values and falls back to `DEFAULT_AUTO_GIT_COMMIT` for all other payloads. Runtime is O(1). No side effects occur.
 - @param[in] value {unknown} Candidate persisted automatic git-commit payload.
 - @return {"enable" | "disable"} Canonical automatic git-commit mode.
 - @satisfies REQ-212
 
-### fn `export function normalizeGitWorktreeEnabled(value: unknown): "enable" | "disable"` (L339-341)
+### fn `export function normalizeGitWorktreeEnabled(value: unknown): "enable" | "disable"` (L492-494)
 - @brief Normalizes one persisted worktree-enable flag value.
 - @details Accepts only the documented `enable|disable` values and falls back to `DEFAULT_GIT_WORKTREE_ENABLED` for all other payloads. Runtime is O(1). No side effects occur.
 - @param[in] value {unknown} Candidate persisted worktree-enable payload.
 - @return {"enable" | "disable"} Canonical persisted worktree-enable mode.
 - @satisfies REQ-204
 
-### fn `export function resolveEffectiveGitWorktreeEnabled(` (L350-355)
+### fn `export function resolveEffectiveGitWorktreeEnabled(` (L503-508)
 - @brief Resolves the effective worktree mode after automatic-commit policy is applied.
 - @details Forces `disable` whenever `AUTO_GIT_COMMIT` is disabled; otherwise preserves the normalized persisted worktree flag. Runtime is O(1). No side effects occur.
 - @param[in] autoGitCommit {"enable" | "disable"} Effective automatic git-commit mode.
@@ -671,70 +718,149 @@ import { makeRelativeIfContainsProject } from "./utils.js";
 - @return {"enable" | "disable"} Effective worktree mode used by menus, persistence, and prompt execution.
 - @satisfies REQ-204, REQ-215
 
-### fn `export function normalizeGitWorktreePrefix(value: unknown): string` (L369-375)
+### fn `export function normalizeGitWorktreePrefix(value: unknown): string` (L522-528)
 - @brief Normalizes one persisted worktree-name prefix value.
 - @details Accepts only non-empty strings, trims surrounding whitespace, and falls back to `DEFAULT_GIT_WORKTREE_PREFIX` when the candidate is absent or blank. Runtime is O(n) in prefix length. No side effects occur.
 - @param[in] value {unknown} Candidate persisted prefix payload.
 - @return {string} Canonical worktree-name prefix.
 - @satisfies REQ-205
 
-### fn `export function getProjectConfigPath(projectBase: string): string` (L382-384)
-- @brief Computes the per-project config file path.
-- @details Joins the project base with `.pi-usereq.json`, producing the canonical persistence location used by CLI and extension code. Time complexity is O(1). No I/O side effects occur.
+### fn `export function getProjectConfigPath(projectBase: string): string` (L535-537)
+- @brief Computes the per-project local config file path.
+- @details Joins the project base with `.pi-usereq.json`, producing the canonical local persistence location used by CLI and extension code. Time complexity is O(1). No I/O side effects occur.
 - @param[in] projectBase {string} Absolute project root path.
-- @return {string} Absolute config file path.
-
-### fn `export function getDefaultConfig(_projectBase: string): UseReqConfig` (L393-433)
-- @brief Builds the default project configuration.
-- @details Populates canonical docs/test/source directories, documented per-language static-check defaults, default prompt-command worktree settings, default debug fields including dedicated workflow-event logging, the default startup tool set, default command-notify, sound, and Pushover fields, and excludes runtime-derived path metadata. Time complexity is O(n) in default selector count plus default static-check entry count. No filesystem side effects occur.
-- @param[in] projectBase {string} Absolute project root path.
-- @return {UseReqConfig} Fresh default configuration object.
-- @satisfies CTN-001, CTN-012, CTN-013, REQ-066, REQ-146, REQ-163, REQ-174, REQ-178, REQ-184, REQ-185, REQ-196, REQ-204, REQ-205, REQ-212, REQ-236, REQ-237, REQ-238, REQ-239, REQ-249, REQ-250, REQ-251, REQ-252, REQ-277
-
-### fn `function normalizeStaticCheckEntries(value: unknown): StaticCheckEntry[]` (L441-461)
+- @return {string} Absolute local config file path.
+
+### fn `export function getGlobalConfigPath(): string` (L544-546)
+- @brief Computes the cross-project global config file path.
+- @details Resolves `~/.config/pi-usereq/config.json` through the shared runtime path helper so CLI and extension code use one canonical global persistence location. Time complexity is O(1). No I/O side effects occur.
+- @return {string} Absolute global config file path.
+
+### fn `function getDefaultLocalConfig(` (L554-570)
+- @brief Builds the default persisted local configuration.
+- @details Populates canonical docs/test/source directories, derives local static-check enable defaults from the supplied global checker definitions, and seeds documented debug defaults without any cross-project fields. Runtime is O(l). No filesystem side effects occur.
+- @param[in] globalStaticCheckConfig {Record<string, GlobalStaticCheckLanguageConfig>} Global checker definitions used to derive local enable defaults.
+- @return {UseReqLocalConfig} Fresh default local configuration object.
+
+### fn `function getDefaultGlobalConfig(): UseReqGlobalConfig` (L577-607)
+- @brief Builds the default persisted global configuration.
+- @details Populates documented cross-project static-check checker commands, enabled tools, git automation fields, and notification defaults without any project-local directory or debug fields. Runtime is O(l + c). No filesystem side effects occur.
+- @return {UseReqGlobalConfig} Fresh default global configuration object.
+
+### fn `function mergeConfigScopes(` (L616-682)
+- @brief Merges persisted local and global configuration scopes into the effective runtime config.
+- @details Normalizes local directories, combines local static-check enable flags with global checker arrays, resolves effective worktree disablement when automatic git commit is off, normalizes debug and notification fields, and disables Pushover until both credentials are populated. Runtime is O(l + c + p). No external state is mutated.
+- @param[in] localConfig {UseReqLocalConfig} Persisted local configuration.
+- @param[in] globalConfig {UseReqGlobalConfig} Persisted global configuration.
+- @return {UseReqConfig} Effective merged configuration.
+
+### fn `export function getDefaultConfig(_projectBase: string): UseReqConfig` (L691-697)
+- @brief Builds the default effective configuration.
+- @details Composes documented local and global defaults, then merges them into the effective runtime config consumed by CLI and extension code. Time complexity is O(l + c). No filesystem side effects occur.
+- @param[in] _projectBase {string} Absolute project root path retained for stable call sites.
+- @return {UseReqConfig} Fresh default effective configuration object.
+- @satisfies CTN-001, CTN-012, CTN-013, CTN-018, REQ-066, REQ-137, REQ-146, REQ-163, REQ-174, REQ-178, REQ-184, REQ-185, REQ-196, REQ-204, REQ-205, REQ-212, REQ-236, REQ-237, REQ-238, REQ-239, REQ-249, REQ-250, REQ-251, REQ-252, REQ-277, REQ-315, REQ-316
+
+### fn `function normalizeStaticCheckEntries(value: unknown): StaticCheckEntry[]` (L705-725)
 - @brief Normalizes one raw checker-entry array from persisted config.
 - @details Accepts only object entries with a non-empty module string, trims optional command text, filters blank params, and drops malformed records without applying any legacy schema migrations. Runtime is O(c + p). No external state is mutated.
 - @param[in] value {unknown} Candidate persisted checker array.
 - @return {StaticCheckEntry[]} Normalized checker-entry vector.
 
-### fn `function normalizeStaticCheckConfig(` (L470-489)
-- @brief Normalizes the persisted per-language static-check configuration map.
-- @details Accepts only object-valued language entries using the new `{ enabled, checkers }` schema, normalizes missing or invalid `enabled` values from checker-list presence, and drops malformed or legacy non-object language payloads without migration. Runtime is O(l + c + p). No external state is mutated.
-- @param[in] value {unknown} Candidate persisted static-check payload.
-- @return {Record<string, StaticCheckLanguageConfig>} Normalized per-language static-check map.
-- @satisfies REQ-249
+### fn `function readConfigPayload(configPath: string): Record<string, unknown> | undefined` (L734-750)
+- @brief Reads and validates one persisted config payload.
+- @details Returns `undefined` when the target file does not exist. Otherwise parses UTF-8 JSON, rejects array or primitive payloads, and surfaces deterministic `ReqError` diagnostics keyed by the exact path. Runtime is O(n) in file size. Side effects are limited to filesystem reads.
+- @param[in] configPath {string} Absolute config file path.
+- @return {Record<string, unknown> | undefined} Parsed object payload or `undefined` when the file is absent.
+- @throws {ReqError} Throws with exit code `11` when the config file contains invalid JSON or a non-object payload.
 
-### fn `export function loadConfig(projectBase: string): UseReqConfig` (L499-618)
-- @brief Loads and sanitizes the persisted project configuration.
-- @details Returns defaults when the config file does not exist. Otherwise parses JSON, validates directory and per-language static-check object shapes, normalizes enabled tool names plus prompt-command worktree, debug, notify, sound, and Pushover fields including dedicated workflow-event logging, preserves non-empty template text verbatim, forces the effective worktree mode off when automatic git commit is disabled, forces effective Pushover disablement until both credentials are populated, applies documented per-flag defaults for missing payloads, and ignores removed, malformed, or runtime-derived path metadata without legacy schema migration. Runtime is O(n) in config size. Side effects are limited to filesystem reads.
+### fn `function normalizeLocalStaticCheckConfig(` (L760-784)
+- @brief Normalizes the persisted local static-check enable map.
+- @details Starts from the supplied default enable map, accepts only object-valued language entries, reads only `enabled`, and ignores misplaced checker arrays or legacy non-object payloads without migration. Runtime is O(l). No external state is mutated.
+- @param[in] value {unknown} Candidate persisted local static-check payload.
+- @param[in] defaultConfig {Record<string, LocalStaticCheckLanguageConfig>} Default enable map derived from global checker definitions.
+- @return {Record<string, LocalStaticCheckLanguageConfig>} Normalized local static-check enable map.
+- @satisfies REQ-249, REQ-316
+
+### fn `function normalizeGlobalStaticCheckConfig(` (L793-810)
+- @brief Normalizes the persisted global static-check checker map.
+- @details Starts from documented global checker defaults, accepts only object-valued language entries, reads only `checkers`, and ignores misplaced local enable flags or legacy non-object payloads without migration. Runtime is O(l + c + p). No external state is mutated.
+- @param[in] value {unknown} Candidate persisted global static-check payload.
+- @return {Record<string, GlobalStaticCheckLanguageConfig>} Normalized global static-check checker map.
+- @satisfies REQ-249, REQ-250, REQ-251, REQ-252
+
+### fn `function loadLocalConfig(` (L819-865)
+- @brief Loads and sanitizes the persisted local configuration.
+- @details Returns defaults when `<base-path>/.pi-usereq.json` is absent. Otherwise parses the local JSON payload, normalizes project-scoped directory, debug, and static-check enable fields, and ignores misplaced global keys without migration. Runtime is O(n) in file size. Side effects are limited to filesystem reads.
+- @param[in] projectBase {string} Absolute project root path.
+- @param[in] defaultStaticCheckConfig {Record<string, LocalStaticCheckLanguageConfig>} Local static-check enable defaults derived from the current global checker map.
+- @return {UseReqLocalConfig} Sanitized local configuration.
+
+### fn `function loadGlobalConfig(): UseReqGlobalConfig` (L872-913)
+- @brief Loads and sanitizes the persisted global configuration.
+- @details Returns defaults when `~/.config/pi-usereq/config.json` is absent. Otherwise parses the global JSON payload, normalizes cross-project checker, tool, git, and notification fields, and ignores misplaced local keys without migration. Runtime is O(n) in file size. Side effects are limited to filesystem reads.
+- @return {UseReqGlobalConfig} Sanitized global configuration.
+
+### fn `export function loadConfig(projectBase: string): UseReqConfig` (L923-930)
+- @brief Loads and sanitizes the effective merged configuration.
+- @details Loads global configuration first so local static-check enable defaults can be derived from the active global checker map, then merges both scopes into the effective runtime config without applying legacy single-file migrations. Runtime is O(n) in combined local and global config size. Side effects are limited to filesystem reads.
 - @param[in] projectBase {string} Absolute project root path.
 - @return {UseReqConfig} Sanitized effective configuration.
-- @throws {ReqError} Throws with exit code `11` when the config file contains invalid JSON or a non-object payload.
-- @satisfies CTN-012, CTN-013, REQ-066, REQ-146, REQ-163, REQ-174, REQ-178, REQ-184, REQ-185, REQ-196, REQ-204, REQ-205, REQ-212, REQ-215, REQ-234, REQ-235, REQ-236, REQ-237, REQ-238, REQ-239, REQ-249, REQ-277
+- @throws {ReqError} Throws with exit code `11` when either persisted config file contains invalid JSON or a non-object payload.
+- @satisfies CTN-012, CTN-013, CTN-018, REQ-066, REQ-137, REQ-146, REQ-163, REQ-174, REQ-178, REQ-184, REQ-185, REQ-196, REQ-204, REQ-205, REQ-212, REQ-215, REQ-234, REQ-235, REQ-236, REQ-237, REQ-238, REQ-239, REQ-249, REQ-277, REQ-315, REQ-316
 
-### fn `function buildPersistedConfig(config: UseReqConfig): UseReqConfig` (L627-687)
-- @brief Builds the persisted configuration payload that excludes runtime-derived fields.
-- @details Copies only the canonical persisted configuration keys into a fresh object so runtime-derived metadata such as `base-path` and `git-path` can never be written to disk, serializes per-language static-check objects with key order `enabled` then `checkers`, normalizes `GIT_WORKTREE_PREFIX` plus debug fields including dedicated workflow-event logging, forces persisted worktree disablement when automatic git commit is disabled, forces persisted Pushover disablement until both credentials are populated, and preserves the remaining notification and Pushover settings. Runtime is O(n) in config size. No external state is mutated.
+### fn `function buildPersistedLocalConfig(config: UseReqConfig): UseReqLocalConfig` (L939-966)
+- @brief Builds the persisted local configuration payload.
+- @details Copies only project-scoped keys into a fresh object so runtime-derived metadata plus global checker, tool, git, and notification fields never reach `.pi-usereq.json`. Runtime is O(n) in config size. No external state is mutated.
 - @param[in] config {UseReqConfig} Effective configuration object.
-- @return {UseReqConfig} Persistable configuration payload.
-- @satisfies CTN-012, CTN-013, REQ-146, REQ-163, REQ-204, REQ-205, REQ-212, REQ-215, REQ-234, REQ-236, REQ-237, REQ-238, REQ-239, REQ-249, REQ-277
+- @return {UseReqLocalConfig} Persistable local configuration payload.
+- @satisfies CTN-012, CTN-013, REQ-104, REQ-146, REQ-249, REQ-316, REQ-277
 
-### fn `export function saveConfig(projectBase: string, config: UseReqConfig): void` (L697-701)
-- @brief Persists the project configuration to disk.
-- @details Creates the base directory path when necessary, strips runtime-derived fields from the serialized payload, and writes formatted JSON terminated by a newline to `.pi-usereq.json`. Runtime is O(n) in serialized config size. Side effects include directory creation and file overwrite.
+### fn `function buildPersistedGlobalConfig(config: UseReqConfig): UseReqGlobalConfig` (L975-1014)
+- @brief Builds the persisted global configuration payload.
+- @details Copies only cross-project keys into a fresh object so local directory and debug fields never reach `~/.config/pi-usereq/config.json`, while forcing persisted worktree disablement when automatic git commit is disabled and forcing persisted Pushover disablement until both credentials are populated. Runtime is O(n) in config size. No external state is mutated.
+- @param[in] config {UseReqConfig} Effective configuration object.
+- @return {UseReqGlobalConfig} Persistable global configuration payload.
+- @satisfies REQ-137, REQ-163, REQ-174, REQ-178, REQ-184, REQ-196, REQ-204, REQ-205, REQ-212, REQ-234, REQ-249, REQ-315
+
+### fn `function writeConfigFile(configPath: string, payload: object): void` (L1023-1026)
+- @brief Writes one normalized config payload to disk.
+- @details Creates the parent directory when required, formats JSON with two-space indentation, and terminates the file with a newline. Runtime is O(n) in serialized payload size. Side effects include directory creation and file overwrite.
+- @param[in] configPath {string} Absolute destination config path.
+- @param[in] payload {object} Persistable config payload.
+- @return {void} No return value.
+
+### fn `export function saveLocalConfig(projectBase: string, config: UseReqConfig): void` (L1036-1038)
+- @brief Persists the local configuration scope to disk.
+- @details Serializes only project-scoped fields into `<base-path>/.pi-usereq.json`, excluding runtime-derived metadata and every global-scope configuration key. Runtime is O(n) in serialized local config size. Side effects include directory creation and file overwrite.
 - @param[in] projectBase {string} Absolute project root path.
-- @param[in] config {UseReqConfig} Configuration object to persist.
+- @param[in] config {UseReqConfig} Effective configuration object to persist.
 - @return {void} No return value.
-- @satisfies CTN-012, REQ-146
+- @satisfies CTN-012, REQ-104, REQ-146
+
+### fn `export function saveGlobalConfig(config: UseReqConfig): void` (L1047-1049)
+- @brief Persists the global configuration scope to disk.
+- @details Serializes only cross-project fields into `~/.config/pi-usereq/config.json`, excluding every project-local directory and debug setting. Runtime is O(n) in serialized global config size. Side effects include directory creation and file overwrite.
+- @param[in] config {UseReqConfig} Effective configuration object to persist.
+- @return {void} No return value.
+- @satisfies CTN-012, CTN-018, REQ-137, REQ-146, REQ-315
 
-### fn `export function normalizeConfigPaths(projectBase: string, config: UseReqConfig): UseReqConfig` (L710-728)
+### fn `export function saveConfig(projectBase: string, config: UseReqConfig): void` (L1059-1062)
+- @brief Persists the effective configuration to local and global config files.
+- @details Splits the effective runtime config into project-scoped and cross-project payloads, then writes both files with normalized JSON formatting. Runtime is O(n) in combined serialized config size. Side effects include directory creation and file overwrite in both persistence locations.
+- @param[in] projectBase {string} Absolute project root path.
+- @param[in] config {UseReqConfig} Effective configuration object to persist.
+- @return {void} No return value.
+- @satisfies CTN-012, CTN-018, REQ-137, REQ-146, REQ-315
+
+### fn `export function normalizeConfigPaths(projectBase: string, config: UseReqConfig): UseReqConfig` (L1071-1089)
 - @brief Normalizes persisted directory fields to project-relative forms.
 - @details Rewrites docs, tests, and source directories using project containment heuristics, strips trailing separators, and restores defaults for empty results. Runtime is O(n) in configured path count plus path-length processing. No filesystem writes occur.
 - @param[in] projectBase {string} Absolute project root path.
 - @param[in] config {UseReqConfig} Configuration object to normalize.
 - @return {UseReqConfig} Normalized configuration copy.
 
-### fn `export function buildPromptReplacementPaths(` (L738-780)
+### fn `export function buildPromptReplacementPaths(` (L1099-1141)
 - @brief Builds placeholder replacements for bundled prompt rendering.
 - @details Computes runtime path context from the execution path, derives installation-owned template and guideline paths, enumerates visible guideline files from the installed resource tree, and returns the token map consumed by prompt templates. Runtime is O(g log g + s) where g is guideline count and s is source-directory count. Side effects are limited to filesystem reads.
 - @param[in] projectBase {string} Absolute project root path.
@@ -745,28 +871,49 @@ import { makeRelativeIfContainsProject } from "./utils.js";
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
 |---|---|---|---|---|
-|`StaticCheckEntry`|iface||54-58|export interface StaticCheckEntry|
-|`StaticCheckEnabled`|type||64||
-|`StaticCheckLanguageConfig`|iface||70-73|export interface StaticCheckLanguageConfig|
-|`UseReqConfig`|iface||79-117|export interface UseReqConfig|
-|`cloneStaticCheckEntry`|fn||234-243|function cloneStaticCheckEntry(entry: StaticCheckEntry): ...|
-|`createStaticCheckLanguageConfig`|fn||252-261|export function createStaticCheckLanguageConfig(|
-|`getDefaultStaticCheckConfig`|fn||269-274|export function getDefaultStaticCheckConfig(): Record<str...|
-|`normalizeStaticCheckEnabled`|fn||284-289|export function normalizeStaticCheckEnabled(|
-|`getActiveStaticCheckEntries`|fn||299-308|export function getActiveStaticCheckEntries(|
-|`normalizeAutoGitCommit`|fn||323-325|export function normalizeAutoGitCommit(value: unknown): "...|
-|`normalizeGitWorktreeEnabled`|fn||339-341|export function normalizeGitWorktreeEnabled(value: unknow...|
-|`resolveEffectiveGitWorktreeEnabled`|fn||350-355|export function resolveEffectiveGitWorktreeEnabled(|
-|`normalizeGitWorktreePrefix`|fn||369-375|export function normalizeGitWorktreePrefix(value: unknown...|
-|`getProjectConfigPath`|fn||382-384|export function getProjectConfigPath(projectBase: string)...|
-|`getDefaultConfig`|fn||393-433|export function getDefaultConfig(_projectBase: string): U...|
-|`normalizeStaticCheckEntries`|fn||441-461|function normalizeStaticCheckEntries(value: unknown): Sta...|
-|`normalizeStaticCheckConfig`|fn||470-489|function normalizeStaticCheckConfig(|
-|`loadConfig`|fn||499-618|export function loadConfig(projectBase: string): UseReqCo...|
-|`buildPersistedConfig`|fn||627-687|function buildPersistedConfig(config: UseReqConfig): UseR...|
-|`saveConfig`|fn||697-701|export function saveConfig(projectBase: string, config: U...|
-|`normalizeConfigPaths`|fn||710-728|export function normalizeConfigPaths(projectBase: string,...|
-|`buildPromptReplacementPaths`|fn||738-780|export function buildPromptReplacementPaths(|
+|`StaticCheckEntry`|iface||55-59|export interface StaticCheckEntry|
+|`StaticCheckEnabled`|type||65||
+|`StaticCheckLanguageConfig`|iface||71-74|export interface StaticCheckLanguageConfig|
+|`UseReqConfig`|iface||80-118|export interface UseReqConfig|
+|`LocalStaticCheckLanguageConfig`|iface||124-126|interface LocalStaticCheckLanguageConfig|
+|`GlobalStaticCheckLanguageConfig`|iface||132-134|interface GlobalStaticCheckLanguageConfig|
+|`UseReqLocalConfig`|iface||140-152|interface UseReqLocalConfig|
+|`UseReqGlobalConfig`|iface||158-186|interface UseReqGlobalConfig|
+|`cloneStaticCheckEntry`|fn||303-312|function cloneStaticCheckEntry(entry: StaticCheckEntry): ...|
+|`createStaticCheckLanguageConfig`|fn||321-330|export function createStaticCheckLanguageConfig(|
+|`createLocalStaticCheckLanguageConfig`|fn||338-342|function createLocalStaticCheckLanguageConfig(|
+|`createGlobalStaticCheckLanguageConfig`|fn||350-356|function createGlobalStaticCheckLanguageConfig(|
+|`getDefaultGlobalStaticCheckConfig`|fn||363-368|function getDefaultGlobalStaticCheckConfig(): Record<stri...|
+|`getDefaultLocalStaticCheckConfig`|fn||376-385|function getDefaultLocalStaticCheckConfig(|
+|`mergeStaticCheckConfig`|fn||394-413|function mergeStaticCheckConfig(|
+|`getDefaultStaticCheckConfig`|fn||421-427|export function getDefaultStaticCheckConfig(): Record<str...|
+|`normalizeStaticCheckEnabled`|fn||437-442|export function normalizeStaticCheckEnabled(|
+|`getActiveStaticCheckEntries`|fn||452-461|export function getActiveStaticCheckEntries(|
+|`normalizeAutoGitCommit`|fn||476-478|export function normalizeAutoGitCommit(value: unknown): "...|
+|`normalizeGitWorktreeEnabled`|fn||492-494|export function normalizeGitWorktreeEnabled(value: unknow...|
+|`resolveEffectiveGitWorktreeEnabled`|fn||503-508|export function resolveEffectiveGitWorktreeEnabled(|
+|`normalizeGitWorktreePrefix`|fn||522-528|export function normalizeGitWorktreePrefix(value: unknown...|
+|`getProjectConfigPath`|fn||535-537|export function getProjectConfigPath(projectBase: string)...|
+|`getGlobalConfigPath`|fn||544-546|export function getGlobalConfigPath(): string|
+|`getDefaultLocalConfig`|fn||554-570|function getDefaultLocalConfig(|
+|`getDefaultGlobalConfig`|fn||577-607|function getDefaultGlobalConfig(): UseReqGlobalConfig|
+|`mergeConfigScopes`|fn||616-682|function mergeConfigScopes(|
+|`getDefaultConfig`|fn||691-697|export function getDefaultConfig(_projectBase: string): U...|
+|`normalizeStaticCheckEntries`|fn||705-725|function normalizeStaticCheckEntries(value: unknown): Sta...|
+|`readConfigPayload`|fn||734-750|function readConfigPayload(configPath: string): Record<st...|
+|`normalizeLocalStaticCheckConfig`|fn||760-784|function normalizeLocalStaticCheckConfig(|
+|`normalizeGlobalStaticCheckConfig`|fn||793-810|function normalizeGlobalStaticCheckConfig(|
+|`loadLocalConfig`|fn||819-865|function loadLocalConfig(|
+|`loadGlobalConfig`|fn||872-913|function loadGlobalConfig(): UseReqGlobalConfig|
+|`loadConfig`|fn||923-930|export function loadConfig(projectBase: string): UseReqCo...|
+|`buildPersistedLocalConfig`|fn||939-966|function buildPersistedLocalConfig(config: UseReqConfig):...|
+|`buildPersistedGlobalConfig`|fn||975-1014|function buildPersistedGlobalConfig(config: UseReqConfig)...|
+|`writeConfigFile`|fn||1023-1026|function writeConfigFile(configPath: string, payload: obj...|
+|`saveLocalConfig`|fn||1036-1038|export function saveLocalConfig(projectBase: string, conf...|
+|`saveGlobalConfig`|fn||1047-1049|export function saveGlobalConfig(config: UseReqConfig): void|
+|`saveConfig`|fn||1059-1062|export function saveConfig(projectBase: string, config: U...|
+|`normalizeConfigPaths`|fn||1071-1089|export function normalizeConfigPaths(projectBase: string,...|
+|`buildPromptReplacementPaths`|fn||1099-1141|export function buildPromptReplacementPaths(|
 
 
 ---
@@ -1127,7 +1274,7 @@ import {
 
 ---
 
-# extension-status.ts | TypeScript | 823L | 43 symbols | 5 imports | 45 comments
+# extension-status.ts | TypeScript | 880L | 46 symbols | 6 imports | 48 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, active-branch lookup, run timing, and deterministic status-bar formatting for the pi-usereq extension. Runtime
@@ -1139,6 +1286,7 @@ scheduling through exported controller helpers.
 ```
 import type {
 import type { UseReqConfig } from "./config.js";
+import type { PiNotifySoundLevel } from "./pi-notify.js";
 import type { PromptCommandExecutionPlan } from "./prompt-command-runtime.js";
 import {
 import { resolveRuntimeGitBranchName } from "./runtime-project-paths.js";
@@ -1146,120 +1294,120 @@ import { resolveRuntimeGitBranchName } from "./runtime-project-paths.js";
 
 ## Definitions
 
-- type `type StatusForegroundColor = Extract<` (L30)
+- type `type StatusForegroundColor = Extract<` (L31)
 - @brief Enumerates the CLI-supported theme tokens consumed by status rendering.
 - @details Restricts the status formatter to documented pi theme tokens so the
 status bar remains compatible with the active CLI theme schema. Compile-time
 only and introduces no runtime cost.
-### iface `interface RawStatusTheme` (L40-42)
+### iface `interface RawStatusTheme` (L41-43)
 - @brief Describes the raw theme capabilities required for status rendering.
 - @details Accepts the `ctx.ui.theme` foreground renderer used by the
 single-line footer. Compile-time only and introduces no runtime cost.
 
-### iface `interface StatusThemeAdapter` (L50-55)
+### iface `interface StatusThemeAdapter` (L51-56)
 - @brief Describes the normalized theme adapter used by status formatters.
 - @details Exposes deterministic label, value, foreground, and separator
 renderers so status text generation stays independent from the raw theme API.
 Compile-time only and introduces no runtime cost.
 
-- type `export type PiUsereqStatusHookName = (typeof PI_USEREQ_STATUS_HOOK_NAMES)[number];` (L98)
+- type `export type PiUsereqStatusHookName = (typeof PI_USEREQ_STATUS_HOOK_NAMES)[number];` (L99)
 - @brief Represents one hook name handled by the pi-usereq status controller.
 - @details Narrows hook registration and event-update calls to the canonical
 intercepted-hook set. Compile-time only and introduces no runtime cost.
-- type `export type PiUsereqPromptRequest = PromptCommandExecutionPlan;` (L104)
+- type `export type PiUsereqPromptRequest = PromptCommandExecutionPlan;` (L105)
 - @brief Describes one prompt request tracked across extension command delivery and runtime execution.
 - @details Reuses the prepared prompt-command execution plan so status rendering and prompt-end side effects can recover the original project base, active execution base, and optional worktree metadata for the current prompt run. The alias is compile-time only and introduces no runtime cost.
-- type `export type PiUsereqWorkflowState = "idle" | "checking" | "running" | "merging" | "error";` (L110)
+- type `export type PiUsereqWorkflowState = "idle" | "checking" | "running" | "merging" | "error";` (L111)
 - @brief Represents one prompt-orchestration workflow state displayed in the status bar.
 - @details Narrows workflow tracking to the documented `idle`, `checking`, `running`, `merging`, and `error` states reused by prompt-command gating, prompt-end orchestration, and status rendering. Compile-time only and introduces no runtime cost.
-### iface `export interface PiUsereqStatusState` (L116-124)
+### iface `export interface PiUsereqStatusState` (L117-126)
 - @brief Stores the mutable runtime facts displayed by the status bar.
-- @details Persists the prompt-orchestration workflow state, the latest context-usage snapshot, the active run start timestamp, the most recent normally completed run duration, the accumulated duration of all normally completed runs, and prompt-request metadata carried from command dispatch into the next runtime execution. Runtime state is mutated in-place by controller helpers. Compile-time only and introduces no runtime cost.
+- @details Persists the prompt-orchestration workflow state, the latest context-usage snapshot, the active run start timestamp, the most recent normally completed run duration, the accumulated duration of all normally completed runs, the in-memory runtime sound level, and prompt-request metadata carried from command dispatch into the next runtime execution. Runtime state is mutated in-place by controller helpers. Compile-time only and introduces no runtime cost.
 
-### iface `export interface PiUsereqStatusController` (L133-138)
+### iface `export interface PiUsereqStatusController` (L135-140)
 - @brief Stores the controller state required for event-driven status updates.
 - @details Keeps the mutable status snapshot, the current configuration, the
 latest extension context used for rendering, and the interval handle used
 for live elapsed-time refreshes. Compile-time only and introduces no runtime
 cost.
 
-### iface `interface PiUsereqStatusPersistenceStore` (L144-147)
+### iface `interface PiUsereqStatusPersistenceStore` (L146-149)
 - @brief Stores the process-scoped elapsed-timer snapshot reused across session replacement.
 - @details Preserves only the latest completed duration and accumulated completed runtime so `/new`, `/resume`, and `/fork` can restore elapsed counters after the extension runtime is rebound. Compile-time only and introduces no runtime cost.
 
-### fn `function getPiUsereqStatusPersistenceStore(): PiUsereqStatusPersistenceStore` (L161-170)
+### fn `function getPiUsereqStatusPersistenceStore(): PiUsereqStatusPersistenceStore` (L163-172)
 - @brief Returns the process-scoped elapsed-timer persistence store.
 - @details Lazily initializes one internal `globalThis` record because pi rebinds extension modules for `/new`, `/resume`, `/fork`, and `/reload`, but the hosting process persists across those operations. Runtime is O(1). Side effect: initializes internal process-scoped state on first access.
 - @return {PiUsereqStatusPersistenceStore} Mutable persistence record.
 - @note Design rationale: required to preserve elapsed counters across session replacement without writing session-global menu state into project configuration.
 
-### fn `function restorePersistedElapsedState(state: PiUsereqStatusState): void` (L178-182)
+### fn `function restorePersistedElapsedState(state: PiUsereqStatusState): void` (L180-184)
 - @brief Restores persisted elapsed counters into one mutable status snapshot.
 - @details Copies the process-scoped last-run and accumulated completed durations into the supplied controller state so rebinding events can continue showing prior counters. Runtime is O(1). Side effect: mutates `state`.
 - @param[in,out] state {PiUsereqStatusState} Mutable status state.
 - @return {void} No return value.
 
-### fn `function persistElapsedState(state: PiUsereqStatusState): void` (L190-194)
+### fn `function persistElapsedState(state: PiUsereqStatusState): void` (L192-196)
 - @brief Persists elapsed counters from one mutable status snapshot.
 - @details Copies the current last-run and accumulated completed durations into the process-scoped store so later extension instances can restore them after session replacement. Runtime is O(1). Side effect: mutates internal process-scoped state.
 - @param[in] state {PiUsereqStatusState} Mutable status state snapshot.
 - @return {void} No return value.
 
-### fn `function persistPromptCommandState(state: PiUsereqStatusState): void` (L202-208)
+### fn `function persistPromptCommandState(state: PiUsereqStatusState): void` (L204-210)
 - @brief Mirrors one controller prompt state into the process-scoped persistence store.
 - @details Persists the current workflow state plus the pending and active prompt execution plans so prompt orchestration can survive session replacement. Runtime is O(1). Side effect: mutates process-scoped prompt-command persistence state.
 - @param[in] state {PiUsereqStatusState} Current controller state snapshot.
 - @return {void} No return value.
 
-### fn `export function shouldPreservePromptCommandStateOnShutdown(state: PiUsereqStatusState): boolean` (L217-220)
+### fn `export function shouldPreservePromptCommandStateOnShutdown(state: PiUsereqStatusState): boolean` (L219-222)
 - @brief Detects whether `session_shutdown` must preserve prompt-command state.
 - @details Keeps both the in-memory controller prompt state and the process-scoped prompt execution plan intact while pi switches from the original session into the forked execution session, because the old extension instance can keep running the initiating command handler after `session_shutdown` fires and before the replacement session fully takes over. Runtime is O(1). No external state is mutated.
 - @param[in] state {PiUsereqStatusState} Controller state before shutdown mutation.
 - @return {boolean} `true` when prompt-command state must survive the shutdown event.
 - @satisfies REQ-278
 
-### fn `function restorePersistedPromptCommandState(` (L229-240)
+### fn `function restorePersistedPromptCommandState(` (L231-242)
 - @brief Restores prompt-command persistence into one fresh controller when the active session matches.
 - @details Rehydrates workflow state plus pending or active prompt execution plans only when the current session file targets the persisted execution session created for prompt orchestration. Runtime is O(1). Side effect: mutates `state` when persisted prompt state is available.
 - @param[in] sessionFile {string | undefined} Current active session file.
 - @param[in,out] state {PiUsereqStatusState} Mutable controller state.
 - @return {void} No return value.
 
-### fn `function getContextSessionFile(ctx: ExtensionContext): string | undefined` (L248-252)
+### fn `function getContextSessionFile(ctx: ExtensionContext): string | undefined` (L250-254)
 - @brief Resolves the active session file exposed by one extension context.
 - @details Reads the session-manager session-file getter when available so prompt-command persistence can be resynchronized on every lifecycle hook after session replacement. Runtime is O(1). No external state is mutated.
 - @param[in] ctx {ExtensionContext} Active extension context.
 - @return {string | undefined} Current session file when available.
 
-### fn `export function isStaleExtensionContextError(error: unknown): boolean` (L261-264)
+### fn `export function isStaleExtensionContextError(error: unknown): boolean` (L263-266)
 - @brief Detects stale extension-context access after session replacement.
 - @details Matches the guarded pi runtime error emitted when one invalidated extension context, command context, or replacement-session context is accessed after session replacement or reload. Runtime is O(n) in message length only when an error is supplied. No external state is mutated.
 - @param[in] error {unknown} Candidate thrown value.
 - @return {boolean} `true` when the value matches the stale-extension-context runtime error.
 - @satisfies REQ-280
 
-### fn `function resetElapsedState(state: PiUsereqStatusState): void` (L273-277)
+### fn `function resetElapsedState(state: PiUsereqStatusState): void` (L275-279)
 - @brief Resets the in-memory and persisted elapsed counters.
 - @details Clears both completed-duration fields in the supplied state and mirrors that cleared snapshot into the process-scoped store. Runtime is O(1). Side effects include mutable state reset and process-scoped persistence update.
 - @param[in,out] state {PiUsereqStatusState} Mutable status state.
 - @return {void} No return value.
 - @satisfies REQ-217
 
-### fn `function shouldResetElapsedStateOnSessionStart(event: unknown): boolean` (L286-289)
+### fn `function shouldResetElapsedStateOnSessionStart(event: unknown): boolean` (L288-291)
 - @brief Detects whether a `session_start` event must reset elapsed counters.
 - @details Treats `startup` and `reload` as hard-reset boundaries while preserving counters for `new`, `resume`, and `fork`. Runtime is O(1). No external state is mutated.
 - @param[in] event {unknown} Session-start payload.
 - @return {boolean} `true` when elapsed counters must reset.
 - @satisfies REQ-217
 
-### fn `function shouldResetWorkflowStateOnSessionStart(event: unknown): boolean` (L298-301)
+### fn `function shouldResetWorkflowStateOnSessionStart(event: unknown): boolean` (L300-303)
 - @brief Detects whether a `session_start` event must reset the workflow state to `idle`.
 - @details Treats `startup`, `new`, and `reload` as workflow-reset boundaries so prompt-orchestration state never leaks across boot, explicit session replacement, or extension reload. Runtime is O(1). No external state is mutated.
 - @param[in] event {unknown} Session-start payload.
 - @return {boolean} `true` when workflow state must reset to `idle`.
 - @satisfies REQ-009, REQ-221
 
-### fn `function createStatusThemeAdapter(theme: RawStatusTheme): StatusThemeAdapter` (L311-320)
+### fn `function createStatusThemeAdapter(theme: RawStatusTheme): StatusThemeAdapter` (L313-322)
 - @brief Builds the normalized theme adapter used by pi-usereq status formatters.
 - @details Precomputes label, value, foreground, and separator renderers so
 status formatting remains stable across real TUI themes and deterministic
@@ -1267,16 +1415,16 @@ test doubles. Runtime is O(1). No external state is mutated.
 - @param[in] theme {RawStatusTheme} Raw theme implementation from `ctx.ui.theme`.
 - @return {StatusThemeAdapter} Normalized status-theme adapter.
 
-### fn `const colorize = (color: StatusForegroundColor, text: string): string =>` (L312-319)
+### fn `const colorize = (color: StatusForegroundColor, text: string): string =>` (L314-321)
 
-### fn `function resolveStatusBranchValue(ctx: ExtensionContext): string` (L329-331)
+### fn `function resolveStatusBranchValue(ctx: ExtensionContext): string` (L331-333)
 - @brief Resolves the active git branch value rendered in the status bar.
 - @details Reads the current branch from the active context working directory on every status render so worktree switches and restored base-session renders expose the latest branch immediately. Runtime is dominated by git execution when the working directory belongs to a repository. Side effects include subprocess creation.
 - @param[in] ctx {ExtensionContext} Active extension context.
 - @return {string} Active branch name or `unknown` when unavailable.
 - @satisfies REQ-121, REQ-283
 
-### fn `function normalizeContextUsage(` (L342-359)
+### fn `function normalizeContextUsage(` (L344-361)
 - @brief Normalizes one raw context-usage snapshot.
 - @details Preserves the runtime token and context-window counts, derives a
 percentage when the runtime omits it, clamps negative percentages to `0`,
@@ -1285,7 +1433,7 @@ external state is mutated.
 - @param[in] contextUsage {ContextUsage | undefined} Raw runtime snapshot.
 - @return {ContextUsage | undefined} Normalized snapshot.
 
-### fn `function refreshContextUsage(` (L371-376)
+### fn `function refreshContextUsage(` (L373-378)
 - @brief Refreshes the stored context-usage snapshot from the active extension context.
 - @details Calls `ctx.getContextUsage()` on every intercepted event so the
 controller retains the newest context-usage facts available from the pi
@@ -1295,22 +1443,22 @@ runtime. Runtime is O(1). Side effect: mutates `state.contextUsage`.
 - @return {void} No return value.
 - @satisfies REQ-118, REQ-119
 
-### fn `function resolveContextUsageIconText(` (L385-402)
+### fn `function resolveContextUsageIconText(` (L387-404)
 - @brief Resolves the icon text for one normalized context-usage snapshot.
 - @details Maps context usage to one fixed-width icon band so footer rendering remains compact and deterministic across the documented `0`, `>0-<25`, `>=25-<50`, `>=50-<75`, and `>=75` percent bands. Unavailable usage degrades to the `0%` icon. Runtime is O(1). No external state is mutated.
 - @param[in] contextUsage {ContextUsage | undefined} Normalized context snapshot.
 - @return {string} Fixed-width gauge icon text.
 - @satisfies REQ-122, REQ-284
 
-### fn `function formatContextUsageBar(` (L412-424)
+### fn `function formatContextUsageBar(` (L414-426)
 - @brief Formats one icon-based context-usage gauge.
-- @details Renders the documented gauge icon with theme `error` for `>=90%`, enables terminal blink only for `>=100%`, and otherwise leaves the gauge in the default terminal color. Runtime is O(1). No external state is mutated.
+- @details Renders the documented gauge icon with the same non-error status-value theme token used by `status` below `90%`, switches to theme `error` for `>=90%`, and enables terminal blink only for `>=100%`. 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 fixed-width gauge icon.
 - @satisfies REQ-122, REQ-126, REQ-127, REQ-128, REQ-233, REQ-284
 
-### fn `function formatStatusDuration(durationMs: number): string` (L435-440)
+### fn `function formatStatusDuration(durationMs: number): string` (L437-442)
 - @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
@@ -1319,7 +1467,7 @@ mutated.
 - @return {string} Duration rendered as `M:SS`.
 - @satisfies REQ-125
 
-### fn `function formatCompletedStatusDuration(` (L451-455)
+### fn `function formatCompletedStatusDuration(` (L453-457)
 - @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
@@ -1328,7 +1476,7 @@ timer receives a normally completed prompt duration, then delegates to
 - @return {string} Rendered duration or unset placeholder.
 - @satisfies REQ-124
 
-### fn `function formatElapsedStatusValue(` (L468-478)
+### fn `function formatElapsedStatusValue(` (L470-480)
 - @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
@@ -1339,7 +1487,7 @@ mutated.
 - @return {string} Consolidated `elapsed` field value.
 - @satisfies REQ-123, REQ-124, REQ-125, REQ-159
 
-### fn `function formatStatusField(` (L489-495)
+### fn `function formatStatusField(` (L491-497)
 - @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.
@@ -1348,7 +1496,7 @@ color. Runtime is O(n) in combined text length. No external state is mutated.
 - @param[in] value {string} Unstyled field value.
 - @return {string} Rendered status-field fragment.
 
-### fn `function formatRenderedStatusField(` (L507-513)
+### fn `function formatRenderedStatusField(` (L509-515)
 - @brief Formats one pre-rendered status-bar field value.
 - @details Preserves the accent-colored field label while allowing callers to
 provide a custom styled value such as the context-usage bar. Runtime is O(n)
@@ -1358,7 +1506,7 @@ in combined text length. No external state is mutated.
 - @param[in] renderedValue {string} Pre-rendered field value.
 - @return {string} Rendered status-field fragment.
 
-### fn `function formatWorkflowStateValue(` (L523-531)
+### fn `function formatWorkflowStateValue(` (L525-533)
 - @brief Formats the rendered workflow-state value for the `status` field.
 - @details Uses the standard warning-colored value renderer for non-error states and emits a blinking `error`-colored value for `status:error` so the footer highlights orchestration failures immediately. Runtime is O(n) in text length. No external state is mutated.
 - @param[in] theme {StatusThemeAdapter} Normalized status theme.
@@ -1366,7 +1514,7 @@ in combined text length. No external state is mutated.
 - @return {string} Rendered workflow-state value.
 - @satisfies REQ-112, REQ-223
 
-### fn `function didAgentEndAbort(messages: AgentEndEvent["messages"]): boolean` (L542-549)
+### fn `function didAgentEndAbort(messages: AgentEndEvent["messages"]): boolean` (L544-551)
 - @brief Detects whether an agent run ended through abort semantics.
 - @details Treats any assistant message whose `stopReason` equals `aborted` as
 an escape-triggered termination that must not overwrite the `last` timer.
@@ -1375,9 +1523,17 @@ 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(` (L562-586)
+### fn `function resolvePiUsereqRuntimeSoundLevel(` (L561-566)
+- @brief Resolves the active runtime sound level used by status and notify flows.
+- @details Prefers the mutable runtime sound state, then falls back to the cached persisted boot value, and finally defaults to `none` before `session_start` loads configuration. Runtime is O(1). No external state is mutated.
+- @param[in] state {PiUsereqStatusState} Mutable status state snapshot.
+- @param[in] config {UseReqConfig | undefined} Cached project configuration.
+- @return {PiNotifySoundLevel} Active runtime sound level.
+- @satisfies REQ-180, REQ-285
+
+### fn `function buildPiUsereqStatusText(` (L579-603)
 - @brief Builds the full single-line pi-usereq status-bar payload.
-- @details Renders status, branch, context, elapsed, and sound fields in the canonical order with dim bullet separators, workflow-state highlighting, and the documented icon-based context gauge. Runtime is O(1). No external state is mutated.
+- @details Renders status, branch, context, elapsed, and sound fields in the canonical order with dim bullet separators, workflow-state highlighting, the documented icon-based context gauge, and the active runtime sound level instead of the persisted boot value. Runtime is O(1). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @param[in] theme {StatusThemeAdapter} Normalized status theme.
 - @param[in] state {PiUsereqStatusState} Mutable status state snapshot.
@@ -1386,7 +1542,7 @@ Runtime is O(n) in message count. No external state is mutated.
 - @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-156, REQ-159, REQ-180, REQ-222, REQ-223, REQ-233, REQ-283, REQ-284
 
-### fn `function stopStatusTicker(controller: PiUsereqStatusController): void` (L596-601)
+### fn `function stopStatusTicker(controller: PiUsereqStatusController): void` (L613-618)
 - @brief Stops the live elapsed-time ticker when it is active.
 - @details Clears the interval handle and resets the stored timer reference so
 subsequent runs can reinitialize live status refreshes deterministically.
@@ -1394,7 +1550,7 @@ Runtime is O(1). Side effect: mutates `controller.tickHandle`.
 - @param[in,out] controller {PiUsereqStatusController} Mutable status controller.
 - @return {void} No return value.
 
-### fn `function syncPiUsereqStatusTicker(` (L613-629)
+### fn `function syncPiUsereqStatusTicker(` (L630-646)
 - @brief Synchronizes the live elapsed-time ticker with the current run state.
 - @details Starts a 1-second render ticker while a run is active and stops the
 ticker when the run returns to idle. Runtime is O(1). Side effects include
@@ -1404,31 +1560,48 @@ ticks.
 - @return {void} No return value.
 - @satisfies REQ-123
 
-### fn `export function createPiUsereqStatusController(): PiUsereqStatusController` (L637-652)
+### fn `export function createPiUsereqStatusController(): PiUsereqStatusController` (L654-670)
 - @brief Creates an empty pi-usereq status controller.
-- @details Initializes the mutable status snapshot, including empty prompt-request tracking, and starts with no config, no context, and no live ticker. Runtime is O(1). No external state is mutated.
+- @details Initializes the mutable status snapshot, including empty prompt-request tracking and an unset runtime sound level that later loads from persisted config during `session_start`, and starts with no config, no context, and no live ticker. Runtime is O(1). No external state is mutated.
 - @return {PiUsereqStatusController} New status controller.
 - @satisfies DES-010
 
-### fn `export function setPiUsereqStatusConfig(` (L664-669)
+### fn `export function setPiUsereqStatusConfig(` (L683-688)
 - @brief Stores the effective project configuration used by status rendering.
 - @details Replaces the controller's cached configuration so later status
-renders reuse the latest docs, tests, source-path, and pi-notify values
-without reading from disk on every event. Runtime is O(1). Side effect:
+renders reuse the latest docs, tests, source-path, and persisted pi-notify
+values without reading from disk on every event, while leaving the active
+runtime sound level in `controller.state`. Runtime is O(1). Side effect:
 mutates `controller.config`.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @param[in,out] controller {PiUsereqStatusController} Mutable status controller.
 - @return {void} No return value.
 
-### fn `export function renderPiUsereqStatus(` (L679-709)
+### fn `export function getPiUsereqRuntimeSoundLevel(` (L697-701)
+- @brief Returns the active runtime sound level tracked by the status controller.
+- @details Exposes the in-memory runtime sound state so shortcut handlers and prompt-end notification dispatch can stay decoupled from the persisted boot value stored in global configuration. Runtime is O(1). No external state is mutated.
+- @param[in] controller {PiUsereqStatusController} Mutable status controller.
+- @return {PiNotifySoundLevel} Active runtime sound level.
+- @satisfies REQ-180, REQ-285
+
+### fn `export function setPiUsereqRuntimeSoundLevel(` (L712-722)
+- @brief Stores one new runtime sound level and refreshes the status bar.
+- @details Mutates only the in-memory runtime sound state so shortcut-driven sound changes do not update persisted local or global configuration, then re-renders the footer when an active extension context is available. Runtime is O(1). Side effect: mutates `controller.state.runtimeSoundLevel` and may update `ctx.ui` status.
+- @param[in] runtimeSoundLevel {PiNotifySoundLevel} Next active runtime sound level.
+- @param[in] ctx {ExtensionContext | undefined} Optional active extension context.
+- @param[in,out] controller {PiUsereqStatusController} Mutable status controller.
+- @return {void} No return value.
+- @satisfies REQ-180, REQ-286, REQ-287
+
+### fn `export function renderPiUsereqStatus(` (L732-763)
 - @brief Renders the current pi-usereq status bar into the active UI context.
-- @details Updates the controller's latest context pointer and writes the single-line status text only when configuration is available, including the active branch field and documented icon-based context gauge. When pi has already invalidated the supplied context after session replacement or reload, the helper clears the stale cached context and returns without surfacing the stale-instance exception. Runtime is O(1) plus git execution for branch refresh. Side effect: mutates `ctx.ui` status when the context is still active.
+- @details Updates the controller's latest context pointer, refreshes the live `getContextUsage()` snapshot for direct render call sites that do not pass through `updateExtensionStatus(...)`, and writes the single-line status text only when configuration is available, including the active branch field, documented icon-based context gauge, and active runtime sound level. When pi has already invalidated the supplied context after session replacement or reload, the helper clears the stale cached context and returns without surfacing the stale-instance exception. Runtime is O(1) plus git execution for branch refresh. Side effect: mutates `controller.state.contextUsage` and `ctx.ui` status when the context is still active.
 - @param[in] ctx {ExtensionContext} Active extension context.
 - @param[in,out] controller {PiUsereqStatusController} Mutable status controller.
 - @return {void} No return value.
-- @satisfies REQ-120, REQ-121, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-159, REQ-180, REQ-233, REQ-280, REQ-283, REQ-284
+- @satisfies REQ-118, REQ-119, REQ-120, REQ-121, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-159, REQ-180, REQ-233, REQ-280, REQ-283, REQ-284
 
-### fn `export function setPiUsereqWorkflowState(` (L720-731)
+### fn `export function setPiUsereqWorkflowState(` (L774-785)
 - @brief Transitions the prompt-orchestration workflow state and refreshes the status bar.
 - @details Mutates the tracked workflow state, preserves the latest extension context when available, and re-renders the single-line footer immediately so internal command transitions and pi lifecycle transitions stay visible to the user. Runtime is O(1). Side effect: mutates workflow state and may update `ctx.ui` status.
 - @param[in] workflowState {PiUsereqWorkflowState} Next workflow state.
@@ -1437,17 +1610,17 @@ mutates `controller.config`.
 - @return {void} No return value.
 - @satisfies REQ-221, REQ-222, REQ-223
 
-### fn `export function updateExtensionStatus(` (L743-807)
+### fn `export function updateExtensionStatus(` (L797-864)
 - @brief Updates mutable status state for one intercepted lifecycle hook.
-- @details Refreshes stored context usage on every hook, resets or restores persisted elapsed counters during `session_start`, restores persisted prompt-command metadata when the active session matches a forked execution session, resynchronizes that metadata on later lifecycle hooks so post-switch workflow transitions performed by the initiating command handler become visible to the replacement-session runtime, resets workflow state to `idle` for documented session-start reasons, starts run timing on `agent_start`, promotes pending prompt-request metadata into the active run, captures non-aborted run duration on `agent_end`, accumulates successful runtime into `Σ`, preserves in-memory prompt-command state plus process-scoped persistence across switch-triggered `session_shutdown`, tolerates stale post-replacement render contexts, synchronizes the live ticker, and re-renders the status bar when configuration is available. Runtime is O(n) in `agent_end` message count and otherwise O(1). Side effects include in-memory state mutation, interval scheduling, process-scoped persistence mutation, and footer-status updates.
+- @details Refreshes stored context usage on every hook, resets or restores persisted elapsed counters during `session_start`, loads the active runtime sound level from persisted config during `session_start`, restores persisted prompt-command metadata when the active session matches a forked execution session, resynchronizes that metadata on later lifecycle hooks so post-switch workflow transitions performed by the initiating command handler become visible to the replacement-session runtime, resets workflow state to `idle` for documented session-start reasons, starts run timing on `agent_start`, promotes pending prompt-request metadata into the active run, captures non-aborted run duration on `agent_end`, accumulates successful runtime into `Σ`, preserves in-memory prompt-command state plus process-scoped persistence across switch-triggered `session_shutdown`, tolerates stale post-replacement render contexts, synchronizes the live ticker, and re-renders the status bar when configuration is available. Runtime is O(n) in `agent_end` message count and otherwise O(1). Side effects include in-memory state mutation, interval scheduling, process-scoped persistence mutation, and footer-status updates.
 - @param[in] hookName {PiUsereqStatusHookName} Intercepted hook name.
 - @param[in] event {unknown} Hook payload forwarded from the wrapper.
 - @param[in] ctx {ExtensionContext} Active extension context.
 - @param[in,out] controller {PiUsereqStatusController} Mutable status controller.
 - @return {void} No return value.
-- @satisfies REQ-009, REQ-117, REQ-118, REQ-119, REQ-123, REQ-124, REQ-125, REQ-159, REQ-169, REQ-217, REQ-221, REQ-278, REQ-279, REQ-280
+- @satisfies REQ-009, REQ-117, REQ-118, REQ-119, REQ-123, REQ-124, REQ-125, REQ-159, REQ-169, REQ-217, REQ-221, REQ-278, REQ-279, REQ-280, REQ-285
 
-### fn `export function disposePiUsereqStatusController(` (L818-823)
+### fn `export function disposePiUsereqStatusController(` (L875-880)
 - @brief Disposes the pi-usereq status controller.
 - @details Stops the live ticker, clears the cached context pointer, and leaves
 the last captured status snapshot available for inspection until the
@@ -1459,49 +1632,52 @@ limited to interval disposal and in-memory state mutation.
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
 |---|---|---|---|---|
-|`StatusForegroundColor`|type||30||
-|`RawStatusTheme`|iface||40-42|interface RawStatusTheme|
-|`StatusThemeAdapter`|iface||50-55|interface StatusThemeAdapter|
-|`PiUsereqStatusHookName`|type||98||
-|`PiUsereqPromptRequest`|type||104||
-|`PiUsereqWorkflowState`|type||110||
-|`PiUsereqStatusState`|iface||116-124|export interface PiUsereqStatusState|
-|`PiUsereqStatusController`|iface||133-138|export interface PiUsereqStatusController|
-|`PiUsereqStatusPersistenceStore`|iface||144-147|interface PiUsereqStatusPersistenceStore|
-|`getPiUsereqStatusPersistenceStore`|fn||161-170|function getPiUsereqStatusPersistenceStore(): PiUsereqSta...|
-|`restorePersistedElapsedState`|fn||178-182|function restorePersistedElapsedState(state: PiUsereqStat...|
-|`persistElapsedState`|fn||190-194|function persistElapsedState(state: PiUsereqStatusState):...|
-|`persistPromptCommandState`|fn||202-208|function persistPromptCommandState(state: PiUsereqStatusS...|
-|`shouldPreservePromptCommandStateOnShutdown`|fn||217-220|export function shouldPreservePromptCommandStateOnShutdow...|
-|`restorePersistedPromptCommandState`|fn||229-240|function restorePersistedPromptCommandState(|
-|`getContextSessionFile`|fn||248-252|function getContextSessionFile(ctx: ExtensionContext): st...|
-|`isStaleExtensionContextError`|fn||261-264|export function isStaleExtensionContextError(error: unkno...|
-|`resetElapsedState`|fn||273-277|function resetElapsedState(state: PiUsereqStatusState): void|
-|`shouldResetElapsedStateOnSessionStart`|fn||286-289|function shouldResetElapsedStateOnSessionStart(event: unk...|
-|`shouldResetWorkflowStateOnSessionStart`|fn||298-301|function shouldResetWorkflowStateOnSessionStart(event: un...|
-|`createStatusThemeAdapter`|fn||311-320|function createStatusThemeAdapter(theme: RawStatusTheme):...|
-|`colorize`|fn||312-319|const colorize = (color: StatusForegroundColor, text: str...|
-|`resolveStatusBranchValue`|fn||329-331|function resolveStatusBranchValue(ctx: ExtensionContext):...|
-|`normalizeContextUsage`|fn||342-359|function normalizeContextUsage(|
-|`refreshContextUsage`|fn||371-376|function refreshContextUsage(|
-|`resolveContextUsageIconText`|fn||385-402|function resolveContextUsageIconText(|
-|`formatContextUsageBar`|fn||412-424|function formatContextUsageBar(|
-|`formatStatusDuration`|fn||435-440|function formatStatusDuration(durationMs: number): string|
-|`formatCompletedStatusDuration`|fn||451-455|function formatCompletedStatusDuration(|
-|`formatElapsedStatusValue`|fn||468-478|function formatElapsedStatusValue(|
-|`formatStatusField`|fn||489-495|function formatStatusField(|
-|`formatRenderedStatusField`|fn||507-513|function formatRenderedStatusField(|
-|`formatWorkflowStateValue`|fn||523-531|function formatWorkflowStateValue(|
-|`didAgentEndAbort`|fn||542-549|function didAgentEndAbort(messages: AgentEndEvent["messag...|
-|`buildPiUsereqStatusText`|fn||562-586|function buildPiUsereqStatusText(|
-|`stopStatusTicker`|fn||596-601|function stopStatusTicker(controller: PiUsereqStatusContr...|
-|`syncPiUsereqStatusTicker`|fn||613-629|function syncPiUsereqStatusTicker(|
-|`createPiUsereqStatusController`|fn||637-652|export function createPiUsereqStatusController(): PiUsere...|
-|`setPiUsereqStatusConfig`|fn||664-669|export function setPiUsereqStatusConfig(|
-|`renderPiUsereqStatus`|fn||679-709|export function renderPiUsereqStatus(|
-|`setPiUsereqWorkflowState`|fn||720-731|export function setPiUsereqWorkflowState(|
-|`updateExtensionStatus`|fn||743-807|export function updateExtensionStatus(|
-|`disposePiUsereqStatusController`|fn||818-823|export function disposePiUsereqStatusController(|
+|`StatusForegroundColor`|type||31||
+|`RawStatusTheme`|iface||41-43|interface RawStatusTheme|
+|`StatusThemeAdapter`|iface||51-56|interface StatusThemeAdapter|
+|`PiUsereqStatusHookName`|type||99||
+|`PiUsereqPromptRequest`|type||105||
+|`PiUsereqWorkflowState`|type||111||
+|`PiUsereqStatusState`|iface||117-126|export interface PiUsereqStatusState|
+|`PiUsereqStatusController`|iface||135-140|export interface PiUsereqStatusController|
+|`PiUsereqStatusPersistenceStore`|iface||146-149|interface PiUsereqStatusPersistenceStore|
+|`getPiUsereqStatusPersistenceStore`|fn||163-172|function getPiUsereqStatusPersistenceStore(): PiUsereqSta...|
+|`restorePersistedElapsedState`|fn||180-184|function restorePersistedElapsedState(state: PiUsereqStat...|
+|`persistElapsedState`|fn||192-196|function persistElapsedState(state: PiUsereqStatusState):...|
+|`persistPromptCommandState`|fn||204-210|function persistPromptCommandState(state: PiUsereqStatusS...|
+|`shouldPreservePromptCommandStateOnShutdown`|fn||219-222|export function shouldPreservePromptCommandStateOnShutdow...|
+|`restorePersistedPromptCommandState`|fn||231-242|function restorePersistedPromptCommandState(|
+|`getContextSessionFile`|fn||250-254|function getContextSessionFile(ctx: ExtensionContext): st...|
+|`isStaleExtensionContextError`|fn||263-266|export function isStaleExtensionContextError(error: unkno...|
+|`resetElapsedState`|fn||275-279|function resetElapsedState(state: PiUsereqStatusState): void|
+|`shouldResetElapsedStateOnSessionStart`|fn||288-291|function shouldResetElapsedStateOnSessionStart(event: unk...|
+|`shouldResetWorkflowStateOnSessionStart`|fn||300-303|function shouldResetWorkflowStateOnSessionStart(event: un...|
+|`createStatusThemeAdapter`|fn||313-322|function createStatusThemeAdapter(theme: RawStatusTheme):...|
+|`colorize`|fn||314-321|const colorize = (color: StatusForegroundColor, text: str...|
+|`resolveStatusBranchValue`|fn||331-333|function resolveStatusBranchValue(ctx: ExtensionContext):...|
+|`normalizeContextUsage`|fn||344-361|function normalizeContextUsage(|
+|`refreshContextUsage`|fn||373-378|function refreshContextUsage(|
+|`resolveContextUsageIconText`|fn||387-404|function resolveContextUsageIconText(|
+|`formatContextUsageBar`|fn||414-426|function formatContextUsageBar(|
+|`formatStatusDuration`|fn||437-442|function formatStatusDuration(durationMs: number): string|
+|`formatCompletedStatusDuration`|fn||453-457|function formatCompletedStatusDuration(|
+|`formatElapsedStatusValue`|fn||470-480|function formatElapsedStatusValue(|
+|`formatStatusField`|fn||491-497|function formatStatusField(|
+|`formatRenderedStatusField`|fn||509-515|function formatRenderedStatusField(|
+|`formatWorkflowStateValue`|fn||525-533|function formatWorkflowStateValue(|
+|`didAgentEndAbort`|fn||544-551|function didAgentEndAbort(messages: AgentEndEvent["messag...|
+|`resolvePiUsereqRuntimeSoundLevel`|fn||561-566|function resolvePiUsereqRuntimeSoundLevel(|
+|`buildPiUsereqStatusText`|fn||579-603|function buildPiUsereqStatusText(|
+|`stopStatusTicker`|fn||613-618|function stopStatusTicker(controller: PiUsereqStatusContr...|
+|`syncPiUsereqStatusTicker`|fn||630-646|function syncPiUsereqStatusTicker(|
+|`createPiUsereqStatusController`|fn||654-670|export function createPiUsereqStatusController(): PiUsere...|
+|`setPiUsereqStatusConfig`|fn||683-688|export function setPiUsereqStatusConfig(|
+|`getPiUsereqRuntimeSoundLevel`|fn||697-701|export function getPiUsereqRuntimeSoundLevel(|
+|`setPiUsereqRuntimeSoundLevel`|fn||712-722|export function setPiUsereqRuntimeSoundLevel(|
+|`renderPiUsereqStatus`|fn||732-763|export function renderPiUsereqStatus(|
+|`setPiUsereqWorkflowState`|fn||774-785|export function setPiUsereqWorkflowState(|
+|`updateExtensionStatus`|fn||797-864|export function updateExtensionStatus(|
+|`disposePiUsereqStatusController`|fn||875-880|export function disposePiUsereqStatusController(|
 
 
 ---
@@ -1894,7 +2070,7 @@ import { SourceAnalyzer, formatMarkdown } from "./source-analyzer.js";
 
 ---
 
-# path-context.ts | TypeScript | 461L | 22 symbols | 5 imports | 26 comments
+# path-context.ts | TypeScript | 476L | 23 symbols | 5 imports | 28 comments
 > Path: `src/core/path-context.ts`
 - @brief Derives shared runtime path contracts for prompts, tools, and configuration flows.
 - @details Centralizes the static bootstrap paths and dynamic cwd-aligned paths used across the extension runtime. The module also exposes home-relative display formatting, trailing-slash-free normalization, and prompt-facing path facts. Runtime is O(s + p) where s is the configured source-directory count and p is aggregate path length. Side effects are limited to module-local runtime-path state mutation.
@@ -1910,122 +2086,127 @@ import type { UseReqConfig } from "./config.js";
 
 ## Definitions
 
-### iface `export interface RuntimePathState` (L29-37)
+### iface `export interface RuntimePathState` (L35-43)
 - @brief Stores the mutable runtime path state shared across extension callbacks.
 - @details Persists the static bootstrap `base-path`, the dynamic `context-path`, the optional repository-derived `git-path`, the derived `parent-path` and `base-dir`, and the optional active worktree facts. The interface is compile-time only and introduces no runtime cost.
 
-### iface `export interface RuntimePathContext extends RuntimePathState` : RuntimePathState (L43-56)
+### iface `export interface RuntimePathContext extends RuntimePathState` : RuntimePathState (L49-62)
 - @brief Describes the absolute runtime path context shared across extension components.
 - @details Aggregates the static installation, base, git, parent, and config paths with the dynamic context and optional worktree paths plus execution-resolved docs/tests/source absolute paths. The interface is compile-time only and introduces no runtime cost.
 
-### iface `export interface RuntimePathFacts` (L62-83)
+### iface `export interface RuntimePathFacts` (L68-89)
 - @brief Describes the prompt/tool-facing runtime paths rendered for display.
 - @details Mirrors `RuntimePathContext` in a serialization-oriented shape so downstream agents can consume stable `~`-relative absolute paths and trailing-slash-free relative directories without reparsing platform-specific separators. The interface is compile-time only and introduces no runtime cost.
 
-### fn `export function getInstallationPath(): string` (L98-100)
+### fn `export function getInstallationPath(): string` (L104-106)
 - @brief Resolves the installed extension root that owns `index.ts` and bundled resources.
 - @details Uses the current module location under `src/core` or its installed equivalent, then moves one directory upward so the returned path is the runtime installation root containing `resources/`. Runtime is O(1). No external state is mutated.
 - @return {string} Absolute installation path.
 
-### fn `export function normalizePathSlashes(value: string): string` (L108-110)
+### fn `export function normalizePathSlashes(value: string): string` (L114-116)
 - @brief Formats one path with slash separators.
 - @details Rewrites backslashes to `/` without changing semantic path identity so serialized payloads remain stable across operating systems. Runtime is O(p) in path length. No external state is mutated.
 - @param[in] value {string} Absolute or relative filesystem path.
 - @return {string} Slash-normalized path string.
 
-### fn `function trimTrailingSeparatorsPreserveRoot(value: string): string` (L118-132)
+### fn `function trimTrailingSeparatorsPreserveRoot(value: string): string` (L124-138)
 - @brief Removes trailing separators while preserving a filesystem root.
 - @details Keeps `/`, drive roots, and UNC roots intact while trimming redundant trailing separators from every other absolute or relative path string. Runtime is O(p) in path length. No external state is mutated.
 - @param[in] value {string} Raw path string.
 - @return {string} Trailing-slash-free path string.
 
-### fn `export function normalizeAbsolutePathContract(value: string): string` (L140-142)
+### fn `export function normalizeAbsolutePathContract(value: string): string` (L146-148)
 - @brief Normalizes one absolute path contract value.
 - @details Resolves the supplied value to an absolute path, removes trailing separators except for the filesystem root, and rewrites separators to `/`. Runtime is O(p) in path length. No external state is mutated.
 - @param[in] value {string} Absolute or relative path candidate.
 - @return {string} Canonical trailing-slash-free absolute path.
 
-### fn `export function normalizeRelativeDirContract(value: string): string` (L150-155)
+### fn `export function normalizeRelativeDirContract(value: string): string` (L156-161)
 - @brief Normalizes one relative-directory contract value.
 - @details Trims whitespace, rewrites separators to `/`, removes a leading `./`, and removes trailing separators so persisted `*-dir` values stay relative and trailing-slash-free. Runtime is O(p) in path length. No external state is mutated.
 - @param[in] value {string} Relative-directory candidate.
 - @return {string} Canonical trailing-slash-free relative-directory string.
 
-### fn `export function getConfigPath(basePath: string): string` (L163-165)
-- @brief Computes the absolute project config path for one base path.
+### fn `export function getConfigPath(basePath: string): string` (L169-171)
+- @brief Computes the absolute local project config path for one base path.
 - @details Appends `.pi-usereq.json` to the supplied base path using the canonical repository-local configuration layout. Runtime is O(1). No external state is mutated.
 - @param[in] basePath {string} Absolute or relative base path.
-- @return {string} Absolute config-file path.
+- @return {string} Absolute local config-file path.
 
-### fn `export function isSameOrAncestorPath(` (L174-188)
+### fn `export function getGlobalConfigPath(): string` (L178-180)
+- @brief Computes the absolute global config path for the current user.
+- @details Resolves `~/.config/pi-usereq/config.json` from the current user home directory without consulting project state. Runtime is O(1). No external state is mutated.
+- @return {string} Absolute global config-file path.
+
+### fn `export function isSameOrAncestorPath(` (L189-203)
 - @brief Tests whether one path is identical to or an ancestor of another path.
 - @details Resolves both inputs, computes a relative traversal from the candidate ancestor to the candidate child, and accepts only exact matches or descendant traversals that stay within the ancestor subtree. Runtime is O(p) in path length. No external state is mutated.
 - @param[in] ancestorPath {string} Candidate ancestor or identical path.
 - @param[in] childPath {string} Candidate child or identical path.
 - @return {boolean} `true` when `ancestorPath` equals `childPath` or strictly contains it.
 
-### fn `function deriveStaticRuntimePathState(` (L197-222)
+### fn `function deriveStaticRuntimePathState(` (L212-237)
 - @brief Derives repository-relative runtime state from one base path and optional git path.
 - @details Normalizes `base-path`, keeps `git-path` only when it is identical to or an ancestor of `base-path`, derives `parent-path` from `git-path`, and derives `base-dir` as `base-path` relative to `git-path`. Runtime is O(p) in path length. No external state is mutated.
 - @param[in] basePath {string} Static base path candidate.
 - @param[in] gitPath {string | undefined} Optional repository-root candidate.
 - @return {{ basePath: string; gitPath?: string; parentPath?: string; baseDir: string }} Derived static path facts.
 
-### fn `export function bootstrapRuntimePathState(` (L231-233)
+### fn `export function bootstrapRuntimePathState(` (L246-248)
 - @brief Bootstraps the shared runtime path state for one extension session or command preflight.
 - @details Sets static `base-path`, initializes dynamic `context-path` to the same value, stores derived `git-path`, `parent-path`, and `base-dir`, and clears any prior worktree facts. Runtime is O(p) in path length. Side effect: mutates module-local runtime-path state.
 - @param[in] basePath {string} Bootstrap cwd that becomes the static base path.
 - @param[in] options {{ gitPath?: string | undefined } | undefined} Optional repository-root override.
 - @return {void} No return value.
 
-### fn `export function ensureRuntimePathState(cwd: string): void` (L251-257)
+### fn `export function ensureRuntimePathState(cwd: string): void` (L266-272)
 - @brief Ensures the shared runtime path state has at least fallback base and context values.
 - @details Lazily bootstraps the module-local state from the supplied cwd only when no prior bootstrap has occurred, preserving any already-established static or dynamic path state. Runtime is O(1). Side effect: may initialize module-local runtime-path state.
 - @param[in] cwd {string} Fallback cwd.
 - @return {void} No return value.
 
-### fn `export function getRuntimeBasePath(fallbackPath: string): string` (L265-270)
+### fn `export function getRuntimeBasePath(fallbackPath: string): string` (L280-285)
 - @brief Returns the current static base path.
 - @details Falls back to the supplied path only when the runtime path state has not been bootstrapped yet. Runtime is O(1). No external state is mutated.
 - @param[in] fallbackPath {string} Fallback cwd.
 - @return {string} Static base path.
 
-### fn `export function getRuntimeContextPath(fallbackPath: string): string` (L278-283)
+### fn `export function getRuntimeContextPath(fallbackPath: string): string` (L293-298)
 - @brief Returns the current dynamic context path.
 - @details Falls back to the supplied path only when the runtime path state has not been bootstrapped yet. Runtime is O(1). No external state is mutated.
 - @param[in] fallbackPath {string} Fallback cwd.
 - @return {string} Dynamic context path.
 
-### fn `export function setRuntimeGitPath(gitPath?: string): void` (L291-298)
+### fn `export function setRuntimeGitPath(gitPath?: string): void` (L306-313)
 - @brief Stores the derived git-root facts in the shared runtime path state.
 - @details Re-derives `parent-path` and `base-dir` from the stored static `base-path` plus the supplied `git-path`, preserving the existing dynamic context path. Runtime is O(p) in path length. Side effect: mutates module-local runtime-path state.
 - @param[in] gitPath {string | undefined} Optional repository-root path.
 - @return {void} No return value.
 
-### fn `export function setRuntimeContextPath(contextPath: string): void` (L306-308)
+### fn `export function setRuntimeContextPath(contextPath: string): void` (L321-323)
 - @brief Stores the current dynamic context path.
 - @details Replaces the module-local `context-path` with the supplied trailing-slash-free absolute path. Runtime is O(1). Side effect: mutates module-local runtime-path state.
 - @param[in] contextPath {string} Next context path.
 - @return {void} No return value.
 
-### fn `export function setRuntimeWorktreePathState(options:` (L316-326)
+### fn `export function setRuntimeWorktreePathState(options:` (L331-341)
 - @brief Stores the current worktree directory and path facts.
 - @details Normalizes the supplied relative `worktree-dir` and absolute `worktree-path` so later prompt rendering and tool execution can reuse the derived values across modules. Runtime is O(p) in path length. Side effect: mutates module-local runtime-path state.
 - @param[in] options {{ worktreeDir?: string | undefined; worktreePath?: string | undefined }} Optional active worktree facts.
 - @return {void} No return value.
 
-### fn `export function getRuntimePathState(): RuntimePathState` (L333-344)
+### fn `export function getRuntimePathState(): RuntimePathState` (L348-359)
 - @brief Returns a snapshot of the shared runtime path state.
 - @details Materializes the current static and dynamic path facts into a read-only copy suitable for prompt rendering, tool execution, and tests. Runtime is O(1). No external state is mutated.
 - @return {RuntimePathState} Snapshot of the current runtime path state.
 
-### fn `export function formatRuntimePathForDisplay(absolutePath: string): string` (L352-365)
+### fn `export function formatRuntimePathForDisplay(absolutePath: string): string` (L367-380)
 - @brief Formats one absolute path relative to the user home using `~` when possible.
 - @details Returns `~` when the path equals the current home directory and returns `~/...` when the path descends from it; otherwise returns the normalized absolute path unchanged. Runtime is O(p) in path length. No external state is mutated.
 - @param[in] absolutePath {string} Absolute or relative path candidate.
 - @return {string} Home-relative or trailing-slash-free absolute path.
 
-### fn `export function buildRuntimePathContext(` (L376-385)
+### fn `export function buildRuntimePathContext(` (L391-400)
 - @brief Builds the absolute runtime path context for one base path, context path, and configuration.
 - @details Derives static `install-path`, `git-path`, `parent-path`, and `base-dir`, resolves the static `config-path`, preserves the dynamic `context-path`, and resolves docs/tests/source absolute paths against `context-path` so worktree-backed execution uses the active checkout. Runtime is O(s + p) where s is configured source-directory count and p is aggregate path length. No external state is mutated.
 - @param[in] basePath {string} Static base path.
@@ -2034,7 +2215,7 @@ import type { UseReqConfig } from "./config.js";
 - @param[in] options {{ installationPath?: string; gitPath?: string | undefined; worktreeDir?: string | undefined; worktreePath?: string | undefined } | undefined} Optional installation, repository, and worktree overrides.
 - @return {RuntimePathContext} Absolute runtime path context.
 
-### fn `export function buildRuntimePathFacts(` (L436-461)
+### fn `export function buildRuntimePathFacts(` (L451-476)
 - @brief Converts the absolute runtime path context into prompt/tool-facing path facts.
 - @details Re-encodes every absolute path with the home-relative formatter while preserving trailing-slash-free relative directories for `base-dir` and `worktree-dir`. Runtime is O(s + p) where s is source-directory count and p is aggregate path length. No external state is mutated.
 - @param[in] context {RuntimePathContext} Absolute runtime path context.
@@ -2043,28 +2224,29 @@ import type { UseReqConfig } from "./config.js";
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
 |---|---|---|---|---|
-|`RuntimePathState`|iface||29-37|export interface RuntimePathState|
-|`RuntimePathContext`|iface||43-56|export interface RuntimePathContext extends RuntimePathState|
-|`RuntimePathFacts`|iface||62-83|export interface RuntimePathFacts|
-|`getInstallationPath`|fn||98-100|export function getInstallationPath(): string|
-|`normalizePathSlashes`|fn||108-110|export function normalizePathSlashes(value: string): string|
-|`trimTrailingSeparatorsPreserveRoot`|fn||118-132|function trimTrailingSeparatorsPreserveRoot(value: string...|
-|`normalizeAbsolutePathContract`|fn||140-142|export function normalizeAbsolutePathContract(value: stri...|
-|`normalizeRelativeDirContract`|fn||150-155|export function normalizeRelativeDirContract(value: strin...|
-|`getConfigPath`|fn||163-165|export function getConfigPath(basePath: string): string|
-|`isSameOrAncestorPath`|fn||174-188|export function isSameOrAncestorPath(|
-|`deriveStaticRuntimePathState`|fn||197-222|function deriveStaticRuntimePathState(|
-|`bootstrapRuntimePathState`|fn||231-233|export function bootstrapRuntimePathState(|
-|`ensureRuntimePathState`|fn||251-257|export function ensureRuntimePathState(cwd: string): void|
-|`getRuntimeBasePath`|fn||265-270|export function getRuntimeBasePath(fallbackPath: string):...|
-|`getRuntimeContextPath`|fn||278-283|export function getRuntimeContextPath(fallbackPath: strin...|
-|`setRuntimeGitPath`|fn||291-298|export function setRuntimeGitPath(gitPath?: string): void|
-|`setRuntimeContextPath`|fn||306-308|export function setRuntimeContextPath(contextPath: string...|
-|`setRuntimeWorktreePathState`|fn||316-326|export function setRuntimeWorktreePathState(options:|
-|`getRuntimePathState`|fn||333-344|export function getRuntimePathState(): RuntimePathState|
-|`formatRuntimePathForDisplay`|fn||352-365|export function formatRuntimePathForDisplay(absolutePath:...|
-|`buildRuntimePathContext`|fn||376-385|export function buildRuntimePathContext(|
-|`buildRuntimePathFacts`|fn||436-461|export function buildRuntimePathFacts(|
+|`RuntimePathState`|iface||35-43|export interface RuntimePathState|
+|`RuntimePathContext`|iface||49-62|export interface RuntimePathContext extends RuntimePathState|
+|`RuntimePathFacts`|iface||68-89|export interface RuntimePathFacts|
+|`getInstallationPath`|fn||104-106|export function getInstallationPath(): string|
+|`normalizePathSlashes`|fn||114-116|export function normalizePathSlashes(value: string): string|
+|`trimTrailingSeparatorsPreserveRoot`|fn||124-138|function trimTrailingSeparatorsPreserveRoot(value: string...|
+|`normalizeAbsolutePathContract`|fn||146-148|export function normalizeAbsolutePathContract(value: stri...|
+|`normalizeRelativeDirContract`|fn||156-161|export function normalizeRelativeDirContract(value: strin...|
+|`getConfigPath`|fn||169-171|export function getConfigPath(basePath: string): string|
+|`getGlobalConfigPath`|fn||178-180|export function getGlobalConfigPath(): string|
+|`isSameOrAncestorPath`|fn||189-203|export function isSameOrAncestorPath(|
+|`deriveStaticRuntimePathState`|fn||212-237|function deriveStaticRuntimePathState(|
+|`bootstrapRuntimePathState`|fn||246-248|export function bootstrapRuntimePathState(|
+|`ensureRuntimePathState`|fn||266-272|export function ensureRuntimePathState(cwd: string): void|
+|`getRuntimeBasePath`|fn||280-285|export function getRuntimeBasePath(fallbackPath: string):...|
+|`getRuntimeContextPath`|fn||293-298|export function getRuntimeContextPath(fallbackPath: strin...|
+|`setRuntimeGitPath`|fn||306-313|export function setRuntimeGitPath(gitPath?: string): void|
+|`setRuntimeContextPath`|fn||321-323|export function setRuntimeContextPath(contextPath: string...|
+|`setRuntimeWorktreePathState`|fn||331-341|export function setRuntimeWorktreePathState(options:|
+|`getRuntimePathState`|fn||348-359|export function getRuntimePathState(): RuntimePathState|
+|`formatRuntimePathForDisplay`|fn||367-380|export function formatRuntimePathForDisplay(absolutePath:...|
+|`buildRuntimePathContext`|fn||391-400|export function buildRuntimePathContext(|
+|`buildRuntimePathFacts`|fn||451-476|export function buildRuntimePathFacts(|
 
 
 ---
@@ -2102,7 +2284,7 @@ import type { UseReqConfig } from "./config.js";
 
 - type `export type PiNotifyConfigFields = Pick<` (L115)
 - @brief Describes the configuration fields consumed by pi-notify helpers.
-- @details Narrows the full project config to the persisted notify, sound, and Pushover fields used by status rendering, prompt-end routing, and shortcut toggles. Compile-time only and introduces no runtime cost.
+- @details Narrows the full project config to the notify, sound, and Pushover fields used by status rendering and prompt-end routing. Callers may override `notify-sound` with the active runtime sound level before dispatch. Compile-time only and introduces no runtime cost.
 - type `type PiNotifySpawn = typeof spawn;` (L145)
 - @brief Describes the shell-spawn callback used by prompt-end command dispatch.
 - @details Narrows the injected spawn surface so deterministic tests can capture detached shell invocations without patching global module state externally. Compile-time only and introduces no runtime cost.
@@ -2187,10 +2369,10 @@ import type { UseReqConfig } from "./config.js";
 
 ### fn `export function cyclePiNotifySoundLevel(currentLevel: PiNotifySoundLevel): PiNotifySoundLevel` (L371-377)
 - @brief Cycles one sound level through the canonical shortcut order.
-- @details Advances persisted sound state in the exact order `none -> low -> mid -> high -> none`, enabling deterministic shortcut toggling and menu reuse. Runtime is O(1). No external state is mutated.
-- @param[in] currentLevel {PiNotifySoundLevel} Current persisted sound level.
-- @return {PiNotifySoundLevel} Next sound level in the cycle.
-- @satisfies REQ-134
+- @details Advances the active runtime sound state in the exact order `none -> low -> mid -> high -> none`, enabling deterministic shortcut toggling without mutating persisted boot configuration. Runtime is O(1). No external state is mutated.
+- @param[in] currentLevel {PiNotifySoundLevel} Current active runtime sound level.
+- @return {PiNotifySoundLevel} Next runtime sound level in the cycle.
+- @satisfies REQ-286
 
 ### fn `function isPiNotifyOutcomeEnabled(` (L388-402)
 - @brief Tests whether one outcome-specific toggle is enabled.
@@ -2445,29 +2627,29 @@ import type { UseReqConfig } from "./config.js";
 
 ---
 
-# pi-usereq-tools.ts | TypeScript | 178L | 7 symbols | 0 imports | 17 comments
+# pi-usereq-tools.ts | TypeScript | 180L | 7 symbols | 0 imports | 17 comments
 > Path: `src/core/pi-usereq-tools.ts`
 - @brief Declares the configurable pi-usereq active-tool inventory.
 - @details Provides canonical custom-tool names, supported embedded-tool names, default enablement subsets, and normalization helpers shared by configuration loading, extension startup, and test doubles. The module is side-effect free. Lookup and normalization costs are linear in configured tool count.
 
 ## Definitions
 
-- type `export type PiUsereqCustomToolName = (typeof PI_USEREQ_CUSTOM_TOOL_NAMES)[number];` (L79)
+- type `export type PiUsereqCustomToolName = (typeof PI_USEREQ_CUSTOM_TOOL_NAMES)[number];` (L81)
 - @brief Represents one valid extension-owned configurable tool identifier.
 - @details Narrows arbitrary strings to the literal union derived from `PI_USEREQ_CUSTOM_TOOL_NAMES`. The alias is compile-time only and introduces no runtime cost.
-- type `export type PiUsereqEmbeddedToolName = (typeof PI_USEREQ_EMBEDDED_TOOL_NAMES)[number];` (L85)
+- type `export type PiUsereqEmbeddedToolName = (typeof PI_USEREQ_EMBEDDED_TOOL_NAMES)[number];` (L87)
 - @brief Represents one valid embedded configurable tool identifier.
 - @details Narrows arbitrary strings to the literal union derived from `PI_USEREQ_EMBEDDED_TOOL_NAMES`. The alias is compile-time only and introduces no runtime cost.
-- type `export type PiUsereqStartupToolName = (typeof PI_USEREQ_STARTUP_TOOL_NAMES)[number];` (L91)
+- type `export type PiUsereqStartupToolName = (typeof PI_USEREQ_STARTUP_TOOL_NAMES)[number];` (L93)
 - @brief Represents one valid configurable active-tool identifier.
 - @details Narrows arbitrary strings to the literal union derived from `PI_USEREQ_STARTUP_TOOL_NAMES`. The alias is compile-time only and introduces no runtime cost.
-### fn `export function isPiUsereqEmbeddedToolName(name: string): name is PiUsereqEmbeddedToolName` (L117-119)
+### fn `export function isPiUsereqEmbeddedToolName(name: string): name is PiUsereqEmbeddedToolName` (L119-121)
 - @brief Tests whether one tool name belongs to the supported embedded-tool subset.
 - @details Performs one set-membership probe against `PI_USEREQ_EMBEDDED_TOOL_SET`. Runtime is O(1). No external state is mutated.
 - @param[in] name {string} Candidate tool name.
 - @return {boolean} `true` when the name belongs to the embedded configurable-tool subset.
 
-### fn `export function normalizeEnabledPiUsereqTools(value: unknown): PiUsereqStartupToolName[]` (L129-136)
+### fn `export function normalizeEnabledPiUsereqTools(value: unknown): PiUsereqStartupToolName[]` (L131-138)
 - @brief Normalizes a user-configured active-tool list.
 - @details Returns the default enabled-tool tuple when the input is not an array. Otherwise filters to string entries, removes names outside the configurable tool set, and deduplicates while preserving first-seen order. Time complexity is O(n). No external state is mutated.
 - @param[in] value {unknown} Raw configuration payload for `enabled-tools`.
@@ -2475,14 +2657,14 @@ import type { UseReqConfig } from "./config.js";
 - @satisfies REQ-064
 - @post Returned values are members of `PI_USEREQ_STARTUP_TOOL_NAMES` only.
 
-### fn `function buildPiUsereqStartupToolSortKey(` (L145-153)
+### fn `function buildPiUsereqStartupToolSortKey(` (L147-155)
 - @brief Builds the menu-order partition key for one configurable tool name.
 - @details Encodes the documented `Enable tools` ordering by grouping custom tools before embedded tools, placing non-`files-*` custom tools before `files-*` custom tools, and moving default-disabled names to the tail of each resolved partition. Runtime is O(1). No external state is mutated.
 - @param[in] name {PiUsereqStartupToolName} Canonical configurable tool name.
 - @return {[number, number, number, string]} Stable tuple `{group, subgroup, default_state, name}` used for lexicographic ordering.
 - @satisfies REQ-007, REQ-231, REQ-232
 
-### fn `export function comparePiUsereqStartupToolNames(` (L163-178)
+### fn `export function comparePiUsereqStartupToolNames(` (L165-180)
 - @brief Compares two configurable tool names using the documented menu order.
 - @details Applies the partition key emitted by `buildPiUsereqStartupToolSortKey(...)` and falls back to lexical comparison inside the final key slot so the `Enable tools` submenu stays deterministic across runtimes. Runtime is O(1). No external state is mutated.
 - @param[in] left {PiUsereqStartupToolName} Left configurable tool name.
@@ -2493,28 +2675,28 @@ import type { UseReqConfig } from "./config.js";
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
 |---|---|---|---|---|
-|`PiUsereqCustomToolName`|type||79||
-|`PiUsereqEmbeddedToolName`|type||85||
-|`PiUsereqStartupToolName`|type||91||
-|`isPiUsereqEmbeddedToolName`|fn||117-119|export function isPiUsereqEmbeddedToolName(name: string):...|
-|`normalizeEnabledPiUsereqTools`|fn||129-136|export function normalizeEnabledPiUsereqTools(value: unkn...|
-|`buildPiUsereqStartupToolSortKey`|fn||145-153|function buildPiUsereqStartupToolSortKey(|
-|`comparePiUsereqStartupToolNames`|fn||163-178|export function comparePiUsereqStartupToolNames(|
+|`PiUsereqCustomToolName`|type||81||
+|`PiUsereqEmbeddedToolName`|type||87||
+|`PiUsereqStartupToolName`|type||93||
+|`isPiUsereqEmbeddedToolName`|fn||119-121|export function isPiUsereqEmbeddedToolName(name: string):...|
+|`normalizeEnabledPiUsereqTools`|fn||131-138|export function normalizeEnabledPiUsereqTools(value: unkn...|
+|`buildPiUsereqStartupToolSortKey`|fn||147-155|function buildPiUsereqStartupToolSortKey(|
+|`comparePiUsereqStartupToolNames`|fn||165-180|export function comparePiUsereqStartupToolNames(|
 
 
 ---
 
-# prompt-command-catalog.ts | TypeScript | 46L | 2 symbols | 0 imports | 4 comments
+# prompt-command-catalog.ts | TypeScript | 45L | 2 symbols | 0 imports | 4 comments
 > Path: `src/core/prompt-command-catalog.ts`
-- @brief Declares the canonical bundled `req-*` prompt-command inventory.
-- @details Centralizes prompt-command names shared by extension registration, configuration normalization, debug-menu rendering, and prompt-runtime orchestration. The module is side-effect free. Lookup cost is O(1) per exported constant access.
+- @brief Declares the canonical bundled prompt-backed `req-*` command inventory.
+- @details Centralizes only prompt-template-backed command names shared by extension registration, configuration normalization, debug-menu rendering, and prompt-runtime orchestration. Specialized slash commands such as `req-references` and `req-reset` are registered outside this inventory. The module is side-effect free. Lookup cost is O(1) per exported constant access.
 
 ## Definitions
 
-- type `export type PromptCommandName = (typeof PROMPT_COMMAND_NAMES)[number];` (L34)
+- type `export type PromptCommandName = (typeof PROMPT_COMMAND_NAMES)[number];` (L33)
 - @brief Narrows prompt-command identifiers to the bundled command set.
 - @details Compile-time alias reused by orchestration helpers, debug inventory normalization, and command registration. The alias introduces no runtime cost.
-### fn `export function formatPromptCommandName(` (L42-46)
+### fn `export function formatPromptCommandName(` (L41-45)
 - @brief Formats one bundled prompt-command identifier as its slash-command name.
 - @details Prefixes the canonical prompt name with `req-` so debug menus and log filters can use the invokable slash-command form without duplicating the underlying inventory. Runtime is O(n) in prompt-name length. No external state is mutated.
 - @param[in] promptName {PromptCommandName} Canonical bundled prompt name.
@@ -2523,16 +2705,16 @@ import type { UseReqConfig } from "./config.js";
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
 |---|---|---|---|---|
-|`PromptCommandName`|type||34||
-|`formatPromptCommandName`|fn||42-46|export function formatPromptCommandName(|
+|`PromptCommandName`|type||33||
+|`formatPromptCommandName`|fn||41-45|export function formatPromptCommandName(|
 
 
 ---
 
-# prompt-command-runtime.ts | TypeScript | 1816L | 54 symbols | 12 imports | 58 comments
+# prompt-command-runtime.ts | TypeScript | 1955L | 56 symbols | 12 imports | 60 comments
 > Path: `src/core/prompt-command-runtime.ts`
-- @brief Implements prompt-command preflight and worktree orchestration.
-- @details Centralizes `req-<prompt>` repository validation, prompt-specific required-document checks, slash-command-owned worktree naming and lifecycle handling, session-backed cwd switching plus verification, persisted replacement-session context reuse for non-command lifecycle handlers, matched-success fast-forward merge finalization with restored-session transcript preservation, and command-side abort cleanup. Runtime is dominated by git subprocess execution plus bounded filesystem and session-file metadata checks. Side effects include active-session replacement, worktree creation and deletion, branch merges, and filesystem reads and writes.
+- @brief Implements bundled prompt-command preflight and worktree orchestration.
+- @details Centralizes prompt-template-backed `req-<prompt>` repository validation, prompt-specific required-document checks, slash-command-owned worktree naming and lifecycle handling, reusable transcript-preservation plus session-restoration helpers, persisted replacement-session context reuse for non-command lifecycle handlers, matched-success stash-assisted fast-forward merge finalization, and command-side abort cleanup. Runtime is dominated by git subprocess execution plus bounded filesystem and session-file metadata checks. Side effects include active-session replacement, worktree creation and deletion, branch merges, stash-stack mutation, and filesystem reads and writes.
 
 ## Imports
 ```
@@ -2543,7 +2725,7 @@ import { ReqError } from "./errors.js";
 import { classifyPiNotifyOutcome, type PiNotifyOutcome } from "./pi-notify.js";
 import {
 import {
-import {
+import { type PromptCommandName } from "./prompt-command-catalog.js";
 import {
 import { SessionManager } from "@mariozechner/pi-coding-agent";
 import { resolveRuntimeGitPath } from "./runtime-project-paths.js";
@@ -2552,57 +2734,57 @@ import {
 
 ## Definitions
 
-### iface `export interface PromptRequiredDocSpec` (L45-48)
+### iface `export interface PromptRequiredDocSpec` (L42-45)
 - @brief Describes one canonical required-document probe.
 - @details Binds a canonical doc filename to the remediation prompt command surfaced on failure so prompt-specific doc validation can stay deterministic. The interface is compile-time only and introduces no runtime cost.
 
-### iface `export interface PromptCommandExecutionPlan` (L54-68)
+### iface `export interface PromptCommandExecutionPlan` (L51-65)
 - @brief Describes one prompt-command execution plan tracked across lifecycle hooks.
 - @details Stores the prompt identity, runtime git root, associated branch name, original project base, execution context path, persisted origin and execution session files, and optional worktree metadata so the extension can switch all cwd surfaces before prompt dispatch and finalize worktree lifecycle after agent end. The interface is compile-time only and introduces no runtime cost.
 
-### iface `interface PromptCommandPostCreateHookContext` (L74-79)
+### iface `interface PromptCommandPostCreateHookContext` (L71-76)
 - @brief Describes one post-create test hook payload for prompt-command worktrees.
 - @details Exposes the git root, generated worktree name, sibling worktree path, and effective execution base so tests can simulate post-create verification failures deterministically. The interface is compile-time only and introduces no runtime cost.
 
-- type `type PromptCommandPostCreateHook = (context: PromptCommandPostCreateHookContext) => void;` (L85)
+- type `type PromptCommandPostCreateHook = (context: PromptCommandPostCreateHookContext) => void;` (L82)
 - @brief Represents one synchronous test hook invoked after prompt worktree creation.
 - @details Allows tests to mutate or remove newly created worktree artifacts before verification executes. The alias is compile-time only and introduces no runtime cost.
-### iface `interface PromptCommandDebugOptions` (L91-94)
+### iface `interface PromptCommandDebugOptions` (L88-91)
 - @brief Describes optional debug logging context for prompt orchestration helpers.
 - @details Carries the effective project configuration and current workflow state so prompt-runtime helpers can append selected debug entries without depending on extension UI types. The interface is compile-time only and introduces no runtime cost.
 
-### iface `interface PromptCommandSessionMessageOptions` (L100-102)
+### iface `interface PromptCommandSessionMessageOptions` (L97-99)
 - @brief Describes prompt-delivery options supported by replacement-session callbacks.
 - @details Mirrors the documented `sendUserMessage(...)` delivery modes needed when prompt orchestration targets a replacement session after a slash-command-owned session switch. The interface is compile-time only and introduces no runtime cost.
 
-### iface `interface PromptCommandSessionSwitchOptions` (L108-110)
+### iface `interface PromptCommandSessionSwitchOptions` (L105-107)
 - @brief Describes the replacement-session callback options accepted by session switching.
 - @details Mirrors the documented pi runtime `withSession(...)` hook so prompt-command orchestration can continue work against the replacement session after the old command context becomes stale. The interface is compile-time only and introduces no runtime cost.
 
-### iface `interface PromptCommandActiveContext extends PromptCommandSessionContext` : PromptCommandSessionContext (L116-121)
+### iface `interface PromptCommandActiveContext extends PromptCommandSessionContext` : PromptCommandSessionContext (L113-118)
 - @brief Describes the minimal session-bound surface available after session replacement.
 - @details Extends the shared prompt-command context with `sendUserMessage(...)` so prompt dispatch can target the replacement session without reusing stale pre-switch runtime objects. The interface is compile-time only and introduces no runtime cost.
 
-### iface `interface PromptCommandSessionEntry` (L127-133)
+### iface `interface PromptCommandSessionEntry` (L124-130)
 - @brief Describes one serializable session entry copied into a materialized execution-session file.
 - @details Captures the stable tree-entry fields needed to write a JSONL session snapshot for cross-cwd session replacement when the origin session file has not been flushed yet. The interface is compile-time only and introduces no runtime cost.
 
-### iface `interface PromptCommandSessionContext` (L139-151)
+### iface `interface PromptCommandSessionContext` (L136-148)
 - @brief Describes the minimal command-context session surface used by prompt orchestration.
 - @details Narrows extension command contexts to the `switchSession(...)` hook, the mutable `cwd` mirror, and the session metadata probes required for cwd verification and session snapshot materialization. The interface is compile-time only and introduces no runtime cost.
 
-### iface `interface PromptCommandContextError extends Error` : Error (L157-159)
+### iface `interface PromptCommandContextError extends Error` : Error (L154-156)
 - @brief Describes one error object enriched with a replacement-session context.
 - @details Allows prompt orchestration helpers to preserve the last valid session-bound context across replacement boundaries so callers can continue notifications and status updates after switch-triggered failures. The interface is compile-time only and introduces no runtime cost.
 
-### fn `function isUsablePromptSessionFile(` (L174-192)
+### fn `function isUsablePromptSessionFile(` (L171-189)
 - @brief Tests whether the current session file remains reusable for prompt-command bootstrap.
 - @details Accepts only persisted session files whose header cwd is readable, still exists on disk, and remains inside the active project base. This rejects stale execution-session files that still point at deleted or sibling worktrees from earlier prompt runs. Runtime is O(p) plus one session-header read. No external state is mutated.
 - @param[in] sessionFile {string | undefined} Candidate current session file.
 - @param[in] projectBase {string} Active project base path.
 - @return {sessionFile is string} `true` when the session file remains reusable for prompt bootstrap.
 
-### fn `function resolvePromptSessionFile(sessionFile: string | undefined, cwd: string): string` (L202-212)
+### fn `function resolvePromptSessionFile(sessionFile: string | undefined, cwd: string): string` (L199-209)
 - @brief Resolves the session file path used as the origin for prompt-command session switching.
 - @details Reuses the current session file only when its persisted header cwd is still readable, exists on disk, and remains inside the active project base. Otherwise allocates a fresh session file path rooted at the supplied cwd so later worktree switching and restoration never inherit stale deleted-worktree session metadata. Runtime is dominated by one optional session-header read plus optional session-file allocation. Side effects include session-file path allocation when the active session metadata is stale or ephemeral.
 - @param[in] sessionFile {string | undefined} Current active session file when available.
@@ -2610,7 +2792,7 @@ import {
 - @return {string} Session file path reserved for prompt orchestration.
 - @throws {ReqError} Throws when a session file path cannot be resolved.
 
-### fn `function writePromptExecutionSessionSnapshot(` (L226-252)
+### fn `function writePromptExecutionSessionSnapshot(` (L223-249)
 - @brief Writes one execution-session snapshot file with the target worktree cwd.
 - @details Persists a version-3 JSONL session header whose `cwd` equals the supplied target worktree path, then appends the supplied current-session branch entries unchanged so pi can reopen the replacement session in the correct cwd even when the origin session file has not been flushed yet. Runtime is O(n) in branch-entry count plus serialized byte size. Side effects include directory creation and file overwrite.
 - @param[in] sessionFile {string} Target execution-session file path.
@@ -2622,7 +2804,7 @@ import {
 - @throws {ReqError} Throws when the execution-session snapshot cannot be written.
 - @satisfies REQ-271
 
-### fn `function createPromptExecutionSessionFile(` (L265-288)
+### fn `function createPromptExecutionSessionFile(` (L262-285)
 - @brief Creates the persisted session file used for worktree-backed prompt execution.
 - @details Forks the resolved origin session into the target cwd when the origin session file is already persisted. Otherwise allocates a new execution-session path, materializes a JSONL header whose `cwd` equals the target worktree path, and copies the current in-memory session branch so pi can switch into the worktree session with the correct runtime cwd. Runtime is dominated by session-file copy or snapshot-write cost. Side effects include session-file creation under the target cwd session directory.
 - @param[in] sourceSessionFile {string} Origin session file path.
@@ -2633,25 +2815,25 @@ import {
 - @throws {ReqError} Throws when the execution-session file cannot be created.
 - @satisfies REQ-271
 
-### fn `function getPromptSessionCwd(ctx?: PromptCommandSessionContext): string | undefined` (L296-304)
+### fn `function getPromptSessionCwd(ctx?: PromptCommandSessionContext): string | undefined` (L293-301)
 - @brief Reads the current active session cwd from a prompt-command context.
 - @details Returns the session-manager cwd only when the supplied context exposes the documented `getCwd()` probe and the probe remains valid after any prior session replacement. Stale or missing probes degrade to `undefined` so verification paths never reuse invalidated pre-switch session objects. Runtime is O(1). No external state is mutated.
 - @param[in] ctx {PromptCommandSessionContext | undefined} Candidate prompt-command context.
 - @return {string | undefined} Active session cwd when available.
 
-### fn `function getPromptSessionFile(ctx?: PromptCommandSessionContext): string | undefined` (L312-320)
+### fn `function getPromptSessionFile(ctx?: PromptCommandSessionContext): string | undefined` (L309-317)
 - @brief Reads the current active session file from a prompt-command context.
 - @details Returns the session-manager file path only when the supplied context exposes the documented `getSessionFile()` probe and the probe remains valid after any prior session replacement. Stale or missing probes degrade to `undefined` so verification paths never reuse invalidated pre-switch session objects. Runtime is O(1). No external state is mutated.
 - @param[in] ctx {PromptCommandSessionContext | undefined} Candidate prompt-command context.
 - @return {string | undefined} Active session file when available.
 
-### fn `function getPromptContextCwd(ctx?: PromptCommandSessionContext): string | undefined` (L328-334)
+### fn `function getPromptContextCwd(ctx?: PromptCommandSessionContext): string | undefined` (L325-331)
 - @brief Reads the current context cwd from a prompt-command context.
 - @details Returns the context `cwd` only when the supplied getter remains valid after any prior session replacement. Stale getters degrade to `undefined` so verification paths never depend on invalidated pre-switch command objects. Runtime is O(1). No external state is mutated.
 - @param[in] ctx {PromptCommandSessionContext | undefined} Candidate prompt-command context.
 - @return {string | undefined} Context cwd when available.
 
-### fn `function resolvePromptCommandSwitchContext(` (L344-359)
+### fn `function resolvePromptCommandSwitchContext(` (L341-356)
 - @brief Resolves the best available command-capable context for prompt session switching.
 - @details Prefers the caller-supplied context when it still exposes `switchSession(...)`, otherwise falls back to the persisted replacement-session context associated with the execution-session file so lifecycle handlers can complete closure when pi emits non-command event contexts. Runtime is O(1). No external state is mutated.
 - @param[in] plan {PromptCommandExecutionPlan} Prompt execution plan whose execution-session file keys the persisted context.
@@ -2659,7 +2841,7 @@ import {
 - @return {{ context: PromptCommandSessionContext | undefined; source: "provided" | "persisted" | "missing" }} Preferred switch context plus its provenance.
 - @satisfies REQ-272, REQ-276
 
-### fn `function syncPromptCommandProcessCwd(expectedPath: string, stageLabel: string): void` (L370-390)
+### fn `function syncPromptCommandProcessCwd(expectedPath: string, stageLabel: string): void` (L367-387)
 - @brief Aligns the host process cwd to one expected prompt-orchestration path.
 - @details Applies `process.chdir(...)` only when the host process is still anchored to a different directory than the active prompt session, then re-reads `process.cwd()` and throws a deterministic error when the mutation fails or does not take effect. Runtime is O(p) in path length plus one optional cwd mutation. Side effect: mutates the host process cwd.
 - @param[in] expectedPath {string} Path that `process.cwd()` must match.
@@ -2668,28 +2850,28 @@ import {
 - @throws {ReqError} Throws when `process.chdir(...)` fails or leaves `process.cwd()` misaligned.
 - @satisfies REQ-257, REQ-272
 
-### fn `function readPromptSessionFileCwd(sessionFile: string): string | undefined` (L398-422)
+### fn `function readPromptSessionFileCwd(sessionFile: string): string | undefined` (L395-419)
 - @brief Reads the persisted working directory recorded in one prompt-command session file header.
 - @details Opens the JSONL session file, parses the first non-empty line as JSON, and returns the `cwd` field when present as a string so session-target verification can rely on live on-disk session state instead of stale handler-scoped `ctx` references. Runtime is O(n) in header size. No external state is mutated.
 - @param[in] sessionFile {string} Absolute session-file path.
 - @return {string | undefined} Persisted session cwd when readable; otherwise undefined.
 
-### fn `function readPromptSessionJsonLines(` (L431-478)
+### fn `function readPromptSessionJsonLines(` (L428-475)
 - @brief Reads one persisted session file as ordered parsed JSONL records.
 - @details Loads the raw session file, preserves every non-empty serialized line verbatim, parses each line as one JSON object, and rejects unreadable or structurally invalid files so prompt-closure helpers can replay exact execution-session transcript records into the restored base session without reserialization drift. Runtime is O(n) in session-file size. No external state is mutated.
 - @param[in] sessionFile {string} Absolute session-file path.
 - @return {Array<{ rawLine: string; parsed: Record<string, unknown> }>} Parsed non-empty JSONL lines in file order.
 - @throws {ReqError} Throws when the file cannot be read, when it contains no JSONL records, when any record is not a JSON object, or when the header record is missing.
 
-### fn `function preservePromptCommandExecutionTranscript(plan: PromptCommandExecutionPlan): void` (L488-585)
+### fn `export function preservePromptCommandExecutionTranscript(plan: PromptCommandExecutionPlan): void` (L485-582)
 - @brief Copies successful execution-session transcript records into the restored base session file.
 - @details Reads the execution session JSONL file, preserves the original base-session header when it already exists, materializes a restored base-session header when the reserved original session file is still pending persistence, appends any execution-session records missing from the original session in original execution order, and re-reads the restored file to verify both `base-path` cwd and copied entry identifiers. Runtime is O(n) in combined session-file size. Side effects include session-file creation or append operations for the restored base session.
 - @param[in] plan {PromptCommandExecutionPlan} Prompt execution plan whose original and execution session files must be synchronized.
 - @return {void} No return value.
 - @throws {ReqError} Throws when either session file is unreadable or when appended execution records are not persisted to the original session file.
-- @satisfies REQ-208
+- @satisfies REQ-208, REQ-307
 
-### fn `function verifyPromptCommandSessionTarget(` (L598-642)
+### fn `function verifyPromptCommandSessionTarget(` (L595-639)
 - @brief Verifies that the active session file and cwd surfaces match one expected prompt-orchestration target.
 - @details Re-reads the persisted session-file header when present plus the host `process.cwd()` and throws on the first mismatch so prompt commands abort before prompt dispatch or prompt-end handling whenever session switching leaves execution attached to the wrong cwd. A missing persisted session file is treated as a non-fatal lazy-persistence state because pi's `SessionManager` writes session files on first assistant flush rather than eagerly during `ctx.switchSession(sessionPath)`; when the file is absent, pi aligns its internal session cwd to the live `process.cwd()`, so verifying `process.cwd()` alone is authoritative in that state. Reads of `ctx.cwd`, `ctx.sessionManager.getCwd()`, and `ctx.sessionManager.getSessionFile()` are advisory only because the pi `ctx.switchSession(sessionPath)` SDK contract does not mutate the handler-scoped `ctx` object, so those probes stay bound to the pre-switch session and a divergent value alone never triggers abort; they only surface a mismatch when they disagree with both the persisted header cwd and the live `process.cwd()`. Runtime is O(p) in aggregate path length plus one session-file header read. No external state is mutated.
 - @param[in] expectedSessionFile {string} Session file that must remain active.
@@ -2700,7 +2882,7 @@ import {
 - @throws {ReqError} Throws when the persisted session-file header cwd diverges from the expected target or when `process.cwd()` diverges from the expected target.
 - @satisfies REQ-257, REQ-272
 
-### fn `function verifyPromptCommandClosureArtifacts(` (L652-687)
+### fn `function verifyPromptCommandClosureArtifacts(` (L649-684)
 - @brief Verifies persisted prompt execution artifacts before successful closure merge.
 - @details Re-reads the persisted execution-session header, verifies the worktree path still exists, confirms the sibling worktree remains registered, and confirms the linked branch is still present before prompt-end closure attempts to restore `base-path` and merge from the original repository. Unlike prompt-start activation checks, this helper intentionally does not require the live process cwd or current session-bound context to remain on `worktree-path`, because pi CLI may already have started end-of-session session replacement or other post-run housekeeping before the extension finishes closure handling. Runtime is dominated by one session-file read, two git subprocess checks, and bounded filesystem probes. No external state is mutated.
 - @param[in] plan {PromptCommandExecutionPlan} Prompt execution plan.
@@ -2708,7 +2890,7 @@ import {
 - @throws {ReqError} Throws when persisted execution-session metadata or worktree artifacts no longer match the expected worktree target.
 - @satisfies REQ-208, REQ-219, REQ-258, REQ-282
 
-### fn `async function switchPromptCommandSession(` (L698-727)
+### fn `async function switchPromptCommandSession(` (L695-724)
 - @brief Switches the active prompt session to one persisted session file when required.
 - @details Calls `ctx.switchSession(sessionPath, { withSession })` so current pi runtimes can expose a fresh replacement-session context for every post-switch session-bound operation. When a runtime ignores the callback, the helper falls back to the caller-supplied context and downstream verification continues to rely on the persisted session-file header plus `process.cwd()`. If pi surfaces only the documented stale-extension-context error while invalidating the old execution-session closure, the helper treats that side effect as non-fatal and lets downstream verification confirm whether the target session actually became active. Runtime is dominated by the session switch. Side effects include active-session replacement and cwd mutation by the host runtime.
 - @param[in] sessionFile {string} Target persisted session file.
@@ -2717,47 +2899,63 @@ import {
 - @throws {ReqError} Throws when the context cannot switch sessions, when the host cancels the switch, or when later verification proves the target session never became active.
 - @satisfies REQ-068, REQ-271, REQ-272
 
-### fn `function isPromptCommandStaleContextError(error: unknown): boolean` (L736-739)
+### fn `function isPromptCommandStaleContextError(error: unknown): boolean` (L733-736)
 - @brief Detects the documented stale-extension-context runtime error during prompt-command session switching.
 - @details Matches the guarded pi runtime error emitted when the old execution-session closure is invalidated during a session replacement or reload. Prompt-command session-switch helpers use this detector to distinguish a late stale-context side effect from genuine switch failures, then rely on post-switch verification to confirm whether the target session actually became active. Runtime is O(n) in message length only when an error is supplied. No external state is mutated.
 - @param[in] error {unknown} Candidate thrown value.
 - @return {boolean} `true` when the value matches the stale-extension-context runtime error.
 - @satisfies REQ-280
 
-### fn `function attachPromptCommandErrorContext(` (L748-756)
+### fn `function attachPromptCommandErrorContext(` (L745-753)
 - @brief Attaches the last valid prompt-command context to one thrown error.
 - @details Preserves the replacement-session context discovered after `ctx.switchSession(...)` so outer callers can continue UI notifications and cleanup without reusing stale pre-switch command objects. Runtime is O(1). Side effect: mutates the error object when it is an `Error` instance.
 - @param[in] error {unknown} Thrown value.
 - @param[in] ctx {PromptCommandSessionContext | undefined} Last valid prompt-command context.
 - @return {unknown} Original thrown value with optional attached prompt context.
 
-### fn `export function getPromptCommandErrorContext(` (L764-770)
+### fn `export function getPromptCommandErrorContext(` (L761-767)
 - @brief Reads an attached prompt-command context from one thrown error.
 - @details Returns the replacement-session context captured by prompt orchestration helpers when a switch-triggered failure occurs after the original command context became stale. Runtime is O(1). No external state is mutated.
 - @param[in] error {unknown} Thrown value.
 - @return {PromptCommandSessionContext | undefined} Attached prompt-command context when available.
 
-### fn `function runCapture(command: string[], cwd: string): ReturnType<typeof spawnSync>` (L851-856)
+### fn `function runCapture(command: string[], cwd: string): ReturnType<typeof spawnSync>` (L845-850)
 - @brief Executes one git subprocess synchronously and captures UTF-8 output.
 - @details Delegates to `spawnSync`, preserves the supplied working directory, and returns the raw subprocess result used by prompt-command orchestration. Runtime is dominated by external process execution. Side effects include process spawning.
 - @param[in] command {string[]} Executable plus argument vector.
 - @param[in] cwd {string} Working directory for the subprocess.
 - @return {ReturnType<typeof spawnSync>} Captured subprocess result.
 
-### fn `export function setPromptCommandPostCreateHookForTests(` (L864-868)
+### fn `function listPromptTrackedBasePathChanges(basePath: string): string[]` (L860-878)
+- @brief Lists tracked `base-path` status rows that require stash-assisted merge handling.
+- @details Executes `git status --porcelain`, retains only tracked rows whose index or worktree slot reports a change, and excludes untracked or ignored rows because the required `git stash` command does not preserve them. Runtime is dominated by one git subprocess plus O(n) parsing in status-line count. Side effects include process spawning.
+- @param[in] basePath {string} Restored project base path.
+- @return {string[]} Tracked status rows requiring stash-assisted merge handling.
+- @throws {ReqError} Throws when git status cannot be read from `basePath`.
+- @satisfies REQ-291
+
+### fn `function finalizePromptCommandMerge(` (L888-1010)
+- @brief Executes the successful-closure merge sequence from restored `base-path`.
+- @details Detects tracked staged or unstaged `base-path` changes, wraps the existing fast-forward merge in `git stash` and `git stash pop` when required, preserves the direct merge path when no tracked changes exist, emits a warning-only result after successful local-change restoration, and writes one merge-finalization debug entry when enabled. Runtime is dominated by up to four git subprocesses plus O(n) status parsing. Side effects include stash-stack mutation, branch merge attempts, and optional debug-log writes.
+- @param[in] plan {PromptCommandExecutionPlan} Prompt execution plan whose branch should be merged.
+- @param[in] debugOptions {PromptCommandDebugOptions | undefined} Optional prompt debug logging context.
+- @return {{ mergeAttempted: boolean; mergeSucceeded: boolean; errorMessage?: string; warningMessage?: string }} Merge-attempt facts plus optional warning text.
+- @satisfies REQ-208, REQ-245, REQ-291, REQ-292
+
+### fn `export function setPromptCommandPostCreateHookForTests(` (L1018-1022)
 - @brief Stores or clears the prompt-command post-create test hook.
 - @details Enables deterministic simulation of post-create worktree verification failures without altering production control flow. Runtime is O(1). Side effect: mutates module-local test state.
 - @param[in] hook {PromptCommandPostCreateHook | undefined} Optional replacement hook.
 - @return {void} No return value.
 
-### fn `function resolvePromptDocsRoot(projectBase: string, config: UseReqConfig): string` (L877-880)
+### fn `function resolvePromptDocsRoot(projectBase: string, config: UseReqConfig): string` (L1031-1034)
 - @brief Resolves the configured docs root for one project base.
 - @details Joins the project base with the normalized `docs-dir` value while stripping trailing separators from the persisted config field. Runtime is O(p) in path length. No external state is mutated.
 - @param[in] projectBase {string} Absolute project root.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {string} Absolute canonical docs root path.
 
-### fn `function resolveWorktreePaths(` (L890-917)
+### fn `function resolveWorktreePaths(` (L1044-1071)
 - @brief Resolves the effective worktree project base relative to the git root.
 - @details Reuses the original project-base location relative to the git root so nested repository subdirectories remain aligned inside the sibling worktree. Runtime is O(p) in path length. No external state is mutated.
 - @param[in] projectBase {string} Original absolute project base path.
@@ -2765,51 +2963,51 @@ import {
 - @param[in] worktreeName {string} Created worktree name.
 - @return {{ worktreePath: string; worktreeBasePath: string }} Derived worktree paths.
 
-### fn `function sanitizePromptWorktreeBranchName(branch: string): string` (L925-927)
+### fn `function sanitizePromptWorktreeBranchName(branch: string): string` (L1079-1081)
 - @brief Rewrites a branch name into a filesystem-safe token for prompt worktrees.
 - @details Replaces characters invalid for worktree directory and branch-name generation with `-`. Runtime is O(n). No external state is mutated.
 - @param[in] branch {string} Raw branch name.
 - @return {string} Sanitized token.
 
-### fn `function validatePromptWorktreeName(wtName: string): boolean` (L935-940)
+### fn `function validatePromptWorktreeName(wtName: string): boolean` (L1089-1094)
 - @brief Validates a prompt-command-generated worktree or branch name.
 - @details Rejects empty names, dot-path markers, whitespace, and filesystem-invalid characters. Runtime is O(n). No external state is mutated.
 - @param[in] wtName {string} Candidate worktree name.
 - @return {boolean} `true` when the name is acceptable for worktree creation.
 
-### fn `function throwPromptGitStatusError(): never` (L948-950)
+### fn `function throwPromptGitStatusError(): never` (L1102-1104)
 - @brief Throws the canonical prompt-command git-preflight failure.
 - @details Normalizes all repository-validation failures to the contractually stable prompt-command error string consumed by tests and downstream prompt workflows. Runtime is O(1). No external state is mutated.
 - @return {never} Always throws.
 - @throws {ReqError} Always throws with exit code `1`.
 
-### fn `function validatePromptGitState(projectBase: string, config?: UseReqConfig): string` (L961-1005)
-- @brief Runs prompt-command-owned git validation and returns the runtime git root.
-- @details Validates work-tree membership, porcelain cleanliness, and symbolic or detached `HEAD` presence without invoking extension custom-tool executors. Runtime is dominated by git subprocess execution. Side effects include process spawning.
+### fn `export function validatePromptGitState(projectBase: string, config?: UseReqConfig): string` (L1115-1159)
+- @brief Runs slash-command-owned git validation and returns the runtime git root.
+- @details Validates work-tree membership, porcelain cleanliness, and symbolic or detached `HEAD` presence for bundled prompt commands and `req-references` without invoking extension custom-tool executors. Runtime is dominated by git subprocess execution. Side effects include process spawning.
 - @param[in] projectBase {string} Absolute current project base.
 - @param[in] config {UseReqConfig | undefined} Optional effective project configuration used to ignore extension-owned debug-log artifacts.
 - @return {string} Absolute runtime git root.
 - @throws {ReqError} Throws the canonical prompt-command git-preflight error on any validation failure.
 - @satisfies REQ-200, REQ-220
 
-### fn `function resolveCurrentPromptBranchName(gitRoot: string): string` (L1013-1018)
+### fn `function resolveCurrentPromptBranchName(gitRoot: string): string` (L1167-1172)
 - @brief Resolves the current local branch name used by prompt-command orchestration.
 - @details Reads `git branch --show-current`, falls back to `unknown` when git cannot provide a branch name, and preserves the raw branch token for later worktree-name generation and state tracking. Runtime is dominated by one git subprocess. Side effects include process spawning.
 - @param[in] gitRoot {string} Absolute runtime git root.
 - @return {string} Current branch name or `unknown` when unavailable.
 
-### fn `function formatPromptWorktreeExecutionId(timestamp: Date): string` (L1032-1034)
+### fn `function formatPromptWorktreeExecutionId(timestamp: Date): string` (L1186-1188)
 - @brief Formats one prompt-worktree execution identifier.
 - @details Serializes the supplied timestamp as `YYYYMMDDHHMMSS` with zero-padded calendar and clock fields so generated worktree names remain stable, lexicographically sortable, and requirement-compatible. Runtime is O(1). No external state is mutated.
 - @param[in] timestamp {Date} Timestamp to encode.
 - @return {string} Formatted execution identifier.
 
-### fn `function getNextPromptWorktreeExecutionId(): string` (L1041-1054)
+### fn `function getNextPromptWorktreeExecutionId(): string` (L1195-1208)
 - @brief Resolves the next unique prompt-worktree execution identifier.
 - @details Formats the current wall-clock second as `YYYYMMDDHHMMSS`, then monotonically advances by one-second steps until the identifier is strictly greater than the last value emitted in the current host process. This preserves the documented timestamp-only name shape while preventing immediate same-process worktree-name reuse after fast back-to-back prompt starts. Runtime is O(1) in the common case and O(k) in repeated same-second collisions. Side effect: mutates process-scoped execution-id persistence.
 - @return {string} Unique execution identifier for worktree naming.
 
-### fn `function buildPromptWorktreeName(gitRoot: string, config: UseReqConfig): string` (L1065-1076)
+### fn `function buildPromptWorktreeName(gitRoot: string, config: UseReqConfig): string` (L1219-1230)
 - @brief Builds the prompt-command worktree name without invoking agent-tool executors.
 - @details Combines the normalized persisted worktree prefix, repository basename, sanitized current branch, and timestamp execution identifier into the dedicated prompt-command worktree name. Runtime is O(1) plus git execution cost. Side effects include process spawning.
 - @param[in] gitRoot {string} Absolute runtime git root.
@@ -2818,21 +3016,21 @@ import {
 - @throws {ReqError} Throws when the generated name is invalid.
 - @satisfies REQ-206, REQ-220
 
-### fn `function promptWorktreeBranchExists(gitRoot: string, branchName: string): boolean` (L1085-1094)
+### fn `function promptWorktreeBranchExists(gitRoot: string, branchName: string): boolean` (L1239-1248)
 - @brief Tests whether the exact prompt-command branch is present in the local branch list.
 - @details Queries `git branch --list --format=%(refname:short)` and returns a boolean without mutating repository state. Runtime is dominated by one git subprocess plus O(n) parsing in listed branch count. Side effects include process spawning.
 - @param[in] gitRoot {string} Absolute runtime git root.
 - @param[in] branchName {string} Candidate local branch name.
 - @return {boolean} `true` when the exact local branch is listed.
 
-### fn `function promptWorktreeRegistered(gitRoot: string, worktreePath: string): boolean` (L1103-1114)
+### fn `function promptWorktreeRegistered(gitRoot: string, worktreePath: string): boolean` (L1257-1268)
 - @brief Tests whether the exact prompt-command worktree is registered.
 - @details Scans `git worktree list --porcelain` for the resolved target path so cleanup and verification can distinguish registered worktrees from unrelated sibling directories. Runtime is dominated by one git subprocess plus O(n) parsing in listed worktree count. Side effects include process spawning.
 - @param[in] gitRoot {string} Absolute runtime git root.
 - @param[in] worktreePath {string} Absolute sibling worktree path.
 - @return {boolean} `true` when the exact path is registered as a git worktree.
 
-### fn `function cleanupPromptWorktreeCreation(` (L1124-1138)
+### fn `function cleanupPromptWorktreeCreation(` (L1278-1292)
 - @brief Removes partially created prompt-command worktree resources.
 - @details Force-removes the registered sibling worktree when present, deletes the matching local branch, and falls back to filesystem removal for leftover directories so failed prompt preflight leaves no reusable worktree residue. Runtime is dominated by git subprocess execution. Side effects include branch deletion and directory removal.
 - @param[in] gitRoot {string} Absolute runtime git root.
@@ -2840,7 +3038,7 @@ import {
 - @param[in] worktreeName {string} Exact worktree and branch name.
 - @return {void} No return value.
 
-### fn `function createPromptWorktree(` (L1152-1272)
+### fn `function createPromptWorktree(` (L1306-1426)
 - @brief Creates and verifies the prompt-command worktree and branch.
 - @details Creates the sibling worktree, mirrors project config when present, runs the optional post-create test hook, verifies git worktree registration, verifies git branch listing, verifies filesystem paths before prompt dispatch, and appends selected debug entries for worktree creation. Failed verification triggers immediate rollback. Runtime is dominated by git subprocess execution and filesystem metadata checks. Side effects include worktree creation, branch creation, directory creation, file copying, optional debug-log writes, and rollback on failure.
 - @param[in] projectBase {string} Absolute original project base.
@@ -2852,7 +3050,7 @@ import {
 - @throws {ReqError} Throws when worktree creation, verification, or rollback finalization fails.
 - @satisfies REQ-206, REQ-219, REQ-220, REQ-245
 
-### fn `function deletePromptWorktree(` (L1285-1345)
+### fn `export function deletePromptWorktree(` (L1439-1499)
 - @brief Deletes prompt-command worktree resources without invoking custom-tool executors.
 - @details Force-removes the sibling worktree and matching branch, verifies both are absent so prompt finalization remains independent from agent-tool implementations, and appends selected debug entries for worktree deletion. Runtime is dominated by git subprocess execution plus filesystem probes. Side effects include worktree deletion, branch deletion, and optional debug-log writes.
 - @param[in] projectBase {string} Absolute original project base.
@@ -2861,16 +3059,16 @@ import {
 - @param[in] debugOptions {PromptCommandDebugOptions | undefined} Optional prompt debug logging context.
 - @return {void} No return value.
 - @throws {ReqError} Throws when cleanup cannot remove the worktree and branch fully.
-- @satisfies REQ-208, REQ-220, REQ-245
+- @satisfies REQ-208, REQ-220, REQ-245, REQ-309
 
-### fn `export function getPromptRequiredDocs(promptName: PromptCommandName): readonly PromptRequiredDocSpec[]` (L1354-1356)
+### fn `export function getPromptRequiredDocs(promptName: PromptCommandName): readonly PromptRequiredDocSpec[]` (L1508-1510)
 - @brief Returns the canonical required-document probes for one prompt command.
 - @details Performs a constant-time lookup in the prompt-doc matrix used by command preflight validation. No filesystem access occurs.
 - @param[in] promptName {PromptCommandName} Bundled prompt identifier.
 - @return {readonly PromptRequiredDocSpec[]} Required-doc definitions in probe order.
 - @satisfies REQ-201, REQ-202
 
-### fn `export function validatePromptRequiredDocs(` (L1369-1420)
+### fn `export function validatePromptRequiredDocs(` (L1523-1574)
 - @brief Runs prompt-specific required-document validation.
 - @details Resolves the configured docs root, verifies the prompt-mapped canonical docs exist as files, throws a deterministic remediation error for the first missing document, and appends selected debug entries for required-doc checks. Runtime is O(d) in required-doc count plus filesystem metadata cost. Side effects are limited to filesystem reads and optional debug-log writes.
 - @param[in] promptName {PromptCommandName} Bundled prompt identifier.
@@ -2881,7 +3079,7 @@ import {
 - @throws {ReqError} Throws when a required canonical doc is missing.
 - @satisfies REQ-201, REQ-202, REQ-203, REQ-245
 
-### fn `export function preparePromptCommandExecution(` (L1437-1513)
+### fn `export function preparePromptCommandExecution(` (L1591-1667)
 - @brief Prepares prompt-command execution for one bundled prompt.
 - @details Runs slash-command-owned git validation, enforces the prompt-specific required-doc matrix, resolves persisted origin and execution session files, applies the effective worktree policy, generates and verifies a dedicated worktree when enabled, and returns the execution plan consumed by prompt rendering plus lifecycle hooks. Worktree-backed execution reuses the active session directory for the forked session file. Runtime is dominated by git subprocesses, worktree creation, and optional session-file cloning. Side effects include worktree creation, session-file creation, filesystem reads, and optional prompt debug-log writes.
 - @param[in] promptName {PromptCommandName} Bundled prompt identifier.
@@ -2896,7 +3094,7 @@ import {
 - @throws {ReqError} Throws when repository validation, required-doc validation, worktree creation, or session preparation fails.
 - @satisfies REQ-200, REQ-203, REQ-206, REQ-207, REQ-215, REQ-219, REQ-220, REQ-245, REQ-256, REQ-271
 
-### fn `export async function activatePromptCommandExecution(` (L1524-1557)
+### fn `export async function activatePromptCommandExecution(` (L1678-1711)
 - @brief Activates the prepared prompt execution path before prompt dispatch or agent start.
 - @details Switches the active session to the execution-session file when worktree routing changed the cwd, re-aligns `process.cwd()` to the execution path, verifies active-session cwd plus cwd mirrors after the switch completes, and stores the verified command-capable replacement-session context for later closure handling. Runtime is dominated by the optional session switch and one optional cwd mutation. Side effects include active-session replacement, host-process cwd mutation, runtime-path state mutation, and process-scoped command-context persistence.
 - @param[in] plan {PromptCommandExecutionPlan} Prepared prompt execution plan.
@@ -2905,7 +3103,7 @@ import {
 - @throws {ReqError} Throws when the session switch or cwd verification fails.
 - @satisfies REQ-206, REQ-207, REQ-257, REQ-272, REQ-276
 
-### fn `export async function restorePromptCommandExecution(` (L1569-1633)
+### fn `export async function restorePromptCommandExecution(` (L1723-1787)
 - @brief Restores the original project base path before merge or session-closure return.
 - @details Switches the active session back to the original session file when worktree routing changed the cwd, re-aligns `process.cwd()` to `base-path`, verifies the restored session target, reuses the persisted replacement-session context when lifecycle handlers receive non-command contexts, tolerates the documented stale-extension-context error when the old replacement-session closure becomes invalid immediately after a successful restore, emits optional workflow restoration debug entries, and clears active worktree path facts before session closure continues. Runtime is dominated by the optional session switch and one optional cwd mutation. Side effects include active-session replacement, host-process cwd mutation, runtime-path state mutation, and optional workflow-debug writes.
 - @param[in] plan {PromptCommandExecutionPlan} Prompt execution plan whose original base should be restored.
@@ -2915,7 +3113,7 @@ import {
 - @throws {ReqError} Throws when the session switch or cwd verification fails.
 - @satisfies REQ-208, REQ-209, REQ-245, REQ-257, REQ-272, REQ-276
 
-### fn `export async function abortPromptCommandExecution(` (L1644-1690)
+### fn `export async function abortPromptCommandExecution(` (L1798-1844)
 - @brief Aborts one prepared prompt-command execution before pi CLI takes ownership.
 - @details Restores the original session-backed cwd and deletes any created worktree plus branch when command-side preflight, prompt rendering, or prompt handoff fails before agent completion. Restoration failures are returned as structured cleanup errors so the original preflight failure is not masked. Runtime is dominated by the optional session switch plus git subprocess execution. Side effects include active-session replacement, optional worktree deletion, and optional debug-log writes.
 - @param[in] plan {PromptCommandExecutionPlan} Prepared prompt execution plan.
@@ -2924,16 +3122,16 @@ import {
 - @return {Promise<{ cleanupSucceeded: boolean; errorMessage?: string; activeContext?: PromptCommandSessionContext }>} Abort-cleanup facts plus the last valid active prompt-command context.
 - @satisfies REQ-226, REQ-220, REQ-245
 
-### fn `export async function finalizePromptCommandExecution(` (L1701-1804)
+### fn `export async function finalizePromptCommandExecution(` (L1855-1943)
 - @brief Finalizes one matched successful worktree-backed prompt execution.
-- @details Re-verifies persisted execution-session metadata plus worktree artifacts, copies any execution-session transcript records missing from the original session file, restores the original session-backed `base-path`, fast-forward merges the successful worktree branch from `base-path`, deletes the worktree after merge success, and preserves the restored base session across closure failures. Closure intentionally treats `base-path` restoration as authoritative even when pi CLI has already started end-of-session session replacement or other housekeeping that moved the live runtime away from `worktree-path`. Runtime is dominated by session switching plus git subprocess execution. Side effects include session-file appends, active-session replacement, branch merges, worktree deletion, and optional debug-log writes.
+- @details Re-verifies persisted execution-session metadata plus worktree artifacts, copies any execution-session transcript records missing from the original session file, restores the original session-backed `base-path`, executes the stash-assisted fast-forward merge sequence from `base-path`, deletes the worktree after merge success, and preserves the restored base session across closure failures. Closure intentionally treats `base-path` restoration as authoritative even when pi CLI has already started end-of-session session replacement or other housekeeping that moved the live runtime away from `worktree-path`. Runtime is dominated by session switching plus git subprocess execution. Side effects include session-file appends, active-session replacement, branch merges, stash-stack mutation, worktree deletion, and optional debug-log writes.
 - @param[in] plan {PromptCommandExecutionPlan} Prompt execution plan.
 - @param[in] ctx {PromptCommandSessionContext | undefined} Optional prompt-command context.
 - @param[in] debugOptions {PromptCommandDebugOptions | undefined} Optional prompt debug logging context.
-- @return {Promise<{ mergeAttempted: boolean; mergeSucceeded: boolean; cleanupSucceeded: boolean; errorMessage?: string; activeContext?: PromptCommandSessionContext }>} Finalization facts plus the last valid active prompt-command context.
-- @satisfies REQ-208, REQ-209, REQ-220, REQ-245, REQ-282
+- @return {Promise<{ mergeAttempted: boolean; mergeSucceeded: boolean; cleanupSucceeded: boolean; errorMessage?: string; warningMessage?: string; activeContext?: PromptCommandSessionContext }>} Finalization facts plus the last valid active prompt-command context.
+- @satisfies REQ-208, REQ-209, REQ-220, REQ-245, REQ-282, REQ-291, REQ-292
 
-### fn `export function classifyPromptCommandOutcome(` (L1812-1816)
+### fn `export function classifyPromptCommandOutcome(` (L1951-1955)
 - @brief Maps one `agent_end` payload into the canonical prompt-worktree finalization outcome.
 - @details Delegates to the shared notification outcome classifier so worktree merge and fork-session retention decisions stay aligned with prompt-end notification routing. Runtime is O(m) in assistant message count. No external state is mutated.
 - @param[in] event {Pick<import("@mariozechner/pi-coding-agent").AgentEndEvent, "messages">} Agent-end payload subset.
@@ -2942,60 +3140,62 @@ import {
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
 |---|---|---|---|---|
-|`PromptRequiredDocSpec`|iface||45-48|export interface PromptRequiredDocSpec|
-|`PromptCommandExecutionPlan`|iface||54-68|export interface PromptCommandExecutionPlan|
-|`PromptCommandPostCreateHookContext`|iface||74-79|interface PromptCommandPostCreateHookContext|
-|`PromptCommandPostCreateHook`|type||85||
-|`PromptCommandDebugOptions`|iface||91-94|interface PromptCommandDebugOptions|
-|`PromptCommandSessionMessageOptions`|iface||100-102|interface PromptCommandSessionMessageOptions|
-|`PromptCommandSessionSwitchOptions`|iface||108-110|interface PromptCommandSessionSwitchOptions|
-|`PromptCommandActiveContext`|iface||116-121|interface PromptCommandActiveContext extends PromptComman...|
-|`PromptCommandSessionEntry`|iface||127-133|interface PromptCommandSessionEntry|
-|`PromptCommandSessionContext`|iface||139-151|interface PromptCommandSessionContext|
-|`PromptCommandContextError`|iface||157-159|interface PromptCommandContextError extends Error|
-|`isUsablePromptSessionFile`|fn||174-192|function isUsablePromptSessionFile(|
-|`resolvePromptSessionFile`|fn||202-212|function resolvePromptSessionFile(sessionFile: string | u...|
-|`writePromptExecutionSessionSnapshot`|fn||226-252|function writePromptExecutionSessionSnapshot(|
-|`createPromptExecutionSessionFile`|fn||265-288|function createPromptExecutionSessionFile(|
-|`getPromptSessionCwd`|fn||296-304|function getPromptSessionCwd(ctx?: PromptCommandSessionCo...|
-|`getPromptSessionFile`|fn||312-320|function getPromptSessionFile(ctx?: PromptCommandSessionC...|
-|`getPromptContextCwd`|fn||328-334|function getPromptContextCwd(ctx?: PromptCommandSessionCo...|
-|`resolvePromptCommandSwitchContext`|fn||344-359|function resolvePromptCommandSwitchContext(|
-|`syncPromptCommandProcessCwd`|fn||370-390|function syncPromptCommandProcessCwd(expectedPath: string...|
-|`readPromptSessionFileCwd`|fn||398-422|function readPromptSessionFileCwd(sessionFile: string): s...|
-|`readPromptSessionJsonLines`|fn||431-478|function readPromptSessionJsonLines(|
-|`preservePromptCommandExecutionTranscript`|fn||488-585|function preservePromptCommandExecutionTranscript(plan: P...|
-|`verifyPromptCommandSessionTarget`|fn||598-642|function verifyPromptCommandSessionTarget(|
-|`verifyPromptCommandClosureArtifacts`|fn||652-687|function verifyPromptCommandClosureArtifacts(|
-|`switchPromptCommandSession`|fn||698-727|async function switchPromptCommandSession(|
-|`isPromptCommandStaleContextError`|fn||736-739|function isPromptCommandStaleContextError(error: unknown)...|
-|`attachPromptCommandErrorContext`|fn||748-756|function attachPromptCommandErrorContext(|
-|`getPromptCommandErrorContext`|fn||764-770|export function getPromptCommandErrorContext(|
-|`runCapture`|fn||851-856|function runCapture(command: string[], cwd: string): Retu...|
-|`setPromptCommandPostCreateHookForTests`|fn||864-868|export function setPromptCommandPostCreateHookForTests(|
-|`resolvePromptDocsRoot`|fn||877-880|function resolvePromptDocsRoot(projectBase: string, confi...|
-|`resolveWorktreePaths`|fn||890-917|function resolveWorktreePaths(|
-|`sanitizePromptWorktreeBranchName`|fn||925-927|function sanitizePromptWorktreeBranchName(branch: string)...|
-|`validatePromptWorktreeName`|fn||935-940|function validatePromptWorktreeName(wtName: string): boolean|
-|`throwPromptGitStatusError`|fn||948-950|function throwPromptGitStatusError(): never|
-|`validatePromptGitState`|fn||961-1005|function validatePromptGitState(projectBase: string, conf...|
-|`resolveCurrentPromptBranchName`|fn||1013-1018|function resolveCurrentPromptBranchName(gitRoot: string):...|
-|`formatPromptWorktreeExecutionId`|fn||1032-1034|function formatPromptWorktreeExecutionId(timestamp: Date)...|
-|`getNextPromptWorktreeExecutionId`|fn||1041-1054|function getNextPromptWorktreeExecutionId(): string|
-|`buildPromptWorktreeName`|fn||1065-1076|function buildPromptWorktreeName(gitRoot: string, config:...|
-|`promptWorktreeBranchExists`|fn||1085-1094|function promptWorktreeBranchExists(gitRoot: string, bran...|
-|`promptWorktreeRegistered`|fn||1103-1114|function promptWorktreeRegistered(gitRoot: string, worktr...|
-|`cleanupPromptWorktreeCreation`|fn||1124-1138|function cleanupPromptWorktreeCreation(|
-|`createPromptWorktree`|fn||1152-1272|function createPromptWorktree(|
-|`deletePromptWorktree`|fn||1285-1345|function deletePromptWorktree(|
-|`getPromptRequiredDocs`|fn||1354-1356|export function getPromptRequiredDocs(promptName: PromptC...|
-|`validatePromptRequiredDocs`|fn||1369-1420|export function validatePromptRequiredDocs(|
-|`preparePromptCommandExecution`|fn||1437-1513|export function preparePromptCommandExecution(|
-|`activatePromptCommandExecution`|fn||1524-1557|export async function activatePromptCommandExecution(|
-|`restorePromptCommandExecution`|fn||1569-1633|export async function restorePromptCommandExecution(|
-|`abortPromptCommandExecution`|fn||1644-1690|export async function abortPromptCommandExecution(|
-|`finalizePromptCommandExecution`|fn||1701-1804|export async function finalizePromptCommandExecution(|
-|`classifyPromptCommandOutcome`|fn||1812-1816|export function classifyPromptCommandOutcome(|
+|`PromptRequiredDocSpec`|iface||42-45|export interface PromptRequiredDocSpec|
+|`PromptCommandExecutionPlan`|iface||51-65|export interface PromptCommandExecutionPlan|
+|`PromptCommandPostCreateHookContext`|iface||71-76|interface PromptCommandPostCreateHookContext|
+|`PromptCommandPostCreateHook`|type||82||
+|`PromptCommandDebugOptions`|iface||88-91|interface PromptCommandDebugOptions|
+|`PromptCommandSessionMessageOptions`|iface||97-99|interface PromptCommandSessionMessageOptions|
+|`PromptCommandSessionSwitchOptions`|iface||105-107|interface PromptCommandSessionSwitchOptions|
+|`PromptCommandActiveContext`|iface||113-118|interface PromptCommandActiveContext extends PromptComman...|
+|`PromptCommandSessionEntry`|iface||124-130|interface PromptCommandSessionEntry|
+|`PromptCommandSessionContext`|iface||136-148|interface PromptCommandSessionContext|
+|`PromptCommandContextError`|iface||154-156|interface PromptCommandContextError extends Error|
+|`isUsablePromptSessionFile`|fn||171-189|function isUsablePromptSessionFile(|
+|`resolvePromptSessionFile`|fn||199-209|function resolvePromptSessionFile(sessionFile: string | u...|
+|`writePromptExecutionSessionSnapshot`|fn||223-249|function writePromptExecutionSessionSnapshot(|
+|`createPromptExecutionSessionFile`|fn||262-285|function createPromptExecutionSessionFile(|
+|`getPromptSessionCwd`|fn||293-301|function getPromptSessionCwd(ctx?: PromptCommandSessionCo...|
+|`getPromptSessionFile`|fn||309-317|function getPromptSessionFile(ctx?: PromptCommandSessionC...|
+|`getPromptContextCwd`|fn||325-331|function getPromptContextCwd(ctx?: PromptCommandSessionCo...|
+|`resolvePromptCommandSwitchContext`|fn||341-356|function resolvePromptCommandSwitchContext(|
+|`syncPromptCommandProcessCwd`|fn||367-387|function syncPromptCommandProcessCwd(expectedPath: string...|
+|`readPromptSessionFileCwd`|fn||395-419|function readPromptSessionFileCwd(sessionFile: string): s...|
+|`readPromptSessionJsonLines`|fn||428-475|function readPromptSessionJsonLines(|
+|`preservePromptCommandExecutionTranscript`|fn||485-582|export function preservePromptCommandExecutionTranscript(...|
+|`verifyPromptCommandSessionTarget`|fn||595-639|function verifyPromptCommandSessionTarget(|
+|`verifyPromptCommandClosureArtifacts`|fn||649-684|function verifyPromptCommandClosureArtifacts(|
+|`switchPromptCommandSession`|fn||695-724|async function switchPromptCommandSession(|
+|`isPromptCommandStaleContextError`|fn||733-736|function isPromptCommandStaleContextError(error: unknown)...|
+|`attachPromptCommandErrorContext`|fn||745-753|function attachPromptCommandErrorContext(|
+|`getPromptCommandErrorContext`|fn||761-767|export function getPromptCommandErrorContext(|
+|`runCapture`|fn||845-850|function runCapture(command: string[], cwd: string): Retu...|
+|`listPromptTrackedBasePathChanges`|fn||860-878|function listPromptTrackedBasePathChanges(basePath: strin...|
+|`finalizePromptCommandMerge`|fn||888-1010|function finalizePromptCommandMerge(|
+|`setPromptCommandPostCreateHookForTests`|fn||1018-1022|export function setPromptCommandPostCreateHookForTests(|
+|`resolvePromptDocsRoot`|fn||1031-1034|function resolvePromptDocsRoot(projectBase: string, confi...|
+|`resolveWorktreePaths`|fn||1044-1071|function resolveWorktreePaths(|
+|`sanitizePromptWorktreeBranchName`|fn||1079-1081|function sanitizePromptWorktreeBranchName(branch: string)...|
+|`validatePromptWorktreeName`|fn||1089-1094|function validatePromptWorktreeName(wtName: string): boolean|
+|`throwPromptGitStatusError`|fn||1102-1104|function throwPromptGitStatusError(): never|
+|`validatePromptGitState`|fn||1115-1159|export function validatePromptGitState(projectBase: strin...|
+|`resolveCurrentPromptBranchName`|fn||1167-1172|function resolveCurrentPromptBranchName(gitRoot: string):...|
+|`formatPromptWorktreeExecutionId`|fn||1186-1188|function formatPromptWorktreeExecutionId(timestamp: Date)...|
+|`getNextPromptWorktreeExecutionId`|fn||1195-1208|function getNextPromptWorktreeExecutionId(): string|
+|`buildPromptWorktreeName`|fn||1219-1230|function buildPromptWorktreeName(gitRoot: string, config:...|
+|`promptWorktreeBranchExists`|fn||1239-1248|function promptWorktreeBranchExists(gitRoot: string, bran...|
+|`promptWorktreeRegistered`|fn||1257-1268|function promptWorktreeRegistered(gitRoot: string, worktr...|
+|`cleanupPromptWorktreeCreation`|fn||1278-1292|function cleanupPromptWorktreeCreation(|
+|`createPromptWorktree`|fn||1306-1426|function createPromptWorktree(|
+|`deletePromptWorktree`|fn||1439-1499|export function deletePromptWorktree(|
+|`getPromptRequiredDocs`|fn||1508-1510|export function getPromptRequiredDocs(promptName: PromptC...|
+|`validatePromptRequiredDocs`|fn||1523-1574|export function validatePromptRequiredDocs(|
+|`preparePromptCommandExecution`|fn||1591-1667|export function preparePromptCommandExecution(|
+|`activatePromptCommandExecution`|fn||1678-1711|export async function activatePromptCommandExecution(|
+|`restorePromptCommandExecution`|fn||1723-1787|export async function restorePromptCommandExecution(|
+|`abortPromptCommandExecution`|fn||1798-1844|export async function abortPromptCommandExecution(|
+|`finalizePromptCommandExecution`|fn||1855-1943|export async function finalizePromptCommandExecution(|
+|`classifyPromptCommandOutcome`|fn||1951-1955|export function classifyPromptCommandOutcome(|
 
 
 ---
@@ -3093,7 +3293,7 @@ import type { PromptCommandExecutionPlan } from "./prompt-command-runtime.js";
 
 ---
 
-# prompts.ts | TypeScript | 316L | 9 symbols | 7 imports | 17 comments
+# prompts.ts | TypeScript | 314L | 9 symbols | 7 imports | 17 comments
 > Path: `src/core/prompts.ts`
 - @brief Renders bundled pi-usereq prompts for the current project context.
 - @details Applies placeholder substitution, legacy tool-name rewrites, and conditional pi.dev governance guidance before prompt text is sent to the agent. Runtime is linear in prompt size plus replacement count. Side effects are limited to filesystem reads used for manifest checks and bundled prompt loading.
@@ -3111,7 +3311,7 @@ import { readBundledInstruction, readBundledPrompt } from "./resources.js";
 
 ## Definitions
 
-### fn `function buildPiDevConformanceBlock(promptName: string, projectBase: string): string` (L111-120)
+### fn `function buildPiDevConformanceBlock(promptName: string, projectBase: string): string` (L109-118)
 - @brief Builds the conditional pi.dev governance block for one rendered prompt.
 - @details Emits the manifest-driven governance rules only when the selected bundled prompt can analyze or mutate source code and the project root contains the pi.dev manifest. Time complexity O(1). No filesystem writes.
 - @param[in] promptName {string} Bundled prompt identifier.
@@ -3119,7 +3319,7 @@ import { readBundledInstruction, readBundledPrompt } from "./resources.js";
 - @return {string} Markdown bullet block or the empty string when injection is not applicable.
 - @satisfies REQ-032, REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275
 
-### fn `function injectPiDevConformanceBlock(text: string, promptName: string, projectBase: string): string` (L131-138)
+### fn `function injectPiDevConformanceBlock(text: string, promptName: string, projectBase: string): string` (L129-136)
 - @brief Injects the pi.dev governance block into the prompt behavior section.
 - @details Inserts the block immediately after the `## Behavior` heading so downstream agents evaluate the rule before workflow steps. Leaves prompts unchanged when no behavior section exists or the block is already present. Time complexity O(n).
 - @param[in] text {string} Prompt markdown after placeholder replacement.
@@ -3128,14 +3328,14 @@ import { readBundledInstruction, readBundledPrompt } from "./resources.js";
 - @return {string} Prompt markdown with zero or one injected conformance block.
 - @satisfies REQ-032, REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275
 
-### fn `export function adaptPromptForInternalTools(text: string): string` (L147-153)
+### fn `export function adaptPromptForInternalTools(text: string): string` (L145-151)
 - @brief Rewrites bundled prompt tool references from legacy `req --...` syntax to internal tool names.
 - @details Applies deterministic global regex replacements so prompt text matches the extension-registered tool surface instead of the standalone CLI spelling. Time complexity O(p*r) where p is pattern count and r is prompt length.
 - @param[in] text {string} Prompt markdown before tool-reference normalization.
 - @return {string} Prompt markdown with internal tool names.
 - @satisfies REQ-003
 
-### fn `export function applyReplacements(text: string, replacements: Record<string, string>): string` (L163-169)
+### fn `export function applyReplacements(text: string, replacements: Record<string, string>): string` (L161-167)
 - @brief Applies literal placeholder replacements to bundled prompt markdown.
 - @details Replaces every placeholder token using split/join semantics so all occurrences are updated without regex escaping. Time complexity O(t*n) where t is replacement count and n is prompt length.
 - @param[in] text {string} Prompt markdown containing placeholder tokens.
@@ -3143,7 +3343,7 @@ import { readBundledInstruction, readBundledPrompt } from "./resources.js";
 - @return {string} Prompt markdown with all placeholder tokens expanded.
 - @satisfies REQ-002
 
-### fn `function buildPromptExecutionBlock(` (L179-201)
+### fn `function buildPromptExecutionBlock(` (L177-199)
 - @brief Builds the prompt-command execution block injected at prompt start.
 - @details Serializes the already-completed repository validation, prompt-specific required-doc validation, worktree routing decision, and extension-owned lifecycle responsibilities so downstream agents do not repeat command-side orchestration. Time complexity is O(d) in required-doc count. No external state is mutated.
 - @param[in] promptName {PromptCommandName} Bundled prompt identifier.
@@ -3151,7 +3351,7 @@ import { readBundledInstruction, readBundledPrompt } from "./resources.js";
 - @return {string} Markdown block or the empty string when runtime execution metadata is unavailable.
 - @satisfies REQ-200, REQ-201, REQ-202, REQ-206, REQ-207, REQ-208, REQ-209
 
-### fn `function injectPromptExecutionBlock(` (L211-222)
+### fn `function injectPromptExecutionBlock(` (L209-220)
 - @brief Injects the prompt-command execution block near the start of the rendered prompt.
 - @details Inserts the execution block immediately after the first level-1 heading so downstream agents evaluate extension-owned orchestration before workflow steps. Leaves prompts unchanged when no execution block is provided or when the block is already present. Time complexity O(n).
 - @param[in] text {string} Prompt markdown after placeholder replacement.
@@ -3159,7 +3359,7 @@ import { readBundledInstruction, readBundledPrompt } from "./resources.js";
 - @param[in] executionPlan {PromptCommandExecutionPlan | undefined} Prepared execution plan.
 - @return {string} Prompt markdown with zero or one injected execution block.
 
-### fn `function buildPromptReplacements(` (L234-246)
+### fn `function buildPromptReplacements(` (L232-244)
 - @brief Builds prompt-specific runtime placeholder replacements.
 - @details Merges shared path substitutions with prompt-scoped runtime values for `%%ARGS%%` and `%%PROMPT%%`. Time complexity is O(g log g + s) due to delegated path replacement building, where g is guideline count and s is source-directory count. Side effects are limited to filesystem reads delegated to shared path-context helpers.
 - @param[in] promptName {string} Bundled prompt identifier without the `req-` prefix.
@@ -3169,7 +3369,7 @@ import { readBundledInstruction, readBundledPrompt } from "./resources.js";
 - @return {Record<string, string>} Prompt-specific placeholder-to-value map.
 - @satisfies REQ-002, REQ-211
 
-### fn `function renderBundledCommitInstruction(` (L258-272)
+### fn `function renderBundledCommitInstruction(` (L256-270)
 - @brief Renders the bundled git instruction injected through `%%COMMIT%%`.
 - @details Selects `resources/instructions/git_commit.md` when automatic git commit is enabled and `resources/instructions/git_read-only.md` otherwise, then applies the same runtime placeholder substitutions used by bundled prompts before returning the rendered markdown. Time complexity is O(n + g log g + s) where n is instruction size, g is guideline count, and s is source-directory count. Side effects are limited to filesystem reads.
 - @param[in] promptName {string} Bundled prompt identifier without the `req-` prefix.
@@ -3179,7 +3379,7 @@ import { readBundledInstruction, readBundledPrompt } from "./resources.js";
 - @return {string} Rendered bundled git instruction selected for the current automatic-commit mode.
 - @satisfies REQ-211, REQ-213, REQ-214
 
-### fn `export function renderPrompt(` (L285-316)
+### fn `export function renderPrompt(` (L283-314)
 - @brief Renders a bundled prompt for the current project context.
 - @details Loads the bundled markdown template, expands configuration-derived placeholders, injects extension-owned execution guidance plus conditional pi.dev governance guidance, expands the optional bundled commit instruction, and rewrites legacy tool references to internal names. Time complexity O(n) relative to prompt size plus delegated commit-instruction rendering. No tracked files are modified.
 - @param[in] promptName {string} Bundled prompt identifier.
@@ -3193,211 +3393,223 @@ import { readBundledInstruction, readBundledPrompt } from "./resources.js";
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
 |---|---|---|---|---|
-|`buildPiDevConformanceBlock`|fn||111-120|function buildPiDevConformanceBlock(promptName: string, p...|
-|`injectPiDevConformanceBlock`|fn||131-138|function injectPiDevConformanceBlock(text: string, prompt...|
-|`adaptPromptForInternalTools`|fn||147-153|export function adaptPromptForInternalTools(text: string)...|
-|`applyReplacements`|fn||163-169|export function applyReplacements(text: string, replaceme...|
-|`buildPromptExecutionBlock`|fn||179-201|function buildPromptExecutionBlock(|
-|`injectPromptExecutionBlock`|fn||211-222|function injectPromptExecutionBlock(|
-|`buildPromptReplacements`|fn||234-246|function buildPromptReplacements(|
-|`renderBundledCommitInstruction`|fn||258-272|function renderBundledCommitInstruction(|
-|`renderPrompt`|fn||285-316|export function renderPrompt(|
+|`buildPiDevConformanceBlock`|fn||109-118|function buildPiDevConformanceBlock(promptName: string, p...|
+|`injectPiDevConformanceBlock`|fn||129-136|function injectPiDevConformanceBlock(text: string, prompt...|
+|`adaptPromptForInternalTools`|fn||145-151|export function adaptPromptForInternalTools(text: string)...|
+|`applyReplacements`|fn||161-167|export function applyReplacements(text: string, replaceme...|
+|`buildPromptExecutionBlock`|fn||177-199|function buildPromptExecutionBlock(|
+|`injectPromptExecutionBlock`|fn||209-220|function injectPromptExecutionBlock(|
+|`buildPromptReplacements`|fn||232-244|function buildPromptReplacements(|
+|`renderBundledCommitInstruction`|fn||256-270|function renderBundledCommitInstruction(|
+|`renderPrompt`|fn||283-314|export function renderPrompt(|
 
 
 ---
 
-# reference-payload.ts | TypeScript | 752L | 28 symbols | 5 imports | 27 comments
-> Path: `src/core/reference-payload.ts`
-- @brief Builds agent-oriented JSON payloads for `files-references` and `references`.
-- @details Converts analyzed source files into deterministic JSON sections ordered for LLM traversal, including repository structure, per-file metrics, imports, symbols, structured Doxygen fields, and structured comment evidence. Runtime is O(F log F + S) where F is file count and S is total source size. Side effects are limited to filesystem reads and optional stderr logging.
+# req-references-command.ts | TypeScript | 175L | 7 symbols | 6 imports | 10 comments
+> Path: `src/core/req-references-command.ts`
+- @brief Implements the specialized `req-references` slash-command workflow.
+- @details Performs slash-command-owned git validation reuse, reference-file generation, targeted staging, fixed-message commit creation, and post-commit cleanliness verification without creating a worktree or starting an LLM session. Runtime is dominated by git subprocess execution plus source-summary generation and one documentation write. Side effects include filesystem writes and git index/history mutation.
 
 ## Imports
 ```
-import fs from "node:fs";
+import { spawnSync } from "node:child_process";
 import path from "node:path";
-import {
-import { detectLanguage } from "./compress.js";
-import {
+import type { UseReqConfig } from "./config.js";
+import { ReqError } from "./errors.js";
+import { validatePromptGitState } from "./prompt-command-runtime.js";
+import { runReferences } from "./tool-runner.js";
 ```
 
 ## Definitions
 
-- type `export type ReferenceToolScope = "explicit-files" | "configured-source-directories";` (L27)
-- @brief Enumerates supported references-payload scopes.
-- @details Distinguishes explicit-file requests from configured project scans while preserving one stable JSON contract. The alias is compile-time only and introduces no runtime cost.
-- type `export type ReferenceFileStatus = "analyzed" | "error" | "skipped";` (L33)
-- @brief Enumerates supported per-file references entry statuses.
-- @details Separates analyzed files, analysis failures, and skipped inputs so downstream agents can branch without reparsing stderr text. The alias is compile-time only and introduces no runtime cost.
-### iface `export interface ReferenceLineRange` (L39-43)
-- @brief Describes one numeric source line range.
-- @details Exposes start and end line numbers plus the same inclusive range as a numeric tuple for direct agent access. The interface is compile-time only and introduces no runtime cost.
-
-### iface `export interface ReferenceImportEntry extends ReferenceLineRange` : ReferenceLineRange (L49-52)
-- @brief Describes one structured import record.
-- @details Stores the normalized import identity, raw import statement, and declaration line range without requiring agents to parse markdown blocks. The interface is compile-time only and introduces no runtime cost.
-
-### iface `export interface ReferenceCommentEntry extends ReferenceLineRange` : ReferenceLineRange (L58-61)
-- @brief Describes one structured standalone or attached comment record.
-- @details Preserves normalized comment text plus per-line comment fragments so agents can consume comment evidence without reparsing source delimiters. The interface is compile-time only and introduces no runtime cost.
-
-### iface `export interface ReferenceExitPointEntry` (L67-70)
-- @brief Describes one structured exit-point annotation.
-- @details Preserves the normalized exit expression text together with its source line number for downstream reasoning about control flow hints. The interface is compile-time only and introduces no runtime cost.
-
-### iface `export interface ReferenceSymbolEntry extends ReferenceLineRange` : ReferenceLineRange (L76-96)
-- @brief Describes one structured symbol record.
-- @details Orders direct-access identity fields before hierarchy, locations, Doxygen metadata, and comment evidence so agents can branch without reparsing monolithic summaries. The interface is compile-time only and introduces no runtime cost.
-
-### iface `export interface ReferenceToolFileEntry extends ReferenceLineRange` : ReferenceLineRange (L102-115)
-- @brief Describes one per-file references payload entry.
-- @details Stores canonical identity, line metrics, structured imports, structured symbols, structured comment evidence, and optional file-level Doxygen metadata. Derivable identity and filesystem-probe fields are intentionally omitted to reduce token cost. The interface is compile-time only and introduces no runtime cost.
-
-### iface `export interface ReferenceToolRequestSection` (L121-130)
-- @brief Describes the request section of the references payload.
-- @details Captures tool identity, scope, base directory, requested path inventory, and configured source-directory scope so agents can reason about how the file set was selected. The interface is compile-time only and introduces no runtime cost.
-
-### iface `export interface ReferenceToolSummarySection` (L136-147)
-- @brief Describes the summary section of the references payload.
-- @details Exposes aggregate file, symbol, import, comment, and Doxygen counts as numeric fields plus deterministic symbol-kind totals. The interface is compile-time only and introduces no runtime cost.
+### iface `export interface ReqReferencesCommandPlan` (L30-35)
+- @brief Describes the prepared execution facts for one `req-references` run.
+- @details Stores the validated project base, resolved git root, target references path, and fixed commit message needed by the specialized direct-write workflow. The interface is compile-time only and introduces no runtime cost.
 
-### iface `export interface ReferenceRepositoryTreeNode` (L153-159)
-- @brief Describes one repository tree node in the references payload.
-- @details Encodes directory and file hierarchy without ASCII-art decoration so agents can traverse repository structure as structured JSON. The interface is compile-time only and introduces no runtime cost.
+### fn `function runCapture(command: string[], cwd: string): ReturnType<typeof spawnSync>` (L44-49)
+- @brief Executes one synchronous subprocess and captures UTF-8 output.
+- @details Delegates to `spawnSync(...)`, preserves the supplied working directory, and returns the raw result so callers can interpret git exit status plus diagnostics deterministically. Runtime is dominated by external process execution. Side effects include subprocess creation.
+- @param[in] command {string[]} Executable plus argument vector.
+- @param[in] cwd {string} Working directory for the subprocess.
+- @return {ReturnType<typeof spawnSync>} Captured subprocess result.
 
-### iface `export interface ReferenceToolRepositorySection` (L165-169)
-- @brief Describes the repository section of the references payload.
-- @details Stores configured source-directory scope, the canonical analyzed file list, and the structured directory tree used during analysis. Static root-path echoes are intentionally omitted to reduce token cost. The interface is compile-time only and introduces no runtime cost.
+### fn `function buildIgnoredGitStatusPaths(` (L59-73)
+- @brief Builds the set of git-status paths ignored for cleanliness checks.
+- @details Reuses the configured debug-log path exception already honored by prompt-command git validation so extension-owned debug artifacts do not block `req-references` execution or post-commit cleanliness verification. Runtime is O(p) in path length. No external state is mutated.
+- @param[in] projectBase {string} Absolute project base path.
+- @param[in] gitRoot {string} Absolute git root path.
+- @param[in] config {UseReqConfig} Effective project configuration.
+- @return {Set<string>} Slash-normalized relative paths ignored during git-status evaluation.
 
-### iface `export interface ReferenceToolPayload` (L175-179)
-- @brief Describes the full agent-oriented references payload.
-- @details Exposes only aggregate analysis totals, repository structure, and per-file reference records, omitting request echoes that are already known to the caller or encoded in the tool registration. The interface is compile-time only and introduces no runtime cost.
+### fn `function listResidualGitStatusLines(` (L84-102)
+- @brief Lists residual git-status rows after ignored extension-owned paths are filtered out.
+- @details Executes `git status --porcelain`, drops the configured debug-log path when present inside the active repository, and returns all remaining staged or unstaged rows used for post-commit cleanliness verification. Runtime is dominated by one git subprocess plus O(n) parsing in status-line count. Side effects include subprocess creation.
+- @param[in] projectBase {string} Absolute project base path.
+- @param[in] gitRoot {string} Absolute git root path.
+- @param[in] config {UseReqConfig} Effective project configuration.
+- @return {string[]} Residual status rows after ignored paths are removed.
+- @throws {ReqError} Throws when git status cannot be inspected.
+
+### fn `function getGitAddTargetPath(gitRoot: string, absolutePath: string): string` (L111-117)
+- @brief Converts one absolute repository path into the preferred git-add target syntax.
+- @details Emits a slash-normalized relative path when the target is inside the git root and falls back to the absolute path otherwise, preserving deterministic add semantics across nested project-base layouts. Runtime is O(p) in path length. No external state is mutated.
+- @param[in] gitRoot {string} Absolute git root path.
+- @param[in] absolutePath {string} Absolute path to stage.
+- @return {string} Relative or absolute git-add target path.
+
+### fn `export function prepareReqReferencesCommandExecution(` (L128-141)
+- @brief Prepares the specialized `req-references` execution plan.
+- @details Reuses slash-command-owned git validation, resolves the configured references document path, and returns the fixed commit metadata consumed by the direct-write workflow. Runtime is dominated by git validation subprocesses. Side effects include subprocess creation delegated through `validatePromptGitState(...)`.
+- @param[in] projectBase {string} Absolute project base path.
+- @param[in] config {UseReqConfig} Effective project configuration.
+- @return {ReqReferencesCommandPlan} Prepared execution plan for direct references regeneration.
+- @throws {ReqError} Throws when git validation fails.
+- @satisfies REQ-200, REQ-299
+
+### fn `export function executeReqReferencesCommandExecution(` (L152-175)
+- @brief Executes the specialized `req-references` direct-write workflow.
+- @details Regenerates `REFERENCES.md` through the same source-summary path used by the `references` tool, stages only the target file, creates the fixed-message commit, and verifies that no residual git-status rows remain after ignored extension-owned debug artifacts are filtered out. Runtime is dominated by summary generation plus three git subprocesses. Side effects include documentation writes, index mutation, commit creation, and subprocess creation.
+- @param[in] plan {ReqReferencesCommandPlan} Prepared direct-write execution plan.
+- @param[in] config {UseReqConfig} Effective project configuration.
+- @return {void} No return value.
+- @throws {ReqError} Throws when reference generation, staging, commit creation, or cleanliness verification fails.
+- @satisfies REQ-300, REQ-301, REQ-302, REQ-303
 
-### iface `export interface BuildReferenceToolPayloadOptions` (L185-192)
-- @brief Describes the options required to build one references payload.
-- @details Supplies tool identity, scope, base directory, requested paths, and optional configured source directories while keeping payload construction deterministic. The interface is compile-time only and introduces no runtime cost.
+## Symbol Index
+|Symbol|Kind|Vis|Lines|Sig|
+|---|---|---|---|---|
+|`ReqReferencesCommandPlan`|iface||30-35|export interface ReqReferencesCommandPlan|
+|`runCapture`|fn||44-49|function runCapture(command: string[], cwd: string): Retu...|
+|`buildIgnoredGitStatusPaths`|fn||59-73|function buildIgnoredGitStatusPaths(|
+|`listResidualGitStatusLines`|fn||84-102|function listResidualGitStatusLines(|
+|`getGitAddTargetPath`|fn||111-117|function getGitAddTargetPath(gitRoot: string, absolutePat...|
+|`prepareReqReferencesCommandExecution`|fn||128-141|export function prepareReqReferencesCommandExecution(|
+|`executeReqReferencesCommandExecution`|fn||152-175|export function executeReqReferencesCommandExecution(|
 
-### fn `function canonicalizeReferencePath(targetPath: string, baseDir: string): string` (L201-209)
-- @brief Canonicalizes one filesystem path relative to the payload base directory.
-- @details Emits a slash-normalized relative path when the target is under the base directory; otherwise emits the normalized absolute path. Runtime is O(p) in path length. No side effects occur.
-- @param[in] targetPath {string} Absolute or relative filesystem path.
-- @param[in] baseDir {string} Base directory used for relative canonicalization.
-- @return {string} Canonicalized path string.
 
-### fn `function buildLineRange(startLineNumber: number, endLineNumber: number): ReferenceLineRange` (L218-224)
-- @brief Builds one structured line-range record.
-- @details Duplicates the inclusive range as start, end, and tuple fields so callers can address whichever shape is most convenient. Runtime is O(1). No side effects occur.
-- @param[in] startLineNumber {number} Inclusive start line number.
-- @param[in] endLineNumber {number} Inclusive end line number.
-- @return {ReferenceLineRange} Structured line-range record.
+---
 
-### fn `function extractCommentText(commentElement: SourceElement, maxLength = 0): string` (L233-253)
-- @brief Extracts normalized plain text from one comment element.
-- @details Removes language comment markers, drops delimiter-only lines, joins content with spaces, and optionally truncates the result. Runtime is O(n) in comment length. No side effects occur.
-- @param[in] commentElement {SourceElement} Comment element.
-- @param[in] maxLength {number} Optional maximum output length; `0` disables truncation.
-- @return {string} Cleaned comment text.
+# req-reset-command.ts | TypeScript | 323L | 12 symbols | 7 imports | 14 comments
+> Path: `src/core/req-reset-command.ts`
+- @brief Implements the specialized `req-reset` slash-command workflow.
+- @details Performs non-agentic prompt-orchestration recovery by preserving the current execution-session transcript when available, restoring the original session-backed `base-path`, force-removing every generated sibling worktree and matching branch, and returning deterministic cleanup facts to the extension command handler. Runtime is dominated by session switching plus git subprocess execution. Side effects include session-file reads and writes, active-session replacement, host-process cwd mutation, worktree deletion, branch deletion, and filesystem removal.
 
-### fn `function extractCommentLines(commentElement: SourceElement): string[]` (L261-275)
-- @brief Extracts cleaned individual lines from one comment element.
-- @details Removes language comment markers while preserving line granularity for structured comment payloads. Runtime is O(n) in comment length. No side effects occur.
-- @param[in] commentElement {SourceElement} Comment element.
-- @return {string[]} Cleaned comment lines.
+## Imports
+```
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import {
+import { ReqError } from "./errors.js";
+import {
+import { resolveRuntimeGitPath } from "./runtime-project-paths.js";
+```
 
-### fn `function buildCommentMaps(elements: SourceElement[]): [Record<number, SourceElement[]>, SourceElement[], string]` (L283-333)
-- @brief Associates nearby comment blocks with definitions and standalone comment groups.
-- @details Reuses the repository comment-attachment heuristic that binds comments within three lines of a definition while preserving early file-description text. Runtime is O(n log n). No side effects occur.
-- @param[in] elements {SourceElement[]} Analyzed source elements.
-- @return {[Record<number, SourceElement[]>, SourceElement[], string]} Attached-comment map, standalone comments, and compact file description.
+## Definitions
 
-### fn `function resolveSymbolName(element: SourceElement): string` (L341-343)
-- @brief Resolves one stable symbol name from an analyzed element.
-- @details Prefers explicit analyzer name metadata, then falls back to the derived signature or the first source line so every symbol retains a direct-access identifier. Runtime is O(1). No side effects occur.
-- @param[in] element {SourceElement} Source element.
-- @return {string} Stable symbol name.
+### iface `export interface ReqResetCommandPlan` (L34-40)
+- @brief Describes the prepared execution facts for one `req-reset` run.
+- @details Stores the validated project base, resolved git root, sibling-worktree parent directory, generated-name matcher, and optional persisted prompt execution plan used for transcript preservation plus base-path restoration. The interface is compile-time only and introduces no runtime cost.
 
-### fn `function resolveParentElement(definitions: SourceElement[], child: SourceElement): SourceElement | undefined` (L352-361)
-- @brief Resolves the direct parent element for one child symbol.
-- @details Matches by parent name plus inclusive line containment and chooses the deepest enclosing definition. Runtime is O(n) in definition count. No side effects occur.
-- @param[in] definitions {SourceElement[]} Sorted definition elements.
-- @param[in] child {SourceElement} Candidate child symbol.
-- @return {SourceElement | undefined} Matched parent definition when available.
+### iface `export interface ReqResetCommandExecutionResult` (L46-53)
+- @brief Describes the outcome of one `req-reset` execution attempt.
+- @details Captures the last valid session-bound context, transcript-preservation and base-path-restoration facts, removed generated worktree and branch names, and one aggregated failure string when any recovery step fails. The interface is compile-time only and introduces no runtime cost.
 
-### fn `function buildCommentEntry(commentElement: SourceElement): ReferenceCommentEntry` (L369-376)
-- @brief Builds one structured comment record from a comment element.
-- @details Preserves numeric line-range metadata plus normalized text and per-line fragments. Runtime is O(n) in comment length. No side effects occur.
-- @param[in] commentElement {SourceElement} Source comment element.
-- @return {ReferenceCommentEntry} Structured comment record.
+- type `type ReqResetCommandContext = Parameters<typeof restorePromptCommandExecution>[1];` (L59)
+- @brief Describes the session-bound context surface reused during `req-reset` recovery.
+- @details Reuses the session-switching contract already accepted by `restorePromptCommandExecution(...)` so the dedicated reset command can restore the original session without depending on concrete pi runtime classes. The alias is compile-time only and introduces no runtime cost.
+### fn `function runCapture(command: string[], cwd: string): ReturnType<typeof spawnSync>` (L68-73)
+- @brief Executes one synchronous subprocess and captures UTF-8 output.
+- @details Delegates to `spawnSync(...)`, preserves the supplied working directory, and returns the raw result so callers can interpret git exit status plus diagnostics deterministically. Runtime is dominated by external process execution. Side effects include subprocess creation.
+- @param[in] command {string[]} Executable plus argument vector.
+- @param[in] cwd {string} Working directory for the subprocess.
+- @return {ReturnType<typeof spawnSync>} Captured subprocess result.
 
-### fn `function buildRepositoryTree(canonicalPaths: string[]): ReferenceRepositoryTreeNode` (L384-443)
-- @brief Builds one structured repository tree from canonical file paths.
-- @details Materializes a nested directory map and converts it into recursively ordered JSON nodes without decorative ASCII formatting. Runtime is O(n log n) in path count. No side effects occur.
-- @param[in] canonicalPaths {string[]} Canonical file paths.
-- @return {ReferenceRepositoryTreeNode} Structured repository tree rooted at `.`.
+### fn `function escapeReqResetRegExpLiteral(text: string): string` (L81-83)
+- @brief Escapes one literal string for safe JavaScript regular-expression reuse.
+- @details Prefixes every regular-expression metacharacter with `\\` so generated worktree-name patterns can embed persisted prefixes and repository basenames without introducing unintended matcher semantics. Runtime is O(n) in string length. No external state is mutated.
+- @param[in] text {string} Literal text fragment.
+- @return {string} Regular-expression-safe literal fragment.
 
-### fn `const ensureDirectory = (parent: ReferenceRepositoryTreeNode, nodeName: string, relativePath: string): ReferenceRepositoryTreeNode =>` (L393-407)
+### fn `function buildReqResetWorktreeNamePattern(gitRoot: string, config: UseReqConfig): RegExp` (L93-100)
+- @brief Builds the generated-worktree name matcher used by `req-reset` cleanup.
+- @details Reuses the configured worktree prefix plus repository basename, accepts any sanitized branch token between those fixed segments and the final execution identifier, and constrains the timestamp suffix to the documented `YYYYMMDDHHMMSS` shape. Runtime is O(p) in combined prefix and project-name length. No external state is mutated.
+- @param[in] gitRoot {string} Absolute runtime git root.
+- @param[in] config {UseReqConfig} Effective project configuration.
+- @return {RegExp} Matcher for generated prompt-command worktree and branch names.
+- @satisfies REQ-309, REQ-310, REQ-311
 
-### fn `const finalizeNode = (node: ReferenceRepositoryTreeNode): ReferenceRepositoryTreeNode =>` (L429-440)
+### fn `function listReqResetRegisteredWorktreeRoots(gitRoot: string): string[]` (L109-118)
+- @brief Lists every registered git worktree root for one repository.
+- @details Executes `git worktree list --porcelain`, extracts each `worktree <path>` record, resolves every listed path to an absolute form, and returns the ordered list used by generated-worktree cleanup. Runtime is dominated by one git subprocess plus O(n) parsing in listed worktree count. Side effects include subprocess creation.
+- @param[in] gitRoot {string} Absolute runtime git root.
+- @return {string[]} Absolute registered worktree-root paths.
+- @throws {ReqError} Throws when git worktree enumeration fails.
+
+### fn `function listReqResetSiblingWorktreeRoots(` (L128-146)
+- @brief Lists sibling directories whose names match the generated-worktree contract.
+- @details Reads the repository parent directory, keeps only direct child directories whose basenames match the supplied generated-name pattern, and resolves each candidate to an absolute path so `req-reset` can remove unregistered leftover directories as well as registered git worktrees. Runtime is dominated by directory enumeration plus O(n) matcher cost. Side effects are limited to filesystem reads.
+- @param[in] parentPath {string} Absolute directory containing sibling worktree roots.
+- @param[in] worktreeNamePattern {RegExp} Generated-worktree name matcher.
+- @return {string[]} Absolute sibling directory paths whose basenames match the generated-name contract.
+- @throws {ReqError} Throws when directory enumeration fails.
+
+### fn `function listReqResetMatchingWorktreeRoots(` (L157-172)
+- @brief Lists every generated sibling worktree candidate targeted by `req-reset`.
+- @details Unions registered git-worktree roots with matching sibling directories so cleanup covers both registered worktrees and unregistered leftover directories, then sorts the canonical absolute paths for deterministic deletion order. Runtime is dominated by git worktree enumeration plus sibling-directory scanning. Side effects are limited to subprocess creation and filesystem reads.
+- @param[in] parentPath {string} Absolute directory containing sibling worktree roots.
+- @param[in] gitRoot {string} Absolute runtime git root.
+- @param[in] worktreeNamePattern {RegExp} Generated-worktree name matcher.
+- @return {string[]} Sorted absolute worktree-root paths targeted for deletion.
+- @throws {ReqError} Throws when git worktree or sibling-directory enumeration fails.
 
-### fn `function analyzeReferenceFile(` (L456-621)
-- @brief Builds one analyzed file entry for the references payload.
-- @details Parses the file with `SourceAnalyzer`, extracts structured imports and symbols, attaches structured Doxygen fields, and preserves standalone comment evidence. Runtime is O(S log S) in file size and symbol count. Side effects are limited to filesystem reads and optional stderr logging.
-- @param[in] analyzer {SourceAnalyzer} Shared source analyzer instance.
-- @param[in] inputPath {string} Caller-provided input path.
-- @param[in] absolutePath {string} Absolute file path.
-- @param[in] requestIndex {number} Zero-based request index.
-- @param[in] baseDir {string} Base directory used for canonical paths.
-- @param[in] verbose {boolean} When `true`, emit per-file progress diagnostics to stderr.
-- @return {ReferenceToolFileEntry} Structured file entry.
-
-### fn `export function buildReferenceToolPayload(options: BuildReferenceToolPayloadOptions): ReferenceToolPayload` (L630-730)
-- @brief Builds the full agent-oriented references payload.
-- @details Validates requested paths against the filesystem, analyzes processable files in caller order, preserves skipped and failed inputs in structured file entries, computes aggregate numeric totals, and emits structured repository data without echoing request metadata already known to the caller. Runtime is O(F log F + S). Side effects are limited to filesystem reads and optional stderr logging.
-- @param[in] options {BuildReferenceToolPayloadOptions} Payload-construction options.
-- @return {ReferenceToolPayload} Structured references payload ordered as summary, repository, and files.
-- @satisfies REQ-011, REQ-014, REQ-076, REQ-077, REQ-078, REQ-079
-
-### fn `export function buildReferenceToolExecutionStderr(payload: ReferenceToolPayload): string` (L738-752)
-- @brief Builds deterministic stderr diagnostics from a references payload.
-- @details Serializes skipped-input and analysis-error entries into stable newline-delimited diagnostics while leaving fully analyzed payloads silent. Runtime is O(n) in file-entry count. No side effects occur.
-- @param[in] payload {ReferenceToolPayload} Structured references payload.
-- @return {string} Newline-delimited diagnostics.
+### fn `function listReqResetMatchingBranchNames(` (L182-195)
+- @brief Lists every matching generated branch targeted by `req-reset`.
+- @details Executes `git branch --list --format=%(refname:short)`, filters the local branch inventory through the generated-name matcher, and returns a sorted list so later forced branch deletion remains deterministic. Runtime is dominated by one git subprocess plus O(n) parsing in listed branch count. Side effects include subprocess creation.
+- @param[in] gitRoot {string} Absolute runtime git root.
+- @param[in] worktreeNamePattern {RegExp} Generated-worktree name matcher.
+- @return {string[]} Sorted local branch names targeted for deletion.
+- @throws {ReqError} Throws when local branch enumeration fails.
+
+### fn `export function prepareReqResetCommandExecution(` (L207-230)
+- @brief Prepares the specialized `req-reset` execution plan.
+- @details Resolves the active project base into a runtime git root, derives the sibling-worktree parent directory and generated-name matcher from the same prefix plus repository-basename contract used by prompt-command worktree generation, and keeps only worktree-backed persisted prompt execution plans for transcript-preserving base-path restoration. Runtime is O(p) in path length. No external state is mutated.
+- @param[in] projectBase {string} Absolute project base path.
+- @param[in] config {UseReqConfig} Effective project configuration.
+- @param[in] promptRequest {PromptCommandExecutionPlan | undefined} Pending or active prompt execution plan when available.
+- @return {ReqResetCommandPlan} Prepared recovery and cleanup plan.
+- @throws {ReqError} Throws when the repository root cannot be resolved.
+- @satisfies REQ-306, REQ-309, REQ-310, REQ-311
+
+### fn `export async function executeReqResetCommandExecution(` (L240-323)
+- @brief Executes the specialized `req-reset` recovery and cleanup workflow.
+- @details Preserves the execution-session transcript into the original session file when a worktree-backed prompt execution plan is still available, restores the original session-backed `base-path` through the shared prompt-command restoration helper, force-removes every matching sibling worktree directory, force-removes every remaining matching local branch, and aggregates any failure diagnostics without rolling back successful cleanup steps. Runtime is dominated by session switching plus git subprocess execution. Side effects include session-file reads and writes, active-session replacement, host-process cwd mutation, worktree deletion, branch deletion, and filesystem reads.
+- @param[in] plan {ReqResetCommandPlan} Prepared recovery and cleanup plan.
+- @param[in] ctx {ReqResetCommandContext | undefined} Optional session-bound command context.
+- @return {Promise<ReqResetCommandExecutionResult>} Recovery and cleanup outcome facts.
+- @satisfies REQ-305, REQ-307, REQ-308, REQ-309, REQ-310, REQ-313
 
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
 |---|---|---|---|---|
-|`ReferenceToolScope`|type||27||
-|`ReferenceFileStatus`|type||33||
-|`ReferenceLineRange`|iface||39-43|export interface ReferenceLineRange|
-|`ReferenceImportEntry`|iface||49-52|export interface ReferenceImportEntry extends ReferenceLi...|
-|`ReferenceCommentEntry`|iface||58-61|export interface ReferenceCommentEntry extends ReferenceL...|
-|`ReferenceExitPointEntry`|iface||67-70|export interface ReferenceExitPointEntry|
-|`ReferenceSymbolEntry`|iface||76-96|export interface ReferenceSymbolEntry extends ReferenceLi...|
-|`ReferenceToolFileEntry`|iface||102-115|export interface ReferenceToolFileEntry extends Reference...|
-|`ReferenceToolRequestSection`|iface||121-130|export interface ReferenceToolRequestSection|
-|`ReferenceToolSummarySection`|iface||136-147|export interface ReferenceToolSummarySection|
-|`ReferenceRepositoryTreeNode`|iface||153-159|export interface ReferenceRepositoryTreeNode|
-|`ReferenceToolRepositorySection`|iface||165-169|export interface ReferenceToolRepositorySection|
-|`ReferenceToolPayload`|iface||175-179|export interface ReferenceToolPayload|
-|`BuildReferenceToolPayloadOptions`|iface||185-192|export interface BuildReferenceToolPayloadOptions|
-|`canonicalizeReferencePath`|fn||201-209|function canonicalizeReferencePath(targetPath: string, ba...|
-|`buildLineRange`|fn||218-224|function buildLineRange(startLineNumber: number, endLineN...|
-|`extractCommentText`|fn||233-253|function extractCommentText(commentElement: SourceElement...|
-|`extractCommentLines`|fn||261-275|function extractCommentLines(commentElement: SourceElemen...|
-|`buildCommentMaps`|fn||283-333|function buildCommentMaps(elements: SourceElement[]): [Re...|
-|`resolveSymbolName`|fn||341-343|function resolveSymbolName(element: SourceElement): string|
-|`resolveParentElement`|fn||352-361|function resolveParentElement(definitions: SourceElement[...|
-|`buildCommentEntry`|fn||369-376|function buildCommentEntry(commentElement: SourceElement)...|
-|`buildRepositoryTree`|fn||384-443|function buildRepositoryTree(canonicalPaths: string[]): R...|
-|`ensureDirectory`|fn||393-407|const ensureDirectory = (parent: ReferenceRepositoryTreeN...|
-|`finalizeNode`|fn||429-440|const finalizeNode = (node: ReferenceRepositoryTreeNode):...|
-|`analyzeReferenceFile`|fn||456-621|function analyzeReferenceFile(|
-|`buildReferenceToolPayload`|fn||630-730|export function buildReferenceToolPayload(options: BuildR...|
-|`buildReferenceToolExecutionStderr`|fn||738-752|export function buildReferenceToolExecutionStderr(payload...|
+|`ReqResetCommandPlan`|iface||34-40|export interface ReqResetCommandPlan|
+|`ReqResetCommandExecutionResult`|iface||46-53|export interface ReqResetCommandExecutionResult|
+|`ReqResetCommandContext`|type||59||
+|`runCapture`|fn||68-73|function runCapture(command: string[], cwd: string): Retu...|
+|`escapeReqResetRegExpLiteral`|fn||81-83|function escapeReqResetRegExpLiteral(text: string): string|
+|`buildReqResetWorktreeNamePattern`|fn||93-100|function buildReqResetWorktreeNamePattern(gitRoot: string...|
+|`listReqResetRegisteredWorktreeRoots`|fn||109-118|function listReqResetRegisteredWorktreeRoots(gitRoot: str...|
+|`listReqResetSiblingWorktreeRoots`|fn||128-146|function listReqResetSiblingWorktreeRoots(|
+|`listReqResetMatchingWorktreeRoots`|fn||157-172|function listReqResetMatchingWorktreeRoots(|
+|`listReqResetMatchingBranchNames`|fn||182-195|function listReqResetMatchingBranchNames(|
+|`prepareReqResetCommandExecution`|fn||207-230|export function prepareReqResetCommandExecution(|
+|`executeReqResetCommandExecution`|fn||240-323|export async function executeReqResetCommandExecution(|
 
 
 ---
 
-# resources.ts | TypeScript | 119L | 7 symbols | 3 imports | 8 comments
+# resources.ts | TypeScript | 102L | 7 symbols | 3 imports | 8 comments
 > Path: `src/core/resources.ts`
 - @brief Resolves installation-owned bundled resource locations.
 - @details Encapsulates installation-path discovery, bundled-resource validation, prompt enumeration, prompt loading, and bundled instruction loading directly from the installed extension payload. Runtime is proportional to directory-entry enumeration and resource file size. Side effects are limited to filesystem reads.
@@ -3437,20 +3649,20 @@ import { getInstallationPath, RESOURCE_ROOT_DIRNAME } from "./path-context.js";
 - @return {string} Raw prompt markdown content.
 - @throws {Error} Propagates `fs.readFileSync` errors when the prompt file is missing or unreadable.
 
-### fn `export function readBundledPromptDescription(promptName: string): string` (L73-95)
-- @brief Extracts the YAML-front-matter `description` field from one bundled prompt.
-- @details Parses only the leading front-matter block, resolves the first scalar `description` entry, strips one matching pair of wrapping quotes, and unescapes quoted apostrophe or quote characters used in prompt metadata. Runtime is O(n) in prompt length. Side effects are limited to filesystem reads delegated through `readBundledPrompt(...)`.
+### fn `export function readBundledPromptDescription(promptName: string): string` (L73-78)
+- @brief Extracts the first Markdown level-one heading from one bundled prompt.
+- @details Removes one optional leading YAML front-matter block, scans the remaining markdown body for the first line that begins with `# `, and returns the heading payload without the marker or surrounding whitespace. Runtime is O(n) in prompt length. Side effects are limited to filesystem reads delegated through `readBundledPrompt(...)`.
 - @param[in] promptName {string} Prompt identifier without the `.md` suffix.
-- @return {string} Normalized prompt description or the empty string when the front matter does not declare one.
+- @return {string} First `# ` heading payload, or the empty string when no level-one heading exists.
 
-### fn `export function readBundledInstruction(instructionName: string): string` (L104-106)
+### fn `export function readBundledInstruction(instructionName: string): string` (L87-89)
 - @brief Reads one bundled markdown instruction by logical instruction name.
 - @details Resolves the instruction file under the installation-owned `resources/instructions` directory, validates resource accessibility, and loads it as UTF-8 text. Time complexity is O(n) in file size. Side effects are limited to filesystem reads.
 - @param[in] instructionName {string} Instruction identifier without the `.md` suffix.
 - @return {string} Raw instruction markdown content.
 - @throws {Error} Propagates `fs.readFileSync` errors when the instruction file is missing or unreadable.
 
-### fn `export function listBundledPromptNames(): string[]` (L113-119)
+### fn `export function listBundledPromptNames(): string[]` (L96-102)
 - @brief Lists bundled prompt identifiers available in the installed extension payload.
 - @details Scans the installation-owned prompt directory, keeps visible markdown files only, strips the `.md` suffix, and returns a lexicographically sorted list. Time complexity is O(n log n). Side effects are limited to filesystem reads.
 - @return {string[]} Sorted prompt names without file extensions.
@@ -3462,9 +3674,9 @@ import { getInstallationPath, RESOURCE_ROOT_DIRNAME } from "./path-context.js";
 |`ensureBundledResourcesAccessible`|fn||26-38|export function ensureBundledResourcesAccessible(): string|
 |`readBundledMarkdownResource`|fn||48-54|function readBundledMarkdownResource(|
 |`readBundledPrompt`|fn||63-65|export function readBundledPrompt(promptName: string): st...|
-|`readBundledPromptDescription`|fn||73-95|export function readBundledPromptDescription(promptName: ...|
-|`readBundledInstruction`|fn||104-106|export function readBundledInstruction(instructionName: s...|
-|`listBundledPromptNames`|fn||113-119|export function listBundledPromptNames(): string[]|
+|`readBundledPromptDescription`|fn||73-78|export function readBundledPromptDescription(promptName: ...|
+|`readBundledInstruction`|fn||87-89|export function readBundledInstruction(instructionName: s...|
+|`listBundledPromptNames`|fn||96-102|export function listBundledPromptNames(): string[]|
 
 
 ---
@@ -3532,7 +3744,7 @@ import { isSameOrAncestorPath } from "./path-context.js";
 
 ---
 
-# settings-menu.ts | TypeScript | 264L | 12 symbols | 2 imports | 13 comments
+# settings-menu.ts | TypeScript | 321L | 15 symbols | 2 imports | 15 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.
@@ -3545,37 +3757,35 @@ import { Container, SettingsList, Text, type Component, type SettingItem, type S
 
 ## Definitions
 
-### iface `export interface PiUsereqSettingsMenuChoice` (L14-22)
+### iface `export interface PiUsereqSettingsMenuChoice` (L14-23)
 - @brief Describes one selectable pi-usereq settings-menu choice.
-- @details Stores the stable action identifier, left-column label, optional label and value tone overrides, optional disabled state, 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, optional label and value tone overrides, optional disabled state, right-column current value, optional inline-cycle values, 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` (L28-34)
+### iface `export interface PiUsereqSettingsMenuBridge` (L29-35)
 - @brief Describes the offline bridge exposed by shared settings-menu components.
 - @details Lets deterministic harnesses and unit tests drive the same settings-menu choices by label without simulating raw terminal key streams. The interface is runtime-facing but carries no side effects by itself.
 
-### iface `export interface PiUsereqSettingsMenuOptions` (L42-44)
+### iface `export interface PiUsereqSettingsMenuOptions` (L41-45)
 - @brief Describes optional behavior overrides for one settings-menu render.
-- @details Carries the caller-selected initial focus row so menu re-renders can
-preserve selection after an in-place toggle or value edit. The interface is
-compile-time only and introduces no runtime cost.
+- @details Carries the caller-selected initial focus row, the optional dynamic choice supplier used to rebuild dependent rows after inline toggles, and the optional inline-change callback used to persist `SettingsList` value cycles without closing the menu. The interface is compile-time only and introduces no runtime cost.
 
-### iface `export interface PiUsereqSettingsMenuComponent extends Component` : Component (L50-52)
+### iface `export interface PiUsereqSettingsMenuComponent extends Component` : Component (L51-53)
 - @brief Represents a custom menu component augmented with the offline bridge.
 - @details Extends the generic TUI `Component` contract with one optional bridge field consumed only by deterministic test and debug harness adapters. The interface is compile-time only and introduces no runtime cost.
 
-- type `type PiUsereqSettingsThemeColor = Extract<ThemeColor, "accent" | "muted" | "dim">;` (L60)
+- type `type PiUsereqSettingsThemeColor = Extract<ThemeColor, "accent" | "muted" | "dim">;` (L61)
 - @brief Enumerates the CLI-supported theme tokens consumed by settings menus.
 - @details Narrows callback-local theme calls to the documented settings-list
 semantics used by the pi CLI. Compile-time only and introduces no runtime
 cost.
-### iface `interface PiUsereqSettingsTheme` (L69-72)
+### iface `interface PiUsereqSettingsTheme` (L70-73)
 - @brief Describes the callback-local theme surface required by settings menus.
 - @details Captures the subset of the custom-UI theme API needed to rebuild
 title and fallback settings-list styling when the shared global theme is not
 available in tests or offline replay. Compile-time only and introduces no
 runtime cost.
 
-### fn `function buildFallbackPiUsereqSettingsListTheme(` (L84-96)
+### fn `function buildFallbackPiUsereqSettingsListTheme(` (L85-97)
 - @brief Builds the fallback settings-list theme matching CLI settings semantics.
 - @details Mirrors the shared CLI settings theme token mapping for labels,
 values, descriptions, cursor, and hints while avoiding the global theme
@@ -3585,7 +3795,7 @@ mutated.
 - @return {SettingsListTheme} Fallback settings-list theme.
 - @satisfies REQ-151, REQ-156
 
-### fn `function buildPiUsereqSettingsListTheme(` (L109-123)
+### fn `function buildPiUsereqSettingsListTheme(` (L110-124)
 - @brief Resolves the settings-list theme used by pi-usereq configuration menus.
 - @details Prefers the shared CLI `getSettingsListTheme()` API so extension
 menus inherit active-theme behavior from pi itself, then falls back to an
@@ -3596,7 +3806,7 @@ external state is mutated.
 - @return {SettingsListTheme} Settings-list theme used by pi-usereq menus.
 - @satisfies REQ-151, REQ-156
 
-### fn `function formatPiUsereqSettingsMenuTitle(` (L135-140)
+### fn `function formatPiUsereqSettingsMenuTitle(` (L136-141)
 - @brief Formats the settings-menu title with active-theme semantics.
 - @details Applies the callback-local `accent` token and bold styling on every
 rebuild so custom-menu titles stay synchronized with live theme changes.
@@ -3606,46 +3816,64 @@ Runtime is O(n) in title length. No external state is mutated.
 - @return {string} Styled title text.
 - @satisfies REQ-151, REQ-156
 
-### fn `function createImmediateSelectionComponent(choiceId: string, done: (value?: string) => void): Component` (L149-161)
+### fn `function createImmediateSelectionComponent(choiceId: string, done: (value?: string) => void): Component` (L150-162)
 - @brief Closes a settings menu immediately with one selected action identifier.
 - @details Provides the submenu callback used by `SettingsList` so pressing Enter on any menu row resolves the outer custom UI promise with the row identifier. Runtime is O(1). Side effects are limited to one custom-UI completion callback.
 - @param[in] choiceId {string} Stable choice identifier to emit.
 - @param[in] done {(value?: string) => void} Outer custom-UI completion callback.
 - @return {Component} Immediate-completion submenu component.
 
-### fn `function buildSettingItems(` (L171-189)
+### fn `function buildSettingItems(` (L172-193)
 - @brief Builds `SettingsList` items from one menu-choice vector.
-- @details Copies labels, current values, label-tone overrides, value-tone overrides, disabled-state semantics, and descriptions into `SettingItem` records and attaches a submenu that resolves the outer custom UI with the selected choice identifier only for enabled rows. Runtime is O(n) in choice count. No external state is mutated.
+- @details Copies labels, current values, label-tone overrides, value-tone overrides, disabled-state semantics, inline-cycle values, and descriptions into `SettingItem` records. Non-disabled rows with `values` cycle inline on `Enter` or `Space`, while other non-disabled rows resolve the outer custom UI through the immediate submenu bridge. 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.
 
-### fn `export async function showPiUsereqSettingsMenu(` (L201-205)
+### fn `function setSettingsListSelectedIndex(` (L202-207)
+- @brief Writes one best-effort selected row index into a `SettingsList` instance.
+- @details Uses reflective access so pi-usereq can preserve focus across menu re-renders without depending on the private field at compile time. Runtime is O(1). Side effect: mutates the underlying `SettingsList` selection state when the field exists.
+- @param[in] selectedIndex {number} Zero-based row index to restore.
+- @param[in,out] settingsList {SettingsList} Mutable settings-list instance.
+- @return {void} No return value.
+
+### fn `function getSettingsListSelectedIndex(` (L215-220)
+- @brief Reads the current selected row index from a `SettingsList` instance.
+- @details Uses reflective access so pi-usereq can report the current focused row through the offline bridge without referencing the private field in the static type system. Runtime is O(1). No external state is mutated.
+- @param[in] settingsList {SettingsList} Settings-list instance.
+- @return {number | undefined} Zero-based selected row index when available.
+
+### fn `export async function showPiUsereqSettingsMenu(` (L232-236)
 - @brief Renders one shared pi-usereq settings menu and resolves the selected action.
-- @details Uses `ctx.ui.custom(...)` plus `SettingsList` so every configuration menu shares pi.dev styling, right-aligned current values, circular scrolling, bottom-line descriptions, and optional disabled rows. The returned custom component also exposes an offline bridge for deterministic tests and debug harnesses. Runtime is O(n) in visible choice count plus user interaction cost. Side effects are limited to transient custom-UI rendering.
+- @details Uses `ctx.ui.custom(...)` plus `SettingsList` so every configuration menu shares pi.dev styling, right-aligned current values, circular scrolling, bottom-line descriptions, optional disabled rows, and inline toggle cycles that do not close the menu. When callers provide `getChoices(...)`, dependent rows are rebuilt after inline changes while preserving focus on the changed row. The returned custom component also exposes an offline bridge for deterministic tests and debug harnesses. Runtime is O(n) in visible choice count plus user interaction cost. Side effects are limited to transient custom-UI rendering and caller-owned inline-change callbacks.
 - @param[in] ctx {ExtensionCommandContext} Active command context.
 - @param[in] title {string} Menu title displayed in the heading and offline bridge.
 - @param[in] choices {PiUsereqSettingsMenuChoice[]} Ordered menu-choice vector.
-- @param[in] options {PiUsereqSettingsMenuOptions | undefined} Optional initial-focus override.
+- @param[in] options {PiUsereqSettingsMenuOptions | undefined} Optional initial-focus override plus inline-change behavior.
 - @return {Promise<string | undefined>} Selected choice identifier or `undefined` when cancelled.
 - @satisfies REQ-151, REQ-152, REQ-153, REQ-154, REQ-156, REQ-192
 
+### fn `const rebuildMenu = (selectedChoiceId?: string): void =>` (L272-279)
+
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
 |---|---|---|---|---|
-|`PiUsereqSettingsMenuChoice`|iface||14-22|export interface PiUsereqSettingsMenuChoice|
-|`PiUsereqSettingsMenuBridge`|iface||28-34|export interface PiUsereqSettingsMenuBridge|
-|`PiUsereqSettingsMenuOptions`|iface||42-44|export interface PiUsereqSettingsMenuOptions|
-|`PiUsereqSettingsMenuComponent`|iface||50-52|export interface PiUsereqSettingsMenuComponent extends Co...|
-|`PiUsereqSettingsThemeColor`|type||60||
-|`PiUsereqSettingsTheme`|iface||69-72|interface PiUsereqSettingsTheme|
-|`buildFallbackPiUsereqSettingsListTheme`|fn||84-96|function buildFallbackPiUsereqSettingsListTheme(|
-|`buildPiUsereqSettingsListTheme`|fn||109-123|function buildPiUsereqSettingsListTheme(|
-|`formatPiUsereqSettingsMenuTitle`|fn||135-140|function formatPiUsereqSettingsMenuTitle(|
-|`createImmediateSelectionComponent`|fn||149-161|function createImmediateSelectionComponent(choiceId: stri...|
-|`buildSettingItems`|fn||171-189|function buildSettingItems(|
-|`showPiUsereqSettingsMenu`|fn||201-205|export async function showPiUsereqSettingsMenu(|
+|`PiUsereqSettingsMenuChoice`|iface||14-23|export interface PiUsereqSettingsMenuChoice|
+|`PiUsereqSettingsMenuBridge`|iface||29-35|export interface PiUsereqSettingsMenuBridge|
+|`PiUsereqSettingsMenuOptions`|iface||41-45|export interface PiUsereqSettingsMenuOptions|
+|`PiUsereqSettingsMenuComponent`|iface||51-53|export interface PiUsereqSettingsMenuComponent extends Co...|
+|`PiUsereqSettingsThemeColor`|type||61||
+|`PiUsereqSettingsTheme`|iface||70-73|interface PiUsereqSettingsTheme|
+|`buildFallbackPiUsereqSettingsListTheme`|fn||85-97|function buildFallbackPiUsereqSettingsListTheme(|
+|`buildPiUsereqSettingsListTheme`|fn||110-124|function buildPiUsereqSettingsListTheme(|
+|`formatPiUsereqSettingsMenuTitle`|fn||136-141|function formatPiUsereqSettingsMenuTitle(|
+|`createImmediateSelectionComponent`|fn||150-162|function createImmediateSelectionComponent(choiceId: stri...|
+|`buildSettingItems`|fn||172-193|function buildSettingItems(|
+|`setSettingsListSelectedIndex`|fn||202-207|function setSettingsListSelectedIndex(|
+|`getSettingsListSelectedIndex`|fn||215-220|function getSettingsListSelectedIndex(|
+|`showPiUsereqSettingsMenu`|fn||232-236|export async function showPiUsereqSettingsMenu(|
+|`rebuildMenu`|fn||272-279|const rebuildMenu = (selectedChoiceId?: string): void =>|
 
 
 ---
@@ -4155,7 +4383,7 @@ import { ReqError } from "./errors.js";
 
 ---
 
-# tool-runner.ts | TypeScript | 438L | 21 symbols | 11 imports | 23 comments
+# tool-runner.ts | TypeScript | 458L | 22 symbols | 11 imports | 24 comments
 > Path: `src/core/tool-runner.ts`
 - @brief Implements the executable back-end for pi-usereq CLI analysis and static-check commands.
 - @details Centralizes project discovery, git-backed source-file collection, documentation token generation, compression, construct lookup, and static-check dispatch. Runtime depends on the selected command and may include filesystem reads, config writes, and process spawning.
@@ -4257,9 +4485,9 @@ import { makeRelativeIfContainsProject } from "./utils.js";
 - @return {ToolResult} Tool result containing the formatted summary and warnings.
 - @throws {ReqError} Throws when no valid files are provided.
 
-### fn `export function runFilesReferences(files: string[], cwd = process.cwd(), verbose = false): ToolResult` (L250-256)
-- @brief Generates the monolithic references markdown for explicit files.
-- @details Delegates to `generateMarkdown(...)`, keeps output paths relative to the caller cwd, and returns the Python-compatible markdown document through stdout. Runtime is O(F + S). Side effects are limited to filesystem reads and optional stderr logging.
+### fn `export function runFilesSummarize(files: string[], cwd = process.cwd(), verbose = false): ToolResult` (L250-256)
+- @brief Generates the monolithic summary markdown for explicit files.
+- @details Delegates to `generateMarkdown(...)`, keeps output paths relative to the caller cwd, and returns the Python-compatible summary markdown document through stdout. Runtime is O(F + S). Side effects are limited to filesystem reads and optional stderr logging.
 - @param[in] files {string[]} Explicit file paths.
 - @param[in] cwd {string} Base directory used for relative output paths. Defaults to `process.cwd()`.
 - @param[in] verbose {boolean} When `true`, emit per-file progress diagnostics to stderr.
@@ -4284,9 +4512,9 @@ import { makeRelativeIfContainsProject } from "./utils.js";
 - @return {ToolResult} Successful tool result containing construct markdown.
 - @throws {ReqError} Throws when required arguments are missing.
 
-### fn `export function runReferences(projectBase: string, config?: UseReqConfig, verbose = false): ToolResult` (L298-309)
-- @brief Generates the monolithic references markdown for configured source directories.
-- @details Resolves the project base, collects configured source files, prepends the repository file-structure markdown block, and returns the Python-compatible references document through stdout. Runtime is O(F log F + S). Side effects are limited to filesystem reads and optional stderr logging.
+### fn `export function runSummarize(projectBase: string, config?: UseReqConfig, verbose = false): ToolResult` (L298-309)
+- @brief Generates the monolithic summary markdown for configured source directories.
+- @details Resolves the project base, collects configured source files, prepends the repository file-structure markdown block, and returns the Python-compatible summary document through stdout. Runtime is O(F log F + S). Side effects are limited to filesystem reads and optional stderr logging.
 - @param[in] projectBase {string} Candidate project root.
 - @param[in] config {UseReqConfig | undefined} Optional preloaded configuration.
 - @param[in] verbose {boolean} When `true`, emit per-file diagnostics to stderr.
@@ -4294,7 +4522,17 @@ import { makeRelativeIfContainsProject } from "./utils.js";
 - @throws {ReqError} Throws when no source files are found or no file can be analyzed.
 - @satisfies REQ-014, REQ-076, REQ-077, REQ-078, REQ-079
 
-### fn `export function runCompress(projectBase: string, config?: UseReqConfig, enableLineNumbers = false, verbose = false): ToolResult` (L321-326)
+### fn `export function runReferences(projectBase: string, config?: UseReqConfig, verbose = false): ToolResult` (L321-329)
+- @brief Writes configured project references markdown to the canonical docs file.
+- @details Reuses `runSummarize(...)` to generate the same file-structure-plus-summary markdown, resolves `<docs-dir>/REFERENCES.md` from the effective project configuration, overwrites the target file, and returns the status-only stdout `success`. Runtime is O(F log F + S) plus one file write. Side effects include filesystem writes.
+- @param[in] projectBase {string} Candidate project root.
+- @param[in] config {UseReqConfig | undefined} Optional preloaded configuration.
+- @param[in] verbose {boolean} When `true`, emit per-file diagnostics to stderr during summary generation.
+- @return {ToolResult} Successful tool result containing the status-only stdout payload.
+- @throws {ReqError} Throws when source discovery, summary generation, or file writing fails.
+- @satisfies REQ-293
+
+### fn `export function runCompress(projectBase: string, config?: UseReqConfig, enableLineNumbers = false, verbose = false): ToolResult` (L341-346)
 - @brief Compresses all source files from configured source directories.
 - @details Resolves the project base, collects source files, and delegates to `compressFiles`. Runtime is O(F + S). Side effects are limited to filesystem reads and optional stderr logging.
 - @param[in] projectBase {string} Candidate project root.
@@ -4304,7 +4542,7 @@ import { makeRelativeIfContainsProject } from "./utils.js";
 - @return {ToolResult} Successful tool result containing compressed output.
 - @throws {ReqError} Throws when no source files are found.
 
-### fn `export function runSearch(projectBase: string, tagFilter: string, pattern: string, config?: UseReqConfig, enableLineNumbers = false, verbose = false): ToolResult` (L340-349)
+### fn `export function runSearch(projectBase: string, tagFilter: string, pattern: string, config?: UseReqConfig, enableLineNumbers = false, verbose = false): ToolResult` (L360-369)
 - @brief Searches named constructs across configured project source files.
 - @details Resolves the project base, collects source files, delegates to `searchConstructsInFiles`, and converts thrown search errors into structured `ReqError` failures. Runtime is O(F + S + M). Side effects are limited to filesystem reads and optional stderr logging.
 - @param[in] projectBase {string} Candidate project root.
@@ -4316,7 +4554,7 @@ import { makeRelativeIfContainsProject } from "./utils.js";
 - @return {ToolResult} Successful tool result containing construct markdown.
 - @throws {ReqError} Throws when no source files are found or the search fails.
 
-### fn `export function runTokens(projectBase: string, config?: UseReqConfig): ToolResult` (L359-368)
+### fn `export function runTokens(projectBase: string, config?: UseReqConfig): ToolResult` (L379-388)
 - @brief Counts tokens for canonical documentation files.
 - @details Loads the configured docs directory, selects `REQUIREMENTS.md`, `WORKFLOW.md`, and `REFERENCES.md` when present, and delegates to `runFilesTokens`. Runtime is O(F + S). Side effects are limited to filesystem reads.
 - @param[in] projectBase {string} Candidate project root.
@@ -4324,7 +4562,7 @@ import { makeRelativeIfContainsProject } from "./utils.js";
 - @return {ToolResult} Tool result containing documentation token metrics.
 - @throws {ReqError} Throws when no canonical docs files exist.
 
-### fn `export function runFilesStaticCheck(files: string[], projectBase: string, config?: UseReqConfig): ToolResult` (L378-414)
+### fn `export function runFilesStaticCheck(files: string[], projectBase: string, config?: UseReqConfig): ToolResult` (L398-434)
 - @brief Runs configured static checks for explicit files.
 - @details Loads the effective static-check config, resolves the active checker list per file-extension language through the per-language enable flag, captures checker stdout for each dispatched entry, and aggregates stderr warnings for invalid paths. Runtime is O(F * C) plus external checker cost. Side effects include filesystem reads, stdout interception, and process spawning.
 - @param[in] files {string[]} Explicit file paths.
@@ -4332,7 +4570,7 @@ import { makeRelativeIfContainsProject } from "./utils.js";
 - @param[in] config {UseReqConfig | undefined} Optional preloaded configuration.
 - @return {ToolResult} Aggregated static-check result.
 
-### fn `export function runProjectStaticCheck(projectBase: string, config?: UseReqConfig): ToolResult` (L424-437)
+### fn `export function runProjectStaticCheck(projectBase: string, config?: UseReqConfig): ToolResult` (L444-457)
 - @brief Runs configured static checks for project source and test directories.
 - @details Collects source and test files, excludes fixture roots, and delegates to `runFilesStaticCheck`. Runtime is O(F * C) plus external checker cost. Side effects include filesystem reads, stdout interception, and process spawning.
 - @param[in] projectBase {string} Candidate project root.
@@ -4355,15 +4593,16 @@ import { makeRelativeIfContainsProject } from "./utils.js";
 |`resolveProjectSrcDirs`|fn||196-204|export function resolveProjectSrcDirs(projectBase: string...|
 |`loadAndRepairConfig`|fn||213-218|export function loadAndRepairConfig(projectBase: string):...|
 |`runFilesTokens`|fn||227-239|export function runFilesTokens(files: string[]): ToolResult|
-|`runFilesReferences`|fn||250-256|export function runFilesReferences(files: string[], cwd =...|
+|`runFilesSummarize`|fn||250-256|export function runFilesSummarize(files: string[], cwd = ...|
 |`runFilesCompress`|fn||267-269|export function runFilesCompress(files: string[], cwd = p...|
 |`runFilesSearch`|fn||280-286|export function runFilesSearch(argsList: string[], enable...|
-|`runReferences`|fn||298-309|export function runReferences(projectBase: string, config...|
-|`runCompress`|fn||321-326|export function runCompress(projectBase: string, config?:...|
-|`runSearch`|fn||340-349|export function runSearch(projectBase: string, tagFilter:...|
-|`runTokens`|fn||359-368|export function runTokens(projectBase: string, config?: U...|
-|`runFilesStaticCheck`|fn||378-414|export function runFilesStaticCheck(files: string[], proj...|
-|`runProjectStaticCheck`|fn||424-437|export function runProjectStaticCheck(projectBase: string...|
+|`runSummarize`|fn||298-309|export function runSummarize(projectBase: string, config?...|
+|`runReferences`|fn||321-329|export function runReferences(projectBase: string, config...|
+|`runCompress`|fn||341-346|export function runCompress(projectBase: string, config?:...|
+|`runSearch`|fn||360-369|export function runSearch(projectBase: string, tagFilter:...|
+|`runTokens`|fn||379-388|export function runTokens(projectBase: string, config?: U...|
+|`runFilesStaticCheck`|fn||398-434|export function runFilesStaticCheck(files: string[], proj...|
+|`runProjectStaticCheck`|fn||444-457|export function runProjectStaticCheck(projectBase: string...|
 
 
 ---
@@ -4450,7 +4689,7 @@ import path from "node:path";
 
 ---
 
-# index.ts | TypeScript | 3765L | 87 symbols | 25 imports | 93 comments
+# index.ts | TypeScript | 4250L | 96 symbols | 27 imports | 102 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.
@@ -4472,6 +4711,8 @@ import {
 import { renderPrompt } from "./core/prompts.js";
 import {
 import {
+import {
+import {
 import { PROMPT_COMMAND_NAMES } from "./core/prompt-command-catalog.js";
 import { resolveRuntimeGitPath } from "./core/runtime-project-paths.js";
 import {
@@ -4486,78 +4727,84 @@ import { makeRelativeIfContainsProject, shellSplit } from "./core/utils.js";
 
 ## Definitions
 
-### iface `interface PiShortcutRegistrar` (L161-169)
+### iface `interface PiShortcutRegistrar` (L178-186)
 - @brief Describes the optional shortcut-registration surface used by pi-usereq.
 - @details Narrows the runtime API to the documented `registerShortcut(...)`
 method so the extension can remain compatible with offline harnesses that do
 not implement shortcut capture. Compile-time only and introduces no runtime
 cost.
 
-### fn `function getProjectBase(cwd: string): string` (L177-186)
+### fn `function getProjectBase(cwd: string): string` (L194-203)
 - @brief Resolves the effective project base from a working directory.
 - @details Normalizes the provided cwd into an absolute path without consulting configuration. Time complexity is O(1). No I/O side effects occur.
 - @param[in] cwd {string} Current working directory.
 - @return {string} Absolute project base path.
 
-### fn `function getProcessCwdSafe(): string` (L193-202)
+### fn `function getProcessCwdSafe(): string` (L210-219)
 - @brief Resolves a safe process working directory for extension-load paths.
 - @details Returns `process.cwd()` when available and falls back to absolute `PWD`, `HOME`, or `/` when the current shell directory has been deleted. Runtime is O(1). No external state is mutated.
 - @return {string} Absolute fallback-safe process working directory.
 
-### fn `function resolveLiveBootstrapCwd(cwd: string): string` (L210-222)
+### fn `function resolveLiveBootstrapCwd(cwd: string): string` (L227-239)
 - @brief Resolves the live working directory used for bootstrap-sensitive flows.
 - @details Prefers the supplied cwd when it still exists. Otherwise reuses the tracked runtime context path when it remains live, then the tracked runtime base path, and finally a process-safe cwd so deleted worktree paths retained by stale contexts cannot poison later prompt preflight or lifecycle bootstrap. Runtime is O(1) plus bounded filesystem probes. No external state is mutated.
 - @param[in] cwd {string} Candidate context cwd.
 - @return {string} Existing absolute cwd used for bootstrap work.
 
-### fn `function syncContextCwdMirror(ctx: { cwd?: string }, cwd: string): void` (L231-240)
+### fn `function syncContextCwdMirror(ctx: { cwd?: string }, cwd: string): void` (L248-257)
 - @brief Best-effort synchronizes one context `cwd` mirror with bootstrap reality.
 - @details Applies the resolved live cwd to the supplied context when writable and ignores stale or read-only mirrors so command bootstrap can continue using authoritative filesystem probes. Runtime is O(1). Side effects are limited to optional `ctx.cwd` mutation.
 - @param[in] cwd {string} Resolved live cwd.
 - @param[in,out] ctx {{ cwd?: string }} Mutable context-like object.
 - @return {void} No return value.
 
-### fn `function loadProjectConfig(cwd: string): UseReqConfig` (L249-252)
+### fn `function loadProjectConfig(cwd: string): UseReqConfig` (L266-269)
 - @brief Loads project configuration for the extension runtime.
 - @details Resolves the project base, loads persisted config, and normalizes configured directory paths without reading or persisting runtime-derived `base-path` or `git-path` metadata. Runtime is dominated by config I/O. Side effects are limited to filesystem reads.
 - @param[in] cwd {string} Current working directory.
 - @return {UseReqConfig} Effective project configuration.
 - @satisfies REQ-030, REQ-145, REQ-146
 
-### fn `function saveProjectConfig(cwd: string, config: UseReqConfig): void` (L262-265)
-- @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.
+### fn `function saveProjectConfig(cwd: string, config: UseReqConfig): void` (L279-282)
+- @brief Persists effective project configuration from the extension runtime.
+- @details Resolves the project base, normalizes configured local directory paths into project-relative form, and delegates split local/global 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.
-- @param[in] config {UseReqConfig} Configuration to persist.
+- @param[in] config {UseReqConfig} Effective configuration to persist.
 - @return {void} No return value.
-- @satisfies REQ-146
+- @satisfies REQ-146, REQ-315
 
-### fn `function formatProjectConfigPathForMenu(cwd: string): string` (L274-278)
-- @brief Formats the current project config path for top-level menu display.
-- @details Resolves `<base-path>/.pi-usereq.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.
+### fn `function formatLocalConfigPathForMenu(cwd: string): string` (L291-295)
+- @brief Formats the current local config path for top-level menu display.
+- @details Resolves `<base-path>/.pi-usereq.json` from the cwd-derived project base and reuses the shared runtime-path formatter so the `Show local configuration` row uses the documented `~`-relative display contract. Runtime is O(p) in path length. No external state is mutated.
 - @param[in] cwd {string} Current working directory.
-- @return {string} `~`-relative or absolute config path display value.
+- @return {string} `~`-relative or absolute local config-path display value.
 - @satisfies REQ-162
 
-### fn `function buildTerminalSettingsMenuChoices(options:` (L287-298)
+### fn `function formatGlobalConfigPathForMenu(): string` (L303-305)
+- @brief Formats the current global config path for top-level menu display.
+- @details Resolves `~/.config/pi-usereq/config.json` through the shared runtime-path formatter so the `Show global configuration` row uses the documented `~`-relative display contract. Runtime is O(p) in path length. No external state is mutated.
+- @return {string} `~`-relative or absolute global config-path display value.
+- @satisfies REQ-319
+
+### fn `function buildTerminalSettingsMenuChoices(options:` (L314-325)
 - @brief Builds the standardized terminal rows appended to every configuration menu.
 - @details Returns the canonical value-less `Reset defaults` row so all configuration menus and descendant selector menus share the same terminal ordering contract without rendering `Save and close`. Runtime is O(1). No external state is mutated.
 - @param[in] options {{ resetDefaultsDescription: string }} Menu-specific terminal-row metadata.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered terminal menu rows.
 - @satisfies REQ-193
 
-### iface `interface ResetConfirmationChange` (L304-308)
+### iface `interface ResetConfirmationChange` (L331-335)
 - @brief Describes one pending reset value change shown in confirmation menus.
 - @details Stores the row label plus its previous and next values so reset-confirmation submenus can expose machine-readable and human-verifiable change previews. The interface is compile-time only and introduces no runtime cost.
 
-### fn `function formatResetConfirmationValue(previousValue: string, nextValue: string): string` (L317-319)
+### fn `function formatResetConfirmationValue(previousValue: string, nextValue: string): string` (L344-346)
 - @brief Formats one reset-confirmation value pair for menu display.
 - @details Serializes the previous and next values into a deterministic `previous -> next` preview string used by confirmation submenus. Runtime is O(n) in combined value length. No external state is mutated.
 - @param[in] previousValue {string} Current persisted value.
 - @param[in] nextValue {string} Candidate default value.
 - @return {string} Rendered preview string.
 
-### fn `function buildResetConfirmationChoices(` (L329-368)
+### fn `function buildResetConfirmationChoices(` (L356-395)
 - @brief Builds the shared settings-menu choices for one reset-confirmation submenu.
 - @details Renders each pending changed value as a disabled preview row, appends explicit approve and abort actions, and falls back to one disabled no-op row when no values would change. Runtime is O(n) in changed-value count. No external state is mutated.
 - @param[in] changes {ResetConfirmationChange[]} Changed-value preview rows.
@@ -4565,7 +4812,7 @@ cost.
 - @param[in] abortDescription {string} Description for the abort action.
 - @return {PiUsereqSettingsMenuChoice[]} Reset-confirmation submenu choices.
 
-### fn `async function confirmResetChanges(` (L380-393)
+### fn `async function confirmResetChanges(` (L407-420)
 - @brief Opens one explicit reset-confirmation submenu.
 - @details Uses the shared settings-menu renderer to show every changed value before reset application and returns `true` only when the user selects the explicit approval action. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
 - @param[in] ctx {ExtensionCommandContext} Active command context.
@@ -4575,60 +4822,73 @@ cost.
 - @param[in] abortDescription {string} Description for the abort action.
 - @return {Promise<boolean>} `true` when the reset is explicitly approved.
 
-### fn `function writePersistedProjectConfigToEditor(` (L404-411)
-- @brief Writes the already-persisted project configuration file text into the editor.
-- @details Reads the current `.pi-usereq.json` file content from disk after the caller has saved any pending configuration changes and forwards that exact persisted text into the editor. Runtime is O(n) in serialized config size. Side effects include filesystem reads and editor-text mutation.
+### fn `function writePersistedConfigToEditor(` (L429-434)
+- @brief Writes one already-persisted config file text into the editor.
+- @details Reads the target config file from disk after the caller has saved any pending changes and forwards the exact persisted text into the editor. Runtime is O(n) in serialized config size. Side effects include filesystem reads and editor-text mutation.
+- @param[in] ctx {ExtensionCommandContext} Active command context.
+- @param[in] configPath {string} Absolute persisted config path.
+- @return {void} No return value.
+
+### fn `function writePersistedLocalConfigToEditor(` (L444-450)
+- @brief Writes the already-persisted local configuration file text into the editor.
+- @details Reads `<base-path>/.pi-usereq.json` from disk after the caller has saved any pending local and global configuration changes, then forwards that exact persisted text into the editor. Runtime is O(n) in serialized config size. Side effects include filesystem reads and editor-text mutation.
 - @param[in] ctx {ExtensionCommandContext} Active command context.
 - @param[in] cwd {string} Current working directory.
-- @param[in] _config {UseReqConfig} Unused effective project configuration retained for stable call-site shape.
 - @return {void} No return value.
 - @satisfies REQ-031
 
-### fn `function buildSearchToolSupportedTagGuidelines(): string[]` (L472-476)
+### fn `function writePersistedGlobalConfigToEditor(` (L459-463)
+- @brief Writes the already-persisted global configuration file text into the editor.
+- @details Reads `~/.config/pi-usereq/config.json` from disk after the caller has saved any pending local and global configuration changes, then forwards that exact persisted text into the editor. Runtime is O(n) in serialized config size. Side effects include filesystem reads and editor-text mutation.
+- @param[in] ctx {ExtensionCommandContext} Active command context.
+- @return {void} No return value.
+- @satisfies REQ-318
+
+### fn `function buildSearchToolSupportedTagGuidelines(): string[]` (L524-528)
 - @brief Builds the supported-tag guidance lines embedded in search-tool registrations.
 - @details Emits one deterministic line per supported language containing its canonical registration label and sorted tag list so downstream agents can specialize requests without invoking the tool first. Runtime is O(l * t log t). No side effects occur.
 - @return {string[]} Supported-tag guidance lines.
 
-### fn `function buildSearchToolSchemaDescription(scope: FindToolScope): string` (L484-489)
+### fn `function buildSearchToolSchemaDescription(scope: FindToolScope): string` (L536-541)
 - @brief Builds the schema description for one search-tool registration.
 - @details Specializes the explicit-file and configured-directory input contracts while documenting the monolithic markdown output channel and minimal execution details shape. Runtime is O(1). No side effects occur.
 - @param[in] scope {FindToolScope} Search-tool scope.
 - @return {string} Parameter-schema description.
 
-### fn `function buildSearchToolPromptGuidelines(scope: FindToolScope): string[]` (L497-510)
+### fn `function buildSearchToolPromptGuidelines(scope: FindToolScope): string[]` (L549-562)
 - @brief Builds the prompt-guideline set for one search-tool registration.
 - @details Encodes scope selection, monolithic markdown output semantics, regex semantics, line-number behavior, tag-filter rules, and the full language-to-tag matrix as stable agent-oriented strings. Runtime is O(l * t log t). No side effects occur.
 - @param[in] scope {FindToolScope} Search-tool scope.
 - @return {string[]} Prompt-guideline strings.
 
-- type `type MonolithicToolRenderResult = {` (L516)
+- type `type MonolithicToolRenderResult = {` (L568)
 - @brief Describes the monolithic tool-result surface consumed by tool-row renderers.
 - @details Narrows execute-result data to the primary text content block plus the minimal `details.execution` metadata returned by monolithic tool wrappers. The alias is compile-time only and introduces no runtime cost.
-### fn `function getMonolithicToolText(result: MonolithicToolRenderResult): string` (L533-536)
+### fn `function getMonolithicToolText(result: MonolithicToolRenderResult): string` (L585-588)
 - @brief Extracts the primary monolithic text block from one tool result.
 - @details Returns the first text content block when present and falls back to an empty string when the tool emitted no LLM-facing content. Runtime is O(1). No external state is mutated.
 - @param[in] result {MonolithicToolRenderResult} Tool result wrapper.
 - @return {string} Primary monolithic content text.
 
-### fn `function getMonolithicToolErrorText(result: MonolithicToolRenderResult): string | undefined` (L544-554)
+### fn `function getMonolithicToolErrorText(result: MonolithicToolRenderResult): string | undefined` (L596-606)
 - @brief Reads the first residual execution error string from one monolithic tool result.
 - @details Prefers the first `stderr_lines` entry when present and otherwise falls back to the first line of `stderr`. Runtime is O(1) plus first-line split cost. No external state is mutated.
 - @param[in] result {MonolithicToolRenderResult} Tool result wrapper.
 - @return {string | undefined} First residual execution error string.
 
-### fn `function formatCompactToolArgumentValue(value: unknown): string | undefined` (L562-601)
+### fn `function formatCompactToolArgumentValue(value: unknown): string | undefined` (L614-653)
 - @brief Formats one scalar or structural tool argument for compact render summaries.
 - @details Truncates long strings, compresses arrays into short previews, and renders plain object arguments as key indexes so collapsed tool rows stay compact while still exposing the essential invocation shape. Runtime is O(n) in preview size. No external state is mutated.
 - @param[in] value {unknown} Candidate tool argument value.
 - @return {string | undefined} Compact preview string or `undefined` when the value carries no useful summary.
 
-### fn `function buildCompactToolInvocationText(args: Record<string, unknown> | undefined): string` (L609-620)
+### fn `function buildCompactToolInvocationText(args: Record<string, unknown> | undefined): string` (L661-672)
 - @brief Builds the compact invocation summary appended to collapsed tool rows.
 - @details Renders only caller-supplied parameters that have stable, non-empty compact previews and joins them in insertion order so agents can infer how the tool was used without expanding the full result. Runtime is O(n) in argument count and preview size. No external state is mutated.
 - @param[in] args {Record<string, unknown> | undefined} Current tool call arguments.
 - @return {string} Compact invocation summary prefixed with one separating space, or the empty string when no useful preview exists.
 
-### fn `function summarizeStructuredToolResult(` (L630-645)
+### fn `function summarizeStructuredToolResult(` (L682-697)
 - @brief Builds the compact default text for one monolithic tool result row.
 - @details Prefers the tool name, compact invocation preview, and success marker for collapsed rows, and falls back to residual execution diagnostics when the tool failed before completing successfully. Runtime is O(n) in compact argument-preview size. No external state is mutated.
 - @param[in] toolName {string} Registered tool name.
@@ -4636,20 +4896,27 @@ cost.
 - @param[in] args {Record<string, unknown> | undefined} Current tool call arguments.
 - @return {string} Compact single-line summary.
 
-### fn `function buildStructuredToolRenderResult(toolName: string)` (L654-673)
+### fn `function buildStructuredToolRenderResult(toolName: string)` (L706-725)
 - @brief Builds a custom `renderResult` implementation for one monolithic tool.
 - @details Reuses a mutable `Text` component when possible, keeps the default collapsed row compact with essential invocation parameters plus result status, and reveals the full monolithic content only when the tool row is expanded. Runtime is O(n) in expanded content length and compact argument-preview size. No external state is mutated.
 - @param[in] toolName {string} Registered tool name.
 - @return {(result: MonolithicToolRenderResult, options: { expanded?: boolean; isPartial?: boolean }, _theme: unknown, context: { args?: Record<string, unknown>; lastComponent?: unknown }) => Text} Custom result renderer.
 - @satisfies REQ-210
 
-### fn `function executeMonolithicTool(operation: () => ToolResult): ReturnType<typeof buildMonolithicToolExecuteResult>` (L681-687)
+### fn `function executeMonolithicTool(operation: () => ToolResult): ReturnType<typeof buildMonolithicToolExecuteResult>` (L733-739)
 - @brief Executes one CLI-style runner for a monolithic agent tool.
 - @details Reuses the standalone tool-runner contract, normalizes thrown failures into `ToolResult`, and wraps the selected stdout or stderr text into the monolithic content channel. Runtime is dominated by the delegated runner. Side effects depend on the selected tool.
 - @param[in] operation {() => ToolResult} Runner callback.
 - @return {ReturnType<typeof buildMonolithicToolExecuteResult>} Monolithic tool execute result.
 
-### fn `function deliverPromptCommand(` (L698-716)
+### fn `function executeStatusTool(operation: () => ToolResult): ReturnType<typeof buildMonolithicToolExecuteResult>` (L748-777)
+- @brief Executes one CLI-style runner for a status-only agent tool.
+- @details Reuses the standalone tool-runner contract, preserves `content[0].text` as the status-only `success` or `error: <diagnostic>` payload, and strips success-path `stdout_lines` so `details.execution` stays limited to the numeric code plus optional residual stderr diagnostics. Runtime is dominated by the delegated runner. Side effects depend on the selected tool.
+- @param[in] operation {() => ToolResult} Runner callback.
+- @return {ReturnType<typeof buildMonolithicToolExecuteResult>} Status-only tool execute result.
+- @satisfies REQ-294, REQ-295, REQ-296
+
+### fn `function deliverPromptCommand(` (L788-806)
 - @brief Starts delivery of one rendered prompt into the current active session.
 - @details Prefers the replacement-session `sendUserMessage(...)` helper exposed by `withSession(...)` callbacks after session replacement so post-switch prompt delivery never reuses stale pre-switch session-bound extension objects. Returns the underlying delivery promise without awaiting it so callers can record the `running` workflow transition as soon as prompt handoff is accepted instead of waiting for the full agent turn to complete on runtimes whose async replacement-session helpers resolve only after `agent_end`. When pi later invalidates that replacement-session context during successful prompt-end restoration, the helper suppresses the documented stale-extension-context rejection because the prompt was already accepted and late rethrow would surface a false orchestration failure. Falls back to `pi.sendUserMessage(...)` only for non-replacement flows or runtimes that do not expose replacement-session helpers. Runtime is O(n) in prompt length. Side effects are limited to user-message delivery.
 - @param[in] pi {ExtensionAPI} Handler-scoped extension API instance retained as the fallback dispatcher.
@@ -4658,7 +4925,7 @@ cost.
 - @return {Promise<void>} Promise representing eventual prompt-delivery completion.
 - @satisfies REQ-004, REQ-067, REQ-068, REQ-227, REQ-281
 
-### fn `function shouldIgnoreLatePromptDeliveryFailure(` (L727-743)
+### fn `function shouldIgnoreLatePromptDeliveryFailure(` (L817-833)
 - @brief Detects prompt-delivery failures that can be ignored after prompt ownership has moved past the command handler.
 - @details Matches the documented stale-extension-context runtime error once prompt ownership has already moved beyond command-side preflight. The helper treats the failure as ignorable when the persisted prompt runtime state shows the same execution session as the active prompt run or when the persisted workflow state has already advanced beyond `checking|running`, because rethrowing at that point would incorrectly re-enter command-side abort logic after the prompt was already accepted. Runtime is O(n) in error-message length plus path length. No external state is mutated.
 - @param[in] error {unknown} Candidate prompt-delivery failure.
@@ -4667,7 +4934,7 @@ cost.
 - @return {boolean} `true` when the failure is a late stale-context delivery rejection that MUST be ignored.
 - @satisfies REQ-208, REQ-280, REQ-281, REQ-282
 
-### fn `function logPromptWorkflowStateChange(` (L756-775)
+### fn `function logPromptWorkflowStateChange(` (L846-865)
 - @brief Appends one workflow-state debug entry for a bundled prompt when selected.
 - @details Reuses the shared debug logger so `req-*` command handlers and prompt-end orchestration can record deterministic workflow transitions without duplicating JSON payload shaping. Runtime is O(n) in serialized payload size only when logging is enabled and O(1) otherwise. Side effects include debug-log file writes for matching enabled prompts.
 - @param[in] projectBase {string} Absolute original project base path.
@@ -4678,7 +4945,7 @@ cost.
 - @return {void} No return value.
 - @satisfies REQ-245, REQ-246, REQ-247
 
-### fn `function logPromptWorkflowEvent(` (L791-811)
+### fn `function logPromptWorkflowEvent(` (L881-901)
 - @brief Appends one dedicated prompt workflow debug entry when selected.
 - @details Reuses the shared workflow-event logger so prompt activation, restoration, closure, and session-shutdown paths can emit higher-granularity orchestration diagnostics without duplicating JSON payload shaping. Runtime is O(n) in serialized payload size only when logging is enabled and O(1) otherwise. Side effects include debug-log file writes for matching enabled prompts.
 - @param[in] projectBase {string} Absolute original project base path.
@@ -4692,7 +4959,7 @@ cost.
 - @return {void} No return value.
 - @satisfies REQ-245, REQ-246, REQ-247, REQ-277
 
-### fn `function transitionPromptWorkflowState(` (L824-837)
+### fn `function transitionPromptWorkflowState(` (L914-927)
 - @brief Transitions one prompt workflow state and logs the transition immediately after the state update.
 - @details Captures the previous workflow state, applies the new state through the shared status helper, and appends the gated `workflow_state` debug entry only after the transition has completed. Runtime is O(1). Side effects include status mutation, status-bar rendering, and optional debug-log writes.
 - @param[in] ctx {ExtensionContext | ExtensionCommandContext} Active extension context.
@@ -4703,20 +4970,20 @@ cost.
 - @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
 - @return {void} No return value.
 
-### fn `function resolvePromptCommandDescription(` (L845-849)
+### fn `function resolvePromptCommandDescription(` (L935-939)
 - @brief Resolves the runtime slash-command description for one bundled prompt.
-- @details Reads the bundled prompt front matter, extracts its normalized `description` field, and falls back to the historical generated label when the prompt metadata omits a description. Runtime is O(n) in prompt length. Side effects are limited to filesystem reads.
+- @details Reads the bundled prompt markdown, extracts the first `# ` heading payload, and falls back to the historical generated label when the prompt omits a level-one heading. Runtime is O(n) in prompt length. Side effects are limited to filesystem reads.
 - @param[in] promptName {import("./core/prompt-command-catalog.js").PromptCommandName} Bundled prompt name.
 - @return {string} Runtime command description.
 
-### fn `function resolveDebugProjectBase(cwd: string, statusController: PiUsereqStatusController): string` (L858-862)
+### fn `function resolveDebugProjectBase(cwd: string, statusController: PiUsereqStatusController): string` (L948-952)
 - @brief Resolves the original project base used for debug-log file writes.
 - @details Prefers the active or pending prompt execution plan so tool-result logging during worktree-backed prompt runs persists into the original repository path instead of transient worktree directories. Runtime is O(1). No external state is mutated.
 - @param[in] cwd {string} Current extension working directory.
 - @param[in] statusController {PiUsereqStatusController} Mutable status controller.
 - @return {string} Absolute original project base path for debug logging.
 
-### fn `function notifyContextSafely(` (L873-890)
+### fn `function notifyContextSafely(` (L963-980)
 - @brief Delivers one best-effort UI notification without failing on stale replacement contexts.
 - @details Attempts to use the supplied extension context for UI notification delivery and suppresses the documented stale-extension-context runtime error raised after session replacement, because prompt-orchestration closure can outlive the context that initiated the switch. Runtime is O(n) in message length. Side effects are limited to user notification delivery when the context is still active.
 - @param[in] ctx {ExtensionContext | ExtensionCommandContext | undefined} Candidate UI context.
@@ -4725,20 +4992,30 @@ cost.
 - @return {boolean} `true` when the notification was delivered and `false` when the context was already stale.
 - @satisfies REQ-280
 
-### fn `function getPiUsereqStartupTools(pi: ExtensionAPI): ToolInfo[]` (L899-907)
+### fn `function rejectNonIdleReqCommand(` (L992-1012)
+- @brief Rejects one non-`idle` req-command invocation and records the workflow error state.
+- @details Builds a deterministic busy-state diagnostic from the current workflow state, transitions the shared workflow state to `error`, preserves any pending or active prompt execution metadata for later closure handling, emits an error notification, and throws `ReqError`. Bundled prompt commands reuse `transitionPromptWorkflowState(...)` when cached configuration is available so prompt debug logging captures the actual state transition; specialized non-prompt commands fall back to direct status mutation. Runtime is O(1). Side effects include workflow-state mutation, status-bar rendering, optional debug-log writes, and user notification delivery.
+- @param[in] ctx {ExtensionContext | ExtensionCommandContext} Active extension context.
+- @param[in] promptName {import("./core/prompt-command-catalog.js").PromptCommandName | undefined} Optional bundled prompt name used for prompt debug logging.
+- @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
+- @return {never} This helper always throws a deterministic `ReqError`.
+- @throws {ReqError} Always throws because non-`idle` req commands are rejected.
+- @satisfies REQ-224
+
+### fn `function getPiUsereqStartupTools(pi: ExtensionAPI): ToolInfo[]` (L1021-1029)
 - @brief Returns the configurable active-tool inventory visible to the extension.
 - @details Filters runtime tools against the canonical configurable-tool set, keeps only builtin-backed embedded tools, and orders the result by the documented custom/files/embedded/default-disabled grouping. Runtime is O(t log t). No external state is mutated.
 - @param[in] pi {ExtensionAPI} Active extension API instance.
 - @return {ToolInfo[]} Sorted configurable tool descriptors.
 - @satisfies REQ-007, REQ-063, REQ-231, REQ-232
 
-### fn `function getConfiguredEnabledPiUsereqTools(config: UseReqConfig): string[]` (L915-919)
+### fn `function getConfiguredEnabledPiUsereqTools(config: UseReqConfig): string[]` (L1037-1041)
 - @brief Normalizes and returns the configured enabled active tools.
 - @details Reuses repository normalization rules, updates the config object in place, and returns the normalized array. Runtime is O(n) in configured tool count. Side effect: mutates `config["enabled-tools"]`.
 - @param[in,out] config {UseReqConfig} Mutable configuration object.
 - @return {string[]} Normalized enabled tool names.
 
-### fn `function applyConfiguredPiUsereqTools(pi: ExtensionAPI, config: UseReqConfig): void` (L929-946)
+### fn `function applyConfiguredPiUsereqTools(pi: ExtensionAPI, config: UseReqConfig): void` (L1051-1068)
 - @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(...)`.
 - @param[in] pi {ExtensionAPI} Active extension API instance.
@@ -4746,18 +5023,18 @@ cost.
 - @return {void} No return value.
 - @satisfies REQ-009, REQ-064
 
-### fn `async function handleExtensionStatusEvent(` (L959-1219)
+### fn `async function handleExtensionStatusEvent(` (L1081-1352)
 - @brief Handles one intercepted pi lifecycle hook for pi-usereq status updates.
-- @details Applies session-start-specific resource validation, project-config refresh, startup-tool enablement, and selected debug-tool logging before forwarding the originating hook name and payload into the shared `updateExtensionStatus(...)` pipeline. Before `agent_start`, re-verifies any prepared prompt execution session switch. On `agent_end`, dispatches configured command-notify, sound, and prompt-specific Pushover effects, logs dedicated workflow-closure diagnostics, restores the original session-backed `base-path` for every matched worktree-backed completion by reusing persisted replacement-session command contexts when event contexts omit `switchSession()`, merges and deletes the worktree only for matched successful completions, tolerates stale replacement-session notification contexts after session replacement, retains the worktree plus notifies closure failure for interrupted or failed outcomes, logs selected prompt workflow transitions, and transitions workflow state through `merging`, `error`, and `idle` as required. On `session_shutdown`, captures pre-update prompt snapshots so workflow-shutdown diagnostics and same-runtime command continuation preserve the active prompt workflow state across switch-triggered rebinding, then disposes the shared controller. Runtime is dominated by configuration loading during `session_start` and git finalization during matched successful `agent_end` handling; all other hooks are O(1). Side effects include resource checks, active-tool mutation, active-session replacement, status updates, live-ticker disposal on shutdown, optional child-process spawning, outbound HTTPS requests, branch merges, worktree deletion, and optional debug-log writes.
+- @details Applies session-start-specific resource validation, project-config refresh, startup-tool enablement, and selected debug-tool logging before forwarding the originating hook name and payload into the shared `updateExtensionStatus(...)` pipeline. Before `agent_start`, re-verifies any prepared prompt execution session switch. On `agent_end`, dispatches configured command-notify, sound, and prompt-specific Pushover effects, logs dedicated workflow-closure diagnostics, restores the original session-backed `base-path` for every matched worktree-backed completion by reusing persisted replacement-session command contexts when event contexts omit `switchSession()`, executes the stash-assisted merge-and-delete finalization path for every matched successful worktree-backed completion even when a later busy-command rejection already moved workflow state to `error`, emits a warning-only notification when restored `base-path` changes are reapplied after merge, tolerates stale replacement-session notification contexts after session replacement, retains the worktree plus notifies closure failure for interrupted or failed outcomes, logs selected prompt workflow transitions, and transitions workflow state through `merging`, `error`, and `idle` as required. On `session_shutdown`, captures pre-update prompt snapshots so workflow-shutdown diagnostics and same-runtime command continuation preserve the active prompt workflow state across switch-triggered rebinding, then disposes the shared controller. Runtime is dominated by configuration loading during `session_start` and git finalization during matched successful `agent_end` handling; all other hooks are O(1). Side effects include resource checks, active-tool mutation, active-session replacement, status updates, live-ticker disposal on shutdown, optional child-process spawning, outbound HTTPS requests, branch merges, worktree deletion, and optional debug-log writes.
 - @param[in] pi {ExtensionAPI} Active extension API instance.
 - @param[in] hookName {PiUsereqStatusHookName} Intercepted hook name.
 - @param[in] event {unknown} Hook payload forwarded by pi.
 - @param[in] ctx {ExtensionContext} Active extension context.
 - @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
 - @return {Promise<void>} Promise resolved when hook processing completes.
-- @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, REQ-208, REQ-209, REQ-221, REQ-228, REQ-229, REQ-230, REQ-244, REQ-245, REQ-246, REQ-247, REQ-276, REQ-277, REQ-278, REQ-279, REQ-280
+- @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, REQ-208, REQ-209, REQ-221, REQ-228, REQ-229, REQ-230, REQ-244, REQ-245, REQ-246, REQ-247, REQ-276, REQ-277, REQ-278, REQ-279, REQ-280, REQ-291, REQ-292
 
-### fn `function registerExtensionStatusHooks(` (L1235-1254)
+### fn `function registerExtensionStatusHooks(` (L1368-1387)
 - @brief Registers shared wrappers for every supported pi lifecycle hook.
 - @details Installs one generic wrapper per intercepted hook so every resource,
 session, agent, model, tool, bash, and input event is routed through the
@@ -4771,7 +5048,7 @@ registered hook count. Side effects include hook registration.
 - @return {void} No return value.
 - @satisfies DES-002, REQ-113, REQ-114, REQ-115, REQ-116, REQ-117
 
-### fn `function setConfiguredPiUsereqTools(pi: ExtensionAPI, config: UseReqConfig, enabledTools: string[]): void` (L1264-1267)
+### fn `function setConfiguredPiUsereqTools(pi: ExtensionAPI, config: UseReqConfig, enabledTools: string[]): void` (L1397-1400)
 - @brief Replaces the configured active-tool selection and applies it immediately.
 - @details Normalizes the requested tool names, stores them in config, and synchronizes the active tool set with runtime registration state. Runtime is O(n + t). Side effect: mutates config and active tools.
 - @param[in] pi {ExtensionAPI} Active extension API instance.
@@ -4779,26 +5056,26 @@ registered hook count. Side effects include hook registration.
 - @param[in,out] config {UseReqConfig} Mutable configuration object.
 - @return {void} No return value.
 
-### fn `function getDebugToolToggleNames(): PiUsereqStartupToolName[]` (L1275-1277)
+### fn `function getDebugToolToggleNames(): PiUsereqStartupToolName[]` (L1408-1410)
 - @brief Returns the canonical debug-tool toggle order.
 - @details Reuses the documented configurable-tool ordering so debug toggles list extension-owned tools before embedded tools and remain deterministic across sessions. Runtime is O(t log t). No external state is mutated.
 - @return {PiUsereqStartupToolName[]} Ordered debug-tool toggle names.
 - @satisfies REQ-242
 
-### fn `function resetDebugConfigToDefaults(config: UseReqConfig): void` (L1286-1294)
+### fn `function resetDebugConfigToDefaults(config: UseReqConfig): void` (L1419-1427)
 - @brief Restores the debug configuration subtree to its documented defaults.
 - @details Resets global debug enablement, log path, workflow-state filter, dedicated workflow-event logging, and selected tool plus prompt debug toggles without mutating unrelated settings. Runtime is O(1). Side effect: mutates `config`.
 - @param[in,out] config {UseReqConfig} Mutable configuration object.
 - @return {void} No return value.
 - @satisfies REQ-236, REQ-237, REQ-238, REQ-239, REQ-195, REQ-277
 
-### fn `function formatDebugMenuSummary(config: UseReqConfig): string` (L1302-1308)
+### fn `function formatDebugMenuSummary(config: UseReqConfig): string` (L1435-1441)
 - @brief Formats the top-level Debug summary value.
 - @details Emits the current global debug mode plus compact selected-tool and selected-prompt counts for right-aligned menu display. Runtime is O(n) in configured selector count. No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {string} Compact debug summary string.
 
-### fn `function buildDebugMenuChoice(` (L1318-1331)
+### fn `function buildDebugMenuChoice(` (L1451-1464)
 - @brief Builds one debug-menu row with optional disabled styling.
 - @details Applies dim styling and disables selection whenever global debug is off for all rows except the global `Debug` toggle row. Runtime is O(1). No external state is mutated.
 - @param[in] choice {PiUsereqSettingsMenuChoice} Base debug-menu row.
@@ -4806,21 +5083,21 @@ registered hook count. Side effects include hook registration.
 - @return {PiUsereqSettingsMenuChoice} Styled debug-menu row.
 - @satisfies REQ-241
 
-### fn `async function selectDebugLogOnStatus(` (L1340-1368)
+### fn `async function selectDebugLogOnStatus(` (L1473-1501)
 - @brief Opens the workflow-state filter selector used by the Debug submenu.
 - @details Exposes `any` plus each canonical workflow state through the shared settings-menu renderer and returns the selected normalized filter or `undefined` when the user cancels the submenu. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
 - @param[in] ctx {ExtensionCommandContext} Active command context.
 - @param[in] currentValue {DebugLogOnStatus} Current persisted workflow-state filter.
 - @return {Promise<DebugLogOnStatus | undefined>} Selected workflow-state filter or `undefined` when cancelled.
 
-### fn `function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L1377-1448)
+### fn `function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L1510-1586)
 - @brief Builds the shared settings-menu choices for debug logging configuration.
 - @details Serializes global debug controls plus workflow-state, dedicated workflow-event, per-tool, and per-prompt toggles into one submenu, deriving inventories from the canonical tool and prompt lists and dimming locked rows while debug is disabled. Runtime is O(t + p). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered debug-menu choices.
 - @satisfies REQ-240, REQ-241, REQ-242, REQ-243, REQ-193, REQ-277
 
-### fn `async function configureDebugMenu(` (L1458-1575)
+### fn `async function configureDebugMenu(` (L1596-1765)
 - @brief Runs the interactive Debug submenu.
 - @details Lets the user toggle global debug enablement, edit debug file and workflow filters, toggle dedicated workflow-event logging, mutate per-tool and per-prompt debug selectors, and restore subtree defaults while preserving row focus across re-renders. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
 - @param[in] ctx {ExtensionCommandContext} Active command context.
@@ -4828,45 +5105,45 @@ registered hook count. Side effects include hook registration.
 - @return {Promise<void>} Promise resolved when the submenu closes.
 - @satisfies REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-192, REQ-193, REQ-195, REQ-277
 
-- type `type PiNotifyBooleanConfigKey =` (L1581)
+- type `type PiNotifyBooleanConfigKey =` (L1771)
 - @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.
-- type `type PiNotifyEventBooleanConfigKey = Exclude<` (L1598)
+- type `type PiNotifyEventBooleanConfigKey = Exclude<` (L1788)
 - @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 `type PiNotifyEventId = "completed" | "interrupted" | "failed";` (L1607)
+- type `type PiNotifyEventId = "completed" | "interrupted" | "failed";` (L1797)
 - @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.
-### iface `interface PiNotifyEventRowDefinition` (L1613-1617)
+### iface `interface PiNotifyEventRowDefinition` (L1803-1807)
 - @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.
 
-### iface `interface PiNotifyEventMenuDefinition` (L1623-1629)
+### iface `interface PiNotifyEventMenuDefinition` (L1813-1819)
 - @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.
 
-### fn `function togglePiNotifyFlag(config: UseReqConfig, key: PiNotifyBooleanConfigKey): boolean` (L1638-1641)
+### fn `function togglePiNotifyFlag(config: UseReqConfig, key: PiNotifyBooleanConfigKey): boolean` (L1828-1831)
 - @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] key {PiNotifyBooleanConfigKey} Boolean configuration key to toggle.
 - @param[in,out] config {UseReqConfig} Mutable configuration object.
 - @return {boolean} Next enabled state.
 
-### fn `function resetPiNotifyConfigToDefaults(config: UseReqConfig): void` (L1650-1674)
+### fn `function resetPiNotifyConfigToDefaults(config: UseReqConfig): void` (L1840-1864)
 - @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
 
-### fn `function formatPiNotifyPushoverPriority(priority: PiNotifyPushoverPriority): string` (L1683-1685)
+### fn `function formatPiNotifyPushoverPriority(priority: PiNotifyPushoverPriority): string` (L1873-1875)
 - @brief Formats one persisted Pushover priority for menu display.
 - @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-172
 
-### fn `function formatPiNotifyEventMenuSummary(` (L1762-1770)
+### fn `function formatPiNotifyEventMenuSummary(` (L1959-1967)
 - @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.
@@ -4874,7 +5151,7 @@ registered hook count. Side effects include hook registration.
 - @return {string} Compact enabled-toggle summary.
 - @satisfies REQ-198
 
-### fn `function buildPiNotifyEventLauncherChoice(` (L1780-1790)
+### fn `function buildPiNotifyEventLauncherChoice(` (L1977-1987)
 - @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.
@@ -4882,7 +5159,7 @@ registered hook count. Side effects include hook registration.
 - @return {PiUsereqSettingsMenuChoice} Launcher row for the selected event submenu.
 - @satisfies REQ-181, REQ-183, REQ-165, REQ-198
 
-### fn `function buildPiNotifyEventMenuChoices(` (L1800-1815)
+### fn `function buildPiNotifyEventMenuChoices(` (L1997-2013)
 - @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 a value-less `Reset defaults` row for submenu-scoped mutation control. Runtime is O(1). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
@@ -4890,7 +5167,7 @@ registered hook count. Side effects include hook registration.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered event-submenu choice vector.
 - @satisfies REQ-188, REQ-193, REQ-198
 
-### fn `function resetPiNotifyEventMenuToDefaults(` (L1825-1833)
+### fn `function resetPiNotifyEventMenuToDefaults(` (L2023-2031)
 - @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] eventMenu {PiNotifyEventMenuDefinition} Notification-system event submenu contract.
@@ -4898,7 +5175,7 @@ registered hook count. Side effects include hook registration.
 - @return {void} No return value.
 - @satisfies REQ-174, REQ-178, REQ-184, REQ-195
 
-### fn `function resolvePiNotifyEventLabel(` (L1843-1850)
+### fn `function resolvePiNotifyEventLabel(` (L2041-2048)
 - @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.
@@ -4906,7 +5183,7 @@ registered hook count. Side effects include hook registration.
 - @return {string} Human-readable event label.
 - @satisfies REQ-188, REQ-198
 
-### fn `async function configurePiNotifyEventMenu(` (L1861-1921)
+### fn `async function configurePiNotifyEventMenu(` (L2059-2135)
 - @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.
@@ -4915,14 +5192,14 @@ registered hook count. Side effects include hook registration.
 - @return {Promise<void>} Promise resolved when the submenu closes.
 - @satisfies REQ-188, REQ-192, REQ-193, REQ-195, REQ-198
 
-### fn `function buildPiNotifyPushoverRows(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L1930-1979)
+### fn `function buildPiNotifyPushoverRows(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L2144-2194)
 - @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, dims and disables the enable row until both credentials are populated, and escapes control characters for the single-line `Pushover text` value. Runtime is O(n) in the rendered text-template length. No external state is mutated.
+- @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, dims and disables the enable row until both credentials are populated, renders the locked value as `configure user/token keys first`, and escapes control characters for the single-line `Pushover text` value. Runtime is O(n) in the rendered text-template length. 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, REQ-234, REQ-235
 
-### fn `async function selectPiNotifyPushoverPriority(` (L1989-2017)
+### fn `async function selectPiNotifyPushoverPriority(` (L2204-2232)
 - @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 notification menus and appends a value-less subtree-local `Reset defaults` row. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
 - @param[in] ctx {ExtensionCommandContext} Active command context.
@@ -4930,58 +5207,82 @@ registered hook count. Side effects include hook registration.
 - @return {Promise<PiNotifyPushoverPriority | "reset-defaults" | undefined>} Selected priority, reset action, or `undefined` when cancelled.
 - @satisfies REQ-172, REQ-192
 
-### fn `function buildPiNotifyMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L2026-2083)
+### fn `function buildPiNotifyMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L2241-2299)
 - @brief Builds the shared settings-menu choices for notification configuration.
-- @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, including locked Pushover enablement and escaped single-line rendering for `Pushover text`. Runtime is O(n) in the longest rendered command or text field. 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, including locked Pushover enablement, persisted boot-sound rows that stay decoupled from the active runtime sound level, and escaped single-line rendering for `Pushover text`. Runtime is O(n) in the longest rendered command or text field. 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-172, REQ-179, REQ-181, REQ-183, REQ-188, REQ-193, REQ-198, REQ-234, REQ-235
+- @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, REQ-234, REQ-235, REQ-289
 
-### fn `async function selectPiNotifySoundLevel(` (L2093-2133)
-- @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 appends a value-less subtree-local `Reset defaults` row. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
+### fn `async function selectPiNotifySoundLevel(` (L2309-2349)
+- @brief Opens the shared settings-menu selector for the persisted boot sound level.
+- @details Reuses the pi-usereq settings-menu renderer so boot-sound selection remains stylistically aligned with the notification menu, keeps the active runtime sound level unchanged, and appends a value-less subtree-local `Reset defaults` row. 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 sound level.
-- @return {Promise<PiNotifySoundLevel | "reset-defaults" | undefined>} Selected sound level, reset action, or `undefined` when cancelled.
-- @satisfies REQ-131, REQ-179, REQ-192
+- @param[in] currentLevel {PiNotifySoundLevel} Persisted boot sound level.
+- @return {Promise<PiNotifySoundLevel | "reset-defaults" | undefined>} Selected boot sound level, reset action, or `undefined` when cancelled.
+- @satisfies REQ-131, REQ-179, REQ-192, REQ-289
 
-### fn `async function configurePiNotifyMenu(` (L2143-2409)
+### fn `async function configurePiNotifyMenu(` (L2359-2645)
 - @brief Runs the interactive notification-configuration menu.
-- @details Exposes command-notify, sound, and Pushover controls through the shared settings-menu renderer, delegates completed/interrupted/failed toggles to dedicated event submenus, keeps `Enable pushover` locked until both credentials are populated, decodes escaped control-sequence input for `Pushover text`, and preserves row focus across menu re-renders. 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, persists every notification subtree mutation into global configuration, delegates completed/interrupted/failed toggles to dedicated event submenus, preserves boot-sound edits without altering the active runtime sound level, keeps `Enable pushover` locked until both credentials are populated, decodes escaped control-sequence input for `Pushover text`, 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-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, REQ-234, REQ-235
+- @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, REQ-234, REQ-235, REQ-288, REQ-289
 
-### fn `function registerPiNotifyShortcut(` (L2424-2444)
+### fn `function registerPiNotifyShortcut(` (L2660-2683)
 - @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
-notification. Runtime is O(1) for registration plus config I/O per shortcut
-use. Side effects include shortcut registration, config writes, and status
-updates.
+- @details Loads the current effective config, registers one raw pi shortcut when
+the runtime exposes `registerShortcut(...)`, cycles only the active runtime
+sound level on invocation, leaves persisted local and global configuration
+unchanged, refreshes the status bar, and emits one info notification. Runtime is O(1) for registration
+plus one status update per shortcut use. Side effects include shortcut
+registration and status updates.
+- @param[in] pi {ExtensionAPI} Active extension API instance.
+- @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
+- @return {void} No return value.
+- @satisfies REQ-134, REQ-180, REQ-286, REQ-287
+
+### fn `function resolveReqResetPromptRequest(` (L2691-2717)
+- @brief Resolves the prompt execution plan targeted by `req-reset` recovery.
+- @details Prefers the current in-memory active request, then the current in-memory pending request, then the process-scoped persisted prompt runtime state so the dedicated reset command can recover from same-host unclean prompt termination after session replacement. Runtime is O(1). No external state is mutated.
+- @param[in] statusController {PiUsereqStatusController} Mutable status controller.
+- @return {PromptCommandExecutionPlan | undefined} Recoverable prompt execution plan when one remains available.
+
+### fn `const isWorktreeBacked = (request: PromptCommandExecutionPlan | undefined): request is PromptCommandExecutionPlan =>` (L2694-2701)
+
+### fn `function registerReqResetCommand(` (L2727-2781)
+- @brief Registers the specialized `req-reset` slash command.
+- @details Registers the non-agentic prompt-recovery command that accepts any current workflow state, reuses persisted prompt runtime state when available, restores the original session-backed `base-path`, force-removes matching generated worktrees plus branches, clears recoverable prompt state when restoration succeeds, and notifies pi without starting an LLM session or creating a worktree. Runtime is dominated by session restoration plus git cleanup. Side effects include command registration, status-controller mutation, active-session replacement, worktree deletion, branch deletion, and user notifications.
+- @param[in] pi {ExtensionAPI} Active extension API instance.
+- @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
+- @return {void} No return value.
+- @satisfies REQ-304, REQ-305, REQ-306, REQ-307, REQ-308, REQ-309, REQ-310, REQ-311, REQ-312, REQ-313
+
+### fn `function registerReqReferencesCommand(` (L2791-2831)
+- @brief Registers the specialized `req-references` slash command.
+- @details Registers the non-agentic references-maintenance command that rejects non-`idle` invocations by transitioning workflow state to `error` before direct execution, otherwise reuses slash-command-owned git validation, transitions workflow state through `checking|running|idle`, regenerates `REFERENCES.md` directly from configured source directories, stages only the generated file, creates the fixed-message git commit, verifies repository cleanliness, and notifies pi without starting an LLM session or creating a worktree. Runtime is dominated by git subprocess execution plus source-summary generation. Side effects include command registration, status-controller mutation, filesystem writes, git index/history mutation, and user notifications.
 - @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-180
+- @satisfies REQ-200, REQ-221, REQ-224, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303
 
-### fn `function registerPromptCommands(` (L2454-2572)
-- @brief Registers bundled prompt commands with the extension.
-- @details Creates one `req-<prompt>` command per bundled prompt name. Each handler rejects non-`idle` workflow state, transitions the shared workflow state through `checking`, `error`, and `running`, runs dedicated prompt-command git and required-doc preflight checks, optionally prepares a dedicated worktree execution plan using the active session directory, persists the prompt metadata needed for switch-triggered rebinding, switches the active session to the verified execution cwd before prompt handoff, logs dedicated workflow-activation diagnostics, renders the prompt, starts prompt delivery into the forked active session, records `running` immediately after delivery handoff begins, and then awaits the wrapped prompt-delivery promise whose stale post-restore rejections are suppressed. Runtime is O(p) for registration; handler cost depends on prompt preflight, worktree preparation, session switching, prompt rendering, prompt dispatch, and optional debug logging. Side effects include command registration, status-controller mutation, worktree creation, active-session replacement, optional worktree rollback, user-message delivery during execution, and optional debug-log writes.
+### fn `function registerPromptCommands(` (L2841-2957)
+- @brief Registers bundled prompt-backed commands with the extension.
+- @details Creates one prompt-template-backed `req-<prompt>` command per bundled prompt name. Each handler rejects non-`idle` workflow state by transitioning the shared workflow state to `error` before command-side preflight, otherwise transitions the shared workflow state through `checking`, `error`, and `running`, runs dedicated prompt-command git and required-doc preflight checks, optionally prepares a dedicated worktree execution plan using the active session directory, persists the prompt metadata needed for switch-triggered rebinding, switches the active session to the verified execution cwd before prompt handoff, logs dedicated workflow-activation diagnostics, renders the prompt, starts prompt delivery into the forked active session, records `running` immediately after delivery handoff begins, and then awaits the wrapped prompt-delivery promise whose stale post-restore rejections are suppressed. Runtime is O(p) for registration; handler cost depends on prompt preflight, worktree preparation, session switching, prompt rendering, prompt dispatch, and optional debug logging. Side effects include command registration, status-controller mutation, worktree creation, active-session replacement, optional worktree rollback, user-message delivery during execution, and optional debug-log writes.
 - @param[in] pi {ExtensionAPI} Active extension API instance.
 - @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
 - @return {void} No return value.
 - @satisfies REQ-004, REQ-067, REQ-068, REQ-169, REQ-200, REQ-201, REQ-202, REQ-203, REQ-206, REQ-207, REQ-219, REQ-220, REQ-221, REQ-224, REQ-225, REQ-226, REQ-227, REQ-245, REQ-246, REQ-247, REQ-277, REQ-281
 
-### fn `function registerAgentTools(pi: ExtensionAPI): void` (L2582-2881)
+### fn `function registerAgentTools(pi: ExtensionAPI): void` (L2967-3266)
 - @brief Registers pi-usereq agent tools exposed to the model.
 - @details Defines the tool schemas, prompt metadata, and execution handlers that bridge extension tool calls into tool-runner operations without registering duplicate custom slash commands for the same capabilities. Runtime is O(t) for registration; execution cost depends on the selected tool. Side effects include tool registration.
 - @param[in] pi {ExtensionAPI} Active extension API instance.
 - @return {void} No return value.
-- @satisfies REQ-005, REQ-010, REQ-011, REQ-014, REQ-017, REQ-044, REQ-069, REQ-070, REQ-071, REQ-072, REQ-073, REQ-074, REQ-075, REQ-076, REQ-077, REQ-078, REQ-079, REQ-080, REQ-089, REQ-090, REQ-091, REQ-092, REQ-093, REQ-094, REQ-095, REQ-096, REQ-097, REQ-098, REQ-099, REQ-100, REQ-101, REQ-102
+- @satisfies REQ-005, REQ-010, REQ-011, REQ-014, REQ-017, REQ-044, REQ-069, REQ-070, REQ-071, REQ-072, REQ-073, REQ-074, REQ-075, REQ-076, REQ-077, REQ-078, REQ-079, REQ-080, REQ-089, REQ-090, REQ-091, REQ-092, REQ-093, REQ-094, REQ-095, REQ-096, REQ-097, REQ-098, REQ-099, REQ-100, REQ-101, REQ-102, REQ-293, REQ-294, REQ-295, REQ-296, REQ-297
 
-### fn `function buildPiUsereqToolsMenuChoices(pi: ExtensionAPI, config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L2899-2924)
+### fn `function buildPiUsereqToolsMenuChoices(pi: ExtensionAPI, config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3311-3336)
 - @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 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.
@@ -4989,7 +5290,7 @@ updates.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered startup-tool menu choices.
 - @satisfies REQ-007, REQ-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-193
 
-### fn `function buildPiUsereqToolToggleChoices(pi: ExtensionAPI, config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L2934-2947)
+### fn `function buildPiUsereqToolToggleChoices(pi: ExtensionAPI, config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3346-3360)
 - @brief Builds the shared settings-menu choices for per-tool startup toggles.
 - @details Exposes every configurable startup tool as one row whose right-side value reports the current enabled state, preserves the documented custom/files/embedded/default-disabled ordering, and appends a value-less subtree-local `Reset defaults` row. Runtime is O(t) in configurable-tool count. No external state is mutated.
 - @param[in] pi {ExtensionAPI} Active extension API instance.
@@ -4997,108 +5298,108 @@ updates.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered per-tool toggle choices.
 - @satisfies REQ-007, REQ-151, REQ-152, REQ-153, REQ-154, REQ-231, REQ-232
 
-### fn `async function configurePiUsereqToolsMenu(` (L2958-3053)
+### fn `async function configurePiUsereqToolsMenu(` (L3371-3488)
 - @brief Runs the interactive active-tool configuration menu.
-- @details Synchronizes runtime active tools with persisted config, renders startup-tool actions through the shared settings-menu UI, preserves the documented per-tool ordering, and updates configuration state in response to selections until the user exits. Runtime depends on user interaction count. Side effects include UI updates, active-tool changes, and config mutation.
+- @details Synchronizes runtime active tools with the effective config, renders startup-tool actions through the shared settings-menu UI, persists enablement changes into global configuration, preserves the documented per-tool ordering, and updates configuration state in response to selections until the user exits. Runtime depends on user interaction count. Side effects include UI updates, active-tool changes, and config mutation.
 - @param[in] pi {ExtensionAPI} Active extension API instance.
 - @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-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-193, REQ-231, REQ-232
 
-### fn `function getStaticCheckLanguageConfigForMenu(` (L3062-3067)
+### fn `function getStaticCheckLanguageConfigForMenu(` (L3497-3502)
 - @brief Resolves one static-check language config for menu rendering.
 - @details Returns the configured per-language static-check object when present and otherwise synthesizes a disabled empty-language object so menu code can render all supported languages deterministically. Runtime is O(1). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @param[in] language {string} Canonical language name.
 - @return {StaticCheckLanguageConfig} Resolved per-language config object.
 
-### fn `function countConfiguredStaticCheckLanguages(config: UseReqConfig): number` (L3075-3077)
+### fn `function countConfiguredStaticCheckLanguages(config: UseReqConfig): number` (L3510-3512)
 - @brief Counts languages that currently expose at least one configured checker.
 - @details Treats configured-but-disabled languages as configured when their checker list is non-empty so removal actions remain deterministic. Runtime is O(l). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {number} Number of languages with at least one configured checker.
 
-### fn `function countEnabledStaticCheckLanguages(config: UseReqConfig): number` (L3085-3087)
+### fn `function countEnabledStaticCheckLanguages(config: UseReqConfig): number` (L3520-3522)
 - @brief Counts languages whose static-check enable flag is on.
 - @details Counts only languages whose persisted per-language config explicitly sets `enabled=enable`, regardless of checker count. Runtime is O(l). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {number} Number of enabled languages.
 
-### fn `function resetStaticCheckConfig(config: UseReqConfig): void` (L3096-3098)
+### fn `function resetStaticCheckConfig(config: UseReqConfig): void` (L3531-3533)
 - @brief Restores the documented static-check default configuration.
 - @details Replaces the mutable config subtree with a fresh clone of the documented per-language defaults so menu reset actions restore both enable flags and checker lists in one step. Runtime is O(l + c). Side effect: mutates `config`.
 - @param[in,out] config {UseReqConfig} Mutable configuration object.
 - @return {void} No return value.
 - @satisfies REQ-250, REQ-251, REQ-252
 
-### fn `function formatStaticCheckLanguagesSummary(config: UseReqConfig): string` (L3106-3108)
+### fn `function formatStaticCheckLanguagesSummary(config: UseReqConfig): string` (L3541-3543)
 - @brief Summarizes enabled and configured static-check languages.
 - @details Counts enabled languages and languages with at least one checker, then emits one compact summary string suitable for the top-level configuration menu. Runtime is O(l). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {string} Compact summary string.
 
-### fn `function buildStaticCheckMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3117-3148)
+### fn `function buildStaticCheckMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3552-3584)
 - @brief Builds the shared settings-menu choices for static-check management.
 - @details Serializes guided Command-oriented add and remove actions, renders one direct on/off toggle row for every supported language, and appends canonical terminal rows while omitting raw-spec and reference-only actions. Runtime is O(l). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered static-check menu choices.
 - @satisfies REQ-008, REQ-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-160, REQ-161, REQ-193, REQ-248
 
-### fn `function buildSupportedStaticCheckLanguageChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3156-3173)
+### fn `function buildSupportedStaticCheckLanguageChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3592-3609)
 - @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, enablement, and configured checker count for guided Command configuration flows, then appends subtree-local terminal rows. Runtime is O(l). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered language-choice vector.
 
-### fn `function buildConfiguredStaticCheckLanguageChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3181-3198)
+### fn `function buildConfiguredStaticCheckLanguageChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3617-3634)
 - @brief Builds the shared settings-menu choices for configured static-check languages.
 - @details Exposes only languages whose checker lists are non-empty so removal remains deterministic, then appends subtree-local terminal rows. Runtime is O(l). No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered configured-language vector.
 
-### fn `async function configureStaticCheckMenu(` (L3208-3341)
+### fn `async function configureStaticCheckMenu(` (L3644-3790)
 - @brief Runs the interactive static-check configuration menu.
-- @details Lets the user add Command entries by guided prompts, remove configured language entries, toggle direct per-language enable flags, and reset the subtree to documented defaults 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 and remove global Command entries, toggle direct local per-language enable flags, and reset the subtree to documented defaults 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, REQ-160, REQ-161, REQ-193, REQ-195, REQ-248, REQ-253
 
-### fn `function buildPiUsereqMenuChoices(` (L3351-3440)
+### fn `function buildPiUsereqMenuChoices(` (L3800-3899)
 - @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, including automatic git-commit mode, effective prompt-command worktree state, notification summary, debug summary, locked worktree rows when automatic git commit is disabled, and the display-only config path beside `show-config`. 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 automatic git-commit mode, effective prompt-command worktree state, notification summary, debug summary, locked worktree rows when automatic git commit is disabled, and display-only local plus global config paths. 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, REQ-162, REQ-190, REQ-191, REQ-197, REQ-204, REQ-205, REQ-212, REQ-215, REQ-216, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240
+- @satisfies REQ-006, REQ-031, REQ-137, REQ-150, REQ-151, REQ-152, REQ-162, REQ-190, REQ-191, REQ-197, REQ-204, REQ-205, REQ-212, REQ-215, REQ-216, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-314, REQ-318, REQ-319, REQ-320
 
-### fn `function buildSrcDirMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3449-3467)
+### fn `function buildSrcDirMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3908-3926)
 - @brief Builds the shared settings-menu choices for source-directory management.
 - @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, REQ-193
 
-### fn `function buildSrcDirRemovalChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3476-3488)
+### fn `function buildSrcDirRemovalChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3935-3947)
 - @brief Builds the shared settings-menu choices for removing one source-directory entry.
 - @details Exposes every configured `src-dir` entry as one removable row and appends a value-less subtree-local `Reset defaults` row. Runtime is O(s) in source-directory count. No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
 - @return {PiUsereqSettingsMenuChoice[]} Ordered removable source-directory choices.
 - @satisfies REQ-006, REQ-151, REQ-152, REQ-153, REQ-154
 
-### fn `async function configurePiUsereq(` (L3499-3719)
+### fn `async function configurePiUsereq(` (L3958-4211)
 - @brief Runs the top-level pi-usereq configuration menu.
-- @details Loads project config, exposes docs/test/source/automatic-commit/worktree/static-check/startup-tool/notification/debug actions through the shared settings-menu renderer, forces worktree disablement when automatic git commit is disabled, prevents locked row edits, persists changes on exit, closes immediately after `Show configuration`, 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.
+- @details Loads the effective merged config, exposes docs/test/source/automatic-commit/worktree/static-check/startup-tool/notification/debug actions through the shared settings-menu renderer, forces worktree disablement when automatic git commit is disabled, prevents locked row edits, persists changes on exit, closes immediately after `Show local configuration` or `Show global configuration`, 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, REQ-162, REQ-190, REQ-191, REQ-192, REQ-194, REQ-195, REQ-204, REQ-205, REQ-212, REQ-215, REQ-216, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243
+- @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, REQ-204, REQ-205, REQ-212, REQ-215, REQ-216, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-314, REQ-318, REQ-319, REQ-320
 
-### fn `const persistConfigChange = () =>` (L3510-3515)
+### fn `const persistConfigChange = () =>` (L3969-3974)
 
-### fn `function registerConfigCommands(` (L3729-3739)
+### fn `function registerConfigCommands(` (L4221-4231)
 - @brief Registers configuration-management commands.
 - @details Adds the interactive `pi-usereq` configuration command only; the config-viewer action is now exposed exclusively inside that menu. Runtime is O(1) for registration. Side effects include command registration.
 - @param[in] pi {ExtensionAPI} Active extension API instance.
@@ -5106,110 +5407,110 @@ updates.
 - @return {void} No return value.
 - @satisfies REQ-006, REQ-031
 
-### fn `export default function piUsereqExtension(pi: ExtensionAPI): void` (L3757-3765)
+### fn `export default function piUsereqExtension(pi: ExtensionAPI): void` (L4240-4250)
 - @brief Registers the complete pi-usereq extension.
-- @details Validates installation-owned bundled resources, registers prompt and
-configuration commands plus agent tools, registers the configurable
-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, tool-result debug logging, and prompt-orchestration debug
-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,
-optional debug-log writes, and timer scheduling.
+- @details Validates installation-owned bundled resources, registers the specialized `req-reset` and `req-references` commands plus bundled prompt-backed commands and agent tools, registers configuration commands, registers the configurable 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, tool-result debug logging, and prompt-orchestration 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, optional debug-log writes, 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-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-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, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-244, REQ-245, REQ-246, REQ-247
+- @satisfies DES-002, REQ-004, REQ-005, REQ-009, REQ-044, 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-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, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-244, REQ-245, REQ-246, REQ-247, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303, REQ-304, REQ-305, REQ-306, REQ-312, REQ-313
 
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
 |---|---|---|---|---|
-|`PiShortcutRegistrar`|iface||161-169|interface PiShortcutRegistrar|
-|`getProjectBase`|fn||177-186|function getProjectBase(cwd: string): string|
-|`getProcessCwdSafe`|fn||193-202|function getProcessCwdSafe(): string|
-|`resolveLiveBootstrapCwd`|fn||210-222|function resolveLiveBootstrapCwd(cwd: string): string|
-|`syncContextCwdMirror`|fn||231-240|function syncContextCwdMirror(ctx: { cwd?: string }, cwd:...|
-|`loadProjectConfig`|fn||249-252|function loadProjectConfig(cwd: string): UseReqConfig|
-|`saveProjectConfig`|fn||262-265|function saveProjectConfig(cwd: string, config: UseReqCon...|
-|`formatProjectConfigPathForMenu`|fn||274-278|function formatProjectConfigPathForMenu(cwd: string): string|
-|`buildTerminalSettingsMenuChoices`|fn||287-298|function buildTerminalSettingsMenuChoices(options:|
-|`ResetConfirmationChange`|iface||304-308|interface ResetConfirmationChange|
-|`formatResetConfirmationValue`|fn||317-319|function formatResetConfirmationValue(previousValue: stri...|
-|`buildResetConfirmationChoices`|fn||329-368|function buildResetConfirmationChoices(|
-|`confirmResetChanges`|fn||380-393|async function confirmResetChanges(|
-|`writePersistedProjectConfigToEditor`|fn||404-411|function writePersistedProjectConfigToEditor(|
-|`buildSearchToolSupportedTagGuidelines`|fn||472-476|function buildSearchToolSupportedTagGuidelines(): string[]|
-|`buildSearchToolSchemaDescription`|fn||484-489|function buildSearchToolSchemaDescription(scope: FindTool...|
-|`buildSearchToolPromptGuidelines`|fn||497-510|function buildSearchToolPromptGuidelines(scope: FindToolS...|
-|`MonolithicToolRenderResult`|type||516||
-|`getMonolithicToolText`|fn||533-536|function getMonolithicToolText(result: MonolithicToolRend...|
-|`getMonolithicToolErrorText`|fn||544-554|function getMonolithicToolErrorText(result: MonolithicToo...|
-|`formatCompactToolArgumentValue`|fn||562-601|function formatCompactToolArgumentValue(value: unknown): ...|
-|`buildCompactToolInvocationText`|fn||609-620|function buildCompactToolInvocationText(args: Record<stri...|
-|`summarizeStructuredToolResult`|fn||630-645|function summarizeStructuredToolResult(|
-|`buildStructuredToolRenderResult`|fn||654-673|function buildStructuredToolRenderResult(toolName: string)|
-|`executeMonolithicTool`|fn||681-687|function executeMonolithicTool(operation: () => ToolResul...|
-|`deliverPromptCommand`|fn||698-716|function deliverPromptCommand(|
-|`shouldIgnoreLatePromptDeliveryFailure`|fn||727-743|function shouldIgnoreLatePromptDeliveryFailure(|
-|`logPromptWorkflowStateChange`|fn||756-775|function logPromptWorkflowStateChange(|
-|`logPromptWorkflowEvent`|fn||791-811|function logPromptWorkflowEvent(|
-|`transitionPromptWorkflowState`|fn||824-837|function transitionPromptWorkflowState(|
-|`resolvePromptCommandDescription`|fn||845-849|function resolvePromptCommandDescription(|
-|`resolveDebugProjectBase`|fn||858-862|function resolveDebugProjectBase(cwd: string, statusContr...|
-|`notifyContextSafely`|fn||873-890|function notifyContextSafely(|
-|`getPiUsereqStartupTools`|fn||899-907|function getPiUsereqStartupTools(pi: ExtensionAPI): ToolI...|
-|`getConfiguredEnabledPiUsereqTools`|fn||915-919|function getConfiguredEnabledPiUsereqTools(config: UseReq...|
-|`applyConfiguredPiUsereqTools`|fn||929-946|function applyConfiguredPiUsereqTools(pi: ExtensionAPI, c...|
-|`handleExtensionStatusEvent`|fn||959-1219|async function handleExtensionStatusEvent(|
-|`registerExtensionStatusHooks`|fn||1235-1254|function registerExtensionStatusHooks(|
-|`setConfiguredPiUsereqTools`|fn||1264-1267|function setConfiguredPiUsereqTools(pi: ExtensionAPI, con...|
-|`getDebugToolToggleNames`|fn||1275-1277|function getDebugToolToggleNames(): PiUsereqStartupToolNa...|
-|`resetDebugConfigToDefaults`|fn||1286-1294|function resetDebugConfigToDefaults(config: UseReqConfig)...|
-|`formatDebugMenuSummary`|fn||1302-1308|function formatDebugMenuSummary(config: UseReqConfig): st...|
-|`buildDebugMenuChoice`|fn||1318-1331|function buildDebugMenuChoice(|
-|`selectDebugLogOnStatus`|fn||1340-1368|async function selectDebugLogOnStatus(|
-|`buildDebugMenuChoices`|fn||1377-1448|function buildDebugMenuChoices(config: UseReqConfig): PiU...|
-|`configureDebugMenu`|fn||1458-1575|async function configureDebugMenu(|
-|`PiNotifyBooleanConfigKey`|type||1581||
-|`PiNotifyEventBooleanConfigKey`|type||1598||
-|`PiNotifyEventId`|type||1607||
-|`PiNotifyEventRowDefinition`|iface||1613-1617|interface PiNotifyEventRowDefinition|
-|`PiNotifyEventMenuDefinition`|iface||1623-1629|interface PiNotifyEventMenuDefinition|
-|`togglePiNotifyFlag`|fn||1638-1641|function togglePiNotifyFlag(config: UseReqConfig, key: Pi...|
-|`resetPiNotifyConfigToDefaults`|fn||1650-1674|function resetPiNotifyConfigToDefaults(config: UseReqConf...|
-|`formatPiNotifyPushoverPriority`|fn||1683-1685|function formatPiNotifyPushoverPriority(priority: PiNotif...|
-|`formatPiNotifyEventMenuSummary`|fn||1762-1770|function formatPiNotifyEventMenuSummary(|
-|`buildPiNotifyEventLauncherChoice`|fn||1780-1790|function buildPiNotifyEventLauncherChoice(|
-|`buildPiNotifyEventMenuChoices`|fn||1800-1815|function buildPiNotifyEventMenuChoices(|
-|`resetPiNotifyEventMenuToDefaults`|fn||1825-1833|function resetPiNotifyEventMenuToDefaults(|
-|`resolvePiNotifyEventLabel`|fn||1843-1850|function resolvePiNotifyEventLabel(|
-|`configurePiNotifyEventMenu`|fn||1861-1921|async function configurePiNotifyEventMenu(|
-|`buildPiNotifyPushoverRows`|fn||1930-1979|function buildPiNotifyPushoverRows(config: UseReqConfig):...|
-|`selectPiNotifyPushoverPriority`|fn||1989-2017|async function selectPiNotifyPushoverPriority(|
-|`buildPiNotifyMenuChoices`|fn||2026-2083|function buildPiNotifyMenuChoices(config: UseReqConfig): ...|
-|`selectPiNotifySoundLevel`|fn||2093-2133|async function selectPiNotifySoundLevel(|
-|`configurePiNotifyMenu`|fn||2143-2409|async function configurePiNotifyMenu(|
-|`registerPiNotifyShortcut`|fn||2424-2444|function registerPiNotifyShortcut(|
-|`registerPromptCommands`|fn||2454-2572|function registerPromptCommands(|
-|`registerAgentTools`|fn||2582-2881|function registerAgentTools(pi: ExtensionAPI): void|
-|`buildPiUsereqToolsMenuChoices`|fn||2899-2924|function buildPiUsereqToolsMenuChoices(pi: ExtensionAPI, ...|
-|`buildPiUsereqToolToggleChoices`|fn||2934-2947|function buildPiUsereqToolToggleChoices(pi: ExtensionAPI,...|
-|`configurePiUsereqToolsMenu`|fn||2958-3053|async function configurePiUsereqToolsMenu(|
-|`getStaticCheckLanguageConfigForMenu`|fn||3062-3067|function getStaticCheckLanguageConfigForMenu(|
-|`countConfiguredStaticCheckLanguages`|fn||3075-3077|function countConfiguredStaticCheckLanguages(config: UseR...|
-|`countEnabledStaticCheckLanguages`|fn||3085-3087|function countEnabledStaticCheckLanguages(config: UseReqC...|
-|`resetStaticCheckConfig`|fn||3096-3098|function resetStaticCheckConfig(config: UseReqConfig): void|
-|`formatStaticCheckLanguagesSummary`|fn||3106-3108|function formatStaticCheckLanguagesSummary(config: UseReq...|
-|`buildStaticCheckMenuChoices`|fn||3117-3148|function buildStaticCheckMenuChoices(config: UseReqConfig...|
-|`buildSupportedStaticCheckLanguageChoices`|fn||3156-3173|function buildSupportedStaticCheckLanguageChoices(config:...|
-|`buildConfiguredStaticCheckLanguageChoices`|fn||3181-3198|function buildConfiguredStaticCheckLanguageChoices(config...|
-|`configureStaticCheckMenu`|fn||3208-3341|async function configureStaticCheckMenu(|
-|`buildPiUsereqMenuChoices`|fn||3351-3440|function buildPiUsereqMenuChoices(|
-|`buildSrcDirMenuChoices`|fn||3449-3467|function buildSrcDirMenuChoices(config: UseReqConfig): Pi...|
-|`buildSrcDirRemovalChoices`|fn||3476-3488|function buildSrcDirRemovalChoices(config: UseReqConfig):...|
-|`configurePiUsereq`|fn||3499-3719|async function configurePiUsereq(|
-|`persistConfigChange`|fn||3510-3515|const persistConfigChange = () =>|
-|`registerConfigCommands`|fn||3729-3739|function registerConfigCommands(|
-|`piUsereqExtension`|fn||3757-3765|export default function piUsereqExtension(pi: ExtensionAP...|
+|`PiShortcutRegistrar`|iface||178-186|interface PiShortcutRegistrar|
+|`getProjectBase`|fn||194-203|function getProjectBase(cwd: string): string|
+|`getProcessCwdSafe`|fn||210-219|function getProcessCwdSafe(): string|
+|`resolveLiveBootstrapCwd`|fn||227-239|function resolveLiveBootstrapCwd(cwd: string): string|
+|`syncContextCwdMirror`|fn||248-257|function syncContextCwdMirror(ctx: { cwd?: string }, cwd:...|
+|`loadProjectConfig`|fn||266-269|function loadProjectConfig(cwd: string): UseReqConfig|
+|`saveProjectConfig`|fn||279-282|function saveProjectConfig(cwd: string, config: UseReqCon...|
+|`formatLocalConfigPathForMenu`|fn||291-295|function formatLocalConfigPathForMenu(cwd: string): string|
+|`formatGlobalConfigPathForMenu`|fn||303-305|function formatGlobalConfigPathForMenu(): string|
+|`buildTerminalSettingsMenuChoices`|fn||314-325|function buildTerminalSettingsMenuChoices(options:|
+|`ResetConfirmationChange`|iface||331-335|interface ResetConfirmationChange|
+|`formatResetConfirmationValue`|fn||344-346|function formatResetConfirmationValue(previousValue: stri...|
+|`buildResetConfirmationChoices`|fn||356-395|function buildResetConfirmationChoices(|
+|`confirmResetChanges`|fn||407-420|async function confirmResetChanges(|
+|`writePersistedConfigToEditor`|fn||429-434|function writePersistedConfigToEditor(|
+|`writePersistedLocalConfigToEditor`|fn||444-450|function writePersistedLocalConfigToEditor(|
+|`writePersistedGlobalConfigToEditor`|fn||459-463|function writePersistedGlobalConfigToEditor(|
+|`buildSearchToolSupportedTagGuidelines`|fn||524-528|function buildSearchToolSupportedTagGuidelines(): string[]|
+|`buildSearchToolSchemaDescription`|fn||536-541|function buildSearchToolSchemaDescription(scope: FindTool...|
+|`buildSearchToolPromptGuidelines`|fn||549-562|function buildSearchToolPromptGuidelines(scope: FindToolS...|
+|`MonolithicToolRenderResult`|type||568||
+|`getMonolithicToolText`|fn||585-588|function getMonolithicToolText(result: MonolithicToolRend...|
+|`getMonolithicToolErrorText`|fn||596-606|function getMonolithicToolErrorText(result: MonolithicToo...|
+|`formatCompactToolArgumentValue`|fn||614-653|function formatCompactToolArgumentValue(value: unknown): ...|
+|`buildCompactToolInvocationText`|fn||661-672|function buildCompactToolInvocationText(args: Record<stri...|
+|`summarizeStructuredToolResult`|fn||682-697|function summarizeStructuredToolResult(|
+|`buildStructuredToolRenderResult`|fn||706-725|function buildStructuredToolRenderResult(toolName: string)|
+|`executeMonolithicTool`|fn||733-739|function executeMonolithicTool(operation: () => ToolResul...|
+|`executeStatusTool`|fn||748-777|function executeStatusTool(operation: () => ToolResult): ...|
+|`deliverPromptCommand`|fn||788-806|function deliverPromptCommand(|
+|`shouldIgnoreLatePromptDeliveryFailure`|fn||817-833|function shouldIgnoreLatePromptDeliveryFailure(|
+|`logPromptWorkflowStateChange`|fn||846-865|function logPromptWorkflowStateChange(|
+|`logPromptWorkflowEvent`|fn||881-901|function logPromptWorkflowEvent(|
+|`transitionPromptWorkflowState`|fn||914-927|function transitionPromptWorkflowState(|
+|`resolvePromptCommandDescription`|fn||935-939|function resolvePromptCommandDescription(|
+|`resolveDebugProjectBase`|fn||948-952|function resolveDebugProjectBase(cwd: string, statusContr...|
+|`notifyContextSafely`|fn||963-980|function notifyContextSafely(|
+|`rejectNonIdleReqCommand`|fn||992-1012|function rejectNonIdleReqCommand(|
+|`getPiUsereqStartupTools`|fn||1021-1029|function getPiUsereqStartupTools(pi: ExtensionAPI): ToolI...|
+|`getConfiguredEnabledPiUsereqTools`|fn||1037-1041|function getConfiguredEnabledPiUsereqTools(config: UseReq...|
+|`applyConfiguredPiUsereqTools`|fn||1051-1068|function applyConfiguredPiUsereqTools(pi: ExtensionAPI, c...|
+|`handleExtensionStatusEvent`|fn||1081-1352|async function handleExtensionStatusEvent(|
+|`registerExtensionStatusHooks`|fn||1368-1387|function registerExtensionStatusHooks(|
+|`setConfiguredPiUsereqTools`|fn||1397-1400|function setConfiguredPiUsereqTools(pi: ExtensionAPI, con...|
+|`getDebugToolToggleNames`|fn||1408-1410|function getDebugToolToggleNames(): PiUsereqStartupToolNa...|
+|`resetDebugConfigToDefaults`|fn||1419-1427|function resetDebugConfigToDefaults(config: UseReqConfig)...|
+|`formatDebugMenuSummary`|fn||1435-1441|function formatDebugMenuSummary(config: UseReqConfig): st...|
+|`buildDebugMenuChoice`|fn||1451-1464|function buildDebugMenuChoice(|
+|`selectDebugLogOnStatus`|fn||1473-1501|async function selectDebugLogOnStatus(|
+|`buildDebugMenuChoices`|fn||1510-1586|function buildDebugMenuChoices(config: UseReqConfig): PiU...|
+|`configureDebugMenu`|fn||1596-1765|async function configureDebugMenu(|
+|`PiNotifyBooleanConfigKey`|type||1771||
+|`PiNotifyEventBooleanConfigKey`|type||1788||
+|`PiNotifyEventId`|type||1797||
+|`PiNotifyEventRowDefinition`|iface||1803-1807|interface PiNotifyEventRowDefinition|
+|`PiNotifyEventMenuDefinition`|iface||1813-1819|interface PiNotifyEventMenuDefinition|
+|`togglePiNotifyFlag`|fn||1828-1831|function togglePiNotifyFlag(config: UseReqConfig, key: Pi...|
+|`resetPiNotifyConfigToDefaults`|fn||1840-1864|function resetPiNotifyConfigToDefaults(config: UseReqConf...|
+|`formatPiNotifyPushoverPriority`|fn||1873-1875|function formatPiNotifyPushoverPriority(priority: PiNotif...|
+|`formatPiNotifyEventMenuSummary`|fn||1959-1967|function formatPiNotifyEventMenuSummary(|
+|`buildPiNotifyEventLauncherChoice`|fn||1977-1987|function buildPiNotifyEventLauncherChoice(|
+|`buildPiNotifyEventMenuChoices`|fn||1997-2013|function buildPiNotifyEventMenuChoices(|
+|`resetPiNotifyEventMenuToDefaults`|fn||2023-2031|function resetPiNotifyEventMenuToDefaults(|
+|`resolvePiNotifyEventLabel`|fn||2041-2048|function resolvePiNotifyEventLabel(|
+|`configurePiNotifyEventMenu`|fn||2059-2135|async function configurePiNotifyEventMenu(|
+|`buildPiNotifyPushoverRows`|fn||2144-2194|function buildPiNotifyPushoverRows(config: UseReqConfig):...|
+|`selectPiNotifyPushoverPriority`|fn||2204-2232|async function selectPiNotifyPushoverPriority(|
+|`buildPiNotifyMenuChoices`|fn||2241-2299|function buildPiNotifyMenuChoices(config: UseReqConfig): ...|
+|`selectPiNotifySoundLevel`|fn||2309-2349|async function selectPiNotifySoundLevel(|
+|`configurePiNotifyMenu`|fn||2359-2645|async function configurePiNotifyMenu(|
+|`registerPiNotifyShortcut`|fn||2660-2683|function registerPiNotifyShortcut(|
+|`resolveReqResetPromptRequest`|fn||2691-2717|function resolveReqResetPromptRequest(|
+|`isWorktreeBacked`|fn||2694-2701|const isWorktreeBacked = (request: PromptCommandExecution...|
+|`registerReqResetCommand`|fn||2727-2781|function registerReqResetCommand(|
+|`registerReqReferencesCommand`|fn||2791-2831|function registerReqReferencesCommand(|
+|`registerPromptCommands`|fn||2841-2957|function registerPromptCommands(|
+|`registerAgentTools`|fn||2967-3266|function registerAgentTools(pi: ExtensionAPI): void|
+|`buildPiUsereqToolsMenuChoices`|fn||3311-3336|function buildPiUsereqToolsMenuChoices(pi: ExtensionAPI, ...|
+|`buildPiUsereqToolToggleChoices`|fn||3346-3360|function buildPiUsereqToolToggleChoices(pi: ExtensionAPI,...|
+|`configurePiUsereqToolsMenu`|fn||3371-3488|async function configurePiUsereqToolsMenu(|
+|`getStaticCheckLanguageConfigForMenu`|fn||3497-3502|function getStaticCheckLanguageConfigForMenu(|
+|`countConfiguredStaticCheckLanguages`|fn||3510-3512|function countConfiguredStaticCheckLanguages(config: UseR...|
+|`countEnabledStaticCheckLanguages`|fn||3520-3522|function countEnabledStaticCheckLanguages(config: UseReqC...|
+|`resetStaticCheckConfig`|fn||3531-3533|function resetStaticCheckConfig(config: UseReqConfig): void|
+|`formatStaticCheckLanguagesSummary`|fn||3541-3543|function formatStaticCheckLanguagesSummary(config: UseReq...|
+|`buildStaticCheckMenuChoices`|fn||3552-3584|function buildStaticCheckMenuChoices(config: UseReqConfig...|
+|`buildSupportedStaticCheckLanguageChoices`|fn||3592-3609|function buildSupportedStaticCheckLanguageChoices(config:...|
+|`buildConfiguredStaticCheckLanguageChoices`|fn||3617-3634|function buildConfiguredStaticCheckLanguageChoices(config...|
+|`configureStaticCheckMenu`|fn||3644-3790|async function configureStaticCheckMenu(|
+|`buildPiUsereqMenuChoices`|fn||3800-3899|function buildPiUsereqMenuChoices(|
+|`buildSrcDirMenuChoices`|fn||3908-3926|function buildSrcDirMenuChoices(config: UseReqConfig): Pi...|
+|`buildSrcDirRemovalChoices`|fn||3935-3947|function buildSrcDirRemovalChoices(config: UseReqConfig):...|
+|`configurePiUsereq`|fn||3958-4211|async function configurePiUsereq(|
+|`persistConfigChange`|fn||3969-3974|const persistConfigChange = () =>|
+|`registerConfigCommands`|fn||4221-4231|function registerConfigCommands(|
+|`piUsereqExtension`|fn||4240-4250|export default function piUsereqExtension(pi: ExtensionAP...|