pi-usereq 0.12.0 → 0.32.0

package/pi-usereq/docs/REFERENCES.md

@@ -581,10 +581,10 @@ import { buildLanguageSpecs } from "./source-analyzer.js";
 
 ---
 
-# config.ts | TypeScript | 780L | 22 symbols | 8 imports | 31 comments
+# config.ts | TypeScript | 1153L | 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
 ```
@@ -600,41 +600,87 @@ import { makeRelativeIfContainsProject } from "./utils.js";
 
 ## Definitions
 
-### iface `export interface StaticCheckEntry` (L54-58)
+### iface `export interface StaticCheckEntry` (L58-62)
 - @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";` (L68)
 - @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` (L74-77)
 - @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` (L83-122)
+- @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` (L128-130)
+- @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` (L136-138)
+- @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` (L144-157)
+- @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` (L163-191)
+- @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` (L308-317)
 - @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(` (L326-335)
 - @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(` (L343-347)
+- @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(` (L355-361)
+- @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>` (L368-373)
+- @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(` (L381-390)
+- @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(` (L399-418)
+- @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>` (L426-432)
 - @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(` (L442-447)
 - @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.
@@ -642,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(` (L457-466)
 - @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.
@@ -650,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"` (L481-483)
 - @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"` (L497-499)
 - @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(` (L508-513)
 - @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.
@@ -672,70 +718,151 @@ 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` (L527-533)
 - @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.
-- @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.
+### fn `export function getProjectConfigPath(projectBase: string): string` (L540-542)
+- @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 {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` (L549-551)
+- @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(` (L560-577)
+- @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 including tool-wrapper command registration 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.
+- @satisfies CTN-019
+
+### fn `function getDefaultGlobalConfig(): UseReqGlobalConfig` (L584-614)
+- @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(` (L623-690)
+- @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 including tool-wrapper command registration, 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` (L699-705)
+- @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, CTN-019, 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[]` (L713-733)
 - @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` (L742-758)
+- @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(` (L768-792)
+- @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(` (L801-818)
+- @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(` (L828-876)
+- @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, tool-wrapper command registration, 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.
+- @satisfies CTN-019
+
+### fn `function loadGlobalConfig(): UseReqGlobalConfig` (L883-924)
+- @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` (L934-941)
+- @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, CTN-019, 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` (L950-978)
+- @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`, while preserving the debug tool-wrapper command flag beside other local debug settings. 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, CTN-019, 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` (L987-1026)
+- @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` (L1035-1038)
+- @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` (L1048-1050)
+- @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 normalizeConfigPaths(projectBase: string, config: UseReqConfig): UseReqConfig` (L710-728)
+### fn `export function saveGlobalConfig(config: UseReqConfig): void` (L1059-1061)
+- @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 saveConfig(projectBase: string, config: UseReqConfig): void` (L1071-1074)
+- @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` (L1083-1101)
 - @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(` (L1111-1153)
 - @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.
@@ -746,33 +873,54 @@ 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||58-62|export interface StaticCheckEntry|
+|`StaticCheckEnabled`|type||68||
+|`StaticCheckLanguageConfig`|iface||74-77|export interface StaticCheckLanguageConfig|
+|`UseReqConfig`|iface||83-122|export interface UseReqConfig|
+|`LocalStaticCheckLanguageConfig`|iface||128-130|interface LocalStaticCheckLanguageConfig|
+|`GlobalStaticCheckLanguageConfig`|iface||136-138|interface GlobalStaticCheckLanguageConfig|
+|`UseReqLocalConfig`|iface||144-157|interface UseReqLocalConfig|
+|`UseReqGlobalConfig`|iface||163-191|interface UseReqGlobalConfig|
+|`cloneStaticCheckEntry`|fn||308-317|function cloneStaticCheckEntry(entry: StaticCheckEntry): ...|
+|`createStaticCheckLanguageConfig`|fn||326-335|export function createStaticCheckLanguageConfig(|
+|`createLocalStaticCheckLanguageConfig`|fn||343-347|function createLocalStaticCheckLanguageConfig(|
+|`createGlobalStaticCheckLanguageConfig`|fn||355-361|function createGlobalStaticCheckLanguageConfig(|
+|`getDefaultGlobalStaticCheckConfig`|fn||368-373|function getDefaultGlobalStaticCheckConfig(): Record<stri...|
+|`getDefaultLocalStaticCheckConfig`|fn||381-390|function getDefaultLocalStaticCheckConfig(|
+|`mergeStaticCheckConfig`|fn||399-418|function mergeStaticCheckConfig(|
+|`getDefaultStaticCheckConfig`|fn||426-432|export function getDefaultStaticCheckConfig(): Record<str...|
+|`normalizeStaticCheckEnabled`|fn||442-447|export function normalizeStaticCheckEnabled(|
+|`getActiveStaticCheckEntries`|fn||457-466|export function getActiveStaticCheckEntries(|
+|`normalizeAutoGitCommit`|fn||481-483|export function normalizeAutoGitCommit(value: unknown): "...|
+|`normalizeGitWorktreeEnabled`|fn||497-499|export function normalizeGitWorktreeEnabled(value: unknow...|
+|`resolveEffectiveGitWorktreeEnabled`|fn||508-513|export function resolveEffectiveGitWorktreeEnabled(|
+|`normalizeGitWorktreePrefix`|fn||527-533|export function normalizeGitWorktreePrefix(value: unknown...|
+|`getProjectConfigPath`|fn||540-542|export function getProjectConfigPath(projectBase: string)...|
+|`getGlobalConfigPath`|fn||549-551|export function getGlobalConfigPath(): string|
+|`getDefaultLocalConfig`|fn||560-577|function getDefaultLocalConfig(|
+|`getDefaultGlobalConfig`|fn||584-614|function getDefaultGlobalConfig(): UseReqGlobalConfig|
+|`mergeConfigScopes`|fn||623-690|function mergeConfigScopes(|
+|`getDefaultConfig`|fn||699-705|export function getDefaultConfig(_projectBase: string): U...|
+|`normalizeStaticCheckEntries`|fn||713-733|function normalizeStaticCheckEntries(value: unknown): Sta...|
+|`readConfigPayload`|fn||742-758|function readConfigPayload(configPath: string): Record<st...|
+|`normalizeLocalStaticCheckConfig`|fn||768-792|function normalizeLocalStaticCheckConfig(|
+|`normalizeGlobalStaticCheckConfig`|fn||801-818|function normalizeGlobalStaticCheckConfig(|
+|`loadLocalConfig`|fn||828-876|function loadLocalConfig(|
+|`loadGlobalConfig`|fn||883-924|function loadGlobalConfig(): UseReqGlobalConfig|
+|`loadConfig`|fn||934-941|export function loadConfig(projectBase: string): UseReqCo...|
+|`buildPersistedLocalConfig`|fn||950-978|function buildPersistedLocalConfig(config: UseReqConfig):...|
+|`buildPersistedGlobalConfig`|fn||987-1026|function buildPersistedGlobalConfig(config: UseReqConfig)...|
+|`writeConfigFile`|fn||1035-1038|function writeConfigFile(configPath: string, payload: obj...|
+|`saveLocalConfig`|fn||1048-1050|export function saveLocalConfig(projectBase: string, conf...|
+|`saveGlobalConfig`|fn||1059-1061|export function saveGlobalConfig(config: UseReqConfig): void|
+|`saveConfig`|fn||1071-1074|export function saveConfig(projectBase: string, config: U...|
+|`normalizeConfigPaths`|fn||1083-1101|export function normalizeConfigPaths(projectBase: string,...|
+|`buildPromptReplacementPaths`|fn||1111-1153|export function buildPromptReplacementPaths(|
 
 
 ---
 
-# debug-runtime.ts | TypeScript | 542L | 26 symbols | 5 imports | 36 comments
+# debug-runtime.ts | TypeScript | 566L | 28 symbols | 5 imports | 39 comments
 > Path: `src/core/debug-runtime.ts`
 - @brief Declares debug inventories, normalizers, and JSON log persistence helpers.
 - @details Centralizes debug-menu selector inventories, config-field normalization, workflow-status gating, and append-only JSON log writing for tool, prompt, and dedicated workflow debug events. Runtime is dominated by JSON serialization plus filesystem I/O during log writes. Side effects include directory creation and file overwrite when debug entries are appended.
@@ -788,84 +936,94 @@ import {
 
 ## Definitions
 
-- type `export type DebugToolName =` (L59)
+- type `export type DebugToolName =` (L66)
 - @brief Represents one valid debug-enabled tool selector.
 - @details Combines extension-owned tool names and supported embedded builtin tool names into one compile-time selector domain. The alias introduces no runtime cost.
-- type `export type DebugPromptName = `req-${PromptCommandName}`;` (L67)
+- type `export type DebugPromptName = `req-${PromptCommandName}`;` (L74)
 - @brief Represents one valid debug-enabled prompt selector.
 - @details Restricts prompt debug toggles to invokable bundled `req-*` slash-command names derived from `PROMPT_COMMAND_NAMES`. The alias introduces no runtime cost.
-- type `export type DebugWorkflowState =` (L85)
+- type `export type DebugWorkflowState =` (L92)
 - @brief Represents one workflow-state value used by debug gating and payloads.
 - @details Extends the documented prompt workflow states with `unknown` for callers that cannot recover a concrete state. The alias is compile-time only and introduces no runtime cost.
-- type `export type DebugStatusChanges = "enable" | "disable";` (L93)
+- type `export type DebugStatusChanges = "enable" | "disable";` (L100)
 - @brief Represents one persisted workflow-transition logging flag.
 - @details Restricts `workflow_state` emission to the documented `enable|disable` domain. The alias is compile-time only and introduces no runtime cost.
-- type `export type DebugWorkflowEvents = "enable" | "disable";` (L99)
+- type `export type DebugWorkflowEvents = "enable" | "disable";` (L106)
 - @brief Represents one persisted dedicated workflow-event logging flag.
 - @details Restricts session-activation, restoration, closure, and shutdown workflow-event emission to the documented `enable|disable` domain. The alias is compile-time only and introduces no runtime cost.
-- type `export type DebugLogOnStatus = "any" | (typeof DEBUG_WORKFLOW_STATES)[number];` (L105)
+- type `export type DebugToolCommandsEnabled = "enable" | "disable";` (L112)
+- @brief Represents one persisted debug-tool command-wrapper flag.
+- @details Restricts debug slash-command wrapper registration to the documented `enable|disable` domain. The alias is compile-time only and introduces no runtime cost.
+- type `export type DebugLogOnStatus = "any" | (typeof DEBUG_WORKFLOW_STATES)[number];` (L118)
 - @brief Represents one persisted workflow-status filter value.
 - @details Restricts debug log filtering to `any` or one explicit documented workflow state. The alias is compile-time only and introduces no runtime cost.
-### iface `export interface DebugLogEntry` (L111-120)
+### iface `export interface DebugLogEntry` (L124-133)
 - @brief Describes one append-only JSON debug log entry.
 - @details Stores a timestamped tool or prompt event with workflow-state context plus optional input, result, and error metadata. The interface is compile-time only and introduces no runtime cost.
 
-### fn `export function normalizeDebugEnabled(value: unknown): "enable" | "disable"` (L153-155)
+### fn `export function normalizeDebugEnabled(value: unknown): "enable" | "disable"` (L166-168)
 - @brief Normalizes one persisted debug enable flag.
 - @details Accepts only the documented `enable|disable` values and falls back to `DEFAULT_DEBUG_ENABLED` for all other payloads. Runtime is O(1). No external state is mutated.
 - @param[in] value {unknown} Candidate persisted debug-enable payload.
 - @return {"enable" | "disable"} Canonical debug-enable value.
 - @satisfies REQ-236
 
-### fn `export function normalizeDebugLogFile(value: unknown): string` (L164-170)
+### fn `export function normalizeDebugLogFile(value: unknown): string` (L177-183)
 - @brief Normalizes one persisted debug log file value.
 - @details Accepts only non-empty strings, trims surrounding whitespace, and falls back to `DEFAULT_DEBUG_LOG_FILE` when the candidate is absent or blank. Runtime is O(n) in path length. No external state is mutated.
 - @param[in] value {unknown} Candidate persisted debug-log file payload.
 - @return {string} Canonical debug-log file value.
 - @satisfies REQ-237
 
-### fn `export function normalizeDebugStatusChanges(value: unknown): DebugStatusChanges` (L179-181)
+### fn `export function normalizeDebugStatusChanges(value: unknown): DebugStatusChanges` (L192-194)
 - @brief Normalizes one persisted workflow-transition logging flag.
 - @details Accepts only the documented `enable|disable` values and falls back to `DEFAULT_DEBUG_STATUS_CHANGES` for all other payloads. Runtime is O(1). No external state is mutated.
 - @param[in] value {unknown} Candidate persisted workflow-transition logging payload.
 - @return {DebugStatusChanges} Canonical workflow-transition logging flag.
 - @satisfies REQ-254
 
-### fn `export function normalizeDebugWorkflowEvents(value: unknown): DebugWorkflowEvents` (L190-192)
+### fn `export function normalizeDebugWorkflowEvents(value: unknown): DebugWorkflowEvents` (L203-205)
 - @brief Normalizes one persisted dedicated workflow-event logging flag.
 - @details Accepts only the documented `enable|disable` values and falls back to `DEFAULT_DEBUG_WORKFLOW_EVENTS` for all other payloads. Runtime is O(1). No external state is mutated.
 - @param[in] value {unknown} Candidate persisted workflow-event logging payload.
 - @return {DebugWorkflowEvents} Canonical workflow-event logging flag.
 - @satisfies REQ-277
 
-### fn `export function normalizeDebugLogOnStatus(value: unknown): DebugLogOnStatus` (L201-208)
+### fn `export function normalizeDebugToolCommandsEnabled(value: unknown): DebugToolCommandsEnabled` (L214-216)
+- @brief Normalizes one persisted debug-tool command-wrapper flag.
+- @details Accepts only the documented `enable|disable` values and falls back to `DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED` for all other payloads. Runtime is O(1). No external state is mutated.
+- @param[in] value {unknown} Candidate persisted debug-tool command-wrapper payload.
+- @return {DebugToolCommandsEnabled} Canonical debug-tool command-wrapper flag.
+- @satisfies CTN-019, REQ-322
+
+### fn `export function normalizeDebugLogOnStatus(value: unknown): DebugLogOnStatus` (L225-232)
 - @brief Normalizes one persisted debug workflow-status filter.
 - @details Accepts only the documented `any` token or one explicit workflow state and falls back to `DEFAULT_DEBUG_LOG_ON_STATUS` for all other payloads. Runtime is O(1). No external state is mutated.
 - @param[in] value {unknown} Candidate persisted debug workflow-status filter.
 - @return {DebugLogOnStatus} Canonical debug workflow-status filter.
 - @satisfies REQ-238
 
-### fn `export function normalizeDebugEnabledTools(value: unknown): DebugToolName[]` (L217-225)
+### fn `export function normalizeDebugEnabledTools(value: unknown): DebugToolName[]` (L241-249)
 - @brief Normalizes one persisted debug-tool selector array.
 - @details Filters to string entries, discards unknown tool names, deduplicates while preserving first-seen order, and returns an empty array for non-array payloads. Runtime is O(n). No external state is mutated.
 - @param[in] value {unknown} Candidate persisted debug-tool selector payload.
 - @return {DebugToolName[]} Deduplicated canonical debug-tool selectors.
 - @satisfies REQ-239, REQ-242
 
-### fn `export function normalizeDebugEnabledPrompts(value: unknown): DebugPromptName[]` (L234-242)
+### fn `export function normalizeDebugEnabledPrompts(value: unknown): DebugPromptName[]` (L258-266)
 - @brief Normalizes one persisted debug-prompt selector array.
 - @details Filters to string entries, discards unknown `req-*` names, deduplicates while preserving first-seen order, and returns an empty array for non-array payloads. Runtime is O(n). No external state is mutated.
 - @param[in] value {unknown} Candidate persisted debug-prompt selector payload.
 - @return {DebugPromptName[]} Deduplicated canonical debug-prompt selectors.
 - @satisfies REQ-239, REQ-243
 
-### fn `export function getDebugPromptName(promptName: PromptCommandName): DebugPromptName` (L250-252)
+### fn `export function getDebugPromptName(promptName: PromptCommandName): DebugPromptName` (L274-276)
 - @brief Resolves the canonical debug prompt selector for one bundled prompt.
 - @details Reuses the shared prompt-command formatter so prompt-runtime and extension hook logging can target the same `DEBUG_ENABLED_PROMPTS` domain as the configuration menu. Runtime is O(n) in prompt-name length. No external state is mutated.
 - @param[in] promptName {PromptCommandName} Canonical bundled prompt name.
 - @return {DebugPromptName} Canonical debug prompt selector.
 
-### fn `export function matchesDebugWorkflowState(` (L262-267)
+### fn `export function matchesDebugWorkflowState(` (L286-291)
 - @brief Tests whether one debug workflow-state filter matches the current state.
 - @details Treats `any` as an unconditional pass-through and otherwise requires `workflowState` to equal the configured explicit workflow state. Runtime is O(1). No external state is mutated.
 - @param[in] logOnStatus {DebugLogOnStatus} Persisted debug workflow-state filter.
@@ -873,7 +1031,7 @@ import {
 - @return {boolean} `true` when the entry should be emitted for the supplied state.
 - @satisfies REQ-247
 
-### fn `export function resolveDebugLogPath(projectBase: string, config: UseReqConfig): string` (L277-282)
+### fn `export function resolveDebugLogPath(projectBase: string, config: UseReqConfig): string` (L301-306)
 - @brief Resolves the absolute debug log file path for one project base.
 - @details Preserves absolute configured paths and otherwise resolves relative values against the original project base so prompt-worktree cleanup cannot discard accumulated debug evidence. Runtime is O(p) in path length. No external state is mutated.
 - @param[in] projectBase {string} Absolute original project base path.
@@ -881,7 +1039,7 @@ import {
 - @return {string} Absolute debug log path.
 - @satisfies REQ-237
 
-### fn `export function shouldLogDebugTool(` (L293-301)
+### fn `export function shouldLogDebugTool(` (L317-325)
 - @brief Tests whether one tool execution should be appended to the debug log.
 - @details Requires global debug enablement, membership in `DEBUG_ENABLED_TOOLS`, and a matching workflow-state filter before any filesystem work occurs. Runtime is O(n) in configured selector count. No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
@@ -890,7 +1048,7 @@ import {
 - @return {boolean} `true` when the tool execution should be logged.
 - @satisfies REQ-242, REQ-246, REQ-247
 
-### fn `export function shouldLogDebugPrompt(` (L312-320)
+### fn `export function shouldLogDebugPrompt(` (L336-344)
 - @brief Tests whether one prompt event should be appended to the debug log.
 - @details Requires global debug enablement, membership in `DEBUG_ENABLED_PROMPTS`, and a matching workflow-state filter before any filesystem work occurs. Runtime is O(n) in configured selector count. No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
@@ -899,7 +1057,7 @@ import {
 - @return {boolean} `true` when the prompt event should be logged.
 - @satisfies REQ-243, REQ-246, REQ-247
 
-### fn `export function shouldLogDebugPromptWorkflowState(` (L331-338)
+### fn `export function shouldLogDebugPromptWorkflowState(` (L355-362)
 - @brief Tests whether one prompt workflow-state transition should be appended to the debug log.
 - @details Requires global debug enablement, prompt-selector membership, explicit `DEBUG_STATUS_CHANGES=enable`, and a matching post-transition workflow-state filter before any filesystem work occurs. Runtime is O(n) in configured selector count. No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
@@ -908,7 +1066,7 @@ import {
 - @return {boolean} `true` when the prompt workflow-state entry should be logged.
 - @satisfies REQ-246, REQ-247, REQ-255
 
-### fn `export function shouldLogDebugPromptWorkflowEvent(` (L349-356)
+### fn `export function shouldLogDebugPromptWorkflowEvent(` (L373-380)
 - @brief Tests whether one dedicated prompt workflow event should be appended to the debug log.
 - @details Requires global debug enablement, prompt-selector membership, explicit `DEBUG_WORKFLOW_EVENTS=enable`, and a matching workflow-state filter before any filesystem work occurs. Runtime is O(n) in configured selector count. No external state is mutated.
 - @param[in] config {UseReqConfig} Effective project configuration.
@@ -917,13 +1075,13 @@ import {
 - @return {boolean} `true` when the dedicated workflow event should be logged.
 - @satisfies REQ-245, REQ-246, REQ-247, REQ-277
 
-### fn `function normalizeDebugValue(value: unknown): unknown` (L364-392)
+### fn `function normalizeDebugValue(value: unknown): unknown` (L388-416)
 - @brief Serializes arbitrary debug payloads into deterministic JSON-compatible values.
 - @details Converts `Error` instances into structured records, elides functions, stringifies bigint values, and falls back to a best-effort string when JSON serialization fails. Runtime is O(n) in payload size. No external state is mutated.
 - @param[in] value {unknown} Arbitrary debug payload.
 - @return {unknown} JSON-compatible debug payload.
 
-### fn `function appendDebugLogEntry(` (L402-427)
+### fn `function appendDebugLogEntry(` (L426-451)
 - @brief Appends one normalized debug log entry to the configured JSON log file.
 - @details Loads the existing JSON array when present, falls back to an empty array for missing or invalid files, appends the normalized entry, and rewrites the full file with a trailing newline. Runtime is dominated by JSON parse plus serialization and filesystem I/O. Side effects include directory creation and file overwrite.
 - @param[in] projectBase {string} Absolute original project base path.
@@ -931,7 +1089,7 @@ import {
 - @param[in] entry {DebugLogEntry} Candidate debug log entry.
 - @return {boolean} `true` when the entry is written successfully; `false` when filesystem writing fails.
 
-### fn `export function logDebugToolExecution(` (L442-464)
+### fn `export function logDebugToolExecution(` (L466-488)
 - @brief Appends one tool-execution debug entry when the current config enables it.
 - @details Applies tool-selector and workflow-state gating before serializing the executed tool input, final result payload, and error flag into the configured JSON log file. Runtime is dominated by JSON serialization plus filesystem I/O when enabled and O(n) in selector count otherwise. Side effects include directory creation and file overwrite only for enabled matching entries.
 - @param[in] projectBase {string} Absolute original project base path.
@@ -944,7 +1102,7 @@ import {
 - @return {boolean} `true` when the tool entry is written; otherwise `false`.
 - @satisfies REQ-244, REQ-246, REQ-247
 
-### fn `export function logDebugPromptEvent(` (L480-503)
+### fn `export function logDebugPromptEvent(` (L504-527)
 - @brief Appends one prompt debug entry when the current config enables it.
 - @details Applies prompt-selector and workflow-state gating before serializing the supplied action payload into the configured JSON log file. Runtime is dominated by JSON serialization plus filesystem I/O when enabled and O(n) in selector count otherwise. Side effects include directory creation and file overwrite only for enabled matching entries.
 - @param[in] projectBase {string} Absolute original project base path.
@@ -958,7 +1116,7 @@ import {
 - @return {boolean} `true` when the prompt entry is written; otherwise `false`.
 - @satisfies REQ-245, REQ-246, REQ-247
 
-### fn `export function logDebugPromptWorkflowEvent(` (L519-542)
+### fn `export function logDebugPromptWorkflowEvent(` (L543-566)
 - @brief Appends one dedicated prompt workflow debug entry when the current config enables it.
 - @details Applies prompt-selector, workflow-event-flag, and workflow-state gating before serializing session-activation, restoration, closure, or shutdown workflow payloads into the configured JSON log file. Runtime is dominated by JSON serialization plus filesystem I/O when enabled and O(n) in selector count otherwise. Side effects include directory creation and file overwrite only for enabled matching entries.
 - @param[in] projectBase {string} Absolute original project base path.
@@ -975,32 +1133,34 @@ import {
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
 |---|---|---|---|---|
-|`DebugToolName`|type||59||
-|`DebugPromptName`|type||67||
-|`DebugWorkflowState`|type||85||
-|`DebugStatusChanges`|type||93||
-|`DebugWorkflowEvents`|type||99||
-|`DebugLogOnStatus`|type||105||
-|`DebugLogEntry`|iface||111-120|export interface DebugLogEntry|
-|`normalizeDebugEnabled`|fn||153-155|export function normalizeDebugEnabled(value: unknown): "e...|
-|`normalizeDebugLogFile`|fn||164-170|export function normalizeDebugLogFile(value: unknown): st...|
-|`normalizeDebugStatusChanges`|fn||179-181|export function normalizeDebugStatusChanges(value: unknow...|
-|`normalizeDebugWorkflowEvents`|fn||190-192|export function normalizeDebugWorkflowEvents(value: unkno...|
-|`normalizeDebugLogOnStatus`|fn||201-208|export function normalizeDebugLogOnStatus(value: unknown)...|
-|`normalizeDebugEnabledTools`|fn||217-225|export function normalizeDebugEnabledTools(value: unknown...|
-|`normalizeDebugEnabledPrompts`|fn||234-242|export function normalizeDebugEnabledPrompts(value: unkno...|
-|`getDebugPromptName`|fn||250-252|export function getDebugPromptName(promptName: PromptComm...|
-|`matchesDebugWorkflowState`|fn||262-267|export function matchesDebugWorkflowState(|
-|`resolveDebugLogPath`|fn||277-282|export function resolveDebugLogPath(projectBase: string, ...|
-|`shouldLogDebugTool`|fn||293-301|export function shouldLogDebugTool(|
-|`shouldLogDebugPrompt`|fn||312-320|export function shouldLogDebugPrompt(|
-|`shouldLogDebugPromptWorkflowState`|fn||331-338|export function shouldLogDebugPromptWorkflowState(|
-|`shouldLogDebugPromptWorkflowEvent`|fn||349-356|export function shouldLogDebugPromptWorkflowEvent(|
-|`normalizeDebugValue`|fn||364-392|function normalizeDebugValue(value: unknown): unknown|
-|`appendDebugLogEntry`|fn||402-427|function appendDebugLogEntry(|
-|`logDebugToolExecution`|fn||442-464|export function logDebugToolExecution(|
-|`logDebugPromptEvent`|fn||480-503|export function logDebugPromptEvent(|
-|`logDebugPromptWorkflowEvent`|fn||519-542|export function logDebugPromptWorkflowEvent(|
+|`DebugToolName`|type||66||
+|`DebugPromptName`|type||74||
+|`DebugWorkflowState`|type||92||
+|`DebugStatusChanges`|type||100||
+|`DebugWorkflowEvents`|type||106||
+|`DebugToolCommandsEnabled`|type||112||
+|`DebugLogOnStatus`|type||118||
+|`DebugLogEntry`|iface||124-133|export interface DebugLogEntry|
+|`normalizeDebugEnabled`|fn||166-168|export function normalizeDebugEnabled(value: unknown): "e...|
+|`normalizeDebugLogFile`|fn||177-183|export function normalizeDebugLogFile(value: unknown): st...|
+|`normalizeDebugStatusChanges`|fn||192-194|export function normalizeDebugStatusChanges(value: unknow...|
+|`normalizeDebugWorkflowEvents`|fn||203-205|export function normalizeDebugWorkflowEvents(value: unkno...|
+|`normalizeDebugToolCommandsEnabled`|fn||214-216|export function normalizeDebugToolCommandsEnabled(value: ...|
+|`normalizeDebugLogOnStatus`|fn||225-232|export function normalizeDebugLogOnStatus(value: unknown)...|
+|`normalizeDebugEnabledTools`|fn||241-249|export function normalizeDebugEnabledTools(value: unknown...|
+|`normalizeDebugEnabledPrompts`|fn||258-266|export function normalizeDebugEnabledPrompts(value: unkno...|
+|`getDebugPromptName`|fn||274-276|export function getDebugPromptName(promptName: PromptComm...|
+|`matchesDebugWorkflowState`|fn||286-291|export function matchesDebugWorkflowState(|
+|`resolveDebugLogPath`|fn||301-306|export function resolveDebugLogPath(projectBase: string, ...|
+|`shouldLogDebugTool`|fn||317-325|export function shouldLogDebugTool(|
+|`shouldLogDebugPrompt`|fn||336-344|export function shouldLogDebugPrompt(|
+|`shouldLogDebugPromptWorkflowState`|fn||355-362|export function shouldLogDebugPromptWorkflowState(|
+|`shouldLogDebugPromptWorkflowEvent`|fn||373-380|export function shouldLogDebugPromptWorkflowEvent(|
+|`normalizeDebugValue`|fn||388-416|function normalizeDebugValue(value: unknown): unknown|
+|`appendDebugLogEntry`|fn||426-451|function appendDebugLogEntry(|
+|`logDebugToolExecution`|fn||466-488|export function logDebugToolExecution(|
+|`logDebugPromptEvent`|fn||504-527|export function logDebugPromptEvent(|
+|`logDebugPromptWorkflowEvent`|fn||543-566|export function logDebugPromptWorkflowEvent(|
 
 
 ---
@@ -1433,14 +1593,14 @@ mutates `controller.config`.
 
 ### 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 `.pi-usereq.json`. Runtime is O(1). No external state is mutated.
+- @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 `.pi-usereq.json`, 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.
+- @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.
@@ -1924,7 +2084,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.
@@ -1940,122 +2100,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.
@@ -2064,7 +2229,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.
@@ -2073,28 +2238,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(|
 
 
 ---
@@ -4537,7 +4703,7 @@ import path from "node:path";
 
 ---
 
-# index.ts | TypeScript | 4203L | 93 symbols | 27 imports | 99 comments
+# index.ts | TypeScript | 4407L | 102 symbols | 27 imports | 107 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.
@@ -4575,78 +4741,120 @@ import { makeRelativeIfContainsProject, shellSplit } from "./core/utils.js";
 
 ## Definitions
 
-### iface `interface PiShortcutRegistrar` (L177-185)
+### iface `interface PiShortcutRegistrar` (L180-188)
 - @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` (L193-202)
+### fn `function getProjectBase(cwd: string): string` (L196-205)
 - @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` (L209-218)
+### fn `function getProcessCwdSafe(): string` (L212-221)
 - @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` (L226-238)
+### fn `function resolveLiveBootstrapCwd(cwd: string): string` (L229-241)
 - @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` (L247-256)
+### fn `function syncContextCwdMirror(ctx: { cwd?: string }, cwd: string): void` (L250-259)
 - @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` (L265-268)
+### fn `function loadProjectConfig(cwd: string): UseReqConfig` (L268-271)
 - @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` (L278-281)
-- @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.
+- type `type DebugToolCommandExecuteResult = ReturnType<typeof buildMonolithicToolExecuteResult>;` (L277)
+- @brief Describes the execute-result surface reused by debug tool wrapper commands.
+- @details Narrows debug slash-command handlers to the same monolithic content-plus-execution wrapper returned by agent tools so editor output and notifications can reuse shared extraction helpers. The alias is compile-time only and introduces no runtime cost.
+### fn `function shouldRegisterDebugToolCommands(cwd: string): boolean` (L286-292)
+- @brief Tests whether debug tool wrapper commands should be registered for one runtime cwd.
+- @details Loads the effective project configuration for the supplied cwd and returns `true` only when `DEBUG_TOOL_COMMANDS_ENABLED` resolves to `enable`. Malformed or unreadable config payloads degrade to `false` so extension activation never aborts while deciding whether to register optional debug commands. Runtime is dominated by config I/O. Side effects are limited to filesystem reads.
+- @param[in] cwd {string} Candidate runtime working directory.
+- @return {boolean} `true` when debug tool wrapper commands should be registered.
+- @satisfies REQ-323
+
+### fn `function writeDebugToolCommandResultToEditor(` (L303-317)
+- @brief Writes one debug tool-wrapper result into the editor and emits a status notification.
+- @details Extracts the primary monolithic content text from the wrapped tool result, forwards that exact text to the editor, and emits an informational or error notification keyed by the tool exit code. Runtime is O(n) in output length. Side effects include editor-text mutation and UI notifications.
+- @param[in] ctx {ExtensionCommandContext} Active command context.
+- @param[in] commandName {string} Invoked debug slash-command name without the leading `/`.
+- @param[in] result {DebugToolCommandExecuteResult} Wrapped tool execution result.
+- @return {void} No return value.
+- @satisfies REQ-324
+
+### fn `function executeDebugToolCommand(` (L329-347)
+- @brief Executes one config-gated debug tool wrapper slash command.
+- @details Resolves a live cwd for the invoking command context, refreshes runtime path state, loads the effective project configuration, rejects execution when debug tool wrapper commands are disabled, and otherwise writes the selected wrapped tool output into the editor. Runtime is dominated by the delegated tool runner. Side effects include runtime-path bootstrap, filesystem reads, optional tool side effects, editor-text mutation, and UI notifications.
+- @param[in] ctx {ExtensionCommandContext} Active command context.
+- @param[in] commandName {string} Invoked debug slash-command name without the leading `/`.
+- @param[in] operation {(projectBase: string, config: UseReqConfig) => DebugToolCommandExecuteResult} Wrapped tool executor.
+- @return {void} No return value.
+- @throws {ReqError} Throws when debug tool wrapper commands are disabled for the active project.
+- @satisfies REQ-324, REQ-325
+
+### fn `function registerDebugToolCommands(pi: ExtensionAPI): void` (L356-390)
+- @brief Registers config-gated debug slash-command wrappers for selected built-in analysis tools.
+- @details Registers `debug-compress`, `debug-references`, `debug-static-check`, and `debug-tokens` as extension commands that reuse the same runner paths as the corresponding agent tools and write the resulting monolithic text into the editor instead of the LLM content channel. Re-registering the same commands is idempotent because pi keeps the latest same-extension command definition per name. Runtime is O(1) for registration; handler cost depends on the selected runner. Side effects include command registration.
+- @param[in] pi {ExtensionAPI} Active extension API instance.
+- @return {void} No return value.
+- @satisfies DES-015, REQ-323, REQ-324, REQ-325
+
+### fn `function saveProjectConfig(cwd: string, config: UseReqConfig): void` (L400-403)
+- @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` (L290-294)
-- @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` (L412-416)
+- @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:` (L303-314)
+### fn `function formatGlobalConfigPathForMenu(): string` (L424-426)
+- @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:` (L435-446)
 - @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` (L320-324)
+### iface `interface ResetConfirmationChange` (L452-456)
 - @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` (L333-335)
+### fn `function formatResetConfirmationValue(previousValue: string, nextValue: string): string` (L465-467)
 - @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(` (L345-384)
+### fn `function buildResetConfirmationChoices(` (L477-516)
 - @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.
@@ -4654,7 +4862,7 @@ cost.
 - @param[in] abortDescription {string} Description for the abort action.
 - @return {PiUsereqSettingsMenuChoice[]} Reset-confirmation submenu choices.
 
-### fn `async function confirmResetChanges(` (L396-409)
+### fn `async function confirmResetChanges(` (L528-541)
 - @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.
@@ -4664,60 +4872,73 @@ cost.
 - @param[in] abortDescription {string} Description for the abort action.
 - @return {Promise<boolean>} `true` when the reset is explicitly approved.
 
-### fn `function writePersistedProjectConfigToEditor(` (L420-427)
-- @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(` (L550-555)
+- @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(` (L565-571)
+- @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[]` (L488-492)
+### fn `function writePersistedGlobalConfigToEditor(` (L580-584)
+- @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[]` (L645-649)
 - @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` (L500-505)
+### fn `function buildSearchToolSchemaDescription(scope: FindToolScope): string` (L657-662)
 - @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[]` (L513-526)
+### fn `function buildSearchToolPromptGuidelines(scope: FindToolScope): string[]` (L670-683)
 - @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 = {` (L532)
+- type `type MonolithicToolRenderResult = {` (L689)
 - @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` (L549-552)
+### fn `function getMonolithicToolText(result: MonolithicToolRenderResult): string` (L706-709)
 - @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` (L560-570)
+### fn `function getMonolithicToolErrorText(result: MonolithicToolRenderResult): string | undefined` (L717-727)
 - @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` (L578-617)
+### fn `function formatCompactToolArgumentValue(value: unknown): string | undefined` (L735-774)
 - @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` (L625-636)
+### fn `function buildCompactToolInvocationText(args: Record<string, unknown> | undefined): string` (L782-793)
 - @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(` (L646-661)
+### fn `function summarizeStructuredToolResult(` (L803-818)
 - @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.
@@ -4725,27 +4946,27 @@ cost.
 - @param[in] args {Record<string, unknown> | undefined} Current tool call arguments.
 - @return {string} Compact single-line summary.
 
-### fn `function buildStructuredToolRenderResult(toolName: string)` (L670-689)
+### fn `function buildStructuredToolRenderResult(toolName: string)` (L827-846)
 - @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>` (L697-703)
+### fn `function executeMonolithicTool(operation: () => ToolResult): ReturnType<typeof buildMonolithicToolExecuteResult>` (L854-860)
 - @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 executeStatusTool(operation: () => ToolResult): ReturnType<typeof buildMonolithicToolExecuteResult>` (L712-741)
+### fn `function executeStatusTool(operation: () => ToolResult): ReturnType<typeof buildMonolithicToolExecuteResult>` (L869-898)
 - @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(` (L752-770)
+### fn `function deliverPromptCommand(` (L909-927)
 - @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.
@@ -4754,7 +4975,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(` (L781-797)
+### fn `function shouldIgnoreLatePromptDeliveryFailure(` (L938-954)
 - @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.
@@ -4763,7 +4984,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(` (L810-829)
+### fn `function logPromptWorkflowStateChange(` (L967-986)
 - @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.
@@ -4774,7 +4995,7 @@ cost.
 - @return {void} No return value.
 - @satisfies REQ-245, REQ-246, REQ-247
 
-### fn `function logPromptWorkflowEvent(` (L845-865)
+### fn `function logPromptWorkflowEvent(` (L1002-1022)
 - @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.
@@ -4788,7 +5009,7 @@ cost.
 - @return {void} No return value.
 - @satisfies REQ-245, REQ-246, REQ-247, REQ-277
 
-### fn `function transitionPromptWorkflowState(` (L878-891)
+### fn `function transitionPromptWorkflowState(` (L1035-1048)
 - @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.
@@ -4799,20 +5020,20 @@ cost.
 - @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
 - @return {void} No return value.
 
-### fn `function resolvePromptCommandDescription(` (L899-903)
+### fn `function resolvePromptCommandDescription(` (L1056-1060)
 - @brief Resolves the runtime slash-command description for one bundled prompt.
 - @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` (L912-916)
+### fn `function resolveDebugProjectBase(cwd: string, statusController: PiUsereqStatusController): string` (L1069-1073)
 - @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(` (L927-944)
+### fn `function notifyContextSafely(` (L1084-1101)
 - @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.
@@ -4821,7 +5042,7 @@ cost.
 - @return {boolean} `true` when the notification was delivered and `false` when the context was already stale.
 - @satisfies REQ-280
 
-### fn `function rejectNonIdleReqCommand(` (L956-976)
+### fn `function rejectNonIdleReqCommand(` (L1113-1133)
 - @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.
@@ -4831,20 +5052,20 @@ cost.
 - @throws {ReqError} Always throws because non-`idle` req commands are rejected.
 - @satisfies REQ-224
 
-### fn `function getPiUsereqStartupTools(pi: ExtensionAPI): ToolInfo[]` (L985-993)
+### fn `function getPiUsereqStartupTools(pi: ExtensionAPI): ToolInfo[]` (L1142-1150)
 - @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[]` (L1001-1005)
+### fn `function getConfiguredEnabledPiUsereqTools(config: UseReqConfig): string[]` (L1158-1162)
 - @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` (L1015-1032)
+### fn `function applyConfiguredPiUsereqTools(pi: ExtensionAPI, config: UseReqConfig): void` (L1172-1189)
 - @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.
@@ -4852,7 +5073,7 @@ cost.
 - @return {void} No return value.
 - @satisfies REQ-009, REQ-064
 
-### fn `async function handleExtensionStatusEvent(` (L1045-1316)
+### fn `async function handleExtensionStatusEvent(` (L1202-1473)
 - @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()`, 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.
@@ -4863,7 +5084,7 @@ cost.
 - @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, REQ-291, REQ-292
 
-### fn `function registerExtensionStatusHooks(` (L1332-1351)
+### fn `function registerExtensionStatusHooks(` (L1489-1508)
 - @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
@@ -4877,7 +5098,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` (L1361-1364)
+### fn `function setConfiguredPiUsereqTools(pi: ExtensionAPI, config: UseReqConfig, enabledTools: string[]): void` (L1518-1521)
 - @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.
@@ -4885,26 +5106,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[]` (L1372-1374)
+### fn `function getDebugToolToggleNames(): PiUsereqStartupToolName[]` (L1529-1531)
 - @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` (L1383-1391)
+### fn `function resetDebugConfigToDefaults(config: UseReqConfig): void` (L1540-1549)
 - @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`.
+- @details Resets global debug enablement, log path, tool-wrapper command registration, 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
+- @satisfies REQ-236, REQ-237, REQ-238, REQ-239, REQ-195, REQ-277, REQ-322
 
-### fn `function formatDebugMenuSummary(config: UseReqConfig): string` (L1399-1405)
+### fn `function formatDebugMenuSummary(config: UseReqConfig): string` (L1557-1563)
 - @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(` (L1415-1428)
+### fn `function buildDebugMenuChoice(` (L1573-1586)
 - @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.
@@ -4912,67 +5133,70 @@ registered hook count. Side effects include hook registration.
 - @return {PiUsereqSettingsMenuChoice} Styled debug-menu row.
 - @satisfies REQ-241
 
-### fn `async function selectDebugLogOnStatus(` (L1437-1465)
+### fn `async function selectDebugLogOnStatus(` (L1595-1623)
 - @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[]` (L1474-1550)
+### fn `function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L1632-1718)
 - @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.
+- @details Serializes global debug controls plus tool-wrapper command registration, 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
+- @satisfies REQ-240, REQ-241, REQ-242, REQ-243, REQ-193, REQ-277, REQ-321, REQ-322
 
-### fn `async function configureDebugMenu(` (L1560-1729)
+### fn `async function configureDebugMenu(` (L1729-1919)
 - @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.
+- @details Lets the user toggle global debug enablement, tool-wrapper command registration, debug file and workflow filters, dedicated workflow-event logging, per-tool selectors, and per-prompt selectors while preserving row focus across re-renders. Runtime depends on user interaction count. Side effects include UI updates, config mutation, and optional debug command registration.
+- @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 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
+- @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, REQ-321, REQ-322, REQ-323
+
+### fn `const updateDebugToolCommandsEnabled = (nextValue: unknown): void =>` (L1735-1742)
 
-- type `type PiNotifyBooleanConfigKey =` (L1735)
+- type `type PiNotifyBooleanConfigKey =` (L1925)
 - @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<` (L1752)
+- type `type PiNotifyEventBooleanConfigKey = Exclude<` (L1942)
 - @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";` (L1761)
+- type `type PiNotifyEventId = "completed" | "interrupted" | "failed";` (L1951)
 - @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` (L1767-1771)
+### iface `interface PiNotifyEventRowDefinition` (L1957-1961)
 - @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` (L1777-1783)
+### iface `interface PiNotifyEventMenuDefinition` (L1967-1973)
 - @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` (L1792-1795)
+### fn `function togglePiNotifyFlag(config: UseReqConfig, key: PiNotifyBooleanConfigKey): boolean` (L1982-1985)
 - @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` (L1804-1828)
+### fn `function resetPiNotifyConfigToDefaults(config: UseReqConfig): void` (L1994-2018)
 - @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` (L1837-1839)
+### fn `function formatPiNotifyPushoverPriority(priority: PiNotifyPushoverPriority): string` (L2027-2029)
 - @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(` (L1923-1931)
+### fn `function formatPiNotifyEventMenuSummary(` (L2113-2121)
 - @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.
@@ -4980,7 +5204,7 @@ registered hook count. Side effects include hook registration.
 - @return {string} Compact enabled-toggle summary.
 - @satisfies REQ-198
 
-### fn `function buildPiNotifyEventLauncherChoice(` (L1941-1951)
+### fn `function buildPiNotifyEventLauncherChoice(` (L2131-2141)
 - @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.
@@ -4988,7 +5212,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(` (L1961-1977)
+### fn `function buildPiNotifyEventMenuChoices(` (L2151-2167)
 - @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.
@@ -4996,7 +5220,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(` (L1987-1995)
+### fn `function resetPiNotifyEventMenuToDefaults(` (L2177-2185)
 - @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.
@@ -5004,7 +5228,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(` (L2005-2012)
+### fn `function resolvePiNotifyEventLabel(` (L2195-2202)
 - @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.
@@ -5012,7 +5236,7 @@ registered hook count. Side effects include hook registration.
 - @return {string} Human-readable event label.
 - @satisfies REQ-188, REQ-198
 
-### fn `async function configurePiNotifyEventMenu(` (L2023-2099)
+### fn `async function configurePiNotifyEventMenu(` (L2213-2289)
 - @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.
@@ -5021,14 +5245,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[]` (L2108-2158)
+### fn `function buildPiNotifyPushoverRows(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L2298-2348)
 - @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, 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(` (L2168-2196)
+### fn `async function selectPiNotifyPushoverPriority(` (L2358-2386)
 - @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.
@@ -5036,14 +5260,14 @@ 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[]` (L2205-2263)
+### fn `function buildPiNotifyMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L2395-2453)
 - @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, 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, REQ-289
 
-### fn `async function selectPiNotifySoundLevel(` (L2273-2313)
+### fn `async function selectPiNotifySoundLevel(` (L2463-2503)
 - @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.
@@ -5051,20 +5275,20 @@ registered hook count. Side effects include hook registration.
 - @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(` (L2323-2609)
+### fn `async function configurePiNotifyMenu(` (L2513-2799)
 - @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, persists boot-sound changes 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.
+- @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, REQ-288, REQ-289
 
-### fn `function registerPiNotifyShortcut(` (L2624-2647)
+### fn `function registerPiNotifyShortcut(` (L2814-2837)
 - @brief Registers the configurable notification-sound shortcut when supported.
-- @details Loads the current project config, registers one raw pi shortcut when
+- @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 `.pi-usereq.json` unchanged, refreshes the
-status bar, and emits one info notification. Runtime is O(1) for registration
+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.
@@ -5072,15 +5296,15 @@ registration and status updates.
 - @return {void} No return value.
 - @satisfies REQ-134, REQ-180, REQ-286, REQ-287
 
-### fn `function resolveReqResetPromptRequest(` (L2655-2681)
+### fn `function resolveReqResetPromptRequest(` (L2845-2871)
 - @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 =>` (L2658-2665)
+### fn `const isWorktreeBacked = (request: PromptCommandExecutionPlan | undefined): request is PromptCommandExecutionPlan =>` (L2848-2855)
 
-### fn `function registerReqResetCommand(` (L2691-2745)
+### fn `function registerReqResetCommand(` (L2881-2935)
 - @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.
@@ -5088,7 +5312,7 @@ registration and status updates.
 - @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(` (L2755-2795)
+### fn `function registerReqReferencesCommand(` (L2945-2985)
 - @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.
@@ -5096,7 +5320,7 @@ registration and status updates.
 - @return {void} No return value.
 - @satisfies REQ-200, REQ-221, REQ-224, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303
 
-### fn `function registerPromptCommands(` (L2805-2921)
+### fn `function registerPromptCommands(` (L2995-3111)
 - @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.
@@ -5104,14 +5328,14 @@ registration and status updates.
 - @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` (L2931-3230)
+### fn `function registerAgentTools(pi: ExtensionAPI): void` (L3121-3420)
 - @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, REQ-293, REQ-294, REQ-295, REQ-296, REQ-297
 
-### fn `function buildPiUsereqToolsMenuChoices(pi: ExtensionAPI, config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3275-3300)
+### fn `function buildPiUsereqToolsMenuChoices(pi: ExtensionAPI, config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3465-3490)
 - @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.
@@ -5119,7 +5343,7 @@ registration and status 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[]` (L3310-3324)
+### fn `function buildPiUsereqToolToggleChoices(pi: ExtensionAPI, config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3500-3514)
 - @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.
@@ -5127,108 +5351,108 @@ registration and status 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(` (L3335-3452)
+### fn `async function configurePiUsereqToolsMenu(` (L3525-3642)
 - @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(` (L3461-3466)
+### fn `function getStaticCheckLanguageConfigForMenu(` (L3651-3656)
 - @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` (L3474-3476)
+### fn `function countConfiguredStaticCheckLanguages(config: UseReqConfig): number` (L3664-3666)
 - @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` (L3484-3486)
+### fn `function countEnabledStaticCheckLanguages(config: UseReqConfig): number` (L3674-3676)
 - @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` (L3495-3497)
+### fn `function resetStaticCheckConfig(config: UseReqConfig): void` (L3685-3687)
 - @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` (L3505-3507)
+### fn `function formatStaticCheckLanguagesSummary(config: UseReqConfig): string` (L3695-3697)
 - @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[]` (L3516-3548)
+### fn `function buildStaticCheckMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3706-3738)
 - @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[]` (L3556-3573)
+### fn `function buildSupportedStaticCheckLanguageChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3746-3763)
 - @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[]` (L3581-3598)
+### fn `function buildConfiguredStaticCheckLanguageChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L3771-3788)
 - @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(` (L3608-3754)
+### fn `async function configureStaticCheckMenu(` (L3798-3944)
 - @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(` (L3764-3856)
+### fn `function buildPiUsereqMenuChoices(` (L3954-4053)
 - @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[]` (L3865-3883)
+### fn `function buildSrcDirMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L4062-4080)
 - @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[]` (L3892-3904)
+### fn `function buildSrcDirRemovalChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[]` (L4089-4101)
 - @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(` (L3915-4164)
+### fn `async function configurePiUsereq(` (L4112-4365)
 - @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 = () =>` (L3926-3931)
+### fn `const persistConfigChange = () =>` (L4123-4128)
 
-### fn `function registerConfigCommands(` (L4174-4184)
+### fn `function registerConfigCommands(` (L4375-4385)
 - @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.
@@ -5236,107 +5460,116 @@ registration and status updates.
 - @return {void} No return value.
 - @satisfies REQ-006, REQ-031
 
-### fn `export default function piUsereqExtension(pi: ExtensionAPI): void` (L4193-4203)
+### fn `export default function piUsereqExtension(pi: ExtensionAPI): void` (L4394-4407)
 - @brief Registers the complete pi-usereq extension.
-- @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.
+- @details Validates installation-owned bundled resources, registers the specialized `req-reset` and `req-references` commands plus bundled prompt-backed commands and agent tools, conditionally registers config-gated debug tool wrapper commands when the current project enables them, 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, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303, REQ-304, REQ-305, REQ-306, REQ-312, REQ-313
+- @satisfies DES-002, DES-015, 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, REQ-323, REQ-324, REQ-325
 
 ## Symbol Index
 |Symbol|Kind|Vis|Lines|Sig|
 |---|---|---|---|---|
-|`PiShortcutRegistrar`|iface||177-185|interface PiShortcutRegistrar|
-|`getProjectBase`|fn||193-202|function getProjectBase(cwd: string): string|
-|`getProcessCwdSafe`|fn||209-218|function getProcessCwdSafe(): string|
-|`resolveLiveBootstrapCwd`|fn||226-238|function resolveLiveBootstrapCwd(cwd: string): string|
-|`syncContextCwdMirror`|fn||247-256|function syncContextCwdMirror(ctx: { cwd?: string }, cwd:...|
-|`loadProjectConfig`|fn||265-268|function loadProjectConfig(cwd: string): UseReqConfig|
-|`saveProjectConfig`|fn||278-281|function saveProjectConfig(cwd: string, config: UseReqCon...|
-|`formatProjectConfigPathForMenu`|fn||290-294|function formatProjectConfigPathForMenu(cwd: string): string|
-|`buildTerminalSettingsMenuChoices`|fn||303-314|function buildTerminalSettingsMenuChoices(options:|
-|`ResetConfirmationChange`|iface||320-324|interface ResetConfirmationChange|
-|`formatResetConfirmationValue`|fn||333-335|function formatResetConfirmationValue(previousValue: stri...|
-|`buildResetConfirmationChoices`|fn||345-384|function buildResetConfirmationChoices(|
-|`confirmResetChanges`|fn||396-409|async function confirmResetChanges(|
-|`writePersistedProjectConfigToEditor`|fn||420-427|function writePersistedProjectConfigToEditor(|
-|`buildSearchToolSupportedTagGuidelines`|fn||488-492|function buildSearchToolSupportedTagGuidelines(): string[]|
-|`buildSearchToolSchemaDescription`|fn||500-505|function buildSearchToolSchemaDescription(scope: FindTool...|
-|`buildSearchToolPromptGuidelines`|fn||513-526|function buildSearchToolPromptGuidelines(scope: FindToolS...|
-|`MonolithicToolRenderResult`|type||532||
-|`getMonolithicToolText`|fn||549-552|function getMonolithicToolText(result: MonolithicToolRend...|
-|`getMonolithicToolErrorText`|fn||560-570|function getMonolithicToolErrorText(result: MonolithicToo...|
-|`formatCompactToolArgumentValue`|fn||578-617|function formatCompactToolArgumentValue(value: unknown): ...|
-|`buildCompactToolInvocationText`|fn||625-636|function buildCompactToolInvocationText(args: Record<stri...|
-|`summarizeStructuredToolResult`|fn||646-661|function summarizeStructuredToolResult(|
-|`buildStructuredToolRenderResult`|fn||670-689|function buildStructuredToolRenderResult(toolName: string)|
-|`executeMonolithicTool`|fn||697-703|function executeMonolithicTool(operation: () => ToolResul...|
-|`executeStatusTool`|fn||712-741|function executeStatusTool(operation: () => ToolResult): ...|
-|`deliverPromptCommand`|fn||752-770|function deliverPromptCommand(|
-|`shouldIgnoreLatePromptDeliveryFailure`|fn||781-797|function shouldIgnoreLatePromptDeliveryFailure(|
-|`logPromptWorkflowStateChange`|fn||810-829|function logPromptWorkflowStateChange(|
-|`logPromptWorkflowEvent`|fn||845-865|function logPromptWorkflowEvent(|
-|`transitionPromptWorkflowState`|fn||878-891|function transitionPromptWorkflowState(|
-|`resolvePromptCommandDescription`|fn||899-903|function resolvePromptCommandDescription(|
-|`resolveDebugProjectBase`|fn||912-916|function resolveDebugProjectBase(cwd: string, statusContr...|
-|`notifyContextSafely`|fn||927-944|function notifyContextSafely(|
-|`rejectNonIdleReqCommand`|fn||956-976|function rejectNonIdleReqCommand(|
-|`getPiUsereqStartupTools`|fn||985-993|function getPiUsereqStartupTools(pi: ExtensionAPI): ToolI...|
-|`getConfiguredEnabledPiUsereqTools`|fn||1001-1005|function getConfiguredEnabledPiUsereqTools(config: UseReq...|
-|`applyConfiguredPiUsereqTools`|fn||1015-1032|function applyConfiguredPiUsereqTools(pi: ExtensionAPI, c...|
-|`handleExtensionStatusEvent`|fn||1045-1316|async function handleExtensionStatusEvent(|
-|`registerExtensionStatusHooks`|fn||1332-1351|function registerExtensionStatusHooks(|
-|`setConfiguredPiUsereqTools`|fn||1361-1364|function setConfiguredPiUsereqTools(pi: ExtensionAPI, con...|
-|`getDebugToolToggleNames`|fn||1372-1374|function getDebugToolToggleNames(): PiUsereqStartupToolNa...|
-|`resetDebugConfigToDefaults`|fn||1383-1391|function resetDebugConfigToDefaults(config: UseReqConfig)...|
-|`formatDebugMenuSummary`|fn||1399-1405|function formatDebugMenuSummary(config: UseReqConfig): st...|
-|`buildDebugMenuChoice`|fn||1415-1428|function buildDebugMenuChoice(|
-|`selectDebugLogOnStatus`|fn||1437-1465|async function selectDebugLogOnStatus(|
-|`buildDebugMenuChoices`|fn||1474-1550|function buildDebugMenuChoices(config: UseReqConfig): PiU...|
-|`configureDebugMenu`|fn||1560-1729|async function configureDebugMenu(|
-|`PiNotifyBooleanConfigKey`|type||1735||
-|`PiNotifyEventBooleanConfigKey`|type||1752||
-|`PiNotifyEventId`|type||1761||
-|`PiNotifyEventRowDefinition`|iface||1767-1771|interface PiNotifyEventRowDefinition|
-|`PiNotifyEventMenuDefinition`|iface||1777-1783|interface PiNotifyEventMenuDefinition|
-|`togglePiNotifyFlag`|fn||1792-1795|function togglePiNotifyFlag(config: UseReqConfig, key: Pi...|
-|`resetPiNotifyConfigToDefaults`|fn||1804-1828|function resetPiNotifyConfigToDefaults(config: UseReqConf...|
-|`formatPiNotifyPushoverPriority`|fn||1837-1839|function formatPiNotifyPushoverPriority(priority: PiNotif...|
-|`formatPiNotifyEventMenuSummary`|fn||1923-1931|function formatPiNotifyEventMenuSummary(|
-|`buildPiNotifyEventLauncherChoice`|fn||1941-1951|function buildPiNotifyEventLauncherChoice(|
-|`buildPiNotifyEventMenuChoices`|fn||1961-1977|function buildPiNotifyEventMenuChoices(|
-|`resetPiNotifyEventMenuToDefaults`|fn||1987-1995|function resetPiNotifyEventMenuToDefaults(|
-|`resolvePiNotifyEventLabel`|fn||2005-2012|function resolvePiNotifyEventLabel(|
-|`configurePiNotifyEventMenu`|fn||2023-2099|async function configurePiNotifyEventMenu(|
-|`buildPiNotifyPushoverRows`|fn||2108-2158|function buildPiNotifyPushoverRows(config: UseReqConfig):...|
-|`selectPiNotifyPushoverPriority`|fn||2168-2196|async function selectPiNotifyPushoverPriority(|
-|`buildPiNotifyMenuChoices`|fn||2205-2263|function buildPiNotifyMenuChoices(config: UseReqConfig): ...|
-|`selectPiNotifySoundLevel`|fn||2273-2313|async function selectPiNotifySoundLevel(|
-|`configurePiNotifyMenu`|fn||2323-2609|async function configurePiNotifyMenu(|
-|`registerPiNotifyShortcut`|fn||2624-2647|function registerPiNotifyShortcut(|
-|`resolveReqResetPromptRequest`|fn||2655-2681|function resolveReqResetPromptRequest(|
-|`isWorktreeBacked`|fn||2658-2665|const isWorktreeBacked = (request: PromptCommandExecution...|
-|`registerReqResetCommand`|fn||2691-2745|function registerReqResetCommand(|
-|`registerReqReferencesCommand`|fn||2755-2795|function registerReqReferencesCommand(|
-|`registerPromptCommands`|fn||2805-2921|function registerPromptCommands(|
-|`registerAgentTools`|fn||2931-3230|function registerAgentTools(pi: ExtensionAPI): void|
-|`buildPiUsereqToolsMenuChoices`|fn||3275-3300|function buildPiUsereqToolsMenuChoices(pi: ExtensionAPI, ...|
-|`buildPiUsereqToolToggleChoices`|fn||3310-3324|function buildPiUsereqToolToggleChoices(pi: ExtensionAPI,...|
-|`configurePiUsereqToolsMenu`|fn||3335-3452|async function configurePiUsereqToolsMenu(|
-|`getStaticCheckLanguageConfigForMenu`|fn||3461-3466|function getStaticCheckLanguageConfigForMenu(|
-|`countConfiguredStaticCheckLanguages`|fn||3474-3476|function countConfiguredStaticCheckLanguages(config: UseR...|
-|`countEnabledStaticCheckLanguages`|fn||3484-3486|function countEnabledStaticCheckLanguages(config: UseReqC...|
-|`resetStaticCheckConfig`|fn||3495-3497|function resetStaticCheckConfig(config: UseReqConfig): void|
-|`formatStaticCheckLanguagesSummary`|fn||3505-3507|function formatStaticCheckLanguagesSummary(config: UseReq...|
-|`buildStaticCheckMenuChoices`|fn||3516-3548|function buildStaticCheckMenuChoices(config: UseReqConfig...|
-|`buildSupportedStaticCheckLanguageChoices`|fn||3556-3573|function buildSupportedStaticCheckLanguageChoices(config:...|
-|`buildConfiguredStaticCheckLanguageChoices`|fn||3581-3598|function buildConfiguredStaticCheckLanguageChoices(config...|
-|`configureStaticCheckMenu`|fn||3608-3754|async function configureStaticCheckMenu(|
-|`buildPiUsereqMenuChoices`|fn||3764-3856|function buildPiUsereqMenuChoices(|
-|`buildSrcDirMenuChoices`|fn||3865-3883|function buildSrcDirMenuChoices(config: UseReqConfig): Pi...|
-|`buildSrcDirRemovalChoices`|fn||3892-3904|function buildSrcDirRemovalChoices(config: UseReqConfig):...|
-|`configurePiUsereq`|fn||3915-4164|async function configurePiUsereq(|
-|`persistConfigChange`|fn||3926-3931|const persistConfigChange = () =>|
-|`registerConfigCommands`|fn||4174-4184|function registerConfigCommands(|
-|`piUsereqExtension`|fn||4193-4203|export default function piUsereqExtension(pi: ExtensionAP...|
+|`PiShortcutRegistrar`|iface||180-188|interface PiShortcutRegistrar|
+|`getProjectBase`|fn||196-205|function getProjectBase(cwd: string): string|
+|`getProcessCwdSafe`|fn||212-221|function getProcessCwdSafe(): string|
+|`resolveLiveBootstrapCwd`|fn||229-241|function resolveLiveBootstrapCwd(cwd: string): string|
+|`syncContextCwdMirror`|fn||250-259|function syncContextCwdMirror(ctx: { cwd?: string }, cwd:...|
+|`loadProjectConfig`|fn||268-271|function loadProjectConfig(cwd: string): UseReqConfig|
+|`DebugToolCommandExecuteResult`|type||277||
+|`shouldRegisterDebugToolCommands`|fn||286-292|function shouldRegisterDebugToolCommands(cwd: string): bo...|
+|`writeDebugToolCommandResultToEditor`|fn||303-317|function writeDebugToolCommandResultToEditor(|
+|`executeDebugToolCommand`|fn||329-347|function executeDebugToolCommand(|
+|`registerDebugToolCommands`|fn||356-390|function registerDebugToolCommands(pi: ExtensionAPI): void|
+|`saveProjectConfig`|fn||400-403|function saveProjectConfig(cwd: string, config: UseReqCon...|
+|`formatLocalConfigPathForMenu`|fn||412-416|function formatLocalConfigPathForMenu(cwd: string): string|
+|`formatGlobalConfigPathForMenu`|fn||424-426|function formatGlobalConfigPathForMenu(): string|
+|`buildTerminalSettingsMenuChoices`|fn||435-446|function buildTerminalSettingsMenuChoices(options:|
+|`ResetConfirmationChange`|iface||452-456|interface ResetConfirmationChange|
+|`formatResetConfirmationValue`|fn||465-467|function formatResetConfirmationValue(previousValue: stri...|
+|`buildResetConfirmationChoices`|fn||477-516|function buildResetConfirmationChoices(|
+|`confirmResetChanges`|fn||528-541|async function confirmResetChanges(|
+|`writePersistedConfigToEditor`|fn||550-555|function writePersistedConfigToEditor(|
+|`writePersistedLocalConfigToEditor`|fn||565-571|function writePersistedLocalConfigToEditor(|
+|`writePersistedGlobalConfigToEditor`|fn||580-584|function writePersistedGlobalConfigToEditor(|
+|`buildSearchToolSupportedTagGuidelines`|fn||645-649|function buildSearchToolSupportedTagGuidelines(): string[]|
+|`buildSearchToolSchemaDescription`|fn||657-662|function buildSearchToolSchemaDescription(scope: FindTool...|
+|`buildSearchToolPromptGuidelines`|fn||670-683|function buildSearchToolPromptGuidelines(scope: FindToolS...|
+|`MonolithicToolRenderResult`|type||689||
+|`getMonolithicToolText`|fn||706-709|function getMonolithicToolText(result: MonolithicToolRend...|
+|`getMonolithicToolErrorText`|fn||717-727|function getMonolithicToolErrorText(result: MonolithicToo...|
+|`formatCompactToolArgumentValue`|fn||735-774|function formatCompactToolArgumentValue(value: unknown): ...|
+|`buildCompactToolInvocationText`|fn||782-793|function buildCompactToolInvocationText(args: Record<stri...|
+|`summarizeStructuredToolResult`|fn||803-818|function summarizeStructuredToolResult(|
+|`buildStructuredToolRenderResult`|fn||827-846|function buildStructuredToolRenderResult(toolName: string)|
+|`executeMonolithicTool`|fn||854-860|function executeMonolithicTool(operation: () => ToolResul...|
+|`executeStatusTool`|fn||869-898|function executeStatusTool(operation: () => ToolResult): ...|
+|`deliverPromptCommand`|fn||909-927|function deliverPromptCommand(|
+|`shouldIgnoreLatePromptDeliveryFailure`|fn||938-954|function shouldIgnoreLatePromptDeliveryFailure(|
+|`logPromptWorkflowStateChange`|fn||967-986|function logPromptWorkflowStateChange(|
+|`logPromptWorkflowEvent`|fn||1002-1022|function logPromptWorkflowEvent(|
+|`transitionPromptWorkflowState`|fn||1035-1048|function transitionPromptWorkflowState(|
+|`resolvePromptCommandDescription`|fn||1056-1060|function resolvePromptCommandDescription(|
+|`resolveDebugProjectBase`|fn||1069-1073|function resolveDebugProjectBase(cwd: string, statusContr...|
+|`notifyContextSafely`|fn||1084-1101|function notifyContextSafely(|
+|`rejectNonIdleReqCommand`|fn||1113-1133|function rejectNonIdleReqCommand(|
+|`getPiUsereqStartupTools`|fn||1142-1150|function getPiUsereqStartupTools(pi: ExtensionAPI): ToolI...|
+|`getConfiguredEnabledPiUsereqTools`|fn||1158-1162|function getConfiguredEnabledPiUsereqTools(config: UseReq...|
+|`applyConfiguredPiUsereqTools`|fn||1172-1189|function applyConfiguredPiUsereqTools(pi: ExtensionAPI, c...|
+|`handleExtensionStatusEvent`|fn||1202-1473|async function handleExtensionStatusEvent(|
+|`registerExtensionStatusHooks`|fn||1489-1508|function registerExtensionStatusHooks(|
+|`setConfiguredPiUsereqTools`|fn||1518-1521|function setConfiguredPiUsereqTools(pi: ExtensionAPI, con...|
+|`getDebugToolToggleNames`|fn||1529-1531|function getDebugToolToggleNames(): PiUsereqStartupToolNa...|
+|`resetDebugConfigToDefaults`|fn||1540-1549|function resetDebugConfigToDefaults(config: UseReqConfig)...|
+|`formatDebugMenuSummary`|fn||1557-1563|function formatDebugMenuSummary(config: UseReqConfig): st...|
+|`buildDebugMenuChoice`|fn||1573-1586|function buildDebugMenuChoice(|
+|`selectDebugLogOnStatus`|fn||1595-1623|async function selectDebugLogOnStatus(|
+|`buildDebugMenuChoices`|fn||1632-1718|function buildDebugMenuChoices(config: UseReqConfig): PiU...|
+|`configureDebugMenu`|fn||1729-1919|async function configureDebugMenu(|
+|`updateDebugToolCommandsEnabled`|fn||1735-1742|const updateDebugToolCommandsEnabled = (nextValue: unknow...|
+|`PiNotifyBooleanConfigKey`|type||1925||
+|`PiNotifyEventBooleanConfigKey`|type||1942||
+|`PiNotifyEventId`|type||1951||
+|`PiNotifyEventRowDefinition`|iface||1957-1961|interface PiNotifyEventRowDefinition|
+|`PiNotifyEventMenuDefinition`|iface||1967-1973|interface PiNotifyEventMenuDefinition|
+|`togglePiNotifyFlag`|fn||1982-1985|function togglePiNotifyFlag(config: UseReqConfig, key: Pi...|
+|`resetPiNotifyConfigToDefaults`|fn||1994-2018|function resetPiNotifyConfigToDefaults(config: UseReqConf...|
+|`formatPiNotifyPushoverPriority`|fn||2027-2029|function formatPiNotifyPushoverPriority(priority: PiNotif...|
+|`formatPiNotifyEventMenuSummary`|fn||2113-2121|function formatPiNotifyEventMenuSummary(|
+|`buildPiNotifyEventLauncherChoice`|fn||2131-2141|function buildPiNotifyEventLauncherChoice(|
+|`buildPiNotifyEventMenuChoices`|fn||2151-2167|function buildPiNotifyEventMenuChoices(|
+|`resetPiNotifyEventMenuToDefaults`|fn||2177-2185|function resetPiNotifyEventMenuToDefaults(|
+|`resolvePiNotifyEventLabel`|fn||2195-2202|function resolvePiNotifyEventLabel(|
+|`configurePiNotifyEventMenu`|fn||2213-2289|async function configurePiNotifyEventMenu(|
+|`buildPiNotifyPushoverRows`|fn||2298-2348|function buildPiNotifyPushoverRows(config: UseReqConfig):...|
+|`selectPiNotifyPushoverPriority`|fn||2358-2386|async function selectPiNotifyPushoverPriority(|
+|`buildPiNotifyMenuChoices`|fn||2395-2453|function buildPiNotifyMenuChoices(config: UseReqConfig): ...|
+|`selectPiNotifySoundLevel`|fn||2463-2503|async function selectPiNotifySoundLevel(|
+|`configurePiNotifyMenu`|fn||2513-2799|async function configurePiNotifyMenu(|
+|`registerPiNotifyShortcut`|fn||2814-2837|function registerPiNotifyShortcut(|
+|`resolveReqResetPromptRequest`|fn||2845-2871|function resolveReqResetPromptRequest(|
+|`isWorktreeBacked`|fn||2848-2855|const isWorktreeBacked = (request: PromptCommandExecution...|
+|`registerReqResetCommand`|fn||2881-2935|function registerReqResetCommand(|
+|`registerReqReferencesCommand`|fn||2945-2985|function registerReqReferencesCommand(|
+|`registerPromptCommands`|fn||2995-3111|function registerPromptCommands(|
+|`registerAgentTools`|fn||3121-3420|function registerAgentTools(pi: ExtensionAPI): void|
+|`buildPiUsereqToolsMenuChoices`|fn||3465-3490|function buildPiUsereqToolsMenuChoices(pi: ExtensionAPI, ...|
+|`buildPiUsereqToolToggleChoices`|fn||3500-3514|function buildPiUsereqToolToggleChoices(pi: ExtensionAPI,...|
+|`configurePiUsereqToolsMenu`|fn||3525-3642|async function configurePiUsereqToolsMenu(|
+|`getStaticCheckLanguageConfigForMenu`|fn||3651-3656|function getStaticCheckLanguageConfigForMenu(|
+|`countConfiguredStaticCheckLanguages`|fn||3664-3666|function countConfiguredStaticCheckLanguages(config: UseR...|
+|`countEnabledStaticCheckLanguages`|fn||3674-3676|function countEnabledStaticCheckLanguages(config: UseReqC...|
+|`resetStaticCheckConfig`|fn||3685-3687|function resetStaticCheckConfig(config: UseReqConfig): void|
+|`formatStaticCheckLanguagesSummary`|fn||3695-3697|function formatStaticCheckLanguagesSummary(config: UseReq...|
+|`buildStaticCheckMenuChoices`|fn||3706-3738|function buildStaticCheckMenuChoices(config: UseReqConfig...|
+|`buildSupportedStaticCheckLanguageChoices`|fn||3746-3763|function buildSupportedStaticCheckLanguageChoices(config:...|
+|`buildConfiguredStaticCheckLanguageChoices`|fn||3771-3788|function buildConfiguredStaticCheckLanguageChoices(config...|
+|`configureStaticCheckMenu`|fn||3798-3944|async function configureStaticCheckMenu(|
+|`buildPiUsereqMenuChoices`|fn||3954-4053|function buildPiUsereqMenuChoices(|
+|`buildSrcDirMenuChoices`|fn||4062-4080|function buildSrcDirMenuChoices(config: UseReqConfig): Pi...|
+|`buildSrcDirRemovalChoices`|fn||4089-4101|function buildSrcDirRemovalChoices(config: UseReqConfig):...|
+|`configurePiUsereq`|fn||4112-4365|async function configurePiUsereq(|
+|`persistConfigChange`|fn||4123-4128|const persistConfigChange = () =>|
+|`registerConfigCommands`|fn||4375-4385|function registerConfigCommands(|
+|`piUsereqExtension`|fn||4394-4407|export default function piUsereqExtension(pi: ExtensionAP...|