petal/SUGGESTIONS.md

# Petal — product suggestions: becoming essential for language learners

**Status:** written 2026-07-26 against `feat/writing-passport`; **ratified by
the user 2026-07-26** (recommendations accepted — reviewer Q1–Q3 settled
below; Q4–Q6 remain genuinely open and don't block execution). This document
is the *why*; the checkboxed execution phases live in `BUILD_PLAN.md`
(Phase 15 onward).

**The brief:** make Petal essential for two audiences — ESL writers (native
Mandarin / pt-PT / French → English), and English natives learning Mandarin,
European Portuguese, French, maybe Spanish. Preserve privacy and warmth.

**The language model (settled by the user, 2026-07-26):** every user has
exactly one language **pair, with English always one half** — (en + X),
X ∈ {zh, pt-PT, fr, maybe es}. This is a deliberate scope decision: never an
X↔Y pair without English, never more than one pair per user. The UI is
bilingual in the pair everywhere (tips, pet responses, cards), and the user
may **type in either language of the pair**; Petal infers direction from the
text rather than asking.

---

## 1. What the pair model implies

The wife's zh setup is already exactly this — she writes Mandarin and English
mixed, the UI is zh+en bilingual, and Petal adapts per span (CJK is never
spellchecked, English words gloss to Chinese). So the pair model isn't a new
design; it's a *promotion of today's behavior to the spec*. Three consequences:

- **Schema:** one column, `users.pair_lang` (the X half; default `'zh'`).
  No per-document language, no target/native split. Add it in whatever
  migration Phase B's provisioning touches — one column now vs. a real
  migration later, the same logic that put `user_id` in the schema on day one.
- **Direction is inferred, not declared.** The zh pair gets inference for free
  (script boundaries separate the languages). Latin pairs don't — see §3a,
  which is the one genuinely new problem the pair model creates.
- **Every bilingual surface stays two-language**, just parameterized: the
  `中文 · English` pattern becomes `X · English`. Nothing about the UI's shape
  changes, which is why the copy extraction in §2 is safe to do early.

## 2. Languages as data, not code ("langpacks")

Adding pt-PT today means editing code in many places. A quick census: **29
frontend files** carry hardcoded zh-first bilingual strings (`tips.ts`,
`GardenPanel`, `StatusBar`, `WordCard`, every popover…), plus the
Mandarin-first prompt copy in `internal/llm/prompts.go`. Adding each new
language by hunting through those files doesn't scale to four pairs and would
slowly erode the bilingual-copy quality that makes Petal feel cared-for.

Because English is always one half, a **langpack is keyed by X alone** — one
pack per pair, holding everything that varies:

- UI copy pairs — extract the existing `中文 · English` strings into a copy
  module; the current strings become the `zh` pack verbatim, so nothing
  visible changes. This is the biggest single chore in the whole effort;
  better done once than per-language.
- Companion tip/cheer/bedtime lines (`tips.ts` is already data-shaped —
  closest to done).
- LLM prompt copy: bilingual explanation phrasing, "natives usually say…"
  example pairs, and the both-directions framing (the text may be English, X,
  or mixed — respond appropriately).
- Hunspell dictionary for X where one exists (`pt-PT`, `fr`, `es` upstream;
  zh has none — see §4). The en-US dictionary is shared by every pair.
- DreamDict wiring: gloss both directions (`en→X` and `X→en`), phonetics.
- Piper voices for X (both for reading X text aloud and as the L1 voice);
  font stack (CJK stacks only for zh).

Shared across all pairs, untouched: nspell en-US, the English IPA dataset, the
EN Piper voice, and all of the editor machinery.

This is refactoring, not product, so it's tempting to skip. Don't: it's the
difference between "Spanish is a data drop" and "Spanish is a month."

## 3. Sequencing: Latin-script targets first, and in this order

**pt-PT → fr → es.** Everything needed for these exists already: Hunspell
dictionaries, Piper voices, DreamDict data (en/fr/pt-PT/zh), and — critically —
the entire decoration/anchoring machinery (`wordAt`, spell tokenizer, suggestion
re-anchoring) already works, because these languages are space-delimited and
Latin-script like English.

Caveats worth writing down now:

- **DreamDict has no Spanish.** "Maybe Spanish" is gated on adding es to
  DreamDict first, or a separate dataset. Cheap to note, expensive to discover
  later.
- **pt-BR drift is the main quality risk.** Qwen will default to Brazilian
  Portuguese in both explanations and "natives say…" examples. Prompts must pin
  European Portuguese explicitly, and the pt-PT pack should be reviewed by a
  pt-PT speaker before it's trusted — same standard the zh copy got by being
  written for a real reader. The multi-user plan's ECDICT-vs-DreamDict
  compare-on-real-lookups discipline applies here too.
### 3a. The Latin+Latin wrinkle: inferring direction without a script boundary

The zh pair gets "which language is this word?" for free — the script answers
it, and all of today's behavior (CJK never spellchecked, English words gloss
to Chinese) hangs off that. In an en+fr or en+pt pair, both halves are Latin
script, so the two per-word decisions need a real answer:

- **Spellcheck:** load both Hunspell dictionaries and pass a token if *either*
  accepts it; flag only words wrong in both. This never falsely squiggles
  correct writing in either language — the failure mode is missing a French
  word that happens to be a valid English word, which is the gentle direction
  to fail in. Correction pills can offer both dictionaries' suggestions.
- **Gloss/WordCard:** look the word up in both directions via DreamDict; if it
  exists in only one language, done. For collisions (*chat*, *pain*, *sale*
  are all real words in both English and French), show both compactly — a
  two-line card ("🇫🇷 chat → cat · 🇬🇧 chat → bavarder") is honest, needs no
  detector, and is arguably *delightful* for a learner. A sentence-level
  language guess can order the lines, but shouldn't hide either.

No trained language detector, no heuristics that can be wrong about someone's
writing — both-dictionaries membership plus show-both-on-collision covers it.
The LLM passes need nothing: the prompt already sees the mixed text whole.

- The Hunspell tokenizer's current rule "CJK is never tokenized" stays correct
  for the zh pair unchanged.

## 4. The zh pair's *other* direction is a separate epic — say so explicitly

The en+zh pair already exists, but only one direction of it is built: today
Petal deliberately ignores typed hanzi (never tokenized, never flagged, never
glossed) — exactly right for a zh-native writer practicing English, and
exactly insufficient for an English native *learning* Chinese, for whom the
hanzi side is the whole point. Supporting that direction breaks assumptions
that are load-bearing everywhere:

- No spaces → `wordAt`, the spell tokenizer, and word-boundary lookups need
  real word segmentation (a jieba-style segmenter, client- or server-side).
- Hunspell has no concept of Chinese; "spellcheck" becomes wrong-character
  (错别字) detection — a different problem, probably LLM-assisted.
- Smart-typography input rules and the IME interact; input rules are currently
  ASCII-gated, which is correct, but selection/caret behavior mid-IME
  composition needs testing.
- The learning aids that matter are different: pinyin annotation (useful here,
  unlike for the current user who reads hanzi), tone-mark help, HSK-level word
  difficulty, hanzi stroke/handwriting practice.

None of this is unbuildable, but it is its **own phase with its own spec**, not
part of the langpack drop. Recommendation: ship the pt-PT/fr pairs first to
prove the pair model, and treat learner-facing Chinese writing as Petal's next
big product bet after that — it's also the most differentiated one (very few
warm, private tools exist for writing practice in Chinese).

## 5. Deepening the learning loop (all local, all gentle)

Petal's suggestion pipeline currently *corrects and forgets*. The vocabulary
garden proved that capturing what the user already does (lookups) creates a
learning surface for free. The same move is available twice more:

### 5a. Growth journal (patterns from accepted suggestions)

Accepted grammar/collocation suggestions are a record of what the writer is
learning. Aggregate them **locally** into gentle patterns: "this month you've
mostly stopped mixing 在/at" / "make a decision has stuck — you've used it
right 4 times since." Two framing rules that keep it warm: it reports *growth*,
never an error tally, and it only ever compares the writer to her own past
self. Feeds the companion's cheer pool with genuinely personal material
("上次你还问过这个词，这次自己用对了! 🌱"). Data is already in the
`suggestions` table (status + type + original/replacement); this is a read-side
feature, no new capture needed.

### 5b. Plant accepted collocations in the garden

An accepted collocation ("do a decision" → "make a decision") is a learnable
chunk, exactly like a looked-up word. Auto-capture it into the vocabulary
garden as a phrase card (the SM-2-lite scheduler doesn't care that it's two
words). The garden then reflects *both* halves of learning: words she sought
out, and phrasing she was gently given.

### 5c. Companion as tutor-lite: a daily invitation to write

The companion nudges about breaks and bedtime but never *invites writing*. A
once-a-day bilingual prompt ("写 50 个字：今天让你微笑的一件小事 · Write 50
words: one small thing that made you smile today"), offered when a session
starts with no doc open. Explicitly **no streaks, no guilt** — the existing
no-streak-shaming ethos in the SR scheduler is the right precedent; a declined
prompt just gets a sleepy "好吧，我继续睡 😴". Prompt lists live in the
native-language pack.

### 5d. Use DreamDict's richer fields

The multi-user plan notes DreamDict carries `Frequency`, `Difficulty`,
`Antonyms`, `Etymology` with "no equivalent" in Petal. Three cheap, high-value
surfaces:
- A **frequency/difficulty chip** in the WordCard ("common word" / "advanced")
  — helps a learner decide whether a word is worth gardening.
- **Etymology for the en-native audience**: Romance-language learners live on
  cognates; a one-line "from Latin *decidere*, like English *decide*" is the
  single best memory hook for pt/fr/es vocabulary.
- **False friends**: a small curated list per pair (en↔pt: *embarrassed* ≠
  *embaraçada*-adjacent traps, *actually*/*atualmente*; en↔fr likewise),
  surfaced as a warm heads-up in the WordCard and as a collocation-style
  gentle flag when one is used suspiciously. Tiny data, disproportionate
  trust-building — this is the mistake that makes learners feel foolish, and
  catching it kindly is very Petal.

### 5e. Read-aloud, slower

Piper voices exist per target language; wire the target-language voice into the
existing 🔊 surfaces, and add a **slow toggle** (Piper's `length_scale`) —
learners replaying a sentence at 0.75× is one of the oldest, most-loved
listening aids, and it's a query parameter away.

## 6. LLM-minimalism: essential help in plain code, the model as garnish

**Stated by the user (2026-07-26):** with the LLM on the far side of a VPN,
preserve as much essential functionality as possible in ordinary code inside
Petal, and rely on the LLM as little as possible. This deserves to be a
standing design principle, not just a deployment reaction — it's also what
keeps Petal instant (no 38-second checkpoints for things a lookup can answer)
and private by construction.

Where Petal stands today, by dependency:

| Already pure code (survives VPN-down) | LLM-only today |
|---|---|
| Spellcheck (Hunspell), gloss/definitions/synonyms/phonetics (embedded lexicon → DreamDict), thesaurus, vocabulary garden + SR review, search, tags, versions + writing passport, export, find/replace, typography, TTS (Piper, VPS-local) | Grammar checkpoint, collocation coach, voice pass, Ask Petal, tone rewrite |

Everything in §5 lands in the left column by design (growth journal, garden
planting, daily prompts, DreamDict fields, false friends — all lookups and
local aggregation). The right column splits into two groups:

**Worth a code-first layer (the essential two):**

- **Grammar lite** — a rule-pack of high-precision, data-driven checks for
  the classic ESL patterns: a/an before vowel sounds, uncountables
  ("informations", "advices", "furnitures"), subject–verb agreement in simple
  clauses, doubled comparatives, common preposition pairs ("depend of" →
  "depend on"), per-pair L1-interference rules (zh: dropped articles, he/she
  slips; pt/fr: "have X years" for age). These run instantly on every edit —
  no debounce, no 30s rate limit — as a fourth suggestion family through the
  existing rail. The bar is **precision over recall**: an offline rule must be
  near-certain before it flags, because a wrong correction is colder than a
  missed one. LanguageTool's open rule corpus is a mineable source for
  vetted patterns (extract data, not the Java).
- **Collocation data** — the same curated-list move as false friends: the
  do/make, say/tell, strong-tea/heavy-rain families that fill every ESL
  collocation workbook are a few hundred entries of data, not a model. A
  small embedded miscollocation list catches the top offenders offline; the
  LLM pass, when reachable, adds the long tail. Same family, same rail, same
  warm phrasing — the writer never needs to know which engine spoke.

**Inherently LLM (degrade warmly, don't imitate):** Ask Petal, tone rewrite,
and the voice pass are open-ended language generation — a code fake would be
worse than the existing honest "小助手在休息" state. Leave them as the
garnish they are.

The framing that falls out: **the LLM never holds essential functionality
hostage.** Every daily-writing need — spell, define, gloss, pronounce, catch
the common mistakes, review vocabulary, prove authorship — works on a
disconnected VPS. The model adds depth and conversation when the tunnel is up.

## 7. The writing passport is an ESL flagship — treat it as one

The passport exists because AI detectors misfire on non-native English (the
commit message cites the Stanford TOEFL finding). That's not a side feature —
for the ESL audience it may be *the* reason to adopt Petal over any other
editor: **the tool that protects you from being wrongly accused, instead of
scoring you.** No product change needed beyond making sure it works identically
for any target language (it should — it's language-agnostic snapshot history).
Worth a prominent place in the README/landing copy when Petal gets one.

## 8. Ties into MULTIUSER_PLAN.md

For the open questions there, this document's brief implies:

- **OPEN #1 (auth):** Option B (in-app OIDC), and the planned deployment
  settles it. The user's stated topology (2026-07-26) is: **Petal hosted on
  the parodia.dev VPS, reaching vLLM on millenia over headscale VPN.** A
  public-internet app is exactly the case where "must never be reachable
  except through Traefik" is a footgun — one proxy misconfiguration on a VPS
  and forged identity headers reach the app. In-app OIDC is safe to expose
  directly.
- **Deployment topology consequences** worth writing into the plan's Phase 2
  (deploy plumbing):
  - The LLM becomes the only cross-VPN runtime dependency (Piper is already
    installed on parodia.dev, so TTS stays VPS-local). The warm
    "小助手在休息" degradation path was built for a flaky co-tenant Ollama; a
    VPN link-down hits the same path, so the architecture already fails
    gently — but checkpoint latency now includes a WAN+VPN round trip, worth
    a look at the 60s LLM timeout.
  - Everything offline-by-design (DreamDict lookups, spellcheck, gloss,
    garden, search, the whole editor) keeps working when the VPN is down —
    another argument for MULTIUSER_PLAN Option 3 over an HTTP dictionary
    service, which would otherwise add a second cross-machine dependency.
  - vLLM and Piper on millenia should bind to the headscale interface only,
    never 0.0.0.0 on the LAN-facing side.
  - The writing moves onto rented VPS disk. "The writing never leaves the
    box" (§8) becomes "the box is a VPS" — at-rest encryption and an
    off-VPS backup of `petal.db` (e.g. nightly to millenia over the same
    VPN) deserve a line in the deploy phase.
- **OPEN #6a (DreamDict):** Option 3 (import, read-only `dict.db`), agreed —
  it's the only option where four languages stay offline and instant, which
  §6 and §9 treat as non-negotiable.
- **Phase B provisioning** should set `users.pair_lang` from the operator's
  provisioning step or a first-run picker — add the column in the same
  migration. (The plan's Phase D "native language becomes a `users` column"
  becomes this: one column, the X half of the pair.)
- **localStorage namespacing** matters slightly more than the plan says once a
  household mixes pairs: the personal spell dictionary is per-*language* as
  well as per-user (a user's en words and pt-PT words must not merge into one
  Hunspell overlay). Key by `user + lang`.

## 9. Privacy & warmth guardrails (the checklist for every item above)

Everything suggested here passes these; future ideas should too.

1. **Offline-first, always — and code-first (§6).** Every essential surface
   must work with the LLM unreachable and the network unplugged
   (DreamDict-as-local-file preserves this; an HTTP dictionary service would
   not). The LLM only ever adds depth to something that already works.
   Cloud APIs are off the table even when they'd be easier.
2. **The writing never leaves the box.** No telemetry, no "anonymous usage
   stats," ever. The growth journal (§5a) is computed locally from local rows.
3. **No scores, no percentages, no red.** Petal already refuses AI-detection
   scores and classic red squiggles; the growth journal and false-friend flags
   must hold the same line — evidence and gentle phrasing, never grades.
4. **No streaks, no guilt.** The SR scheduler set the precedent (gentle
   "again", no wipe). Daily prompts (§5c) are invitations, not obligations.
5. **Both languages of the pair, always visible** — every explanation, tip,
   and pet response renders bilingual in (en + X). That's the warmth: being
   helped in the language you think in, next to the one you're learning.
6. **The kitten stays asleep.** Every new companion behavior routes through
   the existing mood/cooldown engine; 瞌睡猫 keeps mumbling helpful things
   without waking up. (A reactive-animation puppy is on the wishlist — low
   priority per the user; the `companions.ts` roster + mood engine is already
   the drop-in point, richer per-mood Lottie segments are the only new work.)

## 10. Suggested sequence (interleaved with the multi-user plan's)

1. Add the `users.pair_lang` column (with the Phase B migration or sooner).
2. Extract the bilingual UI copy into the langpack (zh pack = today's strings
   verbatim; pure refactor, no visible change).
3. DreamDict integration per MULTIUSER_PLAN Option 3 (module rename → lexicon
   provider → pt-PT/fr wired first, zh compared before converging).
4. pt-PT as the first full second pair: Hunspell pt-PT, Piper pt-PT voices,
   pinned-pt-PT prompts, native-speaker copy review, and the both-dictionaries
   spellcheck + show-both-gloss behavior from §3a. French follows the same
   groove; Spanish gated on DreamDict es data.
5. Learning-loop features (§5) — each is small and independent; growth journal
   and garden-planting of collocations first, since they're read-side over
   existing data.
6. Code-first layers (§6): the embedded miscollocation list first (same shape
   as false friends, drops into the existing collocation family), then
   grammar lite as its own suggestion family. Both are per-pair data, so
   they slot naturally into the langpacks from step 2.
7. Learner-facing Chinese writing (the zh pair's second direction): spec it as
   its own phase (§4) only after the pair model is proven on pt-PT/fr.

## 11. Questions for the reviewer (1–3 settled 2026-07-26)

1. ~~§3a's no-detector stance~~ **Settled: yes** — pass if either dictionary
   accepts it, show both glosses on collision, no language detector.
2. ~~UI-copy extraction first?~~ **Settled: yes** — the extraction (§2) is a
   prerequisite chore, done before pt-PT is wired.
3. ~~Growth journal framing~~ **Settled: build it** with the two framing rules
   as hard constraints (growth only, self-comparison only).
4. When (not whether) to build the learner-facing hanzi direction of the zh
   pair — after pt-PT/fr, or is it wanted sooner?
5. Spanish: worth asking DreamDict to grow an es dataset now, or park it?
6. Grammar lite (§6): hand-curate the rule pack from ESL teaching materials
   (small, fully understood), or mine LanguageTool's open rule corpus for
   vetted patterns (bigger head start, needs licensing + quality triage)?