Code-review follow-ups: httputil, validation caps, a11y

Backend:
- Extract shared internal/httputil (WriteJSON/ErrorJSON/BadRequest/
  ServerError); drop the triple-duplicated helpers in docs, suggestions,
  vocab. ServerError now logs the real error and returns a generic 500 so
  raw DB/internal errors never reach the client.
- vocab capture: validate doc_id ownership (blank -> none, unknown -> 400
  instead of a leaked FK 500); rune-safe clamp word/gloss/definition/
  phonetic/example.
- vocab review(): wrap the read-modify-write in a transaction (TOCTOU).
- /api request-size cap via MaxBytesReader middleware (2 MiB), exempting
  /api/images (own 10 MiB limit).

Frontend:
- StatusBar: drive the checking/voicing/collocating indicators from one
  array; llmDown uses !anyBusy.
- Slide-overs: new useFocusTrap hook (focus-in, Tab trap, focus-restore)
  on GardenPanel + HistoryPanel, both role=dialog/aria-modal/aria-label.
- speech.ts: export stopSpeech(); GardenPanel cancels audio on unmount.

Tests: add doc_id-validation and field-clamp coverage; full suite green.

Claude-Session: https://claude.ai/code/session_016Yr6jELuRc7hyzYLccQKZd

BUILD_PLAN.md

@@ -105,25 +105,25 @@ Multi-session build. **Source of truth for what's done and what's next.** Update
 - [x] **English phonetic (pivot from pinyin)** — for a native-Mandarin English learner the useful pronunciation aid is the English IPA, not pinyin (she reads Chinese fluently). `scripts/build_phonetic.py` extracts ECDICT's `phonetic` column (same source/freq-gate as the gloss); `phonetic.json.gz` embedded + lazily loaded; `Result.Phonetic` resolved via the same de-inflecting candidate walk; shown as `/ˈrɪvər/` in the WordCard. **Full dataset built from ECDICT: 46,579 words (361KB gz)**, in line with the other lexicon assets. The script also has a `--seed` mode (71 curated common words) that ships as a fallback / works without the csv. Curated seed entries (clean IPA) override the ECDICT form where both exist.
 - Verified: go build/vet/test (incl. new `TestExportAll`), tsc, vite build all clean; live smoke vs throwaway binaries — `/word/river|running|serendipity|rivers` all return phonetic (`rivers`→`river` de-inflected), export-all returns a valid 2-entry zip with de-duped CJK filenames + dated name, route doesn't collide with `/{id}`.
 
-### Phase 12 — Collocation coach 🔜 (planned 2026-06-26)
+### Phase 12 — Collocation coach ✅ (2026-06-26)
 **Why:** ESL writers nail grammar but miss *which words go together* — "do a decision" → "make a decision", "strong rain" → "heavy rain". These aren't *wrong*, so the grammar pass won't flag them; they're just non-native. Gentle "natives usually say…" hints are the single highest-leverage upgrade for making her writing sound native. **Build this first** — it's small and de-risks the migration-rebuild pattern Phase 13 also needs.
 
 **Key insight:** the suggestion pipeline is already generic over a `pass` + a `pendingScope` "family" (`runPass` in `internal/suggestions/handlers.go`; grammar + voice already prove it). Collocation drops in as a **third family** and reuses the entire accept/dismiss/re-anchoring/rail/Mandarin-explanation machinery — no new frontend rendering layer.
-- [ ] `internal/llm/collocation.go` — `CollocationInterval` (~25s) + `RunCollocation(...)`, reusing the existing `ParseCheckpoint` parser (same as `RunVoice`). No new parsing.
-- [ ] `internal/llm/prompts.go` — `CollocationMessages(contentText, tone)`. **This prompt is the whole feature**: flag only non-wrong-but-non-native word pairings; explicitly defer real grammar errors to the grammar family; phrase every explanation as warm "natives usually say…" with a Mandarin gloss — never "error/wrong".
-- [ ] `internal/db/models.go` + migration `0005` — new suggestion type `collocation`. ⚠️ The `type` column has a `CHECK(...)` and **SQLite can't `ALTER` a CHECK** → migration must **rebuild** the `suggestions` table (create new w/ extended CHECK, copy rows, drop, rename, recreate `idx_suggestions_doc_id`). Not a one-line ALTER.
-- [ ] `internal/suggestions/handlers.go` — add `collocationScope` (`deleteWhere: "type = 'collocation'"`, `forceType: collocation`), a `CollocationLimit` on `Handler` (+ wire in `New`), register `POST /{id}/collocation`. Mirrors `voice`, ~15 lines. Also extend `normalizeType` to accept the new type.
-- [ ] Frontend: `suggestionMeta.ts` collocation entry (💡 icon + its own warm color so cards read as friendly tips); `client.ts` `collocation(docId)`; a gentle trigger like the existing "Check my voice" pill — **"Make it sound natural 🌸"** — rendering straight into `SuggestionRail`/`SuggestionCard`.
-- [ ] Verify via the millenia UI-test harness (real-browser editor check) + go/tsc/vite clean. **Est. ~½ day** (mostly the new prompt + the table-rebuild migration).
+- [x] `internal/llm/collocation.go` — `CollocationInterval` (25s) + `RunCollocation(...)`, reusing the existing `ParseCheckpoint` parser (same as `RunVoice`). Whole-document (no `TruncateDoc`), tone passed through.
+- [x] `internal/llm/prompts.go` — `CollocationMessages(contentText, tone)` + `collocationSystemPrompt`. The prompt flags only non-wrong-but-non-native word pairings ("do a decision" → "make a decision"), explicitly defers grammar/spelling to the grammar family, and frames every explanation as warm "Natives usually say…" with a Mandarin gloss — never "error/wrong/mistake".
+- [x] `internal/db/models.go` (`SuggestionTypeCollocation`) + migration `0005_collocation_suggestion_type` — **rebuilds** the `suggestions` table (new table w/ extended CHECK, copy rows, drop, rename, recreate `idx_suggestions_doc_id`), since SQLite can't `ALTER` a CHECK. Verified against a copy of the live DB (5 migrations apply cleanly, collocation insert accepted, rows preserved).
+- [x] `internal/suggestions/handlers.go` — `collocationScope` (`deleteWhere: "type = 'collocation'"`, `forceType: collocation`), `CollocationLimit` on `Handler` (+ wired in `New`), `POST /{id}/collocation`, `normalizeType` extended. **Also fixed `grammarScope`** from `type != 'voice'` → `type NOT IN ('voice','collocation')` so a grammar checkpoint no longer wipes the collocation pending flags (the third family must survive like voice does).
+- [x] Frontend: `suggestionMeta.ts` collocation entry (`--color-blossom` warm pink, "Word pairing" label); `client.ts` `collocationDoc(docId)` + `SuggestionType` extended; `index.css` token + `.petal-suggestion-collocation` decoration; `useCheckpoint` `collocating`/`runCollocation` (mirrors `runVoice`, shares the run-token guard); `Toolbar` blossom **"Make it sound natural 🌸"** pill (→ "Reading…"); `StatusBar` breathing blossom dot "Finding natural phrasing…"; threaded through `EditorCore`/`App`. Renders straight into the existing `SuggestionRail`/`SuggestionCard` (Accept applies the native pairing).
+- [x] Verified: go build/vet/test (`TestCollocationPassCoexists` — three families coexist, grammar checkpoint doesn't wipe voice/collocation), tsc, vite build, vitest 51/51 all clean; live smoke vs the binary (dead LLM) → collocation route returns the warm 502 like check/voice.
 
-### Phase 13 — Vocabulary garden (spaced repetition) 🔜 (planned 2026-06-26)
+### Phase 13 — Vocabulary garden (spaced repetition) ✅ (2026-06-26)
 **Why:** the lexicon (`internal/lexicon`) is a stateless static-dataset lookup — **nothing records which words she's looked up.** Capturing them turns passive lookups into real vocabulary, and the review surface ties straight into the "petal garden" delight idea (words become blossoms; the sleeping kitten naps among them). Build **after** Phase 12.
-- [ ] New `internal/vocab` package + migration `0005`/`0006` — `vocab_words` table: `word, gloss, phonetic, example` (sentence captured at lookup for context), `doc_id`, + SM-2-lite scheduling: `due_at, interval_days, ease, reps, lapses, last_reviewed`; `UNIQUE(user_id, word)`.
-- [ ] Auto-capture: when `WordCard` calls `lookupWord`, also fire `POST /api/vocab` (upsert; new word → `due_at = now + 1 day`). Looking words up *is* the data source — zero extra effort from her.
-- [ ] Endpoints: `POST /api/vocab` (record/upsert), `GET /api/vocab/due` (cards due now), `POST /api/vocab/{id}/review` (grade again/good/easy → reschedule), `GET /api/vocab` (full garden), `DELETE /api/vocab/{id}`.
-- [ ] SR scheduler: gentle SM-2-lite / Leitner intervals (1d → 3d → 7d → 16d → 35d). No streak-shaming. This is the only genuinely new logic.
-- [ ] Frontend Garden panel (sibling to `HistoryPanel`/`DocList`): each learned word a blossom, more reps → more bloomed; the `PetalCompanion` kitten naps among them. Flashcard review: captured sentence with the word blanked → recall → EN↔中文 flip → again/good/easy (direction flips for recognition *and* production). A 🤍 "save to garden" on `WordCard` for explicit saves alongside auto-capture.
-- [ ] Verify via the millenia UI-test harness + go/tsc/vite clean. **Est. ~1½–2 days** (new package + table + panel/review UI; reuses existing panel/companion patterns).
+- [x] New `internal/vocab` package + migration `0006_vocab_garden` (0005 was taken by collocation) — `vocab_words` table: `word, gloss, phonetic, example` (sentence captured at lookup), `doc_id` (`ON DELETE SET NULL` so a word outlives its source doc), + SM-2-lite scheduling: `due_at, interval_days, ease, reps, lapses, last_reviewed`; `UNIQUE(user_id, word)` + `idx_vocab_due`.
+- [x] Auto-capture: `EditorCore.openWordLookup` fires `POST /api/vocab` after a successful lookup — **only for words the dictionary actually knows** (a real gloss or definition), so typos/proper-noun lookups don't clutter the garden. Captures the surrounding sentence (`sentenceAround`) + `doc_id`. Idempotent upsert: re-looking-up a word refreshes its gloss/phonetic/example but never resets its schedule.
+- [x] Endpoints (`internal/vocab/handlers.go`): `POST /api/vocab` (upsert; new word → `due_at = datetime('now','+1 day')`), `GET /api/vocab/due` (due now, server-side `datetime('now')` comparison — avoids JS local-vs-UTC parsing bugs), `POST /api/vocab/{id}/review` (grade → reschedule via `datetime('now','+N days')`), `GET /api/vocab` (full garden), `DELETE /api/vocab/{id}`. All owner-scoped.
+- [x] SR scheduler (`internal/vocab/scheduler.go`): gentle SM-2-lite / Leitner ladder (1d → 3d → 7d → 16d → 35d, then geometric by ease). "again" steps back to 1d + counts a lapse + nudges ease down (floored at 1.3) — no harsh wipe; "good" climbs one rung; "easy" climbs a rung and a bit more + raises ease. No streaks to break.
+- [x] Frontend `GardenPanel` (slide-over drawer, sibling to `HistoryPanel`): each word a blossom that opens further with reps (🌱→🌿→🌷→🌸→🌺); a "复习 N 个词 · Review N due" button; per-word detail (phonetic/example/source-doc/remove); footer "🐱💤 N 朵花在花园里" — the sleepy kitten napping among the blossoms. **Flashcard review**: due queue, the example sentence with the word blanked (`blankOut`), flip to reveal word+phonetic+gloss+sentence, again/good/easy grades; **direction alternates** by cursor parity for recognition (EN→中文) *and* production (中文→EN). A 🤍/💚 "save to garden" toggle on `WordCard` alongside the silent auto-capture. Opened from a global 🌷 词汇花园 button in the app header. All copy bilingual zh-first.
+- [x] Verified: go build/vet/test (`scheduler_test.go` — ladder/again-gentle/easy-further; `handlers_test.go` — capture/upsert/due/review/delete lifecycle + empty-word 400 + doc-delete SET NULL), tsc, vite build, vitest 51/51 all clean; live smoke vs the binary (throwaway DB) — full capture→list→due→review→delete flow + 400 on bad grade verified end-to-end.
 
 ### Phase 14 — Companion warmth + bedtime nag + night mode ✅
 **Why:** the companion kitten is the heart of Petal's "built for her" feel. Three additions: (1) a wider, fresher pool of **encouraging phrases** so cheers don't repeat as quickly; (2) when she's still writing **late at night (≥11pm)**, the kitten gently nags her to go to bed; (3) at the same hour the whole app drifts into a calm **night mode** — dark moonlit theme + the falling petals become **falling stars**. Caring, never scolding — the sleepy-cat gag makes "you should be sleeping too 🐱💤" land perfectly. Self-contained, frontend-only.
@@ -142,11 +142,12 @@ Multi-session build. **Source of truth for what's done and what's next.** Update
 ### Next-up (post-v1 product, agreed with user 2026-06-26)
 - [x] **Phase 9 — ESL superpowers**: inline Chinese gloss on hover/select; "say it more naturally" / tone-rewrite. ✅ (see Phase 9 above)
 - [x] **Phase 10 — organization & polish**: cross-doc search, tags, tablet/touch polish, warm LLM-down failure states. ✅ (see Phase 10 above; "tags only" chosen over folders, FTS5 over LIKE)
-- [ ] **Phase 12 — collocation coach**: gentle "natives usually say…" hints for non-native word pairings, as a third suggestion family. 🔜 (see Phase 12 above; build first)
-- [ ] **Phase 13 — vocabulary garden**: spaced-repetition review built from looked-up words, surfaced as a blooming garden. 🔜 (see Phase 13 above)
+- [x] **Phase 12 — collocation coach**: gentle "natives usually say…" hints for non-native word pairings, as a third suggestion family. ✅ (see Phase 12 above)
+- [x] **Phase 13 — vocabulary garden**: spaced-repetition review built from looked-up words, surfaced as a blooming garden. ✅ (see Phase 13 above)
 - [x] **Phase 14 — companion warmth + bedtime nag + night mode**: more encouraging phrases, a gentle "go to bed" nudge after 11pm, and a calm dark theme + falling stars at night. ✅ (see Phase 14 above)
 
 ## Session log
+- 2026-06-26: **Phases 12 + 13 complete** (collocation coach + vocabulary garden — "finish the rest of the build plan except Authentik/Traefik"). **Phase 12**: collocation drops in as a third suggestion family reusing the whole `runPass`/`pendingScope` machinery — `llm/collocation.go` (`RunCollocation`, 25s floor, reuses `ParseCheckpoint`), `collocationSystemPrompt`/`CollocationMessages` (warm "Natives usually say…" + Mandarin gloss, defers grammar elsewhere), migration `0005` **rebuilds** the suggestions table to extend the `type` CHECK (SQLite can't ALTER a CHECK), `collocationScope` + `CollocationLimit` + `POST /{id}/collocation`. **Caught a latent bug**: `grammarScope` was `type != 'voice'` → would wipe collocation flags; fixed to `type NOT IN ('voice','collocation')`. Frontend: `--color-blossom` pink, "Make it sound natural 🌸" toolbar pill, `collocating`/`runCollocation` in `useCheckpoint`, StatusBar dot — all into the existing rail/card. **Phase 13**: new `internal/vocab` package — migration `0006_vocab_garden` (`vocab_words`, SM-2-lite columns, doc_id `ON DELETE SET NULL`, `UNIQUE(user_id,word)`), `scheduler.go` (Leitner ladder 1/3/7/16/35 → geometric; gentle "again", no streak-shaming), `handlers.go` (capture-upsert/list/due/review/delete, all owner-scoped, time math via SQLite `datetime()` so stored values stay canonical-UTC). Auto-capture wired into `EditorCore.openWordLookup` (only dictionary-known words, captures the surrounding sentence + doc_id) + a 🤍/💚 toggle on `WordCard`. `GardenPanel` slide-over: blossom grid (bloom stage by reps), flashcard review (sentence blanked, flip, again/good/easy, direction alternates recognition↔production), sleepy-kitten footer; opened from a global 🌷 header button. Tests: `TestCollocationPassCoexists`, vocab `scheduler_test.go` + `handlers_test.go`, db CHECK test extended. go build/vet/test + tsc + vite + vitest (51/51) all clean; migration verified against a copy of the live DB; live backend smoke (throwaway DB) walked the full vocab lifecycle + the warm-502 collocation path. **Remaining: only the deferred infra bucket** — Authentik auth, Copyleaks Tier-2 (needs a public webhook), Docker/Traefik/deploy — all on hold per the user's "except Authentik/Traefik".
 - 2026-06-26: **Phase 14 complete** (companion warmth + bedtime nag + night mode). `tips.ts`: `ENCOURAGEMENTS` 5→10 lines; new `BEDTIME` array (4 lines, user-supplied English wit + gentle Mandarin leads). `useCompanion.ts`: bedtime branch in the 10s heartbeat (after idle-return + break, before the generic tip); only nudges while actively writing; own `lastBedtime` ref + 30min `BEDTIME_GAP`, respects `PROACTIVE_GAP`; new `'bedtime'` `BubbleTone` lingers ~4s longer. **Night mode** (added same session, user request): `lib/night.ts` centralizes `isBedtime()` + window (now shared by the nag too); `hooks/useNightMode.ts` toggles `petal-night` on `<html>` (60s re-check); `index.css` `html.petal-night` re-points only the palette tokens → whole UI flips via `var()` (no component edits), 600ms dusk fade, print stays white; `PetalFall` gains a `night` prop → chunky cartoon power stars (`makeCartoonStar`, Mario/Kirby-style, 5 candy colors) mixed ~70/30 with small twinkle sparkles, gentle spin + shallow shimmer, effect re-inits on flip; App: `useNightMode()` → `<PetalFall night={night}/>`. tsc + vite clean, companion vitest 45/45; verified with real-browser Playwright screenshots (clock mocked to 23:30) — day petals/cream vs night stars/dark-plum, both pretty. Bedtime window is `BEDTIME_FROM`/`BEDTIME_TO` (local clock) for easy retune.
 - 2026-06-26: **Phase 11 complete** (writer power-ups, batch requested as "do it all"). Seven features: (1) in-doc **Find & Replace** — `SearchHighlight` decoration extension + `FindReplace` bar (Ctrl/Cmd+F, match-case, replace-all back-to-front, DOM scroll that doesn't trigger the selection bubble); (2) **read-aloud** Web Speech util + 🔊 in WordCard & selection bubble; (3) **keyboard/touch access** — Ctrl/Cmd+D caret lookup, Ctrl/Cmd+J rewrite, touch long-press (refactored `handleContextMenu` → shared `openWordLookup(pos)`); (4) **export-all** backup zip (`GET /api/docs/export-all`, `TestExportAll`, sidebar download links); (5) **smart typography** input-rules extension (curly quotes/em-dash/ellipsis, ASCII-only so CJK untouched); (6) **duplicate doc + sidebar sort + outline popover**; (7) **English phonetic** (pivoted from pinyin — IPA is what an English learner needs; pinyin annotates Chinese she already reads) via `scripts/build_phonetic.py` + embedded `phonetic.json.gz` + `Result.Phonetic` + WordCard `/ˈrɪvər/` line — **full 46,579-word dataset built from ECDICT** (the csv re-download worked; `--seed` mode kept as a csv-free fallback). Also folded in this session: the **selection-bubble vs copy/paste fix** (bubble deferred to pointer-up + container `pointer-events:none` so it never sits where you click). go build/vet/test + tsc + vite all clean; live smoke verified word-phonetic (incl. de-inflection) + export-all zip (de-duped CJK names, route priority). Next: deferred bucket (auth/Copyleaks/deploy), still on hold per user.
 - 2026-06-26: **Phase 10 complete** (organization & polish). Scope confirmed with user: all four areas, **tags** (not folders), **FTS5** search. Backend: migration `0004_tags_and_search` (tags + document_tags + `documents_fts` trigram virtual table with sync triggers + back-fill); `db.Tag` model + color constants; `internal/docs/tags.go` (tag CRUD + idempotent assignment + `tagsByDoc` helper, doc list now carries tags); `internal/docs/search.go` (`GET /api/search`, FTS for ≥3 runes + LIKE fallback for 1-2, Go-built sentinel-highlighted rune-aware snippets, owner-scoped). Mounted `/api/tags` + `/api/search` in main.go. Frontend: `useTags`, `TagChip`/`TagPicker`/`SearchBox`, rewritten `DocList`/`DocListItem` (chips + filter bar + search), `api.search`/tag methods + `splitSnippet`/`tagColorVar`; responsive sidebar drawer (hamburger + scrim, <768px) + `pointer:coarse` tap-target/affordance CSS; tap-to-open + outside-pointerdown-close for suggestion cards (touch); `useCheckpoint` `llmDown` flag → warm bilingual "小助手在休息" StatusBar note. Tests: `tags_test.go`, `search_test.go` (incl. update-trigger re-index). All builds/tests/vet/tsc/vite clean; live smoke vs binary on :8061 (dead LLM host) verified search EN/CJK/2-char, full tag lifecycle, check→502 warm path, bundle contents; FTS backfill of pre-existing docs verified. **All v1 phases (0–7) + post-v1 product (8–10) done.** Remaining: deferred bucket (auth/Copyleaks/deploy), on hold per user.

cmd/server/main.go

@@ -20,6 +20,7 @@ import (
 	"gitea.parodia.dev/drwily/petal/internal/llm"
 	"gitea.parodia.dev/drwily/petal/internal/suggestions"
 	"gitea.parodia.dev/drwily/petal/internal/tts"
+	"gitea.parodia.dev/drwily/petal/internal/vocab"
 	"gitea.parodia.dev/drwily/petal/web"
 )
 
@@ -47,6 +48,11 @@ func main() {
 	log.Printf("frontend build version %s", version)
 
 	r.Route("/api", func(api chi.Router) {
+		// Cap request bodies so a runaway or hostile client can't stream an
+		// unbounded payload into a JSON decoder. Image uploads carry their own
+		// (larger) limit inside the images handler, so they're exempt here.
+		api.Use(limitBody(maxAPIBodyBytes, "/api/images"))
+
 		api.Get("/health", func(w http.ResponseWriter, _ *http.Request) {
 			w.Header().Set("Content-Type", "application/json")
 			_, _ = w.Write([]byte(`{"status":"ok"}`))
@@ -83,6 +89,10 @@ func main() {
 		api.Mount("/word", lex.Routes())
 		api.Mount("/gloss", lex.GlossRoutes())
 
+		// Vocabulary garden: words the writer looks up are captured here and
+		// surfaced for gentle spaced-repetition review.
+		api.Mount("/vocab", vocab.New(database).Routes())
+
 		// Editor image uploads, stored on disk and served back by content hash.
 		imgHandler, err := images.New(cfg.ImageDir)
 		if err != nil {
@@ -109,6 +119,32 @@ func main() {
 	}
 }
 
+// maxAPIBodyBytes caps a JSON API request body at 2 MiB. That's far above any
+// real document save (the body is text plus lightweight marks; images upload
+// separately by reference) while still bounding abuse. Exceeding it makes the
+// handler's json.Decode fail, which surfaces as a 400.
+const maxAPIBodyBytes = 2 << 20
+
+// limitBody wraps each request body in an http.MaxBytesReader so handlers can't
+// be made to read an unbounded payload. Paths under any of exemptPrefixes are
+// left alone (e.g. image uploads, which set their own, larger limit).
+func limitBody(max int64, exemptPrefixes ...string) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			for _, p := range exemptPrefixes {
+				if strings.HasPrefix(r.URL.Path, p) {
+					next.ServeHTTP(w, r)
+					return
+				}
+			}
+			if r.Body != nil {
+				r.Body = http.MaxBytesReader(w, r.Body, max)
+			}
+			next.ServeHTTP(w, r)
+		})
+	}
+}
+
 // buildVersion derives a short, stable identifier for the currently embedded
 // frontend by hashing dist/index.html. Vite stamps content-hashed asset names
 // into that file each build, so the digest is a reliable "did the deploy

internal/db/db.go

@@ -260,6 +260,82 @@ END;
 
 INSERT INTO documents_fts (doc_id, title, content_text)
 SELECT id, title, content_text FROM documents;
+`,
+		},
+		{
+			// Collocation coach (Phase 12). Adds a third suggestion family,
+			// 'collocation', for gentle "natives usually say…" hints on
+			// non-native word pairings. The `type` column carries a CHECK
+			// constraint and SQLite cannot ALTER one in place, so we rebuild the
+			// suggestions table with the extended CHECK, copy every row across,
+			// and recreate its index. Nothing references suggestions, so dropping
+			// the old table is safe; the new table keeps the same ON DELETE
+			// CASCADE to documents.
+			name: "0005_collocation_suggestion_type",
+			stmt: `
+CREATE TABLE suggestions_new (
+    id           TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+    doc_id       TEXT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    from_pos     INTEGER NOT NULL,
+    to_pos       INTEGER NOT NULL,
+    original     TEXT NOT NULL,
+    replacement  TEXT NOT NULL,
+    explanation  TEXT NOT NULL,
+    type         TEXT NOT NULL CHECK(type IN ('grammar','phrasing','idiom','clarity','voice','collocation')),
+    status       TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending','accepted','rejected')),
+    created_at   DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+INSERT INTO suggestions_new (id, doc_id, from_pos, to_pos, original, replacement, explanation, type, status, created_at)
+SELECT id, doc_id, from_pos, to_pos, original, replacement, explanation, type, status, created_at FROM suggestions;
+
+DROP TABLE suggestions;
+ALTER TABLE suggestions_new RENAME TO suggestions;
+CREATE INDEX idx_suggestions_doc_id ON suggestions(doc_id);
+`,
+		},
+		{
+			// Vocabulary garden (Phase 13). Every word the writer looks up is
+			// captured here and put on a gentle spaced-repetition schedule, turning
+			// passive lookups into real vocabulary. `example` holds the sentence the
+			// word appeared in (captured at lookup) for context during review;
+			// `doc_id` links back to where she met the word (nulled if that doc is
+			// deleted — the word stays in the garden). The SM-2-lite scheduling
+			// columns (due_at/interval_days/ease/reps/lapses/last_reviewed) drive a
+			// Leitner-style ladder (see internal/vocab/scheduler.go). UNIQUE on
+			// (user_id, word) makes capture an idempotent upsert.
+			name: "0006_vocab_garden",
+			stmt: `
+CREATE TABLE vocab_words (
+    id            TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+    user_id       TEXT NOT NULL REFERENCES users(id),
+    word          TEXT NOT NULL,
+    gloss         TEXT NOT NULL DEFAULT '',
+    phonetic      TEXT NOT NULL DEFAULT '',
+    example       TEXT NOT NULL DEFAULT '',
+    doc_id        TEXT REFERENCES documents(id) ON DELETE SET NULL,
+    due_at        DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    interval_days INTEGER NOT NULL DEFAULT 0,
+    ease          REAL NOT NULL DEFAULT 2.5,
+    reps          INTEGER NOT NULL DEFAULT 0,
+    lapses        INTEGER NOT NULL DEFAULT 0,
+    last_reviewed DATETIME,
+    created_at    DATETIME DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE(user_id, word)
+);
+
+CREATE INDEX idx_vocab_due ON vocab_words(user_id, due_at);
+`,
+		},
+		{
+			// Vocabulary garden, follow-up. Some looked-up words have an English
+			// definition but no Chinese gloss; those produced an unanswerable review
+			// card (review reveals only the gloss). `definition` stores a short
+			// English sense captured at lookup as a fallback "meaning" so such words
+			// are still reviewable.
+			name: "0007_vocab_definition",
+			stmt: `
+ALTER TABLE vocab_words ADD COLUMN definition TEXT NOT NULL DEFAULT '';
 `,
 		},
 	}

internal/db/db_test.go

@@ -39,6 +39,14 @@ func TestOpenMigratesAndSeeds(t *testing.T) {
 		t.Fatalf("insert voice suggestion: %v", err)
 	}
 
+	// The collocation type (added by migration 0005's table rebuild) is permitted.
+	if _, err := d.Exec(
+		`INSERT INTO suggestions (doc_id, from_pos, to_pos, original, replacement, explanation, type)
+		 VALUES ('d1', 0, 9, 'do a decision', 'make a decision', 'natives usually say…', 'collocation')`,
+	); err != nil {
+		t.Fatalf("insert collocation suggestion: %v", err)
+	}
+
 	// An invalid type is rejected.
 	if _, err := d.Exec(
 		`INSERT INTO suggestions (doc_id, from_pos, to_pos, original, replacement, explanation, type)

internal/db/models.go

@@ -88,18 +88,19 @@ type Suggestion struct {
 	Original    string    `json:"original"`
 	Replacement string    `json:"replacement"`
 	Explanation string    `json:"explanation"`
-	Type        string    `json:"type"`   // grammar | phrasing | idiom | clarity | voice
+	Type        string    `json:"type"`   // grammar | phrasing | idiom | clarity | voice | collocation
 	Status      string    `json:"status"` // pending | accepted | rejected
 	CreatedAt   time.Time `json:"created_at"`
 }
 
 // Suggestion type and status values, mirrored from the schema CHECK constraints.
 const (
-	SuggestionTypeGrammar  = "grammar"
-	SuggestionTypePhrasing = "phrasing"
-	SuggestionTypeIdiom    = "idiom"
-	SuggestionTypeClarity  = "clarity"
-	SuggestionTypeVoice    = "voice"
+	SuggestionTypeGrammar     = "grammar"
+	SuggestionTypePhrasing    = "phrasing"
+	SuggestionTypeIdiom       = "idiom"
+	SuggestionTypeClarity     = "clarity"
+	SuggestionTypeVoice       = "voice"
+	SuggestionTypeCollocation = "collocation"
 
 	SuggestionStatusPending  = "pending"
 	SuggestionStatusAccepted = "accepted"

internal/docs/export.go

@@ -14,6 +14,7 @@ import (
 	"github.com/go-chi/chi/v5"
 
 	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/httputil"
 )
 
 // exportRoutes registers the download endpoints: one document
@@ -48,7 +49,7 @@ func (h *Handler) exportAll(w http.ResponseWriter, r *http.Request) {
 		db.LocalUserID,
 	)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 	defer rows.Close()
@@ -62,12 +63,12 @@ func (h *Handler) exportAll(w http.ResponseWriter, r *http.Request) {
 			&doc.ID, &doc.UserID, &doc.Title, &doc.Content, &doc.ContentText,
 			&doc.Tone, &doc.WordCount, &doc.CreatedAt, &doc.UpdatedAt,
 		); err != nil {
-			serverError(w, err)
+			httputil.ServerError(w, err)
 			return
 		}
 		body, err := format.render(doc)
 		if err != nil {
-			serverError(w, err)
+			httputil.ServerError(w, err)
 			return
 		}
 		base := sanitizeFilename(doc.Title)
@@ -82,20 +83,20 @@ func (h *Handler) exportAll(w http.ResponseWriter, r *http.Request) {
 		seen[key]++
 		f, err := zw.Create(name)
 		if err != nil {
-			serverError(w, err)
+			httputil.ServerError(w, err)
 			return
 		}
 		if _, err := f.Write(body); err != nil {
-			serverError(w, err)
+			httputil.ServerError(w, err)
 			return
 		}
 	}
 	if err := rows.Err(); err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 	if err := zw.Close(); err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 
@@ -148,13 +149,13 @@ func (h *Handler) export(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 
 	body, err := format.render(doc)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 

internal/docs/handlers.go

@@ -13,6 +13,7 @@ import (
 	"github.com/go-chi/chi/v5"
 
 	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/httputil"
 )
 
 // Handler holds the dependencies shared by every document route.
@@ -62,7 +63,7 @@ func (h *Handler) list(w http.ResponseWriter, r *http.Request) {
 		db.LocalUserID,
 	)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 	defer rows.Close()
@@ -72,20 +73,20 @@ func (h *Handler) list(w http.ResponseWriter, r *http.Request) {
 	for rows.Next() {
 		var d docSummary
 		if err := rows.Scan(&d.ID, &d.Title, &d.WordCount, &d.UpdatedAt); err != nil {
-			serverError(w, err)
+			httputil.ServerError(w, err)
 			return
 		}
 		out = append(out, d)
 		ids = append(ids, d.ID)
 	}
 	if err := rows.Err(); err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 
 	byDoc, err := h.tagsByDoc(ids)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 	for i := range out {
@@ -94,7 +95,7 @@ func (h *Handler) list(w http.ResponseWriter, r *http.Request) {
 			out[i].Tags = []db.Tag{}
 		}
 	}
-	writeJSON(w, http.StatusOK, out)
+	httputil.WriteJSON(w, http.StatusOK, out)
 }
 
 // create inserts a fresh blank document and returns it in full.
@@ -109,10 +110,10 @@ func (h *Handler) create(w http.ResponseWriter, r *http.Request) {
 		&doc.Tone, &doc.WordCount, &doc.CreatedAt, &doc.UpdatedAt,
 	)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
-	writeJSON(w, http.StatusCreated, doc)
+	httputil.WriteJSON(w, http.StatusCreated, doc)
 }
 
 // get returns a single full document by id.
@@ -123,10 +124,10 @@ func (h *Handler) get(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
-	writeJSON(w, http.StatusOK, doc)
+	httputil.WriteJSON(w, http.StatusOK, doc)
 }
 
 // updateRequest is the auto-save payload. Every field is optional (a pointer) so
@@ -163,7 +164,7 @@ func (h *Handler) update(w http.ResponseWriter, r *http.Request) {
 		req.Title, req.Content, req.ContentText, req.Tone, req.WordCount, id, db.LocalUserID,
 	)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 	if n, _ := res.RowsAffected(); n == 0 {
@@ -173,7 +174,7 @@ func (h *Handler) update(w http.ResponseWriter, r *http.Request) {
 
 	doc, err := h.fetch(id)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 
@@ -186,7 +187,7 @@ func (h *Handler) update(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 
-	writeJSON(w, http.StatusOK, doc)
+	httputil.WriteJSON(w, http.StatusOK, doc)
 }
 
 // delete removes a document (suggestions cascade via the FK).
@@ -196,7 +197,7 @@ func (h *Handler) delete(w http.ResponseWriter, r *http.Request) {
 		chi.URLParam(r, "id"), db.LocalUserID,
 	)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 	if n, _ := res.RowsAffected(); n == 0 {
@@ -222,21 +223,12 @@ func (h *Handler) fetch(id string) (db.Document, error) {
 }
 
 // --- small response helpers -------------------------------------------------
+//
+// The generic JSON/error helpers live in internal/httputil; these are the
+// document-specific shorthands that carry domain wording.
 
-func writeJSON(w http.ResponseWriter, status int, v any) {
-	w.Header().Set("Content-Type", "application/json")
-	w.WriteHeader(status)
-	_ = json.NewEncoder(w).Encode(v)
+func badRequest(w http.ResponseWriter, msg string) { httputil.BadRequest(w, msg) }
+func notFound(w http.ResponseWriter) {
+	httputil.ErrorJSON(w, http.StatusNotFound, "document not found")
 }
-
-func errorJSON(w http.ResponseWriter, status int, msg string) {
-	writeJSON(w, status, map[string]string{"error": msg})
-}
-
-func serverError(w http.ResponseWriter, err error) {
-	errorJSON(w, http.StatusInternalServerError, err.Error())
-}
-
-func badRequest(w http.ResponseWriter, msg string) { errorJSON(w, http.StatusBadRequest, msg) }
-func notFound(w http.ResponseWriter)               { errorJSON(w, http.StatusNotFound, "document not found") }
-func notFoundMsg(w http.ResponseWriter, msg string) { errorJSON(w, http.StatusNotFound, msg) }
+func notFoundMsg(w http.ResponseWriter, msg string) { httputil.ErrorJSON(w, http.StatusNotFound, msg) }

internal/docs/search.go

@@ -8,6 +8,7 @@ import (
 	"github.com/go-chi/chi/v5"
 
 	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/httputil"
 )
 
 // Search snippet shaping.
@@ -57,7 +58,7 @@ func (h *Handler) SearchRoutes() chi.Router {
 func (h *Handler) search(w http.ResponseWriter, r *http.Request) {
 	q := strings.TrimSpace(r.URL.Query().Get("q"))
 	if q == "" {
-		writeJSON(w, http.StatusOK, []searchResult{})
+		httputil.WriteJSON(w, http.StatusOK, []searchResult{})
 		return
 	}
 
@@ -82,20 +83,20 @@ func (h *Handler) search(w http.ResponseWriter, r *http.Request) {
 			phrase, db.LocalUserID, maxSearchResults,
 		)
 		if err != nil {
-			serverError(w, err)
+			httputil.ServerError(w, err)
 			return
 		}
 		defer sqlRows.Close()
 		for sqlRows.Next() {
 			var rw row
 			if err := sqlRows.Scan(&rw.id, &rw.title, &rw.contentText, &rw.wordCount, &rw.updatedAt); err != nil {
-				serverError(w, err)
+				httputil.ServerError(w, err)
 				return
 			}
 			rows = append(rows, rw)
 		}
 		if err := sqlRows.Err(); err != nil {
-			serverError(w, err)
+			httputil.ServerError(w, err)
 			return
 		}
 	} else {
@@ -112,20 +113,20 @@ func (h *Handler) search(w http.ResponseWriter, r *http.Request) {
 			db.LocalUserID, like, like, maxSearchResults,
 		)
 		if err != nil {
-			serverError(w, err)
+			httputil.ServerError(w, err)
 			return
 		}
 		defer sqlRows.Close()
 		for sqlRows.Next() {
 			var rw row
 			if err := sqlRows.Scan(&rw.id, &rw.title, &rw.contentText, &rw.wordCount, &rw.updatedAt); err != nil {
-				serverError(w, err)
+				httputil.ServerError(w, err)
 				return
 			}
 			rows = append(rows, rw)
 		}
 		if err := sqlRows.Err(); err != nil {
-			serverError(w, err)
+			httputil.ServerError(w, err)
 			return
 		}
 	}
@@ -145,7 +146,7 @@ func (h *Handler) search(w http.ResponseWriter, r *http.Request) {
 
 	byDoc, err := h.tagsByDoc(ids)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 	for i := range out {
@@ -154,7 +155,7 @@ func (h *Handler) search(w http.ResponseWriter, r *http.Request) {
 			out[i].Tags = []db.Tag{}
 		}
 	}
-	writeJSON(w, http.StatusOK, out)
+	httputil.WriteJSON(w, http.StatusOK, out)
 }
 
 // escapeLike escapes the LIKE metacharacters (% and _) and the escape character

internal/docs/tags.go

@@ -8,6 +8,7 @@ import (
 	"github.com/go-chi/chi/v5"
 
 	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/httputil"
 )
 
 // validTagColors is the palette a tag may use, mirrored from the design tokens.
@@ -57,7 +58,7 @@ func (h *Handler) listTags(w http.ResponseWriter, r *http.Request) {
 		db.LocalUserID,
 	)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 	defer rows.Close()
@@ -66,16 +67,16 @@ func (h *Handler) listTags(w http.ResponseWriter, r *http.Request) {
 	for rows.Next() {
 		var t db.Tag
 		if err := rows.Scan(&t.ID, &t.Name, &t.Color, &t.DocCount); err != nil {
-			serverError(w, err)
+			httputil.ServerError(w, err)
 			return
 		}
 		out = append(out, t)
 	}
 	if err := rows.Err(); err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
-	writeJSON(w, http.StatusOK, out)
+	httputil.WriteJSON(w, http.StatusOK, out)
 }
 
 type tagRequest struct {
@@ -106,10 +107,10 @@ func (h *Handler) createTag(w http.ResponseWriter, r *http.Request) {
 		db.LocalUserID, name, normalizeColor(req.Color),
 	).Scan(&t.ID, &t.Name, &t.Color)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
-	writeJSON(w, http.StatusCreated, t)
+	httputil.WriteJSON(w, http.StatusCreated, t)
 }
 
 // updateTag renames and/or recolors a tag. Both fields optional via pointers so
@@ -147,7 +148,7 @@ func (h *Handler) updateTag(w http.ResponseWriter, r *http.Request) {
 		namePtr, colorPtr, id, db.LocalUserID,
 	)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 	if n, _ := res.RowsAffected(); n == 0 {
@@ -160,10 +161,10 @@ func (h *Handler) updateTag(w http.ResponseWriter, r *http.Request) {
 		`SELECT id, name, color FROM tags WHERE id = ? AND user_id = ?`,
 		id, db.LocalUserID,
 	).Scan(&t.ID, &t.Name, &t.Color); err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
-	writeJSON(w, http.StatusOK, t)
+	httputil.WriteJSON(w, http.StatusOK, t)
 }
 
 // deleteTag removes a tag; its document assignments cascade away via the FK.
@@ -173,7 +174,7 @@ func (h *Handler) deleteTag(w http.ResponseWriter, r *http.Request) {
 		chi.URLParam(r, "id"), db.LocalUserID,
 	)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 	if n, _ := res.RowsAffected(); n == 0 {
@@ -216,7 +217,7 @@ func (h *Handler) assignTag(w http.ResponseWriter, r *http.Request) {
 		 ON CONFLICT(doc_id, tag_id) DO NOTHING`,
 		docID, req.TagID,
 	); err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 	w.WriteHeader(http.StatusNoContent)
@@ -235,7 +236,7 @@ func (h *Handler) unassignTag(w http.ResponseWriter, r *http.Request) {
 		`DELETE FROM document_tags WHERE doc_id = ? AND tag_id = ?`,
 		docID, tagID,
 	); err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 	w.WriteHeader(http.StatusNoContent)

internal/docs/versions.go

@@ -9,6 +9,7 @@ import (
 	"github.com/go-chi/chi/v5"
 
 	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/httputil"
 )
 
 // Version-history tuning.
@@ -29,8 +30,8 @@ const (
 // resolve to /api/docs/{id}/versions...
 func (h *Handler) versionRoutes(r chi.Router) {
 	r.Get("/{id}/versions", h.listVersions)
-	r.Post("/{id}/versions", h.createVersion)            // explicit "save a restore point"
-	r.Get("/{id}/versions/{vid}", h.getVersion)          // full body for preview
+	r.Post("/{id}/versions", h.createVersion)   // explicit "save a restore point"
+	r.Get("/{id}/versions/{vid}", h.getVersion) // full body for preview
 	r.Post("/{id}/versions/{vid}/restore", h.restoreVersion)
 }
 
@@ -50,7 +51,7 @@ func (h *Handler) listVersions(w http.ResponseWriter, r *http.Request) {
 		docID, db.LocalUserID,
 	)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 	defer rows.Close()
@@ -59,16 +60,16 @@ func (h *Handler) listVersions(w http.ResponseWriter, r *http.Request) {
 	for rows.Next() {
 		var v db.DocumentVersion
 		if err := rows.Scan(&v.ID, &v.DocID, &v.Title, &v.WordCount, &v.Kind, &v.CreatedAt); err != nil {
-			serverError(w, err)
+			httputil.ServerError(w, err)
 			return
 		}
 		out = append(out, v)
 	}
 	if err := rows.Err(); err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
-	writeJSON(w, http.StatusOK, out)
+	httputil.WriteJSON(w, http.StatusOK, out)
 }
 
 // getVersion returns one snapshot in full (including content) for preview.
@@ -79,10 +80,10 @@ func (h *Handler) getVersion(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
-	writeJSON(w, http.StatusOK, v)
+	httputil.WriteJSON(w, http.StatusOK, v)
 }
 
 // createVersion takes an explicit, user-requested ('manual') restore point from
@@ -96,16 +97,16 @@ func (h *Handler) createVersion(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 
 	v, err := h.insertVersion(doc, db.VersionKindManual)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
-	writeJSON(w, http.StatusCreated, v)
+	httputil.WriteJSON(w, http.StatusCreated, v)
 }
 
 // restoreVersion copies a snapshot back onto the live document. Before
@@ -121,17 +122,17 @@ func (h *Handler) restoreVersion(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 
 	current, err := h.fetch(docID)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 	if _, err := h.insertVersion(current, db.VersionKindPreRestore); err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 
@@ -143,7 +144,7 @@ func (h *Handler) restoreVersion(w http.ResponseWriter, r *http.Request) {
 		v.Title, v.Content, v.ContentText, v.WordCount, docID, db.LocalUserID,
 	)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 	if n, _ := res.RowsAffected(); n == 0 {
@@ -153,10 +154,10 @@ func (h *Handler) restoreVersion(w http.ResponseWriter, r *http.Request) {
 
 	doc, err := h.fetch(docID)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
-	writeJSON(w, http.StatusOK, doc)
+	httputil.WriteJSON(w, http.StatusOK, doc)
 }
 
 // maybeAutoSnapshot records a throttled background snapshot of the just-saved

internal/httputil/json.go

@@ -0,0 +1,37 @@
+// Package httputil holds the small HTTP response helpers shared by every API
+// handler package (docs, suggestions, vocab, …). Keeping them in one place means
+// JSON encoding and — crucially — error handling behave identically everywhere:
+// internal errors are logged in full but never leaked to the client.
+package httputil
+
+import (
+	"encoding/json"
+	"log"
+	"net/http"
+)
+
+// WriteJSON encodes v as the response body with the given status code.
+func WriteJSON(w http.ResponseWriter, status int, v any) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(v)
+}
+
+// ErrorJSON sends a {"error": msg} body with the given status. The message is
+// caller-chosen and safe to show the client.
+func ErrorJSON(w http.ResponseWriter, status int, msg string) {
+	WriteJSON(w, status, map[string]string{"error": msg})
+}
+
+// BadRequest is the common 400 shorthand.
+func BadRequest(w http.ResponseWriter, msg string) {
+	ErrorJSON(w, http.StatusBadRequest, msg)
+}
+
+// ServerError logs the real error (with full detail, for the operator) and
+// returns a generic 500 to the client — raw database/internal errors must never
+// reach the browser, where they leak schema and implementation details.
+func ServerError(w http.ResponseWriter, err error) {
+	log.Printf("internal error: %v", err)
+	ErrorJSON(w, http.StatusInternalServerError, "something went wrong")
+}

internal/llm/collocation.go

@@ -0,0 +1,35 @@
+package llm
+
+import (
+	"context"
+	"time"
+)
+
+// CollocationInterval is the minimum gap between collocation passes for one
+// document. Like the voice pass it runs on an explicit user action ("Make it
+// sound natural") rather than a typing cadence, so this floor only guards the
+// inference endpoint against the button being mashed.
+const CollocationInterval = 25 * time.Second
+
+// RunCollocation sends the WHOLE document for a collocation pass — gentle
+// "natives usually say…" hints on non-native word pairings — and parses the JSON
+// result with the checkpoint's tolerant parser. It is deliberately NOT
+// TruncateDoc'd: like the voice pass it reads the whole document so the hints
+// reflect the full piece. Each flag carries a native replacement to apply.
+//
+// The tone argument is accepted for a uniform pass signature and passed through
+// to the prompt so a hint can prefer a register-appropriate pairing.
+func RunCollocation(ctx context.Context, client LLMClient, contentText, tone string) ([]RawSuggestion, error) {
+	raw, err := client.Complete(ctx, CompletionRequest{
+		Messages:          CollocationMessages(contentText, tone),
+		MaxTokens:         2048,
+		Temperature:       0.3,
+		RepetitionPenalty: 1.15,
+		TopP:              0.9,
+		Stop:              []string{"```", "\n\n\n\n"},
+	})
+	if err != nil {
+		return nil, err
+	}
+	return ParseCheckpoint(raw)
+}

internal/llm/prompts.go

@@ -92,6 +92,54 @@ func VoiceMessages(contentText string) []Message {
 	}
 }
 
+// collocationSystemPrompt drives the collocation coach — the single most
+// valuable polish for an ESL writer. It flags word PAIRINGS that are not wrong,
+// just non-native ("do a decision" → "make a decision", "strong rain" → "heavy
+// rain"), and explicitly DEFERS real grammar/spelling errors to the grammar
+// checkpoint so the two families don't overlap. Every explanation is framed as a
+// warm "natives usually say…" note with a short Mandarin gloss — never
+// "error/wrong" — because these are stylistic, not mistakes. It is a distinct
+// pass from the grammar checkpoint (do not bundle them). `replacement` carries
+// the natural pairing the writer can accept in one tap.
+const collocationSystemPrompt = `You are a warm, encouraging writing assistant helping someone who speaks English as a second language. ` +
+	`You are reviewing a COMPLETE document for COLLOCATIONS only — the natural word pairings native speakers use.
+
+A collocation is a pair or short group of words that native speakers habitually say together. ESL writers ` +
+	`often choose words that are grammatically correct but sound non-native: "do a decision" instead of "make a decision", ` +
+	`"strong rain" instead of "heavy rain", "say a joke" instead of "tell a joke". These are NOT grammar mistakes — they ` +
+	`are just not what a native speaker would naturally say.
+
+Identify up to 5 such non-native word pairings. For each, give the natural pairing a native speaker would use. ` +
+	`Be gentle and specific. Do NOT flag grammar errors, spelling mistakes, or unclear sentences — those are handled ` +
+	`elsewhere. Only flag word pairings that are correct but sound non-native.%s
+
+Phrase every explanation warmly as "Natives usually say…" and include a brief Simplified Chinese gloss in parentheses. ` +
+	`Never use the words "error", "wrong", or "mistake" — these are friendly polish, not corrections.
+
+Respond ONLY with valid JSON. No preamble, no markdown fences. Format:
+{
+  "suggestions": [
+    {
+      "original": "exact word pairing from the document",
+      "replacement": "the natural native pairing",
+      "explanation": "friendly note, e.g. 'Natives usually say \"make a decision\" rather than \"do a decision\" (native usage / 地道说法).'",
+      "type": "collocation"
+    }
+  ]
+}
+
+If every pairing already sounds natural, return: {"suggestions": []}`
+
+// CollocationMessages builds the message array for a collocation pass over the
+// WHOLE document (no truncation), gently steered toward the document's tone so a
+// hint can prefer a register-appropriate pairing.
+func CollocationMessages(contentText, tone string) []Message {
+	return []Message{
+		{Role: "system", Content: fmt.Sprintf(collocationSystemPrompt, toneGuidance(tone))},
+		{Role: "user", Content: contentText},
+	}
+}
+
 // askPetalSystemTemplate is the Ask Petal tutor prompt. The suggestion context
 // is interpolated in; the user's own messages are appended after this system
 // turn by the caller.

internal/suggestions/chat.go

@@ -10,6 +10,7 @@ import (
 	"github.com/go-chi/chi/v5"
 
 	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/httputil"
 	"gitea.parodia.dev/drwily/petal/internal/llm"
 )
 
@@ -29,7 +30,7 @@ func (h *Handler) chat(w http.ResponseWriter, r *http.Request) {
 
 	var body chatRequest
 	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
-		errorJSON(w, http.StatusBadRequest, "invalid request body")
+		httputil.ErrorJSON(w, http.StatusBadRequest, "invalid request body")
 		return
 	}
 
@@ -37,8 +38,8 @@ func (h *Handler) chat(w http.ResponseWriter, r *http.Request) {
 	// scoped to the local user so a stray id can't read another user's doc.
 	var (
 		original, replacement, explanation, typ string
-		fromPos                                  int
-		contentText                              string
+		fromPos                                 int
+		contentText                             string
 	)
 	err := h.DB.QueryRow(
 		`SELECT s.original, s.replacement, s.explanation, s.type, s.from_pos, d.content_text
@@ -48,11 +49,11 @@ func (h *Handler) chat(w http.ResponseWriter, r *http.Request) {
 		sugID, db.LocalUserID,
 	).Scan(&original, &replacement, &explanation, &typ, &fromPos, &contentText)
 	if errors.Is(err, sql.ErrNoRows) {
-		errorJSON(w, http.StatusNotFound, "suggestion not found")
+		httputil.ErrorJSON(w, http.StatusNotFound, "suggestion not found")
 		return
 	}
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 
@@ -63,7 +64,7 @@ func (h *Handler) chat(w http.ResponseWriter, r *http.Request) {
 	// Flush through; bail with a plain error if somehow they don't.
 	flusher, ok := w.(http.Flusher)
 	if !ok {
-		serverError(w, errors.New("streaming unsupported"))
+		httputil.ServerError(w, errors.New("streaming unsupported"))
 		return
 	}
 
@@ -71,7 +72,7 @@ func (h *Handler) chat(w http.ResponseWriter, r *http.Request) {
 	if err != nil {
 		// The stream never opened (e.g. LLM unreachable) — a normal JSON error is
 		// still appropriate since we haven't written SSE headers yet.
-		errorJSON(w, http.StatusBadGateway, "chat failed: "+err.Error())
+		httputil.ErrorJSON(w, http.StatusBadGateway, "chat failed: "+err.Error())
 		return
 	}
 

internal/suggestions/handlers.go

@@ -8,7 +8,6 @@ package suggestions
 import (
 	"context"
 	"database/sql"
-	"encoding/json"
 	"errors"
 	"net/http"
 	"strings"
@@ -16,6 +15,7 @@ import (
 	"github.com/go-chi/chi/v5"
 
 	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/httputil"
 	"gitea.parodia.dev/drwily/petal/internal/llm"
 )
 
@@ -23,19 +23,22 @@ import (
 // grammar checkpoint and the voice pass each get their own per-document rate
 // limiter — they are independent passes with different cadences.
 type Handler struct {
-	DB         *db.DB
-	Client     llm.LLMClient
-	Limit      *llm.RateLimiter // grammar checkpoint floor
-	VoiceLimit *llm.RateLimiter // voice-consistency floor
+	DB               *db.DB
+	Client           llm.LLMClient
+	Limit            *llm.RateLimiter // grammar checkpoint floor
+	VoiceLimit       *llm.RateLimiter // voice-consistency floor
+	CollocationLimit *llm.RateLimiter // collocation-coach floor
 }
 
-// New constructs a Handler with per-document checkpoint and voice rate limiters.
+// New constructs a Handler with per-document checkpoint, voice, and collocation
+// rate limiters.
 func New(database *db.DB, client llm.LLMClient) *Handler {
 	return &Handler{
-		DB:         database,
-		Client:     client,
-		Limit:      llm.NewRateLimiter(llm.CheckpointInterval),
-		VoiceLimit: llm.NewRateLimiter(llm.VoiceInterval),
+		DB:               database,
+		Client:           client,
+		Limit:            llm.NewRateLimiter(llm.CheckpointInterval),
+		VoiceLimit:       llm.NewRateLimiter(llm.VoiceInterval),
+		CollocationLimit: llm.NewRateLimiter(llm.CollocationInterval),
 	}
 }
 
@@ -44,6 +47,7 @@ func New(database *db.DB, client llm.LLMClient) *Handler {
 func (h *Handler) RegisterDocRoutes(r chi.Router) {
 	r.Post("/{id}/check", h.check)
 	r.Post("/{id}/voice", h.voice)
+	r.Post("/{id}/collocation", h.collocation)
 	r.Post("/{id}/rewrite", h.rewrite)
 	r.Get("/{id}/suggestions", h.listForDoc)
 }
@@ -70,6 +74,13 @@ func (h *Handler) voice(w http.ResponseWriter, r *http.Request) {
 	h.runPass(w, r, h.VoiceLimit, llm.RunVoice, voiceScope)
 }
 
+// collocation runs the collocation coach over the whole document, flagging
+// non-native word pairings. Explicit-action pass; replaces only the pending
+// collocation flags.
+func (h *Handler) collocation(w http.ResponseWriter, r *http.Request) {
+	h.runPass(w, r, h.CollocationLimit, llm.RunCollocation, collocationScope)
+}
+
 // pass is the signature shared by the grammar checkpoint and the voice pass:
 // given the document text and the document's tone it returns the model's raw
 // suggestions. The voice pass ignores tone (see llm.RunVoice).
@@ -88,17 +99,17 @@ func (h *Handler) runPass(w http.ResponseWriter, r *http.Request, limiter *llm.R
 		docID, db.LocalUserID,
 	).Scan(&contentText, &tone)
 	if errors.Is(err, sql.ErrNoRows) {
-		errorJSON(w, http.StatusNotFound, "document not found")
+		httputil.ErrorJSON(w, http.StatusNotFound, "document not found")
 		return
 	}
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 
 	// Nothing to analyze on an empty document — skip the LLM round-trip.
 	if strings.TrimSpace(contentText) == "" {
-		writeJSON(w, http.StatusOK, []db.Suggestion{})
+		httputil.WriteJSON(w, http.StatusOK, []db.Suggestion{})
 		return
 	}
 
@@ -108,10 +119,10 @@ func (h *Handler) runPass(w http.ResponseWriter, r *http.Request, limiter *llm.R
 		// error, so the frontend keeps showing current suggestions.
 		existing, err := h.fetchPending(docID)
 		if err != nil {
-			serverError(w, err)
+			httputil.ServerError(w, err)
 			return
 		}
-		writeJSON(w, http.StatusOK, existing)
+		httputil.WriteJSON(w, http.StatusOK, existing)
 		return
 	}
 
@@ -121,12 +132,12 @@ func (h *Handler) runPass(w http.ResponseWriter, r *http.Request, limiter *llm.R
 		// the per-document slot for the full interval — stranding the frontend's
 		// auto-retry on the throttle path. Release it so a retry can re-run.
 		limiter.Release(docID, slotAt)
-		errorJSON(w, http.StatusBadGateway, "llm pass failed: "+err.Error())
+		httputil.ErrorJSON(w, http.StatusBadGateway, "llm pass failed: "+err.Error())
 		return
 	}
 
 	if err := h.replacePending(docID, contentText, raw, scope); err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 
@@ -135,10 +146,10 @@ func (h *Handler) runPass(w http.ResponseWriter, r *http.Request, limiter *llm.R
 	// throttle path above stays consistent with the success path.
 	out, err := h.fetchPending(docID)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
-	writeJSON(w, http.StatusOK, out)
+	httputil.WriteJSON(w, http.StatusOK, out)
 }
 
 // pendingScope describes how one LLM pass touches the shared suggestions table:
@@ -151,10 +162,14 @@ type pendingScope struct {
 }
 
 var (
-	// grammarScope owns the grammar/phrasing/idiom/clarity flags (everything but voice).
-	grammarScope = pendingScope{deleteWhere: "type != 'voice'", forceType: ""}
+	// grammarScope owns the grammar/phrasing/idiom/clarity flags — everything but
+	// the explicit-action families (voice, collocation), which run on their own
+	// cadence and must survive a grammar checkpoint.
+	grammarScope = pendingScope{deleteWhere: "type NOT IN ('voice','collocation')", forceType: ""}
 	// voiceScope owns the voice flags only.
 	voiceScope = pendingScope{deleteWhere: "type = 'voice'", forceType: db.SuggestionTypeVoice}
+	// collocationScope owns the collocation flags only.
+	collocationScope = pendingScope{deleteWhere: "type = 'collocation'", forceType: db.SuggestionTypeCollocation}
 )
 
 // replacePending swaps a document's pending suggestions within one family for a
@@ -246,10 +261,10 @@ func suggestionKey(original, replacement string) string {
 func (h *Handler) listForDoc(w http.ResponseWriter, r *http.Request) {
 	out, err := h.fetchPending(chi.URLParam(r, "id"))
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
-	writeJSON(w, http.StatusOK, out)
+	httputil.WriteJSON(w, http.StatusOK, out)
 }
 
 func (h *Handler) fetchPending(docID string) ([]db.Suggestion, error) {
@@ -295,11 +310,11 @@ func (h *Handler) setStatus(w http.ResponseWriter, r *http.Request, status strin
 		status, chi.URLParam(r, "id"), db.SuggestionStatusPending,
 	)
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 	if n, _ := res.RowsAffected(); n == 0 {
-		errorJSON(w, http.StatusNotFound, "pending suggestion not found")
+		httputil.ErrorJSON(w, http.StatusNotFound, "pending suggestion not found")
 		return
 	}
 	w.WriteHeader(http.StatusNoContent)
@@ -320,25 +335,9 @@ func locate(contentText, original string) (int, int) {
 // defaulting unknown values to grammar so a stray label never trips the CHECK.
 func normalizeType(t string) string {
 	switch strings.ToLower(strings.TrimSpace(t)) {
-	case db.SuggestionTypeGrammar, db.SuggestionTypePhrasing, db.SuggestionTypeIdiom, db.SuggestionTypeClarity:
+	case db.SuggestionTypeGrammar, db.SuggestionTypePhrasing, db.SuggestionTypeIdiom, db.SuggestionTypeClarity, db.SuggestionTypeCollocation:
 		return strings.ToLower(strings.TrimSpace(t))
 	default:
 		return db.SuggestionTypeGrammar
 	}
 }
-
-// --- response helpers -------------------------------------------------------
-
-func writeJSON(w http.ResponseWriter, status int, v any) {
-	w.Header().Set("Content-Type", "application/json")
-	w.WriteHeader(status)
-	_ = json.NewEncoder(w).Encode(v)
-}
-
-func errorJSON(w http.ResponseWriter, status int, msg string) {
-	writeJSON(w, status, map[string]string{"error": msg})
-}
-
-func serverError(w http.ResponseWriter, err error) {
-	errorJSON(w, http.StatusInternalServerError, err.Error())
-}

internal/suggestions/handlers_test.go

@@ -227,6 +227,65 @@ func TestVoicePassCoexists(t *testing.T) {
 	}
 }
 
+// TestCollocationPassCoexists proves the collocation coach is a third
+// independent family: it never wipes grammar or voice pending flags, a grammar
+// checkpoint never wipes its flags, and each endpoint returns the unified set.
+func TestCollocationPassCoexists(t *testing.T) {
+	client := &switchClient{}
+	srv, docID, h := newTestServer(t, client)
+	// Zero the floors so the test can re-run passes without waiting them out.
+	h.Limit = llm.NewRateLimiter(0)
+	h.VoiceLimit = llm.NewRateLimiter(0)
+	h.CollocationLimit = llm.NewRateLimiter(0)
+
+	// Grammar + voice first, so all three families are exercised.
+	client.response = `{"suggestions":[{"original":"I has","replacement":"I have","explanation":"agreement","type":"grammar"}]}`
+	if rec := do(t, srv, http.MethodPost, "/docs/"+docID+"/check", ""); rec.Code != http.StatusOK {
+		t.Fatalf("check: code=%d body=%s", rec.Code, rec.Body)
+	}
+	client.response = `{"suggestions":[{"original":"two apple","replacement":null,"explanation":"sounds formal","type":"voice"}]}`
+	if rec := do(t, srv, http.MethodPost, "/docs/"+docID+"/voice", ""); rec.Code != http.StatusOK {
+		t.Fatalf("voice: code=%d body=%s", rec.Code, rec.Body)
+	}
+
+	// Collocation pass → a third flag (with a replacement). It must keep the
+	// grammar and voice flags; the response is the unified set of all three.
+	client.response = `{"suggestions":[{"original":"two apple","replacement":"two apples","explanation":"Natives usually say…","type":"collocation"}]}`
+	rec := do(t, srv, http.MethodPost, "/docs/"+docID+"/collocation", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("collocation: code=%d body=%s", rec.Code, rec.Body)
+	}
+	var got []db.Suggestion
+	if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	byType := map[string]bool{}
+	for _, s := range got {
+		byType[s.Type] = true
+	}
+	if !byType[db.SuggestionTypeGrammar] || !byType[db.SuggestionTypeVoice] || !byType[db.SuggestionTypeCollocation] {
+		t.Fatalf("collocation response should carry all three families, got %+v", got)
+	}
+
+	// A grammar checkpoint must NOT wipe the voice or collocation flags.
+	client.response = `{"suggestions":[]}`
+	rec = do(t, srv, http.MethodPost, "/docs/"+docID+"/check", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("second check: code=%d body=%s", rec.Code, rec.Body)
+	}
+	_ = json.Unmarshal(rec.Body.Bytes(), &got)
+	byType = map[string]bool{}
+	for _, s := range got {
+		byType[s.Type] = true
+	}
+	if byType[db.SuggestionTypeGrammar] {
+		t.Fatalf("grammar flag should have cleared, got %+v", got)
+	}
+	if !byType[db.SuggestionTypeVoice] || !byType[db.SuggestionTypeCollocation] {
+		t.Fatalf("grammar checkpoint wiped a sibling family, got %+v", got)
+	}
+}
+
 // switchClient returns a response that can be swapped between calls.
 type switchClient struct {
 	response string

internal/suggestions/rewrite.go

@@ -10,6 +10,7 @@ import (
 	"github.com/go-chi/chi/v5"
 
 	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/httputil"
 	"gitea.parodia.dev/drwily/petal/internal/llm"
 )
 
@@ -36,17 +37,17 @@ func (h *Handler) rewrite(w http.ResponseWriter, r *http.Request) {
 
 	var body rewriteRequest
 	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
-		errorJSON(w, http.StatusBadRequest, "invalid request body")
+		httputil.ErrorJSON(w, http.StatusBadRequest, "invalid request body")
 		return
 	}
 
 	text := strings.TrimSpace(body.Text)
 	if text == "" {
-		errorJSON(w, http.StatusBadRequest, "no text to rewrite")
+		httputil.ErrorJSON(w, http.StatusBadRequest, "no text to rewrite")
 		return
 	}
 	if len([]rune(text)) > llm.RewriteMaxRunes {
-		errorJSON(w, http.StatusBadRequest, "selection too long to rewrite")
+		httputil.ErrorJSON(w, http.StatusBadRequest, "selection too long to rewrite")
 		return
 	}
 
@@ -58,19 +59,19 @@ func (h *Handler) rewrite(w http.ResponseWriter, r *http.Request) {
 		docID, db.LocalUserID,
 	).Scan(&exists)
 	if errors.Is(err, sql.ErrNoRows) {
-		errorJSON(w, http.StatusNotFound, "document not found")
+		httputil.ErrorJSON(w, http.StatusNotFound, "document not found")
 		return
 	}
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 
 	out, err := llm.RunRewrite(r.Context(), h.Client, text, body.Style)
 	if err != nil {
-		errorJSON(w, http.StatusBadGateway, "rewrite failed: "+err.Error())
+		httputil.ErrorJSON(w, http.StatusBadGateway, "rewrite failed: "+err.Error())
 		return
 	}
 
-	writeJSON(w, http.StatusOK, rewriteResponse{Rewrite: out})
+	httputil.WriteJSON(w, http.StatusOK, rewriteResponse{Rewrite: out})
 }

internal/suggestions/translate.go

@@ -9,6 +9,7 @@ import (
 	"github.com/go-chi/chi/v5"
 
 	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/httputil"
 	"gitea.parodia.dev/drwily/petal/internal/llm"
 )
 
@@ -33,25 +34,25 @@ func (h *Handler) translate(w http.ResponseWriter, r *http.Request) {
 		sugID, db.LocalUserID,
 	).Scan(&explanation)
 	if errors.Is(err, sql.ErrNoRows) {
-		errorJSON(w, http.StatusNotFound, "suggestion not found")
+		httputil.ErrorJSON(w, http.StatusNotFound, "suggestion not found")
 		return
 	}
 	if err != nil {
-		serverError(w, err)
+		httputil.ServerError(w, err)
 		return
 	}
 
 	explanation = strings.TrimSpace(explanation)
 	if explanation == "" {
-		writeJSON(w, http.StatusOK, translateResponse{Translation: ""})
+		httputil.WriteJSON(w, http.StatusOK, translateResponse{Translation: ""})
 		return
 	}
 
 	out, err := llm.RunTranslate(r.Context(), h.Client, explanation)
 	if err != nil {
-		errorJSON(w, http.StatusBadGateway, "translate failed: "+err.Error())
+		httputil.ErrorJSON(w, http.StatusBadGateway, "translate failed: "+err.Error())
 		return
 	}
 
-	writeJSON(w, http.StatusOK, translateResponse{Translation: out})
+	httputil.WriteJSON(w, http.StatusOK, translateResponse{Translation: out})
 }

internal/vocab/handlers.go

@@ -0,0 +1,307 @@
+package vocab
+
+import (
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+
+	"gitea.parodia.dev/drwily/petal/internal/db"
+	"gitea.parodia.dev/drwily/petal/internal/httputil"
+)
+
+// Word is one entry in the vocabulary garden: the looked-up word with its gloss,
+// phonetic, and the sentence it was met in, plus its spaced-repetition state.
+type Word struct {
+	ID           string     `json:"id"`
+	Word         string     `json:"word"`
+	Gloss        string     `json:"gloss"`
+	Definition   string     `json:"definition"` // English fallback meaning when there's no Chinese gloss
+	Phonetic     string     `json:"phonetic"`
+	Example      string     `json:"example"`
+	DocID        *string    `json:"doc_id"`
+	DueAt        time.Time  `json:"due_at"`
+	IntervalDays int        `json:"interval_days"`
+	Ease         float64    `json:"ease"`
+	Reps         int        `json:"reps"`
+	Lapses       int        `json:"lapses"`
+	LastReviewed *time.Time `json:"last_reviewed"`
+	CreatedAt    time.Time  `json:"created_at"`
+}
+
+// Handler owns the vocabulary-garden routes. Everything is scoped to the local
+// user while auth is deferred.
+type Handler struct {
+	DB *db.DB
+}
+
+func New(database *db.DB) *Handler { return &Handler{DB: database} }
+
+// Routes mounts the garden endpoints under /api/vocab.
+func (h *Handler) Routes() chi.Router {
+	r := chi.NewRouter()
+	r.Get("/", h.list)     // the whole garden
+	r.Get("/due", h.due)   // only the cards due for review now
+	r.Post("/", h.capture) // record/upsert a looked-up word
+	r.Post("/{id}/review", h.review)
+	r.Delete("/{id}", h.remove)
+	return r
+}
+
+const vocabColumns = `id, word, gloss, definition, phonetic, example, doc_id,
+	due_at, interval_days, ease, reps, lapses, last_reviewed, created_at`
+
+func scanWord(s interface {
+	Scan(dest ...any) error
+}) (Word, error) {
+	var w Word
+	err := s.Scan(
+		&w.ID, &w.Word, &w.Gloss, &w.Definition, &w.Phonetic, &w.Example, &w.DocID,
+		&w.DueAt, &w.IntervalDays, &w.Ease, &w.Reps, &w.Lapses, &w.LastReviewed, &w.CreatedAt,
+	)
+	return w, err
+}
+
+// list returns the full garden, newest blossoms first.
+func (h *Handler) list(w http.ResponseWriter, _ *http.Request) {
+	h.queryList(w, `SELECT `+vocabColumns+` FROM vocab_words
+		WHERE user_id = ? ORDER BY created_at DESC`, db.LocalUserID)
+}
+
+// due returns only the cards whose review time has arrived, soonest first.
+func (h *Handler) due(w http.ResponseWriter, _ *http.Request) {
+	h.queryList(w, `SELECT `+vocabColumns+` FROM vocab_words
+		WHERE user_id = ? AND due_at <= datetime('now') ORDER BY due_at ASC`, db.LocalUserID)
+}
+
+func (h *Handler) queryList(w http.ResponseWriter, query string, args ...any) {
+	rows, err := h.DB.Query(query, args...)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	defer rows.Close()
+	out := []Word{}
+	for rows.Next() {
+		word, err := scanWord(rows)
+		if err != nil {
+			httputil.ServerError(w, err)
+			return
+		}
+		out = append(out, word)
+	}
+	if err := rows.Err(); err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	httputil.WriteJSON(w, http.StatusOK, out)
+}
+
+type captureRequest struct {
+	Word       string  `json:"word"`
+	Gloss      string  `json:"gloss"`
+	Definition string  `json:"definition"`
+	Phonetic   string  `json:"phonetic"`
+	Example    string  `json:"example"`
+	DocID      *string `json:"doc_id"`
+}
+
+// Field-length caps. The captured fields come from the offline lexicon and the
+// editor selection, not free-typed prose, so we clamp rather than reject — a
+// lookup should never fail because a definition ran long. Counts are runes so a
+// Chinese gloss isn't cut mid-character. The word is the upsert key, so an absurd
+// "word" is bounded too.
+const (
+	maxWordLen       = 128
+	maxGlossLen      = 512
+	maxDefinitionLen = 4096
+	maxPhoneticLen   = 256
+	maxExampleLen    = 4096
+)
+
+// clamp trims s to at most max runes (rune-safe so multibyte glosses survive).
+func clamp(s string, max int) string {
+	r := []rune(s)
+	if len(r) <= max {
+		return s
+	}
+	return string(r[:max])
+}
+
+// capture records a looked-up word. It's an idempotent upsert keyed on the word:
+// a new word lands due tomorrow (interval 1 day); an existing word keeps its
+// schedule untouched but refreshes its gloss/phonetic/example/doc_id so the most
+// recent context wins. Looking words up IS the data source — no extra effort.
+func (h *Handler) capture(w http.ResponseWriter, r *http.Request) {
+	var req captureRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		httputil.ErrorJSON(w, http.StatusBadRequest, "invalid body")
+		return
+	}
+	// Normalize the same way the lexicon does (internal/lexicon: lower+trim) so
+	// the UNIQUE(user_id, word) upsert is genuinely idempotent — otherwise
+	// "Apple" at a sentence start and "apple" mid-line would create two separate
+	// cards on independent schedules.
+	word := clamp(strings.ToLower(strings.TrimSpace(req.Word)), maxWordLen)
+	if word == "" {
+		httputil.ErrorJSON(w, http.StatusBadRequest, "word is required")
+		return
+	}
+	req.Gloss = clamp(req.Gloss, maxGlossLen)
+	req.Definition = clamp(req.Definition, maxDefinitionLen)
+	req.Phonetic = clamp(req.Phonetic, maxPhoneticLen)
+	req.Example = clamp(req.Example, maxExampleLen)
+
+	// A blank doc_id is the same as none; otherwise the word must belong to a
+	// document the user actually owns. Without this check a stale or forged id
+	// would hit the foreign key and leak a raw "FOREIGN KEY constraint" 500
+	// instead of a clean 400 (and, once auth lands, would let a word be attached
+	// to another user's document).
+	if req.DocID != nil {
+		if strings.TrimSpace(*req.DocID) == "" {
+			req.DocID = nil
+		} else {
+			var ok int
+			err := h.DB.QueryRow(
+				`SELECT 1 FROM documents WHERE id = ? AND user_id = ?`,
+				*req.DocID, db.LocalUserID,
+			).Scan(&ok)
+			if errors.Is(err, sql.ErrNoRows) {
+				httputil.ErrorJSON(w, http.StatusBadRequest, "unknown doc_id")
+				return
+			}
+			if err != nil {
+				httputil.ServerError(w, err)
+				return
+			}
+		}
+	}
+
+	// New rows start due tomorrow; ON CONFLICT refreshes context but leaves the
+	// schedule (due_at/reps/interval/ease) alone so re-looking-up a word never
+	// resets its progress.
+	_, err := h.DB.Exec(
+		`INSERT INTO vocab_words (user_id, word, gloss, definition, phonetic, example, doc_id, due_at, interval_days)
+		 VALUES (?, ?, ?, ?, ?, ?, ?, datetime('now', '+1 day'), 1)
+		 ON CONFLICT(user_id, word) DO UPDATE SET
+		   gloss      = excluded.gloss,
+		   definition = excluded.definition,
+		   phonetic   = excluded.phonetic,
+		   example    = CASE WHEN excluded.example != '' THEN excluded.example ELSE vocab_words.example END,
+		   doc_id     = COALESCE(excluded.doc_id, vocab_words.doc_id)`,
+		db.LocalUserID, word, req.Gloss, req.Definition, req.Phonetic, req.Example, req.DocID,
+	)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+
+	out, err := h.fetch(word)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	httputil.WriteJSON(w, http.StatusCreated, out)
+}
+
+// fetch loads one word row by its (user, word) key.
+func (h *Handler) fetch(word string) (Word, error) {
+	return scanWord(h.DB.QueryRow(
+		`SELECT `+vocabColumns+` FROM vocab_words WHERE user_id = ? AND word = ?`,
+		db.LocalUserID, word,
+	))
+}
+
+type reviewRequest struct {
+	Grade Grade `json:"grade"`
+}
+
+// review grades one card and reschedules it. The grade drives the SM-2-lite
+// scheduler; the new interval is applied as `due_at = now + interval days`.
+func (h *Handler) review(w http.ResponseWriter, r *http.Request) {
+	id := chi.URLParam(r, "id")
+	var req reviewRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		httputil.ErrorJSON(w, http.StatusBadRequest, "invalid body")
+		return
+	}
+	if req.Grade != GradeAgain && req.Grade != GradeGood && req.Grade != GradeEasy {
+		httputil.ErrorJSON(w, http.StatusBadRequest, "grade must be again, good, or easy")
+		return
+	}
+
+	// The grade is computed in Go (the SM-2-lite scheduler), so the read and the
+	// write must be one atomic unit: a bare SELECT-then-UPDATE could interleave
+	// with a concurrent review of the same card and lose an update. Wrap both in a
+	// transaction.
+	tx, err := h.DB.Begin()
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	defer tx.Rollback() // no-op once committed
+
+	var cur State
+	err = tx.QueryRow(
+		`SELECT reps, interval_days, ease, lapses FROM vocab_words WHERE id = ? AND user_id = ?`,
+		id, db.LocalUserID,
+	).Scan(&cur.Reps, &cur.Interval, &cur.Ease, &cur.Lapses)
+	if errors.Is(err, sql.ErrNoRows) {
+		httputil.ErrorJSON(w, http.StatusNotFound, "word not found")
+		return
+	}
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+
+	nxt := cur.next(req.Grade)
+	// `datetime('now', '+N days')` keeps the stored value in SQLite's canonical
+	// text format, matching CURRENT_TIMESTAMP and the due query's comparison.
+	offset := "+" + strconv.Itoa(nxt.Interval) + " days"
+	if _, err := tx.Exec(
+		`UPDATE vocab_words SET
+		   reps = ?, interval_days = ?, ease = ?, lapses = ?,
+		   last_reviewed = datetime('now'), due_at = datetime('now', ?)
+		 WHERE id = ? AND user_id = ?`,
+		nxt.Reps, nxt.Interval, nxt.Ease, nxt.Lapses, offset, id, db.LocalUserID,
+	); err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+
+	out, err := scanWord(tx.QueryRow(
+		`SELECT `+vocabColumns+` FROM vocab_words WHERE id = ? AND user_id = ?`, id, db.LocalUserID,
+	))
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	if err := tx.Commit(); err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	httputil.WriteJSON(w, http.StatusOK, out)
+}
+
+// remove deletes a word from the garden (e.g. the writer already knows it).
+func (h *Handler) remove(w http.ResponseWriter, r *http.Request) {
+	res, err := h.DB.Exec(
+		`DELETE FROM vocab_words WHERE id = ? AND user_id = ?`,
+		chi.URLParam(r, "id"), db.LocalUserID,
+	)
+	if err != nil {
+		httputil.ServerError(w, err)
+		return
+	}
+	if n, _ := res.RowsAffected(); n == 0 {
+		httputil.ErrorJSON(w, http.StatusNotFound, "word not found")
+		return
+	}
+	w.WriteHeader(http.StatusNoContent)
+}

internal/vocab/handlers_test.go

@@ -0,0 +1,249 @@
+package vocab
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/go-chi/chi/v5"
+
+	"gitea.parodia.dev/drwily/petal/internal/db"
+)
+
+func newTestServer(t *testing.T) (http.Handler, *db.DB) {
+	t.Helper()
+	database, err := db.Open(filepath.Join(t.TempDir(), "test.db"))
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	t.Cleanup(func() { database.Close() })
+	r := chi.NewRouter()
+	r.Mount("/vocab", New(database).Routes())
+	return r, database
+}
+
+func do(t *testing.T, srv http.Handler, method, path, body string) *httptest.ResponseRecorder {
+	t.Helper()
+	var r *http.Request
+	if body != "" {
+		r = httptest.NewRequest(method, path, bytes.NewBufferString(body))
+	} else {
+		r = httptest.NewRequest(method, path, nil)
+	}
+	rec := httptest.NewRecorder()
+	srv.ServeHTTP(rec, r)
+	return rec
+}
+
+// TestCaptureUpsertAndReview walks the garden lifecycle: capture a word (lands
+// in the future, not yet due), re-capture refreshes context without resetting
+// schedule, a forced-due word shows up in /due, a review reschedules it, and
+// delete removes it.
+func TestCaptureUpsertAndReview(t *testing.T) {
+	srv, database := newTestServer(t)
+
+	// Capture a new word → 201, due tomorrow (interval 1), not in /due yet.
+	rec := do(t, srv, http.MethodPost, "/vocab",
+		`{"word":"serendipity","gloss":"机缘巧合","phonetic":"/ˌserənˈdɪpəti/","example":"What a serendipity."}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("capture: code=%d body=%s", rec.Code, rec.Body)
+	}
+	var w Word
+	_ = json.Unmarshal(rec.Body.Bytes(), &w)
+	if w.ID == "" || w.Word != "serendipity" || w.Gloss != "机缘巧合" {
+		t.Fatalf("captured word wrong: %+v", w)
+	}
+	if w.IntervalDays != 1 || w.Reps != 0 {
+		t.Fatalf("new word should start at interval 1, reps 0: %+v", w)
+	}
+
+	// Not due yet (due tomorrow).
+	rec = do(t, srv, http.MethodGet, "/vocab/due", "")
+	var due []Word
+	_ = json.Unmarshal(rec.Body.Bytes(), &due)
+	if len(due) != 0 {
+		t.Fatalf("freshly-captured word should not be due yet, got %d", len(due))
+	}
+
+	// Re-capture with a new gloss → still one row (idempotent upsert), refreshed.
+	rec = do(t, srv, http.MethodPost, "/vocab",
+		`{"word":"serendipity","gloss":"意外的好运","phonetic":"/x/","example":""}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("re-capture: code=%d body=%s", rec.Code, rec.Body)
+	}
+	rec = do(t, srv, http.MethodGet, "/vocab", "")
+	var all []Word
+	_ = json.Unmarshal(rec.Body.Bytes(), &all)
+	if len(all) != 1 {
+		t.Fatalf("re-capture should not add a row, got %d", len(all))
+	}
+	if all[0].Gloss != "意外的好运" {
+		t.Fatalf("gloss should refresh on re-capture, got %q", all[0].Gloss)
+	}
+	if all[0].Example != "What a serendipity." {
+		t.Fatalf("empty example should not clobber the prior one, got %q", all[0].Example)
+	}
+
+	// Force it due now, then it appears in /due.
+	if _, err := database.Exec(`UPDATE vocab_words SET due_at = datetime('now','-1 hour')`); err != nil {
+		t.Fatalf("force due: %v", err)
+	}
+	rec = do(t, srv, http.MethodGet, "/vocab/due", "")
+	_ = json.Unmarshal(rec.Body.Bytes(), &due)
+	if len(due) != 1 {
+		t.Fatalf("forced-due word should be in /due, got %d", len(due))
+	}
+
+	// Review "good" → reschedules forward (interval 3 = second ladder rung, since
+	// reps was 0 and a capture set interval 1 but reps 0; first good → rung 1 = 1).
+	rec = do(t, srv, http.MethodPost, "/vocab/"+w.ID+"/review", `{"grade":"good"}`)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("review: code=%d body=%s", rec.Code, rec.Body)
+	}
+	var reviewed Word
+	_ = json.Unmarshal(rec.Body.Bytes(), &reviewed)
+	if reviewed.Reps != 1 || reviewed.IntervalDays != 1 {
+		t.Fatalf("first good review should be reps 1, interval 1: %+v", reviewed)
+	}
+	if reviewed.LastReviewed == nil {
+		t.Fatalf("review should stamp last_reviewed")
+	}
+
+	// After a forward review it's no longer due.
+	rec = do(t, srv, http.MethodGet, "/vocab/due", "")
+	_ = json.Unmarshal(rec.Body.Bytes(), &due)
+	if len(due) != 0 {
+		t.Fatalf("reviewed word should leave /due, got %d", len(due))
+	}
+
+	// Bad grade → 400.
+	if rec = do(t, srv, http.MethodPost, "/vocab/"+w.ID+"/review", `{"grade":"nope"}`); rec.Code != http.StatusBadRequest {
+		t.Fatalf("bad grade: want 400, got %d", rec.Code)
+	}
+
+	// Delete → 204, garden empty.
+	if rec = do(t, srv, http.MethodDelete, "/vocab/"+w.ID, ""); rec.Code != http.StatusNoContent {
+		t.Fatalf("delete: code=%d", rec.Code)
+	}
+	if rec = do(t, srv, http.MethodDelete, "/vocab/"+w.ID, ""); rec.Code != http.StatusNotFound {
+		t.Fatalf("re-delete: want 404, got %d", rec.Code)
+	}
+}
+
+// TestCaptureValidation rejects an empty word.
+func TestCaptureValidation(t *testing.T) {
+	srv, _ := newTestServer(t)
+	if rec := do(t, srv, http.MethodPost, "/vocab", `{"word":"   "}`); rec.Code != http.StatusBadRequest {
+		t.Fatalf("empty word: want 400, got %d", rec.Code)
+	}
+}
+
+// TestCaptureStoresDefinitionFallback proves a word with an English definition
+// but no Chinese gloss still round-trips its definition, so review has a meaning
+// to reveal instead of a blank card.
+func TestCaptureStoresDefinitionFallback(t *testing.T) {
+	srv, _ := newTestServer(t)
+	rec := do(t, srv, http.MethodPost, "/vocab",
+		`{"word":"ineffable","definition":"too great to be expressed in words"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("capture: code=%d body=%s", rec.Code, rec.Body)
+	}
+	var w Word
+	_ = json.Unmarshal(rec.Body.Bytes(), &w)
+	if w.Gloss != "" {
+		t.Fatalf("expected no gloss, got %q", w.Gloss)
+	}
+	if w.Definition != "too great to be expressed in words" {
+		t.Fatalf("definition not stored, got %q", w.Definition)
+	}
+}
+
+// TestCaptureCaseInsensitive proves "Apple" (sentence start) and "apple"
+// (mid-line) land in the SAME garden card — capture normalizes to lower+trim
+// like the lexicon, so the idempotent upsert isn't defeated by casing.
+func TestCaptureCaseInsensitive(t *testing.T) {
+	srv, _ := newTestServer(t)
+	if rec := do(t, srv, http.MethodPost, "/vocab", `{"word":"Apple","gloss":"苹果"}`); rec.Code != http.StatusCreated {
+		t.Fatalf("capture Apple: code=%d body=%s", rec.Code, rec.Body)
+	}
+	if rec := do(t, srv, http.MethodPost, "/vocab", `{"word":"  apple ","gloss":"苹果"}`); rec.Code != http.StatusCreated {
+		t.Fatalf("capture apple: code=%d body=%s", rec.Code, rec.Body)
+	}
+	rec := do(t, srv, http.MethodGet, "/vocab", "")
+	var all []Word
+	_ = json.Unmarshal(rec.Body.Bytes(), &all)
+	if len(all) != 1 {
+		t.Fatalf("Apple/apple should be one card, got %d", len(all))
+	}
+	if all[0].Word != "apple" {
+		t.Fatalf("word should be normalized to lowercase, got %q", all[0].Word)
+	}
+}
+
+// TestCaptureUnknownDocID rejects an unowned/stale doc_id with a clean 400
+// rather than letting it hit the foreign key and leak a raw 500.
+func TestCaptureUnknownDocID(t *testing.T) {
+	srv, _ := newTestServer(t)
+	rec := do(t, srv, http.MethodPost, "/vocab",
+		`{"word":"quixotic","gloss":"不切实际的","doc_id":"does-not-exist"}`)
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("unknown doc_id: want 400, got %d body=%s", rec.Code, rec.Body)
+	}
+	// A blank doc_id is treated as none, not an error.
+	if rec := do(t, srv, http.MethodPost, "/vocab", `{"word":"limpid","gloss":"清澈的","doc_id":""}`); rec.Code != http.StatusCreated {
+		t.Fatalf("blank doc_id should be accepted as none: code=%d body=%s", rec.Code, rec.Body)
+	}
+}
+
+// TestCaptureClampsLongFields proves over-long fields are clamped (not rejected)
+// so a lookup never fails on length, and the word key stays bounded.
+func TestCaptureClampsLongFields(t *testing.T) {
+	srv, _ := newTestServer(t)
+	longWord := strings.Repeat("a", maxWordLen+50)
+	longDef := strings.Repeat("x", maxDefinitionLen+50)
+	rec := do(t, srv, http.MethodPost, "/vocab",
+		`{"word":"`+longWord+`","definition":"`+longDef+`"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("capture: code=%d body=%s", rec.Code, rec.Body)
+	}
+	var w Word
+	_ = json.Unmarshal(rec.Body.Bytes(), &w)
+	if len([]rune(w.Word)) != maxWordLen {
+		t.Fatalf("word should clamp to %d runes, got %d", maxWordLen, len([]rune(w.Word)))
+	}
+	if len([]rune(w.Definition)) != maxDefinitionLen {
+		t.Fatalf("definition should clamp to %d runes, got %d", maxDefinitionLen, len([]rune(w.Definition)))
+	}
+}
+
+// TestDocLinkSurvivesDocDelete proves the ON DELETE SET NULL keeps a word in the
+// garden when its source document is removed.
+func TestDocLinkSurvivesDocDelete(t *testing.T) {
+	srv, database := newTestServer(t)
+	var docID string
+	if err := database.QueryRow(
+		`INSERT INTO documents (user_id, content_text) VALUES (?, 'hi') RETURNING id`, db.LocalUserID,
+	).Scan(&docID); err != nil {
+		t.Fatalf("seed doc: %v", err)
+	}
+	rec := do(t, srv, http.MethodPost, "/vocab", `{"word":"ephemeral","gloss":"短暂的","doc_id":"`+docID+`"}`)
+	if rec.Code != http.StatusCreated {
+		t.Fatalf("capture: code=%d body=%s", rec.Code, rec.Body)
+	}
+	if _, err := database.Exec(`DELETE FROM documents WHERE id = ?`, docID); err != nil {
+		t.Fatalf("delete doc: %v", err)
+	}
+	rec = do(t, srv, http.MethodGet, "/vocab", "")
+	var all []Word
+	_ = json.Unmarshal(rec.Body.Bytes(), &all)
+	if len(all) != 1 {
+		t.Fatalf("word should survive doc deletion, got %d", len(all))
+	}
+	if all[0].DocID != nil {
+		t.Fatalf("doc_id should be nulled after doc delete, got %v", *all[0].DocID)
+	}
+}

internal/vocab/scheduler.go

@@ -0,0 +1,114 @@
+// Package vocab implements the vocabulary garden: it captures words the writer
+// looks up and schedules them for gentle spaced-repetition review. The scheduler
+// is a deliberately forgiving SM-2-lite / Leitner hybrid — no streaks to break,
+// no harsh resets beyond a single step back — because this is a confidence
+// builder, not a drill sergeant.
+package vocab
+
+import "math"
+
+// Grade is the writer's self-assessment after seeing a flashcard's answer.
+type Grade string
+
+const (
+	GradeAgain Grade = "again" // didn't recall it — show again soon
+	GradeGood  Grade = "good"  // recalled it — advance one rung
+	GradeEasy  Grade = "easy"  // knew it instantly — advance a little further
+)
+
+// ladder is the Leitner interval ladder in days for the first several successful
+// reviews: 1 → 3 → 7 → 16 → 35. Beyond the ladder, intervals grow by the card's
+// ease factor so well-known words drift far into the future.
+var ladder = []int{1, 3, 7, 16, 35}
+
+const (
+	minEase        = 1.3
+	maxEase        = 3.0  // ease ceiling — keeps "easy" from compounding growth without bound
+	startEase      = 2.5
+	easyBonus      = 1.3   // multiplier applied on top of a "good" step for "easy"
+	easeAgainDelta = -0.20 // ease nudged down on a lapse (still floored at minEase)
+	easeEasyDelta  = 0.15  // ease nudged up when a card feels easy
+
+	// maxInterval caps how far a card can drift into the future. Even a word
+	// graded "easy" many times resurfaces about once a year, so nothing silently
+	// leaves the garden forever (the whole point is to keep words in gentle
+	// rotation, not to retire them).
+	maxInterval = 365
+)
+
+// State is the spaced-repetition state of one card. It mirrors the scheduling
+// columns on vocab_words so a review is "load State → next(grade) → persist".
+type State struct {
+	Reps     int
+	Interval int // days until the next review
+	Ease     float64
+	Lapses   int
+}
+
+// next returns the card's state after a review with the given grade. It never
+// mutates the receiver. "again" steps the card back to a 1-day interval and
+// counts a lapse (but only nudges ease down, never wipes progress harshly);
+// "good" advances one rung of the ladder; "easy" advances a rung and a bit more.
+func (s State) next(grade Grade) State {
+	ease := s.Ease
+	if ease == 0 {
+		ease = startEase
+	}
+
+	switch grade {
+	case GradeAgain:
+		return State{
+			Reps:     0,
+			Interval: 1,
+			Ease:     clampEase(ease + easeAgainDelta),
+			Lapses:   s.Lapses + 1,
+		}
+	case GradeEasy:
+		ease = clampEase(ease + easeEasyDelta)
+		reps := s.Reps + 1
+		return State{
+			Reps:     reps,
+			Interval: clampInterval(int(math.Round(float64(goodInterval(reps, s.Interval, ease)) * easyBonus))),
+			Ease:     ease,
+			Lapses:   s.Lapses,
+		}
+	default: // GradeGood
+		reps := s.Reps + 1
+		return State{
+			Reps:     reps,
+			Interval: clampInterval(goodInterval(reps, s.Interval, ease)),
+			Ease:     ease,
+			Lapses:   s.Lapses,
+		}
+	}
+}
+
+// goodInterval returns the day-interval for a successful review: the explicit
+// ladder while it lasts, then geometric growth by ease once past it.
+func goodInterval(reps, prevInterval int, ease float64) int {
+	if reps >= 1 && reps <= len(ladder) {
+		return ladder[reps-1]
+	}
+	prev := prevInterval
+	if prev < ladder[len(ladder)-1] {
+		prev = ladder[len(ladder)-1]
+	}
+	return int(math.Round(float64(prev) * ease))
+}
+
+func clampEase(e float64) float64 {
+	if e < minEase {
+		return minEase
+	}
+	if e > maxEase {
+		return maxEase
+	}
+	return e
+}
+
+func clampInterval(d int) int {
+	if d > maxInterval {
+		return maxInterval
+	}
+	return d
+}

internal/vocab/scheduler_test.go

@@ -0,0 +1,88 @@
+package vocab
+
+import "testing"
+
+// TestLadderProgression walks a card up the Leitner ladder on repeated "good"
+// reviews: 1 → 3 → 7 → 16 → 35 days, then geometric growth by ease.
+func TestLadderProgression(t *testing.T) {
+	s := State{Ease: startEase}
+	want := []int{1, 3, 7, 16, 35}
+	for i, w := range want {
+		s = s.next(GradeGood)
+		if s.Interval != w {
+			t.Fatalf("rung %d: interval=%d, want %d", i, s.Interval, w)
+		}
+		if s.Reps != i+1 {
+			t.Fatalf("rung %d: reps=%d, want %d", i, s.Reps, i+1)
+		}
+	}
+	// Past the ladder it grows by ease (35 * 2.5 = 87.5 → 88).
+	s = s.next(GradeGood)
+	if s.Interval != 88 {
+		t.Fatalf("post-ladder interval=%d, want 88", s.Interval)
+	}
+}
+
+// TestAgainStepsBackGently proves a lapse resets to a 1-day interval and counts
+// a lapse, but only nudges ease down (never below the floor) — no harsh wipe.
+func TestAgainStepsBackGently(t *testing.T) {
+	s := State{Reps: 4, Interval: 35, Ease: startEase}
+	s = s.next(GradeAgain)
+	if s.Interval != 1 {
+		t.Fatalf("again interval=%d, want 1", s.Interval)
+	}
+	if s.Reps != 0 {
+		t.Fatalf("again reps=%d, want 0", s.Reps)
+	}
+	if s.Lapses != 1 {
+		t.Fatalf("again lapses=%d, want 1", s.Lapses)
+	}
+	if s.Ease != startEase+easeAgainDelta {
+		t.Fatalf("again ease=%v, want %v", s.Ease, startEase+easeAgainDelta)
+	}
+
+	// Ease never drops below the floor no matter how many lapses.
+	low := State{Ease: minEase}
+	for i := 0; i < 5; i++ {
+		low = low.next(GradeAgain)
+	}
+	if low.Ease < minEase {
+		t.Fatalf("ease fell below floor: %v", low.Ease)
+	}
+}
+
+// TestCapsBoundGrowth proves runaway "easy" grading can't push ease or the
+// interval past their ceilings, so a word always resurfaces within a year.
+func TestCapsBoundGrowth(t *testing.T) {
+	s := State{Ease: startEase}
+	for i := 0; i < 40; i++ {
+		s = s.next(GradeEasy)
+		if s.Ease > maxEase {
+			t.Fatalf("step %d: ease %v exceeded cap %v", i, s.Ease, maxEase)
+		}
+		if s.Interval > maxInterval {
+			t.Fatalf("step %d: interval %d exceeded cap %d", i, s.Interval, maxInterval)
+		}
+	}
+	// After enough "easy" reviews it should be pinned at the ceilings.
+	if s.Interval != maxInterval {
+		t.Fatalf("interval should saturate at %d, got %d", maxInterval, s.Interval)
+	}
+	if s.Ease != maxEase {
+		t.Fatalf("ease should saturate at %v, got %v", maxEase, s.Ease)
+	}
+}
+
+// TestEasyAdvancesFurther proves "easy" both bumps ease and lands a longer
+// interval than a plain "good" at the same rung.
+func TestEasyAdvancesFurther(t *testing.T) {
+	base := State{Reps: 2, Interval: 7, Ease: startEase}
+	good := base.next(GradeGood)
+	easy := base.next(GradeEasy)
+	if easy.Interval <= good.Interval {
+		t.Fatalf("easy interval %d should exceed good interval %d", easy.Interval, good.Interval)
+	}
+	if easy.Ease <= startEase {
+		t.Fatalf("easy should raise ease, got %v", easy.Ease)
+	}
+}

web/src/App.tsx

@@ -9,6 +9,7 @@ import { EditorCore, type EditorChange } from './components/Editor/EditorCore'
 import { ToneSelect } from './components/Editor/ToneSelect'
 import { ExportMenu } from './components/Export/ExportMenu'
 import { HistoryPanel } from './components/History/HistoryPanel'
+import { GardenPanel } from './components/Garden/GardenPanel'
 import { StatusBar } from './components/StatusBar/StatusBar'
 import { PetalCompanion } from './components/Companion/PetalCompanion'
 import { UpdateBanner } from './components/UpdateBanner/UpdateBanner'
@@ -46,6 +47,7 @@ export default function App() {
   // editor to remount with the restored content (its initialContent is read
   // only on mount).
   const [historyOpen, setHistoryOpen] = useState(false)
+  const [gardenOpen, setGardenOpen] = useState(false)
   const [editorEpoch, setEditorEpoch] = useState(0)
 
   // Live mirrors of the current doc's editable fields so the "discard blank
@@ -70,9 +72,11 @@ export default function App() {
     suggestions,
     checking,
     voicing,
+    collocating,
     llmDown,
     schedule: scheduleCheckpoint,
     runVoice,
+    runCollocation,
     removeSuggestion,
   } = useCheckpoint(currentDoc?.id ?? null)
   // Browser-side spell checker — loads the en-US dictionary once per session.
@@ -395,6 +399,23 @@ export default function App() {
         </button>
         <span className="text-xl">🌸</span>
         <span className="text-lg font-extrabold text-plum">Petal</span>
+        <button
+          type="button"
+          onClick={() => setGardenOpen(true)}
+          aria-label="Vocabulary garden"
+          title="Words you've looked up, blooming for review"
+          className="petal-tap-sm ml-auto inline-flex h-9 items-center gap-1.5 whitespace-nowrap px-3 text-sm font-bold"
+          style={{
+            borderRadius: 'var(--radius-pill)',
+            background: 'var(--color-surface)',
+            color: 'var(--color-plum)',
+            boxShadow: 'var(--shadow-soft)',
+          }}
+        >
+          <span aria-hidden>🌷</span>
+          <span>词汇花园</span>
+          <span style={{ color: 'var(--color-muted)' }}>· Garden</span>
+        </button>
       </header>
 
       <div className="relative flex min-h-0 flex-1">
@@ -471,6 +492,8 @@ export default function App() {
                     onDismiss={handleDismiss}
                     onVoiceCheck={runVoice}
                     voicing={voicing}
+                    onCollocationCheck={runCollocation}
+                    collocating={collocating}
                     onFocusMode={() => setFocusMode(true)}
                     spellChecker={spellChecker}
                     onAddWord={addWord}
@@ -484,6 +507,7 @@ export default function App() {
                   saveStatus={status}
                   checking={checking}
                   voicing={voicing}
+                  collocating={collocating}
                   llmDown={llmDown}
                 />
               </div>
@@ -507,6 +531,16 @@ export default function App() {
         />
       )}
 
+      {gardenOpen && (
+        <GardenPanel
+          onClose={() => setGardenOpen(false)}
+          onOpenDoc={(id) => {
+            setGardenOpen(false)
+            void openDoc(id)
+          }}
+        />
+      )}
+
       {updateAvailable && <UpdateBanner />}
 
       <div className="petal-no-print">

web/src/api/client.ts

@@ -76,7 +76,30 @@ export interface Gloss {
   gloss: string
 }
 
-export type SuggestionType = 'grammar' | 'phrasing' | 'idiom' | 'clarity' | 'voice'
+export type SuggestionType = 'grammar' | 'phrasing' | 'idiom' | 'clarity' | 'voice' | 'collocation'
+
+// One word in the vocabulary garden: a looked-up word with its gloss/phonetic,
+// the sentence it was met in, and its spaced-repetition state. `reps` drives how
+// "bloomed" its blossom looks; `due_at` decides when it next surfaces for review.
+export interface VocabWord {
+  id: string
+  word: string
+  gloss: string
+  definition: string // English fallback meaning shown in review when there's no gloss
+  phonetic: string
+  example: string
+  doc_id: string | null
+  due_at: string
+  interval_days: number
+  ease: number
+  reps: number
+  lapses: number
+  last_reviewed: string | null
+  created_at: string
+}
+
+// The self-assessment grades a flashcard review can record.
+export type VocabGrade = 'again' | 'good' | 'easy'
 
 // A point-in-time snapshot of a document. List responses omit the heavy
 // content/content_text fields; they arrive only on getVersion (preview/restore).
@@ -141,6 +164,10 @@ export const api = {
   // Voice-consistency pass: whole-document, explicit-action, slower. Returns the
   // unified pending set too. Rate-limited per document server-side.
   voiceDoc: (id: string) => req<Suggestion[]>(`/docs/${id}/voice`, { method: 'POST' }),
+  // Collocation coach: whole-document, explicit-action pass flagging non-native
+  // word pairings ("do a decision" → "make a decision"). Returns the unified
+  // pending set too. Rate-limited per document server-side.
+  collocationDoc: (id: string) => req<Suggestion[]>(`/docs/${id}/collocation`, { method: 'POST' }),
   // Pending suggestions for a doc, loaded when the editor opens it.
   listSuggestions: (id: string) => req<Suggestion[]>(`/docs/${id}/suggestions`),
   acceptSuggestion: (id: string) =>
@@ -221,6 +248,24 @@ export const api = {
   unassignTag: (docId: string, tagId: string) =>
     req<void>(`/docs/${docId}/tags/${tagId}`, { method: 'DELETE' }),
 
+  // Vocabulary garden. recordVocab captures (or refreshes) a looked-up word —
+  // idempotent per word, fired automatically on lookup. listVocab is the whole
+  // garden; dueVocab is just the cards ready for review; reviewVocab grades one
+  // card and returns its rescheduled state; deleteVocab removes a word.
+  recordVocab: (body: {
+    word: string
+    gloss?: string
+    definition?: string
+    phonetic?: string
+    example?: string
+    doc_id?: string | null
+  }) => req<VocabWord>('/vocab', { method: 'POST', body: JSON.stringify(body) }),
+  listVocab: () => req<VocabWord[]>('/vocab'),
+  dueVocab: () => req<VocabWord[]>('/vocab/due'),
+  reviewVocab: (id: string, grade: VocabGrade) =>
+    req<VocabWord>(`/vocab/${id}/review`, { method: 'POST', body: JSON.stringify({ grade }) }),
+  deleteVocab: (id: string) => req<void>(`/vocab/${id}`, { method: 'DELETE' }),
+
   // Current deployed build id — changes whenever a new frontend ships. The
   // app polls this to offer a refresh. Bypasses any cache so the answer is live.
   version: () => req<{ version: string }>('/version', { cache: 'no-store' }),

web/src/audio/speech.ts

@@ -28,7 +28,12 @@ let current: { audio: HTMLAudioElement; url: string } | null = null
 // a newer tap can detect it's stale and bow out instead of double-playing.
 let requestSeq = 0
 
-function stopCurrent(): void {
+// stopSpeech halts any read-aloud in flight — both the server-audio element and
+// the Web Speech fallback — and bumps requestSeq so a fetch still in flight bows
+// out instead of playing late. Exported so a panel can cancel audio on unmount,
+// keeping a word's pronunciation from outliving the panel that started it.
+export function stopSpeech(): void {
+  requestSeq++
   if (current) {
     current.audio.pause()
     URL.revokeObjectURL(current.url)
@@ -77,7 +82,7 @@ export function detectLang(text: string): string {
 // with no configured voice).
 export function speak(text: string, lang = detectLang(text)): void {
   if (!text.trim()) return
-  stopCurrent()
+  stopSpeech()
   const seq = ++requestSeq
 
   fetch('/api/tts', {

web/src/components/Editor/EditorCore.tsx

@@ -53,6 +53,10 @@ interface Props {
   // it runs (drives the toolbar button's loading state).
   onVoiceCheck: () => void
   voicing: boolean
+  // Triggers the whole-document collocation coach; `collocating` is true while it
+  // runs (drives the toolbar button's loading state).
+  onCollocationCheck: () => void
+  collocating: boolean
   // Fired when the editor gains focus, so the app can enter distraction-free mode.
   onFocusMode?: () => void
   // Browser-side spell checker (null until the dictionary loads). Adding a word
@@ -81,6 +85,33 @@ interface WordInfoState {
   left: number
   loading: boolean
   info: WordInfo | null
+  // Garden state: the captured word's id (null until the auto-capture returns or
+  // after it's removed) and whether it's currently in the garden.
+  vocabId: string | null
+  saved: boolean
+}
+
+// sentenceAround pulls the sentence containing `word` out of a block of text, so
+// a captured vocab word carries the context it was met in. Falls back to the
+// whole (trimmed, length-capped) text when no sentence boundary is found.
+function sentenceAround(text: string, wordStart: number): string {
+  const stops = /[.!?。！？\n]/
+  let start = 0
+  for (let i = wordStart - 1; i >= 0; i--) {
+    if (stops.test(text[i])) {
+      start = i + 1
+      break
+    }
+  }
+  let end = text.length
+  for (let i = wordStart; i < text.length; i++) {
+    if (stops.test(text[i])) {
+      end = i + 1
+      break
+    }
+  }
+  const s = text.slice(start, end).trim()
+  return s.length > 240 ? s.slice(0, 240).trim() + '…' : s
 }
 
 // A tiny CSS-only confetti burst played at an accept. Four palette-colored dots
@@ -185,6 +216,8 @@ export function EditorCore({
   onDismiss,
   onVoiceCheck,
   voicing,
+  onCollocationCheck,
+  collocating,
   onFocusMode,
   spellChecker,
   onAddWord,
@@ -607,6 +640,20 @@ export function EditorCore({
     setMisspell(null)
   }, [misspell, onAddWord])
 
+  // exampleAt pulls the sentence containing the position out of its block, for
+  // review context in the garden. textBetween with a single-char leaf/break
+  // placeholder keeps the string indices aligned with ProseMirror's parentOffset
+  // (so a hard break or inline atom before the word doesn't desync the slice).
+  const exampleAt = useCallback(
+    (pos: number): string => {
+      if (!editor) return ''
+      const $pos = editor.state.doc.resolve(pos)
+      const text = $pos.parent.textBetween(0, $pos.parent.content.size, '\n', ' ')
+      return sentenceAround(text, Math.max(0, $pos.parentOffset))
+    },
+    [editor],
+  )
+
   // openWordLookup resolves the exact word span at a document position, anchors a
   // popover beneath it, and kicks off the offline lookup. The card opens
   // immediately in a loading state and fills in when the (local) lookup returns.
@@ -630,13 +677,40 @@ export function EditorCore({
       closeCard()
       setMisspell(null)
       const token = ++wordReqRef.current
-      setWordInfo({ word: range.word, from: range.from, to: range.to, top, left, loading: true, info: null })
+      setWordInfo({ word: range.word, from: range.from, to: range.to, top, left, loading: true, info: null, vocabId: null, saved: false })
+      // The sentence the word sits in, for review context in the garden.
+      const example = exampleAt(range.from)
       api
         .lookupWord(range.word)
         .then((info) => {
-          if (token === wordReqRef.current) {
-            setWordInfo((w) => (w ? { ...w, loading: false, info } : null))
-          }
+          if (token !== wordReqRef.current) return
+          // Auto-capture into the vocabulary garden — only words the dictionary
+          // actually knows (a real gloss or definition), so accidental lookups of
+          // typos or proper nouns don't clutter the garden. Looking words up IS
+          // the data source; this costs the writer nothing.
+          const known = !!info.gloss || info.definitions.length > 0
+          // Reflect the saved state optimistically so the heart shows 💚 the
+          // moment a known word loads, rather than flashing 🤍 until the capture
+          // round-trips. vocabId is filled in when recordVocab returns.
+          setWordInfo((w) => (w ? { ...w, loading: false, info, saved: known } : null))
+          if (!known) return
+          api
+            .recordVocab({
+              word: range.word,
+              gloss: info.gloss,
+              definition: info.definitions[0]?.definition ?? '',
+              phonetic: info.phonetic,
+              example,
+              doc_id: docId,
+            })
+            .then((row) => {
+              // Discard a late capture if the card has since been superseded (a
+              // new lookup, navigation, or an explicit remove all bump the token),
+              // so it can't resurrect a word the writer just removed.
+              if (token !== wordReqRef.current) return
+              setWordInfo((w) => (w && w.word === range.word ? { ...w, vocabId: row.id, saved: true } : w))
+            })
+            .catch((err) => console.error('vocab capture failed', err))
         })
         .catch((err) => {
           console.error('word lookup failed', err)
@@ -645,9 +719,44 @@ export function EditorCore({
           }
         })
     },
-    [editor, closeCard],
+    [editor, closeCard, docId],
   )
 
+  // Toggle a looked-up word in/out of the vocabulary garden from the WordCard
+  // heart. Auto-capture saves it on lookup; this lets the writer remove a word
+  // she already knows (or re-add one she removed by mistake).
+  const toggleSaveWord = useCallback(() => {
+    // Read the current card and do the network side effects OUTSIDE the state
+    // updater — an updater must be pure (React StrictMode double-invokes it,
+    // which would otherwise fire each request twice).
+    const w = wordInfo
+    if (!w || !w.info) return
+    if (w.vocabId) {
+      // Already in the garden — remove it, and invalidate any in-flight capture
+      // for this card so a late auto-capture can't resurrect the removed word.
+      const id = w.vocabId
+      wordReqRef.current++
+      setWordInfo((cur) => (cur ? { ...cur, saved: false, vocabId: null } : cur))
+      api.deleteVocab(id).catch((err) => console.error('vocab remove failed', err))
+      return
+    }
+    // Not in the garden yet — save it (idempotent upsert keyed on the word).
+    const word = w.word
+    const example = exampleAt(w.from)
+    setWordInfo((cur) => (cur ? { ...cur, saved: true } : cur))
+    api
+      .recordVocab({
+        word,
+        gloss: w.info.gloss,
+        definition: w.info.definitions[0]?.definition ?? '',
+        phonetic: w.info.phonetic,
+        example,
+        doc_id: docId,
+      })
+      .then((row) => setWordInfo((cur) => (cur && cur.word === word ? { ...cur, vocabId: row.id, saved: true } : cur)))
+      .catch((err) => console.error('vocab save failed', err))
+  }, [wordInfo, exampleAt, docId])
+
   // Right-click a word to look it up. Right-clicking off any word falls through
   // to the native menu (so copy/paste-by-menu still works — see the Selection fix).
   const handleContextMenu = useCallback(
@@ -926,7 +1035,13 @@ export function EditorCore({
 
   return (
     <div className="flex flex-1 flex-col">
-      <Toolbar editor={editor} onVoiceCheck={onVoiceCheck} voicing={voicing} />
+      <Toolbar
+        editor={editor}
+        onVoiceCheck={onVoiceCheck}
+        voicing={voicing}
+        onCollocationCheck={onCollocationCheck}
+        collocating={collocating}
+      />
       <div
         ref={wrapperRef}
         className="relative flex-1"
@@ -969,6 +1084,8 @@ export function EditorCore({
             word={wordInfo.word}
             info={wordInfo.info}
             loading={wordInfo.loading}
+            saved={wordInfo.saved}
+            onToggleSave={toggleSaveWord}
             style={{ top: wordInfo.top, left: wordInfo.left }}
             onReplace={replaceWord}
           />

web/src/components/Editor/WordCard.tsx

@@ -11,11 +11,15 @@ interface Props {
   word: string
   info: WordInfo | null
   loading: boolean
+  // Whether the word is in the vocabulary garden (auto-saved on lookup). The
+  // heart toggles it; `onToggleSave` removes/re-adds it.
+  saved: boolean
+  onToggleSave: () => void
   style: React.CSSProperties
   onReplace: (synonym: string) => void
 }
 
-export function WordCard({ word, info, loading, style, onReplace }: Props) {
+export function WordCard({ word, info, loading, saved, onToggleSave, style, onReplace }: Props) {
   const definitions = info?.definitions ?? []
   const synonyms = info?.synonyms ?? []
   const gloss = info?.gloss ?? ''
@@ -48,18 +52,35 @@ export function WordCard({ word, info, loading, style, onReplace }: Props) {
         <span className="font-bold" style={{ color: 'var(--color-plum)' }}>
           {word}
         </span>
-        {speechSupported() && (
-          <button
-            type="button"
-            onClick={() => speak(word)}
-            aria-label={`Pronounce ${word}`}
-            title="朗读 · Read aloud"
-            className="ml-auto flex h-7 w-7 items-center justify-center rounded-full text-sm"
-            style={{ background: 'var(--color-surface-alt)', color: 'var(--color-plum)' }}
-          >
-            🔊
-          </button>
-        )}
+        <div className="ml-auto flex items-center gap-1.5">
+          {!empty && !loading && (
+            <button
+              type="button"
+              onClick={onToggleSave}
+              aria-label={saved ? 'Remove from vocabulary garden' : 'Save to vocabulary garden'}
+              aria-pressed={saved}
+              title={saved ? '已在词汇花园 · In your garden (tap to remove)' : '加入词汇花园 · Save to garden'}
+              className="flex h-7 w-7 items-center justify-center rounded-full text-sm transition-transform"
+              style={{
+                background: saved ? 'var(--color-accent)' : 'var(--color-surface-alt)',
+              }}
+            >
+              {saved ? '💚' : '🤍'}
+            </button>
+          )}
+          {speechSupported() && (
+            <button
+              type="button"
+              onClick={() => speak(word)}
+              aria-label={`Pronounce ${word}`}
+              title="朗读 · Read aloud"
+              className="flex h-7 w-7 items-center justify-center rounded-full text-sm"
+              style={{ background: 'var(--color-surface-alt)', color: 'var(--color-plum)' }}
+            >
+              🔊
+            </button>
+          )}
+        </div>
       </div>
 
       {/* How to say it — the pronunciation aid for an English learner, paired

web/src/components/Editor/suggestionMeta.ts

@@ -9,4 +9,5 @@ export const TYPE_META: Record<SuggestionType, { color: string; label: string }>
   idiom: { color: 'var(--color-lavender)', label: 'Idiom' },
   clarity: { color: 'var(--color-sky)', label: 'Clarity' },
   voice: { color: 'var(--color-honey)', label: 'Voice' },
+  collocation: { color: 'var(--color-blossom)', label: 'Word pairing' },
 }

web/src/components/Garden/GardenPanel.tsx

@@ -0,0 +1,521 @@
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { api, type VocabGrade, type VocabWord } from '../../api/client'
+import { speak, speechSupported, stopSpeech } from '../../audio/speech'
+import { useFocusTrap } from '../../hooks/useFocusTrap'
+
+// GardenPanel is the vocabulary garden: every word the writer has looked up,
+// grown into a blossom that opens further the more she remembers it, plus a
+// gentle spaced-repetition review. Words are captured automatically on lookup
+// (zero effort), so the garden fills itself as she writes. The sleepy kitten
+// naps among the blossoms — the same companion gag, at rest in her little
+// meadow. Bilingual, zh-first, to match Petal's chrome.
+
+interface Props {
+  onClose: () => void
+  // Open the document a word was met in (so "where did I see this?" is one tap).
+  onOpenDoc?: (docId: string) => void
+}
+
+// blossom maps a word's successful-review count to how bloomed its flower looks:
+// a fresh seedling opens into a full blossom as it's remembered. No wilting — a
+// forgotten word just stops climbing, never shames.
+function blossom(reps: number): string {
+  if (reps <= 0) return '🌱'
+  if (reps <= 2) return '🌿'
+  if (reps <= 4) return '🌷'
+  if (reps <= 6) return '🌸'
+  return '🌺'
+}
+
+// blankOut hides the target word in its example sentence with a soft blank, so a
+// flashcard can quiz recall in context. Whole-word, case-insensitive.
+function blankOut(sentence: string, word: string): string {
+  if (!sentence) return ''
+  try {
+    const re = new RegExp(`\\b${word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'gi')
+    return sentence.replace(re, '____')
+  } catch {
+    return sentence
+  }
+}
+
+export function GardenPanel({ onClose, onOpenDoc }: Props) {
+  const [words, setWords] = useState<VocabWord[] | null>(null)
+  const [due, setDue] = useState<VocabWord[]>([])
+  const [error, setError] = useState(false)
+  // Review session state: the queue (snapshot of due at start), a cursor, and
+  // whether the current card's answer is revealed.
+  const [queue, setQueue] = useState<VocabWord[] | null>(null)
+  const [cursor, setCursor] = useState(0)
+  const [revealed, setRevealed] = useState(false)
+  const [expanded, setExpanded] = useState<string | null>(null)
+  const panelRef = useFocusTrap<HTMLElement>()
+
+  // Read-aloud is fire-and-forget, so a word she tapped could still be speaking
+  // when the panel closes. Cancel any in-flight audio on unmount so it can't
+  // outlive the garden.
+  useEffect(() => stopSpeech, [])
+
+  const load = useCallback(async () => {
+    setError(false)
+    // Settle the two requests independently: a failed /due shouldn't blank the
+    // whole garden when the word list loaded fine. Only listVocab failing is a
+    // true error state; a dueVocab failure just hides the review button.
+    const [allRes, dueRes] = await Promise.allSettled([api.listVocab(), api.dueVocab()])
+    if (allRes.status === 'fulfilled') setWords(allRes.value)
+    else setError(true)
+    if (dueRes.status === 'fulfilled') setDue(dueRes.value)
+    else setDue([])
+  }, [])
+
+  useEffect(() => {
+    void load()
+  }, [load])
+
+  // Escape closes the panel (or ends a review session back to the garden).
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        if (queue) setQueue(null)
+        else onClose()
+      }
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [onClose, queue])
+
+  const startReview = useCallback(() => {
+    if (due.length === 0) return
+    setQueue(due)
+    setCursor(0)
+    setRevealed(false)
+  }, [due])
+
+  const grade = useCallback(
+    async (g: VocabGrade) => {
+      if (!queue) return
+      const card = queue[cursor]
+      if (card) {
+        try {
+          await api.reviewVocab(card.id, g)
+        } catch {
+          /* keep going — a failed grade just won't reschedule */
+        }
+      }
+      const nextCursor = cursor + 1
+      if (nextCursor >= queue.length) {
+        // Session done — refresh the garden and drop back to it.
+        setQueue(null)
+        void load()
+      } else {
+        setCursor(nextCursor)
+        setRevealed(false)
+      }
+    },
+    [queue, cursor, load],
+  )
+
+  const removeWord = useCallback(async (id: string) => {
+    setWords((prev) => (prev ? prev.filter((w) => w.id !== id) : prev))
+    setDue((prev) => prev.filter((w) => w.id !== id))
+    try {
+      await api.deleteVocab(id)
+    } catch {
+      void load()
+    }
+  }, [load])
+
+  return (
+    <div className="petal-no-print fixed inset-0 z-40 flex justify-end">
+      <div
+        className="absolute inset-0"
+        style={{ background: 'rgba(61, 46, 57, 0.18)' }}
+        onClick={() => (queue ? setQueue(null) : onClose())}
+      />
+
+      <aside
+        ref={panelRef}
+        role="dialog"
+        aria-modal="true"
+        aria-label="词汇花园 · Vocabulary Garden"
+        tabIndex={-1}
+        className="relative flex h-full w-full max-w-[420px] flex-col"
+        style={{
+          background: 'var(--color-surface)',
+          borderLeft: '1px solid var(--color-border)',
+          boxShadow: 'var(--shadow-soft)',
+        }}
+      >
+        <header
+          className="flex items-center justify-between px-5 py-4"
+          style={{ borderBottom: '1px solid var(--color-border)' }}
+        >
+          <div>
+            <div className="text-base font-extrabold text-plum">🌷 词汇花园 · Vocabulary Garden</div>
+            <div className="text-xs" style={{ color: 'var(--color-muted)' }}>
+              {queue ? '复习中 · Reviewing — recall, then grade yourself' : 'Words you looked up, blooming as you learn them'}
+            </div>
+          </div>
+          <button
+            type="button"
+            aria-label="Close garden"
+            onClick={onClose}
+            className="flex h-8 w-8 items-center justify-center rounded-full text-lg"
+            style={{ color: 'var(--color-muted)' }}
+            onMouseEnter={(e) => (e.currentTarget.style.background = 'var(--color-surface-alt)')}
+            onMouseLeave={(e) => (e.currentTarget.style.background = 'transparent')}
+          >
+            ✕
+          </button>
+        </header>
+
+        {queue ? (
+          <ReviewSession
+            queue={queue}
+            cursor={cursor}
+            revealed={revealed}
+            onReveal={() => setRevealed(true)}
+            onGrade={grade}
+            onQuit={() => setQueue(null)}
+          />
+        ) : (
+          <GardenView
+            words={words}
+            due={due}
+            error={error}
+            expanded={expanded}
+            onToggleExpand={(id) => setExpanded((cur) => (cur === id ? null : id))}
+            onStartReview={startReview}
+            onRemove={removeWord}
+            onOpenDoc={onOpenDoc}
+            onRetry={load}
+          />
+        )}
+      </aside>
+    </div>
+  )
+}
+
+// --- garden grid ------------------------------------------------------------
+
+function GardenView({
+  words,
+  due,
+  error,
+  expanded,
+  onToggleExpand,
+  onStartReview,
+  onRemove,
+  onOpenDoc,
+  onRetry,
+}: {
+  words: VocabWord[] | null
+  due: VocabWord[]
+  error: boolean
+  expanded: string | null
+  onToggleExpand: (id: string) => void
+  onStartReview: () => void
+  onRemove: (id: string) => void
+  onOpenDoc?: (docId: string) => void
+  onRetry: () => void
+}) {
+  // Index the due cards once so the per-word "due" check below is O(1), not a
+  // linear scan of `due` for every word in the garden.
+  const dueIds = useMemo(() => new Set(due.map((d) => d.id)), [due])
+  return (
+    <>
+      {due.length > 0 && (
+        <div className="px-4 pt-4">
+          <button
+            type="button"
+            onClick={onStartReview}
+            className="w-full rounded-full py-3 text-sm font-extrabold text-white"
+            style={{ background: 'var(--color-accent)' }}
+            onMouseEnter={(e) => (e.currentTarget.style.background = 'var(--color-accent-hover)')}
+            onMouseLeave={(e) => (e.currentTarget.style.background = 'var(--color-accent)')}
+          >
+            复习 {due.length} 个词 · Review {due.length} due 🌸
+          </button>
+        </div>
+      )}
+
+      <div className="min-h-0 flex-1 overflow-y-auto px-4 py-4">
+        {error ? (
+          <div className="px-2 py-6 text-center text-sm" style={{ color: 'var(--color-muted)' }}>
+            Couldn’t load your garden just now.
+            <button onClick={onRetry} className="ml-1 font-bold text-plum underline">
+              Try again
+            </button>
+          </div>
+        ) : words === null ? (
+          <div className="px-2 py-6 text-center text-sm" style={{ color: 'var(--color-muted)' }}>
+            Loading…
+          </div>
+        ) : words.length === 0 ? (
+          <div className="px-3 py-10 text-center" style={{ color: 'var(--color-muted)' }}>
+            <div className="mb-2 text-4xl">🌱🐱💤</div>
+            <p className="text-sm leading-relaxed">
+              你的花园还空着。<br />
+              右键点一个英文单词查它的意思——它就会在这里发芽。
+            </p>
+            <p className="mt-2 text-xs">
+              Your garden is empty. Look up an English word (right-click it) and it’ll sprout here.
+            </p>
+          </div>
+        ) : (
+          <ul className="flex flex-col gap-1.5">
+            {words.map((w) => {
+              const open = expanded === w.id
+              const isDue = dueIds.has(w.id)
+              return (
+                <li key={w.id}>
+                  <button
+                    type="button"
+                    onClick={() => onToggleExpand(w.id)}
+                    className="flex w-full items-center gap-2.5 rounded-2xl px-3 py-2.5 text-left"
+                    style={{
+                      background: open ? 'var(--color-surface-alt)' : 'transparent',
+                      border: `1px solid ${open ? 'var(--color-border)' : 'transparent'}`,
+                    }}
+                  >
+                    <span className="text-xl" aria-hidden>
+                      {blossom(w.reps)}
+                    </span>
+                    <span className="flex min-w-0 flex-1 flex-col">
+                      <span className="truncate text-sm font-bold text-plum">{w.word}</span>
+                      {(w.gloss || w.definition) && (
+                        <span
+                          className="truncate text-xs"
+                          style={{
+                            color: 'var(--color-muted)',
+                            fontFamily: w.gloss
+                              ? "'Nunito','PingFang SC','Microsoft YaHei','Noto Sans CJK SC',sans-serif"
+                              : 'var(--font-body)',
+                          }}
+                        >
+                          {w.gloss || w.definition}
+                        </span>
+                      )}
+                    </span>
+                    {isDue && (
+                      <span
+                        className="shrink-0 rounded-full px-2 py-0.5 text-[10px] font-bold"
+                        style={{ background: 'var(--color-accent)', color: '#fff' }}
+                      >
+                        待复习 · due
+                      </span>
+                    )}
+                  </button>
+
+                  {open && (
+                    <div className="mb-1 ml-9 mr-2 mt-1 flex flex-col gap-2 text-xs" style={{ color: 'var(--color-plum)' }}>
+                      {w.phonetic && <span style={{ color: 'var(--color-muted)' }}>/{w.phonetic}/</span>}
+                      {w.example && (
+                        <p className="italic leading-snug" style={{ fontFamily: 'var(--font-body)' }}>
+                          “{w.example}”
+                        </p>
+                      )}
+                      <div className="text-[11px]" style={{ color: 'var(--color-muted)' }}>
+                        复习 {w.reps} 次 · seen {w.reps}× · 间隔 {w.interval_days}d
+                      </div>
+                      <div className="flex items-center gap-2">
+                        {speechSupported() && (
+                          <button
+                            type="button"
+                            onClick={() => speak(w.word)}
+                            className="rounded-full px-2.5 py-1 text-xs font-semibold"
+                            style={{ background: 'var(--color-surface-alt)' }}
+                          >
+                            🔊 朗读
+                          </button>
+                        )}
+                        {w.doc_id && onOpenDoc && (
+                          <button
+                            type="button"
+                            onClick={() => onOpenDoc(w.doc_id as string)}
+                            className="rounded-full px-2.5 py-1 text-xs font-semibold"
+                            style={{ background: 'var(--color-surface-alt)' }}
+                          >
+                            📄 出处 · Source
+                          </button>
+                        )}
+                        <button
+                          type="button"
+                          onClick={() => onRemove(w.id)}
+                          className="ml-auto rounded-full px-2.5 py-1 text-xs font-semibold"
+                          style={{ color: 'var(--color-muted)' }}
+                        >
+                          🗑 移除
+                        </button>
+                      </div>
+                    </div>
+                  )}
+                </li>
+              )
+            })}
+          </ul>
+        )}
+      </div>
+
+      {!error && words && words.length > 0 && (
+        <div
+          className="shrink-0 px-4 py-2.5 text-center text-[11px]"
+          style={{ borderTop: '1px solid var(--color-border)', color: 'var(--color-muted)' }}
+        >
+          🐱💤 {words.length} 朵花在花园里 · {words.length} blossom{words.length > 1 ? 's' : ''} growing
+        </div>
+      )}
+    </>
+  )
+}
+
+// --- flashcard review -------------------------------------------------------
+
+function ReviewSession({
+  queue,
+  cursor,
+  revealed,
+  onReveal,
+  onGrade,
+  onQuit,
+}: {
+  queue: VocabWord[]
+  cursor: number
+  revealed: boolean
+  onReveal: () => void
+  onGrade: (g: VocabGrade) => void
+  onQuit: () => void
+}) {
+  const card = queue[cursor]
+  // The meaning shown/asked is the Chinese gloss, or the English definition when
+  // a word has no gloss — so definition-only words are still reviewable.
+  const meaning = card?.gloss || card?.definition || ''
+  // Alternate the quiz direction so she practices both recognition (see the
+  // English, recall the meaning) and production (see the meaning, recall the
+  // English word). Parity of the cursor keeps it deterministic within a session.
+  const production = cursor % 2 === 1 && !!meaning
+
+  const prompt = useMemo(() => {
+    if (!card) return ''
+    if (production) return meaning
+    return card.example ? blankOut(card.example, card.word) : card.word
+  }, [card, production, meaning])
+
+  if (!card) return null
+
+  return (
+    <div className="flex min-h-0 flex-1 flex-col px-5 py-4">
+      <div className="mb-3 flex items-center justify-between text-xs" style={{ color: 'var(--color-muted)' }}>
+        <span>
+          {cursor + 1} / {queue.length}
+        </span>
+        <button type="button" onClick={onQuit} className="font-semibold underline">
+          结束 · End
+        </button>
+      </div>
+
+      {/* The card */}
+      <div
+        className="flex flex-1 flex-col items-center justify-center rounded-3xl px-5 py-8 text-center"
+        style={{ background: 'var(--color-surface-alt)', border: '1px solid var(--color-border)' }}
+      >
+        <div className="mb-2 text-3xl" aria-hidden>
+          {blossom(card.reps)}
+        </div>
+        <div
+          className="text-xl font-extrabold leading-snug text-plum"
+          style={{
+            fontFamily: production
+              ? "'Nunito','PingFang SC','Microsoft YaHei','Noto Sans CJK SC',sans-serif"
+              : 'var(--font-body)',
+          }}
+        >
+          {prompt}
+        </div>
+        <div className="mt-1 text-xs" style={{ color: 'var(--color-muted)' }}>
+          {production ? '这个中文意思的英文单词是？· Which English word?' : '这个词什么意思？· What does this mean?'}
+        </div>
+
+        {revealed && (
+          <div className="mt-5 w-full border-t pt-4" style={{ borderColor: 'var(--color-border)' }}>
+            <div className="flex items-center justify-center gap-2">
+              <span className="text-lg font-extrabold text-plum">{card.word}</span>
+              {speechSupported() && (
+                <button
+                  type="button"
+                  onClick={() => speak(card.word)}
+                  aria-label={`Pronounce ${card.word}`}
+                  className="flex h-6 w-6 items-center justify-center rounded-full text-xs"
+                  style={{ background: 'var(--color-surface)' }}
+                >
+                  🔊
+                </button>
+              )}
+            </div>
+            {card.phonetic && (
+              <div className="mt-0.5 text-xs" style={{ color: 'var(--color-muted)' }}>
+                /{card.phonetic}/
+              </div>
+            )}
+            {meaning && (
+              <div
+                className="mt-1 text-sm font-semibold"
+                style={{
+                  color: 'var(--color-accent-hover)',
+                  // Chinese gloss gets the CJK stack; an English definition fallback
+                  // reads better in the body font.
+                  fontFamily: card.gloss
+                    ? "'Nunito','PingFang SC','Microsoft YaHei','Noto Sans CJK SC',sans-serif"
+                    : 'var(--font-body)',
+                }}
+              >
+                {meaning}
+              </div>
+            )}
+            {card.example && (
+              <p className="mt-2 text-xs italic leading-snug" style={{ color: 'var(--color-muted)', fontFamily: 'var(--font-body)' }}>
+                “{card.example}”
+              </p>
+            )}
+          </div>
+        )}
+      </div>
+
+      {/* Controls */}
+      <div className="mt-4">
+        {!revealed ? (
+          <button
+            type="button"
+            onClick={onReveal}
+            className="w-full rounded-full py-3 text-sm font-extrabold text-white"
+            style={{ background: 'var(--color-accent)' }}
+            onMouseEnter={(e) => (e.currentTarget.style.background = 'var(--color-accent-hover)')}
+            onMouseLeave={(e) => (e.currentTarget.style.background = 'var(--color-accent)')}
+          >
+            翻看答案 · Show answer
+          </button>
+        ) : (
+          <div className="grid grid-cols-3 gap-2">
+            <GradeButton color="var(--color-peach)" zh="再来" en="Again" onClick={() => onGrade('again')} />
+            <GradeButton color="var(--color-mint)" zh="记得" en="Good" onClick={() => onGrade('good')} />
+            <GradeButton color="var(--color-honey)" zh="太简单" en="Easy" onClick={() => onGrade('easy')} />
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
+
+function GradeButton({ color, zh, en, onClick }: { color: string; zh: string; en: string; onClick: () => void }) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className="flex flex-col items-center rounded-2xl py-2.5 text-plum"
+      style={{ background: color }}
+    >
+      <span className="text-sm font-extrabold">{zh}</span>
+      <span className="text-[11px] font-semibold opacity-80">{en}</span>
+    </button>
+  )
+}

web/src/components/History/HistoryPanel.tsx

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useState } from 'react'
 import { api, type Document, type DocumentVersion } from '../../api/client'
+import { useFocusTrap } from '../../hooks/useFocusTrap'
 
 // HistoryPanel is the "time machine" drawer: every snapshot Petal kept of this
 // document, newest first, with a one-click preview and restore. It's the safety
@@ -41,6 +42,7 @@ export function HistoryPanel({ docId, onClose, onRestored }: Props) {
   const [selected, setSelected] = useState<DocumentVersion | null>(null)
   const [preview, setPreview] = useState<DocumentVersion | null>(null)
   const [busy, setBusy] = useState(false)
+  const panelRef = useFocusTrap<HTMLElement>()
 
   const load = useCallback(async () => {
     setError(false)
@@ -99,6 +101,11 @@ export function HistoryPanel({ docId, onClose, onRestored }: Props) {
       />
 
       <aside
+        ref={panelRef}
+        role="dialog"
+        aria-modal="true"
+        aria-label="历史 · History"
+        tabIndex={-1}
         className="relative flex h-full w-full max-w-[380px] flex-col"
         style={{
           background: 'var(--color-surface)',

web/src/components/StatusBar/StatusBar.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useRef, useState } from 'react'
+import { Fragment, useEffect, useRef, useState } from 'react'
 import type { SaveStatus } from '../../hooks/useAutoSave'
 import { StatsPanel } from './StatsPanel'
 import { SoundToggle } from './SoundToggle'
@@ -12,6 +12,8 @@ interface Props {
   checking: boolean
   // True while a whole-document voice pass runs — shows a breathing honey dot.
   voicing: boolean
+  // True while a collocation pass runs — shows a breathing blossom dot.
+  collocating: boolean
   // True when Petal can't reach its LLM helper — shows a gentle, reassuring note
   // (the writing still saves locally, so this is awareness, not an error).
   llmDown: boolean
@@ -28,8 +30,40 @@ const SAVE_LABEL: Record<SaveStatus, string> = {
 // StatusBar is the slim footer: word count on the left, save state and the
 // grammar-checkpoint indicator on the right. The checkpoint dot is a soft rose
 // circle that breathes while a check is in flight (spec → Signature animations).
-export function StatusBar({ wordCount, text, saveStatus, checking, voicing, llmDown }: Props) {
+// The live "Petal is working" indicators. Each is a breathing dot + label shown
+// while its pass is in flight; driving them from one array keeps the markup (and
+// the "nothing in flight" check below) in lockstep as passes are added.
+interface Indicator {
+  active: boolean
+  color: string
+  title: string
+  label: string
+}
+
+export function StatusBar({ wordCount, text, saveStatus, checking, voicing, collocating, llmDown }: Props) {
   const label = SAVE_LABEL[saveStatus]
+
+  const indicators: Indicator[] = [
+    {
+      active: checking,
+      color: 'var(--color-accent)',
+      title: 'Petal is reading your writing…',
+      label: 'Checking…',
+    },
+    {
+      active: voicing,
+      color: 'var(--color-honey)',
+      title: 'Petal is reading your voice…',
+      label: 'Reading your voice…',
+    },
+    {
+      active: collocating,
+      color: 'var(--color-blossom)',
+      title: 'Petal is looking for more natural word pairings…',
+      label: 'Finding natural phrasing…',
+    },
+  ]
+  const anyBusy = indicators.some((i) => i.active)
   // The expanded stats panel toggles open when the word count is clicked.
   const [statsOpen, setStatsOpen] = useState(false)
   const statsRef = useRef<HTMLDivElement>(null)
@@ -66,31 +100,21 @@ export function StatusBar({ wordCount, text, saveStatus, checking, voicing, llmD
         </button>
         {statsOpen && <StatsPanel text={text} wordCount={wordCount} />}
       </div>
-      {checking && (
-        <>
-          <span aria-hidden>·</span>
-          <span className="inline-flex items-center gap-1.5" title="Petal is reading your writing…">
-            <span
-              className="petal-checkpoint-dot inline-block h-2 w-2 rounded-full"
-              style={{ background: 'var(--color-accent)' }}
-            />
-            Checking…
-          </span>
-        </>
-      )}
-      {voicing && (
-        <>
-          <span aria-hidden>·</span>
-          <span className="inline-flex items-center gap-1.5" title="Petal is reading your voice…">
-            <span
-              className="petal-checkpoint-dot inline-block h-2 w-2 rounded-full"
-              style={{ background: 'var(--color-honey)' }}
-            />
-            Reading your voice…
-          </span>
-        </>
-      )}
-      {llmDown && !checking && !voicing && (
+      {indicators
+        .filter((i) => i.active)
+        .map((i) => (
+          <Fragment key={i.label}>
+            <span aria-hidden>·</span>
+            <span className="inline-flex items-center gap-1.5" title={i.title}>
+              <span
+                className="petal-checkpoint-dot inline-block h-2 w-2 rounded-full"
+                style={{ background: i.color }}
+              />
+              {i.label}
+            </span>
+          </Fragment>
+        ))}
+      {llmDown && !anyBusy && (
         <>
           <span aria-hidden>·</span>
           <span

web/src/components/Toolbar/Toolbar.tsx

@@ -8,6 +8,9 @@ interface Props {
   // Runs the whole-document voice-consistency pass; `voicing` shows its progress.
   onVoiceCheck: () => void
   voicing: boolean
+  // Runs the whole-document collocation coach; `collocating` shows its progress.
+  onCollocationCheck: () => void
+  collocating: boolean
 }
 
 // A formatting button. `active` gets the rose pill treatment so the writer can
@@ -165,7 +168,7 @@ function Swatch({
 // Toolbar renders inline formatting controls bound to the live Tiptap editor.
 // useEditorState subscribes to just the flags it reads, so the buttons reflect
 // the current selection without re-rendering the whole tree on every keystroke.
-export function Toolbar({ editor, onVoiceCheck, voicing }: Props) {
+export function Toolbar({ editor, onVoiceCheck, voicing, onCollocationCheck, collocating }: Props) {
   // Which popover (if any) is open. Only one at a time.
   const [menu, setMenu] = useState<'color' | 'highlight' | 'size' | 'link' | 'table' | 'outline' | null>(null)
   const [linkUrl, setLinkUrl] = useState('')
@@ -594,6 +597,28 @@ export function Toolbar({ editor, onVoiceCheck, voicing }: Props) {
         />
         {voicing ? 'Reading…' : 'Check my voice 🍯'}
       </button>
+
+      <button
+        type="button"
+        aria-label="Make it sound natural"
+        disabled={collocating}
+        onMouseDown={(e) => e.preventDefault()} // keep editor selection
+        onClick={onCollocationCheck}
+        className="ml-1 inline-flex h-8 items-center gap-1.5 whitespace-nowrap px-3 text-xs font-bold transition-colors disabled:opacity-70"
+        style={{
+          borderRadius: 'var(--radius-pill)',
+          color: 'var(--color-plum)',
+          background: 'var(--color-blossom)',
+        }}
+        title="Find word pairings that natives usually say differently"
+      >
+        <span
+          className={collocating ? 'petal-checkpoint-dot inline-block h-2 w-2 rounded-full' : 'hidden'}
+          style={{ background: 'var(--color-plum)' }}
+          aria-hidden
+        />
+        {collocating ? 'Reading…' : 'Make it sound natural 🌸'}
+      </button>
     </div>
   )
 }

web/src/hooks/useCheckpoint.ts

@@ -13,6 +13,8 @@ export function useCheckpoint(docId: string | null) {
   const [checking, setChecking] = useState(false)
   // True while a whole-document voice pass is in flight (explicit user action).
   const [voicing, setVoicing] = useState(false)
+  // True while a whole-document collocation pass is in flight (explicit action).
+  const [collocating, setCollocating] = useState(false)
   // True when the last LLM pass couldn't reach the model (server 502 or network
   // error). Drives a gentle, reassuring "helper is resting" note — the writing
   // itself still saves fine, so this is awareness, not an error. Cleared on the
@@ -66,28 +68,53 @@ export function useCheckpoint(docId: string | null) {
     }
   }, [])
 
-  // Run the voice-consistency pass now (explicit "Check my voice" action). Like
-  // runCheck it returns the unified pending set, so grammar highlights survive.
-  // Shares the run token so navigating away discards a late voice response.
-  const runVoice = useCallback(async () => {
-    const id = docIdRef.current
-    if (!id) return
-    clearTimeout(retryRef.current) // a voice pass supersedes a queued grammar retry
-    const run = ++runRef.current
-    setVoicing(true)
-    try {
-      const full = await api.voiceDoc(id)
-      if (run === runRef.current && id === docIdRef.current) {
-        setSuggestions(full)
-        setLlmDown(false)
+  // runExplicitPass drives a whole-document, explicit-action pass (voice,
+  // collocation): it returns the unified pending set, so the other families'
+  // highlights survive, and shares the run token so navigating away discards a
+  // late response. It supersedes any queued grammar retry AND clears the
+  // checkpoint's "checking" state, so the breathing rose dot can't linger on
+  // after the retry timer it would have cleared is cancelled here.
+  const runExplicitPass = useCallback(
+    async (call: (id: string) => Promise<Suggestion[]>, setBusy: (b: boolean) => void, label: string) => {
+      const id = docIdRef.current
+      if (!id) return
+      // An explicit action fully supersedes a queued auto-check and grammar
+      // retry, and takes over the indicator — clear the stranded "checking" dot.
+      clearTimeout(debounceRef.current)
+      clearTimeout(retryRef.current)
+      setChecking(false)
+      const run = ++runRef.current
+      setBusy(true)
+      try {
+        const full = await call(id)
+        if (run === runRef.current && id === docIdRef.current) {
+          setSuggestions(full)
+          setLlmDown(false)
+        }
+      } catch (err) {
+        console.error(`${label} failed`, err)
+        if (run === runRef.current) setLlmDown(true)
+      } finally {
+        // setBusy is THIS invocation's own flag (a newer run sets its own), so
+        // clear it unconditionally — otherwise an overlapping pass that bumped
+        // the run token would strand this spinner on "Reading…" forever.
+        setBusy(false)
       }
-    } catch (err) {
-      console.error('voice pass failed', err)
-      if (run === runRef.current) setLlmDown(true)
-    } finally {
-      if (run === runRef.current) setVoicing(false)
-    }
-  }, [])
+    },
+    [],
+  )
+
+  // Run the voice-consistency pass now (explicit "Check my voice" action).
+  const runVoice = useCallback(
+    () => runExplicitPass(api.voiceDoc, setVoicing, 'voice pass'),
+    [runExplicitPass],
+  )
+
+  // Run the collocation coach now (explicit "Make it sound natural" action).
+  const runCollocation = useCallback(
+    () => runExplicitPass(api.collocationDoc, setCollocating, 'collocation pass'),
+    [runExplicitPass],
+  )
 
   // Call on every edit; schedules a check 4s after typing settles.
   const schedule = useCallback(() => {
@@ -105,6 +132,7 @@ export function useCheckpoint(docId: string | null) {
     setSuggestions([])
     setChecking(false)
     setVoicing(false)
+    setCollocating(false)
     setLlmDown(false)
     if (!docId) return
     let cancelled = false
@@ -134,5 +162,5 @@ export function useCheckpoint(docId: string | null) {
     setSuggestions((prev) => prev.filter((s) => s.id !== id))
   }, [])
 
-  return { suggestions, checking, voicing, llmDown, schedule, runVoice, removeSuggestion }
+  return { suggestions, checking, voicing, collocating, llmDown, schedule, runVoice, runCollocation, removeSuggestion }
 }

web/src/hooks/useFocusTrap.ts

@@ -0,0 +1,59 @@
+import { useEffect, useRef } from 'react'
+
+// useFocusTrap makes a slide-over / modal keyboard-accessible. Attach the
+// returned ref to the dialog container and, while it's mounted, it:
+//   • moves focus into the panel on open (so Tab/Escape work without a click),
+//   • keeps Tab/Shift+Tab cycling within the panel instead of escaping to the
+//     page behind the backdrop, and
+//   • restores focus to whatever was focused before it opened on unmount.
+// Escape handling stays with each panel, which has its own close semantics.
+export function useFocusTrap<T extends HTMLElement>() {
+  const ref = useRef<T>(null)
+
+  useEffect(() => {
+    const node = ref.current
+    if (!node) return
+
+    // Remember where focus was so we can hand it back when the panel closes.
+    const previouslyFocused = document.activeElement as HTMLElement | null
+
+    const focusables = () =>
+      Array.from(
+        node.querySelectorAll<HTMLElement>(
+          'a[href], button:not([disabled]), textarea, input, select, [tabindex]:not([tabindex="-1"])',
+        ),
+      ).filter((el) => el.offsetParent !== null)
+
+    // Focus the first interactive element, or the container itself as a fallback.
+    const first = focusables()[0]
+    if (first) first.focus()
+    else node.focus()
+
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== 'Tab') return
+      const items = focusables()
+      if (items.length === 0) {
+        e.preventDefault()
+        return
+      }
+      const firstEl = items[0]
+      const lastEl = items[items.length - 1]
+      const active = document.activeElement
+      if (e.shiftKey && active === firstEl) {
+        e.preventDefault()
+        lastEl.focus()
+      } else if (!e.shiftKey && active === lastEl) {
+        e.preventDefault()
+        firstEl.focus()
+      }
+    }
+
+    node.addEventListener('keydown', onKeyDown)
+    return () => {
+      node.removeEventListener('keydown', onKeyDown)
+      previouslyFocused?.focus?.()
+    }
+  }, [])
+
+  return ref
+}

web/src/index.css

@@ -20,6 +20,7 @@
   --color-lavender: #C5B4E8;    /* idiom */
   --color-sky: #A8CCE8;         /* clarity */
   --color-honey: #CE9B4F;       /* voice */
+  --color-blossom: #E59ABF;     /* collocation — warm blossom pink */
   --color-success: #8FCFA8;     /* saved / accepted */
 
   /* Typography */
@@ -232,6 +233,7 @@ button, a, input {
 .petal-suggestion-idiom    { border-bottom-color: var(--color-lavender); }
 .petal-suggestion-clarity  { border-bottom-color: var(--color-sky); }
 .petal-suggestion-voice    { border-bottom-color: var(--color-honey); }
+.petal-suggestion-collocation { border-bottom-color: var(--color-blossom); }
 
 @keyframes petal-suggestion-in {
   from { opacity: 0; transform: translateY(4px); }