Compact pvs skill; fix PVS-Studio -S/--dump-files docs in AGENTS.md

The AGENTS.md '-S src/foo.c' example was inaccurate: -S takes a plaintext
file listing source paths, not paths directly. Drop --dump-files from the
documented commands (it scatters .PVS-Studio.i/.cfg dumps across the tree;
FP-debugging only) and reference the new pvs skill.

https://claude.ai/code/session_015inWmFhRYSq17CxMukdoqX

2 files changed, 31 insertions, 65 deletions

diff --git a/.claude/skills/pvs/SKILL.md b/.claude/skills/pvs/SKILL.md
index cde453d9a..bc4bf01bd 100644
--- a/.claude/skills/pvs/SKILL.md
+++ b/.claude/skills/pvs/SKILL.md
@@ -1,74 +1,36 @@
 ---
 name: pvs
-description: Use when running PVS-Studio static analysis (SAST + MISRA C:2023 / C++:2008) on TinyUSB for a given board. Wraps building the examples with an exported compile_commands.json and running pvs-studio-analyzer against .PVS-Studio/.pvsconfig, then converts the log to readable + SARIF output.
+description: Use when running PVS-Studio static analysis (SAST + MISRA C:2023 / C++:2008) on TinyUSB for a given board. Builds the examples with an exported compile_commands.json, runs pvs-studio-analyzer against .PVS-Studio/.pvsconfig, and emits readable + SARIF output.
 ---
 
 # PVS-Studio Static Analysis
 
-Run PVS-Studio on TinyUSB for one board. The skill bundles `run_pvs.sh`, which
-follows the "Static Analysis (PVS-Studio)" section of AGENTS.md / CLAUDE.md:
-build all examples for the board with `compile_commands.json` exported, run
-`pvs-studio-analyzer` against it using `.PVS-Studio/.pvsconfig`, then convert the
-log to an `errorfile` view and a SARIF report.
-
-## Quick start
+`run_pvs.sh <BOARD>` builds all examples for the board (with
+`compile_commands.json` exported), runs `pvs-studio-analyzer` against
+`.PVS-Studio/.pvsconfig`, then writes `pvs-<board>.log` and `pvs-<board>.sarif`
+plus printed errorfile findings. Needs a license file or `$PVS_STUDIO_CREDENTIALS`.
 
 ```bash
-# Whole project for a board:
-.claude/skills/pvs/run_pvs.sh raspberry_pi_pico
+.claude/skills/pvs/run_pvs.sh raspberry_pi_pico       # whole project for a board
 
-# Specific files only — -S takes a plaintext list (one path per line), NOT a
-# source file directly (the AGENTS.md "-S src/foo.c" snippet is inaccurate):
+# Scope to specific files — -S takes a plaintext list (one path per line),
+# NOT a source file directly. Extra args pass through to the analyzer.
 printf 'src/tusb.c\nsrc/class/cdc/cdc_device.c\n' > /tmp/files.txt
 .claude/skills/pvs/run_pvs.sh stm32f407disco -S /tmp/files.txt
 ```
 
-The first positional argument is **BOARD** (required). Everything after it is
-forwarded verbatim to `pvs-studio-analyzer analyze`.
-
-## What the script does
-
-1. **License** — if no license file is registered, materializes one from the
-   `PVS_STUDIO_CREDENTIALS` env var (`<name> <key>`, same secret CI uses).
-2. **Build** — `cmake examples -B examples/cmake-build-<board> -G Ninja
-   -DBOARD=<board> -DCMAKE_BUILD_TYPE=MinSizeRel -DCMAKE_EXPORT_COMPILE_COMMANDS=ON`
-   then `cmake --build`. The exported `compile_commands.json` is what PVS reads.
-3. **Analyze** — `pvs-studio-analyzer analyze -f <compile_db>
-   -R .PVS-Studio/.pvsconfig -o pvs-<board>.log -j<nproc>
-   --misra-c-version 2023 --misra-cpp-version 2008 --use-old-parser`.
-   (AGENTS.md shows `--dump-files`; it's omitted because it scatters
-   `.PVS-Studio.i/.cfg` dumps across the tree — only useful for debugging FPs.)
-4. **Report** — `plog-converter -a GA:1,2 -t errorfile` (printed) and
-   `-t sarif` → `pvs-<board>.sarif`.
-
-`.PVS-Studio/.pvsconfig` already excludes vendored code (`lib/`, `hw/mcu/`,
-`pico-sdk/`, `esp-idf/`, IAR runtime) and suppresses the project's accepted
-MISRA deviations — don't duplicate those excludes on the command line.
-
-## Choosing a board
-
-Match the build prerequisites (same as the rest of the repo):
-
-- `raspberry_pi_pico` — what CI's PVS-Studio job uses (needs Pico SDK deps).
-- `stm32f407disco` — no external SDK; fastest to get a clean compile DB.
-- Anything under `hw/bsp/<family>/boards/` works if its deps are fetched
-  (`python3 tools/get_deps.py -b <board>`).
-
-## Outputs
-
-- `pvs-<board>.log` — raw analyzer log (input to plog-converter).
-- `pvs-<board>.sarif` — SARIF report (same format CI uploads).
-- errorfile findings are printed to stdout for a quick read.
-
-## Timing
-
-Dominated by the example build (tens of seconds to a few minutes depending on
-board/deps). The analysis pass itself is ~10-30 s. Use a timeout ≥ 10 minutes
-for boards whose deps must be fetched/built first.
+## Notes
 
-## Reporting results
+- **Board:** `raspberry_pi_pico` mirrors CI (needs Pico SDK deps);
+  `stm32f407disco` is fastest (no external SDK). Any board works once its deps
+  are fetched (`python3 tools/get_deps.py -b <board>`).
+- `.pvsconfig` already excludes vendored code and suppresses accepted MISRA
+  deviations — don't re-add those on the command line. Surviving `src/` findings
+  are genuinely new.
+- Timing is dominated by the build (deps may push it past a minute); the analysis
+  pass is ~10-30 s. Use a timeout ≥ 10 min when deps must be fetched first.
+- `--dump-files` is intentionally omitted — it scatters `.PVS-Studio.i/.cfg`
+  dumps across the tree (FP-debugging only); add it back via the passthrough args.
 
-After a run, summarize the findings by rule/severity from the errorfile output
-and point the user at `pvs-<board>.sarif`. Cross-check anything flagged in
-`src/` against `.pvsconfig` — if it's an already-accepted deviation it will have
-been suppressed, so surviving findings are genuinely new.
+After a run, summarize findings by rule/severity from the errorfile output and
+point the user at `pvs-<board>.sarif`.
diff --git a/AGENTS.md b/AGENTS.md
index 5c9908d19..8ea650ecb 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -153,28 +153,32 @@ Reports land in `cmake-metrics/<board>/metrics_compare.md` (per-board) and `cmak
 
 ## Static Analysis (PVS-Studio)
 
-Requires `compile_commands.json` (CMake `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON`).
+Requires `compile_commands.json` (CMake `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON`). The
+`pvs` skill (`.claude/skills/pvs/SKILL.md`) wraps the build + analyze flow for a
+board; the commands below are the underlying steps.
 
 ```bash
 # Whole project:
 pvs-studio-analyzer analyze \
   -f examples/cmake-build-raspberry_pi_pico/compile_commands.json \
   -R .PVS-Studio/.pvsconfig \
-  -o pvs-report.log -j12 --dump-files \
+  -o pvs-report.log -j12 \
   --misra-c-version 2023 --misra-cpp-version 2008 --use-old-parser
 
-# Specific files (add one or more `-S <file>`):
+# Specific files: -S takes a plaintext list (one path per line), not paths directly:
+printf 'src/foo.c\nsrc/bar.c\n' > files.txt
 pvs-studio-analyzer analyze \
   -f examples/cmake-build-raspberry_pi_pico/compile_commands.json \
   -R .PVS-Studio/.pvsconfig \
-  -S src/foo.c -S src/bar.c \
-  -o pvs-report.log -j12 --dump-files \
+  -S files.txt \
+  -o pvs-report.log -j12 \
   --misra-c-version 2023 --misra-cpp-version 2008 --use-old-parser
 
 plog-converter -a GA:1,2 -t errorfile pvs-report.log     # view results
 ```
 
-Takes ~10-30 s.
+Takes ~10-30 s. (`--dump-files` adds preprocessed `.PVS-Studio.i/.cfg` dumps next
+to every source for false-positive debugging — omit it for normal runs.)
 
 ## Validation After Changes