Docs and metadata: per-OS platform notes, package description

ARCHITECTURE.md

@@ -285,17 +285,27 @@ it receives all keys; `Esc` always closes it.
 
 ## OS abstraction
 
-`internal/platform` exposes `ReadDir(path, func(chunk []Entry) error)` and
+`platform` exposes `read_dir(path, chunk, |entries| …)`, `stat`/`lstat`,
-`Meta` structs. Implementations:
+`Meta`, trash, delete, reveal and name lookups. `platform/unix.rs` and
+`platform/windows.rs` hold the implementations:
 
-* `readdir_linux.go`   — `getdents` via `os.File.ReadDir` + `statx` relative to
+* Linux — `readdir` on an `O_DIRECTORY` descriptor + `statx` (via the raw
-  the directory fd (one syscall per entry, gives birth time).
+  system call, so static musl builds work) relative to that descriptor: one
-* `readdir_unix.go`    — darwin/BSD: `fstatat` relative to the directory fd.
+  system call per entry, birth time included; `fstatat` if the kernel lacks
-* `readdir_windows.go` — `os.File.ReadDir` + `Lstat`; reparse points
+  `statx`. Virtual filesystems are detected with `statfs`. freedesktop.org
-  (junctions, symlinks) are never descended by default.
+  trash; `xdg-open` reveals.
-* `fs_*.go`            — virtual-filesystem detection, owner name lookup.
+* macOS, FreeBSD, NetBSD — the same descriptor-relative walk with
+  `fstatat`. macOS moves items to `~/.Trash` (or the volume's `.Trashes`)
+  and reveals with `open -R`; the BSDs have no trash or reveal, so `d` is
+  only offered as a permanent delete when headless.
+* Windows — `std::fs::read_dir` and metadata. Allocated size is reported as
+  unknown and there is no inode identity, so hard links are not
+  deduplicated and symlinks and junctions are never followed. The Recycle
+  Bin (`SHFileOperationW`) and `explorer /select,` reveal; permanent delete
+  is not offered.
 
-No other package switches on `runtime.GOOS`.
+The terminal code has the only other `cfg` blocks (signals and writing the
+restore sequence).
 
 ## Security handling for hostile filenames
 

Cargo.toml

@@ -3,7 +3,7 @@ name = "mapsize"
 version = "1.2.0"
 edition = "2021"
 license = "GPL-3.0-or-later"
-description = "Interactive terminal disk usage analyser (Rust port)"
+description = "Interactive terminal disk usage analyser with a live, navigable treemap"
 
 [dependencies]
 libc = "0.2"

PERFORMANCE.md

@@ -17,7 +17,7 @@ is the median (and best) of 7 runs.
 
 ## Scanner
 
-Dataset: `~/go/pkg/mod`, a large module cache: 388,307 files + 65,518
+Dataset: a source-package cache directory: 388,307 files + 65,518
 directories (458,510 inventory nodes), 10.5 GiB allocated. **Warm cache
 only**: dropping the page cache needs root, so these measure CPU and syscall
 cost, not disk seeks. Cold-cache behaviour on HDDs will be dominated by seek