diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 43d5471..b60221c 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -12,7 +12,7 @@
       "name": "bmad-builder",
       "source": "./",
       "description": "Build AI agents, workflows, and modules from a conversation. Four skills — Agent Builder, Workflow Builder, Module Builder, and Setup — guide you from idea to production-ready skill structure with built-in quality optimization. Part of the BMad Method ecosystem.",
-      "version": "2.1.0",
+      "version": "2.2.0",
       "author": {
         "name": "Brian (BMad) Madison"
       },
@@ -22,7 +22,7 @@
       "name": "sample-plugins",
       "source": "./",
       "description": "Sample plugins demonstrating how to build BMad agents and skills. Includes a code coach, creative muse, diagram reviewer, dream weaver, sentinel, and excalidraw generator.",
-      "version": "2.1.0",
+      "version": "2.2.0",
       "author": {
         "name": "Brian (BMad) Madison"
       },
@@ -40,7 +40,7 @@
       "name": "bmad-dream-weaver-agent",
       "source": "./",
       "description": "Dream journaling and interpretation agent with lucid dreaming coaching, pattern discovery, symbol analysis, and recall training.",
-      "version": "2.1.0",
+      "version": "2.2.0",
       "author": {
         "name": "Brian (BMad) Madison"
       },
diff --git a/CHANGELOG.md b/CHANGELOG.md
index cecadd6..5745e39 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,16 +1,36 @@
 # Changelog
 
+## [2.2.0] - 2026-08-09
+
+### 🐛 Fixes
+
+- **`uv run` conversion finished across the remaining skills** — v2.1.0 claimed `uv run` was standardized across builder scripts, but #98 reached only `bmad-agent-builder` and `bmad-workflow-builder`. `bmad-bmb-setup`, `bmad-module-builder`, and `bmad-eval-runner` were missed. This converts the remaining 57 invocations across `skills/`, `samples/`, and `docs/how-to/`. It matters beyond consistency: a bare `python3` is not guaranteed to be 3.11+, which BMad's shared `resolve_customization.py` requires for `tomllib`, and `uv run` reads a script's own `requires-python` and provisions a matching interpreter (#105).
+
+- **Emitted templates no longer pass the defect on** — five of the fixes are in `assets/setup-skill-template/` and `assets/standalone-module-template/`, so every module scaffolded by `bmad-module-builder` stops inheriting bare-`python3` invocations. This also closes a visible seam: `init-sanctum-template.py` had been converted in #98, but the three `samples/*/scripts/init-sanctum.py` copies generated from it still said `python3` (#105).
+
+- **pytest docstrings call `uv run --with pytest -m pytest`** — the eval-runner and workflow-builder test files carry no PEP 723 block, so `uv run -m pytest` alone has nothing to resolve pytest from. Matches the convention in BMAD-METHOD (#105).
+
+- **README Python badge corrected to `>=3.11`** — it advertised `>=3.10`, a floor that cannot run the shared resolver (#105).
+
+### 🔧 Maintenance
+
+- **Marketplace plugin versions synced to 2.2.0** — nothing in the release workflow touches `.claude-plugin/marketplace.json`, so its versions drift from `package.json` unless bumped by hand.
+
+### Notes
+
+- Deliberately unconverted: the two anti-pattern cells in `docs/explanation/` (`scripts-in-skills.md`, labelled **Fragile**, and `skill-authoring-best-practices.md`, labelled "do not modify") — they teach what not to do; the "runs under a bare python3" prose in `count_tokens.py` and `prepass.py`, which describes a script's lack of third-party dependencies rather than invoking anything; and the per-script `requires-python` floors, which are correct as written.
+
 ## [2.1.0] - 2026-06-22
 
 ### 🐛 Fixes
 
-* **Standalone module validation hardening** — `validate-module.py` no longer emits false-positive findings for correctly-structured standalone single-skill modules. It now accepts either `merge-config.py`/`merge_config.py` naming (dash or importable underscore form), skips colon-less `preceded-by`/`followed-by` cross-module refs that are unresolvable in isolation while still validating intra-module `skill:action` refs, and recognizes a module when handed its own skill directory directly (#97).
+- **Standalone module validation hardening** — `validate-module.py` no longer emits false-positive findings for correctly-structured standalone single-skill modules. It now accepts either `merge-config.py`/`merge_config.py` naming (dash or importable underscore form), skips colon-less `preceded-by`/`followed-by` cross-module refs that are unresolvable in isolation while still validating intra-module `skill:action` refs, and recognizes a module when handed its own skill directory directly (#97).
 
 ### 🔧 Maintenance
 
-* **Builders use runtime-installed memlog** — Workflow Builder and Agent Builder now point at the shared runtime memlog CLI at `{project-root}/_bmad/scripts/memlog.py` instead of each bundling its own copy. Removes drift between copies; `{project-root}` resolves at runtime so the call works from any skill root. Bundled `scripts/memlog.py` copies (and the workflow-builder memlog test) were deleted, and the obsolete "copy the CLI into each built skill" guidance was rewritten (#98).
+- **Builders use runtime-installed memlog** — Workflow Builder and Agent Builder now point at the shared runtime memlog CLI at `{project-root}/_bmad/scripts/memlog.py` instead of each bundling its own copy. Removes drift between copies; `{project-root}` resolves at runtime so the call works from any skill root. Bundled `scripts/memlog.py` copies (and the workflow-builder memlog test) were deleted, and the obsolete "copy the CLI into each built skill" guidance was rewritten (#98).
 
-* **`uv run` standardized across builder scripts** — Prompt-facing script invocations, usage strings, and emitted init-sanctum/wake templates now call `uv run <script>` instead of `python3 <script>`; `script-standards.md` mandates it. Shebangs (`#!/usr/bin/env python3`), capability notes, and `python3 -m pytest` docstrings are intentionally left as-is (#98).
+- **`uv run` standardized across builder scripts** — Prompt-facing script invocations, usage strings, and emitted init-sanctum/wake templates now call `uv run <script>` instead of `python3 <script>`; `script-standards.md` mandates it. Shebangs (`#!/usr/bin/env python3`), capability notes, and `python3 -m pytest` docstrings are intentionally left as-is (#98).
 
 ## [2.0.0] - 2026-06-13
 
@@ -24,178 +44,178 @@ This is a near-total rebuild of the BMad builders around one conviction: **the p
 
 ### 💥 Breaking Changes
 
-* **Workflow Builder and Eval Runner rebuilt** — The build flow moved from the fixed 5-phase lockstep to a single Process loop; the rigid report-data schema and the `generate-html-report.py` / `extract-report-json.py` pipeline were retired in favor of scanners that return lean JSON in-context plus one report-author filling a stable HTML shell. Skills built with the prior version remain valid, but the build *process* and its outputs differ. The Eval Runner dropped Docker, PTY, keychain staging, and dual isolation in favor of a lean, standalone-or-builder-invoked design.
-* **`customize.toml` is the sole customization mechanism** — Installer questions and `module.yaml` authoring are no longer part of net-new builds; the build flow asks once and defaults to no. Both builders now ship their *own* `customize.toml` with wired org knobs (build standards, eval ship-gate, SKILL.md token tiers).
-* **`--pulse` replaces the built agent's `--headless`** — Autonomous agents now wake on a schedule via `--pulse` (and `--pulse {task-name}` for named task routing); "Quiet Rebirth" is now "Pulse Mode" / Quiet Waking. The builder's own `--headless` flag for non-interactive *builds* is unchanged.
-* **`memlog` replaces `.decision-log.md`** — Build decisions are recorded through a typed, append-only `memlog.py` rather than a free-form decision log.
-* **Token budgets replace line counts** — Length is now measured with `count_tokens.py` (tiktoken) everywhere; line-count rules are gone.
+- **Workflow Builder and Eval Runner rebuilt** — The build flow moved from the fixed 5-phase lockstep to a single Process loop; the rigid report-data schema and the `generate-html-report.py` / `extract-report-json.py` pipeline were retired in favor of scanners that return lean JSON in-context plus one report-author filling a stable HTML shell. Skills built with the prior version remain valid, but the build _process_ and its outputs differ. The Eval Runner dropped Docker, PTY, keychain staging, and dual isolation in favor of a lean, standalone-or-builder-invoked design.
+- **`customize.toml` is the sole customization mechanism** — Installer questions and `module.yaml` authoring are no longer part of net-new builds; the build flow asks once and defaults to no. Both builders now ship their _own_ `customize.toml` with wired org knobs (build standards, eval ship-gate, SKILL.md token tiers).
+- **`--pulse` replaces the built agent's `--headless`** — Autonomous agents now wake on a schedule via `--pulse` (and `--pulse {task-name}` for named task routing); "Quiet Rebirth" is now "Pulse Mode" / Quiet Waking. The builder's own `--headless` flag for non-interactive _builds_ is unchanged.
+- **`memlog` replaces `.decision-log.md`** — Build decisions are recorded through a typed, append-only `memlog.py` rather than a free-form decision log.
+- **Token budgets replace line counts** — Length is now measured with `count_tokens.py` (tiktoken) everywhere; line-count rules are gone.
 
 ### 🎁 Highlights
 
-* **The prompt-quality canon** — `prompt-quality-canon.md` is the single statement of the universal quality tests (the core test, "who reads this," "most fixes are truncation not deletion," the two-version comparison, progressive disclosure). It ships embedded in both builders, kept byte-identical by `test_canon_sync.py`, pulled in on demand, and published as a docs page. Lenses and fix prompts cite it rather than carrying their own copies.
-* **Every emitted skill passes its own lint** — The cross-directory `./` path defect that made every shipped template, sample, and init script fail `scan-path-standards` (33 findings) is fixed; all paths are normalized to the bare skill-root convention, including the strings the init scripts generate into a sanctum.
-* **Eval Runner closes the loop** — Four modes (baseline skill-vs-bare-model, variant full-vs-stripped, quality, trigger), a turn-simulation case format (input + rubric + optional state prefix), a bounded self-improvement loop, and a platform-adapter seam that puts everything runtime-specific (invocation command, auth env var, transcript schema, trigger signals) behind one file. No hardcoded model list anywhere.
-* **Deterministic report v2** — Scanners return lean findings JSON in-context; a single report-author fills a self-contained HTML shell with one JSON island that cannot render blank, with multi-select and copy-to-paste-back fix prompts. Fix prompts now carry the same standards preamble that produced the findings, so the session applying a fix holds the bar that found it.
-* **Continuity-of-self agents** — A one-pass `wake.py` loads an agent's whole sanctum on activation and routes it to Waking / First Breath / Pulse; the bootloader activation is a four-step "Invoke & hold" spine (Wake → Become yourself → Bind standing rules for the whole session → Execute the proper mode); new **Stay in Character** and **Persistent Memory (Critical Directive)** directives keep the agent in persona and capturing memory as-you-go rather than only at session close.
+- **The prompt-quality canon** — `prompt-quality-canon.md` is the single statement of the universal quality tests (the core test, "who reads this," "most fixes are truncation not deletion," the two-version comparison, progressive disclosure). It ships embedded in both builders, kept byte-identical by `test_canon_sync.py`, pulled in on demand, and published as a docs page. Lenses and fix prompts cite it rather than carrying their own copies.
+- **Every emitted skill passes its own lint** — The cross-directory `./` path defect that made every shipped template, sample, and init script fail `scan-path-standards` (33 findings) is fixed; all paths are normalized to the bare skill-root convention, including the strings the init scripts generate into a sanctum.
+- **Eval Runner closes the loop** — Four modes (baseline skill-vs-bare-model, variant full-vs-stripped, quality, trigger), a turn-simulation case format (input + rubric + optional state prefix), a bounded self-improvement loop, and a platform-adapter seam that puts everything runtime-specific (invocation command, auth env var, transcript schema, trigger signals) behind one file. No hardcoded model list anywhere.
+- **Deterministic report v2** — Scanners return lean findings JSON in-context; a single report-author fills a self-contained HTML shell with one JSON island that cannot render blank, with multi-select and copy-to-paste-back fix prompts. Fix prompts now carry the same standards preamble that produced the findings, so the session applying a fix holds the bar that found it.
+- **Continuity-of-self agents** — A one-pass `wake.py` loads an agent's whole sanctum on activation and routes it to Waking / First Breath / Pulse; the bootloader activation is a four-step "Invoke & hold" spine (Wake → Become yourself → Bind standing rules for the whole session → Execute the proper mode); new **Stay in Character** and **Persistent Memory (Critical Directive)** directives keep the agent in persona and capturing memory as-you-go rather than only at session close.
 
 ### ♻️ Refactoring
 
-* **Reference corpus consolidation** — Workflow Builder references went 18 → 17 files and the Agent Builder 26 → 23; a single `lens-contract.md` in each builder states the lens return schema once and all twelve lens files point at it. Three agent samples that were 80–88% line-identical stale copies of their own templates were deleted, with `build-process` rewired to emit from the templates directly.
-* **Lenses load their own lane's spec** — Customization lenses load the toml guide, determinism lenses load the script standards; per-lens subagent context dropped by roughly half. `skill-quality-principles.md` was cut to pure BMad institutional knowledge (the canon-restating sections are gone), and the memlog treatment was relocated off the hot file into `working-state-patterns.md`.
-* **Agent Builder realigned to the rebuild** — Eight quality-scan files folded into six base lenses plus a conditional sanctum-architecture lens; `memlog.py`, `count_tokens.py`, and `prepass.py` vendored in; the template+renderer report path replaced by the self-contained HTML shell; `template-substitution-rules.md` rewritten (legacy `{if-memory}`/`{if-headless}` archaeology removed).
-* **Continuity reframe across templates, validators, samples, and docs** — The Sacred Truth, bootloader, sample agents (code-coach, creative-muse, sentinel, dream-weaver), and validators were regenerated to the new model; `prepass.py` regexes and quality refs were reframed (rebirth → waking, headless-wake → pulse-wake) so new agents are not false-flagged.
-* **Conventions tightened** — Path resolution collapsed into a "Resolution rules" block in both builders; the no-numbered-prefix rule demoted from hard rule to soft preference; `config.yaml` reading is no longer taught to net-new skills.
+- **Reference corpus consolidation** — Workflow Builder references went 18 → 17 files and the Agent Builder 26 → 23; a single `lens-contract.md` in each builder states the lens return schema once and all twelve lens files point at it. Three agent samples that were 80–88% line-identical stale copies of their own templates were deleted, with `build-process` rewired to emit from the templates directly.
+- **Lenses load their own lane's spec** — Customization lenses load the toml guide, determinism lenses load the script standards; per-lens subagent context dropped by roughly half. `skill-quality-principles.md` was cut to pure BMad institutional knowledge (the canon-restating sections are gone), and the memlog treatment was relocated off the hot file into `working-state-patterns.md`.
+- **Agent Builder realigned to the rebuild** — Eight quality-scan files folded into six base lenses plus a conditional sanctum-architecture lens; `memlog.py`, `count_tokens.py`, and `prepass.py` vendored in; the template+renderer report path replaced by the self-contained HTML shell; `template-substitution-rules.md` rewritten (legacy `{if-memory}`/`{if-headless}` archaeology removed).
+- **Continuity reframe across templates, validators, samples, and docs** — The Sacred Truth, bootloader, sample agents (code-coach, creative-muse, sentinel, dream-weaver), and validators were regenerated to the new model; `prepass.py` regexes and quality refs were reframed (rebirth → waking, headless-wake → pulse-wake) so new agents are not false-flagged.
+- **Conventions tightened** — Path resolution collapsed into a "Resolution rules" block in both builders; the no-numbered-prefix rule demoted from hard rule to soft preference; `config.yaml` reading is no longer taught to net-new skills.
 
 ### 📚 Documentation
 
-* **New** `explanation/outcome-driven-prompt-quality.md` — the published source of the prompt-quality canon, synced with the shipped copy.
-* Updated `agent-memory-and-personalization.md`, `what-are-bmad-agents.md`, `customization-for-authors.md`, and `builder-commands.md` for the continuity-of-self model, the `wake.py` loader, the four-step activation, the Stay-in-Character and Persistent-Memory directives, and `--pulse`.
+- **New** `explanation/outcome-driven-prompt-quality.md` — the published source of the prompt-quality canon, synced with the shipped copy.
+- Updated `agent-memory-and-personalization.md`, `what-are-bmad-agents.md`, `customization-for-authors.md`, and `builder-commands.md` for the continuity-of-self model, the `wake.py` loader, the four-step activation, the Stay-in-Character and Persistent-Memory directives, and `--pulse`.
 
 ## [1.8.1] - 2026-05-17
 
 ### 🐛 Fixes
 
-* **Module help catalog header alignment** — Renamed `after`/`before` columns in all `module-help.csv` files (module-level, setup-skill, builder template, samples) to `preceded-by`/`followed-by` to match the canonical 13-column schema introduced in BMAD-METHOD v6.6.0. Warning-only fix; data was already loaded positionally (#89).
+- **Module help catalog header alignment** — Renamed `after`/`before` columns in all `module-help.csv` files (module-level, setup-skill, builder template, samples) to `preceded-by`/`followed-by` to match the canonical 13-column schema introduced in BMAD-METHOD v6.6.0. Warning-only fix; data was already loaded positionally (#89).
 
 ## [1.8.0] - 2026-05-10
 
 ### 🎁 Features
 
-* **New `bmad-eval-runner` skill** — Evaluates a skill's behavior in an isolated workspace (Docker preferred, local fallback) and grades against eval-author expectations. Current supports Claude Code - additional harness and model combinations will come soon.
+- **New `bmad-eval-runner` skill** — Evaluates a skill's behavior in an isolated workspace (Docker preferred, local fallback) and grades against eval-author expectations. Current supports Claude Code - additional harness and model combinations will come soon.
 
-* **Workflow Builder scanner consolidation (7 → 4)** — Same quality, 7 separate scanners were overkill when 4 can cover the same content.
+- **Workflow Builder scanner consolidation (7 → 4)** — Same quality, 7 separate scanners were overkill when 4 can cover the same content.
 
-* **User Experience promoted in HTML report** — User journey analysis now appears as a top-level section in the output.
+- **User Experience promoted in HTML report** — User journey analysis now appears as a top-level section in the output.
 
-* **Headless contract for Workflow Builder** — Build process now supports a complete headless mode with structured JSON output, normalized path conventions, and a Conventions block (#85)
+- **Headless contract for Workflow Builder** — Build process now supports a complete headless mode with structured JSON output, normalized path conventions, and a Conventions block (#85)
 
 ### 💥 Breaking Changes
 
-* **Convert flow removed from Workflow Builder** — Switch to the edit flow - convert was redundant.
+- **Convert flow removed from Workflow Builder** — Switch to the edit flow - convert was redundant.
 
 ## [1.7.0] - 2026-04-23
 
 ### 📚 Documentation
 
-* **Customization authoring flow awareness** — `explanation/customization-for-authors.md` and `how-to/make-a-skill-customizable.md` now mention `bmad-customize`, the conversational authoring helper that walks users through scope selection, override writing, and merge verification. Guides authors to pick field names and defaults that read well in that flow, while preserving that hand-writing TOML still works for users who prefer it (#78)
+- **Customization authoring flow awareness** — `explanation/customization-for-authors.md` and `how-to/make-a-skill-customizable.md` now mention `bmad-customize`, the conversational authoring helper that walks users through scope selection, override writing, and merge verification. Guides authors to pick field names and defaults that read well in that flow, while preserving that hand-writing TOML still works for users who prefer it (#78)
 
 ## [1.6.0] - 2026-04-20
 
 ### 🎁 Features
 
-* **Customize.toml support across all builders** — Workflow Builder, Agent Builder, and Module Builder now emit skills that participate in BMad's per-skill customization model. Workflow Builder gains an opt-in Configurability Discovery phase; Agent Builder always emits an `[agent]` metadata block plus an optional override surface; Module Builder reads agent metadata during create and populates `module.yaml:agents[]` roster
-* **Customization-surface quality scanner** — New `quality-scan-customization-surface.md` in both agent and workflow builders audits opportunities (hardcoded templates, missing defaults, unlifted variance) and abuse patterns (boolean toggle farms, identity leaks, sanctum conflicts on memory agents)
-* **Agent metadata contract** — First-Breath-named agents can ship with an empty `name` field, populated by the owner post-activation via `_bmad/custom/config.toml`. Stateless, memory, and autonomous agents all emit roster-ready metadata
-* **Module roster validation** — `validate-module.md` now checks agent roster validity and flags drift between `module.yaml` and each agent's own `customize.toml`
-* **bmad-help integration** — Added `_meta` row to `skills/module-help.csv` registering `https://bmad-builder-docs.bmad-method.org/llms.txt`, enabling bmad-help to fetch Builder docs contextually
-* **Sample module setup skill** — New `sample-module-setup` skill lets all six sample skills (code coach, creative muse, diagram reviewer, dream weaver, sentinel, excalidraw) install as a collective BMad module (code: `sam`) with module.yaml, six-entry module-help.csv, and standard merge/cleanup scripts
-* **Dream Weaver standalone plugin** — `bmad-dream-weaver-agent` registered as a standalone marketplace entry, enabling independent discovery and installation alongside the sample-plugins bundle
+- **Customize.toml support across all builders** — Workflow Builder, Agent Builder, and Module Builder now emit skills that participate in BMad's per-skill customization model. Workflow Builder gains an opt-in Configurability Discovery phase; Agent Builder always emits an `[agent]` metadata block plus an optional override surface; Module Builder reads agent metadata during create and populates `module.yaml:agents[]` roster
+- **Customization-surface quality scanner** — New `quality-scan-customization-surface.md` in both agent and workflow builders audits opportunities (hardcoded templates, missing defaults, unlifted variance) and abuse patterns (boolean toggle farms, identity leaks, sanctum conflicts on memory agents)
+- **Agent metadata contract** — First-Breath-named agents can ship with an empty `name` field, populated by the owner post-activation via `_bmad/custom/config.toml`. Stateless, memory, and autonomous agents all emit roster-ready metadata
+- **Module roster validation** — `validate-module.md` now checks agent roster validity and flags drift between `module.yaml` and each agent's own `customize.toml`
+- **bmad-help integration** — Added `_meta` row to `skills/module-help.csv` registering `https://bmad-builder-docs.bmad-method.org/llms.txt`, enabling bmad-help to fetch Builder docs contextually
+- **Sample module setup skill** — New `sample-module-setup` skill lets all six sample skills (code coach, creative muse, diagram reviewer, dream weaver, sentinel, excalidraw) install as a collective BMad module (code: `sam`) with module.yaml, six-entry module-help.csv, and standard merge/cleanup scripts
+- **Dream Weaver standalone plugin** — `bmad-dream-weaver-agent` registered as a standalone marketplace entry, enabling independent discovery and installation alongside the sample-plugins bundle
 
 ### 🐛 Bug Fixes
 
-* **BMB skill config fallback** — Agent, Workflow, and Module Builders now fall back to `_bmad/bmb/config.yaml` (legacy per-module format) when unified config files (`_bmad/config.yaml`, `_bmad/config.user.yaml`) do not exist, fixing config resolution for older installer setups
-* **Setup skill template YAML frontmatter** — Fixed invalid YAML frontmatter in emitted setup-skill templates (#55)
-* **Quality scanner self-containment** — Removed hardcoded absolute-path `Load` directives from customization-surface scanners. Scanners now rely solely on embedded lens tables, matching the convention of all other `quality-scan-*.md` files
-* **Marketplace source paths** — Corrected source paths for `sample-plugins` and `bmad-dream-weaver-agent` entries in `marketplace.json`
+- **BMB skill config fallback** — Agent, Workflow, and Module Builders now fall back to `_bmad/bmb/config.yaml` (legacy per-module format) when unified config files (`_bmad/config.yaml`, `_bmad/config.user.yaml`) do not exist, fixing config resolution for older installer setups
+- **Setup skill template YAML frontmatter** — Fixed invalid YAML frontmatter in emitted setup-skill templates (#55)
+- **Quality scanner self-containment** — Removed hardcoded absolute-path `Load` directives from customization-surface scanners. Scanners now rely solely on embedded lens tables, matching the convention of all other `quality-scan-*.md` files
+- **Marketplace source paths** — Corrected source paths for `sample-plugins` and `bmad-dream-weaver-agent` entries in `marketplace.json`
 
 ### 📚 Documentation
 
-* **Customization authoring guide** — New `docs/explanation/customization-for-authors.md` decision guide with full worked example (bmad-session-prep for tabletop RPG GM workflow)
-* **Customization how-to** — New `docs/how-to/make-a-skill-customizable.md` with procedural steps for opt-in moment, scalar naming, default setup, and override testing
-* **Path conventions in emitted skills** — `SKILL-template.md` and `SKILL-template-bootloader.md` now include a `## Conventions` block documenting path tokens: bare paths, `{skill-root}`, `{project-root}`, `{skill-name}`
-* **Removed `{skill-root}` restriction** — Dropped "never use `{skill-root}`" guidance from `builder-commands.md` and `skill-authoring-best-practices.md`. The token is supported; authors decide based on their use case
-* **Updated installer messaging** — Replaced stale "coming soon" and GitHub-only references in `what-are-modules.md`, `distribute-your-module.md`, and `index.md` with current capabilities: any Git host (GitHub, GitLab, Bitbucket, self-hosted) and local paths via `--custom-source` (#71)
-* **Cross-linked customization docs** — Added cross-links from five existing explanation docs (what-are-bmad-agents, what-are-workflows, agent-memory-and-personalization, module-configuration, skill-authoring-best-practices)
-* **Module config clarity** — Clarified that authors still write `module.yaml` as source of truth; the installer flows module-level answers and agents roster into `_bmad/config.toml` at project root, aligning with BMAD-METHOD central config
+- **Customization authoring guide** — New `docs/explanation/customization-for-authors.md` decision guide with full worked example (bmad-session-prep for tabletop RPG GM workflow)
+- **Customization how-to** — New `docs/how-to/make-a-skill-customizable.md` with procedural steps for opt-in moment, scalar naming, default setup, and override testing
+- **Path conventions in emitted skills** — `SKILL-template.md` and `SKILL-template-bootloader.md` now include a `## Conventions` block documenting path tokens: bare paths, `{skill-root}`, `{project-root}`, `{skill-name}`
+- **Removed `{skill-root}` restriction** — Dropped "never use `{skill-root}`" guidance from `builder-commands.md` and `skill-authoring-best-practices.md`. The token is supported; authors decide based on their use case
+- **Updated installer messaging** — Replaced stale "coming soon" and GitHub-only references in `what-are-modules.md`, `distribute-your-module.md`, and `index.md` with current capabilities: any Git host (GitHub, GitLab, Bitbucket, self-hosted) and local paths via `--custom-source` (#71)
+- **Cross-linked customization docs** — Added cross-links from five existing explanation docs (what-are-bmad-agents, what-are-workflows, agent-memory-and-personalization, module-configuration, skill-authoring-best-practices)
+- **Module config clarity** — Clarified that authors still write `module.yaml` as source of truth; the installer flows module-level answers and agents roster into `_bmad/config.toml` at project root, aligning with BMAD-METHOD central config
 
 ### 🔧 Maintenance
 
-* Bump bmad-builder version to 1.6.0 across `package.json` and `marketplace.json`
-* Bump sample-plugins to 1.1.0 in `marketplace.json` to reflect the new `sample-module-setup` skill
-* Replace "opt-out by default" with "disabled by default" for `customize.toml` override surface on memory/autonomous agents
-* Update three end-user-guide links from `bmadcode.github.io/bmad` to `docs.bmad-method.org/how-to/customize-bmad/`
-* Append `.md` to twelve internal cross-links throughout docs to match site convention
-* CI: prettier, markdownlint, and docs validator unblocks for PR #76
+- Bump bmad-builder version to 1.6.0 across `package.json` and `marketplace.json`
+- Bump sample-plugins to 1.1.0 in `marketplace.json` to reflect the new `sample-module-setup` skill
+- Replace "opt-out by default" with "disabled by default" for `customize.toml` override surface on memory/autonomous agents
+- Update three end-user-guide links from `bmadcode.github.io/bmad` to `docs.bmad-method.org/how-to/customize-bmad/`
+- Append `.md` to twelve internal cross-links throughout docs to match site convention
+- CI: prettier, markdownlint, and docs validator unblocks for PR #76
 
 ## [1.5.0] - 2026-04-06
 
 ### 💥 Breaking Changes
 
-* **Agent builder output structure** — Builder now produces three distinct agent types (stateless, memory, autonomous) with different scaffolding per type. Stateless agents retain the familiar full-identity SKILL.md; memory and autonomous agents use a lean bootloader with sanctum architecture
-* **bmad- prefix reserved** — The `bmad-` prefix is now reserved for official BMad ecosystem skills only. User-created skills use `agent-{name}` (standalone) or `{code}-agent-{name}` (module). Convert mode preserves existing prefixes unless the user requests a rename
+- **Agent builder output structure** — Builder now produces three distinct agent types (stateless, memory, autonomous) with different scaffolding per type. Stateless agents retain the familiar full-identity SKILL.md; memory and autonomous agents use a lean bootloader with sanctum architecture
+- **bmad- prefix reserved** — The `bmad-` prefix is now reserved for official BMad ecosystem skills only. User-created skills use `agent-{name}` (standalone) or `{code}-agent-{name}` (module). Convert mode preserves existing prefixes unless the user requests a rename
 
 ### 🎁 Features
 
-* **Agent personalization architecture** — Three agent types along a spectrum: stateless (no memory), memory (sanctum with First Breath initialization), and autonomous (memory + PULSE for background operation). Builder detects the right type through natural conversation during Phase 1
-* **Sanctum memory system** — Memory agents persist through six core files (INDEX, PERSONA, CREED, BOND, MEMORY, CAPABILITIES) loaded on every session rebirth. Two-tier memory: raw session logs for capture, curated MEMORY.md (capped at 200 lines) for long-term knowledge
-* **First Breath initialization** — Two styles for agent onboarding: calibration (deep conversational discovery for creative partners) and configuration (efficient guided setup for domain experts). Saves to sanctum files during the conversation, not in batch
-* **PULSE autonomous wake** — Autonomous agents wake on schedule to curate memory, prune old session logs, and run domain-specific tasks. Supports named task routing via `--headless {task-name}`
-* **Evolvable capabilities** — Memory agents can optionally learn new capabilities over time. Users teach the agent new prompt-based, script-based, or multi-file capabilities that persist in the sanctum
-* **Template processing script** — New `process-template.py` for parameterized sanctum template seeding with agent type conditionals and init script parameters
-* **New sample agents** — bmad-agent-creative-muse (memory, calibration), bmad-agent-code-coach (autonomous), bmad-agent-sentinel (autonomous), bmad-agent-diagram-reviewer (stateless)
+- **Agent personalization architecture** — Three agent types along a spectrum: stateless (no memory), memory (sanctum with First Breath initialization), and autonomous (memory + PULSE for background operation). Builder detects the right type through natural conversation during Phase 1
+- **Sanctum memory system** — Memory agents persist through six core files (INDEX, PERSONA, CREED, BOND, MEMORY, CAPABILITIES) loaded on every session rebirth. Two-tier memory: raw session logs for capture, curated MEMORY.md (capped at 200 lines) for long-term knowledge
+- **First Breath initialization** — Two styles for agent onboarding: calibration (deep conversational discovery for creative partners) and configuration (efficient guided setup for domain experts). Saves to sanctum files during the conversation, not in batch
+- **PULSE autonomous wake** — Autonomous agents wake on schedule to curate memory, prune old session logs, and run domain-specific tasks. Supports named task routing via `--headless {task-name}`
+- **Evolvable capabilities** — Memory agents can optionally learn new capabilities over time. Users teach the agent new prompt-based, script-based, or multi-file capabilities that persist in the sanctum
+- **Template processing script** — New `process-template.py` for parameterized sanctum template seeding with agent type conditionals and init script parameters
+- **New sample agents** — bmad-agent-creative-muse (memory, calibration), bmad-agent-code-coach (autonomous), bmad-agent-sentinel (autonomous), bmad-agent-diagram-reviewer (stateless)
 
 ### 🐛 Bug Fixes
 
-* Fix quality scanner false positives on memory agents — prepass now detects bootloader architecture via Sacred Truth markers and sanctum templates, outputs `is_memory_agent` flag for all five LLM scanners
-* Fix report creator for bootloader agents — reads identity seed and CREED philosophy from sanctum templates instead of missing SKILL.md sections
-* Fix naming validation in workflow builder — remove enforced `bmad-` prefix check that rejected valid user-created skill names
+- Fix quality scanner false positives on memory agents — prepass now detects bootloader architecture via Sacred Truth markers and sanctum templates, outputs `is_memory_agent` flag for all five LLM scanners
+- Fix report creator for bootloader agents — reads identity seed and CREED philosophy from sanctum templates instead of missing SKILL.md sections
+- Fix naming validation in workflow builder — remove enforced `bmad-` prefix check that rejected valid user-created skill names
 
 ### ♻️ Refactoring
 
-* Move builder process and quality scan files into `references/` subdirectory for both agent and workflow builders
-* Unify agent memory terminology — replace "sidecar" with direct memory references across all builders, docs, and samples. Memory path convention updated from `{skillName}-sidecar/` to `{skillName}/` for new builds
-* Restructure builder discovery phases for agent type awareness with new sequencing: type detection, relationship depth, evolvable capabilities, full memory requirements
+- Move builder process and quality scan files into `references/` subdirectory for both agent and workflow builders
+- Unify agent memory terminology — replace "sidecar" with direct memory references across all builders, docs, and samples. Memory path convention updated from `{skillName}-sidecar/` to `{skillName}/` for new builds
+- Restructure builder discovery phases for agent type awareness with new sequencing: type detection, relationship depth, evolvable capabilities, full memory requirements
 
 ### 📚 Documentation
 
-* New explanation doc: "Agent Memory and Personalization" covering sanctum architecture, First Breath, two-tier memory, PULSE, and evolvable capabilities
-* Rewrite "What Are BMad Agents" for the three agent types with comparison tables and decision guidance
-* Expand "Builder Commands Reference" with agent type detection in Phase 1, persona memory requirements in Phase 2-3, and per-type build output structures
-* Add installer coming-soon notices — manual copy instructions as current path, BMad installer as upcoming
-* Update module docs to reference agent type spectrum and new naming conventions
-* Add module contribution guide with ecosystem cross-links
+- New explanation doc: "Agent Memory and Personalization" covering sanctum architecture, First Breath, two-tier memory, PULSE, and evolvable capabilities
+- Rewrite "What Are BMad Agents" for the three agent types with comparison tables and decision guidance
+- Expand "Builder Commands Reference" with agent type detection in Phase 1, persona memory requirements in Phase 2-3, and per-type build output structures
+- Add installer coming-soon notices — manual copy instructions as current path, BMad installer as upcoming
+- Update module docs to reference agent type spectrum and new naming conventions
+- Add module contribution guide with ecosystem cross-links
 
 ### 🔧 Maintenance
 
-* Bump version to 1.5.0 across package.json and marketplace.json
-* Update docs theme to Ghost blog design tokens (Inter/Space Grotesk/JetBrains Mono, dark palette)
-* Add Python 3.10+ and `uv` as documented prerequisites
+- Bump version to 1.5.0 across package.json and marketplace.json
+- Update docs theme to Ghost blog design tokens (Inter/Space Grotesk/JetBrains Mono, dark palette)
+- Add Python 3.10+ and `uv` as documented prerequisites
 
 ## [1.4.0] - 2026-03-29
 
 ### 🎁 Features
 
-* **Standalone self-registering modules** — Single-skill modules no longer need a dedicated `-setup` skill. The Module Builder auto-detects single vs multi-skill input and embeds registration directly in the skill via `assets/module-setup.md`. First-run init hooks into existing agent memory detection for a unified setup experience
-* **Module Builder skill** — New `bmad-module-builder` with three capabilities: Ideate Module (IM) for creative brainstorming, Create Module (CM) for scaffolding both standalone and multi-skill modules, and Validate Module (VM) for structural and quality validation with `--headless` CI support
-* **BMB Setup skill** — Extracted and regenerated as `bmad-bmb-setup` using the Module Builder itself. Manages config.yaml, config.user.yaml, and module-help.csv with anti-zombie merge pattern and legacy migration
-* **Workflow Convert capability (CW)** — One-command skill modernization via `--convert <path-or-url>`. Produces a clean BMad-compliant equivalent with an interactive HTML before/after comparison report including token metrics, categorized changes, and dark/light mode
-* **Script creation standards** — Formalized Python-first policy with PEP 723 metadata, cross-platform portability via `uv run`, and explicit user approval for external dependencies
+- **Standalone self-registering modules** — Single-skill modules no longer need a dedicated `-setup` skill. The Module Builder auto-detects single vs multi-skill input and embeds registration directly in the skill via `assets/module-setup.md`. First-run init hooks into existing agent memory detection for a unified setup experience
+- **Module Builder skill** — New `bmad-module-builder` with three capabilities: Ideate Module (IM) for creative brainstorming, Create Module (CM) for scaffolding both standalone and multi-skill modules, and Validate Module (VM) for structural and quality validation with `--headless` CI support
+- **BMB Setup skill** — Extracted and regenerated as `bmad-bmb-setup` using the Module Builder itself. Manages config.yaml, config.user.yaml, and module-help.csv with anti-zombie merge pattern and legacy migration
+- **Workflow Convert capability (CW)** — One-command skill modernization via `--convert <path-or-url>`. Produces a clean BMad-compliant equivalent with an interactive HTML before/after comparison report including token metrics, categorized changes, and dark/light mode
+- **Script creation standards** — Formalized Python-first policy with PEP 723 metadata, cross-platform portability via `uv run`, and explicit user approval for external dependencies
 
 ### 🐛 Bug Fixes
 
-* Fix HTML quality report data injection — template used `const RAW` but generator looked for `const DATA`, causing broken report rendering in both builders
-* Fix merge-help-csv.py HEADER schema — synced from 15 columns to canonical 13-column schema, preventing silent CSV corruption during module setup
-* Fix `{project-root}` path validation overcorrection — scanner incorrectly rejected valid project-scope paths like `{project-root}/docs/report.md`
-* Add bmad-module-builder to marketplace.json — skill was merged but not registered in the plugin manifest
+- Fix HTML quality report data injection — template used `const RAW` but generator looked for `const DATA`, causing broken report rendering in both builders
+- Fix merge-help-csv.py HEADER schema — synced from 15 columns to canonical 13-column schema, preventing silent CSV corruption during module setup
+- Fix `{project-root}` path validation overcorrection — scanner incorrectly rejected valid project-scope paths like `{project-root}/docs/report.md`
+- Add bmad-module-builder to marketplace.json — skill was merged but not registered in the plugin manifest
 
 ### ♻️ Refactoring
 
-* **Outcome-driven builder overhaul** — Reframe both builders around discovery-first design: existing skill input treated as reference material, 3-way routing (Analyze/Edit/Rebuild), pruning check in Phase 4, "Quality Optimizer" renamed to "Quality Analysis". Net 44% token reduction in Workflow Builder Phase 5 context
-* **Ideation restructured into 7 phases** — Module identity locked in Phase 1, new Phase 6 capability review with user, mandatory config section, self-contained skill briefs, writing discipline (raw ideas in phases 1-2, structured from phase 3+)
-* Consolidate plugin.json metadata into marketplace.json — single source of truth for plugin metadata
-* Remove npm publishing pipeline — distribution now via `.claude-plugin/` manifest
+- **Outcome-driven builder overhaul** — Reframe both builders around discovery-first design: existing skill input treated as reference material, 3-way routing (Analyze/Edit/Rebuild), pruning check in Phase 4, "Quality Optimizer" renamed to "Quality Analysis". Net 44% token reduction in Workflow Builder Phase 5 context
+- **Ideation restructured into 7 phases** — Module identity locked in Phase 1, new Phase 6 capability review with user, mandatory config section, self-contained skill briefs, writing discipline (raw ideas in phases 1-2, structured from phase 3+)
+- Consolidate plugin.json metadata into marketplace.json — single source of truth for plugin metadata
+- Remove npm publishing pipeline — distribution now via `.claude-plugin/` manifest
 
 ### 📚 Documentation
 
-* **Comprehensive docs overhaul** — Quick start guide with `bmad-bmb-setup` registration, full 13-column CSV guide explaining how `bmad-help` uses each column, "Distribution: Plugins and Marketplaces" section covering 43+ skills platforms, standalone vs multi-skill patterns throughout all docs
-* Add personal-use guidance — users can copy skill folders directly to their tool's skills directory without module packaging
-* Remove deprecated bmad-init references from workflow-patterns docs
-* New explanation doc: Scripts in Skills — design patterns for deterministic scripting
+- **Comprehensive docs overhaul** — Quick start guide with `bmad-bmb-setup` registration, full 13-column CSV guide explaining how `bmad-help` uses each column, "Distribution: Plugins and Marketplaces" section covering 43+ skills platforms, standalone vs multi-skill patterns throughout all docs
+- Add personal-use guidance — users can copy skill folders directly to their tool's skills directory without module packaging
+- Remove deprecated bmad-init references from workflow-patterns docs
+- New explanation doc: Scripts in Skills — design patterns for deterministic scripting
 
 ### 🔧 Maintenance
 
-* Bump version to 1.4.0 across package.json and marketplace.json
-* Remove npm release scripts and publishConfig from package.json
+- Bump version to 1.4.0 across package.json and marketplace.json
+- Remove npm release scripts and publishConfig from package.json
 
 ## [1.1.0] - 2026-03-19
 
diff --git a/README.md b/README.md
index 7f5383e..da02ee8 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 [![Version](https://img.shields.io/npm/v/bmad-builder?color=blue&label=version)](https://www.npmjs.com/package/bmad-builder)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Python Version](https://img.shields.io/badge/python-%3E%3D3.10-blue?logo=python&logoColor=white)](https://www.python.org)
+[![Python Version](https://img.shields.io/badge/python-%3E%3D3.11-blue?logo=python&logoColor=white)](https://www.python.org)
 [![uv](https://img.shields.io/badge/uv-package%20manager-blueviolet?logo=uv)](https://docs.astral.sh/uv/)
 [![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj)
 
diff --git a/docs/how-to/install-docker-for-evals.md b/docs/how-to/install-docker-for-evals.md
index 95354e5..1ebf670 100644
--- a/docs/how-to/install-docker-for-evals.md
+++ b/docs/how-to/install-docker-for-evals.md
@@ -78,7 +78,7 @@ The Dockerfile contains no tokens, API keys, or credentials. Your authentication
 
 ## Tips
 
-- Rebuild the image with `python3 scripts/docker_setup.py --rebuild` if you ever need to reset it
+- Rebuild the image with `uv run scripts/docker_setup.py --rebuild` if you ever need to reset it
 - Per-eval container resource use is small (a few hundred MB). Parallel workers each spin up their own container.
 - If `docker info` works in one terminal but not in your editor's integrated terminal, your shell PATH probably differs. Open a fresh terminal session.
 
diff --git a/docs/how-to/make-a-skill-customizable.md b/docs/how-to/make-a-skill-customizable.md
index 40974ae..5f9f26f 100644
--- a/docs/how-to/make-a-skill-customizable.md
+++ b/docs/how-to/make-a-skill-customizable.md
@@ -110,7 +110,7 @@ EOF
 Run the resolver directly to confirm your override takes effect:
 
 ```bash
-python3 _bmad/scripts/resolve_customization.py \
+uv run _bmad/scripts/resolve_customization.py \
   --skill /path/to/built/skill \
   --key workflow.on_complete
 ```
diff --git a/samples/bmad-agent-code-coach/scripts/init-sanctum.py b/samples/bmad-agent-code-coach/scripts/init-sanctum.py
index 6b86225..65e2ae2 100755
--- a/samples/bmad-agent-code-coach/scripts/init-sanctum.py
+++ b/samples/bmad-agent-code-coach/scripts/init-sanctum.py
@@ -11,13 +11,13 @@
 not depend on the skill bundle location for normal operation.
 
 Usage:
-    python3 init-sanctum.py <project-root> <skill-path>
+    uv run init-sanctum.py <project-root> <skill-path>
 
     project-root: The root of the project (where _bmad/ lives)
     skill-path:   Path to the skill directory (where SKILL.md, references/, assets/ live)
 
 Example:
-    python3 scripts/init-sanctum.py /Users/me/myproject /path/to/bmad-agent-code-coach
+    uv run scripts/init-sanctum.py /Users/me/myproject /path/to/bmad-agent-code-coach
 """
 
 import sys
@@ -192,7 +192,7 @@ def substitute_vars(content: str, variables: dict) -> str:
 
 def main():
     if len(sys.argv) < 3:
-        print("Usage: python3 init-sanctum.py <project-root> <skill-path>")
+        print("Usage: uv run init-sanctum.py <project-root> <skill-path>")
         sys.exit(1)
 
     project_root = Path(sys.argv[1]).resolve()
diff --git a/samples/bmad-agent-code-coach/scripts/wake.py b/samples/bmad-agent-code-coach/scripts/wake.py
index 7fc53b2..e7f052c 100644
--- a/samples/bmad-agent-code-coach/scripts/wake.py
+++ b/samples/bmad-agent-code-coach/scripts/wake.py
@@ -14,7 +14,7 @@
 This loads runtime memory only. It never reads or writes config or customize.toml.
 
 Usage:
-    python3 wake.py <project-root> [--pulse]
+    uv run wake.py <project-root> [--pulse]
 
     project-root: The root of the project (where _bmad/ lives)
 """
diff --git a/samples/bmad-agent-creative-muse/scripts/init-sanctum.py b/samples/bmad-agent-creative-muse/scripts/init-sanctum.py
index e7853e7..70959d0 100644
--- a/samples/bmad-agent-creative-muse/scripts/init-sanctum.py
+++ b/samples/bmad-agent-creative-muse/scripts/init-sanctum.py
@@ -11,13 +11,13 @@
 not depend on the skill bundle location for normal operation.
 
 Usage:
-    python3 init-sanctum.py <project-root> <skill-path>
+    uv run init-sanctum.py <project-root> <skill-path>
 
     project-root: The root of the project (where _bmad/ lives)
     skill-path:   Path to the skill directory (where SKILL.md, references/, assets/ live)
 
 Example:
-    python3 scripts/init-sanctum.py /Users/me/myproject /path/to/bmad-agent-creative-muse
+    uv run scripts/init-sanctum.py /Users/me/myproject /path/to/bmad-agent-creative-muse
 """
 
 import sys
@@ -178,7 +178,7 @@ def substitute_vars(content: str, variables: dict) -> str:
 
 def main():
     if len(sys.argv) < 3:
-        print("Usage: python3 init-sanctum.py <project-root> <skill-path>")
+        print("Usage: uv run init-sanctum.py <project-root> <skill-path>")
         sys.exit(1)
 
     project_root = Path(sys.argv[1]).resolve()
diff --git a/samples/bmad-agent-creative-muse/scripts/wake.py b/samples/bmad-agent-creative-muse/scripts/wake.py
index 85cdd2b..4caa8ab 100644
--- a/samples/bmad-agent-creative-muse/scripts/wake.py
+++ b/samples/bmad-agent-creative-muse/scripts/wake.py
@@ -14,7 +14,7 @@
 This loads runtime memory only. It never reads or writes config or customize.toml.
 
 Usage:
-    python3 wake.py <project-root> [--pulse]
+    uv run wake.py <project-root> [--pulse]
 
     project-root: The root of the project (where _bmad/ lives)
 """
diff --git a/samples/bmad-agent-dream-weaver/assets/module-setup.md b/samples/bmad-agent-dream-weaver/assets/module-setup.md
index 67d9a15..90ffb2f 100644
--- a/samples/bmad-agent-dream-weaver/assets/module-setup.md
+++ b/samples/bmad-agent-dream-weaver/assets/module-setup.md
@@ -53,8 +53,8 @@ Write a temp JSON file with the collected answers structured as `{"core": {...},
 In the commands below, replace `{project-root}` in every path argument with the actual project root (e.g. `/home/me/myapp`) before running — these are filesystem paths, not config values.
 
 ```bash
-python3 ./scripts/merge-config.py --config-path "{project-root}/_bmad/config.yaml" --user-config-path "{project-root}/_bmad/config.user.yaml" --module-yaml ./assets/module.yaml --answers {temp-file}
-python3 ./scripts/merge-help-csv.py --target "{project-root}/_bmad/module-help.csv" --source ./assets/module-help.csv --module-code {module-code}
+uv run ./scripts/merge-config.py --config-path "{project-root}/_bmad/config.yaml" --user-config-path "{project-root}/_bmad/config.user.yaml" --module-yaml ./assets/module.yaml --answers {temp-file}
+uv run ./scripts/merge-help-csv.py --target "{project-root}/_bmad/module-help.csv" --source ./assets/module-help.csv --module-code {module-code}
 ```
 
 Both scripts output JSON to stdout with results. If either exits non-zero, surface the error and stop.
diff --git a/samples/bmad-agent-sentinel/scripts/init-sanctum.py b/samples/bmad-agent-sentinel/scripts/init-sanctum.py
index 507ad8a..06e0b37 100644
--- a/samples/bmad-agent-sentinel/scripts/init-sanctum.py
+++ b/samples/bmad-agent-sentinel/scripts/init-sanctum.py
@@ -11,13 +11,13 @@
 not depend on the skill bundle location for normal operation.
 
 Usage:
-    python3 init-sanctum.py <project-root> <skill-path>
+    uv run init-sanctum.py <project-root> <skill-path>
 
     project-root: The root of the project (where _bmad/ lives)
     skill-path:   Path to the skill directory (where SKILL.md, references/, assets/ live)
 
 Example:
-    python3 scripts/init-sanctum.py /Users/me/myproject /path/to/bmad-agent-sentinel
+    uv run scripts/init-sanctum.py /Users/me/myproject /path/to/bmad-agent-sentinel
 """
 
 import sys
@@ -189,7 +189,7 @@ def substitute_vars(content: str, variables: dict) -> str:
 
 def main():
     if len(sys.argv) < 3:
-        print("Usage: python3 init-sanctum.py <project-root> <skill-path>")
+        print("Usage: uv run init-sanctum.py <project-root> <skill-path>")
         sys.exit(1)
 
     project_root = Path(sys.argv[1]).resolve()
diff --git a/samples/bmad-agent-sentinel/scripts/wake.py b/samples/bmad-agent-sentinel/scripts/wake.py
index d54252c..a7a561b 100644
--- a/samples/bmad-agent-sentinel/scripts/wake.py
+++ b/samples/bmad-agent-sentinel/scripts/wake.py
@@ -14,7 +14,7 @@
 This loads runtime memory only. It never reads or writes config or customize.toml.
 
 Usage:
-    python3 wake.py <project-root> [--pulse]
+    uv run wake.py <project-root> [--pulse]
 
     project-root: The root of the project (where _bmad/ lives)
 """
diff --git a/samples/bmad-excalidraw/references/diagram-generation.md b/samples/bmad-excalidraw/references/diagram-generation.md
index 8a489e9..4e515ec 100644
--- a/samples/bmad-excalidraw/references/diagram-generation.md
+++ b/samples/bmad-excalidraw/references/diagram-generation.md
@@ -49,13 +49,13 @@ The specification format:
 Run the generation script:
 
 ```bash
-python3 ../scripts/generate_excalidraw.py --spec '<json-spec>' --output '{output_folder}/diagrams/{filename}.excalidraw'
+uv run ../scripts/generate_excalidraw.py --spec '<json-spec>' --output '{output_folder}/diagrams/{filename}.excalidraw'
 ```
 
 Or pipe the spec via stdin:
 
 ```bash
-echo '<json-spec>' | python3 ../scripts/generate_excalidraw.py --output '{output_folder}/diagrams/{filename}.excalidraw'
+echo '<json-spec>' | uv run ../scripts/generate_excalidraw.py --output '{output_folder}/diagrams/{filename}.excalidraw'
 ```
 
 The script handles:
@@ -72,7 +72,7 @@ The script handles:
 Run validation:
 
 ```bash
-python3 ../scripts/validate_excalidraw.py '{output_folder}/diagrams/{filename}.excalidraw'
+uv run ../scripts/validate_excalidraw.py '{output_folder}/diagrams/{filename}.excalidraw'
 ```
 
 Fix any critical issues before delivering.
diff --git a/samples/bmad-excalidraw/scripts/generate_excalidraw.py b/samples/bmad-excalidraw/scripts/generate_excalidraw.py
index ba4e3fd..d44c975 100644
--- a/samples/bmad-excalidraw/scripts/generate_excalidraw.py
+++ b/samples/bmad-excalidraw/scripts/generate_excalidraw.py
@@ -8,9 +8,9 @@
 with auto-layout positioning.
 
 Usage:
-    python generate_excalidraw.py --spec '{"title":"My Diagram",...}' --output diagram.excalidraw
-    echo '{"title":"My Diagram",...}' | python generate_excalidraw.py --output diagram.excalidraw
-    python generate_excalidraw.py --spec-file spec.json --output diagram.excalidraw
+    uv run generate_excalidraw.py --spec '{"title":"My Diagram",...}' --output diagram.excalidraw
+    echo '{"title":"My Diagram",...}' | uv run generate_excalidraw.py --output diagram.excalidraw
+    uv run generate_excalidraw.py --spec-file spec.json --output diagram.excalidraw
 
 Spec format:
 {
diff --git a/samples/bmad-excalidraw/scripts/validate_excalidraw.py b/samples/bmad-excalidraw/scripts/validate_excalidraw.py
index 64cb5df..d0b11f1 100644
--- a/samples/bmad-excalidraw/scripts/validate_excalidraw.py
+++ b/samples/bmad-excalidraw/scripts/validate_excalidraw.py
@@ -7,8 +7,8 @@
 Validates .excalidraw files for structural correctness.
 
 Usage:
-    python validate_excalidraw.py path/to/diagram.excalidraw
-    python validate_excalidraw.py path/to/diagram.excalidraw -o report.json
+    uv run validate_excalidraw.py path/to/diagram.excalidraw
+    uv run validate_excalidraw.py path/to/diagram.excalidraw -o report.json
 
 Exit codes: 0=pass, 1=fail, 2=error
 """
diff --git a/samples/sample-module-setup/SKILL.md b/samples/sample-module-setup/SKILL.md
index 147375d..6c08558 100644
--- a/samples/sample-module-setup/SKILL.md
+++ b/samples/sample-module-setup/SKILL.md
@@ -45,8 +45,8 @@ Write a temp JSON file with the collected answers structured as `{"core": {...},
 In the commands below, replace `{project-root}` in every path argument with the actual project root (e.g. `/home/me/myapp`) before running — these are filesystem paths, not config values.
 
 ```bash
-python3 ./scripts/merge-config.py --config-path "{project-root}/_bmad/config.yaml" --user-config-path "{project-root}/_bmad/config.user.yaml" --module-yaml ./assets/module.yaml --answers {temp-file} --legacy-dir "{project-root}/_bmad"
-python3 ./scripts/merge-help-csv.py --target "{project-root}/_bmad/module-help.csv" --source ./assets/module-help.csv --legacy-dir "{project-root}/_bmad" --module-code sam
+uv run ./scripts/merge-config.py --config-path "{project-root}/_bmad/config.yaml" --user-config-path "{project-root}/_bmad/config.user.yaml" --module-yaml ./assets/module.yaml --answers {temp-file} --legacy-dir "{project-root}/_bmad"
+uv run ./scripts/merge-help-csv.py --target "{project-root}/_bmad/module-help.csv" --source ./assets/module-help.csv --legacy-dir "{project-root}/_bmad" --module-code sam
 ```
 
 Both scripts output JSON to stdout with results. If either exits non-zero, surface the error and stop. The scripts automatically read legacy config values as fallback defaults, then delete the legacy files after a successful merge. Check `legacy_configs_deleted` and `legacy_csvs_deleted` in the output to confirm cleanup.
@@ -64,7 +64,7 @@ After both merge scripts complete successfully, remove the installer's package d
 As with the merge scripts, replace `{project-root}` in the `--bmad-dir` and `--skills-dir` path arguments with the actual project root before running.
 
 ```bash
-python3 ./scripts/cleanup-legacy.py --bmad-dir "{project-root}/_bmad" --module-code sam --also-remove _config --skills-dir "{project-root}/.claude/skills"
+uv run ./scripts/cleanup-legacy.py --bmad-dir "{project-root}/_bmad" --module-code sam --also-remove _config --skills-dir "{project-root}/.claude/skills"
 ```
 
 The script verifies that every skill in the legacy directories exists at `.claude/skills/` before removing anything. Directories without skills (like `_config/`) are removed directly. If the script exits non-zero, surface the error and stop. Missing directories (already cleaned by a prior run) are not errors — the script is idempotent.
diff --git a/skills/bmad-bmb-setup/SKILL.md b/skills/bmad-bmb-setup/SKILL.md
index 50fb6bf..b2b3fad 100644
--- a/skills/bmad-bmb-setup/SKILL.md
+++ b/skills/bmad-bmb-setup/SKILL.md
@@ -45,8 +45,8 @@ Write a temp JSON file with the collected answers structured as `{"core": {...},
 In the commands below, replace `{project-root}` in every path argument with the actual project root (e.g. `/home/me/myapp`) before running — these are filesystem paths, not config values. Leave `{temp-file}` and `bmb` as-is.
 
 ```bash
-python3 ./scripts/merge-config.py --config-path "{project-root}/_bmad/config.yaml" --user-config-path "{project-root}/_bmad/config.user.yaml" --module-yaml ./assets/module.yaml --answers {temp-file} --legacy-dir "{project-root}/_bmad"
-python3 ./scripts/merge-help-csv.py --target "{project-root}/_bmad/module-help.csv" --source ./assets/module-help.csv --legacy-dir "{project-root}/_bmad" --module-code bmb
+uv run ./scripts/merge-config.py --config-path "{project-root}/_bmad/config.yaml" --user-config-path "{project-root}/_bmad/config.user.yaml" --module-yaml ./assets/module.yaml --answers {temp-file} --legacy-dir "{project-root}/_bmad"
+uv run ./scripts/merge-help-csv.py --target "{project-root}/_bmad/module-help.csv" --source ./assets/module-help.csv --legacy-dir "{project-root}/_bmad" --module-code bmb
 ```
 
 Both scripts output JSON to stdout with results. If either exits non-zero, surface the error and stop. The scripts automatically read legacy config values as fallback defaults, then delete the legacy files after a successful merge. Check `legacy_configs_deleted` and `legacy_csvs_deleted` in the output to confirm cleanup.
@@ -64,7 +64,7 @@ After both merge scripts complete successfully, remove the installer's package d
 As with the merge scripts, replace `{project-root}` in the `--bmad-dir` and `--skills-dir` path arguments with the actual project root before running.
 
 ```bash
-python3 ./scripts/cleanup-legacy.py --bmad-dir "{project-root}/_bmad" --module-code bmb --also-remove _config --skills-dir "{project-root}/.claude/skills"
+uv run ./scripts/cleanup-legacy.py --bmad-dir "{project-root}/_bmad" --module-code bmb --also-remove _config --skills-dir "{project-root}/.claude/skills"
 ```
 
 The script verifies that every skill in the legacy directories exists at `.claude/skills/` before removing anything. Directories without skills (like `_config/`) are removed directly. If the script exits non-zero, surface the error and stop. Missing directories (already cleaned by a prior run) are not errors — the script is idempotent.
diff --git a/skills/bmad-eval-runner/SKILL.md b/skills/bmad-eval-runner/SKILL.md
index 171b693..f5247e2 100644
--- a/skills/bmad-eval-runner/SKILL.md
+++ b/skills/bmad-eval-runner/SKILL.md
@@ -60,7 +60,7 @@ Each case runs in a clean working directory with the skill under test staged int
 For baseline, variant, and quality modes:
 
 ```
-python3 {skill-root}/scripts/run_evals.py \
+uv run {skill-root}/scripts/run_evals.py \
   --cases <cases-file> --skill-path <skill> --output-dir <dir> \
   --mode quality|baseline|variant [--variant-path <skill>] \
   [--adapter <adapter.json>] [--runs N]
@@ -71,7 +71,7 @@ The script stages the skill and any case fixtures, applies any `state_prefix` to
 For trigger mode:
 
 ```
-python3 {skill-root}/scripts/run_triggers.py \
+uv run {skill-root}/scripts/run_triggers.py \
   --skill-path <skill> --queries <queries-file> --output-dir <dir> \
   [--adapter <adapter.json>] [--runs-per-query N]
 ```
@@ -80,7 +80,7 @@ It stages a synthetic skill where the runtime discovers skills, sends each query
 
 For quality mode, spawn the grader described in `references/grader.md` per case, passing the case's rubric, transcript path, artifacts dir (the case's `cwd/`), and a `grading_path` of `<case-folder>/grading.json`. The grader writes that file, gives no partial credit, and flags weak or non-discriminating assertions; relay that feedback. If a grader subagent errors, mark that case `grading_error` — never substitute a default verdict.
 
-When `--runs` is greater than one, call `python3 {skill-root}/scripts/aggregate_benchmark.py --baseline <run-dir>/<config-a> --variant <run-dir>/<config-b>` to produce the mean, sample standard deviation, min, max, and the delta between configs (`--runs <run-dir>/<config>` for a single config's spread).
+When `--runs` is greater than one, call `uv run {skill-root}/scripts/aggregate_benchmark.py --baseline <run-dir>/<config-a> --variant <run-dir>/<config-b>` to produce the mean, sample standard deviation, min, max, and the delta between configs (`--runs <run-dir>/<config>` for a single config's spread).
 
 When a run fails or comes back weak and the user wants the skill improved from the results, follow `references/self-improvement.md`.
 
diff --git a/skills/bmad-eval-runner/scripts/aggregate_benchmark.py b/skills/bmad-eval-runner/scripts/aggregate_benchmark.py
index e4cf019..2746dd9 100644
--- a/skills/bmad-eval-runner/scripts/aggregate_benchmark.py
+++ b/skills/bmad-eval-runner/scripts/aggregate_benchmark.py
@@ -21,14 +21,14 @@
 
 Usage:
   Summarize one config across its runs:
-    python3 aggregate_benchmark.py --runs CONFIG_A.json
-    python3 aggregate_benchmark.py --runs RUN_DIR/        (reads timing.json files)
+    uv run aggregate_benchmark.py --runs CONFIG_A.json
+    uv run aggregate_benchmark.py --runs RUN_DIR/        (reads timing.json files)
 
   Compare two configs (each summarized, then delta = B - A):
-    python3 aggregate_benchmark.py --baseline A.json --variant B.json
+    uv run aggregate_benchmark.py --baseline A.json --variant B.json
 
   Self-test on a known fixture (no external input needed):
-    python3 aggregate_benchmark.py --self-test
+    uv run aggregate_benchmark.py --self-test
 
 Output is one JSON object on stdout.
 """
diff --git a/skills/bmad-eval-runner/scripts/run_evals.py b/skills/bmad-eval-runner/scripts/run_evals.py
index c518c93..7e9d162 100644
--- a/skills/bmad-eval-runner/scripts/run_evals.py
+++ b/skills/bmad-eval-runner/scripts/run_evals.py
@@ -66,7 +66,7 @@
 recorded so the grader sees exactly what ran.
 
 Usage:
-  python3 run_evals.py \\
+  uv run run_evals.py \\
     --cases CASES.json \\
     --skill-path SKILL_DIR \\
     --output-dir DIR \\
diff --git a/skills/bmad-eval-runner/scripts/run_triggers.py b/skills/bmad-eval-runner/scripts/run_triggers.py
index a406b27..c566346 100644
--- a/skills/bmad-eval-runner/scripts/run_triggers.py
+++ b/skills/bmad-eval-runner/scripts/run_triggers.py
@@ -38,7 +38,7 @@
 and records "skipped: no runtime adapter configured" rather than crashing.
 
 Usage:
-  python3 run_triggers.py \\
+  uv run run_triggers.py \\
     --skill-path SKILL_DIR \\
     --queries QUERIES.json \\
     --output-dir DIR \\
diff --git a/skills/bmad-eval-runner/scripts/tests/test_env_isolation.py b/skills/bmad-eval-runner/scripts/tests/test_env_isolation.py
index 7138412..205a5a0 100644
--- a/skills/bmad-eval-runner/scripts/tests/test_env_isolation.py
+++ b/skills/bmad-eval-runner/scripts/tests/test_env_isolation.py
@@ -6,8 +6,8 @@
 deliberately self-contained); this test pins the contract on both copies:
 exactly PATH + fresh HOME + CLAUDE_CONFIG_DIR + auth-var-only-when-set +
 declared passthrough keys, nothing else.
-Run with: python3 -m pytest test_env_isolation.py
-(or plain `python3 test_env_isolation.py` for a lightweight self-check).
+Run with: uv run --with pytest -m pytest test_env_isolation.py
+(or plain `uv run test_env_isolation.py` for a lightweight self-check).
 """
 import sys
 from pathlib import Path
diff --git a/skills/bmad-eval-runner/scripts/tests/test_trigger_detection.py b/skills/bmad-eval-runner/scripts/tests/test_trigger_detection.py
index 4c3e5fa..6e70f64 100644
--- a/skills/bmad-eval-runner/scripts/tests/test_trigger_detection.py
+++ b/skills/bmad-eval-runner/scripts/tests/test_trigger_detection.py
@@ -6,8 +6,8 @@
 rate. These tests pin the rule: only tool_use events (a Skill call naming the
 synthetic skill, or a Read inside its directory) count as a load, and
 substring-style load signals are rejected outright.
-Run with: python3 -m pytest test_trigger_detection.py
-(or plain `python3 test_trigger_detection.py` for a lightweight self-check).
+Run with: uv run --with pytest -m pytest test_trigger_detection.py
+(or plain `uv run test_trigger_detection.py` for a lightweight self-check).
 """
 import json
 import sys
diff --git a/skills/bmad-module-builder/assets/setup-skill-template/SKILL.md b/skills/bmad-module-builder/assets/setup-skill-template/SKILL.md
index 1712675..82c20ae 100644
--- a/skills/bmad-module-builder/assets/setup-skill-template/SKILL.md
+++ b/skills/bmad-module-builder/assets/setup-skill-template/SKILL.md
@@ -45,8 +45,8 @@ Write a temp JSON file with the collected answers structured as `{"core": {...},
 In the commands below, replace `{project-root}` in every path argument with the actual project root (e.g. `/home/me/myapp`) before running — these are filesystem paths, not config values.
 
 ```bash
-python3 ./scripts/merge-config.py --config-path "{project-root}/_bmad/config.yaml" --user-config-path "{project-root}/_bmad/config.user.yaml" --module-yaml ./assets/module.yaml --answers {temp-file} --legacy-dir "{project-root}/_bmad"
-python3 ./scripts/merge-help-csv.py --target "{project-root}/_bmad/module-help.csv" --source ./assets/module-help.csv --legacy-dir "{project-root}/_bmad" --module-code {module-code}
+uv run ./scripts/merge-config.py --config-path "{project-root}/_bmad/config.yaml" --user-config-path "{project-root}/_bmad/config.user.yaml" --module-yaml ./assets/module.yaml --answers {temp-file} --legacy-dir "{project-root}/_bmad"
+uv run ./scripts/merge-help-csv.py --target "{project-root}/_bmad/module-help.csv" --source ./assets/module-help.csv --legacy-dir "{project-root}/_bmad" --module-code {module-code}
 ```
 
 Both scripts output JSON to stdout with results. If either exits non-zero, surface the error and stop. The scripts automatically read legacy config values as fallback defaults, then delete the legacy files after a successful merge. Check `legacy_configs_deleted` and `legacy_csvs_deleted` in the output to confirm cleanup.
@@ -64,7 +64,7 @@ After both merge scripts complete successfully, remove the installer's package d
 As with the merge scripts, replace `{project-root}` in the `--bmad-dir` and `--skills-dir` path arguments with the actual project root before running.
 
 ```bash
-python3 ./scripts/cleanup-legacy.py --bmad-dir "{project-root}/_bmad" --module-code {module-code} --also-remove _config --skills-dir "{project-root}/.claude/skills"
+uv run ./scripts/cleanup-legacy.py --bmad-dir "{project-root}/_bmad" --module-code {module-code} --also-remove _config --skills-dir "{project-root}/.claude/skills"
 ```
 
 The script verifies that every skill in the legacy directories exists at `.claude/skills/` before removing anything. Directories without skills (like `_config/`) are removed directly. If the script exits non-zero, surface the error and stop. Missing directories (already cleaned by a prior run) are not errors — the script is idempotent.
diff --git a/skills/bmad-module-builder/assets/standalone-module-template/module-setup.md b/skills/bmad-module-builder/assets/standalone-module-template/module-setup.md
index f6f8508..380b9ff 100644
--- a/skills/bmad-module-builder/assets/standalone-module-template/module-setup.md
+++ b/skills/bmad-module-builder/assets/standalone-module-template/module-setup.md
@@ -56,8 +56,8 @@ Write a temp JSON file with the collected answers structured as `{"core": {...},
 In the commands below, replace `{project-root}` in every path argument with the actual project root (e.g. `/home/me/myapp`) before running — these are filesystem paths, not config values.
 
 ```bash
-python3 ./scripts/merge-config.py --config-path "{project-root}/_bmad/config.yaml" --user-config-path "{project-root}/_bmad/config.user.yaml" --module-yaml ./assets/module.yaml --answers {temp-file}
-python3 ./scripts/merge-help-csv.py --target "{project-root}/_bmad/module-help.csv" --source ./assets/module-help.csv --module-code {module-code}
+uv run ./scripts/merge-config.py --config-path "{project-root}/_bmad/config.yaml" --user-config-path "{project-root}/_bmad/config.user.yaml" --module-yaml ./assets/module.yaml --answers {temp-file}
+uv run ./scripts/merge-help-csv.py --target "{project-root}/_bmad/module-help.csv" --source ./assets/module-help.csv --module-code {module-code}
 ```
 
 Both scripts output JSON to stdout with results. If either exits non-zero, surface the error and stop.
diff --git a/skills/bmad-module-builder/references/create-module.md b/skills/bmad-module-builder/references/create-module.md
index 0905caf..ffb6fc4 100644
--- a/skills/bmad-module-builder/references/create-module.md
+++ b/skills/bmad-module-builder/references/create-module.md
@@ -170,7 +170,7 @@ Iterate until the user confirms everything is correct.
 Write the confirmed module.yaml and module-help.csv content to temporary files at `{bmad_builder_reports}/{module-code}-temp-module.yaml` and `{bmad_builder_reports}/{module-code}-temp-help.csv`. Run the scaffold script:
 
 ```bash
-python3 ./scripts/scaffold-setup-skill.py \
+uv run ./scripts/scaffold-setup-skill.py \
   --target-dir "{skills-folder}" \
   --module-code "{code}" \
   --module-name "{name}" \
@@ -190,7 +190,7 @@ This creates `{code}-setup/` in the user's skills folder containing:
 Write the confirmed module.yaml and module-help.csv directly to the skill's `assets/` folder (create the folder if needed). Then run the standalone scaffold script to copy the template infrastructure:
 
 ```bash
-python3 ./scripts/scaffold-standalone-module.py \
+uv run ./scripts/scaffold-standalone-module.py \
   --skill-dir "{skill-folder}" \
   --module-code "{code}" \
   --module-name "{name}"
diff --git a/skills/bmad-module-builder/references/validate-module.md b/skills/bmad-module-builder/references/validate-module.md
index d1b3459..0b21106 100644
--- a/skills/bmad-module-builder/references/validate-module.md
+++ b/skills/bmad-module-builder/references/validate-module.md
@@ -20,7 +20,7 @@ Ask the user for the path to their module's skills folder (or a single skill fol
 Run the validation script for deterministic checks:
 
 ```bash
-python3 ./scripts/validate-module.py "{module-skills-folder}"
+uv run ./scripts/validate-module.py "{module-skills-folder}"
 ```
 
 This checks: module structure (setup skill or standalone), module.yaml completeness, CSV integrity (missing entries, orphans, duplicate menu codes, broken before/after references, missing required fields). For standalone modules, it also verifies the presence of module-setup.md and merge scripts.
diff --git a/skills/bmad-workflow-builder/scripts/tests/test_canon_sync.py b/skills/bmad-workflow-builder/scripts/tests/test_canon_sync.py
index 6b62b37..232bb5d 100644
--- a/skills/bmad-workflow-builder/scripts/tests/test_canon_sync.py
+++ b/skills/bmad-workflow-builder/scripts/tests/test_canon_sync.py
@@ -6,8 +6,8 @@
 agents — with no in-file sync note, because the loaded files are LLM-facing
 and a maintenance comment there is paid on every load. This test is the
 sync mechanism instead: all three copies must be byte-identical.
-Run with: python3 -m pytest test_canon_sync.py
-(or plain `python3 test_canon_sync.py` for a lightweight self-check).
+Run with: uv run --with pytest -m pytest test_canon_sync.py
+(or plain `uv run test_canon_sync.py` for a lightweight self-check).
 """
 import sys
 from pathlib import Path
diff --git a/skills/bmad-workflow-builder/scripts/tests/test_count_tokens.py b/skills/bmad-workflow-builder/scripts/tests/test_count_tokens.py
index 2bb4b6a..3871ad4 100644
--- a/skills/bmad-workflow-builder/scripts/tests/test_count_tokens.py
+++ b/skills/bmad-workflow-builder/scripts/tests/test_count_tokens.py
@@ -3,8 +3,8 @@
 
 Covers the output schema, the tiktoken path and the forced-fallback path
 agreeing within tolerance, the CLI over a file and over stdin, and argument
-guards. Run with: python3 -m pytest test_count_tokens.py
-(or plain `python3 test_count_tokens.py` to run a lightweight self-check).
+guards. Run with: uv run --with pytest -m pytest test_count_tokens.py
+(or plain `uv run test_count_tokens.py` to run a lightweight self-check).
 """
 import builtins
 import importlib.util
diff --git a/skills/bmad-workflow-builder/scripts/tests/test_render_report.py b/skills/bmad-workflow-builder/scripts/tests/test_render_report.py
index 156a265..7d49200 100644
--- a/skills/bmad-workflow-builder/scripts/tests/test_render_report.py
+++ b/skills/bmad-workflow-builder/scripts/tests/test_render_report.py
@@ -4,8 +4,8 @@
 Covers: valid island injection, refusal on malformed JSON, refusal on the
 placeholder subject, the --md archival rendering, and that both shipped
 shells carry a parseable placeholder island.
-Run with: python3 -m pytest test_render_report.py
-(or plain `python3 test_render_report.py` for a lightweight self-check).
+Run with: uv run --with pytest -m pytest test_render_report.py
+(or plain `uv run test_render_report.py` for a lightweight self-check).
 """
 import json
 import re