b2c-app-builder 0.221.39

package/surfaces/starters/habit-tracker/starter/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "habit-tracker-starter",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "typecheck": "tsc --noEmit",
+    "test:rls": "supabase test db"
+  },
+  "dependencies": {
+    "@supabase/ssr": "0.12.0",
+    "@supabase/supabase-js": "2.108.1",
+    "next": "16.2.9",
+    "posthog-js": "1.384.1",
+    "posthog-node": "5.36.10",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "stripe": "22.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.20",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "typescript": "5.9.3"
+  }
+}

package/surfaces/starters/habit-tracker/starter/proxy.ts

@@ -0,0 +1,12 @@
+import { type NextRequest } from "next/server";
+import { updateSession } from "@/lib/supabase/proxy";
+
+// Next.js 16 network boundary (formerly middleware.ts). Refreshes the
+// Supabase session on every matched request.
+export async function proxy(request: NextRequest) {
+  return await updateSession(request);
+}
+
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)"],
+};

package/surfaces/starters/habit-tracker/starter/supabase/migrations/0001_init.sql

@@ -0,0 +1,84 @@
+-- Habit-tracker starter schema (prompt 01 baseline).
+-- Habit data is private: owner-only RLS on every table, tested in
+-- supabase/tests/0001_rls.test.sql per backend-data-contract.md.
+-- Timezone matters: streaks are computed against the user's local midnight,
+-- so the profile carries an IANA timezone captured at signup (prompt 02).
+
+create table public.profiles (
+  id uuid primary key references auth.users (id) on delete cascade,
+  display_name text,
+  timezone text not null default 'UTC',
+  created_at timestamptz not null default now()
+);
+
+create table public.habits (
+  id uuid primary key default gen_random_uuid(),
+  owner_id uuid not null references public.profiles (id) on delete cascade,
+  name text not null check (char_length(name) between 1 and 80),
+  cadence text not null default 'daily' check (cadence in ('daily', 'weekly')),
+  archived_at timestamptz,
+  created_at timestamptz not null default now()
+);
+
+-- One check-in per habit per local day; checked_on is the user-local date.
+create table public.habit_checkins (
+  id uuid primary key default gen_random_uuid(),
+  habit_id uuid not null references public.habits (id) on delete cascade,
+  owner_id uuid not null references public.profiles (id) on delete cascade,
+  checked_on date not null,
+  created_at timestamptz not null default now(),
+  unique (habit_id, checked_on)
+);
+
+-- Streak recoveries are the ethical escape hatch for the HIGH-risk streak
+-- mechanic (ethics-guardrail.md): a missed day can be repaired, and usage of
+-- this table is the counter-metric.
+create table public.streak_recoveries (
+  id uuid primary key default gen_random_uuid(),
+  habit_id uuid not null references public.habits (id) on delete cascade,
+  owner_id uuid not null references public.profiles (id) on delete cascade,
+  recovered_on date not null,
+  created_at timestamptz not null default now(),
+  unique (habit_id, recovered_on)
+);
+
+create table public.reminders (
+  id uuid primary key default gen_random_uuid(),
+  habit_id uuid not null references public.habits (id) on delete cascade,
+  owner_id uuid not null references public.profiles (id) on delete cascade,
+  remind_at_local time not null,
+  enabled boolean not null default true,
+  created_at timestamptz not null default now()
+);
+
+create index habits_owner_idx on public.habits (owner_id, created_at);
+create index checkins_habit_day_idx on public.habit_checkins (habit_id, checked_on desc);
+create index checkins_owner_day_idx on public.habit_checkins (owner_id, checked_on desc);
+create index reminders_owner_idx on public.reminders (owner_id);
+
+alter table public.profiles enable row level security;
+alter table public.habits enable row level security;
+alter table public.habit_checkins enable row level security;
+alter table public.streak_recoveries enable row level security;
+alter table public.reminders enable row level security;
+
+create policy "read own profile" on public.profiles for select using ((select auth.uid()) = id);
+create policy "insert own profile" on public.profiles for insert with check ((select auth.uid()) = id);
+create policy "update own profile" on public.profiles for update using ((select auth.uid()) = id);
+
+create policy "read own habits" on public.habits for select using ((select auth.uid()) = owner_id);
+create policy "insert own habits" on public.habits for insert with check ((select auth.uid()) = owner_id);
+create policy "update own habits" on public.habits for update using ((select auth.uid()) = owner_id);
+create policy "delete own habits" on public.habits for delete using ((select auth.uid()) = owner_id);
+
+create policy "read own checkins" on public.habit_checkins for select using ((select auth.uid()) = owner_id);
+create policy "insert own checkins" on public.habit_checkins for insert with check ((select auth.uid()) = owner_id);
+create policy "delete own checkins" on public.habit_checkins for delete using ((select auth.uid()) = owner_id);
+
+create policy "read own recoveries" on public.streak_recoveries for select using ((select auth.uid()) = owner_id);
+create policy "insert own recoveries" on public.streak_recoveries for insert with check ((select auth.uid()) = owner_id);
+
+create policy "read own reminders" on public.reminders for select using ((select auth.uid()) = owner_id);
+create policy "insert own reminders" on public.reminders for insert with check ((select auth.uid()) = owner_id);
+create policy "update own reminders" on public.reminders for update using ((select auth.uid()) = owner_id);
+create policy "delete own reminders" on public.reminders for delete using ((select auth.uid()) = owner_id);

package/surfaces/starters/habit-tracker/starter/supabase/tests/0001_rls.test.sql

@@ -0,0 +1,75 @@
+-- pgTAP RLS tests — run with `supabase test db` (requires the local stack).
+-- backend-data-contract.md: untested authorization rules are a launch blocker.
+-- Habit data is private: owner access works, cross-user and anonymous access
+-- are denied.
+begin;
+create extension if not exists pgtap with schema extensions;
+select plan(6);
+
+insert into auth.users (id, email)
+values
+  ('00000000-0000-0000-0000-000000000001', 'user1@test.local'),
+  ('00000000-0000-0000-0000-000000000002', 'user2@test.local');
+
+insert into public.profiles (id, display_name, timezone)
+values
+  ('00000000-0000-0000-0000-000000000001', 'User One', 'America/New_York'),
+  ('00000000-0000-0000-0000-000000000002', 'User Two', 'UTC');
+
+insert into public.habits (id, owner_id, name)
+values ('10000000-0000-0000-0000-000000000001', '00000000-0000-0000-0000-000000000001', 'morning run');
+
+insert into public.habit_checkins (habit_id, owner_id, checked_on)
+values ('10000000-0000-0000-0000-000000000001', '00000000-0000-0000-0000-000000000001', '2026-06-09');
+
+-- Authenticated as user 1: owner access works.
+set local role authenticated;
+set local request.jwt.claims to '{"sub": "00000000-0000-0000-0000-000000000001", "role": "authenticated"}';
+
+select results_eq(
+  $$select count(*) from public.habits$$,
+  array[1::bigint],
+  'owner can read their own habits'
+);
+
+select lives_ok(
+  $$insert into public.habit_checkins (habit_id, owner_id, checked_on)
+    values ('10000000-0000-0000-0000-000000000001', '00000000-0000-0000-0000-000000000001', '2026-06-10')$$,
+  'owner can check in their own habit'
+);
+
+-- Authenticated as user 2: another user''s habits are invisible and immutable.
+set local request.jwt.claims to '{"sub": "00000000-0000-0000-0000-000000000002", "role": "authenticated"}';
+
+select results_eq(
+  $$select count(*) from public.habits$$,
+  array[0::bigint],
+  'other users cannot read someone else''s habits'
+);
+
+select results_eq(
+  $$select count(*) from public.habit_checkins$$,
+  array[0::bigint],
+  'other users cannot read someone else''s check-ins'
+);
+
+select throws_ok(
+  $$insert into public.habit_checkins (habit_id, owner_id, checked_on)
+    values ('10000000-0000-0000-0000-000000000001', '00000000-0000-0000-0000-000000000001', '2026-06-11')$$,
+  '42501',
+  'new row violates row-level security policy for table "habit_checkins"',
+  'users cannot check in as someone else'
+);
+
+-- Anonymous: nothing is visible.
+set local role anon;
+set local request.jwt.claims to '{}';
+
+select results_eq(
+  $$select count(*) from public.habits$$,
+  array[0::bigint],
+  'anonymous visitors cannot read any habits'
+);
+
+select * from finish();
+rollback;

package/surfaces/starters/habit-tracker/starter/tsconfig.json

@@ -0,0 +1,41 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": [
+        "./*"
+      ]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/surfaces/starters/photo-ai-media/README.md

@@ -0,0 +1,40 @@
+# Photo / AI Media — Boilerplate Prompt Pack
+
+An **app-archetype prompt pack** for this skill: a dependency-ordered set of copy-paste-ready prompts for building a B2C photo / AI-media product (AI avatar or headshot generator, photo enhancer/restorer, AI art/image studio, media-transform utility). Routing, the upfront archetype question, and how each prompt threads into the launch lanes live in [`../../../knowledge/product/photo-ai-media.md`](../../../knowledge/product/photo-ai-media.md). Read that first.
+
+These are **starting prompts**, not final code. Each file has a copy-paste block plus skill-integration notes.
+
+## How to use
+
+1. Confirm the product shape via **AskUserQuestion** (media shape, primary surface, optional systems, niche) — see the reference. Record the selected archetype, scope, and product decisions in `product.yaml`, then render `PRODUCT.md`.
+2. **Copy the runnable starter** ([`starter/`](./starter/README.md)) into the business repo and install it — it is the pre-wired floor (auth, tested owner-only RLS migrations, Supabase Storage wiring, PostHog event catalog, Stripe/RevenueCat stubs, names-only `.env.example`, CI). Do not regenerate this wiring from scratch; `check:archetype-starter` enforces its contract.
+3. Run prompt **00** strategy work on the web interface / Claude.ai.
+4. Run prompts **01 → 04** in order as Claude Code build prompts against the starter (the starter README maps each prompt to the scaffold area it customizes). Build one system, test it, then move on.
+5. Add optional prompts **05 → 07** based on the founder's selection.
+6. Run **08** (content safety & rights) before any public launch — App Store review expects a moderation story from AI-generation apps; this is a launch gate, not a V2 item.
+7. Apply a **variant** (avatar/headshot studio or photo restoration) if relevant.
+
+## Default stack
+
+Next.js App Router + Supabase (Postgres, Auth, **Storage for media**) + Vercel, with all generation calls behind server routes. The **AI generation provider is deliberately not hardcoded**: which image model/provider to use is a paid, founder-gated decision — route it through `paid-tool-routing.md`, record it in `strategy/TOOL_DECISIONS.md`, and keep its API key server-side only via `secrets-management.md` / `SECRETS.md`. Monetization: RevenueCat for native IAP, Stripe for web; per-generation COGS means **credits/metering must exist before monetization**. For a native-mobile surface (camera-first products often need it), the backend carries over but the client is adapted and the Apple/Play store lanes apply in full.
+
+## Build order
+
+| #   | File                                                                                   | Build it                                                                              | Optional?                     |
+| --- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------- |
+| 00  | [`prompts/00-positioning-strategy.md`](./prompts/00-positioning-strategy.md)           | Transformation, wow moment, niche, first 100 users (Claude.ai)                        | strategy                      |
+| 01  | [`prompts/01-database-schema.md`](./prompts/01-database-schema.md)                     | Schema (profiles, media_assets, generations, credits) + RLS + Storage policies + seed | required                      |
+| 02  | [`prompts/02-auth-system.md`](./prompts/02-auth-system.md)                             | Auth + profile (anonymous-try tradeoff noted)                                         | required                      |
+| 03  | [`prompts/03-capture-and-library.md`](./prompts/03-capture-and-library.md)             | Upload/capture, signed URLs, library grid, before/after reveal                        | required                      |
+| 04  | [`prompts/04-ai-generation-pipeline.md`](./prompts/04-ai-generation-pipeline.md)       | Server-side generation route, job/queue, cost tracking, provider-agnostic             | required                      |
+| 05  | [`prompts/05-editing-and-presets.md`](./prompts/05-editing-and-presets.md)             | Presets/styles, re-run with tweaks, watermark lever                                   | optional                      |
+| 06  | [`prompts/06-credits-and-monetization.md`](./prompts/06-credits-and-monetization.md)   | Credit packs vs subscription, paywall                                                 | optional                      |
+| 07  | [`prompts/07-sharing-and-virality.md`](./prompts/07-sharing-and-virality.md)           | Share/export, branded frame, viral loop                                               | optional                      |
+| 08  | [`prompts/08-content-safety-and-rights.md`](./prompts/08-content-safety-and-rights.md) | NSFW/CSAM filtering, consent, rights posture, takedown, age gating                    | required before public launch |
+
+## Variants
+
+| File                                                                                         | Turns the base into                                                                |
+| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| [`prompts/variants/avatar-headshot-studio.md`](./prompts/variants/avatar-headshot-studio.md) | Identity-conditioned avatar/headshot studio (selfie training set → generated pack) |
+| [`prompts/variants/photo-restoration.md`](./prompts/variants/photo-restoration.md)           | Single-image enhance/restore utility with a focused product scope                          |

package/surfaces/starters/photo-ai-media/prompts/00-positioning-strategy.md

@@ -0,0 +1,51 @@
+# 00 — Positioning Strategy (Claude.ai, not Claude Code)
+
+**Run this first, on the web interface / Claude.ai.** AI photo apps are a hit-driven, crowded category; "another AI image app" loses. The win is one specific transformation with a visible before/after wow moment, aimed at a niche a general image studio serves poorly. Replace the bracketed parts with the founder's answers.
+
+```
+I want to build a photo / AI-media product: [avatar/headshot generator /
+photo enhancer-restorer / AI art studio / "turns photos into X" utility] for
+[describe your target user and the occasion that makes them reach for it].
+
+Help me define the positioning:
+1. What is the ONE transformation this product performs, stated as a
+   before → after sentence a user could screenshot and explain?
+2. What is the wow moment — the exact second the user sees the output —
+   and why would it beat what they get from a general AI image tool or a
+   built-in phone editor?
+3. Who is the niche (job seekers, parents with old family photos, dating-
+   profile users, pet owners, a hobby community)? Why does a focused niche
+   beat a general-purpose generator here?
+4. What occasion or trigger creates demand (new job hunt, wedding,
+   holiday card season, profile refresh), and how often does it recur?
+5. What is free, and what does payment unlock (more generations, higher
+   resolution, watermark-free export, premium styles, a full pack)?
+6. How do the first 100 users arrive — which communities, which share
+   format (the before/after image itself?), which creator partnerships?
+
+Also define:
+- The product name direction (3 options with rationale)
+- The tagline (under 8 words)
+- The single before/after example to feature in onboarding and the App Store
+- The moat contract for `PRODUCT.md`'s category and wedge section: the top 2-3
+  incumbents by revenue (what each does well, the moment we beat them, what stops
+  each shipping a copy in a week), the moat class being built (data / workflow /
+  community / taste / model / distribution) with its concrete build plan, and the
+  one-week-copy test answer
+
+Strings: every user-facing label, headline, button, empty state, and error
+comes from product/copy/COPY_DECK.md (author missing rows first — voice from product/copy/COPY_BRIEF.md,
+craft from knowledge/words/conversion-copy.md), typed via the externalized resource
+named in engineering/TECH_SPEC.md. Example copy in this prompt is voice guidance, not
+shipping strings.
+```
+
+## Skill-integration notes
+
+- Answers 1–2 define the wedge → `strategy/RESEARCH.md` and the 11-star magical moment (the reveal in prompt 03/04 must deliver exactly this transformation).
+- Answer 3 (niche) is the whole strategy; it also picks the variant (avatar/headshot vs restoration) and feeds comparable-product research in `strategy/RESEARCH.md`.
+- Answer 4 (occasion + recurrence) is the monetization-model input: one-shot occasions favor credit packs; recurring use favors subscription. Carry it into prompt 06 and `revenue-monetization.md`.
+- Answer 5 constrains metering (prompt 01's credits) and monetization (prompt 06) — per-generation COGS means the free tier is a real cost line, not a marketing default.
+- Answer 6 feeds `VIRAL_GROWTH.md` and `growth/LAUNCH_NARRATIVE.md`; the before/after share format is the loop in prompt 07.
+- Name directions feed naming/collision checks; the tagline and featured before/after feed `APP_STORE_LISTING.md` and landing copy (run `geo-seo.md` before editing landing copy).
+- **Transcribe the wedge into the product contract:** the answers above land in `PRODUCT.md`'s evidence and category section and are held to `product-moat.md`'s tests (one-week-copy, moat class, incumbent beat moment). A done product lane needs a real incumbent row and a named moat class in `PRODUCT.md` — a wedge that lives only in this chat is invisible to every gate.

package/surfaces/starters/photo-ai-media/prompts/01-database-schema.md

@@ -0,0 +1,55 @@
+# 01 — Database Schema (build first)
+
+The foundation: media assets (uploads and generated outputs), the generation ledger, and per-user credits/usage. Get RLS and Storage policies right so one user can never see another's photos — faces are sensitive data.
+
+```
+Design a PostgreSQL database schema for an AI photo/media application (Supabase).
+
+The product supports:
+- Users with accounts (auth handled by Supabase Auth) and a profiles table
+  (display name, optional avatar, marketing-consent flag)
+- media_assets: every media file the system knows about — user uploads AND
+  generated outputs — with owner, storage bucket + path, kind
+  (upload / generated / derived), mime type, width/height, file size,
+  status (pending / ready / failed / removed), optional parent asset
+  (which upload a generation came from), and timestamps
+- generations: one row per generation request — owner, input asset(s),
+  prompt/params (JSONB), preset/style id if any, status
+  (queued / running / succeeded / failed / cancelled), provider + model used,
+  provider job id, cost in credits AND estimated provider cost, error detail,
+  started/finished timestamps, and the output asset id(s)
+- usage_events / credits: a credit ledger (grants, purchases, spends, refunds)
+  with a signed amount, reason, and reference to the generation or purchase —
+  the user's balance is the sum, never a mutable counter
+
+Create:
+1. Full schema with all tables, columns, data types, and constraints
+2. Indexes for the most-queried patterns: a user's library (media_assets by
+   owner + created_at, filtered by kind/status), a user's generation history,
+   and current-balance / period-quota sums over the credit ledger
+3. Row Level Security policies for Supabase so a user can only read/write
+   their own profiles, media_assets, generations, and credit rows (spends are
+   insert-only from the server role, never client-writable)
+4. Supabase Storage bucket definitions and policies: a private media bucket
+   where every object path is prefixed with the owner's user id, with
+   owner-only read/write policies — no public bucket for user media
+5. A seed script with 2 test users, a few uploaded assets, one succeeded and
+   one failed generation, and matching credit-ledger rows
+
+Output as SQL I can run directly in Supabase's SQL editor.
+
+Strings: every user-facing label, headline, button, empty state, and error
+comes from product/copy/COPY_DECK.md (author missing rows first — voice from product/copy/COPY_BRIEF.md,
+craft from knowledge/words/conversion-copy.md), typed via the externalized resource
+named in engineering/TECH_SPEC.md. Example copy in this prompt is voice guidance, not
+shipping strings.
+```
+
+## Skill-integration notes
+
+- Reconcile with `engineering/TECH_SPEC.md` (data model, API contracts, RLS, Storage layout) before building clients. Every user-data table needs a **tested** owner-only policy (pgTAP, per `backend-data-contract.md`) referenced from `trust/SECURITY.md`.
+- **Media is never served from the app server.** Files live in Supabase Storage; clients get short-lived signed URLs (prompt 03). Storage paths are owner-scoped (`<user_id>/...`) so the Storage policies can enforce ownership by prefix.
+- The credit ledger is the metering substrate for prompt 06 — append-only, signed amounts, balance-by-sum. Cost per generation (credits and estimated provider cost) is what makes COGS visible; don't store text-only "success" rows.
+- `generations.provider` / `model` are recorded values, not hardcoded choices — the provider decision is founder-gated (`paid-tool-routing.md`, `strategy/TOOL_DECISIONS.md`); the schema must survive a provider swap.
+- Uploaded faces are biometric-adjacent personal data — note retention and deletion (asset rows AND storage objects AND any provider-side copies) in `privacy-terms.md`.
+- Seed data is development-only.

package/surfaces/starters/photo-ai-media/prompts/02-auth-system.md

@@ -0,0 +1,39 @@
+# 02 — Authentication System
+
+Identity first. Same pattern as any Supabase app; the photo-specific part is that the authenticated user ID scopes every asset, generation, and credit row — and that this category often wants a "try before signup" path, which has a real tradeoff.
+
+```
+Build the authentication system using Next.js App Router and Supabase Auth.
+
+Requirements:
+- Magic-link (email) sign-in as the primary path
+- OAuth login with Google and Apple
+- Protected routes that redirect to login if not authenticated
+- A profile row created on first sign-in (display name, optional avatar)
+- Session management with token refresh
+- A lightweight first-run step (display name + what they want to make) before
+  the first upload
+
+Create:
+1. Login page (/login) with magic-link form and OAuth buttons
+2. Auth middleware that protects all /app/* routes (library, generation)
+3. A useUser() hook that returns the current user anywhere in the app
+4. The first-run profile step
+
+Design: clean, modern, media-forward (the user's photos are the hero). Form
+validation with clear error messages.
+
+Strings: every user-facing label, headline, button, empty state, and error
+comes from product/copy/COPY_DECK.md (author missing rows first — voice from product/copy/COPY_BRIEF.md,
+craft from knowledge/words/conversion-copy.md), typed via the externalized resource
+named in engineering/TECH_SPEC.md. Example copy in this prompt is voice guidance, not
+shipping strings.
+```
+
+## Skill-integration notes
+
+- OAuth client secrets and the Supabase service role key are secrets → route via `SECRETS.md` (`secrets-management.md`). Magic-link and lifecycle emails go through `resend-email-ops.md`.
+- **Anonymous try-before-signup is a common pattern in this category** (upload a photo, see a preview, sign up to keep it). It converts well because the wow moment precedes the ask — but it is also an abuse and cost surface: anonymous generations burn real provider money and dodge per-user quotas. If the founder wants it, gate it deliberately: device-scoped quota of 1 cheap/low-res preview, server-side rate limiting, full safety screening (prompt 08) still applies, and the asset migrates to the account on signup. Surface the tradeoff to the founder; do not silently add or silently skip it.
+- The first-run "what do you want to make" answer is an onboarding surface (`onboarding-conversion.md`) and seeds preset selection (prompt 05) — an Intent Mirroring input, not throwaway copy.
+- Reconcile the look with Design Room tokens (`design-room.md`); don't invent a one-off style.
+- Add `sign_up_completed`, `oauth_used`, `first_run_completed` (and `anonymous_preview_used` if the try-first path ships) to `analytics/ANALYTICS.md`.

package/surfaces/starters/photo-ai-media/prompts/03-capture-and-library.md

@@ -0,0 +1,42 @@
+# 03 — Capture & Library
+
+The media spine: getting photos in, storing them privately, and showing them back fast. The **before/after reveal** built here is the 11-star magical moment — everything else exists to set it up.
+
+```
+Build the photo capture/upload flow and the media library.
+
+Requirements:
+- Upload from file picker and (on supporting devices) camera capture; accept
+  JPEG/PNG/HEIC/WebP with a sensible max size
+- Client-side resize/compress before upload (cap the longest edge, strip EXIF
+  GPS data) so uploads are fast and we never store location metadata
+- Upload to the private Supabase Storage bucket from prompt 01, under the
+  owner-scoped path (<user_id>/uploads/...), creating a media_assets row
+  (kind=upload, status=pending → ready)
+- All display via short-lived signed URLs requested from the server — media is
+  never served from the app server and the bucket is never public
+- Library: a fast grid of the user's assets (uploads and generated outputs),
+  newest first, with kind/status filters, skeleton loading, and empty state
+  that points at the first upload
+- Asset detail view: full-size image, metadata, and — when the asset is a
+  generated output — a before/after reveal against its parent upload
+  (slider or crossfade), plus actions (download, re-run, delete)
+- Delete removes the media_assets row AND the storage object
+
+Handle upload failures with clear retry; show per-file progress for multi-file
+uploads.
+
+Strings: every user-facing label, headline, button, empty state, and error
+comes from product/copy/COPY_DECK.md (author missing rows first — voice from product/copy/COPY_BRIEF.md,
+craft from knowledge/words/conversion-copy.md), typed via the externalized resource
+named in engineering/TECH_SPEC.md. Example copy in this prompt is voice guidance, not
+shipping strings.
+```
+
+## Skill-integration notes
+
+- **The before/after reveal is the magical moment.** Run `eleven-star-experience.md` over it: the slider/crossfade against the original is the second the product proves itself. Name it as an engineered moment with a PostHog event and a reduced-motion fallback (`consumer-product-design-agency.md`, `emotional-design-system.md`, `design-visual-system.md`).
+- Signed URLs are the privacy mechanism, not an optimization: short TTL, generated server-side, never cached into public CDN paths. The owner-scoped path + Storage policies from prompt 01 are part of `security-release-hardening.md`.
+- Client-side resize is also a COGS control — smaller inputs mean cheaper provider calls in prompt 04. Stripping EXIF GPS is a `privacy-terms.md` line item.
+- Deletion must be real: row + storage object (and provider-side copies once prompt 04 exists). Faces are biometric-adjacent data; "delete" that leaves the file in the bucket is a privacy violation.
+- Add `media_uploaded`, `library_viewed`, `before_after_viewed`, `asset_deleted` to `analytics/ANALYTICS.md`.

package/surfaces/starters/photo-ai-media/prompts/04-ai-generation-pipeline.md

@@ -0,0 +1,46 @@
+# 04 — AI Generation Pipeline
+
+This is where product quality and product cost live. The pipeline is **provider-agnostic by design**: which image model/provider to use is a paid, founder-gated decision — route it through `paid-tool-routing.md` and record it in `strategy/TOOL_DECISIONS.md` before filling in the provider adapter. The provider API key is server-side only, via `SECRETS.md`.
+
+```
+Build the AI generation pipeline as a server-side job system. The generation
+provider is pluggable — write a single provider adapter interface
+(submit(input, params) -> provider_job_id, poll(provider_job_id) -> status +
+output) and ONE concrete adapter for the provider I name, keeping the provider
+name, model id, and endpoint in config. Do not scatter provider calls through
+the codebase.
+
+Requirements:
+- A server route that accepts {input asset id(s), preset/params}, validates
+  ownership and remaining credits, creates a generations row (status=queued),
+  and submits the job — the provider API key never reaches the client
+- Asynchronous execution with status polling: the client polls (or subscribes
+  to) the generations row; statuses queued → running → succeeded/failed; show
+  honest progress states tied to the real job status, not a fake timer
+- Idempotency: a client-supplied idempotency key per request so retries and
+  double-taps never create duplicate jobs or double-spend credits
+- On success: store the output in the owner-scoped storage path
+  (<user_id>/generated/...), create the media_assets row (kind=generated,
+  parent = input asset), mark the generation succeeded, and record cost
+  (credits spent + estimated provider cost) in the credit ledger
+- On failure: mark the generation failed with a user-readable reason, refund
+  the credit spend in the ledger, and offer retry; cap automatic retries on
+  transient provider errors with backoff
+- Per-user rate limiting and a concurrent-jobs cap, enforced server-side
+- Never leak raw provider errors or provider identity strings to the client
+
+Strings: every user-facing label, headline, button, empty state, and error
+comes from product/copy/COPY_DECK.md (author missing rows first — voice from product/copy/COPY_BRIEF.md,
+craft from knowledge/words/conversion-copy.md), typed via the externalized resource
+named in engineering/TECH_SPEC.md. Example copy in this prompt is voice guidance, not
+shipping strings.
+```
+
+## Skill-integration notes
+
+- **Provider selection is founder-gated.** Follow `paid-tool-routing.md`: identify the candidate providers, confirm with the founder, record the decision and cost assumptions in `strategy/TOOL_DECISIONS.md`, and route the key through `SECRETS.md`. Do not hardcode a provider because it is familiar — the adapter interface exists so the decision stays swappable.
+- The generation route is the top abuse/cost surface: ownership checks, credit checks, rate limits, and the concurrency cap are `trust/SECURITY.md` items, enforced server-side (a client check is not a control).
+- **The reveal maps to the Variable Reward card — HIGH risk per `ethics-guardrail.md`.** Output quality genuinely varies, which is exactly the variable-ratio mechanism; the card requires `ethics_attestation`, a `user_control_escape_hatch` (the user can always stop; no "one more spin" pressure at the credit floor), a `counter_metric` (e.g. regeneration spirals per session), and `reward_variation_proof` (the variation is the model's real output variance, not engineered near-misses). The waiting state is a Perceived Effort Delay moment: progress must reflect the real job status (`computation_type: real_api_call`) — no fake work, no padded timers (`consumer-product-design-agency.md`).
+- Cost tracking per generation is the unit-economics substrate for prompt 06 — without it, pricing is guesswork. Reconcile the cost model with `revenue-monetization.md`.
+- Add `media_uploaded`, `generation_started`, `generation_completed`, `media_shared` to `analytics/ANALYTICS.md` (the lane's four required events; `generation_completed` carries status, duration, and credit cost as properties — counts and metadata, not image content).
+- Document the queue/polling design and retry/backoff policy in `engineering/TECH_SPEC.md`; provider output retention (does the provider keep copies?) goes in `privacy-terms.md` and feeds prompt 08.

package/surfaces/starters/photo-ai-media/prompts/05-editing-and-presets.md

@@ -0,0 +1,40 @@
+# 05 — Editing & Presets (optional)
+
+Presets are how a one-trick transform becomes a product: named styles the user can browse, apply, and re-run with tweaks. Watermark-free export is the category's classic premium lever.
+
+```
+Add a preset/style system and lightweight editing on top of the generation
+pipeline.
+
+Requirements:
+- A presets table: name, description, preview thumbnail, the parameter bundle
+  it applies (JSONB), sort order, and a premium flag; presets are content the
+  team curates, not user data — readable by all, writable by admin only
+- A preset picker in the generation flow: visual grid with preview thumbnails,
+  the premium ones labeled (not hidden)
+- Re-run with tweaks: from any generated asset, "try another style" or adjust
+  exposed parameters (strength, framing, palette) and submit a new generation
+  that records the parent asset and the preset used — never mutate the
+  original; every variation is a new generations row through the same
+  idempotent, credit-checked pipeline from prompt 04
+- A simple compare view between variations of the same source
+- Watermark behavior: free-tier exports carry a small branded watermark;
+  premium removes it — applied server-side at export time, never client-side
+  only
+
+Keep preset definitions data-driven so adding a style is a row, not a deploy.
+
+Strings: every user-facing label, headline, button, empty state, and error
+comes from product/copy/COPY_DECK.md (author missing rows first — voice from product/copy/COPY_BRIEF.md,
+craft from knowledge/words/conversion-copy.md), typed via the externalized resource
+named in engineering/TECH_SPEC.md. Example copy in this prompt is voice guidance, not
+shipping strings.
+```
+
+## Skill-integration notes
+
+- Re-runs go through the same pipeline as first runs: credit-checked, rate-limited, idempotent. A "tweak" that bypasses metering is a cost leak and an abuse vector (`trust/SECURITY.md`).
+- "Try another style" multiplies the Variable Reward exposure from prompt 04 — the same HIGH-risk `ethics-guardrail.md` contract applies. Watch the `counter_metric` (regeneration spirals, credit-balance crashes in one session) and keep the escape hatch honest: never time a "one more try" nudge to the moment the balance hits zero.
+- Watermark-free as a premium lever is a `revenue-monetization.md` decision (it shapes the free tier's shareability — the watermark is also organic attribution for prompt 07). Surface the tradeoff; the founder picks.
+- Premium presets shown-but-labeled is paywall surface design (`onboarding-conversion.md`): the upgrade moment should land when the user wants a specific style, a real value moment.
+- Add `preset_selected`, `generation_rerun`, `variation_compared`, `watermark_removed_export` to `analytics/ANALYTICS.md`.

package/surfaces/starters/photo-ai-media/prompts/06-credits-and-monetization.md

@@ -0,0 +1,47 @@
+# 06 — Credits & Monetization (optional)
+
+Every generation costs real provider money, so **metering must precede monetization** — the credit ledger from prompt 01 and the cost tracking from prompt 04 are prerequisites, not afterthoughts. The model choice (credit packs vs subscription vs both) and all prices are founder-gated.
+
+```
+Add monetization on top of the credit ledger.
+
+Model (confirm the exact mix and prices with the founder before building):
+- Credit packs: one-time purchases of N credits (consumable) — fits one-shot
+  occasions like a headshot pack
+- Subscription: a monthly/annual plan granting a recurring credit allowance
+  and premium features (watermark-free export, premium presets, higher
+  resolution, priority queue)
+- A small free grant at signup so the wow moment happens before the paywall
+
+Implement:
+1. For the web surface: Stripe Checkout for packs and subscriptions, the
+   Customer Portal for managing/cancelling, and a webhook handler (purchase
+   completed, subscription created/updated/cancelled, payment failed) that
+   writes credit grants and entitlement changes — idempotently — to the ledger
+2. For a native surface: RevenueCat entitlements over StoreKit/Play Billing
+   for both consumable packs and subscriptions; its webhook writes the same
+   ledger rows
+3. Server-side credit check before every generation (already in prompt 04);
+   the out-of-credits state shows the balance, what a pack/plan grants, and a
+   clear price — no silent failure, no dark-pattern countdown
+4. A balance + purchase-history surface in account settings
+
+All grants/spends/refunds flow through the append-only ledger; entitlement
+reads come from a cached status, not a live billing-provider call per request.
+
+Strings: every user-facing label, headline, button, empty state, and error
+comes from product/copy/COPY_DECK.md (author missing rows first — voice from product/copy/COPY_BRIEF.md,
+craft from knowledge/words/conversion-copy.md), typed via the externalized resource
+named in engineering/TECH_SPEC.md. Example copy in this prompt is voice guidance, not
+shipping strings.
+```
+
+## Skill-integration notes
+
+- **Reconcile with `revenue-monetization.md` §3 before picking the model — as defaults to TEST, not dogma:** hard paywalls convert ~5x freemium (median ~10.7% vs ~2.1% D35 download-to-paid), yearly-dominant apps show the highest realized LTV, price reads as a quality signal (high-priced apps show ~5.4x monthly LTV *with higher* conversion), and paid intro offers are worth testing over reflexive free trials. The anti-pattern is reaching for the cozy default (generous freemium, monthly-only, $2.99) by reflex and never surfacing the trade-off. Per the report's AI pattern: AI apps earn more per payer but churn faster — protect margin (annual-led, less-generous freemium) and judge on renewals, not install-day conversion.
+- **Per-generation COGS is the difference from ordinary subscription apps:** a free user is not "free" — every generation has a provider invoice behind it. Price packs and allowances from the measured cost per generation (prompt 04), and never grant unmetered "unlimited" generations without a fair-use cap.
+- Pricing, plan mix, pack sizes, and the free grant are **founder-gated** (`revenue-monetization.md` §2): surface the benchmark trade-offs, then the founder decides. Record in `revenue/REVENUE_OPS.md`.
+- Billing path follows the surface: Stripe for web; native digital purchases go through IAP via RevenueCat — do not ship the web Stripe paywall inside a native binary without resolving store policy first.
+- Webhook signing secrets route through `SECRETS.md`; webhooks are an abuse surface (`trust/SECURITY.md`) and ledger writes must be idempotent. Handle involuntary billing-failure churn (grace period, dunning) per `billing-health-and-reactivation.md` §2.
+- The out-of-credits upgrade moment is paywall timing (`onboarding-conversion.md`) and sits next to the Variable Reward loop — an honest price at a real value moment, never a spend-compulsion nudge (`ethics-guardrail.md`).
+- Add `checkout_started`, `credits_purchased`, `subscription_activated`, `out_of_credits_shown`, `payment_failed` to `analytics/ANALYTICS.md`; pair with per-generation cost for margin dashboards.