superme-scan

name	superme-scan
description	Use when building or refreshing the superme personal database from the machine — first-time setup, "rebuild my database", "what's on my laptop", "find my documents", or when the last scan is stale. Walks the filesystem, git repos, Mail, Calendar and Reminders, and proposes what to track.

superme-scan

Maps the machine and writes a proposal. It never writes the database.

superme scan --quick     # skip slow mailbox enumeration (~2s)
superme scan             # full, includes per-account mailbox counts

Outputs:

• ~/Desktop/SUPERME/SCAN_REPORT.md — read this
• ~/Desktop/SUPERME/.superme/scan/proposal.json — the structured form

What it finds

Area	Detail
Documents	Classified identity · legal · financial · admin · academic. Everything else is counted but not proposed
Duplicates	Fingerprinted by size + first 256 KB. Reports groups, deletes nothing
Repos	Branch, dirty count, unpushed, last commit, linked worktrees, and repos with no commits at all
Not-in-git	Directories under the repo root with no .git — untracked work
Sources	Mail accounts, Calendars, Reminders lists, via AppleScript
Existing systems	Folders that already organise work — a README/CLAUDE.md at the root, or subfolders carrying STATUS.md — detected so they are referenced, not re-derived

Roots scanned by default: ~/Desktop, ~/Downloads, ~/Documents. Downloads matters more than it looks — it is where every mail attachment and every browser download lands, so it is where a document the user just received will be.

Live work and finished work

A curated folder almost always keeps finished projects beside live ones (ACTIVE/ and DONE/, projects/ and archive/). Both are read, and each project is reported with the bucket it came from and a closed flag. The scan report marks finished ones with ✅.

This is worth checking after a scan: if the report shows a system with live projects and no finished ones, and the folder on disk has an archive bucket, the bucket name is not one superme recognises — see SOURCE_CLOSED_BUCKETS in lib/smlib.py.

Pinning a system discovery cannot see

Discovery recognises a folder by its shape: a README.md/CLAUDE.md at the root, or two or more subfolders each carrying a STATUS.md. A folder that is genuinely a working system but has neither — a flat pile of invoices, a build pipeline, a folder nested under a repo root — is invisible to it.

Pin those in <data>/.superme/systems.json:

[
  {"key": "cv", "path": "~/Desktop/cv_design"},
  {"key": "reimbursement", "path": "~/Desktop/reimbursement"}
]

Pinned entries are merged ahead of discovery and de-duplicated by real path, so pinning something discovery would have found is harmless. This file is the right home for personal folder names — it lives in the private data folder, not in the code.

Turning a proposal into the database

The scan proposes; you review it with the user; superme-capture applies. Do not bulk promote every proposed document — a scan of a working Desktop returns hundreds of files and most are noise. Promote what has a deadline, proves something, or is evidence for an open thread.

Priority order when reviewing:

1. Anything with an expiry — certificates, permits, passports. These generate their own deadlines once expires: is set, which is the highest-value field in the whole schema.
2. Documents that prove identity or a legal right.
3. Signed documents where more than one version exists on disk. Same filename + different content is a real hazard, not a tidiness problem — establish which copy is authoritative and record it.
4. Repos with staged work and no commits.

Re-running

Re-runnable and cheap. A second run is a diff — new repos, newly quiet projects, new documents. Run it weekly, or whenever superme status reports the scan stale.

Limits

Bounded at depth 4 and 40,000 files, skipping .git, node_modules, virtualenvs and bundles. Extensions considered are document-like only. If something is missing, it is likely outside the roots — pass --roots explicitly.