# Rhyme Art Vocabulary Library: handoff for a new agent

**What this is.** A finished, public library of **1,386 English vocabulary words**, each with one picture, icon or colour swatch, plus definitions and metadata. Use it to build games, quizzes and lessons for Rhyme Art (learners: adults and teens, many Egyptian and Polish). Nothing is left to generate. Everything below is current as of 8 Oct 2026.

- **Browse it:** https://rhymeart-vocab.pages.dev (all words by theme, search, filters, click for details)
- **Data:** https://rhymeart-vocab.pages.dev/index.json
- **Hosting:** Cloudflare Pages project `rhymeart-vocab` (public, static, free, no read quotas, CORS open so any game can load it)

## The data: `/index.json`

```json
{ "total_words": 1386, "covered": 1386, "missing": [], "assets": {
  "hammer": { "type": "picture", "file": "pictures/hammer.webp",
              "pos": "noun", "tier": "common", "theme": "Tools & Hardware",
              "def": "tool for hitting nails",
              "alt": "a tool with a heavy metal head fixed across a handle",
              "opposite": "", "tags": ["tool"], "alt_spellings": [] },
  "red":    { "type": "swatch", "hex": "#CC2B2B", "pos": "adjective", "...": "..." },
  "plus":   { "type": "icon", "file": "icons/plus.svg", "...": "..." } } }
```

Keys of `assets` are the words (lower case, may contain spaces or hyphens: "light bulb", "hard-working").

| Field | Meaning |
|---|---|
| `type` | `picture` (1,351), `icon` (24), `swatch` (11) |
| `file` | path under the site root. **Spaces become hyphens**: `light bulb` is `pictures/light-bulb.webp` |
| `hex` | swatch only: show a flat colour square, there is no image |
| `pos` | `noun`, `verb` or `adjective` |
| `tier` | real-world frequency: `common` (863), `uncommon` (476), `rare` (47). Not CEFR |
| `theme` | one of 23 themes: Animals, Body & Face, Clothes, Colours, Family & Friends, Food & Drink, Health, The Home, Kitchen & Cooking, Materials, Money & Shopping, Places & Directions, School, Sports & Leisure, Time, Toys, Tools & Hardware, Transport, Weather, Work, The World Around Us, Actions & Movement, Feelings & Descriptions |
| `def`, `alt` | two different short definitions (the primary is written so a learner can guess the word from it; `alt` approaches it from a different angle). Safe to show as hints |
| `opposite` | adjective pairs only (e.g. wild/tame, hard/soft). The pair is always both in the list |
| `tags` | **extra accepted answers** for this picture (hammer's picture also answers "tool"). 43 words have them |
| `alt_spellings` | regional or spelling variants that count as fully correct (donut/doughnut). 10 words |

**Checking a typed answer:** lower-case and trim, then accept the word itself, any `tags` entry and any `alt_spellings` entry.

## The three asset types

- **picture**: WebP, 320 px, transparent background, painted ink-and-paint style. Made to sit on a **cream panel** (`#FAE2AF`, or a lighter `#FFF3D6` tile). Do not put them on busy or dark backgrounds without a light tile behind them.
- **icon**: black SVG pictogram (`fill #000`). The 24 survivors are only shapes, symbols and signs (arrow, plus, minus, equal sign, checkmark, question and exclamation marks, email, dollar, euro, download, repeat, star, snowflake, spiral, zigzag, barcode, cube, hexagon, rectangle, semicircle, square, triangle). Tint with CSS if needed.
- **swatch**: the 11 colour words (orange, gold, silver, black, white, brown, pink, green, red, purple, yellow). Just render the `hex` as a flat square.

Every picture is a single subject on a transparent background. Recurring characters are always unrealistic skin colours on purpose: the **BLUE person** is the default human, the **RED person** is the second person (hug, fight, marry...). Faces are blank unless the word is an emotion. Everything is fully clothed and text-free by design; keep that rule if you add anything.

## Minimal loader (browser JS)

```js
const BASE = 'https://rhymeart-vocab.pages.dev/';
const lib = (await (await fetch(BASE + 'index.json')).json()).assets;
const word = 'hammer', a = lib[word];
const html = a.type === 'swatch'
  ? `<div style="background:${a.hex};width:160px;height:160px"></div>`
  : `<img src="${BASE + a.file}" width="160" height="160" alt="${word}">`;
const isCorrect = typed => [word, ...a.tags, ...a.alt_spellings].includes(typed.trim().toLowerCase());
```

Good building blocks: picture-to-word and word-to-picture matching; multiple choice using other words from the same `theme` and same `pos` as distractors; opposite pairs; "guess from the definition" using `def` then `alt` as a second hint; speed rounds filtered by `tier`.

## Brand look (so new apps match)

Cream page `#FAE2AF`, ink `#160E09`, soft ink `#5C4228`, gilt `#805216`/`#CA9B52`, panel edge `#AA8046`, felt-dark `#241407`/`#180C04`. Fonts: Cormorant Garamond (display) + Libre Baskerville (body), both from Google Fonts. The live browse page (`library\index.html`, deployed at the site root) is the reference implementation of these tokens, including a dark theme.

## How to change or extend it

Everything is in **`C:\Users\Admin\Desktop\CODEX_SANDBOX\vocab-art\`** (the Codex isolation folder; never point Codex at the real project folders).

- `library\` is exactly what is deployed. It is rebuilt from sources by **`py -3.13 assemble_library.py`** (incremental; pictures come from `cut\<word>.png`, icons from `final\icons_black\` and `VOCABULARY\vocabulary-data\icons\`, word data from `VOCABULARY\vocabulary-data\index.json`).
- **Deploy:** set `CLOUDFLARE_ACCOUNT_ID` to the id of the main account ("Dreamsanew@gmail.com's Account", shown by `wrangler whoami`) then `npx wrangler pages deploy library --project-name rhymeart-vocab --branch main --commit-dirty=true` (wrangler is already logged in; no `--force`, that was only needed to create the project). Do not use Workers KV (100k reads/day quota); static Pages has no quota.
- **Source word data** (authoritative): `VOCABULARY\master-wordlist-v8.tsv` (word, pos, tier, opposite, tags, theme), `word-definitions.json` (def, alt, alt_spellings), `vocabulary-data\index.json`. To remove a word: delete its row from `master-wordlist-v7.tsv` and `-v8.tsv`, its entries in `word-definitions.json` (then regenerate the `.txt` mirror), `word-themes.json`, `vocabulary-data\index.json` (also fix `total_words`) and `icon-tool\status.json`; regenerate `vocabulary-by-theme.txt`; if it had an adjective `opposite`, remove the partner too or fix its `opposite`; then re-run `assemble_library.py` and redeploy. (The user only ever removes a word because no good picture for it could be made.)
- **New or redrawn picture:** write a narrow drawing brief (what is drawn, who faces which way, what overlaps, fully clothed, no text), put it in a patch with `make_patch.py word="brief"`, generate with `run_queue.ps1` (Codex image generation, about 20 images per 5-hour window; it retries on its own), slice with `process_new.ps1`, review, then `assemble_library.py` and deploy.
- **Reviewing pictures cheaply:** build contact sheets, give them to the user's ChatGPT chat window with `chatgpt-qa-pack\PROMPT_paste_this_with_each_batch.txt` (describe each picture first, then judge). Cheap sub-agents rubber-stamped errors; this method caught them.

Full history, every decision and the pipeline details are in **`VOCABULARY\PROJECT-STATE.md`** (read it before changing the pipeline).

## Things worth knowing

- The user wants **strict quality**: a picture must make exactly its word unmistakable, not just an example of it. Contrast words are drawn as target plus the opposite crossed out with a red X.
- The user prefers plain-English direction, short answers, and being asked before anything public or irreversible. Everything is already deployed; do not redeploy or delete assets without being asked.
- Data quirks, harmless: some words sit in an odd theme (`fly`, `bubble` are under Animals); `legging` is singular on purpose; a few entries were relabelled so the part of speech matches the definition (peel, smell, wave, tear, vault, light, limp...).
- About 20 words were removed from the original list at the user's request (e.g. lean, mash, perch, stomp, breast, vomit, death, drunk, sober, navel). Never re-add them.