chore: Claude/agent guidance and workspace files

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

files/anki-README.md

@@ -0,0 +1,136 @@
+# ~/Anki — spaced-repetition source tree
+
+This directory is a **source/staging area** for Anki cards, not Anki's
+collection. The actual collection (SQLite DB, media, scheduling state) lives
+at `~/.local/share/Anki2/<profile>/collection.anki2` and is managed by Anki
+itself. Files here are plain-text card sources you author/edit/diff, then
+import into Anki when you want to sync them up.
+
+## Layout
+
+```
+~/Anki/
+├── README.md       this file (symlinked from /etc/nixos/files/anki-README.md)
+├── dev/
+│   └── cards.csv   developer jargon + concepts (GitHub PM lingo, TLV, …)
+├── french/
+│   └── cards.csv   French vocab + phrases, tagged for export by topic
+├── protocols/
+│   └── cards.csv   decentralized protocols (BTC, Lightning, Nostr — BIPs, NIPs, …)
+├── exports/        .apkg files generated to share with others
+└── sources/        raw clippings/articles you're mining cards from (scratch)
+```
+
+Add more top-level deck dirs as new topics show up (`mkdir ~/Anki/<topic> &&
+cp ~/Anki/dev/cards.csv ~/Anki/<topic>/cards.csv` to clone the header).
+
+## CSV format
+
+Each `cards.csv` starts with Anki import directives so File → Import in Anki
+needs zero clicks to configure:
+
+```
+#separator:Comma
+#html:false
+#deck:Dev
+#notetype:Basic
+#tags column:3
+```
+
+Then one row per card: `Front,Back,Tags` — tags are space-separated within
+the column. Quote fields that contain commas.
+
+Example rows:
+
+```
+What does "cutting a release" mean?,Creating a new versioned release \
+branch/tag from main — the point at which the codebase is frozen for that \
+version.,jargon github-pm
+TLV (in protocol design),"Type-Length-Value: a framing scheme where each \
+record carries its type tag, byte length, then payload. Self-describing, \
+extensible, used in BER/DER, Lightning Network messages, etc.",concepts \
+networking
+```
+
+## Adding cards via Claude
+
+Ask Claude in natural language:
+
+> Claude, add a card explaining "dogfooding" to dev/cards.csv
+
+Claude appends a properly-escaped row with sensible tags. You review the
+diff, commit if you version this dir, then re-import into Anki when ready.
+
+## Importing into Anki
+
+1. Open Anki.
+2. **File → Import** → pick `~/Anki/<topic>/cards.csv`.
+3. The header directives drive the import — confirm the deck name and
+   notetype shown in the dialog, then click Import.
+4. Anki uses the **first field** (Front) as the duplicate key, so re-importing
+   the same CSV after appending new rows updates existing notes and adds new
+   ones — no duplicates.
+
+## Exporting a tag-filtered subset (e.g. French → farming, for an employee)
+
+Anki's main File → Export dialog targets whole decks, not tags. To slice by
+tag:
+
+1. **Tools → Create Filtered Deck** (Ctrl+Alt+N).
+2. Search: `deck:French tag:farming` (combine tags with `OR` /`-tag:` as
+   needed).
+3. Anki creates a temporary deck containing just those cards. Filtered decks
+   are references, not copies — originals are untouched.
+4. **File → Export** → pick the filtered deck → **Anki Deck Package
+   (.apkg)** → **uncheck "Include scheduling information"** so the recipient
+   starts fresh.
+5. Save to `~/Anki/exports/french-farming.apkg`. Hand to the recipient; they
+   double-click or File → Import into their own Anki.
+6. Delete the filtered deck after (Decks page → cog → Delete). Originals
+   stay put.
+
+## Decks vs tags — which to use
+
+- **Decks** are the hierarchy you see on Anki's home screen. Cards live in
+  exactly one deck. Use a deck for **a domain you study as a unit** (Dev,
+  French).
+- **Tags** are orthogonal labels. A card can have many. Use tags for
+  **slices within a deck** you'll want to filter on: `farming`, `livestock`,
+  `gardening`, `jargon`, `concepts`, `networking`, `github-pm`.
+
+Splitting `french/farming/`, `french/livestock/` into separate folders would
+duplicate this structure outside Anki and lose the cross-cutting filter
+power — keep one CSV per language/topic and let tags do the slicing.
+
+## Suggested tag vocabulary
+
+- **dev**: `jargon`, `concepts`, `github-pm`, `networking`, `nix`, `git`,
+  `security` — add as you go.
+- **french**: `general`, `phrases`, `farming`, `livestock`, `gardening`,
+  `kitchen`, `weather` — pick one per row at minimum, add specifics as
+  needed.
+- **protocols**: tag every card with **at least one ecosystem tag** plus
+  optionally a **spec tag** and a **topic tag**:
+  - ecosystem: `bitcoin`, `lightning`, `nostr` (a card on a Lightning BOLT
+    that touches both Bitcoin and LN can carry both)
+  - spec: `bip-NN` (e.g. `bip-32`, `bip-39`, `bip-340`), `nip-NN` (e.g.
+    `nip-01`, `nip-04`, `nip-46`), `bolt-NN` for Lightning BOLTs
+  - topic: `cryptography`, `consensus`, `mempool`, `script`, `signing`,
+    `relay`, `keys`, `events`, `bunker`
+  - Bitcoin + Nostr overlap a lot (Schnorr/`bip-340`, key derivation, hash
+    functions). Cross-ecosystem cards get both ecosystem tags so they
+    surface from either filter.
+
+Be conservative: every new tag is a slice you commit to maintaining. Reuse
+existing ones unless a new dimension genuinely needs splitting.
+
+## Versioning this dir (optional)
+
+`~/Anki/` is not under version control by default. If you want history:
+
+```
+cd ~/Anki && git init && echo 'exports/*.apkg' >> .gitignore
+```
+
+The CSV headers + plain-text rows diff cleanly. `.apkg` exports are
+artifacts and don't belong in git.