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 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: the Mac app Settings screen lists discovered volumes. If OneDrive or a thumb drive / portable SSD is missing from that list, use Add OneDrive folder or Add portable drive. Adding a folder shows the full path and does not start a scan. A drive that is still missing stays not present or not configured. That is not a successful validation. Storage and Activity still wait on Sprint 12. Files reads the catalog the scan already wrote. 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.

In this build: Settings → Review path to approve shows the full path, then Enable scan for this path. Discovery and adding a folder do not enable scan. Review path to approve shows that root’s full path on its card, then Enable scan for this path keeps scan on for that folder. Discover does not turn it back off. ~/Library/CloudStorage/OneDrive-Personal and the home OneDrive folder are one card when they are the same drive. Personal and Business stay separate. Turn scan off leaves the card and clears approval. Edit path points the card at a different folder and turns scan off until you enable the new path. Remove takes the card off Settings and turns scan off. It does not delete the folder. Discover can list a drive that is still on the Mac again, still not approved. A missing OneDrive stays not configured. $HOME is not added for you. System-internal paths stay refused.

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.

In this build: Start scan of approved roots runs off the main thread. Settings first says Counting files… while it counts the approved roots. That count does not keep paths or write sizes. Then it says X files of Y scanned and shows a progress bar. The bar is not a guess: it appears only after Y is known. When the walk returns, it says Scan finished and X of Y. A partial return says some roots were incomplete and still leaves Discover, Add, Start, and Review clickable. Button labels stay dark on the light background. Each root shows its own result: in progress, finished, skipped, not present, or not configured. A missing or unconfigured iCloud Drive or OneDrive stays not present or not configured. It is not marked finished. The scan does not keep every path, and it does not load the whole catalog into memory. Sizes are written in batches of 2000. Cancel stops the walk. Settings shows the run log path. On a new install that file is ~/Library/Application Support/Burrow/run.log, beside the catalog. It records the scan’s start, roots, phases, counts, and errors. It does not list every file. Files shows that catalog. Storage and Activity do not yet. 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.

In this build: Files is a three-pane browser of approved roots. Services are on the left (internal storage, iCloud Drive, OneDrive, portable). The folder tree is beside them. Click a folder to drill in. The panel on the right lists the files in that folder from the catalog: name, then logical size, allocated size, and modified date, plus cloud state when the catalog has it. The name is ink on the light row, so it stays readable in dark mode. A folder in the catalog is in the tree, not a nameless file row. A folder with no cataloged children says so. The view does not scan the Mac and does not invent files. It refuses a path outside the approved root. It cannot delete, move, archive, or back up files. Hash and duplicate columns wait for 0.2. Search and filters are not this pane.

Not in this build as a live catalog on the website. Storage and Activity still wait on 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.