docs/ROADMAP.md

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.