pi-usereq 0.4.0

package/req/docs/WORKFLOW.md

@@ -0,0 +1,1059 @@
+## Execution Units Index
+- ID: `PROC:main`
+  - Type: Process
+  - Role: Standalone `req` CLI dispatcher.
+  - Entrypoints:
+    - `main(...)` [`src/cli.ts`]
+  - Parent Process: none
+  - Threads: no explicit threads detected
+- ID: `PROC:req-debug`
+  - Type: Process
+  - Role: Bash wrapper dispatcher for standalone extension-debug inspection, session replay, prompt replay, tool replay, and raw harness passthrough.
+  - Entrypoints:
+    - `main(...)` [`scripts/pi-usereq-debug.sh`]
+  - Parent Process: none
+  - Threads: no explicit threads detected
+- ID: `PROC:tool-args-to-params`
+  - Type: Process
+  - Role: Tool-argument normalization helper that converts wrapper `--args` text into debug-harness `--params` JSON.
+  - Entrypoints:
+    - `main(...)` [`scripts/tool-args-to-params.ts`]
+  - Parent Process: `PROC:req-debug`
+  - Threads: no explicit threads detected
+- ID: `PROC:debug-ext`
+  - Type: Process
+  - Role: Standalone extension debug-harness dispatcher for offline registration inspection, handler replay, and SDK parity smoke execution.
+  - Entrypoints:
+    - `main(...)` [`scripts/debug-extension.ts`]
+  - Parent Process: none
+  - Threads: no explicit threads detected
+- ID: `PROC:pi-host`
+  - Type: Process
+  - Role: pi extension host callback surface for commands, tools, shortcuts, session initialization, and interactive configuration.
+  - Entrypoints:
+    - `piUsereqExtension(...)` [`src/index.ts`]
+    - `configurePiUsereq(...)` [`src/index.ts`]
+  - Parent Process: none
+  - Threads: no explicit threads detected
+- ID: `PROC:gh-release-check`
+  - Type: Process
+  - Role: GitHub Actions release-gate runner that validates the workflow tag trigger ancestry against `origin/master` before downstream release work.
+  - Entrypoints:
+    - `check-branch(...)` [`.github/workflows/release-npm.yml`]
+  - Parent Process: none
+  - Threads: no explicit threads detected
+- ID: `PROC:gh-release-build`
+  - Type: Process
+  - Role: GitHub Actions release runner that publishes the npm package, builds changelog text, and creates the GitHub Release after branch gating succeeds.
+  - Entrypoints:
+    - `build-release(...)` [`.github/workflows/release-npm.yml`]
+  - Parent Process: none
+  - Threads: no explicit threads detected
+
+## Execution Units
+### `PROC:main`
+- Entrypoints:
+  - `main(...)`: CLI runtime root [`src/cli.ts`]
+- Lifecycle/trigger:
+  - Start trigger: Node executes `src/cli.ts` as a one-shot command.
+  - Stop trigger: returns numeric exit code after one dispatch path or caught `ReqError`.
+  - Looping model: single-pass argument parse followed by single branch dispatch.
+  - Threads: no explicit threads detected.
+- Internal Call-Trace Tree:
+  - `main(...)`: parse argv, normalize config, dispatch selected runner, serialize result [`src/cli.ts`]
+    - `parseArgs(...)`: map argv tokens into a structured command selection [`src/cli.ts`]
+      - `takeUntilOption(...)`: collect positional operands until next option token [`src/cli.ts`]
+    - `applyEnableStaticCheckSpecs(...)`: merge repeatable CLI static-check enable specs before command dispatch [`src/cli.ts`]
+      - `loadMutableProjectConfig(...)`: load project config without intermediate persistence [`src/cli.ts`]
+        - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
+        - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+          - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+          - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+            - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+        - `isInsideGitRepo(...)`: probe git repository membership [`src/core/tool-runner.ts`]
+          - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
+        - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
+          - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
+      - `buildStaticCheckEntryIdentity(...)`: normalize entry duplicate identity [`src/core/static-check.ts`]
+      - `parseEnableStaticCheck(...)`: parse one static-check enable specification [`src/core/static-check.ts`]
+      - `validateStaticCheckEntry(...)`: validate command-backed entry before config write [`src/core/static-check.ts`]
+        - `findExecutable(...)`: resolve executable on PATH or explicit path [`src/core/static-check.ts`]
+          - `isExecutableFile(...)`: verify executable access bits [`src/core/static-check.ts`]
+      - `saveConfig(...)`: persist merged config JSON [`src/core/config.ts`]
+        - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+    - `loadAndRepairConfig(...)`: persist normalized config when `--here` or `--base` is active and no CLI static-check mutation is requested [`src/core/tool-runner.ts`]
+      - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
+      - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+        - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+        - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+          - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+      - `isInsideGitRepo(...)`: probe git repository membership [`src/core/tool-runner.ts`]
+        - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
+      - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
+        - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
+      - `saveConfig(...)`: persist normalized config JSON [`src/core/config.ts`]
+        - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+    - `loadConfig(...)`: load effective config for dispatch when no CLI static-check mutation is requested [`src/core/config.ts`]
+      - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+      - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+        - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+    - `runFilesTokens(...)`: branch `--files-tokens`; count explicit-file token, size, and structure metrics [`src/core/tool-runner.ts`]
+      - `countFilesMetrics(...)`: read files and extract token, character, byte, line, heading, and optional Doxygen facts [`src/core/token-counter.ts`]
+        - `buildCountFileMetricsResult(...)`: assemble direct-access per-file metrics and metadata [`src/core/token-counter.ts`]
+          - `TokenCounter.countTokens(...)`: encode content and count tokens [`src/core/token-counter.ts`]
+          - `TokenCounter.countChars(...)`: count characters [`src/core/token-counter.ts`]
+          - `countLines(...)`: count logical lines [`src/core/token-counter.ts`]
+          - `inferLanguageName(...)`: infer agent-oriented language labels [`src/core/token-counter.ts`]
+          - `extractPrimaryHeadingText(...)`: extract the first markdown heading when present [`src/core/token-counter.ts`]
+          - `extractLeadingDoxygenFields(...)`: extract file-level Doxygen fields when present [`src/core/token-counter.ts`]
+            - `parseDoxygenComment(...)`: parse normalized Doxygen fields [`src/core/doxygen-parser.ts`]
+      - `formatPackSummary(...)`: render aggregate summary [`src/core/token-counter.ts`]
+    - `runFilesReferences(...)`: branch `--files-references`; emit structured explicit-file references JSON [`src/core/tool-runner.ts`]
+      - `buildReferenceToolPayload(...)`: analyze requested files into the agent-oriented references payload [`src/core/reference-payload.ts`]
+        - `canonicalizeReferencePath(...)`: normalize request and file paths against the caller base directory [`src/core/reference-payload.ts`]
+        - `analyzeReferenceFile(...)`: analyze one processable file into structured imports, symbols, and comments [`src/core/reference-payload.ts`]
+          - `detectLanguage(...)`: map extension to language key [`src/core/compress.ts`]
+          - `SourceAnalyzer.analyze(...)`: parse source elements [`src/core/source-analyzer.ts`]
+            - `inStringContext(...)`: suppress comment parsing inside strings [`src/core/source-analyzer.ts`]
+            - `findComment(...)`: detect valid single-line comment boundary [`src/core/source-analyzer.ts`]
+            - `findBlockEnd(...)`: compute construct end line [`src/core/source-analyzer.ts`]
+          - `SourceAnalyzer.enrich(...)`: derive signatures, hierarchy, visibility, inheritance, body annotations, and Doxygen bindings [`src/core/source-analyzer.ts`]
+            - `cleanNames(...)`: normalize matched symbol names [`src/core/source-analyzer.ts`]
+            - `extractSignatures(...)`: derive single-line signatures [`src/core/source-analyzer.ts`]
+            - `detectHierarchy(...)`: assign parent-child relationships [`src/core/source-analyzer.ts`]
+            - `extractVisibility(...)`: annotate visibility [`src/core/source-analyzer.ts`]
+              - `parseVisibility(...)`: language-specific visibility classifier [`src/core/source-analyzer.ts`]
+            - `extractInheritance(...)`: annotate inheritance [`src/core/source-analyzer.ts`]
+              - `parseInheritance(...)`: language-specific inheritance parser [`src/core/source-analyzer.ts`]
+            - `extractBodyAnnotations(...)`: capture body comments and exit points [`src/core/source-analyzer.ts`]
+              - `inStringContext(...)`: suppress comment parsing inside strings [`src/core/source-analyzer.ts`]
+              - `findComment(...)`: detect valid single-line comment boundary [`src/core/source-analyzer.ts`]
+              - `cleanCommentLine(...)`: normalize comment payload [`src/core/source-analyzer.ts`]
+            - `extractDoxygenFields(...)`: bind documentation comments to definitions [`src/core/source-analyzer.ts`]
+              - `isPostfixDoxygenComment(...)`: detect postfix documentation markers [`src/core/source-analyzer.ts`]
+              - `parseDoxygenComment(...)`: parse Doxygen tag/value map [`src/core/doxygen-parser.ts`]
+                - `stripCommentDelimiters(...)`: remove language comment wrappers [`src/core/doxygen-parser.ts`]
+                - `normalizeWhitespace(...)`: canonicalize tag body whitespace [`src/core/doxygen-parser.ts`]
+          - `buildCommentMaps(...)`: associate comments with definitions and file descriptions [`src/core/reference-payload.ts`]
+          - `collectFileLevelDoxygenFields(...)`: extract file-level Doxygen fields [`src/core/source-analyzer.ts`]
+            - `parseDoxygenComment(...)`: parse Doxygen tag/value map [`src/core/doxygen-parser.ts`]
+          - `collectElementDoxygenFields(...)`: merge direct and near-body Doxygen fields [`src/core/source-analyzer.ts`]
+            - `parseDoxygenComment(...)`: parse Doxygen tag/value map [`src/core/doxygen-parser.ts`]
+          - `structureDoxygenFields(...)`: normalize Doxygen fields into tag-specific JSON arrays and objects [`src/core/doxygen-parser.ts`]
+          - `countDoxygenFieldValues(...)`: derive aggregate Doxygen counts [`src/core/doxygen-parser.ts`]
+          - `resolveParentElement(...)`: link nested symbols to enclosing definitions [`src/core/reference-payload.ts`]
+          - `buildCommentEntry(...)`: serialize normalized comment text and line ranges [`src/core/reference-payload.ts`]
+        - `buildRepositoryTree(...)`: materialize the repository directory tree as structured JSON [`src/core/reference-payload.ts`]
+      - `buildReferenceToolExecutionStderr(...)`: serialize skipped and analysis-error entries into stderr text [`src/core/reference-payload.ts`]
+    - `runFilesCompress(...)`: branch `--files-compress`; compress explicit files [`src/core/tool-runner.ts`]
+      - `compressFiles(...)`: compress each file into markdown blocks [`src/core/compress-files.ts`]
+        - `detectLanguage(...)`: map extension to language key [`src/core/compress.ts`]
+        - `compressFileDetailed(...)`: compress one file into structured lines and rendered text [`src/core/compress.ts`]
+          - `detectLanguage(...)`: map extension to language key [`src/core/compress.ts`]
+          - `compressSourceDetailed(...)`: strip comments and blank lines into structured line records [`src/core/compress.ts`]
+            - `getSpecs(...)`: memoize parser specs [`src/core/compress.ts`]
+              - `buildLanguageSpecs(...)`: build multi-language parser specs [`src/core/source-analyzer.ts`]
+                - `re(...)`: compile regex fragments [`src/core/source-analyzer.ts`]
+            - `countLogicalLines(...)`: count original source lines [`src/core/compress.ts`]
+            - `isInString(...)`: suppress inline comment stripping inside strings [`src/core/compress.ts`]
+            - `removeInlineComment(...)`: remove single-line comment suffixes [`src/core/compress.ts`]
+            - `buildCompressedLineEntry(...)`: normalize one retained line into structured output [`src/core/compress.ts`]
+            - `formatCompressedSourceText(...)`: render compressed output text [`src/core/compress.ts`]
+        - `formatOutputPath(...)`: normalize emitted file path [`src/core/compress-files.ts`]
+    - `runFilesFind(...)`: branch `--files-find`; extract named constructs from explicit files [`src/core/tool-runner.ts`]
+      - `findConstructsInFiles(...)`: select constructs by tag and regex [`src/core/find-constructs.ts`]
+        - `parseTagFilter(...)`: parse tag filter set [`src/core/find-constructs.ts`]
+        - `detectLanguage(...)`: map extension to language key [`src/core/compress.ts`]
+        - `languageSupportsTags(...)`: reject unsupported tag/language combinations [`src/core/find-constructs.ts`]
+        - `SourceAnalyzer.analyze(...)`: parse source elements [`src/core/source-analyzer.ts`]
+          - `inStringContext(...)`: suppress comment parsing inside strings [`src/core/source-analyzer.ts`]
+          - `findComment(...)`: detect valid single-line comment boundary [`src/core/source-analyzer.ts`]
+          - `findBlockEnd(...)`: compute construct end line [`src/core/source-analyzer.ts`]
+        - `SourceAnalyzer.enrich(...)`: derive signatures, hierarchy, visibility, inheritance, body annotations, and Doxygen bindings [`src/core/source-analyzer.ts`]
+          - `cleanNames(...)`: normalize matched symbol names [`src/core/source-analyzer.ts`]
+          - `extractSignatures(...)`: derive single-line signatures [`src/core/source-analyzer.ts`]
+          - `detectHierarchy(...)`: assign parent-child relationships [`src/core/source-analyzer.ts`]
+          - `extractVisibility(...)`: annotate visibility [`src/core/source-analyzer.ts`]
+            - `parseVisibility(...)`: language-specific visibility classifier [`src/core/source-analyzer.ts`]
+          - `extractInheritance(...)`: annotate inheritance [`src/core/source-analyzer.ts`]
+            - `parseInheritance(...)`: language-specific inheritance parser [`src/core/source-analyzer.ts`]
+          - `extractBodyAnnotations(...)`: capture body comments and exit points [`src/core/source-analyzer.ts`]
+            - `inStringContext(...)`: suppress comment parsing inside strings [`src/core/source-analyzer.ts`]
+            - `findComment(...)`: detect valid single-line comment boundary [`src/core/source-analyzer.ts`]
+            - `cleanCommentLine(...)`: normalize comment payload [`src/core/source-analyzer.ts`]
+          - `extractDoxygenFields(...)`: bind documentation comments to definitions [`src/core/source-analyzer.ts`]
+            - `isPostfixDoxygenComment(...)`: detect postfix documentation markers [`src/core/source-analyzer.ts`]
+            - `parseDoxygenComment(...)`: parse Doxygen tag/value map [`src/core/doxygen-parser.ts`]
+              - `stripCommentDelimiters(...)`: remove language comment wrappers [`src/core/doxygen-parser.ts`]
+              - `normalizeWhitespace(...)`: canonicalize tag body whitespace [`src/core/doxygen-parser.ts`]
+        - `constructMatches(...)`: apply tag and regex filter [`src/core/find-constructs.ts`]
+        - `extractFileLevelDoxygenFields(...)`: extract file-level Doxygen fields [`src/core/find-constructs.ts`]
+          - `parseDoxygenComment(...)`: parse Doxygen tag/value map [`src/core/doxygen-parser.ts`]
+            - `stripCommentDelimiters(...)`: remove language comment wrappers [`src/core/doxygen-parser.ts`]
+            - `normalizeWhitespace(...)`: canonicalize tag body whitespace [`src/core/doxygen-parser.ts`]
+        - `formatConstruct(...)`: render one construct extract [`src/core/find-constructs.ts`]
+          - `extractConstructDoxygenFields(...)`: merge direct and near-body Doxygen fields [`src/core/find-constructs.ts`]
+            - `parseDoxygenComment(...)`: parse Doxygen tag/value map [`src/core/doxygen-parser.ts`]
+              - `stripCommentDelimiters(...)`: remove language comment wrappers [`src/core/doxygen-parser.ts`]
+              - `normalizeWhitespace(...)`: canonicalize tag body whitespace [`src/core/doxygen-parser.ts`]
+          - `formatDoxygenFieldsAsMarkdown(...)`: render Doxygen fields as markdown bullets [`src/core/doxygen-parser.ts`]
+          - `stripConstructComments(...)`: compress construct code while preserving strings [`src/core/find-constructs.ts`]
+            - `compressSource(...)`: strip comments and blank lines [`src/core/compress.ts`]
+              - `getSpecs(...)`: memoize parser specs [`src/core/compress.ts`]
+                - `buildLanguageSpecs(...)`: build multi-language parser specs [`src/core/source-analyzer.ts`]
+                  - `re(...)`: compile regex fragments [`src/core/source-analyzer.ts`]
+              - `isInString(...)`: suppress inline comment stripping inside strings [`src/core/compress.ts`]
+              - `removeInlineComment(...)`: remove single-line comment suffixes [`src/core/compress.ts`]
+              - `formatResult(...)`: render compressed output [`src/core/compress.ts`]
+        - `formatAvailableTags(...)`: render supported tag index for failure paths [`src/core/find-constructs.ts`]
+    - `runStaticCheck(...)`: branch `--test-static-check`; invoke static-check test driver [`src/core/static-check.ts`]
+      - `StaticCheckBase.run(...)`: iterate resolved files for dummy driver [`src/core/static-check.ts`]
+        - `StaticCheckBase.checkFile(...)`: emit success without external checker [`src/core/static-check.ts`]
+          - `StaticCheckBase.headerLine(...)`: format checker header [`src/core/static-check.ts`]
+          - `StaticCheckBase.emitLine(...)`: write checker output [`src/core/static-check.ts`]
+      - `StaticCheckPylance.run(...)`: iterate resolved files for pyright path [`src/core/static-check.ts`]
+        - `StaticCheckPylance.checkFile(...)`: run pyright-based validation [`src/core/static-check.ts`]
+          - `detectPythonExecutable(...)`: resolve Python interpreter [`src/core/static-check.ts`]
+            - `findExecutable(...)`: resolve executable on `PATH` [`src/core/static-check.ts`]
+          - `StaticCheckBase.headerLine(...)`: format checker header [`src/core/static-check.ts`]
+          - `StaticCheckBase.emitLine(...)`: write checker output [`src/core/static-check.ts`]
+      - `StaticCheckRuff.run(...)`: iterate resolved files for ruff path [`src/core/static-check.ts`]
+        - `StaticCheckRuff.checkFile(...)`: run ruff-based validation [`src/core/static-check.ts`]
+          - `detectPythonExecutable(...)`: resolve Python interpreter [`src/core/static-check.ts`]
+            - `findExecutable(...)`: resolve executable on `PATH` [`src/core/static-check.ts`]
+          - `StaticCheckBase.headerLine(...)`: format checker header [`src/core/static-check.ts`]
+          - `StaticCheckBase.emitLine(...)`: write checker output [`src/core/static-check.ts`]
+      - `StaticCheckCommand.run(...)`: iterate resolved files for generic command path [`src/core/static-check.ts`]
+        - `StaticCheckCommand.checkFile(...)`: run external executable against one file [`src/core/static-check.ts`]
+          - `StaticCheckBase.headerLine(...)`: format checker header [`src/core/static-check.ts`]
+          - `StaticCheckBase.emitLine(...)`: write checker output [`src/core/static-check.ts`]
+    - `runFilesStaticCheck(...)`: branch `--files-static-check`; run configured checkers for explicit files [`src/core/tool-runner.ts`]
+      - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
+      - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+        - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+        - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+          - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+      - `dispatchStaticCheckForFile(...)`: instantiate checker by configured module [`src/core/static-check.ts`]
+        - `formatStaticCheckModules(...)`: render valid module names for error paths [`src/core/static-check.ts`]
+        - `StaticCheckBase.run(...)`: execute dummy checker [`src/core/static-check.ts`]
+          - `StaticCheckBase.checkFile(...)`: emit success without external checker [`src/core/static-check.ts`]
+            - `StaticCheckBase.headerLine(...)`: format checker header [`src/core/static-check.ts`]
+            - `StaticCheckBase.emitLine(...)`: write checker output [`src/core/static-check.ts`]
+        - `StaticCheckPylance.run(...)`: execute pyright checker [`src/core/static-check.ts`]
+          - `StaticCheckPylance.checkFile(...)`: run pyright-based validation [`src/core/static-check.ts`]
+            - `detectPythonExecutable(...)`: resolve Python interpreter [`src/core/static-check.ts`]
+              - `findExecutable(...)`: resolve executable on `PATH` [`src/core/static-check.ts`]
+            - `StaticCheckBase.headerLine(...)`: format checker header [`src/core/static-check.ts`]
+            - `StaticCheckBase.emitLine(...)`: write checker output [`src/core/static-check.ts`]
+        - `StaticCheckRuff.run(...)`: execute ruff checker [`src/core/static-check.ts`]
+          - `StaticCheckRuff.checkFile(...)`: run ruff-based validation [`src/core/static-check.ts`]
+            - `detectPythonExecutable(...)`: resolve Python interpreter [`src/core/static-check.ts`]
+              - `findExecutable(...)`: resolve executable on `PATH` [`src/core/static-check.ts`]
+            - `StaticCheckBase.headerLine(...)`: format checker header [`src/core/static-check.ts`]
+            - `StaticCheckBase.emitLine(...)`: write checker output [`src/core/static-check.ts`]
+        - `StaticCheckCommand.run(...)`: execute generic command checker [`src/core/static-check.ts`]
+          - `StaticCheckCommand.checkFile(...)`: run external executable against one file [`src/core/static-check.ts`]
+            - `StaticCheckBase.headerLine(...)`: format checker header [`src/core/static-check.ts`]
+            - `StaticCheckBase.emitLine(...)`: write checker output [`src/core/static-check.ts`]
+    - `runReferences(...)`: branch `--references`; emit structured project references JSON [`src/core/tool-runner.ts`]
+      - `resolveProjectSrcDirs(...)`: load configured source directories [`src/core/tool-runner.ts`]
+        - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
+        - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+          - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+          - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+            - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+      - `collectSourceFiles(...)`: gather tracked and untracked source files under configured roots [`src/core/tool-runner.ts`]
+        - `makeRelativeIfContainsProject(...)`: normalize configured root tokens [`src/core/utils.ts`]
+      - `buildReferenceToolPayload(...)`: analyze configured source files into the agent-oriented references payload [`src/core/reference-payload.ts`]
+        - `canonicalizeReferencePath(...)`: normalize request and file paths against the project base [`src/core/reference-payload.ts`]
+        - `analyzeReferenceFile(...)`: analyze one processable file into structured imports, symbols, and comments [`src/core/reference-payload.ts`]
+          - `detectLanguage(...)`: map extension to language key [`src/core/compress.ts`]
+          - `SourceAnalyzer.analyze(...)`: parse source elements [`src/core/source-analyzer.ts`]
+          - `SourceAnalyzer.enrich(...)`: derive signatures, hierarchy, visibility, inheritance, body annotations, and Doxygen bindings [`src/core/source-analyzer.ts`]
+          - `buildCommentMaps(...)`: associate comments with definitions and file descriptions [`src/core/reference-payload.ts`]
+          - `collectFileLevelDoxygenFields(...)`: extract file-level Doxygen fields [`src/core/source-analyzer.ts`]
+          - `collectElementDoxygenFields(...)`: merge direct and near-body Doxygen fields [`src/core/source-analyzer.ts`]
+          - `structureDoxygenFields(...)`: normalize Doxygen fields into tag-specific JSON arrays and objects [`src/core/doxygen-parser.ts`]
+          - `countDoxygenFieldValues(...)`: derive aggregate Doxygen counts [`src/core/doxygen-parser.ts`]
+          - `resolveParentElement(...)`: link nested symbols to enclosing definitions [`src/core/reference-payload.ts`]
+          - `buildCommentEntry(...)`: serialize normalized comment text and line ranges [`src/core/reference-payload.ts`]
+        - `buildRepositoryTree(...)`: materialize the repository directory tree as structured JSON [`src/core/reference-payload.ts`]
+      - `buildReferenceToolExecutionStderr(...)`: serialize skipped and analysis-error entries into stderr text [`src/core/reference-payload.ts`]
+    - `runCompress(...)`: branch `--compress`; compress configured source files [`src/core/tool-runner.ts`]
+      - `resolveProjectSrcDirs(...)`: load configured source directories [`src/core/tool-runner.ts`]
+        - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
+        - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+          - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+          - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+            - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+      - `collectSourceFiles(...)`: gather tracked and untracked source files under configured roots [`src/core/tool-runner.ts`]
+        - `makeRelativeIfContainsProject(...)`: normalize configured root tokens [`src/core/utils.ts`]
+      - `compressFiles(...)`: compress each file into markdown blocks [`src/core/compress-files.ts`]
+        - `detectLanguage(...)`: map extension to language key [`src/core/compress.ts`]
+        - `compressFileDetailed(...)`: compress one file into structured lines and rendered text [`src/core/compress.ts`]
+          - `detectLanguage(...)`: map extension to language key [`src/core/compress.ts`]
+          - `compressSourceDetailed(...)`: strip comments and blank lines into structured line records [`src/core/compress.ts`]
+            - `getSpecs(...)`: memoize parser specs [`src/core/compress.ts`]
+              - `buildLanguageSpecs(...)`: build multi-language parser specs [`src/core/source-analyzer.ts`]
+                - `re(...)`: compile regex fragments [`src/core/source-analyzer.ts`]
+            - `countLogicalLines(...)`: count original source lines [`src/core/compress.ts`]
+            - `isInString(...)`: suppress inline comment stripping inside strings [`src/core/compress.ts`]
+            - `removeInlineComment(...)`: remove single-line comment suffixes [`src/core/compress.ts`]
+            - `buildCompressedLineEntry(...)`: normalize one retained line into structured output [`src/core/compress.ts`]
+            - `formatCompressedSourceText(...)`: render compressed output text [`src/core/compress.ts`]
+        - `formatOutputPath(...)`: normalize emitted file path [`src/core/compress-files.ts`]
+    - `runFind(...)`: branch `--find`; extract project-wide named constructs [`src/core/tool-runner.ts`]
+      - `resolveProjectSrcDirs(...)`: load configured source directories [`src/core/tool-runner.ts`]
+        - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
+        - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+          - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+          - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+            - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+      - `collectSourceFiles(...)`: gather tracked and untracked source files under configured roots [`src/core/tool-runner.ts`]
+        - `makeRelativeIfContainsProject(...)`: normalize configured root tokens [`src/core/utils.ts`]
+      - `findConstructsInFiles(...)`: select constructs by tag and regex [`src/core/find-constructs.ts`]
+        - `parseTagFilter(...)`: parse tag filter set [`src/core/find-constructs.ts`]
+        - `detectLanguage(...)`: map extension to language key [`src/core/compress.ts`]
+        - `languageSupportsTags(...)`: reject unsupported tag/language combinations [`src/core/find-constructs.ts`]
+        - `SourceAnalyzer.analyze(...)`: parse source elements [`src/core/source-analyzer.ts`]
+          - `inStringContext(...)`: suppress comment parsing inside strings [`src/core/source-analyzer.ts`]
+          - `findComment(...)`: detect valid single-line comment boundary [`src/core/source-analyzer.ts`]
+          - `findBlockEnd(...)`: compute construct end line [`src/core/source-analyzer.ts`]
+        - `SourceAnalyzer.enrich(...)`: derive signatures, hierarchy, visibility, inheritance, body annotations, and Doxygen bindings [`src/core/source-analyzer.ts`]
+          - `cleanNames(...)`: normalize matched symbol names [`src/core/source-analyzer.ts`]
+          - `extractSignatures(...)`: derive single-line signatures [`src/core/source-analyzer.ts`]
+          - `detectHierarchy(...)`: assign parent-child relationships [`src/core/source-analyzer.ts`]
+          - `extractVisibility(...)`: annotate visibility [`src/core/source-analyzer.ts`]
+            - `parseVisibility(...)`: language-specific visibility classifier [`src/core/source-analyzer.ts`]
+          - `extractInheritance(...)`: annotate inheritance [`src/core/source-analyzer.ts`]
+            - `parseInheritance(...)`: language-specific inheritance parser [`src/core/source-analyzer.ts`]
+          - `extractBodyAnnotations(...)`: capture body comments and exit points [`src/core/source-analyzer.ts`]
+            - `inStringContext(...)`: suppress comment parsing inside strings [`src/core/source-analyzer.ts`]
+            - `findComment(...)`: detect valid single-line comment boundary [`src/core/source-analyzer.ts`]
+            - `cleanCommentLine(...)`: normalize comment payload [`src/core/source-analyzer.ts`]
+          - `extractDoxygenFields(...)`: bind documentation comments to definitions [`src/core/source-analyzer.ts`]
+            - `isPostfixDoxygenComment(...)`: detect postfix documentation markers [`src/core/source-analyzer.ts`]
+            - `parseDoxygenComment(...)`: parse Doxygen tag/value map [`src/core/doxygen-parser.ts`]
+              - `stripCommentDelimiters(...)`: remove language comment wrappers [`src/core/doxygen-parser.ts`]
+              - `normalizeWhitespace(...)`: canonicalize tag body whitespace [`src/core/doxygen-parser.ts`]
+        - `constructMatches(...)`: apply tag and regex filter [`src/core/find-constructs.ts`]
+        - `extractFileLevelDoxygenFields(...)`: extract file-level Doxygen fields [`src/core/find-constructs.ts`]
+          - `parseDoxygenComment(...)`: parse Doxygen tag/value map [`src/core/doxygen-parser.ts`]
+            - `stripCommentDelimiters(...)`: remove language comment wrappers [`src/core/doxygen-parser.ts`]
+            - `normalizeWhitespace(...)`: canonicalize tag body whitespace [`src/core/doxygen-parser.ts`]
+        - `formatConstruct(...)`: render one construct extract [`src/core/find-constructs.ts`]
+          - `extractConstructDoxygenFields(...)`: merge direct and near-body Doxygen fields [`src/core/find-constructs.ts`]
+            - `parseDoxygenComment(...)`: parse Doxygen tag/value map [`src/core/doxygen-parser.ts`]
+              - `stripCommentDelimiters(...)`: remove language comment wrappers [`src/core/doxygen-parser.ts`]
+              - `normalizeWhitespace(...)`: canonicalize tag body whitespace [`src/core/doxygen-parser.ts`]
+          - `formatDoxygenFieldsAsMarkdown(...)`: render Doxygen fields as markdown bullets [`src/core/doxygen-parser.ts`]
+          - `stripConstructComments(...)`: compress construct code while preserving strings [`src/core/find-constructs.ts`]
+            - `compressSource(...)`: strip comments and blank lines [`src/core/compress.ts`]
+              - `getSpecs(...)`: memoize parser specs [`src/core/compress.ts`]
+                - `buildLanguageSpecs(...)`: build multi-language parser specs [`src/core/source-analyzer.ts`]
+                  - `re(...)`: compile regex fragments [`src/core/source-analyzer.ts`]
+              - `isInString(...)`: suppress inline comment stripping inside strings [`src/core/compress.ts`]
+              - `removeInlineComment(...)`: remove single-line comment suffixes [`src/core/compress.ts`]
+              - `formatResult(...)`: render compressed output [`src/core/compress.ts`]
+        - `formatAvailableTags(...)`: render supported tag index for failure paths [`src/core/find-constructs.ts`]
+    - `runTokens(...)`: branch `--tokens`; count canonical docs token usage [`src/core/tool-runner.ts`]
+      - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
+      - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+        - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+        - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+          - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+      - `runFilesTokens(...)`: count explicit-file token, size, and structure metrics [`src/core/tool-runner.ts`]
+        - `countFilesMetrics(...)`: read files and extract token, character, byte, line, heading, and optional Doxygen facts [`src/core/token-counter.ts`]
+          - `buildCountFileMetricsResult(...)`: assemble direct-access per-file metrics and metadata [`src/core/token-counter.ts`]
+            - `TokenCounter.countTokens(...)`: encode content and count tokens [`src/core/token-counter.ts`]
+            - `TokenCounter.countChars(...)`: count characters [`src/core/token-counter.ts`]
+            - `countLines(...)`: count logical lines [`src/core/token-counter.ts`]
+            - `inferLanguageName(...)`: infer agent-oriented language labels [`src/core/token-counter.ts`]
+            - `extractPrimaryHeadingText(...)`: extract the first markdown heading when present [`src/core/token-counter.ts`]
+            - `extractLeadingDoxygenFields(...)`: extract file-level Doxygen fields when present [`src/core/token-counter.ts`]
+              - `parseDoxygenComment(...)`: parse normalized Doxygen fields [`src/core/doxygen-parser.ts`]
+        - `formatPackSummary(...)`: render aggregate summary [`src/core/token-counter.ts`]
+    - `runProjectStaticCheck(...)`: branch `--static-check`; run configured checkers for source and test roots [`src/core/tool-runner.ts`]
+      - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
+      - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+        - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+        - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+          - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+      - `collectSourceFiles(...)`: gather tracked and untracked source and test files [`src/core/tool-runner.ts`]
+        - `makeRelativeIfContainsProject(...)`: normalize configured root tokens [`src/core/utils.ts`]
+      - `runFilesStaticCheck(...)`: run configured checkers for explicit files [`src/core/tool-runner.ts`]
+        - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
+        - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+          - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+          - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+            - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+        - `dispatchStaticCheckForFile(...)`: instantiate checker by configured module [`src/core/static-check.ts`]
+          - `formatStaticCheckModules(...)`: render valid module names for error paths [`src/core/static-check.ts`]
+          - `StaticCheckBase.run(...)`: execute dummy checker [`src/core/static-check.ts`]
+            - `StaticCheckBase.checkFile(...)`: emit success without external checker [`src/core/static-check.ts`]
+              - `StaticCheckBase.headerLine(...)`: format checker header [`src/core/static-check.ts`]
+              - `StaticCheckBase.emitLine(...)`: write checker output [`src/core/static-check.ts`]
+          - `StaticCheckPylance.run(...)`: execute pyright checker [`src/core/static-check.ts`]
+            - `StaticCheckPylance.checkFile(...)`: run pyright-based validation [`src/core/static-check.ts`]
+              - `detectPythonExecutable(...)`: resolve Python interpreter [`src/core/static-check.ts`]
+                - `findExecutable(...)`: resolve executable on `PATH` [`src/core/static-check.ts`]
+              - `StaticCheckBase.headerLine(...)`: format checker header [`src/core/static-check.ts`]
+              - `StaticCheckBase.emitLine(...)`: write checker output [`src/core/static-check.ts`]
+          - `StaticCheckRuff.run(...)`: execute ruff checker [`src/core/static-check.ts`]
+            - `StaticCheckRuff.checkFile(...)`: run ruff-based validation [`src/core/static-check.ts`]
+              - `detectPythonExecutable(...)`: resolve Python interpreter [`src/core/static-check.ts`]
+                - `findExecutable(...)`: resolve executable on `PATH` [`src/core/static-check.ts`]
+              - `StaticCheckBase.headerLine(...)`: format checker header [`src/core/static-check.ts`]
+              - `StaticCheckBase.emitLine(...)`: write checker output [`src/core/static-check.ts`]
+          - `StaticCheckCommand.run(...)`: execute generic command checker [`src/core/static-check.ts`]
+            - `StaticCheckCommand.checkFile(...)`: run external executable against one file [`src/core/static-check.ts`]
+              - `StaticCheckBase.headerLine(...)`: format checker header [`src/core/static-check.ts`]
+              - `StaticCheckBase.emitLine(...)`: write checker output [`src/core/static-check.ts`]
+    - `runGitCheck(...)`: branch `--git-check`; validate clean git state [`src/core/tool-runner.ts`]
+      - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
+      - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+        - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+        - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+          - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+      - `resolveEffectiveGitPath(...)`: derive the effective repository root constrained by `base-path` ancestry [`src/core/tool-runner.ts`]
+        - `isSameOrAncestorPath(...)`: validate git-root ancestry against the base path [`src/core/path-context.ts`]
+        - `isInsideGitRepo(...)`: probe git repository membership [`src/core/tool-runner.ts`]
+          - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
+        - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
+          - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
+      - `runCapture(...)`: verify worktree membership [`src/core/tool-runner.ts`]
+      - `runCapture(...)`: inspect porcelain changes [`src/core/tool-runner.ts`]
+      - `runCapture(...)`: resolve symbolic HEAD [`src/core/tool-runner.ts`]
+      - `runCapture(...)`: resolve detached HEAD fallback [`src/core/tool-runner.ts`]
+    - `runDocsCheck(...)`: branch `--docs-check`; validate canonical docs presence [`src/core/tool-runner.ts`]
+      - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
+      - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+        - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+        - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+          - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+    - `runGitWtName(...)`: branch `--git-wt-name`; generate standardized worktree name [`src/core/tool-runner.ts`]
+      - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
+      - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+        - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+        - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+          - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+      - `resolveEffectiveGitPath(...)`: derive the effective repository root constrained by `base-path` ancestry [`src/core/tool-runner.ts`]
+      - `sanitizeBranchName(...)`: canonicalize current branch token [`src/core/tool-runner.ts`]
+    - `runGitWtCreate(...)`: branch `--git-wt-create`; create worktree and copy config [`src/core/tool-runner.ts`]
+      - `validateWtName(...)`: validate requested worktree name [`src/core/tool-runner.ts`]
+      - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
+      - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+        - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+        - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+          - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+      - `resolveEffectiveGitPath(...)`: derive the effective repository root constrained by `base-path` ancestry [`src/core/tool-runner.ts`]
+      - `rollbackWorktreeCreate(...)`: remove partial worktree and branch on copy failure [`src/core/tool-runner.ts`]
+    - `runGitWtDelete(...)`: branch `--git-wt-delete`; remove worktree and branch [`src/core/tool-runner.ts`]
+      - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
+      - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+        - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+        - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+          - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+      - `resolveEffectiveGitPath(...)`: derive the effective repository root constrained by `base-path` ancestry [`src/core/tool-runner.ts`]
+      - `worktreePathExistsExact(...)`: verify exact registered worktree path [`src/core/tool-runner.ts`]
+        - `runCapture(...)`: run git worktree list subprocess [`src/core/tool-runner.ts`]
+    - `runGitPath(...)`: branch `--git-path`; print configured git root [`src/core/tool-runner.ts`]
+      - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
+      - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+        - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+        - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+          - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+      - `resolveEffectiveGitPath(...)`: derive the effective repository root constrained by `base-path` ancestry [`src/core/tool-runner.ts`]
+      - `formatRuntimePathForDisplay(...)`: serialize the git path for CLI output [`src/core/path-context.ts`]
+    - `runGetBasePath(...)`: branch `--get-base-path`; print configured base path [`src/core/tool-runner.ts`]
+      - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
+      - `formatRuntimePathForDisplay(...)`: serialize the base path for CLI output [`src/core/path-context.ts`]
+        - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+        - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+          - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+    - `writeResult(...)`: emit selected runner result [`src/cli.ts`]
+      - `writeStdout(...)`: write stdout payload [`src/cli.ts`]
+      - `writeStderr(...)`: write stderr payload [`src/cli.ts`]
+- External Boundaries:
+  - Node process APIs for argv, cwd, environment, stdout, stderr, and exit code.
+  - Filesystem access for config, docs discovery, source reads, and bundled resources.
+  - Git, bash, pyright, ruff, and arbitrary configured checker subprocesses via child-process execution.
+
+### `PROC:req-debug`
+- Entrypoints:
+  - `main(...)`: bash wrapper runtime root [`scripts/pi-usereq-debug.sh`]
+- Lifecycle/trigger:
+  - Start trigger: Bash executes `scripts/pi-usereq-debug.sh` as a one-shot wrapper.
+  - Stop trigger: returns delegated harness exit status or local validation failure.
+  - Looping model: single-pass subcommand dispatch with no persistent loop.
+  - Threads: no explicit threads detected.
+  - Startup invariant: script body resolves `TSX_BIN` through `resolve_tsx_binary(...)` before invoking `main(...)`.
+- Internal Call-Trace Tree:
+  - `main(...)`: parse wrapper subcommand, normalize prompt and tool convenience aliases, rewrite tool `--args` when requested, and delegate to the TypeScript harness [`scripts/pi-usereq-debug.sh`]
+    - `print_usage(...)`: render wrapper usage text for help and empty invocation [`scripts/pi-usereq-debug.sh`]
+    - `require_value(...)`: validate required command, prompt, tool, or raw operands [`scripts/pi-usereq-debug.sh`]
+    - `contains_exact_option(...)`: detect forwarded `--args` or `--params` tokens for command and prompt replay [`scripts/pi-usereq-debug.sh`]
+    - `contains_long_option(...)`: detect explicit long options before inferring positional payloads [`scripts/pi-usereq-debug.sh`]
+    - `normalize_prompt_name(...)`: map bare prompt aliases to registered `req-*` command names [`scripts/pi-usereq-debug.sh`]
+    - `forward_tool_subcommand(...)`: normalize wrapper tool forwarding and rewrite `--args` into `--params` JSON when present [`scripts/pi-usereq-debug.sh`]
+      - `build_tool_params_json(...)`: spawn the tool-argument converter and capture serialized JSON params [`scripts/pi-usereq-debug.sh`]
+    - `run_debug_extension(...)`: enter repository root, apply default `--cwd` and `--extension`, and spawn the TypeScript harness [`scripts/pi-usereq-debug.sh`]
+- External Boundaries:
+  - Bash shell argument expansion, stdout, and stderr handling.
+  - `git rev-parse`, `ln -s`, and resolved `tsx` executable lookup triggered by `resolve_tsx_binary(...)` during startup.
+  - Child-process execution of `scripts/tool-args-to-params.ts` and `scripts/debug-extension.ts`.
+
+### `PROC:tool-args-to-params`
+- Entrypoints:
+  - `main(...)`: tool-argument conversion runtime root [`scripts/tool-args-to-params.ts`]
+- Lifecycle/trigger:
+  - Start trigger: `PROC:req-debug` executes `scripts/tool-args-to-params.ts` for tool subcommands that pass wrapper `--args`.
+  - Stop trigger: returns numeric exit code after one conversion path or caught `ReqError`.
+  - Looping model: single-pass argument parse followed by one conversion decision.
+  - Threads: no explicit threads detected.
+- Internal Call-Trace Tree:
+  - `main(...)`: parse argv, convert wrapper tool args text into JSON params, and serialize the result [`scripts/tool-args-to-params.ts`]
+    - `parseCliArgs(...)`: map converter CLI options into one normalized request [`scripts/tool-args-to-params.ts`]
+    - `buildToolParamsFromArgsText(...)`: tokenize wrapper args text and map it to one tool-parameter object [`scripts/tool-args-to-params.ts`]
+      - `shellSplit(...)`: split shell-style text into ordered tokens [`src/core/utils.ts`]
+      - `takeBooleanFlag(...)`: remove supported boolean flags while preserving positional order [`scripts/tool-args-to-params.ts`]
+    - `writeStdout(...)`: emit serialized JSON params or usage text [`scripts/tool-args-to-params.ts`]
+    - `writeStderr(...)`: emit conversion diagnostics on error paths [`scripts/tool-args-to-params.ts`]
+- External Boundaries:
+  - Node process APIs for argv, stdout, stderr, and exit code.
+
+### `PROC:debug-ext`
+- Entrypoints:
+  - `main(...)`: debug-harness runtime root [`scripts/debug-extension.ts`]
+- Lifecycle/trigger:
+  - Start trigger: Node executes `scripts/debug-extension.ts` as a one-shot command.
+  - Stop trigger: returns numeric exit code after one harness subcommand or caught `ReqError`.
+  - Looping model: single-pass argument parse followed by single branch dispatch.
+  - Threads: no explicit threads detected.
+- Internal Call-Trace Tree:
+  - `main(...)`: parse argv, dispatch inspect/session-start/command/tool/sdk-smoke, and serialize the selected report [`scripts/debug-extension.ts`]
+    - `parseArgs(...)`: map argv tokens into harness subcommand options [`scripts/debug-extension.ts`]
+    - `parseJsonObject(...)`: parse JSON object options for tool and session replay [`scripts/debug-extension.ts`]
+    - `inspectExtension(...)`: load the extension as a black box, capture registrations, and render the manual [`scripts/lib/extension-debug-harness.ts`]
+      - `registerExtensionOffline(...)`: resolve paths, load the extension default export, and invoke registration under the requested cwd [`scripts/lib/extension-debug-harness.ts`]
+        - `resolveHarnessPaths(...)`: validate working-directory and extension-entry paths [`scripts/lib/extension-debug-harness.ts`]
+        - `loadExtensionFactory(...)`: dynamically import the extension default export [`scripts/lib/extension-debug-harness.ts`]
+        - `withProcessCwd(...)`: execute registration under the requested cwd [`scripts/lib/extension-debug-harness.ts`]
+          - `piUsereqExtension(...)`: register extension commands, tools, shortcuts, and lifecycle hooks [`src/index.ts`]
+            - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources before registration [`src/core/resources.ts`]
+            - `registerPromptCommands(...)`: register bundled `req-*` prompt commands [`src/index.ts`]
+            - `registerAgentTools(...)`: register structured agent tools [`src/index.ts`]
+            - `registerConfigCommands(...)`: register configuration commands [`src/index.ts`]
+            - `registerPiNotifyShortcut(...)`: register the configured successful-run sound shortcut when the runtime supports shortcuts [`src/index.ts`]
+              - `loadProjectConfig(...)`: load the current project config for shortcut registration [`src/index.ts`]
+                - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
+                - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+                  - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+                  - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+                    - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+                  - `normalizePiNotifySoundLevel(...)`: normalize persisted sound level [`src/core/pi-notify.ts`]
+                  - `normalizePiNotifyShortcut(...)`: normalize persisted shortcut [`src/core/pi-notify.ts`]
+                  - `normalizePiNotifyCommand(...)`: normalize persisted sound commands [`src/core/pi-notify.ts`]
+                - `isInsideGitRepo(...)`: probe git repository membership [`src/core/tool-runner.ts`]
+                - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
+      - `buildDebugManual(...)`: render mode and per-command/per-tool examples, including JSON-oriented token-tool examples [`scripts/lib/extension-debug-harness.ts`]
+    - `replaySessionStart(...)`: replay recorded `session_start` handlers and capture resulting UI state [`scripts/lib/extension-debug-harness.ts`]
+      - `registerExtensionOffline(...)`: rebuild the recorded extension registration surface [`scripts/lib/extension-debug-harness.ts`]
+      - `RecordingCommandContext(...)`: initialize the recorded command-context UI adapter and deterministic theme-color encoding [`scripts/lib/recording-extension-api.ts`]
+      - `withProcessCwd(...)`: execute `session_start` under the requested cwd [`scripts/lib/extension-debug-harness.ts`]
+        - `loadProjectConfig(...)`: session-start configuration load [`src/index.ts`]
+          - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
+          - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+          - `isInsideGitRepo(...)`: probe git repository membership [`src/core/tool-runner.ts`]
+          - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
+        - `handleExtensionStatusEvent(...)`: process the replayed `session_start` payload through shared status telemetry helpers [`src/index.ts`]
+          - `loadProjectConfig(...)`: session-start configuration load [`src/index.ts`]
+            - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
+            - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+              - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+              - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+                - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+            - `isInsideGitRepo(...)`: probe git repository membership [`src/core/tool-runner.ts`]
+            - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
+          - `applyConfiguredPiUsereqTools(...)`: enforce configured active tools against the offline runtime inventory [`src/index.ts`]
+            - `getConfiguredEnabledPiUsereqTools(...)`: canonicalize configured enabled tools [`src/index.ts`]
+              - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
+            - `RecordingExtensionAPI.getAllTools(...)`: expose supported builtin plus extension tool inventory [`scripts/lib/recording-extension-api.ts`]
+              - `RecordingExtensionAPI.getBuiltinTools(...)`: synthesize supported builtin tool descriptors [`scripts/lib/recording-extension-api.ts`]
+                - `buildBuiltinToolDefinition(...)`: build one builtin tool descriptor [`scripts/lib/recording-extension-api.ts`]
+                  - `buildBuiltinSourceInfo(...)`: synthesize builtin provenance metadata [`scripts/lib/recording-extension-api.ts`]
+            - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory [`src/index.ts`]
+            - `RecordingExtensionAPI.getActiveTools(...)`: expose current active-tool set [`scripts/lib/recording-extension-api.ts`]
+            - `RecordingExtensionAPI.setActiveTools(...)`: replace active-tool set with runtime-visible names [`scripts/lib/recording-extension-api.ts`]
+              - `RecordingExtensionAPI.getAllTools(...)`: expose supported builtin plus extension tool inventory [`scripts/lib/recording-extension-api.ts`]
+          - `setPiUsereqStatusConfig(...)`: cache docs/tests/src and pi-notify values for later status renders [`src/core/extension-status.ts`]
+          - `updateExtensionStatus(...)`: refresh stored context usage, timers, and rendered status text [`src/core/extension-status.ts`]
+            - `refreshContextUsage(...)`: sync the latest context-usage snapshot [`src/core/extension-status.ts`]
+              - `RecordingCommandContext.getContextUsage(...)`: return the offline context-usage placeholder [`scripts/lib/recording-extension-api.ts`]
+            - `syncPiUsereqStatusTicker(...)`: start or stop the live elapsed-time ticker [`src/core/extension-status.ts`]
+            - `renderPiUsereqStatus(...)`: render the git/base/docs/tests/src/tools/context/elapsed/last/beep/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
+              - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
+              - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with active-theme field and overlay semantics [`src/core/extension-status.ts`]
+                - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
+                - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
+                - `formatContextUsageBar(...)`: render the 5-cell context bar or threshold-specific overlay [`src/core/extension-status.ts`]
+                  - `resolveContextUsageOverlay(...)`: choose `CLEAR` or `FULL!` overlay states with CLI-supported theme tokens [`src/core/extension-status.ts`]
+                  - `formatContextUsageOverlay(...)`: paint the fixed-width overlay with preserved bar background [`src/core/extension-status.ts`]
+                - `formatStatusDuration(...)`: render `M:SS` durations [`src/core/extension-status.ts`]
+                - `formatPiNotifyBeepStatus(...)`: serialize enabled beep flags for the footer [`src/core/pi-notify.ts`]
+          - `runPiNotifyEffects(...)`: dispatch configured terminal beeps and successful-run sound hooks on `agent_end` [`src/core/pi-notify.ts`]
+            - `classifyPiNotifyOutcome(...)`: map assistant stop reasons to `end`, `esc`, or `err` [`src/core/pi-notify.ts`]
+              - `hasAgentEndStopReason(...)`: scan assistant stop reasons inside the `agent_end` payload [`src/core/pi-notify.ts`]
+            - `buildPiNotifyTitle(...)`: build the stable pi-notify title [`src/core/pi-notify.ts`]
+            - `buildPiNotifyBody(...)`: build the stable pi-notify body from the classified outcome [`src/core/pi-notify.ts`]
+            - `notifyPiTerminal(...)`: route terminal notifications by runtime environment when the matching beep flag is enabled [`src/core/pi-notify.ts`]
+              - `notifyWindows(...)`: emit Windows toast notifications [`src/core/pi-notify.ts`]
+              - `notifyOSC99(...)`: emit Kitty OSC 99 notifications [`src/core/pi-notify.ts`]
+              - `notifyOSC9(...)`: emit OSC 9 notifications [`src/core/pi-notify.ts`]
+              - `notifyOSC777(...)`: emit OSC 777 notifications [`src/core/pi-notify.ts`]
+            - `runPiNotifySoundCommand(...)`: execute the configured successful-run sound command when sound is enabled [`src/core/pi-notify.ts`]
+              - `resolvePiNotifySoundCommand(...)`: select the configured command for `low`, `mid`, or `high` [`src/core/pi-notify.ts`]
+              - `substitutePiNotifyInstallPath(...)`: replace `%%INSTALLATION_PATH%%` before shell execution [`src/core/pi-notify.ts`]
+                - `quotePiNotifyInstallPath(...)`: quote the installation path for shell reuse [`src/core/pi-notify.ts`]
+                - `getInstallationPath(...)`: resolve the installed extension root [`src/core/path-context.ts`]
+    - `replayCommand(...)`: replay a recorded command handler and capture prompt/UI side effects [`scripts/lib/extension-debug-harness.ts`]
+      - `registerExtensionOffline(...)`: rebuild the recorded extension registration surface [`scripts/lib/extension-debug-harness.ts`]
+      - `RecordingCommandContext(...)`: initialize the recorded command-context UI adapter and deterministic theme-color encoding [`scripts/lib/recording-extension-api.ts`]
+      - `withProcessCwd(...)`: execute the named command under the requested cwd [`scripts/lib/extension-debug-harness.ts`]
+        - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources when invoking `req-*` handlers [`src/core/resources.ts`]
+        - `getProjectBase(...)`: resolve command project base [`src/index.ts`]
+        - `loadProjectConfig(...)`: load command runtime config [`src/index.ts`]
+        - `renderPrompt(...)`: render prompt-command payloads with conditional pi.dev API-contract guidance [`src/core/prompts.ts`]
+        - `deliverPromptCommand(...)`: dispatch prompt replay into the current recorded session [`src/index.ts`]
+          - External boundaries: `RecordingExtensionAPI.sendUserMessage(...)` records the delivered prompt payload.
+        - `configurePiUsereq(...)`: execute the interactive configuration menu [`src/index.ts`]
+          - `showPiUsereqSettingsMenu(...)`: render the shared settings-menu UI for top-level and submenu actions [`src/core/settings-menu.ts`]
+            - `formatPiUsereqSettingsMenuTitle(...)`: rebuild the menu title with active-theme semantics [`src/core/settings-menu.ts`]
+            - `buildPiUsereqSettingsListTheme(...)`: prefer shared CLI settings-list theming and fall back during offline replay [`src/core/settings-menu.ts`]
+              - `buildFallbackPiUsereqSettingsListTheme(...)`: mirror CLI settings-list token roles from the callback-local theme [`src/core/settings-menu.ts`]
+          - `saveProjectConfig(...)`: persist menu updates on save-and-close [`src/index.ts`]
+          - `setPiUsereqStatusConfig(...)`: cache the saved config for footer rendering [`src/core/extension-status.ts`]
+          - `renderPiUsereqStatus(...)`: render the docs/tests/src/tools/context/elapsed/last/beep/sound footer after save-and-close with CLI-theme token overlays [`src/core/extension-status.ts`]
+            - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
+            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with active-theme field and overlay semantics [`src/core/extension-status.ts`]
+              - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
+              - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
+              - `formatContextUsageBar(...)`: render the 5-cell context bar or threshold-specific overlay [`src/core/extension-status.ts`]
+              - `formatStatusDuration(...)`: render `M:SS` durations [`src/core/extension-status.ts`]
+              - `formatPiNotifyBeepStatus(...)`: serialize enabled beep flags for the footer [`src/core/pi-notify.ts`]
+          - `configureStaticCheckMenu(...)`: interactive static-check editor [`src/index.ts`]
+          - `configurePiUsereqToolsMenu(...)`: interactive active-tool editor [`src/index.ts`]
+          - `configurePiNotifyMenu(...)`: interactive pi-notify editor [`src/index.ts`]
+            - `buildPiNotifyMenuChoices(...)`: serialize notification actions for the shared settings menu [`src/index.ts`]
+            - `togglePiNotifyBeepFlag(...)`: toggle one prompt-end beep flag [`src/index.ts`]
+    - `replayTool(...)`: replay a recorded tool execute handler and capture content/details [`scripts/lib/extension-debug-harness.ts`]
+      - `registerExtensionOffline(...)`: rebuild the recorded extension registration surface [`scripts/lib/extension-debug-harness.ts`]
+      - `RecordingCommandContext(...)`: initialize the recorded command-context UI adapter and deterministic theme-color encoding [`scripts/lib/recording-extension-api.ts`]
+      - `withProcessCwd(...)`: execute the named tool under the requested cwd [`scripts/lib/extension-debug-harness.ts`]
+        - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources for tool executes that need them [`src/core/resources.ts`]
+        - `getProjectBase(...)`: resolve tool project base [`src/index.ts`]
+        - `loadProjectConfig(...)`: load tool runtime config [`src/index.ts`]
+        - `buildTokenToolPayload(...)`: construct agent-oriented token JSON with separated source facts, metrics, and guidance [`src/core/token-counter.ts`]
+          - `probeRequestedPath(...)`: classify requested paths as readable files, missing inputs, or non-file inputs [`src/core/token-counter.ts`]
+          - `countFilesMetrics(...)`: read readable files and extract token, character, byte, line, heading, and optional Doxygen facts [`src/core/token-counter.ts`]
+            - `buildCountFileMetricsResult(...)`: assemble direct-access per-file metrics and metadata [`src/core/token-counter.ts`]
+              - `TokenCounter.countTokens(...)`: encode content and count tokens [`src/core/token-counter.ts`]
+              - `TokenCounter.countChars(...)`: count characters [`src/core/token-counter.ts`]
+              - `countLines(...)`: count logical lines [`src/core/token-counter.ts`]
+              - `inferLanguageName(...)`: infer agent-oriented language labels [`src/core/token-counter.ts`]
+              - `extractPrimaryHeadingText(...)`: extract the first markdown heading when present [`src/core/token-counter.ts`]
+              - `extractLeadingDoxygenFields(...)`: extract file-level Doxygen fields when present [`src/core/token-counter.ts`]
+                - `parseDoxygenComment(...)`: parse normalized Doxygen fields [`src/core/doxygen-parser.ts`]
+          - `orderPathsByMetric(...)`: derive stable counted-path orderings for guidance [`src/core/token-counter.ts`]
+        - `buildTokenToolExecuteResult(...)`: wrap token payloads into tool content and structured details [`src/index.ts`]
+          - `buildTokenToolExecutionStderr(...)`: serialize skipped and error observations into stderr text [`src/index.ts`]
+          - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
+        - `buildReferenceToolPayload(...)`: construct agent-oriented references JSON with repository structure, symbols, and Doxygen fields [`src/core/reference-payload.ts`]
+          - `canonicalizeReferencePath(...)`: normalize request and file paths against the project base [`src/core/reference-payload.ts`]
+          - `analyzeReferenceFile(...)`: analyze one processable file into structured imports, symbols, and comments [`src/core/reference-payload.ts`]
+          - `buildRepositoryTree(...)`: materialize the repository directory tree as structured JSON [`src/core/reference-payload.ts`]
+        - `buildReferenceToolExecuteResult(...)`: wrap references payloads into tool content and structured details [`src/index.ts`]
+          - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
+        - `buildCompressToolPayload(...)`: construct agent-oriented compression JSON with structured line facts, symbols, and Doxygen fields [`src/core/compress-payload.ts`]
+          - `analyzeCompressFile(...)`: compress one requested file and attach symbol metadata when available [`src/core/compress-payload.ts`]
+            - `compressFileDetailed(...)`: compress one file into structured lines and rendered text [`src/core/compress.ts`]
+            - `analyzeCompressedFileSymbols(...)`: extract symbol and Doxygen records for compressed files [`src/core/compress-payload.ts`]
+        - `buildCompressionToolExecuteResult(...)`: wrap compression payloads into tool content and structured details [`src/index.ts`]
+          - `buildCompressToolExecutionStderr(...)`: serialize skipped, error, and symbol-analysis warning entries [`src/core/compress-payload.ts`]
+          - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
+        - `buildFindToolSchemaDescription(...)`: synthesize find parameter-schema descriptions [`src/index.ts`]
+        - `buildFindToolPromptGuidelines(...)`: synthesize agent-oriented find guidance strings [`src/index.ts`]
+          - `buildFindToolSupportedTagGuidelines(...)`: emit per-language supported-tag guidance lines [`src/index.ts`]
+        - `buildFindToolPayload(...)`: construct agent-oriented construct-search JSON with structured file statuses, matches, line facts, and Doxygen fields [`src/core/find-payload.ts`]
+          - `validateTagFilter(...)`: normalize requested construct tags [`src/core/find-payload.ts`]
+          - `validateRegexPattern(...)`: compile the construct-name regex [`src/core/find-payload.ts`]
+          - `analyzeFindFile(...)`: analyze one requested file into structured search status and match records [`src/core/find-payload.ts`]
+            - `buildMatchEntry(...)`: structure one matched construct with typed lines and Doxygen fields [`src/core/find-payload.ts`]
+              - `buildStrippedConstructLineEntries(...)`: strip comments into structured code lines [`src/core/find-constructs.ts`]
+        - `buildFindToolExecuteResult(...)`: wrap construct-search payloads into tool content and structured details [`src/index.ts`]
+          - `buildFindToolExecutionStderr(...)`: serialize invalid-request, skipped, no-match, and analysis-error diagnostics [`src/core/find-payload.ts`]
+          - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
+        - `runGitPath(...)`: query the resolved git-path value [`src/core/tool-runner.ts`]
+        - `runGetBasePath(...)`: query the resolved base-path value [`src/core/tool-runner.ts`]
+        - `buildPathQueryToolPayload(...)`: structure path-query payloads for `git-path` and `get-base-path` [`src/core/agent-tool-json.ts`]
+        - `runFilesStaticCheck(...)`: execute configured checkers for explicit-file requests [`src/core/tool-runner.ts`]
+        - `collectProjectStaticCheckSelection(...)`: derive project static-check file selections and fixture exclusions [`src/index.ts`]
+        - `runProjectStaticCheck(...)`: execute configured checkers for project source and test selections [`src/core/tool-runner.ts`]
+        - `buildStaticCheckToolPayload(...)`: structure static-check request, file-selection, and execution facts [`src/core/agent-tool-json.ts`]
+        - `runGitCheck(...)`: validate runtime repository cleanliness [`src/core/tool-runner.ts`]
+        - `buildGitCheckToolPayload(...)`: structure git-validation status and execution facts [`src/core/agent-tool-json.ts`]
+        - `buildDocsCheckToolPayload(...)`: structure canonical-doc presence and remediation facts [`src/core/agent-tool-json.ts`]
+        - `runGitWtName(...)`: generate the standardized worktree name [`src/core/tool-runner.ts`]
+        - `buildWorktreeNameToolPayload(...)`: structure worktree-name generation facts [`src/core/agent-tool-json.ts`]
+        - `runGitWtCreate(...)`: create a dedicated worktree and branch [`src/core/tool-runner.ts`]
+        - `runGitWtDelete(...)`: delete a dedicated worktree and branch [`src/core/tool-runner.ts`]
+        - `buildWorktreeMutationToolPayload(...)`: structure worktree create/delete facts [`src/core/agent-tool-json.ts`]
+        - `buildToolExecutionSection(...)`: normalize stdout, stderr, and exit-code metadata [`src/core/agent-tool-json.ts`]
+        - `normalizeToolFailure(...)`: convert `ReqError` failures into structured execution records [`src/core/agent-tool-json.ts`]
+    - `runSdkSmoke(...)`: replay offline `session_start`, probe the official SDK runtime, and compare inventories [`scripts/lib/sdk-smoke.ts`]
+      - `replaySessionStart(...)`: capture the offline `session_start` contract [`scripts/lib/extension-debug-harness.ts`]
+      - `probeSdkRuntime(...)`: load the official SDK runtime and extract extension-owned inventory [`scripts/lib/sdk-smoke.ts`]
+        - `resolveHarnessPaths(...)`: validate working-directory and extension-entry paths [`scripts/lib/extension-debug-harness.ts`]
+        - `extractSdkApi(...)`: locate the runtime inventory surface [`scripts/lib/sdk-smoke.ts`]
+        - `normalizeCommandRecord(...)`: normalize SDK command metadata [`scripts/lib/sdk-smoke.ts`]
+          - `normalizeSourceInfo(...)`: normalize command provenance fields [`scripts/lib/sdk-smoke.ts`]
+            - `normalizePathValue(...)`: normalize source paths relative to project root [`scripts/lib/sdk-smoke.ts`]
+        - `normalizeToolRecord(...)`: normalize SDK tool metadata [`scripts/lib/sdk-smoke.ts`]
+          - `normalizeSourceInfo(...)`: normalize tool provenance fields [`scripts/lib/sdk-smoke.ts`]
+            - `normalizePathValue(...)`: normalize source paths relative to project root [`scripts/lib/sdk-smoke.ts`]
+      - `buildParityReport(...)`: compare offline and SDK inventories [`scripts/lib/sdk-smoke.ts`]
+        - `compareCommandInventories(...)`: detect command-name, description, and provenance mismatches [`scripts/lib/sdk-smoke.ts`]
+        - `compareToolInventories(...)`: detect tool-name, description, schema-presence, and provenance mismatches [`scripts/lib/sdk-smoke.ts`]
+        - `compareActiveTools(...)`: detect active-tool mismatches after `session_start` [`scripts/lib/sdk-smoke.ts`]
+    - `formatReport(...)`: serialize the selected report as JSON or markdown [`scripts/debug-extension.ts`]
+      - `formatJson(...)`: serialize a machine-readable payload [`scripts/debug-extension.ts`]
+      - `formatInspectReport(...)`: render offline inspection markdown [`scripts/debug-extension.ts`]
+      - `formatSessionStartReport(...)`: render `session_start` replay markdown [`scripts/debug-extension.ts`]
+      - `formatCommandReplayReport(...)`: render command replay markdown [`scripts/debug-extension.ts`]
+      - `formatToolReplayReport(...)`: render tool replay markdown [`scripts/debug-extension.ts`]
+      - `formatSdkSmokeReport(...)`: render parity markdown [`scripts/debug-extension.ts`]
+    - `writeStdout(...)`: emit the final report payload [`scripts/debug-extension.ts`]
+    - `writeStderr(...)`: emit CLI failure diagnostics on error paths [`scripts/debug-extension.ts`]
+- External Boundaries:
+  - Dynamic module loading for the target extension entry and optional `@mariozechner/pi-coding-agent` SDK package.
+  - Filesystem validation for requested cwd and extension paths.
+  - Any filesystem, git, or subprocess side effects triggered indirectly by the registered extension handlers during replay.
+
+### `PROC:pi-host`
+- Entrypoints:
+  - `piUsereqExtension(...)`: extension activation root [`src/index.ts`]
+  - `configurePiUsereq(...)`: named callback body for interactive configuration [`src/index.ts`]
+- Lifecycle/trigger:
+  - Start trigger: pi extension host imports the default export from `src/index.ts` and invokes `piUsereqExtension(...)`.
+  - Runtime trigger: registered commands, registered tools, and lifecycle-hook callbacks are invoked by external pi runtime.
+  - Stop trigger: host lifecycle is external; each callback returns control after completion.
+  - Looping model: event-driven callbacks; menu handlers loop until user selects exit or back.
+  - Threads: no explicit threads detected.
+- Internal Call-Trace Tree:
+  - `piUsereqExtension(...)`: initialize resources, register commands, tools, shortcuts, and lifecycle-hook telemetry wrappers [`src/index.ts`]
+    - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources [`src/core/resources.ts`]
+      - `getBundledResourceRoot(...)`: resolve installation-owned resource root [`src/core/resources.ts`]
+        - `getInstallationPath(...)`: resolve the installed extension root from the executing module [`src/core/path-context.ts`]
+    - `registerPromptCommands(...)`: register one command per prompt name [`src/index.ts`]
+      - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources before prompt render [`src/core/resources.ts`]
+        - `getBundledResourceRoot(...)`: resolve installation-owned resource root [`src/core/resources.ts`]
+          - `getInstallationPath(...)`: resolve the installed extension root from the executing module [`src/core/path-context.ts`]
+      - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
+      - `loadProjectConfig(...)`: load config and normalize persisted directory paths for command context [`src/index.ts`]
+        - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
+        - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+          - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+          - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+            - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+        - `isInsideGitRepo(...)`: probe git repository membership [`src/core/tool-runner.ts`]
+          - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
+        - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
+          - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
+      - `renderPrompt(...)`: render prompt template with project substitutions and conditional pi.dev API-contract guidance [`src/core/prompts.ts`]
+        - `readBundledPrompt(...)`: read bundled prompt template [`src/core/resources.ts`]
+          - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources [`src/core/resources.ts`]
+            - `getBundledResourceRoot(...)`: resolve installation-owned resource root [`src/core/resources.ts`]
+              - `getInstallationPath(...)`: resolve the installed extension root from the executing module [`src/core/path-context.ts`]
+        - `buildPromptReplacementPaths(...)`: build replacement token map including installation-owned template and guideline paths [`src/core/config.ts`]
+          - `buildRuntimePathContext(...)`: derive installation, execution, base, config, docs, tests, source, and git paths [`src/core/path-context.ts`]
+            - `getInstallationPath(...)`: resolve the installed extension root from the executing module [`src/core/path-context.ts`]
+            - `getConfigPath(...)`: derive the `.pi-usereq/config.json` path [`src/core/path-context.ts`]
+          - `buildRuntimePathFacts(...)`: convert runtime paths into prompt-visible path strings [`src/core/path-context.ts`]
+            - `formatRuntimePathForDisplay(...)`: serialize user-home-relative paths with environment variables [`src/core/path-context.ts`]
+          - `formatRuntimePathForDisplay(...)`: serialize guideline file paths for prompt substitution [`src/core/path-context.ts`]
+        - `applyReplacements(...)`: substitute token values [`src/core/prompts.ts`]
+        - `injectPiDevConformanceBlock(...)`: add conditional pi.dev manifest review and API-contract guidance for prompt workflows [`src/core/prompts.ts`]
+          - `buildPiDevConformanceBlock(...)`: resolve manifest-gated pi.dev review and API-compliance rules [`src/core/prompts.ts`]
+        - `adaptPromptForInternalTools(...)`: rewrite tool names for internal wrappers [`src/core/prompts.ts`]
+      - `deliverPromptCommand(...)`: dispatch the rendered prompt into the current active session [`src/index.ts`]
+        - External boundaries: `pi.sendUserMessage(...)` delivers the rendered prompt payload.
+    - `registerAgentTools(...)`: register structured pi tools whose execute callbacks reuse internal runner families and agent-oriented payload builders [`src/index.ts`]
+      - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources for tool executes that need bundled assets [`src/core/resources.ts`]
+        - `getBundledResourceRoot(...)`: resolve installation-owned resource root [`src/core/resources.ts`]
+          - `getInstallationPath(...)`: resolve the installed extension root from the executing module [`src/core/path-context.ts`]
+      - `getProjectBase(...)`: resolve project base from process cwd [`src/index.ts`]
+      - `loadProjectConfig(...)`: load config and normalize persisted directory paths for project-scoped tool executes [`src/index.ts`]
+        - `getProjectBase(...)`: resolve project base from process cwd [`src/index.ts`]
+        - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+          - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+          - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+            - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+        - `isInsideGitRepo(...)`: probe git repository membership [`src/core/tool-runner.ts`]
+          - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
+        - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
+          - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
+      - `buildSharedRuntimePathFacts(...)`: derive shared runtime path facts for path, git, docs, worktree, and static-check payloads [`src/index.ts`]
+        - `buildRuntimePathContext(...)`: derive installation, execution, base, config, docs, tests, source, and git paths [`src/core/path-context.ts`]
+          - `getInstallationPath(...)`: resolve the installed extension root from the executing module [`src/core/path-context.ts`]
+          - `getConfigPath(...)`: derive the `.pi-usereq/config.json` path [`src/core/path-context.ts`]
+        - `buildRuntimePathFacts(...)`: convert runtime paths into payload-facing path strings [`src/core/path-context.ts`]
+          - `formatRuntimePathForDisplay(...)`: serialize user-home-relative paths with environment variables [`src/core/path-context.ts`]
+      - `runGitPath(...)`: query the resolved git-path value [`src/core/tool-runner.ts`]
+      - `runGetBasePath(...)`: query the resolved base-path value [`src/core/tool-runner.ts`]
+      - `buildPathQueryToolPayload(...)`: structure path-query payloads for `git-path` and `get-base-path` [`src/core/agent-tool-json.ts`]
+      - `buildTokenToolPayload(...)`: construct agent-oriented token JSON with separated source facts, metrics, and guidance [`src/core/token-counter.ts`]
+        - `probeRequestedPath(...)`: classify requested paths as readable files, missing inputs, or non-file inputs [`src/core/token-counter.ts`]
+        - `countFilesMetrics(...)`: read readable files and extract token, character, byte, line, heading, and optional Doxygen facts [`src/core/token-counter.ts`]
+          - `buildCountFileMetricsResult(...)`: assemble direct-access per-file metrics and metadata [`src/core/token-counter.ts`]
+            - `TokenCounter.countTokens(...)`: encode content and count tokens [`src/core/token-counter.ts`]
+            - `TokenCounter.countChars(...)`: count characters [`src/core/token-counter.ts`]
+            - `countLines(...)`: count logical lines [`src/core/token-counter.ts`]
+            - `inferLanguageName(...)`: infer agent-oriented language labels [`src/core/token-counter.ts`]
+            - `extractPrimaryHeadingText(...)`: extract the first markdown heading when present [`src/core/token-counter.ts`]
+            - `extractLeadingDoxygenFields(...)`: extract file-level Doxygen fields when present [`src/core/token-counter.ts`]
+              - `parseDoxygenComment(...)`: parse normalized Doxygen fields [`src/core/doxygen-parser.ts`]
+        - `orderPathsByMetric(...)`: derive stable counted-path orderings for guidance [`src/core/token-counter.ts`]
+      - `buildTokenToolExecuteResult(...)`: wrap token payloads into tool content and structured details [`src/index.ts`]
+        - `buildTokenToolExecutionStderr(...)`: serialize skipped and error observations into stderr text [`src/index.ts`]
+        - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
+      - `buildReferenceToolPayload(...)`: construct agent-oriented references JSON with repository structure, symbols, and Doxygen fields [`src/core/reference-payload.ts`]
+        - `canonicalizeReferencePath(...)`: normalize request and file paths against the project base [`src/core/reference-payload.ts`]
+        - `analyzeReferenceFile(...)`: analyze one processable file into structured imports, symbols, and comments [`src/core/reference-payload.ts`]
+        - `buildRepositoryTree(...)`: materialize the repository directory tree as structured JSON [`src/core/reference-payload.ts`]
+      - `buildReferenceToolExecuteResult(...)`: wrap references payloads into tool content and structured details [`src/index.ts`]
+        - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
+      - `buildCompressToolPayload(...)`: construct agent-oriented compression JSON with structured line facts, symbols, and Doxygen fields [`src/core/compress-payload.ts`]
+        - `analyzeCompressFile(...)`: compress one requested file and attach symbol metadata when available [`src/core/compress-payload.ts`]
+          - `compressFileDetailed(...)`: compress one file into structured lines and rendered text [`src/core/compress.ts`]
+          - `analyzeCompressedFileSymbols(...)`: extract symbol and Doxygen records for compressed files [`src/core/compress-payload.ts`]
+      - `buildCompressionToolExecuteResult(...)`: wrap compression payloads into tool content and structured details [`src/index.ts`]
+        - `buildCompressToolExecutionStderr(...)`: serialize skipped, error, and symbol-analysis warning entries [`src/core/compress-payload.ts`]
+        - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
+      - `buildFindToolSchemaDescription(...)`: synthesize find parameter-schema descriptions [`src/index.ts`]
+      - `buildFindToolPromptGuidelines(...)`: synthesize agent-oriented find guidance strings [`src/index.ts`]
+        - `buildFindToolSupportedTagGuidelines(...)`: emit per-language supported-tag guidance lines [`src/index.ts`]
+      - `buildFindToolPayload(...)`: construct agent-oriented construct-search JSON with structured file statuses, matches, line facts, and Doxygen fields [`src/core/find-payload.ts`]
+        - `validateTagFilter(...)`: normalize requested construct tags [`src/core/find-payload.ts`]
+        - `validateRegexPattern(...)`: compile the construct-name regex [`src/core/find-payload.ts`]
+        - `analyzeFindFile(...)`: analyze one requested file into structured search status and match records [`src/core/find-payload.ts`]
+          - `buildMatchEntry(...)`: structure one matched construct with typed lines and Doxygen fields [`src/core/find-payload.ts`]
+            - `buildStrippedConstructLineEntries(...)`: strip comments into structured code lines [`src/core/find-constructs.ts`]
+      - `buildFindToolExecuteResult(...)`: wrap construct-search payloads into tool content and structured details [`src/index.ts`]
+        - `buildFindToolExecutionStderr(...)`: serialize invalid-request, skipped, no-match, and analysis-error diagnostics [`src/core/find-payload.ts`]
+        - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
+      - `runFilesStaticCheck(...)`: execute configured checkers for explicit-file requests [`src/core/tool-runner.ts`]
+      - `collectProjectStaticCheckSelection(...)`: derive project static-check file selections and fixture exclusions [`src/index.ts`]
+      - `runProjectStaticCheck(...)`: execute configured checkers for project source and test selections [`src/core/tool-runner.ts`]
+      - `buildStaticCheckToolPayload(...)`: structure static-check request, file-selection, and execution facts [`src/core/agent-tool-json.ts`]
+      - `runGitCheck(...)`: validate runtime repository cleanliness [`src/core/tool-runner.ts`]
+      - `buildGitCheckToolPayload(...)`: structure git-validation status and execution facts [`src/core/agent-tool-json.ts`]
+      - `buildDocsCheckToolPayload(...)`: structure canonical-doc presence and remediation facts [`src/core/agent-tool-json.ts`]
+      - `runGitWtName(...)`: generate the standardized worktree name [`src/core/tool-runner.ts`]
+      - `buildWorktreeNameToolPayload(...)`: structure worktree-name generation facts [`src/core/agent-tool-json.ts`]
+      - `runGitWtCreate(...)`: create a dedicated worktree and branch [`src/core/tool-runner.ts`]
+      - `runGitWtDelete(...)`: delete a dedicated worktree and branch [`src/core/tool-runner.ts`]
+      - `buildWorktreeMutationToolPayload(...)`: structure worktree create/delete facts [`src/core/agent-tool-json.ts`]
+      - `buildToolExecutionSection(...)`: normalize stdout, stderr, and exit-code metadata [`src/core/agent-tool-json.ts`]
+      - `normalizeToolFailure(...)`: convert `ReqError` failures into structured execution records [`src/core/agent-tool-json.ts`]
+    - `registerConfigCommands(...)`: register interactive configuration commands [`src/index.ts`]
+      - `configurePiUsereq(...)`: interactive configuration menu root [`src/index.ts`]
+      - `configurePiUsereq(...)`: serve the inline `show-config` action inside the shared settings-menu flow [`src/index.ts`]
+        - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
+        - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+          - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+          - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+            - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+          - `normalizePiNotifySoundLevel(...)`: normalize persisted sound level [`src/core/pi-notify.ts`]
+          - `normalizePiNotifyShortcut(...)`: normalize persisted shortcut [`src/core/pi-notify.ts`]
+          - `normalizePiNotifyCommand(...)`: normalize persisted sound commands [`src/core/pi-notify.ts`]
+        - `isInsideGitRepo(...)`: probe git repository membership [`src/core/tool-runner.ts`]
+          - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
+        - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
+          - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
+    - `registerPiNotifyShortcut(...)`: register the configured successful-run sound shortcut when the runtime supports shortcuts [`src/index.ts`]
+      - `loadProjectConfig(...)`: load config for shortcut registration [`src/index.ts`]
+        - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
+        - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+          - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+          - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+            - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+          - `normalizePiNotifySoundLevel(...)`: normalize persisted sound level [`src/core/pi-notify.ts`]
+          - `normalizePiNotifyShortcut(...)`: normalize persisted shortcut [`src/core/pi-notify.ts`]
+          - `normalizePiNotifyCommand(...)`: normalize persisted sound commands [`src/core/pi-notify.ts`]
+        - `isInsideGitRepo(...)`: probe git repository membership [`src/core/tool-runner.ts`]
+          - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
+        - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
+          - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
+    - `registerExtensionStatusHooks(...)`: register shared wrappers for lifecycle telemetry hooks [`src/index.ts`]
+      - `handleExtensionStatusEvent(...)`: process intercepted hook payloads through shared status helpers [`src/index.ts`]
+        - `loadProjectConfig(...)`: session-start configuration load [`src/index.ts`]
+          - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
+          - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+            - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+            - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+              - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+          - `isInsideGitRepo(...)`: probe git repository membership [`src/core/tool-runner.ts`]
+            - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
+          - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
+            - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
+        - `applyConfiguredPiUsereqTools(...)`: enable configured active tools on `session_start` [`src/index.ts`]
+          - `getConfiguredEnabledPiUsereqTools(...)`: canonicalize configured enabled tools [`src/index.ts`]
+            - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
+          - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory [`src/index.ts`]
+        - `setPiUsereqStatusConfig(...)`: cache docs/tests/src and pi-notify values for later status renders [`src/core/extension-status.ts`]
+        - `updateExtensionStatus(...)`: refresh stored context usage, timers, and rendered status text [`src/core/extension-status.ts`]
+          - `refreshContextUsage(...)`: sync the latest context-usage snapshot [`src/core/extension-status.ts`]
+          - `syncPiUsereqStatusTicker(...)`: start or stop the live elapsed-time ticker [`src/core/extension-status.ts`]
+          - `renderPiUsereqStatus(...)`: render the docs/tests/src/tools/context/elapsed/last/beep/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
+            - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
+            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with active-theme field and overlay semantics [`src/core/extension-status.ts`]
+              - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
+              - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
+              - `formatContextUsageBar(...)`: render the 5-cell context bar or threshold-specific overlay [`src/core/extension-status.ts`]
+                - `resolveContextUsageOverlay(...)`: choose `CLEAR` or `FULL!` overlay states with CLI-supported theme tokens [`src/core/extension-status.ts`]
+                - `formatContextUsageOverlay(...)`: paint the fixed-width overlay with preserved bar background [`src/core/extension-status.ts`]
+              - `formatStatusDuration(...)`: render `M:SS` durations [`src/core/extension-status.ts`]
+              - `formatPiNotifyBeepStatus(...)`: serialize enabled beep flags for the footer [`src/core/pi-notify.ts`]
+        - `runPiNotifyEffects(...)`: dispatch configured terminal beeps and successful-run sound hooks on `agent_end` [`src/core/pi-notify.ts`]
+          - `classifyPiNotifyOutcome(...)`: map assistant stop reasons to `end`, `esc`, or `err` [`src/core/pi-notify.ts`]
+            - `hasAgentEndStopReason(...)`: scan assistant stop reasons inside the `agent_end` payload [`src/core/pi-notify.ts`]
+          - `buildPiNotifyTitle(...)`: build the stable pi-notify title [`src/core/pi-notify.ts`]
+          - `buildPiNotifyBody(...)`: build the stable pi-notify body from the classified outcome [`src/core/pi-notify.ts`]
+          - `notifyPiTerminal(...)`: route terminal notifications by runtime environment when the matching beep flag is enabled [`src/core/pi-notify.ts`]
+            - `notifyWindows(...)`: emit Windows toast notifications [`src/core/pi-notify.ts`]
+            - `notifyOSC99(...)`: emit Kitty OSC 99 notifications [`src/core/pi-notify.ts`]
+            - `notifyOSC9(...)`: emit OSC 9 notifications [`src/core/pi-notify.ts`]
+            - `notifyOSC777(...)`: emit OSC 777 notifications [`src/core/pi-notify.ts`]
+          - `runPiNotifySoundCommand(...)`: execute the configured successful-run sound command when sound is enabled [`src/core/pi-notify.ts`]
+            - `resolvePiNotifySoundCommand(...)`: select the configured command for `low`, `mid`, or `high` [`src/core/pi-notify.ts`]
+            - `substitutePiNotifyInstallPath(...)`: replace `%%INSTALLATION_PATH%%` before shell execution [`src/core/pi-notify.ts`]
+              - `quotePiNotifyInstallPath(...)`: quote the installation path for shell reuse [`src/core/pi-notify.ts`]
+              - `getInstallationPath(...)`: resolve the installed extension root [`src/core/path-context.ts`]
+  - `configurePiUsereq(...)`: interactive configuration menu runtime root [`src/index.ts`]
+    - `loadProjectConfig(...)`: load config and normalize persisted directory paths for command context [`src/index.ts`]
+      - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
+      - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
+        - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+        - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
+          - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+      - `isInsideGitRepo(...)`: probe git repository membership [`src/core/tool-runner.ts`]
+        - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
+      - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
+        - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
+    - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
+    - `showPiUsereqSettingsMenu(...)`: render the shared settings-menu UI for top-level and submenu actions [`src/core/settings-menu.ts`]
+      - `formatPiUsereqSettingsMenuTitle(...)`: rebuild the menu title with active-theme semantics [`src/core/settings-menu.ts`]
+      - `buildPiUsereqSettingsListTheme(...)`: prefer shared CLI settings-list theming and fall back during offline replay [`src/core/settings-menu.ts`]
+        - `buildFallbackPiUsereqSettingsListTheme(...)`: mirror CLI settings-list token roles from the callback-local theme [`src/core/settings-menu.ts`]
+    - `saveProjectConfig(...)`: persist config on save-and-close [`src/index.ts`]
+      - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
+      - `saveConfig(...)`: persist config JSON [`src/core/config.ts`]
+        - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+    - `setPiUsereqStatusConfig(...)`: cache the just-saved docs/tests/src and pi-notify values for status rendering [`src/core/extension-status.ts`]
+    - `renderPiUsereqStatus(...)`: render the git/base/docs/tests/src/tools/context/elapsed/last/beep/sound footer after save-and-close with CLI-theme token overlays [`src/core/extension-status.ts`]
+      - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
+      - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with active-theme field and overlay semantics [`src/core/extension-status.ts`]
+        - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
+        - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
+        - `formatContextUsageBar(...)`: render the 5-cell context bar or threshold-specific overlay [`src/core/extension-status.ts`]
+          - `resolveContextUsageOverlay(...)`: choose `CLEAR` or `FULL!` overlay states with CLI-supported theme tokens [`src/core/extension-status.ts`]
+          - `formatContextUsageOverlay(...)`: paint the fixed-width overlay with preserved bar background [`src/core/extension-status.ts`]
+        - `formatStatusDuration(...)`: render `M:SS` durations [`src/core/extension-status.ts`]
+        - `formatPiNotifyBeepStatus(...)`: serialize enabled beep flags for the footer [`src/core/pi-notify.ts`]
+    - `configureStaticCheckMenu(...)`: interactive static-check editor [`src/index.ts`]
+      - `formatStaticCheckLanguagesSummary(...)`: summarize configured checker languages [`src/index.ts`]
+      - `renderStaticCheckReference(...)`: render static-check reference text [`src/index.ts`]
+        - `formatStaticCheckLanguagesSummary(...)`: summarize configured checker languages [`src/index.ts`]
+        - `formatStaticCheckEntry(...)`: format one configured checker entry [`src/index.ts`]
+        - `getSupportedStaticCheckLanguageSupport(...)`: enumerate supported languages and extensions [`src/core/static-check.ts`]
+          - `getSupportedStaticCheckLanguages(...)`: enumerate canonical supported languages [`src/core/static-check.ts`]
+      - `buildSupportedStaticCheckLanguageChoices(...)`: serialize supported languages with configured counts [`src/index.ts`]
+      - `shellSplit(...)`: parse optional parameter input [`src/core/utils.ts`]
+      - `parseEnableStaticCheck(...)`: parse `LANG=MODULE[,CMD[,PARAM...]]` specification [`src/core/static-check.ts`]
+        - `splitCsvLikeTokens(...)`: split comma-like spec payload with quoting support [`src/core/static-check.ts`]
+        - `formatStaticCheckModules(...)`: render valid module names for error paths [`src/core/static-check.ts`]
+    - `configurePiUsereqToolsMenu(...)`: interactive active-tool editor [`src/index.ts`]
+      - `applyConfiguredPiUsereqTools(...)`: enforce configured active-tool set [`src/index.ts`]
+        - `getConfiguredEnabledPiUsereqTools(...)`: canonicalize configured enabled tools [`src/index.ts`]
+          - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
+        - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory [`src/index.ts`]
+      - `renderPiUsereqToolsReference(...)`: render configurable active-tool reference text [`src/index.ts`]
+        - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory [`src/index.ts`]
+        - `getConfiguredEnabledPiUsereqTools(...)`: canonicalize configured enabled tools [`src/index.ts`]
+          - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
+        - `getPiUsereqToolKind(...)`: classify builtin versus extension tools for UI rendering [`src/index.ts`]
+      - `setConfiguredPiUsereqTools(...)`: persist selected enabled tools in memory [`src/index.ts`]
+        - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
+        - `applyConfiguredPiUsereqTools(...)`: enforce configured active-tool set [`src/index.ts`]
+          - `getConfiguredEnabledPiUsereqTools(...)`: canonicalize configured enabled tools [`src/index.ts`]
+            - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
+          - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory [`src/index.ts`]
+      - `buildPiUsereqToolToggleChoices(...)`: serialize per-tool startup-toggle rows [`src/index.ts`]
+        - `getPiUsereqToolKind(...)`: classify builtin versus extension tools for UI rendering [`src/index.ts`]
+    - `configurePiNotifyMenu(...)`: interactive pi-notify editor [`src/index.ts`]
+      - `buildPiNotifyMenuChoices(...)`: serialize notification actions for the shared settings menu [`src/index.ts`]
+      - `togglePiNotifyBeepFlag(...)`: toggle one prompt-end beep flag [`src/index.ts`]
+    - `getDefaultConfig(...)`: restore default config on reset [`src/core/config.ts`]
+      - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
+    - `applyConfiguredPiUsereqTools(...)`: re-apply active tools after reset [`src/index.ts`]
+      - `getConfiguredEnabledPiUsereqTools(...)`: canonicalize configured enabled tools [`src/index.ts`]
+        - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
+      - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory [`src/index.ts`]
+- External Boundaries:
+  - pi ExtensionAPI plus command-context APIs for command registration, tool registration, shortcut registration, user-message delivery, session events, active-tool mutation, editor updates, notifications, selections, and text input.
+  - Filesystem access for home resource cache, bundled prompt reads, and project config persistence.
+  - Git and static-check subprocesses reused through the same tool-runner and static-check functions documented under `PROC:main`.
+
+### `PROC:gh-release-check`
+- Entrypoints:
+  - `check-branch(...)`: GitHub Actions release-gate job root [`.github/workflows/release-npm.yml`]
+- Lifecycle/trigger:
+  - Start trigger: GitHub Actions starts the job for pushed tags matched by the workflow tag filter.
+  - Stop trigger: writes the `is_master` job output after `origin/master` containment evaluation.
+  - Looping model: single-pass job with sequential step execution.
+  - Threads: no explicit threads detected.
+- Internal Call-Trace Tree:
+  - `check-branch(...)`: fetch `origin/master`, evaluate tagged-commit containment, and export the downstream gate flag [`.github/workflows/release-npm.yml`]
+    - External boundaries: `actions/checkout@v4`, GitHub Actions runner shell, `git` CLI, `grep`, and `$GITHUB_OUTPUT`.
+- External Boundaries:
+  - GitHub Actions event routing, hosted-runner lifecycle, checkout action, git subprocesses, and runner output channels.
+
+### `PROC:gh-release-build`
+- Entrypoints:
+  - `build-release(...)`: GitHub Actions npm-and-release job root [`.github/workflows/release-npm.yml`]
+- Lifecycle/trigger:
+  - Start trigger: GitHub Actions starts the job only when `PROC:gh-release-check` exports `is_master=true`.
+  - Stop trigger: returns runner success after npm publication, changelog generation, and GitHub Release creation or runner failure on action errors.
+  - Looping model: single-pass job with sequential step execution.
+  - Threads: no explicit threads detected.
+- Internal Call-Trace Tree:
+  - `build-release(...)`: checkout repository content, configure Node.js for npm, install dependencies, remove manifest `private`, publish the package, build changelog text, and create the GitHub Release [`.github/workflows/release-npm.yml`]
+    - External boundaries: `actions/checkout@v4`, `actions/setup-node@v4`, npm CLI, npm registry, OIDC token issuance, `mikepenz/release-changelog-builder-action@v6`, `softprops/action-gh-release@v2`, `secrets.NPM_TOKEN`, and `secrets.GITHUB_TOKEN`.
+- External Boundaries:
+  - GitHub Actions event routing, hosted-runner lifecycle, checkout action, setup-node action, npm CLI, npm registry, changelog-builder action, GitHub Releases API, and repository secrets.
+
+## Communication Edges
+- `PROC:req-debug` -> `PROC:tool-args-to-params`
+  - Mechanism: child-process spawn through resolved `tsx` executable.
+  - Endpoint/channel: CLI argv plus captured stdout/stderr.
+  - Payload/data-shape: wrapper tool name plus raw `--args` text, returned as one serialized JSON params object [`scripts/pi-usereq-debug.sh`, `scripts/tool-args-to-params.ts`]
+- `PROC:req-debug` -> `PROC:debug-ext`
+  - Mechanism: child-process spawn through resolved `tsx` executable.
+  - Endpoint/channel: CLI argv plus inherited stdout/stderr.
+  - Payload/data-shape: wrapper-normalized subcommand and forwarded debug-harness options with default `--cwd` and `--extension` values, including rewritten tool `--params` JSON when `--args` was supplied [`scripts/pi-usereq-debug.sh`, `scripts/debug-extension.ts`]
+- `PROC:gh-release-check` -> `PROC:gh-release-build`
+  - Mechanism: GitHub Actions `needs` dependency plus job-output gating.
+  - Endpoint/channel: `is_master` job output and shared tag-run context.
+  - Payload/data-shape: boolean branch-gate flag derived from `origin/master` containment for the tagged commit [`.github/workflows/release-npm.yml`]
+- Internal thread communication edges: none.
+- Relationship note: `PROC:main`, `PROC:req-debug`, `PROC:tool-args-to-params`, `PROC:debug-ext`, `PROC:pi-host`, `PROC:gh-release-check`, and `PROC:gh-release-build` are distinct runtime entry modes; only `PROC:req-debug` directly spawns child processes, while the GitHub Actions units coordinate through workflow job dependencies.