superme

name

superme

description

Use when the user asks what they need to do today, wants their daily briefing, mentions superme, asks about deadlines/documents/threads they are tracking, or says anything that should be remembered ("remind me", "I need to", "X is due", "I'm waiting on Y", "I'll be away"). Maintains the ~/Desktop/SUPERME personal operations folder — the daily cycle, the personal database, todos, threads, and away mode.

superme

A personal operations folder, maintained by you on the user's behalf. The folder is the product; this skill keeps it true.

Repo: ~/Desktop/github_dev/superme (public, code only) Data: ~/Desktop/SUPERME (local only, never gets a git remote)

Run everything through the CLI. Never hand-write the generated files.

superme today                 regenerate every view — markdown, dashboard and audit
superme dashboard [--open]    draw DASHBOARD.html: the whole folder, seen at once
superme audit [--fix]         is the folder still self-contained and tidy?
superme workspace             file projects by lifecycle; pull docs + mail into each folder
superme people                give each person a folder — who owes whom + their mail
superme draft <todo-id>       write an email draft into Mail — you click Send
superme sign <file.pdf>       sign a PDF with the FNMT cert (--selftest to prove it)
superme voice                 learn the email style from pre-2026 sent mail
superme close <id>            mark a todo or thread done (never deletes)
superme brief                 write the re-entry briefing (RE-ENTRY.md)
superme scan [--quick]        map the machine, propose what to track
superme promote               file scanned documents into db/documents/<cat>/
superme vault                 place each document's file beside its .md record
superme fetch [NAME]          go find a referenced file — local, Chrome, Mail
superme capture -f payload    apply a conversation capture
superme status                module health
superme doctor                environment and permissions
superme grant-fda             open the Full Disk Access settings pane
superme index                 rebuild db/_index
superme away --until DATE     narrow autonomy while away  (--clear to return)
superme test                  run the suite

Permissions this depends on

superme needs two macOS permissions on the terminal, both checked by superme doctor:

• Automation — to drive Mail, Calendar, Reminders, and open a browser.
• Full Disk Access — required, so superme can read the on-disk stores and browser profile to collect information and fill forms. If doctor reports it FAIL, run superme grant-fda, add the terminal, and restart it.

Credentials are never read from a file. Forms are filled by driving the real Chrome through Chrome MCP, where Apple Passwords autofill and existing logins already live. superme's own service tokens go in the login keychain (smlib.keychain_set/get). It does not extract Apple Passwords items.

bin/superme is at ~/Desktop/github_dev/superme/bin/superme. Every command takes --dry-run; use it whenever you are unsure.

The three rules

1. Nothing addressed to a human is sent automatically. Drafts, replies and messages wait for the user. This is structural — smlib.NEVER_AUTO blocks it even if a whitelist rule tries to allow it. Do not work around it.
2. Generated files are generated. TODAY.md, ACTION_REQUIRED.md, WAITING.md, README.md, PROJECTS.md, */_WORKSPACE.md all carry a banner and are overwritten. Changes belong in db/ or active/ (a project's STATUS.md and todo-*.md are hand-editable; the _-prefixed files are not).
3. Propose, then apply. scan writes a proposal, never the database. Promotion into db/ happens through capture after review.

The daily cycle

When the user asks what needs doing, or opens the day:

1. superme status — if a module is DEGRADED, say so in one line before anything else.
2. superme scan --quick if the last scan is older than a day.
3. superme today — this rewrites every view, redraws DASHBOARD.html and re-runs the audit. If any score drops below 5, say which and why in one line.
4. Read ~/Desktop/SUPERME/TODAY.md.
5. Report: what is overdue, what is hard-deadlined within 7 days, what is waiting on someone else and how long. Lead with the YOU lane — those are the only things that cannot proceed without them.
6. Anything learned during the conversation goes back in via superme capture.

Do not re-derive state by reading db/ file by file when TODAY.md already answers the question. Read the generated file first.

Show the shape, not only the list

A ranked list answers "what first". It cannot answer "how bunched", "how long has this one been sitting", or "what is about to lapse" — those are facts about shape, and shape does not survive being written as a sorted list. So the same records are also drawn:

Surface	What it shows
DASHBOARD.html	everything at once — KPIs, deadline density, a runway bar per item, the three lanes, wait ages, expiries, momentum, projects, health
TODAY.md	a 14-day strip above the list: where the deadlines actually fall
WAITING.md	each wait as a bar against the longest wait on the page
DOCUMENTS.md	expiry runway; says "nothing live expires within a year" out loud rather than going quiet
PROJECTS.md	open / awaiting / finished as bars, so a portfolio drifting to all-awaiting is visible

The dashboard is one self-contained file — no CDN, no font, no network — because it gets opened on a laptop that may have none. It follows the system theme and can be flipped. It renders from the same smlib.rank_todos the markdown uses: if the page and TODAY.md ever disagree, the page is the one that is wrong.

Momentum is the one panel that is not a photograph of right now. It draws closures per week from the ledger and from each record's closed: date, so it answers the question the rest of the folder cannot: is the list getting shorter? It only fills in when work is closed through superme close <id> — marking a record done by hand leaves no dated trace and no history to draw.

An empty panel says so out loud. No expiries, no closures, nothing waiting — each of those is stated, not omitted. A section that quietly disappears cannot be told apart from a feature that does not exist, and "nothing is expiring" is an answer while silence is not.

Point the user at DASHBOARD.html when they want the whole picture; read TODAY.md when they asked a specific question.

The three lanes

Lane	Meaning
YOU	Only the user can finish it — sign, attend, decide, appear, click send
ME	You can do it — draft, file, rename, verify, prepare, chase
WAITING	Blocked on another human; carries waiting_on and waiting_since

A lane says who finishes, not who does all of it

"Send X the Y email" is not a YOU task with nothing you can do. Writing it is yours; only the click is theirs. The lane has one field and collapses that distinction, so correspondence used to sit in YOU under "nothing moves until you do it" — false, and it left the user composing letters superme could have written.

So every todo also carries a draft state, derived not stored:

State	Means	Shown as
needed	correspondence with no composed body — your move	✍ superme can draft this
ready	draft_body: is on the record	✉ draft ready — review and send
None	not correspondence (a form, an appointment, a commit)	nothing

superme draft --pending          what superme could write but has not
superme draft <id> --adopt FILE  bind an already-written draft to a todo
superme draft <id>               put it in Apple Mail — never sends

When you see needed, compose it: write the email and put it on the record as draft_body: (plus email_to:, email_subject:) via superme capture. Respect the learned voice in .superme/voice.md, and note the per-recipient word ceiling that superme draft enforces — work mail runs far shorter than personal. Then the state flips to ready and the only step left is the one you are never allowed to take.

The audit reports every needed item still in the YOU lane as undrafted_correspondence. It never re-lanes anything: the detection is a guess from a verb ("decide, then tell Ana" is a decision with a letter attached), and a tool that silently moved work between lanes would be taking the decision too.

Written drafts are read, not just copied

~/Desktop/email/_drafts_text/*.txt hold finished emails in a fixed shape — TO:/SUBJECT: headers, working notes, a --- line, then the message. superme mirrors any draft a record references and parses it onto the record, so a task whose email is already written stops looking like one nobody has started.

Everything above --- is working notes and must never reach a body. The parser refuses outright — no recipient, no separator, notes below the line, unfamiliar shape — rather than guess, because the cost of guessing is a sent message that cannot be recalled.

Binding is only ever by explicit reference. --pending suggests likely files by shared words; confirming is --adopt. Filename resemblance is enough to put two things side by side and nowhere near enough to attach a finished letter to an obligation.

hard: true means an external or legal deadline, not a self-imposed one. Only hard deadlines escalate. Be honest when setting it — inflating it destroys the signal that makes the away case work.

One folder per project, filed by lifecycle

active/ holds live work; db/ holds settled records. A live todo is never in db/ — a todo is not "done", so it has no place in the archive. That is the whole layout:

active/
  open/<project>/       🟢 something is on the user's plate
  awaiting/<project>/   ⏳ open, but every task is WAITING on someone else
db/
  archive/<project>/    ✅ finished projects graduate here
  documents/ people/ identity/    reference records (never todos)
PROJECTS.md             every project grouped Open / Awaiting / Finished

Each <project>/ folder is the whole project in one place:

active/open/residence-permit/
  STATUS.md                 the narrative (hand-editable)
  todo-*.md                 the tasks
  _files/                   copies of the project's documents
  _mail/                    drafts + superme-composed READY-TO-SEND emails
                            (grouped into year/ then month/ once past 150)
  _source/STATUS.md         dated snapshot of an external narrative, if any
  evidence/                 the paper trail
  _WORKSPACE.md             generated index: tasks · documents · mail · lifecycle

These subfolders are created by the first thing written into them, never up front — empty scaffolding is fifty directories whose only content is the suggestion that something is missing. superme tidy prunes any that empty out.

superme workspace computes each project's lifecycle and moves the whole folder into the right bucket — open → awaiting → db/archive is automatic, never hand-set. Flip a task's lane or close it and the project re-files on the next run. It also mirrors the project's real documents and emails in from the matching ~/Desktop/email/ACTIVE|DONE/NN_<slug>/ (bound by shared distinctive slug tokens: grant-invoice → 04_grant_invoice, not 08_grant_closure). Originals stay put; superme keeps copies, idempotent by size. The _ prefix keeps the mirror out of the entity scan.

superme today re-buckets and rewrites the indexes cheaply; superme workspace also does the heavier document/mail copy.

Projects arrive on their own. A source folder carrying a STATUS.md that no existing project claims is adopted — it becomes a project, filed by the bucket it was found in, and given a thread record of its own that links (never copies) the live narrative. Without this the project list could only ever shrink: it was built from records superme already held, so nine finished projects sat in DONE/ unseen for the life of the tool. If a project you expect is absent, check that its folder has a STATUS.md and that its bucket name is one smlib.SOURCE_CLOSED_BUCKETS knows.

The folder has to stand on its own

superme audit asks one question — can this folder answer without the laptop around it? — and reports three 1-5 scores in AUDIT.md:

Score	Measures	Reaches 5 when
Self-contained	every path a record names resolves inside the folder, and every view is still derived from the current records	no reference points at something only the machine has, and nothing is stale
Organised	every record once, in its canonical place	nothing misfiled, no empty directory, no flat pile
Visible	the charts were actually written	every visual surface is present and drawn

Staleness counts as a break in self-containment. A view written before the last three edits reads perfectly and quietly omits them — the only failure mode here that looks exactly like success. If stale_view appears, the fix is always superme today.

It is computed from counts, not judgement, so two runs a week apart are comparable. superme today runs it as part of the daily rewrite — a self-containment check nobody remembers to run is not a check.

Findings are graded: 🔴 break means information is gone, 🟠 drift means it is here but the record is out of date, · noise means untidy. --fix only repoints references whose target is unambiguous, and only in instruction fields (next_action:) — never in body prose, where the same path may be a statement about the machine ("a duplicate of X") that a rewrite would silently falsify.

When a project's narrative lives outside (a source folder's STATUS.md), it is both linked and snapshotted to <project>/_source/STATUS.md with the date it was taken. Linking alone left nine archived projects whose folders held a pointer and nothing else. A labelled copy does not mislead; an empty folder does.

Nothing is missing, only not yet found

A record whose file: no longer resolves is not a number to report — see superme-sources for the channels. superme vault runs the fast ones itself; superme fetch runs all of them and leaves what it cannot resolve in .superme/fetch/needed.json, with the URL to open when Chrome remembers one.

One folder per person

superme people gives each person a folder under db/people/<slug>/ that answers "do I owe this person anything?" at a glance:

db/people/dana-vega/
  person.md      the record (hand-editable)
  _PERSON.md     generated: who · projects · they-owe-you · you-owe-them · mail
  _mail/         copies of their drafts + composed READY-TO-SEND emails
PEOPLE.md        root index: who has something open, who is quiet, who is retired

They owe you = open todos whose waiting_on names them. You owe them = open todos whose email_to is their address (with the composed email waiting in _mail/ when there is one). Mail is bound by the person's own name tokens (whole-word) in a draft filename — dana binds Dana's drafts, not dana-scan-2026. A merged duplicate person (marked status: superseded) gets no folder and is footnoted under "Merged / retired". superme today refreshes the _PERSON.md/PEOPLE.md views; superme people does the mail copy.

Existing folders these workspaces draw from

superme copies project artifacts out of these, but never moves or rewrites them:

Folder	What it is
~/Desktop/email/	Per-project source — ACTIVE/*/, DONE/*/, _drafts_text/
a permits folder	Residence permit documents and evidence
~/Desktop/whatsapp/CLAUDE.md	Hard-won WhatsApp-via-Chrome playbook — read it before touching WhatsApp
a career-notes repo	Profile, opportunities, strategy
~/Desktop/cv_design/	cv.html → PDF pipeline

Away mode

superme away --until 2026-09-15 narrows autonomy — it does not widen it. While away, only observation and reminder-creation are permitted; commits and calendar accepts are withheld. Items accumulate for a ranked re-entry briefing. The reasoning: the user is not there to catch a mistake, so a month of accumulated queue costs less than a month of unattended wrong actions.

Related skills

superme-scan · superme-capture · superme-db · superme-todo · superme-docs · superme-sources · superme-cv