Add clean command

docs/cli.md

@@ -24,6 +24,7 @@ Implemented commands:
 - `session init`: create local or remote `session.yml`.
 - `artifacts list`: list effective artifact source IDs.
 - `locks`: list, add, and remove archive promotion locks.
+- `clean`: remove local workspace/spool state for one session or all local sessions.
 
 Unknown commands print usage and exit non-zero.
 
@@ -94,6 +95,17 @@ Valid stage names:
 - `--force`: overwrite local conflicting files with remote archive files.
 - `--include-audio`: include durable archived `audio/**` files in restore scope.
 
+### `clean`
+
+- `--session-id <value>`: required for session cleanup unless `--all` is set.
+- `--config <path>`
+- `--campaign <path>`
+- `--session <path>`
+- `--previous-session-id <value>`
+- `--all`: clean all local session work/spool state using pipeline config only.
+- `--dry-run`: print cleanup targets without deleting.
+- `--clear-cache`: also remove matching S3 audio cache entries.
+
 ### `status`
 
 - `--manifest <path>`: inspect one manifest file.
@@ -378,6 +390,38 @@ Common failure cases:
 
 When `--include-audio` is set, S3 audio files are restored through the shared audio cache. Cache hits avoid re-downloading large audio objects.
 
+### `clean`
+
+Purpose:
+- Remove local Narratio work/spool state for testing, reruns, or recovery from corrupted local files.
+- Preserve durable S3 audio cache state unless `--clear-cache` is passed.
+
+Syntax:
+
+```bash
+narratio clean --session-id <id> [--config <pipeline.yml>] [--campaign <campaign.yml>] [--session <session.yml>] [--previous-session-id <id>] [--dry-run] [--clear-cache]
+narratio clean --all [--config <pipeline.yml>] [--dry-run] [--clear-cache]
+```
+
+Session cleanup deletes:
+- `{workspace.root}/work/{campaign}/{session_id}`
+- `{spool.root}/{campaign}/{session_id}`
+
+All-session cleanup deletes:
+- `{workspace.root}/work`
+- the contents of `{spool.root}`, while preserving the spool root directory itself.
+
+Cache behavior:
+- cache is preserved by default.
+- `--clear-cache` in session mode removes cached S3 audio files for the resolved session.
+- `--all --clear-cache` removes the configured Narratio S3 audio cache namespace for the configured bucket/root prefix.
+- `--clear-cache` does not delete arbitrary files under `pipeline.cache.root`.
+
+Common failure cases:
+- missing `--session-id` when `--all` is not set.
+- combining `--all` with `--campaign`, `--session`, `--session-id`, or `--previous-session-id`.
+- unsafe cleanup target, such as a symlink, a non-directory session target, a configured root directory, or a path outside the configured root.
+
 ## Common Workflows
 
 Default-discovery run:
@@ -423,6 +467,20 @@ Rehydrate canonical previous-session inputs after artifact-input changes:
 narratio run-stage --session-id 2026-04-04 --force prepare
 ```
 
+Reset local state before testing restore:
+
+```bash
+narratio clean --session-id 2026-04-04 --dry-run
+narratio clean --session-id 2026-04-04
+narratio restore --session-id 2026-04-04 --include-audio
+```
+
+Clean all local sessions while keeping cached S3 audio:
+
+```bash
+narratio clean --all
+```
+
 ## Diagnostic / Recovery Commands
 
 Inspect stage status: