superme-capture

name	superme-capture
description	Use when a conversation contains a fact worth keeping — a deadline, a person's role, a document's location or expiry, a new obligation, something the user is waiting on, or a new project. Turns dialogue into superme database entries, threads and folders. Trigger on "remind me", "I need to", "X is due", "I'm waiting on", "I just got", "note that", or whenever a durable fact appears in passing.

superme-capture

The second intake path. superme-scan learns from the machine; this learns from what the user says. Both write the same entities, and both are idempotent — the same deadline mentioned three days running updates one todo, not three.

How to use it

Build a JSON payload, then apply it:

superme capture -f payload.json --dry-run   # always look first
superme capture -f payload.json

Write the payload to the scratchpad, not into the data folder.

Payload shape

{
  "source": "conversation:2026-08-04",
  "entities": [
    {
      "id": "doc-tie-2026",
      "type": "document",
      "title": "TIE — Tarjeta de Identidad de Extranjero",
      "issuer": "Policía Nacional",
      "number": "<NIE>",
      "expires": "2027-01-22",
      "status": "valid",
      "file": "~/Desktop/permits/01_IDENTITY/TIE_2026.pdf",
      "threads": ["permit-renewal-2026"],
      "body": "Prose goes here. Say what is known and, explicitly, what is not."
    }
  ],
  "threads": [
    {"id": "permit-renewal-2026", "title": "Residence permit renewal 2026",
     "status": "open", "deadline": null, "summary": "..."}
  ],
  "todos": [],
  "notes": ["A one-line observation that belongs in the ledger, not the database."]
}

Types: identity person document affiliation project output todo.

Creating a thread creates threads/<id>/STATUS.md and threads/<id>/evidence/. This is how new folders get built from conversation.

Rules

Never invent a value. If the user says a document expires "sometime next year", do not write expires: 2027-01-01. Omit the field and say so in the body: "Expiry not yet recorded — read it off the scan." A fabricated date becomes a fabricated deadline, and the whole system's value rests on its deadlines being real. Frontmatter is for what is known; the body is where uncertainty lives.

Record provenance. If a fact came from conversation rather than from a verified source, say so in the body. captured_from is set automatically.

Merging preserves human edits. On re-capture, superme-managed keys are updated and anything the user added by hand is left alone. An omitted field never erases a known value — to clear one, edit the file.

Dates are YYYY-MM-DD. Anything else fails validation. Resolve "next Tuesday" against today's date before writing it.

Set hard: true only for external or legal deadlines. A self-imposed target is not hard. Inflating this destroys the signal that makes away mode work.

When to capture

Capture when a fact will still matter next week. Do not capture the conversation itself — capture what it established.

Said	Capture
"Dana handles the extranjería paperwork"	person entity, role + thread link
"The cita is on the 20th"	todo, lane YOU, hard: true, deadline
"I sent the form, waiting on Sam"	todo, lane WAITING, waiting_on: Sam, waiting_since
"I'm starting a new paper on X"	project entity + a thread
"The certificate is in my Downloads"	document entity with file:
"I'll be snowboarding in March"	not a capture — run superme away --until

After capturing, run superme today so the generated files reflect it.