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 — FINAL (Byron 2026-08-30): two host voices, opposite temperaments, toggle at onboarding:

• Native (default) — Byron's own cloned voice at ~1.3× his natural pace (demo). The app's system voice for every user until their own voice is cloned and chosen.
• Her — an entirely different voice: very calm, soothing, slowed down — the Her register (Scarlett-Johansson-adjacent as inspiration only; no real-person voice replication — likeness rights). Rendered from the fleet's Rue reference (~/rue-cohost/rue-voice-sample.wav, ex 0.35) and slowed: candidates calm 0.92× · slower 0.85×. The pitch-shifted "female Byron" is scrapped.
• Toggle label: Native · Her (+ You after absorption). Pacing is part of the identity: Native is brisk (1.3×), Her is unhurried (~0.9×).
• Voice campaigns: the sent-clone envelope gains host_voice: "native"|"her" so different campaigns/links can test different host voices; the after-action digest reports which voice ran.
• The endpoint line and twin replies always use the user's own untransformed clone regardless of host choice — the proof-of-clone beat is never the host.

---

2c. Field-test rules (Byron's first live run, 2026-08-30 — binding)

• The interview is hands-free by default. Every question is spoken aloud (all 8 pre-rendered per theme × host voice) and shown as large readable text. After the question plays, the app listens; once you've spoken (~2s of speech energy) and then paused (~2.2s silence, noise-floor calibrated), it acknowledges and asks the next question itself. No Enter, no tap. Tap-to-advance and Skip remain overrides; typed mode stays first-class without a mic. Listening caption: "Answer out loud — I'll move on when you pause."
• Contrast is a hard rule: in dark appearance every headline/status renders in the theme's warm off-white ink — never a dark tone on dark. The meter card gets a solid scrim and lives in a face-safe zone (face upper ⅔, meter lower ⅓, no overlap, ever).
• The face-focus mask is feathered (~24px falloff) — a focus effect, never a hard-edged cutout.

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.**

Appearance axis — light & dark (Byron 2026-08-30: "I'd like the option of the light or dark skin")

Appearance is orthogonal to theme. Two axes, four combinations, one interface:

• Implemented as CSS custom-property sets (--bg/--surface/--ink/--accent…) per (theme, appearance) pair — the manifest's palette becomes palette.dark + palette.light.
• Appearance control: ?mode=light|dark URL param → localStorage → prefers-color-scheme → theme default. Toggle sits beside the theme switch.
• Camera stages force their own treatment regardless of appearance (the face-focus composite defines those screens); light mode softens to blurred-cream instead of blurred-black (mockup 12 shows exactly this).

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).

---

4b. Sent Clones — Conversation Mode + the scope envelope (Byron 2026-08-30)

The idea: sending your clone to someone is just sending a URL (text, email, QR). The recipient opens it and is face-to-face with an instance of you — full-screen talking head, mic-first, one-on-one. But every sent clone travels inside a scope envelope: a mission plus explicit switches for what this instance knows and refuses.

This is also the chosen smoke/user test: the first real-world exercise is Byron sending a scoped clone ("just Byron's AI knowledge") to one real person and watching the conversation hold its boundaries.

The two surfaces

• Send a clone (owner side, mockup 15): one-line MISSION ("Talk AI engineering with Marcus. Be helpful, be me."), SCOPE SWITCHES (AI & ML knowledge ON · Career history ON · Personal life OFF · Family & PII OFF — hard-locked, can never be enabled for sent clones · Opinions on employers OFF), a guardrail preview showing the exact refusal voice, expiry (default 7 days), spend cap (default $1.00 per sent link), then a share pill — clone.arnao.ai/c/<slug> with Copy / Text / Email / QR.
• Conversation Mode (recipient side, mockup 14): the clone fills the screen and talks; a slim always-visible banner declares what it is and its scope ("You're talking to Byron's clone — scope: AI & ML topics only"); mic-first composer; a quiet report/end link. Disclosure is structural, not optional — the banner cannot be dismissed (front-door brand rule + RAI posture).

Architecture — the envelope is enforced server-side, never in the prompt alone

A sent clone is a policy record, not a fork of the persona:

sent-clones/<sub>/<slug>.json = {
  slug, owner_sub, mission, created, expires,
  scopes: { ai_ml:true, career:true, personal:false, pii:false, employer_opinions:false },
  capabilities: {},                  // agency axis (M3) — ships empty/all-OFF; knowledge and action permissions never conflate
  refusal_line,                      // the theme-voiced "I really can't get into that…"
  cap_cents: 100, spent_cents, revoked:false,
  transcript_retention: "summary"    // owner sees a digest, not necessarily raw logs — decide in build
}

• Layer 1 — corpus filtering at build time: the instance's system prompt is assembled from only the persona blocks + confirmed facts whose tags fall inside enabled scopes. Knowledge that's OFF is absent from the context, not merely forbidden — you can't prompt-inject a model into revealing what it was never given. This is the primary defense.
• Layer 2 — policy in the prompt: mission + scopes + refusal line, so the clone declines gracefully and in-character ("this clone is just here for AI talk").
• Layer 3 — output gate: a cheap classifier pass (Gemini Flash / GPT-5.6 Luna) screens replies for out-of-scope leakage (names, employer opinions, PII patterns) before streaming completes; on trip, replace with the refusal line. Belt for the braces.
• PII is a hard lock: the PII/family switch renders locked-off in the composer and the server rejects any envelope with pii:true. Not a preference — an invariant.
• Chat rides the existing published-clone path (/api/chat already allows anonymous visitors on published clones, now rate-limited): the slug resolves to owner clone + envelope; per-slug metering against cap_cents; expiry and a revoke kill on the owner's clone card. sent-clones/ joins delete-me.js's prefix list (same rule as research data).
• Owner visibility: each sent clone shows on the command center as a live card (who/when/spend/state) with a transcript digest — raw-transcript retention is Open Decision #6 (recipient privacy vs owner curiosity).

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."

---

7b. Screen inventory — the complete mocked set (build exactly as mocked)

Byron approved the renders 2026-08-30: "these are amazing, this is exactly what I want." Layout + copy below are canonical; the renders set the visual bar. Full gallery: https://clone-v3.arnao.ai/mockups.html

Known render artifacts (concept art, not spec): garbled card label on 02; duplicate vote row on 03. The PRD text wins wherever a render and this document disagree.

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).

9b. User panel — four evaluations, accepted changes (2026-08-30)

Four independent reviews of this PRD + all 15 mockups: Dana (57, senior technologist — the target demographic), Frank (61, AI skeptic), Maya (AI power-user/enthusiast), and a mobile-first UI lead. Full transcripts summarized; the following changes are ACCEPTED and binding on the build.

From Dana (the customer)

• D1 · Cloning (warm) is the default theme. Absorption stays fully built as the toggle — but it greets no first-timer. (Resolves Open Decision 3.)
• D2 · "You can erase everything with one touch" leads the welcome disclosure — headline, not line three. It's the trust unlock for 50+ users, and the delete path must be complete (Bug 3) before it's made loud.
• D3 · The after-action digest is a first-class screen (P2a): "the recipient asked these 4 things; here's what your clone said; here's what to follow up on yourself." The share link is the demo; the digest is the retention loop.
• D4 · "Test my envelope" mode in the Send composer (P2a): adversarially prompt your own sent clone before the recipient can. Productizes the P2a exit test.
• D5 · Copy rewrites applied in §2's table (endpoint warm line, Dossier warm line, capture warm line). Voice reference is harvested from interview answers only — never a "read this passage" step.

From Frank (the skeptic) — the recipient-protection package

The design's blind spot: everything protected the owner from the recipient; nothing protected the recipient from the clone. All accepted:

• F1 · Reverse-image search will not be built. Ever. Tombstone, not a snooze button. (Deletes Open Decision 5.)
• F2 · Verify page (P2a): every /c/<slug> shows creator, created date, expiry, and a checkable "this is an AI clone" endpoint — the banner's promise, provable.
• F3 · "Are you real?" is answered truthfully, always — un-scopeable, enforced in the Layer-3 output gate. No envelope can turn it off.
• F4 · Watermarking: audio already carries Chatterbox's PerTh watermark (on by default in v3 models — verify in build); generated video gets metadata tagging; sent-clone video keeps the visible scope banner.
• F5 · Recipient one-tap erase (P2a): a control on the scope banner that deletes the recipient's transcript and confirms it. Same power the owner has.
• F6 · Raw-capture retention: the worker purges absorb-in/ raw face/voice blobs after derivation succeeds; derived artifacts are the only long-lived copies. (Mini disk encryption = ops item: FileVault on.)
• F7 · The P2a adversarial scope test is run by someone hostile, not Byron.
• F8 · delete-me prefix coverage becomes a deploy-time check, not a checklist memory.

From Maya (the enthusiast) — structural

• M1 · Persona becomes versioned, tagged, append-only fact blocks — the canonical store, replacing the static prompt document. Layer-1 corpus filtering already requires tagged facts; this makes growing memory, scope filtering, and evolution timelines all fall out of one change. (P2 foundation.)
• M2 · The killer loop — growing memory ⊕ Mirror: every chat + "was that you?" micro-votes distill overnight (worker pass) into new tagged facts; the meter becomes a lifetime fidelity score that compounds past 100%. "A tamagotchi where the pet is yourself." (P3, designed-for now via M1.)
• M3 · The envelope gains a capabilities axis now (capabilities:{} — all OFF), so agency never has to be retrofitted into a knowledge-only permission model.
• M4 · Backlog, ordered: own-clone API token (an envelope as a bearer token — cheapest), scheduled clone actions, clone-to-clone conversations (scope-intersection rules), voice calls to your clone, group presence, evolution timeline, live events, clone games. Job-queue abstraction (second worker box) is the P3 infra unlock.

From the UI lead — build directives (binding on Opus 5)

1. Keyboard avoidance first (screens 8/10): visualViewport resize handling before anything new — every text input is currently coverable on iOS.
2. applyTheme(themeKey, appearance) runtime swap replaces one-shot resolveSkin() (index.html:365).
3. AudioContext primed in the DISCLOSE tap handler (index.html:433) + on theme toggle; muted-speaker chip fallback; captions always; never block the flow on audio.
4. renderAgentCard(envelope, density) — one renderer, four densities (full / row / banner / mention) — is the only markup for a deployed clone, used on screens 02/04/11/13/14/15. States: draft → live → expiring → expired | capped | revoked, server-derived.
5. Extend every status projection deliberately (Bug 2 applies to sent-clone fields too).
6. Meter is monotonic (Math.max(prev, server) in pollUntilDone, index.html:641) and event-driven; 40/70/90 beats fire once each.
7. Resume-safety: persist {jobId, answers, qi, theme} to localStorage on each advance() (index.html:571); on poll failure show "Connection lost — nothing is lost, the forge keeps working" with the meter frozen, resume from server truth.
8. Preload FaceMesh at DISCLOSE (not camera time, index.html:1044); cap particles ~600 at devicePixelRatio>2.
9. Command center / deployments rebuild as single-column mobile stacks; destructive actions (Revoke / RECALL ALL / Erase) all reuse the press-and-hold ring — the app's signature gesture (with ~30px drift forgiveness, index.html:466).
10. Manifest + minimal real /sw.js (shell + /voice/* only, never API); endpoint voice is never faked with SpeechSynthesis — silent + upgrade-poll instead.

10. Open decisions for Byron

1. Billing: top up OpenRouter (consolidates), Anthropic API credits (direct-API skills), or both? (§0)
2. ~~Host narrator voices~~ — RESOLVED (Byron 2026-08-30): Byron's cloned voice; female-register variant is the default; ~1.3× speed. Both ship, toggleable.
3. ~~Default theme~~ — RESOLVED by panel (D1): Cloning (warm) is the default; Absorption is the toggle.
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~~ — RESOLVED by panel (F1): will not be built. Ever.
6. Sent-clone transcript retention: panel resolves the shape — owner gets the after-action digest (D3) and the recipient gets one-tap erase (F5). Remaining call: whether full transcripts exist at all underneath the digest. Build default: digest-only.

---

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