Updated Jul 11, 2026 · Affirmology_AppExperience_MasterPlan_v1.md
Built 2026-07-11 (Cowork, Jeff's supercharge session). This doc is the LEAD for the app experience
workstream: it synthesizes Jeff's 7/11 download (three voice notes + the reports/help addendum) with
everything already decided and built across the workspace, so this chat can drive while Jeff works
with Code. It does NOT fork the roadmap: build order still follows
Affirmology_AudioPossibilities_Map_v2.md (Wave 1/2/3); this doc is the UX and organization layer
on top of it.
Reads with: Affirmology_AppProduct_Principles_v1.md (START THERE: the product principles from the
brand work, 7/10), Affirmology_BrandMessaging_Synthesis_v1.md (positioning: a DAILY ALIGNMENT APP,
comp set Calm not Co-Star), Affirmology_AppExperience_NorthStar_Vision.md (the why),
Affirmology_AudioPossibilities_Map_v2.md (the what and when),
CLAUDE OUTPUTS/Affirmology/Affirmology_Gamification_v1.html (constellation seed),
Affirmology_FoundingPreview_and_Hub_Spec_v1.md (what is live this weekend).
Standing rules apply throughout: everything chart-driven, style shared content never shared, all audio through our engine with QC, no em dashes, retention through real felt value never anxiety.
Four principles from the brand work govern every screen in this doc (AppProduct Principles, 7/10): 1. The pull is being SEEN, never the streak. Gamification is scaffold around the drug of accurate recognition, not the drug. If a screen makes someone feel managed rather than met, it is wrong. 2. Recognition, not inflation is the QC question for every written line: true about them right now, or a wish? Wishes bounce. 3. Depth is opt-in. Ease is mandatory. (This is exactly the Listen-simple / Explore-deep split.) 4. Progress is accrual, never loss. Constellations fill; they never break.
_CHAT_SYNC.md line ~632): official post-beta nav = THREE bottom
tabs, Explore / Listen / Oracle, Explore on the left holding everything else. This doc specs it.Affirmology_ProactiveOracle_ConversationStarters_Spec_v1.md),
feedback question bank (Affirmology_FeedbackOracle_QuestionBank_v1.md), the Habit Engine + testing
kit (Map v2 sections 2 + 4), the constellation-as-spine gamification (Gamification doc + North Star
section 4), the relationships viral loop (North Star 7b).affirmology-studio/affirmology-agent/.../agents/pdf_chart_svg.py (Western wheel, HD bodygraph,
Gene Keys four-gift spheres, Vedic South Indian square, numerology diamond, five-system synthesis
diagram); the synastry + Penta relationship engine (chart/relationship.py); the Understanding
(7-8k words, 12 fields, stored for every profile, ~$0.20 to build); /render-verbatim; /api/compose
with cost brakes; library ingest to app accounts; 12 gold zodiac constellation SVGs (zodiac/).Monday = "your full experience opens." Full does NOT mean all of Explore. Monday-critical:
Everything below is written so Code can build v0 Monday and the rest in waves.
Bottom bar, always present: EXPLORE (left) | LISTEN (center, default) | ORACLE (right)
Rule of thumb for every future feature: if it is a daily habit surface it lives in Listen, if it is conversational it lives in Oracle, everything else enters through Explore. When in doubt, Explore.
pause_preference (normal / wide) and honor it on the NEXT render of that
type. Do not re-render existing audios for it./render-patch engine feature: given a stored script + one edited beat, re-voice ONLY that beat
verbatim and splice it into the existing mix at the beat boundary. Token cost near zero, voice
cost = one sentence. This is how a limiting-belief line or a fixed metaphor updates an audio the
person already loves without losing anything. (Honors "iterate, don't regenerate.") DATA/Studio owns.The completion moment stays a CELEBRATION (Fogg), so keep it to two taps max on screen one:
Decision recommendation on Jeff's open question: keep Oracle PURE. No feature menus up top. The histories, reports, oracle roster, and synthesized artifacts all live in EXPLORE. Oracle gets ONE thin affordance: a small history icon (past conversations, scrollback) and the starter chips that are already spec'd. Reasons: the chat is our differentiator because it feels like a relationship, not a dashboard; and every "organizational" need it has is Explore's job by the rule in section 1.
What Oracle DOES get:
GET /api/app/chat/starters): chart hooks, transit hooks, and,
per Jeff's ask, FEEDBACK asks ("I noticed you've had The Mirror three days and haven't told me how
it landed. Want to?") and journey nudges. The Oracle is the app's proactive voice.Affirmology_VoiceTools_FishAudio_Eval_v1.md).
Standing rule holds: voicenotes = TRANSCRIPT ONLY, raw audio never retained. Build: a custom mic
button inside the composer bar (record → transcribe → editable text in the box). Interim = Whisper
API call from the app; native Parakeet module when the dev's piece is ready.Explore opens as a scrollable index of SECTIONS (cards/rows). v0 ships rows a, b, c, i, j live and the rest as forming cards. Order on screen:
The rotatable sky. First constellation filling; the other 11 zodiac shapes dim in the field.
Where new audios come from (we are not pushing a million audios; they request as they go): - Rows by SLOT (morning, midday, visioning, sleep, reading) and by KIND (from the S-index: micro, deep session, reading, journey chapter). - Each option = a named structure card (S-index) with a one-line promise and "Request this" which enqueues a render (respecting weekly credit allowances, section 7.4). - "Surprise me" = the engine picks from what it knows about them (adaptive default). - v0 = 3-4 requestable types max (Daily Pair variants, one reading, one micro). The menu grows as structures come online per Map v2 waves.
Multi-modal arcs (readings + soul songs + somatic + practices) through a life context. The catalog (consolidated from the use-case docs; roughly ranked by expected demand): 1. Wealth + prosperity (S18 exists as spec; the 72-min wealth reading proves the depth) 2. Relationships: romantic (synastry engine built) 3. Purpose + career/vocation 4. Self-worth + confidence 5. Health, energy + body 6. Family + parenting (incl. parent-child charts) 7. Life transition / "what season am I in" (transit-driven, S15 Threshold) 8. Healing a named block (S1 Rewire Arc / S20 Belief Surgery lane) 9. Deep Gene Keys journey (Activation → Venus → Pearl; the North Star build list) 10. Deep Human Design journey (your story + usable tools) 11. Deep Vedic journey 12. Shadow work / dark night (Gentle Arc guardrails apply) 13. Grief + loss (crisis research exists) 14. Business partnership + team (Penta; also a B2B seed) 15. Creativity + expression 16. Spiritual awakening / deeper meaning (Twelve Rooms S16 lives here) Each journey card: what it is, how long, what forms it uses, its constellation (5.4), entry state (available / forming / invite-your-person for relationship ones).
Jeff's reports addendum, resolved cost-effectively:
- Chart visuals, OUR branding: one screen, five tabs: Human Design bodygraph (defined/open
centers), Western wheel, Vedic square, Gene Keys map, Numerology. REUSE pdf_chart_svg.py: it
already renders every one of these as branded SVGs from the stored chart. Wrap it in one Studio
endpoint GET /api/blueprint-graphics/{person} returning the SVG set; the app renders SVGs
natively. The sixth panel = the five-system SYNTHESIS diagram (also already built), which is our
signature view no competitor has. (Answer to "which system am I leaving out": none of the five;
the missing piece was the synthesis view itself. Astrocartography can be a later seventh.)
- Written sections under each visual: shape from the STORED UNDERSTANDING (never re-run the
council): one Haiku/Sonnet formatting pass per system extracts "your Sun sign/house/degree, your
type/authority/profile, your keys, your numbers + a paragraph of what it means" into structured
text, cached forever on the profile, appended when the Understanding grows. Cost: pennies per
person ONCE. This gives the study-minded their text layer without the PDF pipeline's complexity.
- Highlights: the one_liners + aha_moves fields of the Understanding surface as "your highlights"
cards. Already written, zero new cost.
- Insights: the saved Oracle conversation takeaways (3) + future deep reports live here.
- Progressions/transits text: "What is moving now" panel, from the transit engine, refreshed
weekly/on events. This is also the paid in-season hook later.
- Deeper on-demand written reports ("what is really on for me right now") stay CHATBOT-FIRST for
now (the Oracle can already do this corpus-grounded); a "save as report" button turns any such
answer into a stored Insight. Do not build a separate deep-report generator yet.
Per North Star 7b, surfaced not reinvented:
- Add a person: name + what they are to you (romantic / family / business / friend) + birth data if
known (else "no birth data" mode: context-only guidance through the user's OWN chart, e.g. their
Venus sequence and family houses; honest labeling of what we can and cannot see).
- Outputs: a synergy read (chat first, then a reading, then a two-person audio), business pairs can
later render the Penta view (engine supports it).
- THE VIRAL LOOP: revelations ABOUT the two of you unlock fully when the other person joins; one
button sends them a personal invite; they arrive to their own Origin + the relationship piece
already waiting. Codes/links reuse the /r/ tracked-link machinery that already exists.
- Privacy: entering someone's data = user's own exploration; SHARING requires the person to join
(the consent gate). Keep this language everywhere.
Affirmations to speak, journaling prompts, tapping how-tos, manifesting techniques, micro-practices. Chart + context personalized, refreshed by the Mindset Ninja agent (North Star 6b) as she comes online; v1 can be a static personalized set shaped from the Understanding. Each card: do-it-now body, "why this, for you" line, and a done-tap (counts toward constellation fills where relevant).
Jeff's voices section:
- Audition shelf: named candidate voices (Fish + ElevenLabs; the registry is
Affirmology_VoiceRegistry_v1.md), each with a 20-30s standard sample rendered ONCE from a fixed
house script (not per person). Users: play, speed-toggle, thumbs up/down + "would you want your
readings in this voice?" Kills duds fast, feeds the voice roster.
- Per-person voice preferences: chosen voice per audio TYPE (female soul song voice, male readings
voice, etc.) saved to profile, honored at render.
- SPANISH shelf: 2-3 Spanish candidates (Fish s2 handles Spanish; test first), same audition flow.
First expansion language; our tester base skews Spanish-speaking.
- OWN-VOICE experiment (flagged, later): Fish voice-clone from a reading sample, one test audio in
their own voice. Consent copy + expectations ("some people love it, some hate it") + QC gate. Run
as an A/B experiment with a handful of volunteers, not a default feature.
Affirmology_Olga_Rectification_v1.md). Wave 2-3 build; the AVOIDANCE rule is
Wave 1 (it is a render-side filter, cheap)."How to use this app well": the daily rhythm, how to talk to your guide (including voice notes), what the constellation is, how feedback shapes your audios, how to request new audios. Text first, short videos slot in later (the wiki/walkthrough assets from the weekend plan feed this). Also the support path (Hermes voice → hello@affirmology.ai, already built in chat).
Seeded from the Gamification doc + North Star section 4; this section makes it buildable.
Jeff's spec, refined: - 5 stars = the 4 daily moments (morning, meditation, movement, before sleep) + the weekly reading. - Each star fills in 7 fractions; one fraction per day that slot is completed (max one/day/slot). Misses don't reset; the star holds its fill (building the habit, not punishing). - When a star completes it IGNITES (bright, named). When two ADJACENT stars are lit, the line between them draws itself. All 5 lit + lines = the full figure of the Ram fades in around them (the constellation art moment) + the completion ceremony. - Completion reward (per the Gamification doc's headline mechanic): ACTIVATE YOUR GUIDE. Completing Aries unlocks choosing a Wisdom Council member as their personal guide (the customer-facing voice Sophia/Hermes bring forward). This drives base-audio consumption, makes the guide feel earned, and prevents day-one choice overload. Plus: their week-in-review "release notes for the new you" (which doubles as the day-7 feedback ask + the SOS v2.0 version bump). - Why Aries first: first of the zodiac, action + initiation. On completion the sky rotates and the other 11 shapes become visible territory.
zodiac/ asset set).New guide activation (the headline), a deeper reading, a ceremony audio, chatbot create-credits, early access to new structures, a shareable constellation badge (5.6), bonus deep-journey sessions. One reward table lives with the constellation config so it is data, not code.
THE CURIOSITY GAP DOCTRINE governs (Sol, locked in the brand synthesis): we never publish the audio, we publish the REACTION. So shareables are: the branded constellation card (their constellation, their name, one line from their chart), the day-7 release notes, reaction moments. NO audio snippets in shares, ever; the product stays unheard and the only way to hear it is to get your own. Pride for them, intrigue + a personal link for the friend (ties into 4e's loop).
Needed per zodiac constellation (start with Aries only):
1. Star-field base tile (deep emerald #0a2014, faint nebula, our palette; seamless pan).
2. The constellation in 4 states: dim points → stars igniting (per-star glow sprite) → gold lines
drawing → the full mythic figure faded in behind (marble-and-gold Hellenistic style matching the
council busts; the existing zodiac/ SVGs are the line-work base layer).
3. A star-ignition micro-animation (one reusable sprite/lottie) + a completion ceremony moment.
Prompt style: reuse the locked visual language (emerald/gold/cream, Cormorant, painterly
constellation figures per the Affirmology_GraphicsLibrary_Handoff_v1.md system). Static PNGs +
one sprite is enough for v0; video flourishes later.
This IS the three-move product story from the brand work: pick your context, get your suite, listen and align. At entry (or day 2): "What are you actually working on right now?" ONE pick: Wealth / Love + relationships / Purpose + work / Health + energy / Peace + confidence. The initial suite is then rendered with that context woven in (the context layer the beta group needs to feel: they already know their chart; context + transformation is what will impress them). Week 2: the Oracle refines it in conversation. - THE ASK COPY (approved, use verbatim at the first habit prompt): "We ask you to listen every day, because becoming is not a decision. It is a repetition. One listen will move you. Thirty is when you stop having to try." (The because must stay mechanistic; the Langer research says a large ask needs a real reason.) - THE LAYERS FRAMING (critical, Jeff 7/10): layers 2 and 3 (transformation tools + context) are never presented as unbuilt. The line is: "We have not added your life. Not because we can't, because you have not told us yet." Every context ask, discovery conversation, and upgrade moment is an invitation to be known more fully, never a paywall pitch.
One named block, in their words (this already exists at intake per Map v2's block-intensity metric; this makes it a visible object in Explore). The app SHOWS which audios will respond to it: "Your belief is being worked in: tonight's Night Install (reconsolidation pass), your EFT micro, your visioning." When /render-patch (2.2) exists, a belief update can patch one line into an existing loved audio for pennies. The block-intensity 1-10 at d0 and d7 measures it. One block at a time.
The 4h request lane feeds a weekly triage pass (agent): cluster, compare against roadmap + vision, surface the 3 that matter with who-asked and why. Never auto-promise anything in-app.
| # | Item | Owner |
|---|---|---|
| 1 | Daily Pair + feedback 2-tap (Map v2 floor, unchanged) | DATA renders + Code app taps |
| 2 | Listen tab reshape: Today rail (time-of-day cards, patch-note lines, pending badge) + library | Code |
| 3 | Explore tab v0: section index; live = Constellations (Aries), Get Audios (minimal), Feedback Hub, Profile (thin), Help; rest = forming cards | Code (UI) + Cowork (all copy) |
| 4 | Aries constellation: 5 stars x 7 fills, fill events from play-completions | Code |
| 5 | Playback rate control + per-type saved rate | Code |
| 6 | One-context pick at first open (writes to context_store) | Code + DATA |
| 7 | Time-sensitive-structure filter for unsure-birth-time profiles | DATA |
| 8 | Help/Get Started + all Explore copy + patch-note templates | Cowork |
| 9 | Status banner (manual flag + outage copy) + request-state labels | Code (component) + Cowork (copy) |
Overnight-delivery reveal flow + notify-me (email interim, push later), automatic status-flag wiring, Blueprint charts endpoint + screen (SVG reuse), written blueprint sections from the Understanding, Voice Lab (auditions + Spanish shelf), mic-next-to-send (Whisper interim), Oracle starters if not already in, A/B distributor + "try version B" cards, feedback-log "what changed" loop, /render-patch engine spec, Limiting Belief box, second + third constellations (Taurus or context-picked), request desk expansion, birth-time rectifier flow.
Relationships section + viral invite loop (spec 4e), Penta view, system constellations (GK/HD/Vedic), shareable badges + snippets, Mindset Ninja practice engine, own-voice experiment, dance/music tracks, hard-mode constellations, Spanish full experience, creator/Affirmologist dials.
Beta users must never stare at a spinner wondering if we broke. One reusable STATUS BANNER component
(app-wide, driven by a tiny GET /api/app/status flag the team or the backend can set):
- CREDIT/OUTAGE state: "A note from the team: our audio engine hit a temporary limit on the backend.
Your audio is queued and WILL be created. This is beta; kinks like this get worked out. Check back
in a bit, or we'll let you know." Warm, honest, on-brand, zero fake progress.
- DEGRADED state (slow renders): "Renders are running slower than usual right now; yours is in line."
- The flag can be set manually (an admin endpoint) at first; automatic detection (the credit-error
detector already exists in self-heal) wires in later. The graceful-failure work on the results page
(7/4) is the same philosophy; this brings it in-app.
- Per-request status: every requested audio has a visible state in Get Audios: QUEUED → CREATING →
READY (→ or WAITING ON THE ENGINE during an outage).
Renders are per-person and can trail the journey by a day (Map v2), so make the LANDING an event: - Overnight ingests (via /api/library/ingest) mark audios NEW; the app badges Listen ("1 update pending", the native Zeigarnik loop) and the Today rail shows the new card with its patch notes. - "NOTIFY ME WHEN IT'S READY": every request card carries it. Until push infra exists, this = the daily email carries "your new audio landed" (email is already the interim cue carrier per Map v2); when push notifications come online (Wave 2-3), it becomes a real push, and later the anchor-word push rides the same rail. - The reveal motivates exploring: a landed requested audio deep-links into Explore > Get Audios with a gentle "want another? here's what else can be built for you" row. Request → wait → reveal → request again is itself a habit loop, and an ethical one (real value each cycle).
Later there are account tiers (member / creator / etc.) and audio credits (included + purchasable) governing request volume. Do NOT build the economy now; DO log every request/render against the person with a cost estimate (the engine already tracks render cost), so when credits arrive the ledger and habits already exist. Beta = generous visible allowance (7.4), which doubles as the credits UI dress rehearsal.
Jeff's direction, captured so it is not lost:
- PROBLEM: Jeff currently gets more creation utility from Claude Code sessions than from Atlas.
Atlas must become the attuned lab: create/tweak audio structures conversationally through
Hermes AND through direct dials, no Code session required.
- DIALS: the full per-audio metrics set from North Star section 12 (identity strength,
transformation strength, energy/intensity, pacing, emotional tone, techniques employed, stage,
time-of-day, theme, duration, modality lean, voice, bed, repetition role) as adjustable controls
on every draft, adjustable directly or by telling Hermes.
- THE TECHNIQUE BROWSER: a browsable, clickable LIST of every transformational tool/technique in
the corpus (the 339+ craft entries + the S-index structures), each with a paragraph of what it is
and when it serves; click to include it in a build. New corpus findings flow in automatically
(the corpus IS the memory; Atlas becomes its visible shelf). Favorites, test combinations,
retest, dial in, get suggestions from Hermes.
- PIPELINE: draft in Atlas → test render → listen → tweak → PUSH to (a) your own app library,
(b) a named person's library, or later (c) a community/creator audience. Same engine, same QC
gate, always.
- CREATOR ACCOUNTS (the tier from 11.3): graduated complexity. The consumer app stays streamlined
with decisions made for you; power users upgrade to creator level and get Atlas access to build
for themselves and their communities (the Affirmologist path). App = simple; Atlas = the lab.
- This becomes its own spec doc when the build starts (working name:
Affirmology_AtlasCreatorLab_Spec_v1.md); the existing Atlas decisions (PROJECT_STATE 17b,
permission tiers, voicenote transcript-only) still stand.
Housekeeping: this doc is the app-experience lead; PROJECT_STATE points here. Update section 10's wave tables as items ship. The S-index stays in the Possibilities Maps; journeys catalog (4c) may graduate to its own doc when journeys build starts.