Harden demo export cleanup safety

docs/CODEX_EXECUTION_LOG.md

@@ -2267,3 +2267,27 @@ Limitations:
 
 Next recommended pass:
 - Consider a safe export retention/cleanup command if the artifact table keeps growing beyond demo needs.
+
+## Sprint 57 safer demo export cleanup (2026-06-17)
+
+Changed:
+- Hardened the existing dry-run-first demo export cleanup command instead of creating a parallel cleanup path.
+- Added `--max-delete` with a default cap of 25 so large `--apply` runs are blocked until explicitly reviewed and raised.
+- Added repeatable `--export-type` filters for targeted cleanup, e.g. reports only.
+- Extended the cleanup summary with `keep_latest`, `max_delete`, `export_types`, `type_filtered_export_count` and `blocked_reason`.
+- Updated the root wrapper to expose the new filter helper.
+- Updated `scripts/README.md`, `docs/STORAGE_ARCHITECTURE.md`, `backend/README.md`, `docs/TODO.md` and `CHANGELOG.md`.
+- Added regression coverage for export-type filtering, parser defaults and max-delete options.
+
+Tested:
+- `python -m py_compile scripts/cleanup_demo_artifacts.py backend/scripts/cleanup_demo_artifacts.py`
+- `cd backend && python -m pytest tests/test_sprint24_cleanup_demo_artifacts.py tests/test_readiness_gate.py -q` (`16 passed`)
+
+Open:
+- Run full readiness, deploy Tower and optionally perform a live cleanup dry run inside the all-in-one container before using `--apply`.
+
+Limitations:
+- Cleanup still targets demo export records/files only. It does not delete source uploads, vector features, projects, AOIs, QA/QC records, rasters, tiles, masks or production data.
+
+Next recommended pass:
+- Add a small live maintenance smoke that runs cleanup in dry-run mode through the deployed all-in-one container.

docs/STORAGE_ARCHITECTURE.md

@@ -103,7 +103,8 @@ Offline demo export artifacts can be inspected and cleaned with:
 
 ```bash
 python scripts/cleanup_demo_artifacts.py
-python scripts/cleanup_demo_artifacts.py --keep-latest 3 --apply
+python scripts/cleanup_demo_artifacts.py --keep-latest 10 --export-type project_report_html
+python scripts/cleanup_demo_artifacts.py --keep-latest 10 --max-delete 100 --apply
 docker compose exec -T backend python scripts/cleanup_demo_artifacts.py
 ```
 
@@ -112,7 +113,9 @@ The script is dry-run by default, targets only the explicit
 provided, keeps the newest export artifacts per matching project and refuses to
 delete files outside `STORAGE_ROOT`. It cleans `exports` records/files only; it
 does not remove original uploads, vector features, QA/QC rows, projects, areas,
-tiles, rasters or masks.
+tiles, rasters or masks. `--max-delete` defaults to 25 and blocks oversized
+apply runs until the operator increases the cap after reviewing dry-run output.
+Repeat `--export-type` to restrict cleanup to selected artifact kinds.
 
 ## Model storage
 

docs/TODO.md

@@ -326,4 +326,5 @@ This file now starts with the current implementation status. Older preparation/b
 - [x] Improve populated Data/Exports readability after a demo workflow run.
 - [x] Improve live visual shell width, scroll behavior and Map workspace layout at 1280px.
 - [x] Add export history filtering controls for long-running demo environments.
-- [ ] Add a safe export retention/cleanup command for demo environments.
+- [x] Add a safe export retention/cleanup command for demo environments.
+- [ ] Add a live dry-run maintenance smoke for demo export cleanup.