Add performance measurements, trash test and documentation

README.md

@@ -8,7 +8,63 @@ runs over SSH.
 
 ## Status
 
-Under active development — see [ROADMAP.md](ROADMAP.md) for what works today.
+Milestones 0.1–0.8 are implemented; 0.9 (hardening) is in progress. See
+[ROADMAP.md](ROADMAP.md) for detail and [PERFORMANCE.md](PERFORMANCE.md) for
+measured numbers.
+
+## What it does
+
+* **Live treemap.** A squarified, space-filling treemap fills the terminal
+  and grows while the scan runs. Directories show nested previews of their
+  contents; colours are file categories (video, archives, disk images, code,
+  …). Items too small to draw collapse into a "N smaller items" block until
+  you zoom in.
+* **Spatial navigation.** Arrow keys move to the block that is actually to
+  the left/right/above/below. Enter inspects, Space zooms in, Backspace zooms
+  out, Home returns to the root. The selection survives rescans, resizes and
+  filtering.
+* **Resizes properly.** Every resize recomputes the layout for the new
+  geometry (it never stretches the old one); large terminals get a side
+  panel, small ones a compact layout, tiny ones a polite message.
+* **Search and filter** with a small query language — the treemap shows only
+  matching data:
+  `ubuntu` · `*.iso` · `size > 5GB` · `ext IN (iso,qcow2,vmdk)` ·
+  `age > 365d` · `path contains cache AND NOT type = dir` · `owner = andy`
+* **Investigation views** (Tab): directory list, file types, top lists
+  (largest files/dirs, oldest/newest large files, most entries, sparse and
+  hard-linked files), scan information with every error, duplicates.
+* **Honest numbers.** Allocated vs logical size, hard links counted once,
+  sparse files flagged, permission errors and skipped areas always shown;
+  incomplete totals are labelled as such.
+* **Snapshots**: save a scan, reopen it instantly, compare two — the treemap
+  colours growth and shrinkage.
+* **Safe with hostile filenames**: control characters and escape sequences
+  in names are displayed escaped and never reach the terminal.
+
+## Keys
+
+| Key | Action |
+|---|---|
+| ↑ ↓ ← → / hjkl | move spatially through the map |
+| Enter | item information |
+| Space / → | zoom into directory |
+| Backspace / ← | zoom out |
+| Home | scan root |
+| / | search / filter (Esc clears) |
+| Tab, Shift+Tab, 1–7 | switch views |
+| x, g, e | file types, top lists, scan info & errors |
+| D | find duplicates |
+| a | toggle allocated / logical size |
+| c, o | copy path, reveal in file manager |
+| d | move to trash (asks; disabled with `--read-only`) |
+| s, r | save snapshot, rescan |
+| T | cycle theme |
+| ? | help |
+| Ctrl+C | cancel scan, then quit |
+| q | quit |
+
+Mouse: click selects, double-click zooms, right-click inspects, wheel zooms
+the map or scrolls lists. Everything works without a mouse (`--no-mouse`).
 
 ## Install
 
@@ -72,13 +128,30 @@ Optional JSON file at `$XDG_CONFIG_HOME/mapsize/config.json`
 }
 ```
 
+### Colour
+
+Colour support is auto-detected; `--color truecolor|256|16|none` overrides
+it (handy over SSH, where `COLORTERM` is often not forwarded). Themes:
+`default`, `dark`, `high-contrast`, `mono` (`--theme`, or `T` to cycle).
+`NO_COLOR` is respected. On the Linux console, or with `MAPSIZE_ASCII=1`,
+box drawing falls back to ASCII.
+
 ### Read-only mode
 
 `--read-only` disables every modifying action and shows `READ ONLY` in the
-status bar. It does not make mapsize a forensic acquisition tool: scanning
+header. (Saving a snapshot file is still allowed; it writes only where you
+tell it to.) It does not make mapsize a forensic acquisition tool: scanning
 uses ordinary filesystem APIs, and duplicate detection reads file content
 (which may update access times).
 
+### Deletion
+
+`d` moves the selected item to the system trash (freedesktop.org trash on
+Linux, `~/.Trash` on macOS, the Recycle Bin on Windows) after confirmation,
+using native file operations — never a shell. Permanent deletion is not
+offered. Trash is unavailable while scanning, for snapshots, and in
+read-only mode.
+
 ## Documentation
 
 * [ARCHITECTURE.md](ARCHITECTURE.md) — design and invariants