Phase 1.2 — Onboarding + Trial Implementation

Goal

Ship Phase 1.2.1-1.2.5 implementation согласно plans/onboarding-trial-mode.md (ratified CONV-35): signup + Trial + Quick Build/Object Builder + tier transitions + Plan & Billing UI. Target: first paying customer Stage 1 launch.

Tasks

Phase 1.2.1 — Signup + abuse mitigation + Stripe Customer creation:

• [ ] Path A signup form с billing address fields (country mandatory; line1/city/postal optional per Finance H5 fix)
• [ ] Email verification flow с invite token primitive (Phase 1.3 §1.4.D reuse) + §1.7.J header set hardening (no-referrer / no-store / single-use rotation)
• [ ] Cloudflare Turnstile integration на signup form (managed mode per Security M4)
• [ ] Email domain age check via WHOIS RDAP API (block <7d domains)
• [ ] IP rate limit (3 signups/IP/24h, IPv6 /64 normalisation) + ASN-level rate limit (30/ASN/24h per Security M4)
• [ ] Deferred Stripe Customer creation at trial-init (NOT signup) — Path A only; Path B Free Guest = no Stripe record
• [ ] Email collision на signup recovery during archive window (HTTP 409 + operator flag per Step 13.6)

Phase 1.2.2 — URL architecture middleware:

• [ ] Subdomain resolution middleware ({slug}.offplan.online → organisation_id)
• [ ] Host header canonicalisation (allowlist regex + X-Forwarded-Host distrust per Security M1)
• [ ] requireMembership(user, resolved_org_id) pattern на every admin route (Security M6)
• [ ] Reserved subdomain blocklist (58 from Phase 1.3 §2.7 + brand-relevant extensions per R1)
• [ ] Project path resolution (/{project-slug}/...)
• [ ] Custom domain CNAME resolution + DNS verification flow (Security H2 — TXT challenge + continuous re-verification + 503 on expired)
• [ ] Slug change flows (Org 12mo cooldown; Project free с buyer token invalidation per Phase 1.3 §1.7.J)
• [ ] Custom domain transfer operator action с §1.5.F fraud-signal scoring (B12)
• [ ] Security baseline headers (CSP / HSTS / __Host- cookies / X-Frame-Options / X-Content-Type-Options) per Step 10.1

Phase 1.2.3 — Trial subscription + 14-day timeline + emails:

• [ ] Stripe Subscription create с price_tier_2_monthly (Pro tier per B4) + trial_period_days: 14 + payment_behavior: default_incomplete
• [ ] Trial countdown badge в admin header («TRIAL — N days left»); hidden на public sales-app
• [ ] 14 webhook event handlers (Step 3 expanded table — incl charge.dispute.created/closed, invoice.payment_failed, charge.refunded, credit_note.created, subscription.paused/resumed, invoice.finalized)
• [ ] Webhook signature verification с raw-body capture + 5min clock skew + 400 on failure (Security M2)
• [ ] Daily reconciliation job (events + revenue totals per Finance audit gap #2)
• [ ] Trial cascade emails (T-7 / T-3 / T-1 / T+0 / T+7 / T+23 / T+29) — cron + webhook triggers per Step 8
• [ ] Trial → Free Guest auto-downgrade на subscription deletion webhook
• [ ] Public sales-app freeze cron at T+30 (410 Gone branded page)
• [ ] Trial-to-Paid conversion: card attach via Stripe Elements inline (Setup Intent); auto-finalize pending invoice at original cycle date

Phase 1.2.4 — Object Builder + Live Preview + Trial sidebar + Free Guest sidebar:

• [ ] Object Builder split-screen UI (canonical Atelier mockup docs/mockups/admin-quick-build-atelier-standalone.html)
• [ ] REQUIRED UPLOADS panel с 3-item progress (Exterior / Floor Plans / Gallery) — built-in checklist per Atelier
• [ ] Live Preview right panel: branded skeleton placeholder → mid-upload real content (Pick #11)
• [ ] AI Floor Plan tags Stage 1 fallback — manual page picker (radio: Floor plan / Render / Brochure) + bulk action (Pick #10)
• [ ] Trial sidebar — all Pro features ACTIVE (per B4 Full Pro 14d); SSO + 2nd-project locked
• [ ] Free Guest sidebar — minimal (Dashboard + Guest projects + «Frozen project preview» row per Studios M4 + Settings → Profile + Plan & Billing + Referrals disabled) per Pick #13 + B2 matrix
• [ ] Team invite UI Trial — up to 3 seats (Owner + 2 invitees) per B1
• [ ] Free Guest × host-project capability matrix enforcement per B2 Model B (Edit content, no publish)
• [ ] 3 success-moment upsell modals (first publish / first buyer link / first 50 views) per B6
• [ ] Lock modal templates: 2 Trial-period locks (SSO + 2nd project cap) + 8-12 post-Trial templates (TBD designer)

Phase 1.2.5 — Plan & Billing UI + tier transitions + Customer Portal:

• [ ] Plan & Billing page (Settings → Plan & Billing) layout per Step 11
• [ ] Current Plan card с renewal date + Manage payment button
• [ ] Trial countdown banner / Free Guest banner per Step 11.3-11.4
• [ ] Compare plans table (3 cols Starter/Pro/Enterprise; Free Guest implicit) per Step 11.5
• [ ] Enterprise CTA = mailto [email protected] Stage 1 (B7)
• [ ] Invoice reference field optional settings form (B3) с Stripe Subscription.invoice_settings.custom_fields
• [ ] Tier upgrade flow: subscriptions.update({items, proration_behavior: 'create_prorations'}) + Stripe Elements inline для SCA (Step 2.1 post-Category A fix — NOT Checkout Session)
• [ ] Tier downgrade flow: subscription_schedules.create({from_subscription}) + phases (Step 2.2 post-Category A fix)
• [ ] Tier preview UI: POST /v1/invoices/create_preview (NOT deprecated upcoming_invoice — ADR 0013 v1.1)
• [ ] Free Guest → first paid: Checkout Session redirect (B8) с billing_address_collection: required + tax_id_collection: enabled
• [ ] Stripe Customer Portal session creation + portal configuration per Step 11.6 (2026-01-28.preview API version)
• [ ] Reactivation modal с transparent pricing (B5 — current advertised + comparison line if changed since Trial)
• [ ] Multi-currency pricing config (currency_options USD/EUR/AED) per Step 4
• [ ] Tax ID capture + VIES async validation + corrective invoice flow (Finance M4)
• [ ] Free Guest archive cascade cron (12mo inactivity → email cascade → archive flip → 90d retention → hard delete) per Step 9 + Security H1 deletion_journal 7-stage state machine
• [ ] Invoice cold-storage export job (S3 Object Lock; trigger on invoice.finalized + at archive) per Step 1.5 + Finance audit gap #5

Cross-cutting:

• [ ] Step 13 Operator playbook integration с Phase 1.4.7 sub-plan (9 operator actions + chargeback dispute resolution playbook)
• [ ] Analytics events Phase 1.7.11 (5 base + 4 reactivation KPIs + abuse flag + time-to-first-publish + acquisition channel tracking)
• [ ] pricing-config.ts populated post-Roman input (currently TBD)
• [ ] Email copy 7 templates (T-7/T-3/T-1/T+0/T+7/T+23/T+29) post-Ilya/copywriter
• [ ] Upgrade modal copy + screenshots (8-12 post-Trial + 2 Trial-period + 3 success-moment) post-Ilya/designer
• [x] ADR 0011 email sender architecture ratification — RATIFIED CONV-39 (Resend + 2 own domains audience split + verify-both-now). Phase 1.2 implementation task card T1-T7 в ADR body.
• [x] ADR 0014 MCP wrapper auth ratification — RATIFIED CONV-39 (Iter 1 read-only full + Iter 2 interface stub; OAuth 2.1 PKCE + per-call auth + RBAC + defense-in-depth sanitisation + tiered rate-limit). Phase 1.5.6 unblocked; Stage 1.5 fallback OK — Phase 1.2.4 AI Floor Plan tags continue с manual fallback per Pick #10.
• [ ] Legal entity lock (Abu Dhabi likely candidate per CONV-35) → trigger UAE-specific tax research + e-invoicing middleware decision

What's Next

Post-CONV-39 — ADR 0011 + ADR 0014 unblocked. Remaining blockers: (a) Roman pricing numbers input для pricing-config.ts; (b) legal entity lock decision (Abu Dhabi structure). ADR 0011 task card T1 (Resend account + DNS) can start parallel — это Roman/Sergei DNS work, не блокирован Roma engineering.

Once Roman pricing + legal entity resolve, start с Phase 1.2.2 URL architecture middleware (smallest discrete chunk, unblocks everything else routing-wise). Roma scaffolds initial files based on canonical Atelier mockup + plan body Implementation Steps.

Key Context

• Plan: plans/onboarding-trial-mode.md (1746+ lines body + Part 3 amendments; ratified CONV-35)
• Research: docs/research/stripe-billing-onboarding-stage1-2026-05-11.md (Step 2)
• Business review findings: docs/research/business-review-sub-plan-2-2026-05-11.md (Step 4.4)
• Canonical mockup: docs/mockups/admin-quick-build-atelier-standalone.html (per CONV-21 + ADR 0015)
• ADR dependencies: 0008 (tier model — Trial = T2 amendment CONV-35) · 0011 (email sender — blocker) · 0013 v1.1 (proration) · 0014 (MCP wrapper — Phase 1.5.6 gate) · 0017 (Stripe Stage 1 — ratified CONV-35) · 0009 (tenancy) · 0004 v2 (audit retention)
• Phase 1.3 cross-refs: §1.3.C (Guest section — needs B2 matrix amendment) · §1.4.D (invite token) · §1.5.F (fraud signals → custom domain transfer clone) · §1.7.J (buyer URL hardening → token verify reuse) · §1.8.A/B/E (tier transitions) · §2.4.A (audit events)
• Legal entity status: Abu Dhabi likely candidate per CONV-35 user signal; sub-plan body jurisdiction-agnostic. UAE-specific tax research follow-up triggered on lock.

Session Log

• SK-260511-02 (2026-05-11): Ilya designer brief committed at docs/briefs/ilya-email-templates.md (444 lines) — covers 7 React Email trial cascade templates (T-7 / T-3 / T-1 / T+0 / T+7 / T+23 / T+29) per ADR 0011 T5 + 4 standard transactional (signup verify / password reset / billing receipt / tier transition). Each cascade email has subject + preheader + trigger + audience state + CTA + body sections + variables. Brandbook v2 token pulls, .tsx component contract, 3-checkpoint review loop, ~14-day timeline, 9 open questions for Ilya before C1. Brief is ready to ship to Ilya in next session.
• CONV-35 (2026-05-11): Workstream created. Phase 1.2 sub-plan ratified (Steps 1-5 closed): 14 picks + 2 recommendations + 76 review findings (16 Category A applied + 13 Category B ratified + 47 Category C deferred) + 7-stage deletion_journal cascade + Operator playbook Step 13 + Trial = T2 Pro full 14d (B4) + 3 seats Trial (B1) + Free Guest × host-project Model B (B2) + invoice reference field (B3) + reactivation current price (B5) + 3 success-moment modals (B6) + Enterprise mailto Stage 1 (B7) + Checkout redirect для Free Guest → first paid (B8). Awaiting blockers: ADR 0011 + ADR 0014 + Roman pricing + legal entity lock.
• SK-260511-01 (2026-05-11, local CONV-39 legacy ref): ADR 0011 email sender architecture ratified (compact 30-min /plan format). Decisions: Resend = Stage 1 ESP; 2 own domains (offplan.online customer-facing + offplanonline.com buyer-facing reserved/dormant); audience split; D1 verify-both-now phasing. Decision #2 (Tier 2+ per-Org white-label client-domain) DEFERRED. Task card T1-T7 в ADR body. ADR 0014 MCP wrapper auth ratified (compact 30-min /plan format). Decisions: Iter 1 read-only full + Iter 2 interface stub (Option C); OAuth 2.1 PKCE only Stage 1 (no static tokens production); RBAC (Owner controls grants + Admin delegate; Internal SA opt-in; External SA opt-in с audit marker; Free Guest + Buyer hard block); defense-in-depth sanitisation (structured envelopes + content tagging mandatory + system prompt hardening complementary; output moderation deferred Stage 2); tiered rate-limit proposed (Owner/Admin 1000/h · SM/CE 500/h · Internal SA 100/h · External SA 50/h — TBD by ops). Task card T1-T8 в ADR body. blocked_by shrunk: 4 blockers → 2 (legal entity + Phase 1.3 implementation). NOTE: Session ran в parallel с CONV-36 (admin-panel-redesign) + CONV-37 (admin-panel-foundation Playwright walks); branch diverged 13 vs 9 commits at session end; prior CONV-36 attempt в этой sessии reverted due к 2 другие active claude processes running same repo; user closed parallel processes mid-session, then ratifications persisted.