Clone — Absorption v3 PRD

"It becomes you." Two skins, a living voice, a status bar you can feel, and a clone that already knows you.

Build target: Claude Opus 5 · Creative/plan: Claude Fable 5 (this document) · Architecture critique: folded in (system-architect pass) · Date: 2026-08-29

App: https://clone.arnao.ai · source /Users/byronarnao/clone-mvp · worker /Users/byronarnao/clone-absorb

Predecessor: Absorption v2 proposal (the UX overhaul this builds on)

---

0. Read this first — the billing reality (you don't need new money, you need the right wallet)

You have three separate wallets, and topping up one never funds the others:

Recommendation: top up OpenRouter — it consolidates everything (clone chat + I can re-point the critique skill and worker LLM calls through one balance, at OpenRouter's no-markup token rates), and separately drop ~$20 on the Anthropic API credits only if you want the direct-API skills back verbatim. Neither is your subscription. One-tap: Anthropic API billing · OpenRouter credits.

Why it matters for this PRD: the Mac worker (watch.py) runs Gemini Flash end-to-end — persona, first-line, and any new research summarization. It has no premium path. So "use the default Opus 5 model" (v2 §5) describes the chat path only; the worker needs its own funded LLM route (OpenRouter is the clean answer). This is load-bearing for the research agent below.

---

1. What we're building (on top of v2)

Three things Byron asked for, layered onto Absorption v2:

1. A living voice — the app speaks its beats ("Absorption initiated…") instead of just printing them.
2. Two toggleable skins on one interface — a cold, futuristic Absorption theme and a warm, human Cloning theme. Toggle for giggles; same flow, same code.
3. A background research agent — after your photo, a parallel job quietly assembles what the public web already knows about you, then asks you to confirm each fact before it joins your clone. (Highest-risk feature; owner-only, flagged, P2 — see §5 and the guardrails.)

Plus the v2 backlog and three real bugs the architecture pass surfaced (§6).

---

2. Feature 1 — The living voice

Verdict: sound. One hard constraint: the lines are static, so never run TTS at runtime.

How it works

• Every spoken beat is a fixed string per theme → pre-render once with the chosen host voice, ship as static CDN audio (/voice/<theme>/<beat>.mp3). Zero per-user cost, zero worker load, no Chatterbox on the request path.
• The personalized beats stay dynamic: the endpoint line is the user's own cloned voice (already built — playHello), and the milestone callouts that name the person are rendered by the worker. Everything else is static.
• Audio-unlock gesture (the real engineering problem): mobile blocks audio until a user gesture. The flow's pre-camera gesture is the DISCLOSE tap — prime the audio context there (play a silent buffer). Miss this and the first spoken beat silently fails on mobile. The theme toggle must also re-prime (switching to the warm theme's pre-rendered clips after DISCLOSE needs a fresh unlock).
• Captions are non-optional. The beats carry state meaning; a sound-off or deaf user must still see the state machine. Voice is additive, never a replacement. Keep every on-screen line.
• Fallback: browser SpeechSynthesis is acceptable only for the Absorption theme (robotic is on-brand). The warm theme must use pre-rendered clips — browser voices are uncanny-bad for "human."

The scripts (Fable creative — this is the "say something cool" ask)

Proven already: both hero lines rendered locally today —

Absorption hero (cold) · Cloning hero (warm).

Host narrator voice is a design choice per theme (cold synthetic vs warm human) — distinct from the user's cloned voice, which only speaks the endpoint. Production picks two host reference voices; the demo above reuses Byron's sample at two exaggeration settings to prove the mood range.

---

3. Feature 2 — Two skins, one interface

**Verdict: needs rework. The existing HOST_SKINS cannot carry this — it swaps one CSS var (--accent) and six copy strings. You're renaming a product, not recoloring an accent.**

The theme manifest (replaces the 1-var skin for this axis)

THEMES = {
  absorption: {
    term:  { verb:"absorb", gerund:"absorbing", noun:"absorption", done:"Absorbed." },
    palette: { bg:"#05070a", accent:"#4fd6e0", type:"grotesk, wide-tracking" },  // cold monolith
    voiceSet: "absorption",       // → /voice/absorption/*.mp3
    soundscape: "low-sine-drone + single tone on lock",
    copy: { ...full per-beat strings... }
  },
  cloning: {
    term:  { verb:"clone", gerund:"cloning", noun:"clone", done:"Here you are." },
    palette: { bg:"#0f0b08", accent:"#e0a24f", type:"humanist, soft" },          // warm (≈ current default)
    voiceSet: "cloning",
    soundscape: "warm pad + gentle chime",
    copy: { ... }
  }
}

• Terminology substitution flows from term across all UI copy AND anywhere the literal word "absorption" is currently baked into state/status strings. (Worker stage names — developing/voice/avatar/persona — stay internal; they're never shown, so they don't need renaming. Only user-facing copy reads from term.)
• State & precedence: extend the existing three-tier resolveSkin() pattern (URL param → env default → neutral). New order: ?theme= URL param (shareable) → localStorage (sticky between visits) → env default → cloning.
• Live toggle ("for giggles"): a corner switch that re-renders palette + copy + re-primes the audio context and swaps the voiceSet without reloading. resolveSkin() runs once in boot() today — the toggle needs a applyTheme(key) that's callable at runtime, not a one-shot setProperty.
• The warm Cloning theme is close to today's amber palette, so it's the cheaper of the two to land; Absorption is the net-new cold skin.

---

4. Feature 3 — The Dossier (background research agent)

Verdict: risky. Build P2, behind an owner/admin flag, identity-asserted, reverse-image OFF. Three of the ask's load-bearing claims are false or unenforceable against the current code — corrected below.

The experience (when it's earned)

While your face and voice absorb, a second track — the Dossier — quietly searches the public web for you and returns confirm cards:

> "I found this. Is it you?"

> AI/ML engineer at AWS, Responsible AI — source: linkedin.com/in/… — [Yes, that's me] · [No] · [Skip]

Only cards you tap Yes on join your clone's persona. Each card cites a source URL. The Dossier sub-track fills the status bar alongside Face/Voice/Mind.

Corrections to the ask (architect pass)

1. "Runs in parallel" was false. The worker (watch.py) is strictly sequential — one job at a time inside process_job. A research stage would add 10–60s to the critical path and, if a search hangs, strand the user behind the 20-minute stale timeout. → Build it as a separate research-jobs/ record claimed by a second worker loop, genuinely concurrent with absorption.
2. "Researching themselves" is an unenforced assumption. Nothing verifies the photographed face is the logged-in user — so as-proposed it's a stalking tool (absorb a stranger's photo → research + reverse-image them). → **Key research to asserted identity only: claims.email + claims.name from the signed session + what the user explicitly types** ("I'm an AI engineer at AWS"). This eliminates reverse-image search as an input entirely. Reverse-image, if ever, is isAdmin-only and disabled, not merely defaulted off.
3. "Cheap under the cap" was unbudgeted. Search + summarization per absorption is a real cost, and the worker has no premium LLM. → New metered op COST.research, its own BURST_PER_MIN entry, charged at create-time, summarization routed through the funded OpenRouter path.

Guardrails (all mandatory)

• Compliant search only. Use the fleet's existing Brave Search API (BRAVE_API_KEY, already used by generate-rai-content.py) or the harness search agent. Never scrape LinkedIn/Facebook/Reddit directly — their ToS ban it and the IPs get blocked.
• Provenance mandatory, exclusion default. Every claim carries a source URL; any claim not explicitly confirmed is excluded, not pending-included.
• Persona prompt restructured, not appended. gen_persona today commands "do not invent biography" (watch.py:208). Appending research contradicts it → confidently-wrong facts the user rubber-stamps. Confirmed facts go in a separate "verified facts" block with its own grounding rule.
• Third-party safety. Findings may name other people ("you work with Jane at AWS"). Cards that name third parties are generalized or dropped, never stored with the third party's identity.
• Deletion. research-jobs/ and any research derived/ path must be added to delete-me.js's prefix list in the same PR that creates them (see Bug 3).

---

5. The status bar — the Absorption Meter

One hero number, decomposed into what's being taken. This is the "I want to see how much has happened and how much is left" ask.

  ABSORBING  ▓▓▓▓▓▓▓░░░  68%
  Face ✓   Voice ▓▓▓░   Mind ▓▓░░   Dossier ▓░░░

• Headline % = weighted sum of four sub-tracks, each 0–100:
• Face — capture done = 100 (instant).
• Voice — banked clean-speech seconds toward the 18–20s floor, then worker encode (stages 30→60).
• Mind — interview answers (each of 6–8 questions) + worker persona (stages 85→90).
• Dossier — research job progress + confirm-cards resolved (P2; hidden/zero when the flag is off).
• Tied to the real worker stages via absorb-status; the bar only moves on actual server progress, never a fake timer. The v2 "holding beat" covers slow renders.
• The spoken milestone beats (40/70/90%) fire off this same number.

---

6. Bugs the architecture pass found (fix in P0, before anything new)

1. Metering is dead-code-wired. absorb-create.js:32 charges a hardcoded ABSORB_CENTS = 8; _meter.js COST.absorb is never read on this path. My v2 "raise COST.absorb to 15" edit would do nothing. → Fix the literal in absorb-create.js (or make it read COST.absorb). Real absorption cost ≈ 13¢; chat turn under the new tokenizer ≈ 1.7¢ not 1¢. Re-price both so the $1 cap means what it says before adding the metered research op.
2. jobView() is an allowlist — new fields are invisible. absorb-status.js:25-43 projects a fixed field set; every new field (v2 heartbeat, voice-early stage, research summary, theme) is silently dropped until jobView is extended. → Make "extend jobView" an explicit line item for every new job field, v2 and v3 alike. This is the #1 "we built it and the UI shows nothing" trap.
3. Deletion retains data it didn't ship with. delete-me.js:46-50 deletes a hardcoded prefix list. Any new prefix (research-jobs/, research derived/) survives "delete my clone" — and research data is the one category that names non-consenting third parties. → Register new prefixes in delete-me.js in the same PR; make it a checklist gate. Sharpest legal exposure in the plan.

---

7. Data schema additions (Blob)

• Absorption job (absorb-jobs/<sub>/<id>.json, bump schema:1→2): add theme (active manifest key), heartbeat (worker liveness echo, v2), research_job_id (pointer, nullable).
• Research job (new, research-jobs/<sub>/<id>.json): { schema, sub, jobId, status, claims:[{ text, sourceUrl, sourceType, confidence, decision:"pending"|"confirm"|"reject", namesThirdParty:bool }], summary, error, updated }.
• Confirm/reject posts to a new endpoint → writes decision into the research record; the second loop's persona-merge reads only confirm claims.
• Worker heartbeat (v2, derived/_worker/heartbeat.json or similar): written every cycle; absorb-status exposes it so the UI tells "still cooking" from "the forge is cold."

---

8. Phasing (what Opus 5 builds, in order)

Do not let Feature 3 ride P0's coattails. It's the one feature that can turn a consented self-portrait into an abuse tool.

---

9. Build notes for Opus 5

• Stack: zero-build static HTML + Vercel Node CommonJS serverless + @vercel/blob; worker = Python watch.py polled by loop.sh (relaunch after every reboot — TCC blocks launchd; a real restart-survival mechanism is worth adding).
• Deploy: bash ~/.claude/skills/vercel-deploy/deploy.sh ~/clone-mvp clone --project clone-app.
• Verify from the external user vantage each phase (entry → auth → absorb → twin speaks in your voice → $1 cap negative test → mobile audio unlock) before "done."
• Critical files: api/absorb-create.js · api/absorb-status.js · api/_meter.js · api/delete-me.js · clone-absorb/watch.py · index.html (HOST_SKINS + resolveSkin, ~279–374).
• Auto-update the info.arnao.ai card on ship (frontdoor-catalog skill).

10. Open decisions for Byron

1. Billing: top up OpenRouter (consolidates), Anthropic API credits (direct-API skills), or both? (§0)
2. Host narrator voices: pick two reference voices — one cold/synthetic (Absorption), one warm/human (Cloning) — or reuse a single voice at two exaggeration settings?
3. Default theme on first visit: Absorption or Cloning?
4. Dossier reach: even owner-only, cap it at Brave web search — or also allow you to paste specific profile URLs to summarize?
5. Reverse-image search: keep it fully disabled (recommended), or owner-only behind a second explicit flag later?

---

11. Research & evidence

Talking head: FasterLivePortrait-MLX (proven 47.9s local). Voice: Chatterbox (local, $0). Interview science: Stanford genagents (finite interview ≈ 85% fidelity). Search backbone: Brave Search API (in-fleet, generate-rai-content.py). Meet stand-in (v2): joinly. Models: refreshed benchmarks.

Links