# AI File System Cleanup & Digital Declutter

> Reclaim chaotic Downloads/ and Desktop folders without losing irreplaceable files—combining dry-run manifests, SHA-256 duplicate sweeps, VLM/OCR receipt renaming, 30-day quarantine staging, and native macOS + Windows automation.

- **Topic:** [Desktop & Personal Ops](https://twelve-pages.com/topics/desktop-and-os)
- **Web Edition:** https://twelve-pages.com/guides/desktop-and-os/ai-file-system-cleanup-and-declutter
- **Printable 12-Page PDF:** https://twelve-pages.com/guides/desktop-and-os/ai-file-system-cleanup-and-declutter/AI_File_System_Cleanup_and_Declutter_Complete_How_To_Guide.pdf (3.1 MB)
- **Version:** v1.0 (Updated 2026-11)
- **Reading Time:** 12 minutes (12 pages)
- **Authorship:** AI-authored under human editorial direction & print QA (https://twelve-pages.com/editorial)
- **Tags:** Dry-Run Manifests · SHA-256 Dedup Sweeps · VLM / OCR PDF Naming · 30-Day Quarantine Gate · Mac Hazel vs. Windows · Cowork & Gemini CLI

## Core Takeaways

- **Plan Before Moving a Byte:** Generate readable dry-run manifests (manifest.csv or -WhatIf) with strict node_modules and .DS_Store exclusions before touching live folders.
- **Verify Exact & Visual Clones:** Pair rmlint, fdupes, and Python hashlib SHA-256 checksums with VLM/OCR metadata to name scans cleanly by vendor and date.
- **30-Day Quarantine Shield:** Stage redundant installers and clutter in _quarantine_30d/ with an undo ledger across macOS Hazel, Windows PowerRename, Cowork, and Gemini CLI.

## 1. Why Manifest-First Cleanup Beats Blind Auto-Delete

Pointing an over-eager script or AI assistant straight at a cluttered Downloads/ or Desktop/ folder is the fastest way to break local Git repositories, corrupt half-finished browser transfers, or erase tax receipts. The safest approach treats cleanup like a disciplined engineering deployment: scan read-only, exclude active code trees, verify SHA-256 digests, review a dry-run manifest, and stage removals inside a 30-day quarantine folder.

### Quick Navigation

### The Golden Rule: Never Rename or Delete in One Hop

Humans create clutter incrementally, so your cleanup workflow should unwind it in reversible layers. Separate **discovery** (hashing bytes and reading PDFs) from **decision** (reviewing your proposed move table) and **execution** (routing keepers to clean buckets while parking discards inside `_quarantine_30d/`).

### Architecture: Read-Only Discovery to Reversible Staging

#### Exclude Dev & OS Trees Before Measuring Anything

Even a modest developer laptop hides 120,000+ identical tiny files inside `node_modules/`, `.venv/`, and `.DS_Store` caches. Always apply a hard ignore list on step zero so your cleanup manifest focuses strictly on real documents, installers, screenshots, and archives.

## 2. Safety Exclusions, Hash Tools & Cleanup Matrix

Before invoking a single rename rule or AI planner, lock down what must never be touched and choose the right blend of fast deterministic CLI engines and vision-capable AI helpers for your operating system.

#### 1 Mandatory Exclusion Rules (Never Touch)

- **OS Metadata Files:** Ignore `.DS_Store`, `._*` AppleDouble forks, `Thumbs.db`, and `desktop.ini` so duplicate sweeps never choke on folder-view clutter.
- **Code & Build Trees:** Prune `node_modules/`, `.git/`, `.venv/`, `__pycache__/`, `target/`, `dist/`, and `build/`—identical boilerplate files inside dependencies are structural, not waste.
- **Active Transfers & Stubs:** Skip `*.crdownload`, `*.part`, `*.download`, and unhydrated `.icloud` placeholders unless age exceeds 24 hours.

#### 2 60-Second Cross-Platform Workbench

- **macOS CLI Stack:** Install `brew install rmlint fdupes ocrmypdf`; pair with built-in Spotlight `mdfind`, Finder Folder Actions, and optional **Hazel 6**.
- **Windows 11 Stack:** Install `winget install Microsoft.PowerToys` for **PowerRename** + built-in **PowerShell 7** (`Get-FileHash`, `-WhatIf`).
- **AI Planners:** Run **Claude Cowork** scoped strictly to `Downloads/`, or **Gemini CLI** with `--approval-mode plan --sandbox` for read-only manifests.

#### Universal Exclude List (Paste Into Every CLI Flag, Script & Agent Prompt)

Exclude paths matching: `.git/**` `node_modules/**` `.venv/**` `dist/**` `target/**` `*.DS_Store` `Thumbs.db` `*.crdownload` `*.part` `_quarantine_30d/**`

### Deduplication, Renaming & AI Cleanup Tool Matrix

| Tool / Engine | OS Support | Verification & Dry-Run Mode | Primary Superpower | Best-Fit Cleanup Task |
| --- | --- | --- | --- | --- |
| **rmlint** *C CLI Linter* | macOS, Linux, Win (WSL2) | Generates `rmlint.sh`; test safely via `./rmlint.sh -n`. | `--algorithm=sha256` + `-p` byte check; ultra fast. | Sweeping large media, backup & archive trees safely. |
| **fdupes / jdupes** *Classic CLI* | macOS, Linux, Win ports | **Dry-run by default:** prints dupes; deletes only with `-d`. | Size + MD5 + byte-for-byte check; `-A` skips hidden files. | Quick scriptable text reports & pipe-to-quarantine lists. |
| **Python `hashlib`** *Custom Script* | macOS, Windows, Linux | Writes `manifest.csv` first; requires explicit `--apply`. | `file_digest(..., "sha256")` + custom `_quarantine_30d/`. | Cross-OS reproducible sweeps with rollback CSV logs. |
| **Hazel 6 / PowerRename** *OS Native GUI* | Hazel (Mac) / PowerToys (Win) | `Option+Cmd+P` Preview + Finder Revert / Live preview grid. | Hazel on-the-fly OCR / PowerRename Regex + EXIF/XMP. | Continuous background inbox rules & visual bulk renames. |
| **Claude Cowork & Gemini CLI** | macOS & Windows Desktop / CLI | Approval-gated dry run / `--approval-mode plan --sandbox`. | Semantic PDF/screenshot reading & smart categorization. | Taming messy `Downloads/` & naming ambiguous docs. |

#### Scope Boundary Rule: Never Grant Cleanup Access to Your Home Root

Point Cowork, Gemini CLI, or custom scripts exclusively at leaf folders like `~/Downloads`, `~/Desktop`, or `C:\Users\You\Downloads`. Never aim automated sorters at `~/`, `~/Library`, `AppData`, or active project repositories.

## 3. Annotated Tour: Inside a Safe Declutter Cockpit

Whether you inspect a manifest in Claude Cowork, preview rules in Hazel 6, or review a Python/PowerShell dry-run table in your terminal, every trustworthy cleanup workflow exposes the exact same seven visual checkpoints before moving a single file.

Declutter Cockpit • ~/Downloads (1,428 files)

DRY-RUN Skipped: 14.9k _quarantine_30d/

Run: `2026-11-17_dl` • 0 bytes changed rollback_manifest.csv

**Proposed Dry-Run Manifest** 6 Target Buckets

[MOVE] Q4_Deck_Final.pptx -> Archive/Decks/
 [SKIP] app/node_modules/ -> Excluded rule #2
 [STAG] Chrome_v138.dmg (48d) -> _quarantine_30d/

**SHA-256 Exact Clone Cluster** sha256: 9f86d0...

**KEEP:** `Archive/Tax_2025_W2.pdf` (2.4 MB)
 **STAGE:** `Tax_2025_W2 (1).pdf` -> `_quarantine_30d/dupes/`

`gemini -p "audit Downloads" --approval-mode plan --sandbox`

ACTIVE EXCLUSION GUARD Pruned pre-hash

.DS_Store node_modules/ .git/ *.crdownload .venv/

VLM / OCR RENAME PREVIEW Conf: 0.98

**Before:** `Scan_20261018_0042.pdf`
 **After:** `2026-10-18_Cloudflare_Host.pdf`
 Date=2026-10-18 • Vendor=Cloudflare • Cat=Host

Awaiting human `--apply` approval Hazel • PowerRename

**Read-Only Dry-Run Mode:** Confirms zero destructive actions occur during scanning—matching `rmlint.sh -n`, PowerShell `-WhatIf`, and Gemini `plan` mode.

**Pre-Hash Exclusion Counter:** Shows dev builds, `.DS_Store`, and active browser downloads safely bypassed before hashing begins.

**Dry-Run Move Manifest:** Displays every source path, proposed bucket, and target name so you catch surprises before committing changes.

**SHA-256 Clone Cluster:** Groups byte-identical files regardless of filename, keeping one canonical original and staging duplicates safely.

**VLM / OCR Rename Preview:** Extracts date, vendor, and category from image-only scans into clean `YYYY-MM-DD_Vendor_Category.pdf` names.

**Approval-Gated Agent Bar:** Runs Claude Cowork or Gemini CLI inside strict folder sandboxes with explicit human sign-off required to execute moves.

**30-Day Quarantine Staging & Ledger:** Routes every duplicate and stale installer into `_quarantine_30d/YYYY-MM-DD/` alongside `rollback_manifest.csv` so you can restore any file in seconds during a full month cooling-off window.

## 4. SHA-256 Duplicate Sweeps: Zero-Guesswork Cleanup

Filename heuristics fail in both directions: two different monthly statements might both arrive as statement.pdf, while an identical 200 MB installer lurks under Docker.dmg and Docker (1).dmg. Size pre-filtering followed by SHA-256 hashing finds true clones with mathematical certainty.

*[Illustration: Editorial 3D still life where document cubes pass through a golden optical SHA-256 verification prism separating unique folders from duplicate glass cubes]*

**Size Bucket -> SHA-256 Digest -> Quarantine:** Two files only reach full cryptographic hashing if their exact byte sizes match first, keeping scans blazingly fast across tens of gigabytes.

### Three Proven Duplicate Sweep Engines

#### 1 `rmlint` Script-First Sweep

Rather than deleting live files, `rmlint` writes a clean executable script (`rmlint.sh`). Run `./rmlint.sh -n` first for a dry-run preview; pass `-p` if you want extra byte-by-byte verification alongside SHA-256.

#### 2 `fdupes` Default Dry Run

Classic `fdupes` (or faster C fork `jdupes`) prints duplicate sets without touching disk unless you pass `-d`. Add `-r -n -A -S` to recurse while skipping empty 0-byte files and hidden `.DS_Store` metadata.

#### 3 Python `hashlib.file_digest`

Available natively on both Mac and Windows in Python 3.11+, `hashlib.file_digest(f, "sha256")` streams huge video or ISO files at C speed without loading gigabytes into RAM.

#### 4 Keep Canonical, Stage Clones

Always sort each duplicate cluster to keep the shortest clean path outside `Downloads/` (or oldest original without `(1)`), routing remaining clones straight to `_quarantine_30d/dupes/`.

```
<code># 1) rmlint SHA-256 sweep (macOS / Linux / WSL2) -- generates rmlint.sh without touching files, then dry-run:
rmlint --algorithm=sha256 --types="duplicates" --output=sh -p ~/Downloads ~/Desktop && ./rmlint.sh -n

# 2) fdupes safe read-only report (skips 0-byte files -n and hidden dotfiles like .DS_Store -A):
fdupes -r -n -A -S ~/Downloads > ~/Desktop/dupes_preview.txt

# 3) Cross-OS Python 3.11+ SHA-256 hash helper (streams chunks cleanly at C speed):
python3 -c 'import hashlib, pathlib; print(hashlib.file_digest(open("invoice.pdf","rb"), "sha256").hexdigest())'</code>
```

#### Smart Original Selection Rule: Never Let Random Order Pick the Survivor

When deduplicating across `~/Documents` and `~/Downloads`, list your organized archive folder *before* `~/Downloads` on the CLI (or mark it as a tagged keeper with `rmlint ... // ~/Documents`) so copies in Downloads are staged instead of filed originals.

## 5. The 5-Part Safe Cleanup & Manifest Formula

Whether you write a Python cleanup script, configure a PowerShell audit, or prompt Claude Cowork and Gemini CLI, reliable file automation separates deterministic rules from AI judgment using five non-negotiable building blocks.

#### Deterministic Layer (Scripts & OS Tools)

- **Exact Extensions & Paths:** Moving `.dmg`/`.exe` installers, filtering `node_modules/`, and checking file age (>30 days).
- **Cryptographic Checksums:** Computing SHA-256 hashes and verifying post-move byte integrity.
- **Quarantine & Undo:** Writing deterministic CSV rollback ledgers before moving any file.

#### Semantic AI Layer (Cowork, Gemini, VLMs)

- **Fuzzy Document Triage:** Distinguishing a signed NDA from a draft slide deck or utility receipt.
- **OCR & Screenshot Naming:** Reading vendor logos and dates inside flattened PDFs and PNG screenshots.
- **Folder Proposal:** Clustering 400 random downloads into 5–6 clean, domain-specific folders.

### The 5-Part Guarded Declutter Formula

[1. Strict Scope] Target only `~/Downloads` & `~/Desktop`, [2. Exclusion Guard] skip `.DS_Store`, `node_modules`, `.git` & `*.crdownload`, [3. Hash & Schema] compute SHA-256 + `YYYY-MM-DD_Vendor_Category` names, [4. Dry-Run Manifest] write `manifest.csv` & pause for approval, [5. Quarantine Stage] and route discards to `_quarantine_30d/` instead of deleting.

| Formula Component | What It Enforces | What Fails When Skipped |
| --- | --- | --- |
| Strict Scope | Confines AI and scripts to messy drop zones (Downloads/Desktop). | Agents wander into git repos, app libraries, or synced cloud roots. |
| Exclusion Guard | Prunes dev artifacts, OS dotfiles, and active download partials upfront. | Scripts choke on 100k dependency files or corrupt live browser downloads. |
| Hash & Schema | Proves identical files via SHA-256 and enforces ISO dates on renames. | Files get mislabeled duplicates or collide on generic vendor names. |
| Dry-Run Manifest | Outputs an inspectable CSV/Markdown move plan with zero disk writes. | A single bad regex or hallucinated category scrambles 500 files silently. |
| Quarantine Stage | Holds duplicates and old installers for 30 days with an undo log. | Realizing a week later that an archived installer or tax PDF vanished. |

```
<code># Dry-run manifest generator pattern (safe by default; requires --apply to move files):
SKIP_DIRS = {".git", "node_modules", ".venv", "__pycache__", "dist", "build", "target", "_quarantine_30d"}
SKIP_EXTS = {".crdownload", ".part", ".download", ".tmp"}
# Manifest columns: action | sha256_prefix | size_mb | source_path | proposed_target | reason
# Example row: STAGE_DUPE | 9f86d081 | 2.41 | Downloads/W2 (1).pdf | _quarantine_30d/2026-11-17/W2 (1).pdf | Exact SHA-256 clone</code>
```

## 6. VLM & OCR Receipt Renaming: End Scan_042.pdf Chaos

Generic filenames like document(3).pdf, IMG_4821.HEIC, or Screenshot 2026-11-04.png bury tax deductions and receipts under unsearchable timestamps. Combining lightweight OCR with Vision-Language Models (VLMs) extracts clean metadata into universal YYYY-MM-DD_Vendor_Category.pdf sorting.

#### 1 Text Layer vs. VLM

Digital invoices already contain selectable text. Scanned receipts lack text layers: run `ocrmypdf --deskew --skip-text` first, or inspect page 1 directly with a VLM (Claude, Gemini, or local `qwen-vl`).

#### 2 Strict Filename Schema

Lock output to `YYYY-MM-DD_Vendor_Category.pdf`. Strip spaces, commas, slashes, and corporate suffixes (`Inc`, `LLC`) so filenames sort chronologically across Finder, Explorer, and terminal shells.

#### 3 Low-Confidence Fallback

If a blurry receipt returns missing dates or illegible totals, never guess: move it to `_needs_review/` or stamp file mtime with `_REVIEW` so your tax archive stays 100% trustworthy.

### Real-World Before & After Renaming Transformations

| Raw Incoming File | Extraction Pipeline | Clean Standardized Output |
| --- | --- | --- |
| `Scan_0042.pdf` *Flat scanner image PDF* | `ocrmypdf --deskew --skip-text` + JSON prompt | `2026-10-18_Cloudflare_Hosting.pdf` |
| `receipt_99182.pdf` *Airline e-ticket email PDF* | Direct `pdfplumber` text extract + category enum | `2026-09-30_Delta_Travel.pdf` |
| `Screenshot 2026-11-04.png` *Software SaaS checkout snap* | VLM image read -> PDF convert or PNG rename | `2026-11-04_Figma_Software.pdf` |
| `statement(3).pdf` *Monthly utility bill* | Hazel 6 on-the-fly OCR or local Ollama JSON parser | `2026-10-01_ConEd_Utility.pdf` |
| `tax_locked_2025.pdf` *Encrypted brokerage PDF* | Password prompt skipped -> routed safely for review | `_needs_ocr/tax_locked_2025.pdf` |

```
<code># 1) Add searchable OCR text layer to scanned PDFs (skips PDFs that already have text, straightens crooked scans):
ocrmypdf --deskew --skip-text raw_scan.pdf searchable_scan.pdf

# 2) Structured VLM / LLM JSON prompt for deterministic YYYY-MM-DD_Vendor_Category.pdf dry-run renaming:
"Inspect page 1 of this receipt. Return ONLY JSON:
 {"date": "YYYY-MM-DD", "vendor": "PascalCase", "category": "Hosting|Software|Travel|Utility|Tax", "confidence": 0.95}
 If date or vendor is unreadable, set confidence below 0.70 and return null for missing fields."</code>
```

#### Collision-Proof Renaming Rule: Append `_02`, Never Overwrite

Two legitimate receipts from the same vendor on the same day (like two Uber rides or separate AWS accounts) will collide on `2026-11-10_Uber_Travel.pdf`. Always check `if dest.exists()` and append `_02`, `_03` before renaming—never silently overwrite!

## 7. Mac vs. Windows Automation: Side-by-Side Playbook

Once a deep dry-run cleanup clears your backlog, wire native OS rules so incoming downloads sort themselves quietly every day. macOS pairs Hazel 6, Folder Actions, and Spotlight mdfind; Windows 11 pairs PowerToys PowerRename, File Explorer, and PowerShell.

*[Illustration: Two symmetrical obsidian and amber glass sorting lanes converging through a glowing inspection prism into organized archive drawers and a quarantine vault]*

**Cross-OS Parity:** Whether running macOS rules in Hazel and `mdfind` or Windows regex batches in PowerToys PowerRename and PowerShell `-WhatIf`, both ecosystems converge on identical dry-run safety.

### Side-by-Side Mac vs. Windows Automation Architecture

| Automation Need | macOS Stack (Finder, Hazel 6, Folder Actions, mdfind) | Windows 11 Stack (Explorer, PowerRename, PowerShell) |
| --- | --- | --- |
| **Continuous Inbox Rules** | **Hazel 6:** Watches `~/Downloads` & `Filing Inbox`; supports on-the-fly OCR, encrypted Keychain PDFs, and cloud-stub guards. | **Task Scheduler + PowerShell:** Runs scheduled sorting script cleanly on `$env:USERPROFILE\Downloads` using age & extension filters. |
| **Instant Drop Triggers** | **Folder Actions / Shortcuts:** Right-click folder -> *Services -> Folder Actions Setup* to run shell/AppleScript on new drops. | **Power Automate / FileSystemWatcher:** Triggers script or Power Automate Desktop flow whenever PDFs land in `Receipts\Inbox`. |
| **Bulk Pattern & Photo Rename** | **Finder Rename + Hazel Tokens:** Select items -> right-click *Rename*; Hazel extracts custom text/date tokens automatically. | **PowerToys PowerRename:** Explorer right-click GUI (no native CLI); supports `$1` Regex capture groups, EXIF/XMP photo tags & Copilot hints. |
| **Instant Metadata Search** | **Spotlight `mdfind`:** Queries system index instantaneously (`mdfind "kind:pdf invoice"` or stale `.dmg` sweeps). | **PowerShell + Explorer Search:** `Get-ChildItem -File -Recurse` with `Where-Object` filters and File Explorer `datemodified:` chips. |
| **Dry-Run & Undo Safety** | **Hazel Preview (`Opt+Cmd+P`):** Tests rules before enabling; Finder right-click **Revert** undoes misfiled Hazel moves. | **`-WhatIf` & PowerRename Grid:** PowerRename shows live Before/After preview; PowerShell `Move-Item -WhatIf` logs moves safely. |

```
<code># macOS Spotlight mdfind audit (lists .dmg/.pkg installers in Downloads untouched for 30+ days, zero changes):
mdfind -onlyin ~/Downloads '(kMDItemFSName == "*.dmg" || kMDItemFSName == "*.pkg") && kMDItemLastUsedDate < $time.today(-30)'

# Windows PowerShell dry-run staging + SHA-256 manifest (-WhatIf simulates moves without touching disk):
$q = "$env:USERPROFILE\Downloads\_quarantine_30d\$(Get-Date -Format yyyy-MM-dd)"; New-Item $q -ItemType Directory -Force | Out-Null
Get-ChildItem "$env:USERPROFILE\Downloads" -File | Where-Object { $_.Extension -in ".exe",".msi",".zip" -and $_.LastWriteTime -lt (Get-Date).AddDays(-30) } |
  Move-Item -LiteralPath { $_.FullName } -Destination $q -WhatIf</code>
```

## 8. 5 Real-World Copy-Paste Cleanup & Dry-Run Recipes

Paste these field-tested instructions straight into Claude Cowork, Gemini CLI, or your terminal scripts. Every single recipe enforces strict read-only dry runs and exclusion lists before a single byte moves.

| Recipe & Tool | Copy-Paste Prompt / Command Instruction | Output & Safety Gate |
| --- | --- | --- |
| **1. Downloads/ Dry Run** *Claude Cowork* | `Scope ONLY to ~/Downloads. Do NOT move or delete any files yet. Ignore .DS_Store, node_modules, .git, and *.crdownload. Analyze types, sizes, and duplicates; propose up to 6 clean buckets; write _cleanup_manifest.md and wait for my explicit approval.` | Produces `_cleanup_manifest.md`; zero writes until Turn 2 approval. |
| **2. Plan-Only Clutter Audit** *Gemini CLI* | `gemini -p "Inspect ./Downloads and ./Desktop read-only. Skip dev build folders and hidden OS files. Group stale installers (>30d), unfiled PDFs, and suspected clones into a JSON move table estimating reclaimed GB." --approval-mode plan --sandbox` | Hard read-only `plan` mode inside sandbox container. |
| **3. VLM Receipt Renamer** *OCR / Cowork / Local AI* | `Read page 1 of every PDF/PNG in ./Inbox_Receipts. Extract ISO date, VendorSlug, and Category (Hosting\|Travel\|Utility\|Tax\|Software). Output a dry-run table mapping current name -> YYYY-MM-DD_Vendor_Category.pdf. Route unreadable scans to _needs_ocr/.` | Dry-run rename preview; skips overwrite via `_02` suffix. |
| **4. SHA-256 Safe Dedup** *rmlint / Python* | `Sweep ~/Downloads and ~/Desktop using SHA-256 digests excluding .git, node_modules, .venv, and .DS_Store. Keep the oldest clean path outside Downloads; stage all exact clones into _quarantine_30d/dupes/ and write rollback_manifest.csv.` | Stages clones to `_quarantine_30d/` with full SHA-256 undo CSV. |
| **5. Dev Cache & Installer Trim** *Mac & Win CLI* | `Find stale node_modules/, target/, .venv/, and .dmg/.exe installers untouched for 60+ days. Verify no uncommitted Git changes exist in sibling repos, print total reclaimable GB, and wait for confirmation before staging to _quarantine_30d/.` | Preserves dirty Git worktrees; frees 10–40 GB safely. |

```
<code># Two-Turn Claude Cowork Approval Pattern (Turn 1 = Read-Only Dry Run; Turn 2 = Safe Quarantine Execution):
# Turn 1: Run Recipe #1 above inside Cowork scoped to Downloads/ only (disable auto-delete in settings).
# Turn 2 (after reviewing _cleanup_manifest.md):
"Approved with edits: leave Tax_2025_Drafts/ untouched. Move all remaining approved files into the 6 buckets,
stage duplicates and installers >30 days old into _quarantine_30d/2026-11-17/, and append every move to rollback_manifest.csv."</code>
```

#### Two-Turn Rule: Never Combine Plan & Move in One Prompt

Always make the agent stop after writing the manifest. Reviewing a 30-line dry-run summary takes 20 seconds and catches 99% of wrong-folder assumptions before anything changes on disk.

#### Cap Top-Level Buckets at Five or Six Folders

Tell Cowork or Gemini CLI never to create a subfolder with fewer than five files. Broad anchors like `01_Finance`, `02_Projects`, `03_Media`, `04_Installers`, and `_quarantine_30d` stay navigable for years.

## 9. Quarantine Staging, Privacy & Instant Rollback Safety

Real peace of mind comes from knowing every automated cleanup decision is completely reversible. By parking flagged items in a dated _quarantine_30d/ holding bay with an undo ledger—and keeping sensitive tax or health PDFs local—you eliminate catastrophic mistakes.

#### 1 The `_quarantine_30d/` Cooling-Off Protocol

- **Dated Staging Batches:** Move old installers, empty folders, and SHA-256 duplicates into `_quarantine_30d/YYYY-MM-DD/` instead of running `rm` or `Remove-Item`.
- **Machine-Readable Undo Ledger:** Log every moved item in `rollback_manifest.csv` with `timestamp`, `sha256`, `original_path`, and `quarantine_path`.
- **30-Day Purge Gate:** Only empty batches older than 30 days after verifying you still have a recent Time Machine, Windows File History, or cloud backup snapshot.

#### 2 Sensitive PDF & Metadata Privacy

- **Keep PII Local First:** Never upload unredacted tax forms, bank statements, passports, or medical records to consumer AI chats with training enabled.
- **Local OCR + Local Vision:** Use offline `ocrmypdf`, Hazel 6, or a local Ollama model for sensitive receipts, reserving cloud prompts for zero-retention/enterprise plans.
- **Strip GPS Before Sharing:** Before archiving or sharing phone photos, strip EXIF location coordinates using macOS Preview/Shortcuts or PowerShell/ExifTool.

### Five-Stage Safety Gate & Recovery Matrix

| Safety Gate | Required Guard / Condition | Audit Artifact Created | Recovery Time |
| --- | --- | --- | --- |
| **0. Pre-Sweep Snapshot** | Verify Time Machine / VSS / Cloud sync | Point-in-time OS restore point | Minutes (OS backup) |
| **1. Read-Only Dry Run** | `./rmlint.sh -n` / `-WhatIf` / `plan` | `_cleanup_manifest.md` or `.csv` | 0 sec (nothing moved) |
| **2. Quarantine Staging** | Explicit user `--apply` confirmation | `_quarantine_30d/YYYY-MM-DD/` + undo CSV | <5 sec (single script) |
| **3. Post-Move Verify** | Compare SHA-256 before deleting copies | Verified checksum match log | Instant integrity proof |
| **4. 30-Day Final Purge** | Folder age >30 days + zero missing refs | Moves batch to OS Trash / Recycle Bin | Still in OS Trash briefly |

```
<code># One-command Python Rollback (reads rollback_manifest.csv, verifies SHA-256, restores every file):
import csv, hashlib, shutil, pathlib
for row in reversed(list(csv.DictReader(open("_quarantine_30d/rollback_manifest.csv")))):
    q, orig = pathlib.Path(row["quarantine_path"]), pathlib.Path(row["original_path"])
    if q.exists() and hashlib.file_digest(q.open("rb"), "sha256").hexdigest() == row["sha256"]:
        orig.parent.mkdir(parents=True, exist_ok=True); shutil.move(str(q), str(orig))</code>
```

#### Cloud-Sync Trap: Watch Out for iCloud Drive & OneDrive Stubs

Deleting or moving a synced folder inside iCloud Drive, Dropbox, or OneDrive deletes it across every linked laptop and phone instantly. Always pause or check cloud sync status before purging `_quarantine_30d/`, and exclude cloud-only placeholder files from blind hash sweeps.

## 10. Cross-Tool Synergy: From Messy Drop Zone to Calm Archive

The calmest digital workspace pairs deterministic CLI and OS tools (rmlint, ocrmypdf, Hazel 6, PowerRename, PowerShell) for repeatable speed with AI planners (Claude Cowork and Gemini CLI) for messy, ambiguous documents—all flowing into one unified safety loop.

### Your 10-Minute Weekly Declutter Cadence

#### 1 Let OS Rules Catch Routine Noise

Keep **Hazel 6** (Mac) or scheduled **PowerShell** tasks (Windows) clearing 14-day-old installers, zip archives, and screenshots automatically so clutter never piles past a week.

#### 2 Run Friday Dry-Run AI Triage

Once a week, aim **Claude Cowork** or **Gemini CLI** (`--approval-mode plan`) at remaining mystery PDFs in `Downloads/`, approve the manifest, and rename receipts cleanly.

#### 3 Sweep Clones Monthly via SHA-256

Run `rmlint --algorithm=sha256` or Python `hashlib` once a month across media and docs, routing exact clones to `_quarantine_30d/` while preserving canonical archive paths.

#### 4 Empty Day-30 Quarantine Calmly

Glance at month-old folders inside `_quarantine_30d/` after confirming your backup ran; move expired batches to Trash with zero anxiety that you missed something vital.

#### Simplicity Scales: Stick to Shallow Folders & ISO Filenames

Deep 7-level folder trees collapse back into Desktop dumps because nobody remembers where files live. Pairing 5–6 broad root folders with descriptive `YYYY-MM-DD_Vendor_Category.pdf` names lets Spotlight `mdfind` and Windows Search find anything in 1 second.

## 11. Troubleshooting Clinic & 6-Point Pre-Flight Checklist

Reach for this clinic whenever .DS_Store floods a duplicate report, scanned PDFs refuse to rename, active browser downloads get moved prematurely, or Hazel skips cloud placeholders—followed by our 6-point pre-flight checklist.

| Symptom / Issue | Root Cause | 10-Second Fix |
| --- | --- | --- |
| **1. Scanner choked on 180,000 tiny code files** | Cleanup script traversed `node_modules/`, `.git/`, `.venv/`, or `target/`. | Add an early directory prune guard skipping `SKIP_DIRS` before entering subdirectories or hashing any files. |
| **2. Duplicate list full of `.DS_Store` & `Thumbs.db`** | Hidden OS folder-layout metadata files share identical default byte headers. | Pass `-A` (`--nohidden`) to `fdupes`, exclude dotfiles in `rmlint`, and filter `.DS_Store` / `desktop.ini` upfront. |
| **3. Browser download corrupted mid-transfer** | Folder watcher moved a `.crdownload`, `.part`, or `.download` temp file too early. | Exclude active partial-download extensions and add a rule requiring `modified age > 5 minutes` before sorting. |
| **4. Scanned receipt stayed `Scan_042.pdf`** | Image-only scan lacked an embedded text layer for regex or text tools to read. | Run `ocrmypdf --deskew --skip-text` first, enable Hazel 6 on-the-fly OCR, or pass page 1 to a Vision model. |
| **5. PowerToys PowerRename skipped subfolders** | Launched only on top-level selection, or regex didn't match target scope dropdown. | Expand subfolders inside Explorer search view, check *Use regular expressions*, or use PowerShell `Get-ChildItem -Recurse -WhatIf`. |
| **6. Hazel 6 rule ignored iCloud / Dropbox files** | Files were unhydrated cloud-only stubs rather than downloaded local bytes. | Enable Hazel 6's cloud-only placeholder policy on that folder or wait for local download before OCR inspection. |
| **7. AI agent invented 22 inconsistent folders** | Allowed live file edits on Turn 1 without locking bucket names in the prompt. | Enforce `--approval-mode plan` (Gemini) or Turn-1 dry-run manifest (Cowork) capped at 6 fixed bucket names. |

### 6-Point Safe File System Cleanup Pre-Flight Checklist

✓

**1. Verify Recent Snapshot:** Confirm Time Machine, Windows File History, or cloud backup is up to date before bulk moves.

✓

**2. Lock Scope & Exclusions:** Target only `Downloads/` or `Desktop/` and prune `.git`, `node_modules`, `.DS_Store`, and `*.crdownload`.

✓

**3. Run Read-Only Dry Run First:** Inspect `manifest.csv`, `./rmlint.sh -n`, `-WhatIf`, or Gemini `plan` output line by line.

✓

**4. Verify SHA-256 & Receipt Names:** Confirm duplicate clusters keep canonical originals and PDFs follow `YYYY-MM-DD_Vendor_Category.pdf`.

✓

**5. Stage Discards in `_quarantine_30d/`:** Never delete directly inside scripts; park clones and old installers for a 30-day review window.

✓

**6. Keep Rollback CSV Intact:** Store `rollback_manifest.csv` alongside staged files until Day-30 final purge clears safely.

#### Final Takeaway: Calm Automation Never Makes Irreversible Guesses

Digital clutter builds up because deleting feels risky. When dry-run manifests, SHA-256 checksums, VLM/OCR naming, and a 30-day quarantine bay back every sweep, tidying thousands of files across Mac and Windows becomes effortless, safe, and repeatable.

---

## Edition Note & Attribution

This 12-page handbook, its topic structure, and its illustrations were generated with AI under human editorial direction and print-layout QA. Verify commands, pricing tiers, and security settings against official vendor documentation before production use.

- AI & Editorial Disclosure: https://twelve-pages.com/editorial
- Terms & Licensing: https://twelve-pages.com/terms
- Privacy & Cookie Notice: https://twelve-pages.com/privacy
