---
name: digital_file_organizer
description: Tame messy folders and drives: audit a directory tree, find duplicate files by content hash, propose a clean folder structure, and run approval-before-move workflows with archive rules. Use when someone asks to declutter, organize, deduplicate, or archive files, folders, downloads, photos, or a hard drive.
---

# Digital File Organizer

## Purpose
Turn a messy folder tree into a clean, auditable one without ever losing a file. The whole design follows one safety rule: nothing is deleted or moved until a human has reviewed a plan file and the move itself is logged so it can be undone.

## Workflow

### 1. Audit first
Run `bin/organizer.py audit <dir>` to get an inventory: total files, total bytes, per-extension breakdown, largest files, oldest files, and files not touched in over a year. Read the report before deciding anything. A folder with 40 GB of `.mp4` needs a different plan than one with 20,000 loose screenshots.

### 2. Find duplicates safely
Run `bin/organizer.py duplicates <dir>` to find exact duplicate files. It groups files by size first (different sizes can never be equal, so most files are cleared without opening them), skips hardlinks via inode, then hashes with SHA-256 before declaring a match. Same name alone is never treated as a duplicate. Output is a group list, not a deletion. Deletion only happens if the person explicitly asks, and only after reviewing the groups.

### 3. Propose the target structure
Write a target layout in plain words and get it confirmed. The default recipe works well for most personal messes:

```
~/Files/
  Media/
    Photos/YYYY/           # named by capture date where available
    Video/YYYY/
    Audio/
  Documents/
    Finance/YYYY/
    Legal/
    Work/YYYY/
    Reference/
  Software/
    Installers/
    Projects/
  Inbox/                   # staging area: nothing lives here long
  Archive/YYYY/            # anything past its archive rule
```

Adjust to the actual audit. Never invent categories the tree does not contain.

### 4. Plan, review, then apply
Run `bin/organizer.py plan <dir> --layout <json>` to generate a move plan file listing every source and destination path. The person reviews and edits that file. Then run `bin/organizer.py apply <plan>` which moves each file, logs every action to a rollback journal, and leaves the original directory untouched until the move is verified. To undo, `bin/organizer.py rollback <journal>` reverses every move in order.

### 5. Archive rules
Keep a small `archive-rules.yaml` in the tree root. Each rule names a folder, an age or size trigger, and an action. See `references/archive-rules.md` for the full format and for how ISO 15489 thinking (retention schedule, disposition action, authorization) maps to a personal or small-team archive.

## Output Contract
- An audit report (`audit-YYYY-MM-DD.json` and a short plain-language summary).
- A duplicates report grouped by content hash with file counts and byte totals.
- A move plan file, reviewed and edited by the human before anything moves.
- A rollback journal for every applied move.
- An `archive-rules.yaml` for ongoing maintenance.

## Operating Rules
1. Never delete a file unless the person asks after seeing the duplicates report. Same name or same size is not proof of sameness; only SHA-256 matches count.
2. Never move anything without a reviewed plan file and a rollback journal.
3. Back up first when the audit shows irreplaceable content (photos, documents): say so plainly before proceeding.
4. Leave system directories, app config folders, and anything the person did not name alone.
5. Archive rules are decisions about destruction or relocation. Each rule needs a named person authorizing it, per ISO 15489 disposition practice, even at small scale.