Harden scanner accounting and expose controlled scan reports

README.md

@@ -4,7 +4,7 @@ A fast, concurrent, and feature-rich command-line tool for visualizing disk usag
 
 ## Features
 
-- **Physical by Default**: Prioritizes **Disk Usage** (actual blocks consumed) as the default metric, essential for accurately seeing how much storage is actually gone.
+- **Allocation by Default**: Prioritizes filesystem-reported allocated blocks; sparse files retain their separate apparent size, and hard-link allocation is counted once per scan. Reported allocation is not a promise of bytes freed by deletion on filesystems with shared extents or snapshots.
 - **Fast & Concurrent**: Uses `rayon` to process directories in parallel, making it extremely fast on modern multi-core systems.
 - **Rich Output**: Beautifully formatted tables with colors, distinguishing files and directories.
 - **Apparent Size**: Toggle logical file length with `-a` or `--apparent`.
@@ -98,6 +98,7 @@ sized /path/to/directory
 | `-f`, `--path-full` | Force absolute paths in headers | `sized -f` |
 | `-i`, `--ignore` | Respect .gitignore files | `sized -i` |
 | `-j`, `--threads` | Set number of threads | `sized -j 4` |
+| `-x`, `--one-file-system` | Skip entries on other filesystems | `sized -x /` |
 | `--format` | Output format (text, csv, json) | `sized --format json` |
 | `--save` | Save output to file | `sized --save` |
 | `-c`, `--compare` | Compare total vs. non-ignored files | `sized -i -c` |
@@ -137,6 +138,17 @@ autoload -Uz compinit && compinit
 sized --completions fish > ~/.config/fish/completions/sized.fish
 ```
 
+## Scan status and library API
+
+Scans report missing or unreadable entries on stderr and return a nonzero status
+when incomplete. JSON reports include `complete` so automation can distinguish
+a partial report from a fully scanned tree. Symlinks are not followed.
+
+Library users can call `scan_tree` with `ScanOptions` and a fresh `ScanControl`
+for each request. Clones of the control expose progress and cancellation;
+cancellation is cooperative between filesystem calls. `build_tree` remains as
+a convenience helper, while `scan_tree` retains structured diagnostics.
+
 ## License
 
 This project is licensed under the **GNU General Public License v3.0 (GPL-3.0)**.