spec(§3–4): product personas + product use cases PUC-1..11, grounded in corpus 14.01.* / 01.01.0008

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

specs/SD-0001-mvp-sign-up-and-single-storefront.md

@@ -297,11 +297,156 @@ code *is* email verification; account deletion is deferred and logged in §9).
 
 ## 3. Product Personas
 
-<!-- §3 pending -->
+| Product persona | In ecomm | Maps to business role(s) |
+| --- | --- | --- |
+| **Visitor** | An unauthenticated person on the entry surfaces: landing, sign-up/log-in. | Merchant (before they are known) |
+| **Merchant** | An authenticated account holder; creates and owns the storefront; lands on its admin. The MVP's only authenticated user type. | Merchant |
+| **Operator** | Brings up and deploys environments; interacts through flotilla and the bring-up runbook, not the web UI. | Platform operator; ecomm team |
 
 ## 4. Product Use Cases
 
-<!-- §4 pending -->
+Corpus grounding: scenario IDs cite the harvested Shopify first-run experience
+([flows/first-run-experience.md](https://git.wiggleverse.org/wiggleverse/wiggleverse-ecomm-prototype-content/src/branch/main/research/shopify/flows/first-run-experience.md),
+14.01.\*) and the zero-state dashboard (01.01.0008). Divergences are marked.
+
+**PUC-1 — Landing offers the two doors** *(realizes BUC-1, BUC-2; corpus 14.01.0001)*
+
+```gherkin
+Scenario: PUC-1 — The landing page offers signing up or logging in
+  Given a Visitor on the ecomm landing page
+  Then they see what ecomm is, a primary action to get started, and a link to log in
+  And no trial, pricing, or fee is presented (corpus 14.01.0011)
+```
+
+**PUC-2 — Sign up with email + one-time code** *(realizes BUC-1; corpus 14.01.0002–0004)*
+
+```gherkin
+Scenario: PUC-2 — A Visitor signs up
+  Given a Visitor who chose to get started
+  When they enter their email address and request a code
+  Then a one-time code is sent to that address
+  And the screen moves to code entry, telling them where the code went
+  When they enter the code within its validity window
+  Then they are signed in as a new Merchant
+  And they are taken directly into creating their storefront (PUC-4)
+```
+
+```gherkin
+Scenario: PUC-2a — Wrong code
+  Given a Visitor on the code-entry screen
+  When they enter an incorrect code
+  Then the screen says the code didn't match and lets them retry or request a new one
+  And after repeated failures the code is invalidated and a fresh request is required
+```
+
+```gherkin
+Scenario: PUC-2b — Expired code
+  When they enter a code past its validity window
+  Then the screen says the code expired and offers to send a fresh one
+```
+
+```gherkin
+Scenario: PUC-2c — Resend is rate-limited
+  When they ask for another code immediately after one was sent
+  Then the screen asks them to wait briefly before resending
+```
+
+**PUC-3 — Log in as a returning Merchant** *(realizes BUC-2; corpus 14.01.0009, 14.01.0010)*
+
+```gherkin
+Scenario: PUC-3 — A returning Merchant logs in
+  Given a Visitor whose email already belongs to a Merchant account
+  When they complete the same email + code flow (from either door)
+  Then they are signed in to that same account — the email is the canonical key
+  And no duplicate account is created (corpus 14.01.0010)
+```
+
+*(Sign-up and log-in are deliberately the same mechanism; the two doors differ
+only in framing. A "sign up" with a known email is a log-in; a "log in" with an
+unknown email creates the account. Honest copy on the code-entry screen states
+which happened.)*
+
+**PUC-4 — Create the storefront after sign-up** *(realizes BUC-3; corpus 14.01.0013, 14.01.0015, 14.01.0016, 14.01.0025, 14.01.0026)*
+
+```gherkin
+Scenario: PUC-4 — A new Merchant creates their storefront
+  Given a Merchant signed in with no storefront
+  Then they are on the create-storefront screen — there is nothing else to do yet
+  When they optionally enter a storefront name and confirm
+  Then the storefront is created — named as entered, or with a generated default name
+  And no payment method, plan, or commitment was requested (14.01.0015/0016)
+  And they land on the storefront's admin page (PUC-6)
+```
+
+**PUC-5 — Returning without a storefront → prompted to create** *(realizes BUC-3, BUC-4)*
+
+```gherkin
+Scenario: PUC-5 — A Merchant who never finished creating one
+  Given a returning Merchant who has no storefront
+  When they log in
+  Then they arrive at the create-storefront screen (PUC-4), not an empty admin or an error
+```
+
+**PUC-6 — Returning with a storefront → straight to its admin** *(realizes BUC-4; corpus 14.01.0027)*
+
+```gherkin
+Scenario: PUC-6 — A Merchant returns to their storefront
+  Given a returning Merchant who has a storefront
+  When they log in
+  Then they land directly on that storefront's admin page
+  And nothing further is mandatory (corpus 14.01.0027)
+```
+
+**PUC-7 — One storefront: no second-storefront affordance** *(realizes BUC-3a; **diverges** from corpus 14.01.0012/0014 — multi-store per account is deliberately not offered; see §9 D-2)*
+
+```gherkin
+Scenario: PUC-7 — No "create another storefront" exists
+  Given a Merchant with a storefront
+  Then no surface offers creating another one
+  And directly invoking storefront creation anyway is refused with an honest
+    explanation that ecomm is one storefront per account today
+```
+
+**PUC-8 — The admin shell is honestly empty** *(realizes BUC-4; zero-state per corpus 01.01.0008)*
+
+```gherkin
+Scenario: PUC-8 — Empty admin
+  Given a Merchant on their storefront's admin page
+  Then the page carries the storefront's name and the signed-in account's email
+  And states plainly that there is nothing to manage yet
+  And shows no fabricated metrics, fake modules, or teaser upsells
+```
+
+**PUC-9 — Sign out** *(product-only)*
+
+```gherkin
+Scenario: PUC-9 — A Merchant signs out
+  Given a signed-in Merchant anywhere in the admin
+  When they sign out
+  Then their session ends and they are back on the landing page as a Visitor
+```
+
+**PUC-10 — A developer bootstraps localhost** *(realizes BUC-5; Operator-facing — the surface is a terminal, not a screen)*
+
+```gherkin
+Scenario: PUC-10 — Clean checkout to first storefront, locally
+  Given a clean checkout of wiggleverse-ecomm and the documented prerequisites
+  When the developer runs the documented dev bring-up command
+  Then the app starts against an empty local store, applying schema migrations itself
+  And the developer completes sign-up → create storefront → admin in a browser
+  And the one-time code reaches them through the local dev channel (no real mail needed)
+```
+
+**PUC-11 — The Operator bootstraps a deployed environment (PPE, then Prod)** *(realizes BUC-5, BUC-5a)*
+
+```gherkin
+Scenario: PUC-11 — Fresh deployed environment to first merchant
+  Given an environment provisioned and deployed through flotilla, with empty persistence
+  When the app starts, applying schema migrations itself
+  Then the first real merchant can complete sign-up → storefront → admin
+    through the public flows, with the code arriving by real email
+  And the rehearsal on PPE and the day-one Prod state are the same gesture (BUC-5a)
+```
 
 ## 5. UX Layout