User guide

This guide is for a person who wants to use Burrow™ on their Mac. It describes the intended workflow. Features that are specified but not built are labeled Not in this build. This page does not invent screenshots or UI that is not shipped.

Burrow™ is a local-first macOS storage management machine. It inventories files across internal disks, iCloud Drive, OneDrive, and removable volumes so you can answer:

1. What files do I have?
2. Where are they stored?
3. What is duplicated, stale, or suitable for archival?
4. Are important files actually protected by verified backups?

Safety Level 0 is in effect. Burrow™ may discover volumes, read metadata, and (once the scanner ships) catalog approved roots. It must not move, rename, delete, archive, or back up your files.

The public site is documentation only. Inventory runs in the Burrow™ Mac app. A browser on burrow.jasonkoch.io cannot see your disks.

What you can do in this build

• Read product specifications, designs, and this guide on the website.
• Run the Burrow™ Mac app on this computer to discover volumes, approve roots, and inventory. The website has no console.
• Run the local engine and confirm loopback health. See the Admin / operator guide.

How you will use Burrow™

1. Discover volumes and providers

The engine enumerates mounted volumes and detects iCloud Drive and OneDrive roots. Discovery records identity and classification. It does not scan file contents and does not change cloud synchronization.

In this build: volume discovery and provider detection exist in the engine. The Mac app lists discovered volumes. Live catalog totals still wait on owner-approved roots (VLT-38). Duplicate recovery is not available in 0.1. The website does not show inventory.

2. Approve scan roots

You choose which folders the engine may inventory. Nothing is scanned until a root is approved.

Not in this build. Scanner approval is specified in 04 — Inventory and is not shipped.

3. Inventory approved roots

After approval, a read-only scan records paths, sizes, timestamps, and (when hashing is implemented) content hashes in the local SQLite catalog. The catalog is application metadata. Your documents are not modified. Cloud-only placeholders are recorded by metadata; Burrow™ does not download them merely to inventory them.

Not in this build. The inventory UI and file scanner are not shipped. See 04 — Inventory and 08 — UI/UX.

4. Review files and storage

The Mac app Storage view will list roots and open a read-only drill-down for one root: capacity, scan coverage, largest folders, file-type distribution, age, cloud state, and configured role. Incomplete coverage is labeled. This view cannot delete, move, archive, or back up files. Hosted HTTPS cannot read the local catalog.

Size is the logical file length; Allocated is the local disk footprint. A cloud placeholder can look huge logically and occupy almost nothing locally — Burrow™ does not treat that logical size as immediately reclaimable local disk. Protection in this build is Local only, Synced only, or Unknown. Synced is not treated as backed up.

The Mac app Files table lists catalog rows with name, path, logical size, allocated size, modified date, location, cloud state, protection, and recommendation. Search matches name or path. Filters narrow by location, type, size, age, and cloud state. The query stays inside approved roots and refuses a new unapproved path. This view cannot delete, move, archive, or back up files. Hash and duplicate columns wait for 0.2.

Not in this build as a live catalog on the website. Files and Storage catalog views bind in the Mac app (Sprint 12).

5. Find duplicates

Exact-duplicate groups will show every location and the recoverable local bytes, with evidence. Filename, size, and date are never enough to authorize deletion.

Not in this build. Duplicate detection is specified in 05 — Duplicate Detection. The sidebar item is disabled until release 0.2.

6. Backup and archive

Verified backup and archive-copy workflows come after inventory. They remain forbidden at Safety Level 0.

Not in this build. See 07 — Backup and 06 — Archive. Those sidebar items are disabled placeholders.

Safety, stated plainly

Until that change, treat every recommendation as evidence only. Nothing in the UI can start a delete, move, archive, or backup of user files.

Open the product

Operators who need to run the engine, set secrets, or find the catalog should use the Admin / operator guide.