Plan · BUILD-PLAN.md

tellatribe — Build Plan

Version: 1.0 · Date: October 3, 2026 · Status: Ready for engineering review

This is the document PRD-Activation-Platform.md points at and never had. It reconciles the two PRDs, fixes the decisions already taken, and sequences the build. It is deliberately short; the detail lives in three companion documents under build-plan/:

1. Which document governs

• PRD.md v0.1 (Aug 14, updated Oct 3) and PRODUCT.md are the requirements. Where they disagree with anything else, they win.
• PRD-Activation-Platform.md v1.1 is kept, frozen, as the v2 vision of the sellable platform. It is not a requirements document for this build. Track 03 §A.1 maps all 43 of its requirements to a verdict; its status line should be changed to point at that table.
• .impeccable/surfaces/design-portal.md carries the chosen visual direction for the affiliate portal (the Title Wall), and design/prototype/portal.html is its first rendering. DESIGN.md is written from the built portal at the end of Phase 3, not before.

2. Decisions already made

These are settled. Re-opening one costs a conversation, not a commit.

3. Phases and gates

Sizes are per track: S ≤ 2 days, M ≤ 1 week, L 2–3 weeks. Gates are bold; nothing after a gate starts until it passes. Phase numbers follow PRD §13.

Phase 1 — Ledger (no UI)

Items 1–11 of 01 §7. Tenancy, programs, affiliates, partitioned tracking tables, the ledger, the pure engine, the ledger service.

Gate 1a: schema tests — a third level is refused; a commission without a conversion is refused; a money-column update is refused; a sponsor cycle is refused. Gate 1b: engine test matrix — incl. property tests and a golden replay file. Gate 1c: ledger integration suite — first sale L1+L2; recurring to month 12 then 13; refund pre- and post-payout; dispute; suspended sponsor; self-referral and duplicate flagged; rate change mid-stream; concurrent duplicate conversion.

Rough size: about half of the 8–10 engineer-weeks in track 01.

Phase 2 — Tracking

Items 12–17 of 01 §7. The click and conversion API, the SDK, the platform Stripe webhook route.

Gate 2: end-to-end tracking — a local HealthyApp (or stub) with the SDK route → click → Stripe test-mode Checkout with metadata → invoice.paid → ledger rows; refund → reversal. Verified by reading the tables, not a UI.

Phase 6 (Mode 1) — Collateral, in parallel with Phase 2

Items 6.1–6.9 of 02 §6. Asset schema, token resolver, admin upload and renditions, script editor with read time, vault list and detail.

Gate 6: an affiliate on a phone copies a disclosed, link-substituted caption and saves a correctly cropped JPEG for Instagram in under 30 seconds. Requires the first HealthyApp collateral set (D.9 below) — the vault may not launch empty.

Phase 3 — Affiliate portal

The 20 screens in 03 §B.2, built in the Title Wall world from the direction contract. Order: Wall (with the billboard and product rows), asset sheet, Links, Earnings ledger with commission detail, Studio (taken / scheduled / takes / accounts / rules), Payouts, Team, Payout method, Settings, Notifications, Terms interstitial, Join and Sign-in. Mobile at 390 first; desktop is a wider view of the same thing.

Gate 3: the first five minutes (03 §B.5) run on a real phone by someone who has never seen the product, ending with a caption on the clipboard and an image in Photos. Then the finish review, the verdict, and DESIGN.md written from the built world.

Phase 4 — Admin

The 10 screens in 03 §B.3: Queue first, then Collateral authoring (the most-used screen), Payout runs, Affiliates, Programs with the integration panel, Reports with the four guardrail metrics, Audit, Settings. Desktop-first. MFA on from the first login.

Gate 4: a normal week needs zero logins — the queue digest email carries everything, and the empty queue reads "All services running normally."

Phase 5 — Payouts

Items 18–22 of 01 §7. Express onboarding, the two-phase payout run (assemble marks rows paid; release issues transfers), failure handling, statements.

Gate 5: payout suite — below-minimum carried; negative carried; not-onboarded skipped and notified; invalid destination returns rows to approved; insufficient funds halts the run; re-release is idempotent.

Phase 6b (Mode 2) — Publishing

Items 6b.0–6b.7 of 02 §6. 6b.0 starts on day one (Meta Business Verification, app registrations, privacy and terms URLs live) because it is calendar time, not engineering time.

Phase 7 — HealthyApp live

First real affiliates, first payout run. Instrument the activation funnel (03 §A.2 #8) so PRD §14's success criteria are measurable from the first week.

Phase 6c (Mode 3) — Teleprompter, v1.5

Items 6c.1–6c.7 of 02 §6, two to four weeks after v1. The one surface that needs a physical device QA matrix. 6c.7's in-app-browser arrival rate is the data that decides whether a native wrapper is ever worth it.

Phase 8 — Creator Campaigns (shipped Oct 19)

Briefs, applications, deals, deliverables, verification → bounty, disputes, rights, brand funding (PRD-Creator-Campaigns.md Part B; contract build-plan/04-creator-campaigns.md). Built as four parallel streams against one schema (0017–0019): engine packages/campaigns, admin Campaigns section, portal Open calls / Studio → Deals, API funding webhook + 15-minute cron. Gate: every engine state machine proven on PGlite (37 tests), the admin and portal screens on live rows, the funding webhook end-to-end with a signed test event. Phase 6 of the PRD (platform marketplaces, paid amplification, external discovery, storefronts) stays later.

Phase 1 execution plan — agents

Phase 1 is a schema, a pure engine, and a service over both. The spec in track 01 is column-level, so the work splits by file with the spec as the contract; the shared risk is naming drift between parallel migrations, which the test harness catches at merge because it applies every migration in order. Concurrency is capped where merge conflicts would cost more than the parallelism buys.

Why not more: a fifth wave-1 agent would have to split a single migration or a single test matrix, and both are cheaper to write whole than to reconcile. The ledger service (L) is one transactional module; two agents inside it conflict on every function.

Environment note. No Docker on this machine, so supabase db reset cannot run locally. Schema gates run on PGlite (Postgres in WASM) with citext and btree_gist; the migration files are unchanged and ship to a real Supabase project with supabase db push once one exists (creating it is a billable step and is Jonathan's call).

Branching. Agents work in worktrees off main and return branches; the lead integrates them on phase-1. Nothing merges to main without asking.

Phase 1 status log

| Oct 4 | phase-1 fast-forwarded into main with Jonathan's OK. phase-2 cut. Wave 3 started, four agents in parallel: A1 apps/api (key auth, /v1/clicks, /v1/conversions, cron routes, Postgres Sql adapter) · A2 @affiliate-coach/sdk (/r/[code] handler, cookies, getClickId, stripeCheckoutFields, convert) · A3 @affiliate-coach/stripe-webhooks (platform-event handler with the four topology guards, event ledger, dead letters) · A4 Phase 6 Mode 1: 0009_collateral + the token resolver in core. |

| Oct 4 | Wave 3 merged. Gate 2 green: SDK redirect → /v1/clicks → first-party cookies → Stripe Checkout metadata → signed invoice.paid through the mounted platform webhook → L1 + L2 rows → partial charge.refunded → proportional reversals, on one tree (apps/api/test/gate2.e2e.test.ts). Phase 2 complete: 519 tests (124 core incl. collateral resolver, 149 schema 0001–0009, 96 ledger, 66 SDK, 43 webhooks, 41 API). 0009_collateral live on Supabase. phase-2 → main; phase-3 cut. Integration decisions: RecordConversionInput.mode added (test keys record test rows); API bodies follow the SDK contract (camelCase, outcome); SDK honours the program's cookieWindowDays; HealthyApp mounts the redirect at /go/[code] because app/r/[token] is taken. | | Oct 4 | Wave 4a started on phase-3: S portal shell (apps/portal: Supabase magic-link auth, Tailwind theme from .impeccable/design.json, tab shell) · D admin app (apps/admin: Queue, Programs with integration panel, Affiliates) · Y payouts (packages/payouts: Express onboarding, two-phase run, statements; API mounts) · B publishing (0010_publishing, Ayrshare adapter, publish worker, composer contract). |

| Oct 4 | apps/api deployed to production: https://api.tellatribe.com (prebuilt from the workspace root; recipe in AGENTS.md). DATABASE_URL verified against the live pooler (the ledger's Postgres adapter test ran green against Supabase); CRON_SECRET, CLICK_SALT set; crons registered. Smoke: unauthenticated click 401, cron 401, unconfigured product slug 404. |

| Oct 4 | HealthyApp seeded in the live database by scripts/seed-product.mts: product (redirect_origin https://healthyapp.coach), evergreen program with terms v1, rates 25% recurring 12 months (L1) / 5% lifetime (L2) — the PRD's suggested plan, applied as a decision so Phase 7 can start; change through set_plan_level(). A live track+convert API key was minted once and lives only in the keychain. Live smoke with that key returns unknown_code 404 — the production stack answers end to end. Agent H started: the documentation hub (apps/docs, code 3003). |

| Oct 4 | Wave 4a Y merged: packages/payouts — Express onboarding ("ask Stripe, don't trust the return"), two-phase payout run (assemble marks paid → check funding → release with payout:{id} idempotency; 4xx returns rows via fail_payout(); insufficient funds halts and fails the rest with run_halted), reconciler, statements, tax-year summary, Connect webhook with its own event-ledger rows. Gate 5 green (35 tests). Mounted and redeployed: /api/stripe/connect, cron payout-run on the 1st at 14:00 UTC. Awaiting from Jonathan: the dedicated tellatribe Stripe account (decision 9) → STRIPE_SECRET_KEY, STRIPE_CONNECT_WEBHOOK_SECRET, and workspaces.payout_stripe_account_id; until then /api/stripe/connect answers 500 (no key) and startOnboarding refuses. 588 tests. |

| Oct 4 | Wave 4a landed on phase-3: S portal shell (Supabase magic-link auth, join with live code check, terms interstitial, Settings sheet, theme from design.json; 0010_affiliate_preferences) · B publishing (0011_publishing: social_connections, publish_jobs, enqueue_publish_job with the X open-balance gate, Ayrshare client + six adapters, preview, worker with backoff; cron publish-worker every 5 min) · D admin (MFA-gated; Queue with exception drawer and reasoned actions; Programs with set_plan_level(), terms, integration panel with reveal-once keys and a test conversion; Affiliates with reparent/suspend/write-off/view-as; 0012_admin_flags) · H documentation hub, live at https://docs.tellatribe.com (code 3003). Migrations renumbered at merge (publishing 0010→0011, admin flags 0011→0012) because Supabase keys migrations by version; 0010–0012 applied live. Wave 4b running: P1 Wall + Studio, P2 Links + Earnings (+ 0013_links). Full suite 693 tests when run unloaded; two ledger scenarios timed out once under a load average of 29 and pass in isolation. |

| Oct 4 | Admin and portal deployed: https://admin.tellatribe.com (MFA-gated sign-in) and https://tellatribe.com (shell; Wall/Links/Studio/Earnings screens landing from wave 4b). Env set on both (Supabase URL + anon key as public config, service role, DATABASE_URL, API URL). scripts/deploy-app.sh does the per-app prebuilt deploy. Supabase Auth still needs the magic-link template pointed at /auth/confirm with {{ .TokenHash }} and the two app origins in the redirect allow-list before anyone can sign in. | | Oct 4 | Wave 4b landed and the portal is live with all four tabs: P1 Wall (billboard with first-run / under-minimum / needs-payout / negative states, 4:5 tiles, caption rendering per platform with /go/ links, Join-to-promote) + Studio (asset sheet, composer with server-side disclosure check, "Record it" script sheet as Mode 3 v1, posters, signed-rendition redirect) · P2 Links (list, builder, detail; 0013_links) + Earnings (ledger, next payout, commission sheet, payouts list/detail, CSV statement, payout method with Stripe onboarding action). 0013_links applied live. Full suite + typecheck green on phase-3. Portal redeployed: /wall /links /studio /earnings answer 200 behind sign-in. Wave 5 running: D2 admin second half (Collateral authoring, Payout runs, Reports, Audit, Settings) · R @affiliate-coach/media (renditions matrix, sharp/ffmpeg, Storage bucket, cron) · K HealthyApp integration branch in vera-wellness. Interpretations logged in DECISIONS-FOR-REVIEW.md. | | Oct 4 | Phase 7 prepared — K: HealthyApp integration on branch affiliate-coach-integration in vera-wellness (commit 69b1ec8, not merged, not pushed): SDK vendored to lib/affiliate-coach/, app/go/[code] redirect with .healthyapp.coach cookie domain, /go/ exempted from the auth middleware, stripeCheckoutFormFields spread into startPlatformSubscription only; 13 tests, repo suite 482/482. Go-live checklist in that branch's INTEGRATION.md. Portal: signed-in Join-to-promote flow (/wall/join/[program]) added and deployed; live portal verified signed in as the test affiliate TESTAFF (four tabs render; screenshots in the docs hub). Docs hub status line and Decisions-for-review page live. Agents T (teleprompter, 6c) and C (Connect → publish wiring, 6b) started. | | Oct 4 | Phase 6 Mode 1 media landed — R: packages/media (17-cell rendition matrix, sharp images / ffmpeg video / PDF cover card, Storage port, claim-with-skip-locked worker; 39 tests), cron /api/cron/renditions every 2 min live and answering (401 unauth, 200 → {attempted:0,…}). Getting it live took four deploys: sharp must be a direct dep of apps/api (else bundled), Vercel runs the API on linux-arm64 so pnpm-workspace.yaml now installs that platform's sharp/ffmpeg beside the Mac's, ffmpeg-static → @ffmpeg-installer/ffmpeg, and the media package resolves ffmpeg lazily with a pnpm-store scan because the installer's symlink cannot be traced. Bucket collateral (private, 500 MiB, 16 mimes) created via the Storage API — supabase config push did not create it. API env gained SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY. Shell: Links tab count now from my_links. | | Oct 4 | Checkpoint: main fast-forwarded to phase-3 (809 tests, typecheck clean). Phase 6c teleprompter landed — T and deployed: /studio/record/[asset] (camera gate with in-app-browser detection, 3-2-1 countdown, pace from scriptTiming with 0.8–1.4× speed, 60 s soft / 3 min hard marks, MediaRecorder mp4→webm preference, review with save-to-phone via share sheet, record again, Done → record_completed event + used_at); burn-in opt-in via affiliates.preferences.burn_in_disclosure with canvas compositing when supported; 32 tests. Studio "Takes" copy updated. Remaining agents: D2 (admin half 2) and C (Connect → publish wiring). | | Oct 4 | Admin complete — D2 (Collateral authoring with token palette, sample-affiliate preview, 150 wpm read time, publish gate incl. claims attestation; Payout runs as Assemble → Check funding → Release with history, run detail, statement CSV; Reports with the four guardrails and row drills + CSV export; Audit with before/after diff; Settings with why/consequence lines; 73 tests). The renditions seam now imports the media package's SQL-only half (@affiliate-coach/media/enqueue, new subpath) so the admin never carries sharp/ffmpeg. Phase 6b wired — C: Connect accounts → Ayrshare link session → /studio/connect/return (HMAC state) → syncConnections; Disconnect/Reconnect (0014_social_reconnect, applied live); Composer preflight + preview parity with the worker; X offered only when the gate passes; honest no-key state. Every module in the build plan is now built. Awaiting AYRSHARE_API_KEY for live posting. |

Decisions that surfaced during Phase 1 integration (recorded here so Phase 2 inherits them):

• 0008_flag_vocabulary admits affiliate_suspended in commissions.flag_reason and fraud_flags.kind; the engine's reason is stored verbatim, never mapped to manual.
• A reused idempotency key returns duplicate regardless of body; a body mismatch is written onto the api_requests memo (body_mismatch_seen) for the admin and never acted on. The API layer should surface it as a warning, not a 409.
• A refund larger than the conversion raises refund_exceeds_conversion; the webhook route should dead-letter that event rather than retry it.
• A suspended converting affiliate is paid into flagged (held visibly); closed/pending affiliates are unattributed and never lock a customer.
• approveMatured(workspaceId, now) is scoped per call so one cron sweeps every workspace.
• Rows born approved (reversal, fee, adjustment) carry approved_at at insert; the trigger only stamps it on a transition.
• Phase 1 ran on PGlite; the migrations were also applied to the live project, so the chain is proven on real Postgres. True concurrent-request tests (two connections racing on one customer lock) belong to Phase 2's API tests against Supabase. | Oct 5 | Found while demoing: a conversion in the same second as its click went unattributed (Stripe reports whole seconds) → CLOCK_SKEW_TOLERANCE_MS (60 s) in the window check; focused caption tiles overlapped their title → two-line clamp. Decisions 53–54. | | Oct 9–13 | Paid social: ads/ engine (statics 4:5 / 1:1 / 9:16, two motion MP4s, two carousels) and 14 UGC-style videos (Higgsfield → whisper word timestamps → PNG caption overlays, since the homebrew ffmpeg has no libass); $1,410 demo earnings on the TESTAFF portal screens; docs hub gains the screens gallery and the paid-social page. Executive deck (20 slides, PPTX) with the market-data and Campaigns slides. | | Oct 14 | Creator Campaigns strategy + PRD (PRD-Creator-Campaigns.md, Part A/B, competitive landscape appendix incl. 2025–26 upstarts); Jonathan's six Campaign decisions (55–60). | | Oct 19 | Stripe setup guide for the account administrator (two accounts, hand-off via 1Password). Tax identity shipped (0015_tax_identity): affiliates.tax_status mirrored from account.updated, payout run and admin preview skip tax_identity_missing, Reports → Paid by recipient · tax year (CSV, drill), portal annual statements per calendar year, payout-method tax line. Decisions 61–66. PayPal Payouts evaluated and parked (guide Part 7). | | Oct 19 | Rebrand: affiliate.coach → tellatribe (0016_rebrand_tellatribe, display values only; package scope unchanged). Domains live: tellatribe.com · admin.tellatribe.com · api.tellatribe.com · docs.tellatribe.com. Ads/screens carry the tellatribe wordmark. | | Oct 19 | Creator Campaigns Part B shipped (0017_campaigns, 0018_funding_endpoint, 0019_campaigns_vocabulary; build contract build-plan/04). Four parallel streams merged: packages/campaigns engine (eligibility, quality score, SOW, escrow, review, verification → bounty, disputes, funding ledger; 37 tests), admin Campaigns section + balance strip + Add funds (Stripe Checkout) + four queue kinds + gift value on the 1099 report, portal Open calls / sheets / Studio → Deals / bounty rows, API /api/stripe/funding + /api/cron/campaigns. Decisions 67–106. Totals: schema 221 · engine 37 · admin 87 · portal 166 · API 53 · payouts 40 · ledger 99. Migrations 0015–0019 live; all three apps + docs deployed. Open: campaign screens not yet exercised with live rows; Stripe account (payments + Connect + funding webhook) and Ayrshare key still awaited. |

What runs in parallel

Phase 1 ──gate──► Phase 2 ──gate──► Phase 3 (portal) ──► Phase 7 (live) ──► 6c (v1.5)
                   Phase 6 (Mode 1) ─┘        Phase 4 (admin) ─┘
                   Phase 5 (payouts) ────────────────────────┘
6b.0 platform registrations ─────────────────────────────────► 6b (Mode 2 via aggregator)
Collateral content · counsel ToS review · domains · payout-account confirmation (section 5)

Rough total to v1 (Modes 1 and 2, no teleprompter): four to five months with two engineers, or seven to nine serial. Phase 1 is the half that cannot be compressed and should not be.

4. Non-engineering work that starts now

5. Decisions

All fifteen decided with Jonathan on October 3, 2026. Five depart from the plan's defaults (2, 6, 9, 11, 12); each departure's engineering consequence is in its Note.

Decided

6. What "done" means for v1

From PRD §14, made checkable:

• A new product integrates in under one working day (Gate 2 proves the mechanics; the integration panel's "last click / last webhook received" proves it in production).
• A normal week requires zero admin logins (Gate 4).
• Zero mis-attributed conversions in the first 90 days (ledger-vs-Stripe reconciliation variance on the Reports screen).
• Any commission dispute answered from the ledger in under five minutes (commission detail shows the rule, the amount basis, and the payable-on reason).
• The median new affiliate visits the wall within 48 hours and takes something from it (asset_uses by affiliate, first-week cohort).
• v1.5: a first-time video maker gets from script to posted without leaving the portal.

Rendered from BUILD-PLAN.md. Edit the source, not this page.