| 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
superme scan
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:
- 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.
- Documents that prove identity or a legal right.
- 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.
- 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.
