# Clanker — Roadmap

**The first VADUGWI project.** A community-cared creature with persistent memory and
emotion whose purpose is to make the 7-dimensional VADUGWI state **visible, audible, and
explainable in real time** — and to **log real usage so the VADUGWI formulas can be
audited and improved**. The pet is the vehicle; showing off VADUGWI is the point.

## Framing: this is a SHOWROOM FLOOR
The whole UI is a **showroom for the VADUGWI engine** — every mechanic is on demonstrative
display, not hidden behind a cute pet. The visitor should *see the machine work*: the raw
read, **how the soul's VADUGWI governs how much new emotion it accepts (resilience/armor)**,
the mood that results, and **how words/actions have shaped the soul over time**. The pet is
the exhibit; the engine is the product.

## Governing principle (HARD RULE)
**VADUGWI drives everything — full stop.** Every feature, mechanic, toy, care action,
animation, sound, and bit of GFX must *read from or write to* the VADUGWI state. Nothing is
cosmetic-only; nothing is faked. If a proposed addition can't be tied to a concrete VADUGWI
cause or effect, it does not ship. The creature's every behavior must trace back to real
engine math — and that trace must be loggable for the audit flywheel below.

## Why this matters (the flywheel)
People talk to the creature → clanker-lang scores it → clanker-soul accumulates mood →
the creature shows *exactly why* it feels how it feels (words detected, roles, structures,
per-dimension contributions). Every interaction is logged (input + full VADUGWI + trace).
That corpus lets us **audit the engine against real-world language** — find cases that read
neutral but shouldn't, miscalibrated dimensions, blind spots — and feed fixes back into
the formulas. The pet is a continuous, free, real-world evaluation harness with a face.

## Current status (Phase 1, shipped 2026-06-15)
Live at `huggingface.co/spaces/deucebucket/clanker` (Docker Space, FastAPI + vanilla JS,
no model — simlish voice via browser Web Speech, one shared global SQLite soul).
**Known gap that M1 fixes:** the engine works (VADUGWI moves on every message) but the
showcase is buried — color/face/word are bucketed into only 5 discrete regions so small
talk looks frozen; the numbers hide in one drawer; and the **trace (what it detected) is
discarded entirely** (`scorer.py` drops it). A placeholder "guest" chip clutters the
corner. GFX read as rough-draft; the room is empty.

## Locked decisions
- **Build order:** M1 (showcase core) first.
- **Audit/data store:** a **private HF Dataset** repo — every interaction appended
  (input text, full VADUGWI, trace, care/context, timestamp). Durable, survives rebuilds,
  easy to pull for analysis.
- **Identity:** **anonymous-first**; HF login optional (unlocks being remembered + care
  credit). Maximizes community reach.
- **No language model, ever.** Voice = simlish + emoticons via browser Web Speech ($0).
- **One shared global creature**, permanent state, community-shaped.

---

## M1 — Make VADUGWI visible + auditable  *(the fix + the point)*
The current Space's defect and the showcase, together.
- **Continuous appearance** — color/posture interpolate smoothly across the VADUGWI space
  instead of snapping between 5 buckets, so every message visibly moves the creature.
- **Live 7-dim HUD** — all of V A D U G W I on screen as labeled meters, each showing its
  current value AND the **per-message delta** (e.g. `W −6`). Always visible, not hidden.
- **"What it detected" panel** — surface the discarded trace: the words that fired, their
  roles (SELF_REF, EMOTIONAL, NEGATOR, AMPLIFIER, …), structures detected, and each
  dimension's contributors. This is the explainability no neural pet can do.
- **"Why it feels this way"** — current mood = soul baseline + recent interactions, shown
  as readable contributions.
- **Surface the raw per-message read** (undamped) next to the slow soul mood, so the engine's
  reactivity is obvious even when the soul moves slowly.
- **Resilience/acceptance display** — show how the soul's armor (from its W/D) absorbed part
  of each incoming read (`absorbed_pct`), so the read→mood gap is explained, not mysterious.
- **Soul-over-time** — a timeline of how words/actions shaped the soul across the creature's
  life (from the event log); full historical persistence is M2.
- **Born flimsy** — a newborn soul has low W/D + near-zero resilience, so it swings hard on
  every message (resilience is earned later, see M3). Reset the live creature to baby.
- **Log unknown words / suspected vocab gaps** as first-class audit rows (Jerry's priority).
- **Richer mood vocabulary** — many more mood words than the current 5.
- **Remove the mystery box** (the placeholder identity chip).
- **Audit logging** — append every interaction to the private HF Dataset.
- **First GFX pass** — adopt the **Hugging Face mascot** look (recolorable vector, faithful
  silhouette, resting yellow ≈ neutral; color/face/hands driven by VADUGWI), more shine/depth,
  and a less-empty room (full polish + ambient mascot behaviors are M4).
- **Surface the trace at the source** — `scorer.py` must keep `compute_vadug`'s trace, not
  drop it; expose it through `/say`.
- *Success:* a visitor sends any message and immediately sees numbers move, the words it
  reacted to, and why — and that interaction lands in the audit dataset.

## M2 — Persistence  ✅ DONE (2026-06-15)
- **Soul survives Space rebuilds** via free **HF Dataset snapshot/restore** (chose this over
  paid persistent storage): on boot, pull the latest `soul.db` from a private dataset before
  opening it; after interactions, snapshot back — throttled (≤1/120s), background, fail-soft.
  Audit log already snapshots to its own dataset. (`app/persistence.py`.)
- **Activation (one-time, Jerry):** create private dataset `deucebucket/clanker-soul-state`
  + ensure the Space has the `HF_TOKEN` secret. Until then it's a fail-soft no-op.
- *Identity deferred* → see M2.5.

## M2.5 — Identity  ✅ DONE (2026-06-15) — RECOGNITION-ONLY, privacy-first (`docs/PRIVACY.md`)
- HF OAuth login (optional; **anonymous-first** — everything works logged-out). `hf_oauth: true`
  in README; authlib OIDC flow (`/login`,`/auth/callback`,`/logout`,`/me`); signed session.
- On login, the OIDC `sub` is **sha256-hashed** into the session — raw username NEVER stored
  or shown. `RecognitionStore` (in the soul db, so it persists via M2) tracks first-seen/visits
  per hash; `/say` returns `recognition` only when signed in; the creature welcomes returnees.
- `/me` returns only `{signed_in: bool}`. SESSION_SECRET set as a Space secret.
- *Final check (Jerry):* click "sign in", authorize, confirm it recognizes you on return —
  the logged-in round-trip needs a human HF login to fully validate.
- Foundation for M3's per-user relational memory (affinity VADUGWI + flashbulb).

## M3 — Tamagotchi care + relational memory + Moments  ✅ DONE (2026-06-15)
- **Care loop** (`app/care.py`): feed/play/pet fill needs (hunger/energy/attention) and each
  ingests a positive VADUGWI Score; needs decay over time; sustained **neglect** ingests a
  mild negative Score (floored — always recoverable). `POST /care`; needs in every state.
- **Resilience growth (earned)** (`soul_bridge`): effective `dim_resilience_max` rises with
  lifetime event count (0.08 baby → ~0.5 mature), applied live; persists via M2. `maturity()`.
- **Relational memory** (`app/relation.py`): per hashed-uid affinity EMA + flashbulb
  (vectors+mood word+ts, NO raw text); signed-in users get re-felt on return (recall once/
  session); privacy-clean (no usernames).
- **Moments diary** (`app/moments.py`): `notable()` flags breakdown/breach/elation/wound/
  breakthrough; captured in `/say`; `GET /moments` (snapshots = vectors, no text).
- UI: care buttons + needs bars + Moments panel + "remembers you" hint (no usernames).
- All in the soul SQLite db → persisted by M2's snapshot.
- *Community-shared "who cared for it" surfacing deferred to M5 (economy/governance).*

## M4 — Toys, world, physics, fluid animation, full GFX  ✅ DONE (2026-06-15)
- **Toys** (`app/toys.py`, `POST /toy`): 5 momentary VADUGWI stimuli — balloon (high-arousal
  delight), musicbox (positive valence at LOW arousal+urgency), mirror (self-Worth), teddy
  (comfort/grounding), **rattle (Urgency spike — the dimension chat/care never reach)**. Each
  ingests an absolute-target `Score` into the one shared soul; audit-logged like chat.
- **In-browser physics + fluid animation** (`static/physics.js` pulse engine + `app.js` loop):
  a `requestAnimationFrame` loop drives spring-damped **squish** (impulse on every response,
  sized by |VADUGWI deltas|) and continuous **breathing** (rate+depth from arousal). Writes to
  a `#blob-anim` wrapper so it never fights `renderBlob`'s per-message transform.
- **Mascot behaviors** — idle FSM `behaviorFor(mood)`: **sleep** (arousal+urgency both low →
  eyes close, Zzz, slow deep breath), calm, idle, **roam** (drifts across the floor at moderate
  arousal), **excited** (fast bounce at high arousal). All derived purely from the live mood.
- **GFX**: 5 codex-generated transparent toy sprites adopted into the tray.
- Shipped & verified live on `deucebucket/clanker` (`/toy` returns moving deltas; Playwright
  video confirms breathing/squish/sleep/roam; rattle shows U=210 in the read panel).
- *Community-shared world decor / care economy deferred to M5.*

## M5 — Community economy & governance  *(exploratory / eventual)*
- Caring actions (cleaning up after it, feeding, play, attention) **earn a soft care
  currency**.
- Spend it on toys, cosmetics, room decor (feeds M4's world).
- **Voting / governance** — the community votes on decisions: its name, direction, what it
  gets, possibly moderation of cruelty.
- **Default to a soft in-app currency (points), not real money** — real payments add legal,
  payment-processing, and regulatory weight; revisit a real economy only if explicitly
  wanted.
- *Success:* caring is rewarded, and the community collectively steers the creature.

---

## Cross-cutting
- **W-dimension seam** between clanker-lang and clanker-soul — verify W flows correctly
  before leaning on Worth for care/neglect mechanics (known organism-stack issue).
- **GFX** improves incrementally each milestone; M4 is the final pass. Image assets
  (creature, room, toys — transparent PNGs, etc.) are generated via **codex** (GPT image
  generation), which writes them wherever needed.
- **Audit-first mindset** — anything that affects VADUGWI (chat, care, toys) gets logged
  with its trace, so the whole creature is one big evaluation instrument.