docs(disk-hygiene): fix run-directory, fan-out brief and --project-dir wording

plugins/disk-hygiene/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "disk-hygiene",
-  "version": "0.34.2",
+  "version": "0.34.3",
   "description": "Context-aware disk hygiene for arbitrary directory trees: inventories orphaned and temporary artifacts, classifies evidence into review tiers, and offers exact-path cleanup only after a fresh safety preview and explicit per-tier approval. The target is read-only by default; OS-managed paths, links and mount points, VCS-tracked content without the complete checkout evidence bundle, changed entries, and live-handle uncertainty fail closed.",
   "author": {
     "name": "Melodic Software",

plugins/disk-hygiene/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to the `disk-hygiene` plugin are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.
 
+## [0.34.3] - 2026-09-30
+
+### Fixed
+
+- **`/disk-hygiene:clean` docs match the engine**
+  ([#5520](https://github.com/melodic-software/claude-code-plugins/issues/5520)). Section 1 says the
+  engine creates the run directory instead of telling the agent to create it. The fan-out worker
+  brief tells the parent to fill `<hook-python>`, `<engine>`, `<data-root>`, `<run-dir>` and the
+  optional `<project-dir>` with literal absolute values, since a worker cannot expand `${...}`
+  tokens, and states that `--project-dir` is optional.
+
 ## [0.34.2] - 2026-09-30
 
 ### Fixed

plugins/disk-hygiene/skills/clean/SKILL.md

@@ -165,8 +165,9 @@ and has no entry cap. Detail:
 
 ## 1. Create a read-only snapshot
 
-Create a unique run directory under `${CLAUDE_PLUGIN_DATA}/runs/`; snapshots, plans, and reports must
-stay there, never in the target or `${CLAUDE_PLUGIN_ROOT}`. Run:
+Choose a unique run-directory path under `${CLAUDE_PLUGIN_DATA}/runs/`; the engine creates it (it
+creates the parent of `--output`). Snapshots, plans, and reports must stay there, never in the target
+or `${CLAUDE_PLUGIN_ROOT}`. Run:
 
 ```text
 "<hook-python>" "${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/hygiene.py" scan \

plugins/disk-hygiene/skills/clean/reference/fan-out-worker-brief.md

@@ -4,21 +4,32 @@ Evidence-only subtree worker for `/disk-hygiene:clean` home or large-target audi
 owns classification, the single report, approvals, preview, and execution. You return scan
 evidence only.
 
+## Parent: fill the placeholders before spawning
+
+A worker cannot expand `${...}` tokens (the guard rejects shell expansion), so every value it needs
+must be a literal in its spawn prompt. Before spawning, replace `<hook-python>` and `<data-root>`
+with the literal values from the guard-values note (the probe in `SKILL.md` only when the note is absent). Fill
+`<engine>` with `${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/` plus the engine filename, `<run-dir>`
+with the run directory you chose, and, when it applies, `<project-dir>` with `${CLAUDE_PROJECT_DIR}`,
+each as a literal absolute path.
+
 ## Bash contract (instructions to you; the belt may not enforce them in a subagent)
 
 The session's skill-frontmatter belt is not reliably active inside a subagent, so nothing here is
-enforced for you by that belt. The plugin-level engine gate still checks any call that names
-`hygiene.py`. Follow the contract yourself.
+enforced for you by that belt. The plugin-level engine gate still checks any call that names the
+engine. Follow the contract yourself.
+
+Make every engine call a **single** invocation of the engine with no shell chaining, redirection,
+or extra commands in the same tool call. Required flags on every scan:
 
-Make every engine call a **single** invocation of `hygiene.py` with no shell chaining,
-redirection, or extra commands in the same tool call. Required flags on every scan:
+- `--data-root "<data-root>"` (the plugin data directory the engine gate authorizes)
+- `--output "<run-dir>/snapshot.json"` under `<data-root>/runs/…`, never inside the target
 
-- `--data-root "${CLAUDE_PLUGIN_DATA}"` (the plugin data directory the engine gate authorizes)
-- `--project-dir "${CLAUDE_PROJECT_DIR}"` when the consumer project has standing policy files
-- `--output "<run-dir>/snapshot.json"` under `${CLAUDE_PLUGIN_DATA}/runs/…`, never inside the target
+`--project-dir` is optional: pass it (as a literal absolute path filled by the parent) only when the
+session's project has standing policy that should apply to the target, and omit it otherwise, for
+example in a home-directory session; the engine then skips the project policy layer.
 
-Use the hook Python launcher from the skill (`<hook-python>` in `SKILL.md`), not a bare `python3`
-on PATH.
+Use the hook Python launcher the parent filled in for `<hook-python>`, not a bare `python3` on PATH.
 
 Do not run `apply`, `preview`, `handoff-verify`, `catalog`, `rm`, `del`, moves, or any command that
 mutates the target. Do not wrap the engine in compound shells (`;`, `&&`, `|`).
@@ -28,9 +39,9 @@ mutates the target. Do not wrap the engine in compound shells (`;`, `&&`, `|`).
 **Exact subtree sizing (no per-entry inventory, no entry cap):**
 
 ```text
-"<hook-python>" "${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/hygiene.py" scan \
+"<hook-python>" "<engine>" scan \
   --target "<subtree-path>" --output "<run-dir>/sizes.json" \
-  --project-dir "${CLAUDE_PROJECT_DIR}" --data-root "${CLAUDE_PLUGIN_DATA}" \
+  --data-root "<data-root>" [--project-dir "<project-dir>"] \
   --sizes-only
 ```
 
@@ -41,9 +52,9 @@ floors.
 **Bounded inventory (hints + handoff paths):**
 
 ```text
-"<hook-python>" "${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/hygiene.py" scan \
+"<hook-python>" "<engine>" scan \
   --target "<subtree-path>" --output "<run-dir>/snapshot.json" \
-  --project-dir "${CLAUDE_PROJECT_DIR}" --data-root "${CLAUDE_PLUGIN_DATA}" \
+  --data-root "<data-root>" [--project-dir "<project-dir>"] \
   [--max-depth <N>] [--confirmed-large-scan]
 ```
 
@@ -52,9 +63,9 @@ Depth-cut rollups carry `walked: false` and `unwalked_reasons`; do not treat the
 **Home fan-out after depth-1 (selected top-level children only):**
 
 ```text
-"<hook-python>" "${CLAUDE_PLUGIN_ROOT}/skills/clean/scripts/hygiene.py" scan \
+"<hook-python>" "<engine>" scan \
   --target "<home-path>" --output "<run-dir>/snapshot.json" \
-  --project-dir "${CLAUDE_PROJECT_DIR}" --data-root "${CLAUDE_PLUGIN_DATA}" \
+  --data-root "<data-root>" [--project-dir "<project-dir>"] \
   --root-children --root-child "<ChildName>" [--root-child "<Other>"]...
 ```
 

scripts/spoke-plugin-root-baseline.txt

@@ -54,7 +54,7 @@ plugins/context-guard/skills/setup/reference/legacy-statusline-detect.md 2
 plugins/context-guard/skills/setup/reference/statusline-edit.md 3
 plugins/context-guard/skills/setup/reference/unwrap-before-compose.md 1
 plugins/context7/skills/lookup/context/update.md 3
-plugins/disk-hygiene/skills/clean/reference/fan-out-worker-brief.md 3
+plugins/disk-hygiene/skills/clean/reference/fan-out-worker-brief.md 1
 plugins/disk-hygiene/skills/clean/reference/safety-model.md 7
 plugins/disk-hygiene/skills/clean/reference/unsupported-platform-handoff.md 2
 plugins/dometrain/skills/sync/context/update.md 2