b2c-app-builder 0.221.39

package/knowledge/product/ai-chat-companion.md

@@ -0,0 +1,96 @@
+# AI Chat / Companion Build Lane
+
+Use this reference when the founder wants to build an **AI chat product** — "an AI assistant app", "a chatbot for <domain>", "an AI companion/character", "a coach/tutor/therapist-style chat app", "talk to an AI that remembers me". It is the second **app-archetype prompt pack** (peer to [`social-network.md`](./social-network.md)), shipped as reusable boilerplate under [`../surfaces/starters/ai-chat-companion/`](../../surfaces/starters/ai-chat-companion/README.md).
+
+Like the social lane, this is a layer on top of the launch workflow, not a replacement. It gives the engineering stages a proven sequence and ready prompts for one product shape and routes each piece back into the existing lanes (research, 11-star, emotional design, security/safety, revenue, analytics). It does not skip evidence, design, safety, or provider-proof gates.
+
+## When To Use
+
+Load this reference when the product's core is **a user talking to an LLM over multiple turns**, with conversation history, and usually memory, personalization, and a usage/subscription model. Comparable products: ChatGPT/Claude-style assistants, Character.AI/Replika-style companions, domain copilots (legal, fitness, language tutor), and voice assistants.
+
+Do **not** use it for a product that merely has a support chatbot bolted onto a different core; it is for products whose center of gravity is the conversation itself.
+
+## Step 1 — Confirm The Shape (AskUserQuestion)
+
+Before building, confirm the product shape with the founder via **AskUserQuestion** (or a plain founder choice if unavailable). These answers change the schema, the system prompt, the memory model, the safety posture, and the store path.
+
+1. **Chat type** — what is the conversation for?
+   - **Assistant / productivity** (ChatGPT model): task-oriented, tool-using, accuracy-first.
+   - **Companion / character** (Character.AI / Replika model): persona-driven, relationship + memory, emotional tone. Higher safety burden.
+   - **Domain copilot** (coach / tutor / advisor): a bounded expert in one domain with a strong system prompt and guardrails.
+2. **Primary surface** — **Web / PWA** (default stack: Next.js App Router + Supabase + Vercel + Claude API server routes) or **native mobile** (same backend; client adapted; Apple/Play store lanes apply; digital subscriptions go through IAP).
+3. **Modality** — an intentionally text-only product, or **voice-first** (speech-to-text in, TTS out)? Voice adds latency, audio storage, and cost.
+4. **Memory depth** — session-only, or **long-term per-user memory** the model recalls across conversations? Long-term memory is the "feels like it knows me" moment and a privacy/security item.
+5. **Audience & safety scope** — general adult, or could **minors** use it? Companion/character and any minor exposure raise the safety bar (crisis protocols, age gating) from optional to required.
+
+Record the answers in `state/business-state.json` (e.g. `lanes.product.archetype: ai-chat-companion`, `chat_type`, `primary_surface`, `modality`, `memory_depth`, `safety_scope`).
+
+Honesty note: the bundled prompts target **web (Next.js + Supabase + Claude API)**. The Claude API key and all inference calls must be **server-side only** — never ship the key to the client. For native mobile, the inference proxy/backend carries over unchanged; the chat client is re-expressed for the native stack and IAP applies.
+
+## Runnable Starter
+
+The pack ships a runnable scaffold at [`../surfaces/starters/ai-chat-companion/starter/`](../../surfaces/starters/ai-chat-companion/starter/README.md): Next.js App Router + Supabase pre-wired with magic-link auth, owner-only schema migrations with **tested** RLS (pgTAP, per `backend-data-contract.md`), a server-side streaming Claude route (`ANTHROPIC_API_KEY` never reaches the client; the model id lives in `ANTHROPIC_MODEL`, resolved via the `claude-api` skill), Stripe and RevenueCat stubs, a PostHog event catalog matching the analytics lane's snake_case conventions, a names-only `.env.example`, and a CI workflow. Copy it into the business repo as the floor and customize it with the prompts below — its README maps each prompt to the scaffold area it customizes. Do not improvise the same wiring from scratch; `check:archetype-starter` enforces the starter contract. If the founder selects Firebase or a custom backend, adapt through the data-contract lane instead of running the Supabase pieces verbatim.
+
+## The Core Systems
+
+Every AI chat product is built on six systems. Inference and safety are the two that most teams under-build.
+
+1. **User Identity** — auth, sessions, profile. → prompt `02-auth-system`.
+2. **Conversations & Messages** — threads, message history, ordering, soft-delete, streaming render. → `01-database-schema`, `03-chat-core-loop`.
+3. **Inference & Context** — the server route to Claude, the system prompt, streaming, context-window management, and conversation summarization. The product's quality lives here. → `04-model-integration`.
+4. **Memory & Personalization** — per-user persona and long-term memory retrieved into context; user-editable. → `05-memory-personalization`.
+5. **Usage & Monetization** — message/token metering, free-tier caps, rate limits, and the subscription that raises limits / unlocks a better model. → `06-usage-limits-metering`, `07-stripe-monetization`.
+6. **Safety & Moderation** — input/output moderation, jailbreak resistance, crisis/self-harm protocols, and age gating. Non-optional before public launch. → `08-safety-and-moderation`.
+
+## The Build Sequence
+
+Build one system at a time and test it. Prompts live in [`../surfaces/starters/ai-chat-companion/prompts/`](../../surfaces/starters/ai-chat-companion/README.md):
+
+| #   | Prompt                                                 | Core system                    | Threads into                                                               |
+| --- | ------------------------------------------------------ | ------------------------------ | -------------------------------------------------------------------------- |
+| 00  | `00-positioning-strategy` (Claude.ai, not Claude Code) | positioning                    | `strategy/RESEARCH.md`, naming, `VIRAL_GROWTH.md`                          |
+| 01  | `01-database-schema`                                   | conversations + usage + memory | `engineering/TECH_SPEC.md`, engineering, security (RLS)                    |
+| 02  | `02-auth-system`                                       | identity                       | engineering, `trust/SECURITY.md`, `SECRETS.md`                             |
+| 03  | `03-chat-core-loop`                                    | conversations + streaming UI   | `11_STAR_EXPERIENCE.md`, `analytics/ANALYTICS.md`                          |
+| 04  | `04-model-integration`                                 | inference + context            | `engineering/TECH_SPEC.md`, `SECRETS.md`, security                         |
+| 05  | `05-memory-personalization` (optional)                 | memory                         | `consumer-product-design-agency.md`, privacy                               |
+| 06  | `06-usage-limits-metering`                             | usage                          | `revenue-monetization.md`, `analytics/ANALYTICS.md`                        |
+| 07  | `07-stripe-monetization` (optional)                    | revenue                        | `revenue-monetization.md`, `revenue/REVENUE_OPS.md`                        |
+| 08  | `08-safety-and-moderation`                             | safety                         | `security-release-hardening.md`, `ethics-guardrail.md`, `privacy-terms.md` |
+
+Variants (apply after the text base): [`variants/companion-character`](../../surfaces/starters/ai-chat-companion/prompts/variants/companion-character.md) and [`variants/voice-first`](../../surfaces/starters/ai-chat-companion/prompts/variants/voice-first.md).
+
+Step 0 (positioning) is strategic work for the **web interface / Claude.ai**. The rest are Claude Code build prompts.
+
+## How This Lane Threads Into The Launch Workflow
+
+- **The system prompt is a product asset, not a code detail.** It encodes the persona, the domain guardrails, the refusal style, and the safety rules. Version it, review it against `strategy/BRAND.md §Voice`, and treat changes as [`change-cascade.md`](../process/change-cascade.md) events. When building AI features in this skill, follow the Claude API guidance (the `claude-api` skill) for current model IDs, streaming, tool use, and prompt-caching — do not hardcode model names or pricing from memory.
+- **Inference keys are server-side secrets.** The Claude API key never reaches the client; all calls go through a server route or edge function. Route the key through `SECRETS.md` ([`secrets-management.md`](../operations/secrets-management.md)) and treat the inference endpoint as an abuse/cost surface in `trust/SECURITY.md` (rate limits, per-user quotas, prompt-injection handling).
+- **The first response is the 11-star moment.** Run [`eleven-star-experience.md`](../experience/eleven-star-experience.md) over prompt 03/04: streaming that feels alive, and (with memory) a reply that reflects the user's own context, is the magical accepted product experience. The memory recall is an Intent Mirroring moment (`consumer-product-design-agency.md`); give it a PostHog event and an honest "based on what you told me" attribution per the Human-Centered AI tier.
+- **Usage metering is the monetization spine.** Prompt 06 meters messages/tokens and enforces free-tier caps before prompt 07 sells the upgrade. Reconcile caps, model tiers, and price with `revenue-monetization.md` (Stripe for web; IAP/StoreKit for native digital subscriptions). The upgrade prompt at the cap is an onboarding/paywall-timing decision (`onboarding-conversion.md`).
+- **Safety is a launch gate, scaled to audience.** Prompt 08 is required before public launch: input/output moderation (Claude API or a classifier), jailbreak resistance, and — for companion/character apps or any product minors can reach — crisis/self-harm escalation copy and age gating. This is both a `security-release-hardening.md` item and an `ethics-guardrail.md` item: a companion that encourages dependency or misrepresents itself as human/licensed is a dark pattern and a compliance veto. Reflect data retention and AI-use disclosures in `privacy-terms.md`.
+- **AI-result honesty is a copy rule.** Per the Human-Centered AI tier in `consumer-product-design-agency.md`: every AI result attributes itself to user context where relevant, never claims certainty it cannot verify, and keeps a visible user-override/edit path. Add the rule to `strategy/BRAND.md §Voice`.
+
+## Infrastructure Defaults (record decisions, do not hardcode)
+
+- **Inference:** Claude API via server routes/edge functions, streaming. Use prompt caching for the system prompt + long memory to cut latency and cost. Confirm the current model IDs/params via the `claude-api` skill.
+- **Backend:** Supabase (Postgres + Auth + Realtime + Storage). Conversations and messages in Postgres with RLS; long-term memory as a per-user store (optionally a `pgvector` embedding table for retrieval).
+- **Hosting:** Vercel (web). Mind serverless function timeouts for long streams; use streaming responses, not buffered.
+- **Moderation:** an input/output moderation pass on every turn before public launch.
+- **Resilience:** wrap the inference call in a circuit breaker. Open the circuit after repeated provider failures. Return a structured error with an `is_retryable` field, not a raw exception string. Show the user a graceful degraded state during an open circuit, never a hung request.
+- **Email:** verification and lifecycle via `resend-email-ops.md`.
+
+## Extending / Acceptance
+
+This pack follows the archetype contract enforced by `check:app-archetype` (README + numbered prompts with fenced blocks + reference + SKILL.md routing + agent-behavior eval). To add another archetype, mirror this shape under `starters/<archetype>/`.
+
+Before calling an AI-chat build ready:
+
+- [ ] Chat type, surface, modality, memory depth, and safety scope confirmed via AskUserQuestion and recorded in `state/business-state.json`.
+- [ ] Claude API key is server-side only; inference endpoint has per-user rate limits/quotas and prompt-injection handling in `trust/SECURITY.md`.
+- [ ] System prompt is versioned and reviewed against `strategy/BRAND.md §Voice`.
+- [ ] Streaming + context-window management + summarization are specified in `engineering/TECH_SPEC.md`; current model IDs/params sourced via the `claude-api` skill, not memory.
+- [ ] Usage metering + free-tier caps reconciled with `revenue-monetization.md`; correct billing path for the surface (Stripe web / IAP native).
+- [ ] Safety pass (moderation, jailbreak resistance, crisis protocol + age gating where the audience requires) complete; ethics-guardrail and privacy/AI-use disclosures reconciled.
+- [ ] AI-result honesty copy rule in `strategy/BRAND.md §Voice`; memory recall has a PostHog event and a user-editable/override path.
+</content>

package/knowledge/product/core-loop-and-complete-scope.md

@@ -0,0 +1,82 @@
+# Core Loop And Complete Product Scope
+
+Use this method before accepting the scope of a consumer app, whether its shape matches a
+shipped archetype or requires a new implementation. A complete product can be focused. It
+cannot omit a system needed to deliver its accepted promise and call that omission a later stage.
+
+## Name the promise and core loop
+
+Identify the user, the recurring problem, the useful outcome, the repeated action, and the
+moment a user can see why this product is better than the alternatives. Select a platform
+because it serves that loop, not because a starter happens to exist.
+
+Use decisions delegated in the opening mandate. Do not ask the founder to repeat an already
+supplied choice. Escalate a genuinely ambiguous product decision only when its authority was
+not delegated. Record product meaning in `product.yaml`; render `PRODUCT.md`. Never write
+product decisions into reducer-owned execution state.
+
+## Enumerate every required system
+
+Work backward from the promise and every critical journey. Name the systems required to make
+them real: domain data and its lifecycle, the core interaction, persistence, recovery, privacy,
+accessibility, distribution, support, and measurement. Identity, remote services, monetization,
+notifications, and sharing are conditional on the accepted product, not universal defaults.
+
+For each system specify its user outcome, dependencies, states, responsible surface, and
+observable acceptance evidence. A parcel-tracking promise that requires live carrier status
+cannot be fulfilled by a manually edited demo list. A subscription promise requires real purchase,
+pending, cancellation, entitlement and restore behavior in the selected supported test environment.
+A local-only utility need not acquire a backend simply to satisfy a generic checklist.
+
+State explicitly whether each proposed system is required or outside the accepted promise.
+An exclusion needs a rationale and a scope decision. Missing credentials, a difficult integration,
+time pressure, or a working simulator shell are not reasons to reclassify required work as optional.
+A blocked required system remains pending with its owner, exact missing input and resume action.
+Changing the promise or removing a required system requires an explicit scope decision under the
+founder's authority, not an implementation shortcut.
+
+## Define a complete experience
+
+Translate the core loop into a distinctive, usable experience before production implementation
+hardens. Use the 11-star method to explore ambition and choose a feasible complete experience;
+feasibility limits the promise, not the craft of the accepted promise. Carry that same experience
+through the app, onboarding, landing page, screenshots, support and other selected surfaces.
+
+Define meaningful interaction feedback and motion, interruption and recovery, empty/loading/error
+states, accessibility and reduced-motion behavior. A quiet product may use restrained motion.
+Confetti, a mascot, subscriptions, and a particular visual style are not universal requirements.
+The benchmark describes quality and coherence, not a mandate to copy another app's identity.
+
+Specify the reference evidence, native/runtime proof, independent review and repair needed for
+acceptance. A neat static screenshot cannot establish interaction quality. Unit tests and a
+successful compile cannot establish design quality or a functioning provider integration.
+
+## Plan implementation without shrinking delivery
+
+Break implementation into manageable tasks and use the simulator early for internal tests.
+An internal prototype or partial build is an explicitly unfinished working artifact. It is not
+the completed business promised to the founder. Do not describe required work as postponed to
+another product version merely because one task or research lane has finished.
+
+The accepted `complete_scope` in `product.yaml` names the required systems, explicit exclusions,
+and acceptance conditions. Feature scope uses `required`, `excluded`, or `non-goal`. Historical
+input names may be migrated by the reader, but new product writing uses the complete-scope contract.
+Keep requirements and decisions in this one product owner. Detailed contracts link back to it.
+
+## Carry the mandate through acceptance
+
+Research completion enables independent research review, then the accepted product's design,
+implementation, verification and closeout obligations. Use the active recipe and planner. Do not
+create a private lane list or declare business completion from one validator's exit code.
+
+Pricing hypotheses may be recorded as proposals. An approved production price needs offer evidence
+and the applicable founder decision. Production release, publishing, spending, legal approval and
+account changes remain separately authorized even when the product is otherwise ready.
+
+## Acceptance checklist
+
+The promise and core loop are specific. Every required system has an acceptance condition and a
+real implementation plan. Exclusions do not contradict the promise. No required system is deferred
+without an authorized scope change. Product decisions use the canonical product store. The design
+and interaction bar is explicit, with appropriate current evidence and independent review. The
+business's remaining work and protected holds stay visible after each bounded session.

package/knowledge/product/habit-tracker.md

@@ -0,0 +1,89 @@
+# Habit Tracker / Daily Utility Build Lane
+
+Use this reference when the founder wants to build a **habit or daily-utility app** — "a habit tracker", "a streak app", "a daily routine app", "build a habit app for <niche>", or a wellness/productivity utility whose core is a small daily action logged against a goal (water, meditation, workouts, meds, journaling-as-checkbox). It is an **app-archetype prompt pack** (peer to [`social-network.md`](./social-network.md) and [`ai-chat-companion.md`](./ai-chat-companion.md)), shipped as reusable boilerplate under [`../surfaces/starters/habit-tracker/`](../../surfaces/starters/habit-tracker/README.md).
+
+Like the other archetype lanes, this is a layer on top of the launch workflow, not a replacement. It gives the engineering stages a proven sequence and ready prompts for one product shape and routes each piece back into the existing lanes (research, 11-star, emotional design, security, revenue, analytics). It does not skip evidence, design, ethics, or provider-proof gates — and in this archetype the **ethics gate is load-bearing**, because the streak mechanic at its center is a HIGH-risk Experience Card.
+
+## When To Use
+
+Load this reference when the product's core is **a user committing to a recurring action and logging it daily**, with streaks/progress as the return mechanic and reminders as the retention surface. Comparable products: Streaks, Habitica, Way of Life, water/meds trackers, meditation-streak apps, simple "did I do X today" utilities.
+
+Do **not** force this lane onto a product that merely _contains_ a habit feature (a fitness app with one streak, a journal with a reminder); it is for products whose center of gravity is the daily check-in loop.
+
+## Step 1 — Confirm The Shape (AskUserQuestion)
+
+Before building, confirm the product shape with the founder via **AskUserQuestion** (or a plain founder choice if unavailable). These answers change the schema, the today view, the ethics burden, and the store path. Ask, in one batched call:
+
+1. **Habit model** — what is the user tracking?
+   - **Flexible self-defined habits** (Streaks/Habitica model): the user creates habits with cadences. The pack's base.
+   - **Guided program** (coach model): the app supplies structured programs and day plans; content is the product. → `variants/wellness-coach`.
+   - **Single-purpose counter** (utility model): one tracked thing, one screen. Pairs with `launchScope: essentials`. → `variants/simple-counter-utility`.
+2. **Primary surface** — **Web / PWA** (the pack's default stack: Next.js App Router + Supabase + Vercel) or **native mobile**? Be honest here: habit apps live on phones. Reliable reminders, lock-screen widgets, and local notifications are the retention surface and they push toward native — if the founder picks native, the Apple/Play store lanes in `SKILL.md` apply in full and digital subscriptions go through IAP/RevenueCat. The schema, RLS, and server-side streak engine carry over unchanged; the client prompts are web prompts and must be adapted.
+3. **Which optional systems are in the accepted product?** (multi-select) — stats/insights (prompt 05), monetization (prompt 06), social accountability (prompt 07).
+4. **Niche** — who is this for, and which habit or routine? (Free text. Feeds prompt 00 positioning. A specific niche is the whole strategy; "track anything" loses to free incumbents and the phone's built-in reminders.)
+
+Record the answers in `state/business-state.json` (e.g. `lanes.product.archetype: habit-tracker`, `habit_model`, `primary_surface`, `optional_systems`, plus `project.launchScope: lite` if the counter-utility variant is chosen) so later sessions do not re-litigate the shape.
+
+## Runnable Starter
+
+The pack ships a runnable scaffold at [`../surfaces/starters/habit-tracker/starter/`](../../surfaces/starters/habit-tracker/starter/README.md): Next.js App Router + Supabase pre-wired with magic-link auth, schema migrations with **tested** RLS (pgTAP, per `backend-data-contract.md`), Stripe and RevenueCat stubs, a PostHog event catalog matching the analytics lane's snake_case conventions, a names-only `.env.example`, and a CI workflow. Copy it into the business repo as the floor and customize it with the prompts below — its README maps each prompt to the scaffold area it customizes. Do not improvise the same wiring from scratch; `check:archetype-starter` enforces the starter contract. If the founder selects Firebase or a custom backend, adapt through the data-contract lane instead of running the Supabase pieces verbatim.
+
+## The Core Systems
+
+Every habit app is built on five systems. The streak/reminder engine is the one most teams get wrong — first on timezone correctness, then on ethics.
+
+1. **Identity + Timezone** — auth, profile, and the user's IANA timezone captured at signup, because every streak depends on the user's local midnight. → prompt `02-auth-system`.
+2. **Habit Definition** — habits with cadence (daily / weekdays / N-per-week), archive-not-delete, and the program/counter reshapes in the variants. → `01-database-schema`.
+3. **Check-in Loop** — the today view and the one-tap, optimistic, undoable check-in. The product's magic lives in this two-second moment. → `03-habit-core-loop`.
+4. **Streak / Reminder Engine** — server-side, timezone/DST-correct streak computation; free recovery/freeze mechanics; reminders scheduled in local time with no-guilt copy. → `04-reminders-and-streaks`.
+5. **Insight / Retention Surface** — heatmap history, honest completion rates, weekly review; the usual home of the paid tier and the emotional-measurement data. → `05-stats-and-insights`, plus `06`/`07` as selected.
+
+## The Build Sequence
+
+Build one system at a time and test it. Prompts live in [`../surfaces/starters/habit-tracker/prompts/`](../../surfaces/starters/habit-tracker/README.md):
+
+| #   | Prompt                                                 | Core system                              | Threads into                                                                    |
+| --- | ------------------------------------------------------ | ---------------------------------------- | ------------------------------------------------------------------------------- |
+| 00  | `00-positioning-strategy` (Claude.ai, not Claude Code) | positioning                              | `strategy/RESEARCH.md`, naming, `growth/LAUNCH_NARRATIVE.md`                    |
+| 01  | `01-database-schema`                                   | habit definition + check-ins + reminders | `engineering/TECH_SPEC.md`, engineering, security (RLS)                         |
+| 02  | `02-auth-system`                                       | identity + timezone                      | engineering, `trust/SECURITY.md`, `SECRETS.md`, `onboarding-conversion.md`      |
+| 03  | `03-habit-core-loop`                                   | check-in loop                            | `11_STAR_EXPERIENCE.md`, `emotional-design-system.md`, `analytics/ANALYTICS.md` |
+| 04  | `04-reminders-and-streaks`                             | streak/reminder engine                   | `ethics-guardrail.md`, `SECRETS.md`, `engineering/TECH_SPEC.md` tests           |
+| 05  | `05-stats-and-insights` (optional)                     | insight surface                          | `emotional-experience-measurement.md`, retention                                |
+| 06  | `06-paywall-and-monetization` (optional)               | revenue                                  | `revenue-monetization.md` §3, `revenue/REVENUE_OPS.md`                          |
+| 07  | `07-social-accountability` (optional)                  | accountability + growth                  | `viral-growth-loops.md`, abuse controls                                         |
+
+Variants: [`variants/wellness-coach`](../../surfaces/starters/habit-tracker/prompts/variants/wellness-coach.md) (guided programs, content as product) and [`variants/simple-counter-utility`](../../surfaces/starters/habit-tracker/prompts/variants/simple-counter-utility.md) (strip to a essentials-scope single-purpose utility).
+
+Step 0 (positioning) is strategic work for the **web interface / Claude.ai**. The rest are Claude Code build prompts.
+
+## How This Lane Threads Into The Launch Workflow
+
+- **The check-in is the 11-star magical moment.** Run [`eleven-star-experience.md`](../experience/eleven-star-experience.md) over prompt 03: the tap → instant flip → streak tick is the engineered moment, with a PostHog event and a reduced-motion fallback (`consumer-product-design-agency.md`). The all-done state is the session close — a completion signal under the peak-end rule, never an engagement hook.
+- **The streak is a HIGH-risk Experience Card and carries a contract.** The check-in maps to the **Commitment** card; the streak maps to the **Streak / Loss Aversion** card, HIGH-risk per `ethics-guardrail.md`. Before ship it requires an `ethics_attestation`, a **user-control escape hatch** (free streak freeze/repair — paid-only forgiveness is the named dark line), a **counter-metric** (streak-anxiety signals), and a **truthfulness proof** (streaks derived from real check-ins, never a mutable counter). Guilt/shame/confirmshaming notification copy, or pairing a streak-break with a spend prompt, is a dark-pattern veto (`failure-cards.md`). `check:emotional-design` enforces the attestation fields.
+- **Timezone-correct streaks are the classic correctness trap.** Local dates derive from the profile timezone server-side; DST transitions, timezone changes, and the 11:58pm check-in are required test cases in `engineering/TECH_SPEC.md`. A streak engine that lies after a DST shift fails the truthfulness proof, not just QA.
+- **Analytics before surfaces lock.** `habit_created`, `habit_checked_in`, `streak_extended`, `streak_recovered` (plus the reminder and paywall events in their prompts) must exist in `analytics/ANALYTICS.md` before prompts 03/04 surfaces lock (`analytics-attribution.md`).
+- **Revenue reconciles with the SOSA-grounded defaults — as tests, founder-gated.** Prompt 06 surfaces the `revenue-monetization.md` §3 benchmarks (hard paywall ~5x freemium conversion, yearly-dominant plans realize the highest LTV, ≤4-day trials underperform 17–32-day, low prices anchor worthlessness) as strong defaults to test, not dogma; freemium remains a deliberate choice when free users drive accountability-circle network effects. Pricing, plan mix, and trial length are founder-approved. Billing follows the surface: Stripe web, RevenueCat + IAP native.
+- **Security is owner-only RLS, tested.** Habit data is private, health-adjacent data: every table carries a tested owner-only policy (pgTAP per `backend-data-contract.md`) referenced from `trust/SECURITY.md`; prompt 07's sharing model extends RLS, never client filtering. Reminder push credentials (VAPID/APNs/FCM), cron secrets, and billing webhooks route via `SECRETS.md` and count as abuse surfaces.
+- **Positioning feeds research and launch.** Prompt 00's outputs (the niche's failure mode with generic trackers, the one habit loop, name directions, first-100-users plan) flow into `strategy/RESEARCH.md`, naming, and `growth/LAUNCH_NARRATIVE.md`.
+
+## Infrastructure Defaults (record decisions, do not hardcode)
+
+- **Backend:** Supabase (Postgres + Auth). Check-ins store the local calendar date alongside the UTC timestamp; streaks computed by SQL function/view, never a stored counter.
+- **Hosting:** Vercel (web/PWA). Reminders via a scheduled job (Supabase cron / scheduled function) → web push with email fallback; on native, local notifications replace web push.
+- **Native path:** if reminders/widgets drive a native decision, the backend and streak engine carry over; the Apple/Play signing, store-listing, and review lanes apply in full.
+- **Billing:** Stripe (web) / RevenueCat + StoreKit/Play Billing (native), per `revenue-monetization.md`.
+- **Email:** reminders fallback, magic links, and the weekly review via `resend-email-ops.md`.
+
+## Acceptance Checklist
+
+Before calling a habit-tracker build ready:
+
+- [ ] Habit model, primary surface, optional systems, and niche confirmed via AskUserQuestion and recorded in `state/business-state.json` (with `launchScope: essentials` if the counter variant applies).
+- [ ] Schema (prompt 01) reconciled with `engineering/TECH_SPEC.md`; every user-data table has a tested owner-only RLS policy referenced from `trust/SECURITY.md`; one-check-in-per-day uniqueness enforced in the database.
+- [ ] Timezone captured at signup; streaks computed server-side from local dates; DST/timezone-change/late-night test cases pass in CI.
+- [ ] The check-in loop is run through `11_STAR_EXPERIENCE.md`; Commitment and Streak/Loss-Aversion cards have complete attestation blocks (escape hatch, counter-metric, truthfulness proof, recovery mechanism) passing `check:emotional-design`.
+- [ ] Streak recovery/freeze exists, is free, and is never paired with a spend prompt; notification copy reviewed against the no-guilt rules and `strategy/BRAND.md §Voice`.
+- [ ] `habit_created`, `habit_checked_in`, `streak_extended`, `streak_recovered` (and selected optional-system events) exist in `analytics/ANALYTICS.md`.
+- [ ] Monetization (if in scope) surfaced the `revenue-monetization.md` §3 trade-offs to the founder, uses the correct billing path for the surface, and never paywalls the escape hatch.
+- [ ] Social accountability (if in scope) is opt-in per habit, RLS-scoped, has block/report and invite abuse controls, and never broadcasts misses.

package/knowledge/product/photo-ai-media.md

@@ -0,0 +1,96 @@
+# Photo / AI Media Build Lane
+
+Use this reference when the founder wants to build a **photo / AI-media product** — "an AI avatar app", "a headshot generator", "a photo enhancer/restorer", "an AI art app", "an app that turns photos into X". It is an **app-archetype prompt pack** (peer to [`social-network.md`](./social-network.md) and [`ai-chat-companion.md`](./ai-chat-companion.md)), shipped as reusable boilerplate under [`../surfaces/starters/photo-ai-media/`](../../surfaces/starters/photo-ai-media/README.md).
+
+Like the other archetype lanes, this is a layer on top of the launch workflow, not a replacement. It gives the engineering stages a proven sequence and ready prompts for one product shape and routes each piece back into the existing lanes (research, 11-star, emotional design, security/privacy, revenue, analytics, safety). It does not skip evidence, design, safety, or provider-proof gates.
+
+## When To Use
+
+Load this reference when the product's core is **a user's photo going in and an AI-transformed image coming out** — with a media library, a metered generation pipeline, and a before/after reveal as the central moment. Comparable products: AI headshot/avatar generators, photo restorers and enhancers, AI art/image studios, and "turn your photo into X" utilities.
+
+Do **not** use it for a product that merely has an AI filter bolted onto a different core (a social network with one effect, a chat app that can make images); it is for products whose center of gravity is the transformation itself.
+
+## Step 1 — Confirm The Shape (AskUserQuestion)
+
+Before building, confirm the product shape with the founder via **AskUserQuestion** (or a plain founder choice if unavailable). These answers change the schema, the pipeline, the consent posture, the monetization model, and the store path. Ask, in one batched call:
+
+1. **Media shape** — what is the transformation?
+   - **Identity-conditioned avatars/headshots**: a training set of selfies → generated packs of the user's own face. Highest consent and retention-rule burden; pack economics.
+   - **Single-image transform/restore**: one photo in → one enhanced/restored/stylized photo out. Simplest shape; lite-tier friendly.
+   - **Open prompt-to-image studio**: free-text prompts, with or without an input photo. Broadest surface, heaviest prompt-screening burden.
+2. **Primary surface** — **Web / PWA** (default stack: Next.js App Router + Supabase + Vercel) or **native mobile**? A camera-first capture experience pushes native; if native, the Apple/Play store lanes in `SKILL.md` apply in full and digital purchases go through IAP.
+3. **Which optional systems are in the accepted product?** (multi-select) — editing/presets, credits/monetization, sharing/virality. These map to prompts 05–07.
+4. **Niche** — who is this for, and on what occasion? (Free text. Feeds prompt 00 positioning. A focused niche with a recurring occasion beats a general-purpose generator.)
+
+Record the answers in `state/business-state.json` (e.g. `lanes.product.archetype: photo-ai-media`, `media_shape`, `primary_surface`, `optional_systems`) so later sessions do not re-litigate the shape.
+
+Honesty note on the stack: the bundled prompts target **web (Next.js + Supabase + Vercel)**. The storage, schema, RLS, and generation-pipeline prompts carry over unchanged to native; the capture/library/reveal client prompts must be re-expressed for the native stack, and camera-first products usually deserve that investment.
+
+## Runnable Starter
+
+The pack ships a runnable scaffold at [`../surfaces/starters/photo-ai-media/starter/`](../../surfaces/starters/photo-ai-media/starter/README.md): Next.js App Router + Supabase pre-wired with magic-link auth, owner-only schema migrations with **tested** RLS (pgTAP, per `backend-data-contract.md`), private Storage wiring, Stripe and RevenueCat stubs, a PostHog event catalog matching the analytics lane's snake_case conventions, a names-only `.env.example`, and a CI workflow. The **generation provider is deliberately unbound** in the starter: the provider adapter is a stub, because which image model/provider to pay for is a founder-gated decision routed through [`paid-tool-routing.md`](../operations/paid-tool-routing.md), recorded in `strategy/TOOL_DECISIONS.md`, with its key server-side via `SECRETS.md`. Copy the starter into the business repo as the floor and customize it with the prompts below — its README maps each prompt to the scaffold area it customizes. Do not improvise the same wiring from scratch; `check:archetype-starter` enforces the starter contract. If the founder selects Firebase or a custom backend, adapt through the data-contract lane instead of running the Supabase pieces verbatim.
+
+## The Core Systems
+
+Every photo/AI-media product is built on five systems. The generation pipeline and the safety/rights layer are the two that most teams under-build.
+
+1. **User Identity** — auth, sessions, profile; the anonymous-try tradeoff. → prompt `02-auth-system`.
+2. **Media Storage & Library** — uploads and outputs in private object storage, owner-scoped paths, signed URLs, the library grid. → `01-database-schema`, `03-capture-and-library`.
+3. **Generation Pipeline & Metering** — the server-side job system: queue, status, idempotency, retries, and per-generation cost in a credit ledger. Product cost lives here. → `01-database-schema`, `04-ai-generation-pipeline`, `06-credits-and-monetization`.
+4. **Reveal & Editing Surface** — the before/after reveal, presets/styles, re-runs. Product joy lives here. → `03-capture-and-library`, `05-editing-and-presets`, `07-sharing-and-virality`.
+5. **Safety & Rights Layer** — NSFW/CSAM screening on input and output, likeness consent, rights posture, takedown, age gating. Non-optional before public launch. → `08-content-safety-and-rights`.
+
+## The Build Sequence
+
+Build one system at a time and test it. Prompts live in [`../surfaces/starters/photo-ai-media/prompts/`](../../surfaces/starters/photo-ai-media/README.md):
+
+| #   | Prompt                                                 | Core system                   | Threads into                                                                                |
+| --- | ------------------------------------------------------ | ----------------------------- | ------------------------------------------------------------------------------------------- |
+| 00  | `00-positioning-strategy` (Claude.ai, not Claude Code) | positioning                   | `strategy/RESEARCH.md`, naming, `growth/LAUNCH_NARRATIVE.md`                                |
+| 01  | `01-database-schema`                                   | media + generations + credits | `engineering/TECH_SPEC.md`, engineering, security (RLS + Storage policies)                  |
+| 02  | `02-auth-system`                                       | identity                      | engineering, `trust/SECURITY.md`, `SECRETS.md`                                              |
+| 03  | `03-capture-and-library`                               | storage + library + reveal    | `11_STAR_EXPERIENCE.md`, `analytics/ANALYTICS.md`, privacy                                  |
+| 04  | `04-ai-generation-pipeline`                            | pipeline + metering           | `strategy/TOOL_DECISIONS.md`, `SECRETS.md`, `ethics-guardrail.md`, `analytics/ANALYTICS.md` |
+| 05  | `05-editing-and-presets` (optional)                    | reveal/editing                | `consumer-product-design-agency.md`, revenue                                                |
+| 06  | `06-credits-and-monetization` (optional)               | metering + revenue            | `revenue-monetization.md`, `revenue/REVENUE_OPS.md`                                         |
+| 07  | `07-sharing-and-virality` (optional)                   | sharing/growth                | `viral-growth-loops.md`, `VIRAL_GROWTH.md`                                                  |
+| 08  | `08-content-safety-and-rights`                         | safety/rights                 | `security-release-hardening.md`, `ethics-guardrail.md`, `privacy-terms.md`, store review    |
+
+Variants (apply after the base): [`variants/avatar-headshot-studio`](../../surfaces/starters/photo-ai-media/prompts/variants/avatar-headshot-studio.md) and [`variants/photo-restoration`](../../surfaces/starters/photo-ai-media/prompts/variants/photo-restoration.md).
+
+Step 0 (positioning) is strategic work for the **web interface / Claude.ai**. The rest are Claude Code build prompts. Prompt 08 is required **before any public launch**, regardless of which optional prompts ship.
+
+## How This Lane Threads Into The Launch Workflow
+
+- **The before/after reveal is the 11-star moment.** Run [`eleven-star-experience.md`](../experience/eleven-star-experience.md) over prompts 03/04: the second the user drags the slider and sees their photo transformed is the magical accepted product experience — everything else sets it up. Name it as an engineered moment with a PostHog event and a reduced-motion fallback (`consumer-product-design-agency.md`, `emotional-design-system.md`).
+- **The reveal is a Variable Reward card — HIGH risk.** Output quality genuinely varies between runs, which is exactly the variable-ratio mechanism `ethics-guardrail.md` rates HIGH. The card's contract is mandatory: `ethics_attestation`, a `user_control_escape_hatch` (the user can always stop; no near-miss engineering, no "one more spin" pressure at the credit floor), a `counter_metric` (e.g. regeneration spirals per session), and `reward_variation_proof` (variation is the model's real output variance, never manufactured). The generation wait is a Perceived Effort Delay card: progress reflects the real job status (`computation_type: real_api_call`) — no fake work, no padded timers.
+- **The four lane events must exist in `analytics/ANALYTICS.md` before surfaces lock:** `media_uploaded`, `generation_started`, `generation_completed`, `media_shared` (per `analytics-attribution.md`; counts and metadata, never image content). Prompts 03–07 add their own surface events on top.
+- **Per-generation COGS reshapes the revenue lane.** Every generation has a provider invoice behind it, so **metering precedes monetization**: the credit ledger (prompt 01) and cost tracking (prompt 04) come before any paywall (prompt 06). Reconcile the model with `revenue-monetization.md` and treat its §3 SOSA 2026 figures (hard paywall ~5x freemium, yearly-dominant highest LTV, price as quality signal, AI apps earn more per payer but churn faster) as **defaults to test, not dogma**. Pricing, plan mix, and the free grant are founder-gated.
+- **The generation provider is a paid-tool decision, not a default.** Do not hardcode a model/provider: route the choice through `paid-tool-routing.md`, confirm with the founder, record it in `strategy/TOOL_DECISIONS.md`, and keep the key server-side via `SECRETS.md` ([`secrets-management.md`](../operations/secrets-management.md)). The pipeline's adapter interface exists so the decision stays swappable.
+- **Faces are biometric-adjacent PII.** Owner-scoped storage paths, signed URLs only (media never served from the app server, no public buckets), tested RLS on every user-data table, EXIF GPS stripping, and real retention/deletion paths (rows + storage objects + provider-side copies) are `security-release-hardening.md` and `privacy-terms.md` items, hardened further by the avatar variant's identity-retention rules.
+- **Safety and rights are a launch gate.** Prompt 08 — NSFW/CSAM screening on input AND output, likeness consent, the training-data/rights posture store review asks about, a takedown path, and age gating — is required before any public launch. App Review rejects AI-generation apps without a moderation story; deceptive intimate imagery and non-consensual likeness use are `ethics-guardrail.md` compliance vetoes.
+
+## Infrastructure Defaults (record decisions, do not hardcode)
+
+- **Backend:** Supabase (Postgres + Auth + **Storage**). All media in private Storage buckets with owner-scoped paths and signed URLs; never serve media from the app server. At significant media volume, migrate to zero-egress object storage.
+- **Generation provider:** deliberately unbound — founder-gated via `paid-tool-routing.md`, recorded in `strategy/TOOL_DECISIONS.md`, key server-side via `SECRETS.md`. Generation runs as server-side jobs with status polling, idempotency, and per-generation cost recording.
+- **Hosting:** Vercel (web). Long generations run as background jobs the client polls — do not hold serverless requests open for the provider.
+- **Moderation:** input AND output image screening (plus prompt screening for the studio shape) wired before public launch — a store-review requirement for this category, not a nicety.
+- **Monetization:** Stripe for web; RevenueCat over StoreKit/Play Billing for native IAP (packs are consumables). Credits/metering first.
+- **Email:** magic links, "pack is ready" notifications, and lifecycle via `resend-email-ops.md`.
+
+## Extending / Acceptance
+
+This pack follows the archetype contract enforced by `check:app-archetype` (README + numbered prompts with fenced blocks + reference + SKILL.md routing + agent-behavior eval). To add another archetype, mirror this shape under `starters/<archetype>/`.
+
+Before calling a photo/AI-media build ready:
+
+- [ ] Media shape, primary surface, optional systems, and niche confirmed via AskUserQuestion and recorded in `state/business-state.json`.
+- [ ] Generation provider chosen via `paid-tool-routing.md` with the founder, recorded in `strategy/TOOL_DECISIONS.md`; the provider key is server-side only via `SECRETS.md`; the pipeline route has ownership checks, credit checks, rate limits, and a concurrency cap in `trust/SECURITY.md`.
+- [ ] Schema (prompt 01) reconciled with `engineering/TECH_SPEC.md`; every user-data table has a tested owner-only RLS policy and the Storage bucket policies enforce owner-scoped paths; media is served only via signed URLs.
+- [ ] The before/after reveal is run through `11_STAR_EXPERIENCE.md`; the Variable Reward card carries `ethics_attestation`, `user_control_escape_hatch`, `counter_metric`, and `reward_variation_proof`; the wait state is honest progress (no fake work).
+- [ ] `media_uploaded`, `generation_started`, `generation_completed`, `media_shared` exist in `analytics/ANALYTICS.md` before surfaces lock.
+- [ ] Credits/metering (with per-generation cost) precede any paywall; monetization reconciled with `revenue-monetization.md` (§3 defaults surfaced as tests) and the correct billing path for the surface (Stripe web / IAP native); pricing founder-gated.
+- [ ] Safety/rights pass (prompt 08) complete before public launch: input/output (and prompt) screening, CSAM detection + reporting, likeness consent, rights posture, takedown path, age gating; reconciled with `privacy-terms.md` and the store-review moderation story.
+- [ ] Retention/deletion paths for faces (rows + storage + provider-side copies; identity data for the avatar variant) documented and working.
+- [ ] Positioning outputs from prompt 00 flow into `strategy/RESEARCH.md`, naming, and `growth/LAUNCH_NARRATIVE.md`.

package/knowledge/product/product-moat.md

@@ -0,0 +1,64 @@
+# Product Moat And Core-Loop Innovation
+
+The skill's deepest library makes a chosen feature set feel premium, ethical, and sticky. This reference governs the prior question: whether the feature set itself deserves to exist. Load it with [`eleven-star-experience.md`](../experience/eleven-star-experience.md) — before the 11-star ladder locks the magical moment — and again whenever a wedge claim needs pressure-testing. Polish on a commodity idea produces a beautiful app nobody switches to; the moat work is what gives the polish something to compound on.
+
+## Contents
+
+- 1. The One-Week-Copy Test
+- 2. Moat Taxonomy
+- 3. Functional Benchmark Against The Incumbent
+- 4. Upgrading A Weak Wedge
+- 5. The Differentiation Artifact
+- 6. Anti-Patterns
+
+## 1. The One-Week-Copy Test
+
+For every wedge claim, answer in writing: **if the top incumbent saw this feature today, what stops them shipping it in a week?** Honest answers are structural — accumulated user data the copy would lack, a workflow position the incumbent's architecture fights, a community that lives here, a taste/curation engine that took months to tune, pricing the incumbent's margins cannot follow, or a distribution channel the incumbent does not own. "They have not thought of it" and "ours is better designed" are not answers; both are copied in a sprint. A wedge that fails the test is not necessarily dead — it means the plan must name how the wedge _becomes_ structural before the incumbent notices (§4), or the verdict conversation moves toward Pivot.
+
+## 2. Moat Taxonomy
+
+Name the moat class the app is building toward — one primary, honestly:
+
+- **Data moat:** every session makes the product better for that user in a way a fresh install cannot match (personalization corpus, history-dependent insight). Strongest in consumer apps; starts accruing day one.
+- **Workflow/switching moat:** the user's accumulated state (streaks earned, libraries built, routines encoded) makes leaving expensive. Legitimate when the state serves the user; the ethics contract bans manufacturing lock-in that serves only the chart.
+- **Community/network moat:** value comes from who else is here (partners, groups, shared boards). Only claimable when the loop genuinely needs a second person.
+- **Taste/curation moat:** an opinionated engine (content, coaching, aesthetics) tuned by feedback that a competitor cannot replicate from a screenshot.
+- **Model/pipeline moat:** a generation or analysis pipeline whose quality comes from proprietary tuning, chained steps, or evaluation data — not from a thin wrapper on the same API the incumbent can call (the AI-archetype trap).
+- **Distribution moat:** an owned audience, creator engine, or SEO/GEO position that makes acquisition structurally cheaper. Real, but it protects the business, not the product — pair it with one of the above.
+
+"No moat yet, racing to build X" may be an explicitly acknowledged business risk when X is named, dated, and revisited at the day-30 retro. "Our execution will be better" is not a moat class.
+
+## 3. Functional Benchmark Against The Incumbent
+
+Before the spec hardens, run the app's core job against the named incumbents as a user would experience it:
+
+- Pick the top 2–3 incumbents from `strategy/RESEARCH.md`'s competitor evidence — by revenue, not by similarity comfort.
+- For the single core job, record: steps to first value, quality of the result, and the one moment the incumbent is weak (onboarding friction, generic output, price wall, dated design — with evidence from reviews/social mining, not taste).
+- The new app must name the **beat moment**: the specific moment in the core loop where a user who knows the incumbent would say "this is better," and why that gap survives the one-week-copy test.
+- If no beat moment survives scrutiny, that finding goes into the Go/Pivot/Kill evidence — it is exactly what the checkpoint exists to hear.
+
+## 4. Upgrading A Weak Wedge
+
+A weak wedge is a routing signal, not a verdict. Before it reaches the founder as a Pivot recommendation:
+
+- Run `ce-brainstorm` (or `llm-council` when available) on the specific question "what would make this structurally uncopyable," seeded with the incumbent teardown and the moat taxonomy — not a generic "improve the idea" pass.
+- The productive moves, in rough order: narrow the audience until the incumbent's generality becomes its weakness; move earlier or later in the user's workflow than the incumbent sits; attach the loop to data the incumbent does not collect; or invert the incumbent's monetization (what they charge for, give away; charge for what their model cannot afford to give).
+- One upgrade cycle, time-boxed. If the wedge is still generic after it, the honest evidence goes to the founder — the launch machinery must never outrun the reason for the app to exist.
+
+## 5. The Differentiation Artifact
+
+The wedge lives in `PRODUCT.md`'s **Differentiation And Moat** section, not in a chat transcript. The archetype positioning prompts (each pack's `00-*.md`) produce the raw answers; they are transcribed here verbatim and then held to this reference's tests. The section carries:
+
+- the incumbent table: top 2–3 by revenue, each with what it does well, the beat moment, and what stops a week-one copy
+- the named moat class (§2) and the concrete build plan for it
+- the one-week-copy test answer in writing
+
+A done product lane needs a real incumbent row and a named moat class recorded here — a positioning chat that never lands in the spec is the artifact-less wedge the 2026-07-26 audit found on real launches. The section feeds `state/LAUNCH_TRACE.md`, the 11-star ladder's magical-moment choice, and the Go/Pivot/Kill evidence row.
+
+## 6. Anti-Patterns
+
+- **Polish as strategy.** Betting on execution quality against an incumbent with distribution — the emotional-design library making a commodity loop feel premium while nothing stops the copy.
+- **Wrapper confidence.** An AI app whose entire capability is one API call the incumbent can make tomorrow, with no pipeline, data, or evaluation moat named.
+- **Positioning theater.** A wedge articulated once in a chat, never transcribed, never tested, never traced — invisible to every gate.
+- **Similarity comfort.** Benchmarking against small apps that resemble the idea instead of the revenue leaders who own the users.
+- **Moat someday.** "Network effects eventually" with no named mechanism, date, or retro checkpoint.

package/knowledge/product/social-network.md

@@ -0,0 +1,117 @@
+# Social / Community Platform Build Lane
+
+Use this reference when the founder's request is to build a **social or community platform** — "build a social network", "X/Twitter clone", "Instagram clone", "TikTok clone", "a community app for <niche>", "a forum/feed app", "people post and follow each other". It is the first **app-archetype prompt pack**: a recognizable B2C product shape with a known set of core systems and a battle-tested build sequence, shipped as reusable boilerplate prompts under [`../surfaces/starters/social-network/`](../../surfaces/starters/social-network/README.md).
+
+This lane does **not** replace the launch workflow in `SKILL.md`. It is a layer on top of it: it gives the engineering/build stages a proven sequence and ready prompts for one product shape, and it routes each piece back into the existing lanes (research, 11-star, design, security, revenue, growth, analytics). Do not use it to skip evidence, design, security, or provider-proof gates.
+
+## When To Use
+
+Load this reference when:
+
+- The founder describes a product whose core is **posts + a social graph + a feed + engagement + notifications** (the five core systems below), regardless of the content format.
+- The request names a comparable platform (X, Instagram, TikTok, Reddit, Discord, BeReal, Substack-as-network) or a niche community version of one.
+- You are at the spec/engineering/handoff stage of such a product and want the boilerplate prompt sequence instead of improvising the schema and feed from scratch.
+
+Do **not** force this lane onto a product that merely has a comment section or a single social feature; it is for products whose center of gravity is the social loop.
+
+## Step 1 — Detect The Archetype And Confirm The Variant (AskUserQuestion)
+
+Before writing schema or specs, confirm the product shape with the founder using **AskUserQuestion** (or a plain founder choice if AskUserQuestion is unavailable). This is a bounded product-shape decision that changes the schema, the feed, the design, and the store path — it is worth one upfront question, and it is not a founder-only gate that blocks other work.
+
+Ask, in one batched call:
+
+1. **Content format** — what is a "post" at its core?
+   - **Text-first** (X/Twitter model): short text, optional images. Feed is a timeline list.
+   - **Image-first** (Instagram model): at least one image required, optional caption. Feed is a grid; adds Stories + Explore.
+   - **Video-first** (TikTok model): short vertical video. Feed is full-screen, swipe-driven, algorithmic.
+2. **Primary surface** — where does the accepted product run?
+   - **Web / PWA** (the prompt pack's default stack: Next.js App Router + Supabase + Vercel).
+   - **Native mobile** (iOS/Android): the same five systems and Supabase backend hold, but the client prompts must be re-expressed for the native stack and the Apple/Play store lanes in `SKILL.md` apply in full.
+3. **Which optional systems are in the accepted product?** (multi-select) — direct messages, monetization (subscriptions + creator support), invite-only onboarding, search/discovery. These map to the optional prompts in the pack.
+4. **Niche** — who is this community for? (Free text. Feeds Step 2 positioning. A focused niche is the whole strategy: a smaller, highly engaged community beats a general-purpose clone.)
+
+Record the answers in `state/business-state.json` (under the product lane, e.g. `lanes.product.archetype: social-network`, `content_format`, `primary_surface`, `optional_systems`) so later sessions do not re-litigate the shape.
+
+Honesty note on the stack: the bundled prompts target **web (Next.js + Supabase + Vercel)** because that is the fastest path to a working multi-user social product. If the founder picks native mobile, say so plainly — the schema, RLS, real-time, and storage prompts carry over unchanged, but the auth/feed/profile/DM client prompts are web prompts and must be adapted, and the full iOS signing/ASC/store lanes become required rather than optional.
+
+## Runnable Starter
+
+The pack ships a runnable scaffold at [`../surfaces/starters/social-network/starter/`](../../surfaces/starters/social-network/starter/README.md): Next.js App Router + Supabase pre-wired with magic-link auth, schema migrations with **tested** RLS (pgTAP, per `backend-data-contract.md`), Stripe and RevenueCat stubs, a PostHog event catalog matching the analytics lane's snake_case conventions, a names-only `.env.example`, and a CI workflow. Copy it into the business repo as the floor and customize it with the prompts below — its README maps each prompt to the scaffold area it customizes. Do not improvise the same wiring from scratch; `check:archetype-starter` enforces the starter contract. If the founder selects Firebase or a custom backend, adapt through the data-contract lane instead of running the Supabase pieces verbatim.
+
+## The Five Core Systems
+
+Every social platform — text, image, or video — is built on the same five systems. If any one is missing or broken, the product does not work. The build sequence exists to complete them in dependency order.
+
+1. **User Identity** — registration, authentication, sessions, profiles, verification. First built, last revisited. → prompt `02-auth-system`, profile half of `04-profiles-and-follow`.
+2. **Content Creation & Storage** — posts, media in object storage, validation, association to the creator. Only the media type changes between variants. → prompt `01-database-schema`, `03-feed-and-posts`, plus the variant deltas.
+3. **Social Graph** — who follows whom (asymmetric for the X model). The most performance-sensitive part; it decides what reaches each feed. → follow half of `04-profiles-and-follow`.
+4. **Feed** — what each user sees and in what order. Choose chronological ordering when it serves the accepted user promise (understandable, debuggable, trusted). A required ranked or hybrid feed must be implemented and verified, not deferred as a shortcut. The video-first variant is the exception — it needs a recommendation mix from day one. → `03-feed-and-posts`, video-first variant.
+5. **Engagement & Reactions** — likes, reposts, replies/comments, and the notifications they generate. Notifications must be async and not block the main request cycle. → engagement half of `03-feed-and-posts`, notification half of `04-profiles-and-follow`.
+
+## The Build Sequence
+
+Build **one system at a time, test it, then move on**. A solid identity + feed beats ten half-built features. Run the prompts in this order; each lives in [`../surfaces/starters/social-network/prompts/`](../../surfaces/starters/social-network/README.md):
+
+| #   | Prompt                                           | Core system                      | Threads into                                                                    |
+| --- | ------------------------------------------------ | -------------------------------- | ------------------------------------------------------------------------------- |
+| 00  | `00-niche-strategy` (Claude.ai, not Claude Code) | positioning                      | `strategy/RESEARCH.md`, naming, `VIRAL_GROWTH.md`, `growth/LAUNCH_NARRATIVE.md` |
+| 01  | `01-database-schema`                             | content + graph + engagement     | `engineering/TECH_SPEC.md`, engineering lane, security (RLS)                    |
+| 02  | `02-auth-system`                                 | identity                         | engineering, `trust/SECURITY.md`, `SECRETS.md` (OAuth keys)                     |
+| 03  | `03-feed-and-posts`                              | content + feed + engagement      | `11_STAR_EXPERIENCE.md` core loop, `analytics/ANALYTICS.md` events              |
+| 04  | `04-profiles-and-follow`                         | identity + graph + notifications | engineering, real-time, `analytics/ANALYTICS.md`                                |
+| 05  | `05-search-and-discovery` (optional)             | discovery                        | engineering, growth                                                             |
+| 06  | `06-direct-messages` (optional)                  | engagement                       | engineering, real-time, abuse controls                                          |
+| 07  | `07-stripe-monetization` (optional)              | revenue                          | `revenue-monetization.md`, `revenue/REVENUE_OPS.md`                             |
+| 08  | `08-invite-system` (optional)                    | growth                           | `viral-growth-loops.md`, `VIRAL_GROWTH.md`                                      |
+
+Variants (apply after the text-first base, or fold into prompt 01/03 if chosen upfront): [`variants/image-first-instagram`](../../surfaces/starters/social-network/prompts/variants/image-first-instagram.md) and [`variants/video-first-tiktok`](../../surfaces/starters/social-network/prompts/variants/video-first-tiktok.md).
+
+Step 0 (niche strategy) is strategic work for the **web interface / Claude.ai**, not Claude Code — it is about people, not systems. The rest are Claude Code build prompts.
+
+## How This Lane Threads Into The Launch Workflow
+
+The prompt pack is the engineering spine, not the whole launch. Keep these connections live:
+
+- **Database schema first.** Prompt 01 produces the schema every other system builds on; getting it wrong means expensive rewrites. Reconcile it with `engineering/TECH_SPEC.md` (data model, API contracts, RLS policies) before building clients.
+- **Row Level Security is the security lane, not a checkbox.** The schema prompt emits Supabase RLS so users can only edit their own data. Treat RLS policies as part of `security-release-hardening.md`: every table that holds user data needs a policy and a test, and entitlement/visibility rules (private accounts, blocks) belong in the threat model.
+- **The feed is the 11-star core loop.** Prompt 03 is where the defining product moment lives. Run [`eleven-star-experience.md`](../experience/eleven-star-experience.md) over it, and name the optimistic-UI like/repost reveal and the real-time arrival of new posts as engineered moments with PostHog events and reduced-motion fallbacks (`consumer-product-design-agency.md`, `emotional-design-system.md`).
+- **Monetization reconciles with the revenue lane.** Prompt 07 uses **Stripe** (Checkout + Customer Portal + Connect for creator payouts) because the default surface is web. If the founder ships native iOS, digital subscriptions generally must go through StoreKit/IAP (route via `revenue-monetization.md` and RevenueCat); Stripe Connect creator payouts and physical/real-world value can stay on Stripe. Do not ship the web Stripe paywall inside an iOS binary without resolving App Store policy first.
+- **Invites are a growth loop, not just a gate.** Prompt 08 feeds `viral-growth-loops.md`: invite acceptance rate, inviter attribution, and the invitation tree are the loop's analytics. Pre-loading value before opening the doors (build-in-public → invite-only beta → referral codes) is the standard cold-start sequence.
+- **Positioning feeds research and launch.** Prompt 00's outputs (what the community hates about incumbents, the one tell-a-friend feature, name directions, first-100-users plan) flow into `strategy/RESEARCH.md`, naming, and `growth/LAUNCH_NARRATIVE.md`.
+- **Analytics before surfaces lock.** Every engagement and notification path named in prompts 03/04/06 needs an event in `analytics/ANALYTICS.md` before build (`analytics-attribution.md`).
+- **Don't optimize for scale before users.** Build the monolith, ship it, get users, then optimize the queries that actually become bottlenecks. A feed query that is inefficient at 100 users is fine until ~10,000.
+
+## Infrastructure Defaults (record decisions, do not hardcode)
+
+These are the pack's default choices; confirm and record them in `strategy/TOOL_DECISIONS.md` / `SECRETS.md` rather than assuming:
+
+- **Backend:** Supabase (Postgres + Auth + Realtime + Storage). Object storage for all media — never serve media from the app server. At significant media volume, migrate to Cloudflare R2 (zero egress).
+- **Hosting:** Vercel (preview URL per PR, global CDN) for the web surface.
+- **Video transcoding (video-first only):** Mux or Cloudflare Stream for adaptive bitrate.
+- **Email:** route through the existing `resend-email-ops.md` lane (verification, follower/notification digests).
+- **Moderation from day one:** rate limiting on post creation, a basic word filter, image moderation (Google Vision / AWS Rekognition), and text classification (Claude API) before opening publicly. This is a launch gate for any public social product, not optional future polish.
+
+## Extending This Layer With New Archetypes
+
+This is the first archetype pack. To add another (e.g. marketplace, dating, journaling, habit-tracker):
+
+1. Add `starters/<archetype>/README.md` + `prompts/` with the same shape (numbered, dependency-ordered, copy-paste-ready prompts with skill-integration notes).
+2. Add a peer reference (or a section here) describing its core systems, the AskUserQuestion shape, and how each prompt threads into the existing lanes.
+3. Wire it into `SKILL.md` (archetype-detection step + a When-To-Load rule) and add an agent-behavior eval that locks in "detect archetype → confirm via AskUserQuestion → load the pack → sequence the prompts".
+4. Keep the prompts faithful to their source but improve them to match this skill's contracts (RLS, analytics events, reduced-motion, provider proof).
+
+## Acceptance Checklist
+
+Before calling a social-platform build ready:
+
+- [ ] Archetype + content format + primary surface + optional systems confirmed via AskUserQuestion and recorded in `state/business-state.json`.
+- [ ] Schema (prompt 01) reconciled with `engineering/TECH_SPEC.md`; every user-data table has a tested RLS policy referenced from `trust/SECURITY.md`.
+- [ ] The five core systems are each complete and tested before dependent features start.
+- [ ] The feed core loop is run through `11_STAR_EXPERIENCE.md` with named engineered moments and PostHog events in `analytics/ANALYTICS.md`.
+- [ ] Monetization (if in scope) is reconciled with `revenue-monetization.md` and the correct billing path for the chosen surface (Stripe for web; IAP/StoreKit for native digital subscriptions).
+- [ ] Invite/referral mechanics (if in scope) are tied to `viral-growth-loops.md` with acceptance-rate and attribution analytics and self-referral/abuse controls.
+- [ ] Moderation baseline (rate limits, word filter, image + text classification) is specified before any public launch.
+- [ ] Positioning outputs from prompt 00 flow into `strategy/RESEARCH.md`, naming, and `growth/LAUNCH_NARRATIVE.md`.
+</content>
+
+</invoke>