# Meme library (bundled defaults)

This directory ships inside the app bundle as the default meme library. The
bundled set is original Clankmaxx pixel art, generated from the app's own
sprite sheet by `site/tools/generate_assets.py` (run it again after the
source art changes; keep `memes.json` in sync when adding files).
The user's own library lives at
`~/Library/Application Support/ClawdBuddy/memes/` and **shadows this one by
filename** — a user file named like a bundled file wins.

## Format

`memes.json` holds one entry per meme; the image/GIF files sit next to it:

```json
{
  "memes": [
    { "file": "this-is-fine.gif", "emotions": ["frustrated"], "weight": 1.0, "name": "This is fine" }
  ]
}
```

- `file` — filename in this folder (required). GIF, PNG, JPEG, WebP; GIFs
  and APNGs play animated.
- `emotions` — one or more tags from the taxonomy below (required).
- `weight` — optional, default 1. Higher = picked more often among memes
  sharing an emotion.
- `name` — optional label, for your own reference.

## Emotion taxonomy

The fixed vocabulary shared by the manifest, the classifier's JSON schema,
and the classification prompt (single source of truth: `MemeEmotion` in
`Sources/ClaudeBuddyCore/Memes/MemeLibrary.swift`):

| tag | the moment it reacts to |
|---|---|
| `amused` | something genuinely funny, witty, or absurd just happened |
| `celebrating` | a win — success, relief, shipped it, fixed it, good news |
| `frustrated` | stuck, annoyed, things breaking, exasperation |
| `confused` | puzzlement, "wait what", things not adding up |
| `skeptical` | doubt, side-eye, "are you sure about that" |
| `offended` | indignation at a perceived slight — "excuse me?", playful offense taken |
| `shocked` | surprise, disbelief, an unexpected twist |
| `sympathetic` | the user is tired, sad, stressed, or needs comfort |
| `smug` | told-you-so, a clever comeback, playful self-satisfaction |

## Notes

- Entries with unknown tags or missing files are skipped (and logged), not
  fatal — the rest of the library still loads.
- Edits are picked up automatically while the app runs; Settings → Buddy →
  "Reload library" forces a rescan.
- The classifier can always decide the moment doesn't call for a meme
  (`"none"`), and never memes on serious or distressing exchanges.
