---
name: happycouple-moment-flow
description: Product and implementation workflow for HappyCouple's moment-based relationship coaching flow. Use when Antoine asks to refine HappyCouple positioning, landing-page copy, onboarding, session prompts, or code around the “How can I help your relationship today?” / under-2-minute concrete relationship moment wedge.
tags:
  - happycouple
  - product-strategy
  - landing-page
  - nextjs
  - prompt-design
---

# HappyCouple Moment Flow

## When to use
Use this skill when working on HappyCouple product strategy or implementation, especially:
- Repositioning away from “AI couple therapy” and toward relationship coaching / immediate relationship value.
- Designing the landing page, onboarding, or first session.
- Editing the agent prompt for prescriptive relationship guidance.
- Deciding between broad relationship promise and narrow first-use wedge.
- Updating the codebase at `/Users/antoinelevy/Documents/Code/coupletherapy`.

## Core product stance
1. Brand promise can be broad: help users handle their relationship better.
2. First-use wedge must be concrete: help with one specific relationship moment in under 2 minutes.
3. Antoine's 2026-05-26 Reddit takeaway: there is clearly a `help me write my text` angle, and the product value after signup must be much clearer/faster. Treat this as the primary cold-user artifact until real usage proves users want broader coaching first.
4. Preferred first artifact: a text/message the user can send, with 2–3 tone variants and a compact explanation of why it works. Broader understanding/reporting comes after the sendable text exists.
5. Preferred line: “Handle your relationship better, one moment at a time.”
6. Preferred entry prompt: “What are you trying to say?” or “Paste the situation. Get the text.” can outperform a broad “How can I help your relationship today?” when optimizing for fast value.
7. Show visible example problems/suggestions so the open-ended input does not feel blank or generic.
8. Do not lead with “therapy,” “couple therapy,” long reports, dashboards, relationship maps, or weekly meetings for cold users.
9. Deeper support — partner loop, pattern tracking, longer check-ins, reports — is a later/retention layer, not the first value prop.
10. The landing page can still explain the broader product, but only after the immediate text/moment-first hero. The long-term CTA should anchor to a section like “Beyond the first text” / “From one hard message to a clearer relationship,” not open a distracting hero-side preview. Good product sequence: Text/message draft → optional explanation → save/copy → follow-up/check-in → report/pattern → partner loop → relationship map.

## Agent behavior requirements
The agent should not behave like generic relationship ChatGPT. It should:
1. Start from one concrete situation or moment.
2. If the user is vague, force concreteness gently.
3. Classify the problem silently, e.g. conversation prep, repair after fight, recurring pattern, apology, anxiety/overreaction check, reconnection, practical disagreement, or deeper check-in.
4. Ask at most 1–2 clarifying questions before giving value.
5. Explain what may be underneath the moment.
6. Recommend what to say/do next.
7. Say what to avoid so the user does not make it worse.
8. Offer a deeper next step: practice conversation, invite partner, track the pattern, or do a longer check-in.
9. Stay coaching/education oriented; do not present as therapy or diagnosis.
10. Be prescriptive without commanding: offer clear recommendations and invite reflection.

## Landing UX direction learned from implementation
1. The landing page should become the first product experience, not a brochure that immediately routes away.
2. Keep the pod as the emotional centerpiece. Antoine liked the simple voice-first pod; do not overcorrect into generic split-panel SaaS unless he asks.
3. Best first interaction: click/tap the pod or “Start with voice” and transform the hero in place into a short moment session.
4. Avoid sending the user to onboarding before value. Route onward only after the user wants to continue, save, invite partner, or go deeper.
5. Be careful with LiveKit-inspired layouts. A three-column active state (dialogue / pod / guidance) looked too busy for this product and made Antoine say the page was confusing. Default to one focused active card first; only add side panels progressively after the user gives enough context.
6. Active session should feel like a smooth transformation, not a dashboard: hide below-fold marketing sections while active, keep one main prompt, and avoid premature guidance/continue/save controls.
7. Speak/type should feel unified: voice is primary, typing is always available in the same session, not a separate mode.
8. Voice controls must be real or explicitly labeled as prototype. For the actual voice-first product path, do not wire the homepage pod to browser `SpeechRecognition` as a fake stand-in; use the ElevenLabs `useConversation` path so clicking the pod starts the real voice agent. Browser speech recognition is only acceptable as an explicitly labeled fallback/prototype.
9. Homepage voice entry should not default to solo. Use an undecided/neutral mode first: the coach asks “Are both of you here, or is it just you today?” and only then adapts to solo privacy behavior or together facilitation. Defaulting to solo feels wrong when the product is for couples.
10. Keep the active session constrained to a 2-minute “moment session,” not a full generic chat app.
11. Guidance preview should appear only after user input and be structured around: what may be underneath, what to say next, what to avoid, next move.
11. If the hero feels messy, reduce prompt chips, make the pod CTA dominant, and move detail into progressive panels instead of removing the pod.
12. Antoine likes the LiveKit-style hero reference, but adapt it carefully for HappyCouple:
    - Use a large square pod around 300–310px desktop as the visual center.
    - Add subtle throbbing/pulsing and a hover-only “Click to talk” pill/cue.
    - Make both the pod and “Talk to your coach” CTA perform the same action.
    - On activation, smoothly move/drop the pod down and remove/hide the H1 so the experience becomes the product, not a brochure.
    - Show conversation/transcript on the left in a cool, sparse, terminal-like panel.
    - Put the session map/guidance rail on the right once active, not above the transcript. Make the map labels self-explanatory; for neutral voice entry include: Presence — Solo or together; Moment — What happened; Underneath — What may be driving it; Next words — What to say or avoid.
    - Hide homepage CTAs and prompt chips while active. The active state should have the pod, transcript, right-side session map, and a conventional top-right close button only.
    - Hide the long-term report/plan preview until its CTA is clicked; otherwise it competes with the pod. Prefer making “See a long-term coaching plan” an anchor link to a below-fold broader-product section rather than revealing a side panel in the hero.
    - The broader-product section should match the hero’s positioning/design and explain: Initial session, Private report, Partner loop, Check-ins, Relationship map, Coaching plan. Keep it as the answer to “what does this become if the first moment helps?” — not generic SaaS features.
    - Replace logo/social-proof strip with a 5-slot rotating prompt strip using relationship problems; prompts should rotate periodically and be clickable.
13. Hero must fit in one viewport before polishing animations. If the pod + H1 + subheadline + CTAs + prompt strip overflow, compress the system together instead of only shrinking one element:
    - Reduce section top padding first; large `pt-24`/`lg:pt-14` pushed the hero below the fold.
    - Keep the square pod emotionally central but use roughly 250–260px desktop when the full hero needs to fit; 300–310px can be too tall with a large headline.
    - H1 around `text-3xl md:text-5xl lg:text-6xl` and subheadline around `text-sm md:text-base` preserved impact while fitting better than `lg:text-7xl`.
    - Tighten vertical margins between pod, eyebrow, H1, subheadline, CTAs, and prompt strip.
    - Shorten prompt cards to roughly 58px min-height; 80px+ prompt cards made the below-fold problem worse.
    - Verify visually, not only by accessibility snapshot: snapshots include below-fold DOM and can falsely imply overflow.
    - If the inactive landing H1 wraps to 3 lines, do not only shrink text. Check whether hidden desktop side panels are still occupying grid columns. In `src/app/page.tsx`, the inactive hero should use one wide desktop column (e.g. `lg:grid-cols-1`), and the conversation/plan asides should be `hidden` when inactive rather than `hidden lg:block` with `opacity-0`; otherwise invisible 300px side columns narrow the H1. A robust two-line H1 pattern is a wider wrapper (`max-w-5xl`) plus `md:whitespace-nowrap` on “Handle your relationship better,” followed by the explicit `<br />` before “one moment at a time.”
    - If a screenshot of `/` shows only the global header “HappyCouple” and a “thinking” pod, that is not a hero/H1 layout issue. It means the homepage is stuck in an auth/loading shell or rendering `LoggedInHome`. For landing-page iteration, `/` should render the public landing page directly; do not gate it behind `useAuth` loading or redirect logged-in users into dashboard state. Keep dashboard on `/dashboard` unless Antoine explicitly wants logged-in homepage behavior.

## Reddit marketing and pain-mining workflow
Use this when Antoine asks about HappyCouple marketing, Reddit, acquisition, pain mining, or content strategy.

Core stance:
1. Reddit is primarily a pain-mining, content, SEO, and paid-ads channel for HappyCouple — not a direct self-promotion channel.
2. Most relevant subreddits ban self-promotion, commercial posts, surveys, AI-generated content, links, or low-effort resource drops. Do not recommend “just post the app.”
3. The Reddit-derived marketing wedge is: “I don’t know what to say / am I overreacting / how do I bring this up without making it worse?”
4. Translate Reddit posts into: landing prompt chips, SEO pages, TikTok/Reels scenarios, ad creatives, and product moment taxonomy.
5. Direct organic participation should be advice-first from a human/founder account, with no link unless explicitly allowed, requested, or mod-approved.

Priority subreddits for HappyCouple research/acquisition:
- Core pain mines: `r/relationship_advice`, `r/AmIOverreacting`, `r/dating_advice`, `r/Marriage`, `r/relationships`, `r/LongDistance`, `r/DeadBedrooms`, `r/datingoverthirty`, `r/BreakUps`, `r/texts`.
- “What do I say next?” / message coaching: `r/relationship_advice`, `r/dating_advice`, `r/AmIOverreacting`, `r/texts`, `r/Tinder`, `r/Bumble`, `r/hingeapp`, `r/BreakUps`, `r/ExNoContact`, `r/LongDistance`.
- Long-term paid product / retention signals: `r/Marriage`, `r/DeadBedrooms`, `r/datingoverthirty`, `r/LongDistance`, `r/Parenting`, `r/Mommit`, `r/MarriageAdvice`, `r/AskWomenOver30`, `r/AskMenOver30`, `r/polyamory`.
- Product safety / do-not-market spaces: `r/abusiverelationships`, `r/emotionalabuse`, `r/NarcissisticAbuse`, `r/survivinginfidelity`, `r/ROCD`, `r/AnxiousAttachment`, `r/DeadBedrooms`, `r/JustNoSO`.

Useful additional subreddits:
- Dating/app conversation: `r/dating`, `r/Tinder`, `r/Bumble`, `r/hingeapp`, `r/OnlineDating`, `r/datingoverforty`, `r/datingoverfifty`.
- Gendered perspective: `r/AskWomenOver30`, `r/AskWomen`, `r/TwoXChromosomes`, `r/AskMen`, `r/AskMenAdvice`, `r/AskMenOver30`, `r/menslib`.
- Attachment/personal growth: `r/attachment_theory`, `r/AnxiousAttachment`, `r/avoidantattachment`, `r/relationshipanxiety`, `r/ROCD`, `r/Codependency`, `r/DecidingToBeBetter`.
- Parenting/life-stage conflict: `r/Parenting`, `r/Mommit`, `r/newparents`, `r/stepparents`, `r/Divorce`, `r/JustNoSO`.
- Intimacy/infidelity: `r/sex`, `r/SexOver30`, `r/LoveAfterPorn`, `r/survivinginfidelity`, `r/Infidelity`, `r/AsOneAfterInfidelity`, `r/SupportforBetrayed`.
- Nontraditional/LGBTQ+: `r/polyamory`, `r/nonmonogamy`, `r/lgbt`, `r/actuallesbians`, `r/AskGaybrosOver30`.

Post-mining schema:
- relationship stage: dating / long-term / married / breakup / LDR / parenting / non-monogamous
- moment type: apology, confrontation, repair, boundary, reassurance, sex/intimacy, chores/load, jealousy, family/in-laws, cheating/trust, shutdown/avoidance
- user ask: “what do I say?”, “am I wrong?”, “am I overreacting?”, “should I leave?”, “how do I bring it up?”, “what does this mean?”
- emotional state: angry, anxious, guilty, confused, rejected, resentful, ashamed, lonely
- usable hook / exact user language
- product output idea: what may be underneath, what to say next, what to avoid, next move
- safety flag: abuse, coercion, self-harm, medical/clinical, infidelity crisis, minor involved

Good output format for future Reddit research:
1. Prioritized subreddits by use case, not just one giant list.
2. Subscriber counts when available, but do not overweight size over pain quality.
3. Promotion risk per subreddit.
4. Concrete content/product implications.
5. Anti-targets / places to research only, especially abuse and trauma support communities.

## Implementation workflow in the Next.js app
Project path: `/Users/antoinelevy/Documents/Code/coupletherapy`.

Typical files:
- `docs/product-spec-moment-flow.md` — product spec for the moment-based flow.
- `src/app/page.tsx` — landing page.
- `src/app/onboarding/page.tsx` — mode choice and query-param handling.
- `src/app/session/page.tsx` — session startup and prompt wiring.
- `src/lib/system-prompt.ts` — system prompt and first assistant messages.
- `src/lib/store.ts` — local session data shape.
- `src/app/layout.tsx` — metadata / positioning.

Implementation pattern:
1. Add or maintain a `focusMoment?: string` field in session data.
2. Landing page should pass the user’s entered moment to onboarding, usually as `?moment=`.
3. Onboarding should preserve and display the moment, then save it with mode and transcript metadata.
4. Session page should pass `session?.focusMoment` into `getSystemPrompt(...)` and the first-message generator.
5. For homepage inline voice sessions before onboarding, support `mode?: "together" | "solo"` in `getSystemPrompt(...)` and add an undecided prompt section plus `getFirstMessageUndecided(focusMoment?)`; do not call `getSystemPrompt("solo", ...)` from the landing page unless the user explicitly selected solo.
6. `system-prompt.ts` should have moment-aware prompt sections and first-message functions, e.g. `getFirstMessageSolo(focusMoment?)`, `getFirstMessageTogether(focusMoment?)`, and `getFirstMessageUndecided(focusMoment?)`.
8. Header/auth convention from landing-page iteration: the global “Sign In” button should route to `/auth/login?mode=login`, and the login page should initialize its tab from the `mode=login` query param using a `useState` initializer rather than `setState` in `useEffect` (the repo’s eslint flags synchronous setState in effects). Plain `/auth/login` may remain signup-first for create-account CTAs.
9. First-session handoff convention: after a homepage voice moment, provide an explicit `End and summarize` UI control and also let natural user phrases like “summarize” / “recap” trigger the summary. The post-session object should be called “Your first moment summary” / “first relationship report,” not a complete long-term plan. Include: the moment, what may be underneath, next words, what to avoid, next move, and “what we do not know yet” caveats. The conversion CTA should be “Save my report” and route to `/auth/login?mode=signup&next=save-report` after storing the local session/report so signup preserves value rather than blocking initial value.
10. Report generation should use a real transcript-backed API route (`/api/moment-report`) when possible: send the full transcript, focus moment, strict JSON schema, and explicit “do not invent / caveat unknowns” rules. Keep the deterministic `buildMomentReportPreview` fallback so static previews and missing `OPENAI_API_KEY` still produce a safe first read.

## SEO moment pages workflow
Use this when building or auditing HappyCouple SEO pages around concrete relationship moments, e.g. “what to text after a fight” or “partner asked for space.” See `references/seo-moment-pages.md` for the session-specific checklist and example slugs.

1. Treat moment pages as acquisition artifacts, not just content. Each page should answer a specific painful query, demonstrate the moment-first product wedge, and route naturally into the core “paste the situation / get next words” experience.
2. Keep the page set internally coherent: if a page links to sibling guides like apology, reassurance, overreaction, or partner-space pages, those sibling pages should either exist or be intentionally omitted from the live links until they are ready.
3. In Next.js, a good pattern is a typed data source such as `src/lib/moment-pages.ts`, a dynamic route such as `src/app/(moment-pages)/[slug]/page.tsx`, and `src/app/sitemap.ts` so Google can discover the pages.
4. Do not report pages as “live” just because the local repo contains route files. Check git status, commit/push/deploy if needed, then verify the canonical `https://happycouple.ai/...` URLs return `200`.
5. Default to closing the deployment gap yourself when repo + deployment access are available. If moment pages exist locally but return `404` in production, do not stop at explaining the gap; add missing sibling pages or remove dead internal links, run lint/build, commit, push, wait for Vercel Ready, and verify canonical URLs/sitemap. Only stop for unavoidable auth, payment, destructive-risk, or product-decision gates.
6. Verify `https://happycouple.ai/sitemap.xml` returns `200` and includes the moment page URLs before treating the SEO surface as indexable.
7. When answering Antoine about page links, separate `Defined locally` from `Live on production`. If production returns `404`, say that directly and name the deployment gap, then proceed to fix/deploy it by default rather than leaving Antoine to ask why it was not automatic.

## Obsidian product docs maintenance
Canonical product folder:
`/Users/antoinelevy/Documents/Obsidian Vault/Consumer AI Company Factory/05 Ventures/Venture 001 - HappyCouple/01 Product`

When Antoine asks why product docs are missing/empty, or asks to create/update HappyCouple product structure, do not just summarize from memory. Inspect both Obsidian and the codebase, then backfill product docs from the live implementation and existing venture notes.

Current initial product doc structure:
- `00 Product Command Center.md` — central index, current thesis, wedge, product loop, source-code links, activation bar.
- `HappyCouple - Moment Flow Product Spec.md` — first-use flow, homepage product elements, moment categories, success criteria, risks.
- `HappyCouple - Agent Behavior Spec.md` — tone, solo/together/undecided behavior, moment-first coaching behavior, forbidden behavior, safety protocol.
- `HappyCouple - First Moment Report Spec.md` — report schema, generation rules, fallback logic, natural summary triggers, conversion rule.
- `HappyCouple - Relationship Map and Coaching Plan.md` — long-term product layer: initial session → private report → partner loop → check-ins → relationship map → coaching plan.
- `HappyCouple - Implementation Map.md` — product-area-to-code map for landing, onboarding, session, prompt, report, state model, framework, dashboard, analytics.
- `HappyCouple - Product Backlog and Open Questions.md` — product decisions, architecture tensions, near-term backlog, kill-risk.

Code files worth inspecting before updating these docs:
- `src/app/page.tsx`
- `src/app/onboarding/page.tsx`
- `src/app/session/page.tsx`
- `src/lib/system-prompt.ts`
- `src/lib/moment-report.ts`
- `src/app/api/moment-report/route.ts`
- `src/lib/store.ts`
- `src/lib/framework.ts`
- `src/lib/track.ts`
- `docs/product-spec-moment-flow.md`

Important product issue discovered while creating the docs: homepage inline voice flow and onboarding → `/session` are two different first-session paths. The homepage inline flow is closer to the moment-first wedge; `/session` still carries older 15-minute session logic. Also, `saveReportAndSignUp()` currently stores homepage first-moment reports as `mode: "solo"` even though presence may be undecided/together; flag this when touching product/data flow.

## Verification
Run:
```bash
cd `/Users/antoinelevy/Documents/Code/coupletherapy`
npm run lint
npm run build
```

Expected caveats discovered previously:
- The repo had no `*.test.*` files when checked.
- `npm run lint` may pass with warnings.
- `npm run dev` / `npm start` previously crashed with exit `-11` and no useful output under the default Homebrew Node `v23.9.0`, despite a successful build. Do not treat that as proof the code is broken without further debugging.
- Node 22/webpack may serve briefly and return `HTTP 200` but can still later crash with exit `-11` during browser visual verification; if this happens, rely on `npm run lint`, `npm run build`, `curl -I`, and code/layout inspection unless deeper local Next debugging is the task.
- Workaround that has sometimes served the app locally: build first, then run Next with Node 22 and webpack, e.g. `npx -y node@22 ./node_modules/next/dist/bin/next dev --webpack -p 3008` from the project directory. Verify with `curl -I http://localhost:3008`.
- If adding `@elevenlabs/react` providers outside `/session`, do not import `ConversationProvider` directly into the server `app/layout.tsx`; wrap it in a small `"use client"` component (e.g. `src/components/ConversationRoot.tsx`) and render that from the layout, otherwise `next build` can fail during `/_not-found` page-data collection with `createContext is not a function`.
- Next/Turbopack may warn about multiple lockfiles and infer workspace root as `/Users/antoinelevy/package-lock.json`; consider setting `turbopack.root` or resolving extra lockfile if needed.

## Mobile app / platform posture

Decision pattern from 2026-05-29 mobile-app research: Emma should become phone-native in behavior before native in code.

Default caution: for HappyCouple / Emma, do not build full native iOS/Android apps just because the couples/relationship category is mobile-first. Keep the product web-first but mobile-first until first-context submission, first-value quality, repeat use, partner invites, and reminder value are proven. The next platform layer is often:

1. mobile-first web hardening,
2. text/screenshot-first relationship moment flow alongside voice,
3. lightweight PWA/home-screen readiness,
4. discreet reminders tested via email/SMS/in-app/PWA,
5. no-install partner invite links,
6. native iOS/Android only after explicit retention/mobile/import/share/push/App Store triggers.

Antoine correction from 2026-06-03: if he explicitly says he is building a **full mobile app** and believes it helps distribution, do not keep arguing for web-first. Accept the native decision and reframe the work around what makes native strategically different from web. The native app should not be “the web app in React Native”; it should use mobile-native distribution/product wedges:

- App Store search/ASO around relationship text help, couple communication, argument repair, and “what to say after a fight.”
- Screenshot/chat import as a first-class intake path.
- Copy/share/open-from-message flows for real relationship text moments.
- Push/check-in reminders only after first value, not generic journaling nudges.
- Partner invites/deep links, ideally with no-install handoff where possible.
- Shareable before/after text/result cards for creator and short-form demos.

Native becomes more justified if multiple triggers are true: mobile is the dominant first-context surface, screenshot/chat import friction is real, activated D7/D30 retention is meaningful, partner invites work and notifications/deep links are bottlenecks, reminders lift retention, App Store keyword/CAC tests are viable, or Antoine chooses native as the distribution wedge.

## HappyCouple UGC / creator-testimonial posture

Session-specific reference: `references/happycouple-ugc-emma-testimonial-2026-06-03.md`.

Antoine correction from 2026-06-03: UGC creators should talk about their experience **using Emma**. Do not frame Emma as the UGC creator/persona. Emma is the app/AI relationship coach being demonstrated; the creator is a believable user/testimonial.

Default creator-testimonial structure:
1. Creator opens with a real relationship moment: “I didn’t know what to text after a fight,” “I was overthinking his reply,” “I wanted to apologize without sounding needy.”
2. Creator shows the phone/app behavior: paste text, upload screenshot/chat, or describe the situation.
3. Emma produces the value artifact: what may be underneath, what to say next, 2–3 tone variants, and what to avoid.
4. Creator describes the outcome: copied/sent the calmer version, avoided escalating, understood the partner’s reaction, or used Emma for the follow-up.
5. CTA stays concrete: “If you overthink relationship texts, try Emma,” not generic couple therapy language.

Good UGC lines:
- “I used Emma after a stupid fight with my boyfriend and it helped me write the text without sounding needy.”
- “I screenshotted the conversation, pasted it into Emma, and it told me what was probably going on underneath.”
- “It gave me a soft version, a direct version, and what not to say if I didn’t want to make it worse.”
- “It’s not therapy. It’s like having someone help you not ruin the next message.”

Avoid:
- Random text-to-video creators that do not demonstrate Emma.
- “Emma” as a consistent human influencer character talking to camera.
- Generic relationship-advice monologues with no app interaction or proof moment.
- Cheap B-roll that does not show the screenshot/paste/copy/share wedge.

## Antoine preference reminders
- Keep updates short and practical.
- Push back against agent theater and feature sprawl.
- Ask for concrete user examples rather than adding more features.
- Use “Reddit pain” examples when testing copy, but avoid making the product feel like a trivial text-message rewriter or dating app helper.