Having your cards written

The prompt the app hands you (iOS)

Settings → “How to use” on iOS builds a prompt to hand to an AI agent. Type the subject you want to study, copy, and paste it into Claude or ChatGPT.

The prompt does not restate the format — it carries instructions to read the specification (a copy would only be fixable on the app’s release cycle, and would therefore go stale). An agent with write access to GitHub can be asked to commit the cards directly.

The same prompt works every time you want to add a subject.

This screen exists only on iOS. Starting from Mac or Android, hand the agent the specification or this documentation’s card format page.

Everything about the format is public.

Setting up the repository

• Public or private, either is fine (private is the usual choice)
• Cards go inside at least one directory. Where they sit is free; deck: decides the deck
• Put AGENTS.md / CLAUDE.md at the top saying “cards follow this specification”, and the next agent to touch the vault will read the format again (templates work as-is)
• Material you do not want on the device — scanned textbooks, audio — goes in a directory starting with _, such as _references/. It is excluded from sync

Writing good cards

Passing the format and being worth reviewing are different things. Seven guidelines.

• One card asks one thing. If the answer has independent halves, it is two cards. Decide before the card gets an id and a history
• A set you must produce whole is one card whose back is that set. Facts recallable on their own are one card each, with their shared framing on an ask: false card they reference
• Use a reference only when the same text belongs on three or more cards
• The front must be answerable on its own. “Standard deviation” is a topic; “What does standard deviation tell you that the mean does not?” is a question
• Put the source in the note. A fact you cannot trace cannot be checked
• Write the content in the language you study in. Only the keys and markers are English
• Changing what a card asks is a new card: a new id, and the old file deleted by a person

Let the checker fail, and have it fixed

A vault can be checked mechanically (lint, rules in the card format). One error exits 1, so the “agent writes → lint fails → agent fixes” loop runs inside CI without ever opening the app.

This is where cards being text pays off directly: with a binary card format, nothing in CI can look inside.

Fixing what you notice mid-review

When an explanation looks wrong while you are reviewing, send it off right there.

1. Press Copy on the review screen or the card screen (what you get is the card’s ID, nothing else)
2. Paste it into an AI agent sitting next to you in Split View on iPad or Mac
3. The agent opens the same repository, fixes the card with that id, and opens a PR
4. Read the fixed text in the Changes tab and merge if it is right
5. It comes down on your next sync

Why the ID and not the text. The agent can read the same repository, so naming the card is enough — it fetches the text itself. Pasting the whole card makes it ambiguous which copy is newer, and you end up having the stale one edited.

Sending several at once

• “Copy weak cards for AI” on the Browse tab: up to ten cards, most-forgotten first, with their text, source paths and ids (iOS / Mac)
• “Share this session with AI” right after finishing a session: just the cards you stumbled on today (iOS)
• Every sync writes data/insights.json (your weak cards) to the repository, so an agent can see what you are struggling with just by opening the repo — no clipboard needed

Only the bulk copies carry the card text (fixing several at once needs it). References are not expanded: the referenced card is attached as a separate block, because that is the file to edit. Merged into one card, an agent would “helpfully” copy the definition into the question card and undo the whole point.