Inventory

The inventory phase is a read-only scan. It traverses a directory, hashes every file, and produces a structured manifest. No files are modified, moved, or renamed. This is observation only.

What inventory captures

Every file in the target directory receives a record with the following fields:

Field	Source	Purpose
path	Filesystem	Absolute path at scan time
size	Filesystem	File size in bytes
mtime	Filesystem	Last modification timestamp
ctime	Filesystem	Creation timestamp (where supported)
blake3	Computed	Primary content hash, canonical identifier
sha256	Computed	Secondary hash for cross-tool verification
mime_type	python-magic	Detected MIME type from file content
extension	Filesystem	File extension, lowercased
depth	Computed	Directory depth relative to scan root
sync_state	Platform adapter	iCloud sync status (macOS) or null

BLAKE3 is the canonical identifier. Two files with the same BLAKE3 hash are the same file, regardless of name or location. SHA256 exists for compatibility with external archival tools. See Content Hash as Identity for the rationale.

---

Running a scan

fialr scan ~/Documents

The scan walks the directory tree, computes both hashes for every file, detects MIME types, and writes the results to a job directory.

Output to the terminal includes:

• Total file count
• Total size (human-readable)
• Extension distribution (top extensions by count)
• Exclusion summary (count per exclusion layer)

---

Output

The scan produces a manifest.json inside the job directory:

jobs/2026-03-11_scan_a1b2c3d4/
  manifest.json
  log.json
  report.md

manifest.json contains the full file list with all fields from the table above. log.json records every operation performed during the scan. report.md is a human-readable summary.

---

macOS behavior

On macOS, fialr interacts with iCloud Drive through the platform adapter:

1. Sync pause. Before scanning, fialr pauses iCloud sync using brctl pause com.apple.CloudDocs. This prevents sync activity from modifying files mid-scan.
2. Sync resume. After scanning completes (or if the scan is interrupted), sync is resumed.
3. Evicted file detection. Files that exist only in iCloud (not downloaded locally) are detected by checking st_blocks == 0. By default, these files are skipped to avoid triggering downloads during a read-only scan. They are recorded in the manifest with their sync state, but no hash is computed.
4. Materialization (opt-in). Pass --include-cloud to process evicted files. This triggers iCloud to download each evicted file so it can be hashed and fully inventoried. Use this when you want a complete manifest that includes files stored only in iCloud.

# Default: skip cloud-evicted files
fialr scan ~/Documents

# Materialize and process all files, including iCloud-only
fialr scan ~/Documents --include-cloud

This behavior is handled entirely by the macOS platform adapter. Core modules never reference sys.platform directly.

---

Exclusion system

fialr uses a four-layer exclusion system. Each layer is evaluated in order. A file excluded at any layer is recorded in the manifest with the exclusion reason, but receives no hash computation.

Layer	Source	Examples	Overridable
1. Hardcoded	Built into fialr	.git/, node_modules/, .venv/, __pycache__/, .ssh/, .gnupg/, project roots	No
2. Config directories	fialr.toml [exclusions] directories	Explicit paths to skip	Yes
3. Config patterns	fialr.toml [exclusions] patterns	Glob/regex patterns	Yes
4. XATTR/sentinel	Per-file or per-directory opt-out	com.fialr.exclude XATTR or .fialr-exclude sentinel file	Yes

Nothing is silently skipped. Every excluded file appears in manifest.json with an exclusion_reason field identifying which layer and which rule triggered the exclusion.

To exclude a directory from all future scans, place a .fialr-exclude file in it:

touch ~/Documents/vendor-archives/.fialr-exclude

Or set the XATTR on individual files:

xattr -w com.fialr.exclude true ~/Documents/legacy/old-backup.zip

---

What comes next

The manifest produced by inventory is the input for classification. No files have been modified. The scan is the foundation for every subsequent phase.

For the full command reference, see fialr scan.