fix(signin): key the resend cooldown to the address it was set for (#20)

The email-step Send button disabled on any running cooldown, so a merchant
who mistyped their address was locked out of sending to the corrected one
for the rest of the 60s window — a guard the server never had: request_code
enforces the cooldown per address (SD-0001 INV-3 -> PUC-2c).

Track which address the running cooldown belongs to (cooldownFor) and gate
the email-step button through cooldownAppliesTo(), which blocks only while
the countdown runs AND the input normalizes (strip+lowercase, mirroring
normalize_email / INV-2) to that address. Same address still shows the
honest 'Resend in Ns'; any other address sends immediately. The code-step
resend is unchanged. Verified in the live UI (wrong address -> Wrong
address? -> corrected address sends at once).

package-lock.json: sync recorded version with package.json (0.4.0).

Closes #20

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

README.md

@@ -20,10 +20,14 @@ This app (One Name `ecomm`, see [`app.json`](./app.json)) is composed of:
 
 ## Status
 
-SLICE-2 (identity) of SD-0001 is in place on top of the SLICE-1 skeleton: open,
-passwordless sign-up/log-in by email + one-time code (`accounts` domain, INV-2/INV-3),
-signed-cookie sessions, the `/api/auth/*` endpoints (`request-code`, `verify`, `me`,
-`logout`), the `platform/mailer` port with `LogMailer` (the dev code channel), and the
-Landing + Sign-in screens with the entry-routing rule (storefront hard-wired `null` until
-SLICE-3). See [`docs/BOOTSTRAP.md`](./docs/BOOTSTRAP.md) to run it locally. The storefront
-(SLICE-3) and deployed environments (SLICE-4) are next.
+SLICE-3 (storefront) of SD-0001 is in place on top of SLICE-1/2: the `storefronts`
+domain (create + owner membership, INV-4's one-storefront guard with concurrent-create
+refusal), `POST /api/storefronts`, the Create-storefront and Admin-shell screens, the
+complete entry-routing rule (landing / create-storefront / admin), and the INV-1
+whole-flow bootstrap test — all skinned to the Claude Design export
+(`wiggleverse-ecomm-content/ui/designs/ecomm-login-and-create-storefront-designs/`),
+which also re-skinned the SLICE-2 Landing + Sign-in screens. See
+[`docs/BOOTSTRAP.md`](./docs/BOOTSTRAP.md) to run it locally. SLICE-4's deploy
+contract is in place (versioned `/healthz`, backend-served SPA, `SmtpMailer` with
+honest 502 on delivery failure); PPE provisioning + the bootstrap rehearsal are the
+remaining SLICE-4 steps (BOOTSTRAP.md's PPE section is the runbook).

VERSION

@@ -0,0 +1 @@
+0.4.0

backend/app/domains/accounts/__init__.py

@@ -11,6 +11,7 @@ from .errors import (
     CodeExhausted,
     CodeExpired,
     CodeMismatch,
+    DeliveryFailed,
     InvalidEmail,
     ResendCooldown,
 )
@@ -25,6 +26,7 @@ __all__ = [
     "CodeMismatch",
     "CodeExpired",
     "CodeExhausted",
+    "DeliveryFailed",
     "request_code",
     "verify",
     "get_account",

backend/app/domains/accounts/errors.py

@@ -36,3 +36,7 @@ class CodeExpired(AccountsError):
 
 class CodeExhausted(AccountsError):
     """The code's attempt budget is spent; it is invalidated (INV-3 → §6.4 400 code_exhausted)."""
+
+
+class DeliveryFailed(AccountsError):
+    """The relay refused the code email; nothing was committed (INV-9 → §6.4 502 delivery_failed)."""

backend/app/domains/accounts/service.py

@@ -18,9 +18,16 @@ from datetime import datetime, timedelta, timezone
 import psycopg
 
 from app.platform import config
-from app.platform.mailer import Mailer
+from app.platform.mailer import Mailer, MailerError
 
-from .errors import CodeExhausted, CodeExpired, CodeMismatch, InvalidEmail, ResendCooldown
+from .errors import (
+    CodeExhausted,
+    CodeExpired,
+    CodeMismatch,
+    DeliveryFailed,
+    InvalidEmail,
+    ResendCooldown,
+)
 from .models import Account
 
 # INV-3 constants — the one-time-code policy.
@@ -82,8 +89,10 @@ def request_code(conn: psycopg.Connection, mailer: Mailer, email: str) -> None:
         "INSERT INTO auth_code (email, code_hash, expires_at) VALUES (%s, %s, %s)",
         (email, _hash_code(code), now + CODE_TTL),
     )
-    conn.commit()
 
+    # Send BEFORE commit (ecomm#7): a refused delivery rolls the row back, so no orphan
+    # code blocks the 60s cooldown and the caller can honestly retry at once (INV-9).
+    try:
         mailer.send(
             to=email,
             subject=f"Your ecomm code: {code}",
@@ -93,6 +102,10 @@ def request_code(conn: psycopg.Connection, mailer: Mailer, email: str) -> None:
                 "If you didn't request this, ignore this message."
             ),
         )
+    except MailerError as exc:
+        conn.rollback()
+        raise DeliveryFailed(str(exc)) from exc
+    conn.commit()
 
 
 def verify(conn: psycopg.Connection, email: str, code: str) -> tuple[Account, bool]:

backend/app/domains/storefronts/__init__.py

@@ -0,0 +1,19 @@
+"""storefronts domain — storefront entity, membership, the one-storefront guard.
+
+Owns INV-4 (one storefront per account is a service-layer rule) and INV-5 (tenant rows
+carry storefront_id). Knows nothing about identity (that is the accounts domain). Imported
+via this package surface only (§6.2).
+"""
+from __future__ import annotations
+
+from .errors import AlreadyOwnsStorefront, StorefrontsError
+from .models import Storefront
+from .service import create_storefront, storefront_for
+
+__all__ = [
+    "Storefront",
+    "StorefrontsError",
+    "AlreadyOwnsStorefront",
+    "create_storefront",
+    "storefront_for",
+]

backend/app/domains/storefronts/errors.py

@@ -0,0 +1,10 @@
+"""storefronts domain errors."""
+from __future__ import annotations
+
+
+class StorefrontsError(Exception):
+    """Base for storefronts-domain errors."""
+
+
+class AlreadyOwnsStorefront(StorefrontsError):
+    """INV-4: the account already has its one storefront (PUC-7)."""

backend/app/domains/storefronts/models.py

@@ -0,0 +1,10 @@
+"""Storefront record — the §6.3 entity as the domain returns it."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Storefront:
+    id: int
+    name: str

backend/app/domains/storefronts/service.py

@@ -0,0 +1,56 @@
+"""storefronts — the storefront + membership service (SD-0001 §6.5).
+
+Owns the storefront entity, the account<->storefront membership (INV-5), the entry-routing
+answer (storefront_for), and INV-4's one-storefront guard — the single deletable check that
+makes one-per-account an MVP rule, not a schema law. Never mints identity: the BFF passes
+account_id and email down.
+"""
+from __future__ import annotations
+
+import psycopg
+
+from .errors import AlreadyOwnsStorefront
+from .models import Storefront
+
+
+def _default_name(email: str) -> str:
+    """§6.3: a blank name stores a generated default — never NULL (corpus 14.01.0026)."""
+    return f"{email.split('@', 1)[0]}'s storefront"
+
+
+def storefront_for(conn: psycopg.Connection, account_id: int) -> Storefront | None:
+    """The entry-routing answer (§6.5): which storefront, if any, this account has."""
+    row = conn.execute(
+        "SELECT s.id, s.name FROM storefront s"
+        " JOIN storefront_membership m ON m.storefront_id = s.id"
+        " WHERE m.account_id = %s ORDER BY m.created_at LIMIT 1",
+        (account_id,),
+    ).fetchone()
+    return Storefront(id=row[0], name=row[1]) if row else None
+
+
+def create_storefront(
+    conn: psycopg.Connection, account_id: int, email: str, name: str | None
+) -> Storefront:
+    """Create the account's one storefront + owner membership (PUC-4; INV-4, INV-5).
+
+    Guard + insert run as one atomic unit: a transaction-scoped advisory lock keyed by
+    account_id serializes concurrent creates for the same account, so the second of two
+    racing requests sees the first's committed membership and is refused (§6.5).
+    """
+    conn.execute("SELECT pg_advisory_xact_lock(%s)", (account_id,))
+    existing = storefront_for(conn, account_id)
+    if existing is not None:
+        conn.rollback()  # release the advisory lock; nothing was written
+        raise AlreadyOwnsStorefront()
+    final_name = (name or "").strip() or _default_name(email)
+    sf_id = conn.execute(
+        "INSERT INTO storefront (name) VALUES (%s) RETURNING id", (final_name,)
+    ).fetchone()[0]
+    conn.execute(
+        "INSERT INTO storefront_membership (account_id, storefront_id, role)"
+        " VALUES (%s, %s, 'owner')",
+        (account_id, sf_id),
+    )
+    conn.commit()
+    return Storefront(id=sf_id, name=final_name)

backend/app/main.py

@@ -3,22 +3,24 @@
 SLICE-1 mounted /healthz; SLICE-2 adds the /api/auth/* identity endpoints (§6.4). The BFF
 translates HTTP <-> domain calls and owns no business logic (INV-6): every rule lives in
 the accounts domain. create_app() opens the pool, self-migrates (INV-1, INV-7), and builds
-the configured mailer (INV-8) at startup. storefront is hard-wired null this slice; the
-storefronts domain (SLICE-3) replaces the _storefront_for seam.
+the configured mailer (INV-8) at startup. SLICE-3 adds POST /api/storefronts and feeds the
+_storefront_for seam from the storefronts domain.
 """
 from __future__ import annotations
 
 import logging
 import sys
 from contextlib import asynccontextmanager
+from pathlib import Path
 from typing import Any
 
 import psycopg
 from fastapi import Depends, FastAPI, Response
 from fastapi.responses import JSONResponse
+from fastapi.staticfiles import StaticFiles
 from pydantic import BaseModel
 
-from app.domains import accounts
+from app.domains import accounts, storefronts
 from app.platform import config, db
 from app.platform import mailer as mailer_mod
 from app.platform.deps import SESSION_COOKIE, get_conn, get_mailer, get_session
@@ -26,6 +28,15 @@ from app.platform.mailer import Mailer
 from app.platform import session as session_mod
 
 
+# The repo-root VERSION file is the single version source: the deploy pin checks out its
+# tag, and /healthz must report it back (flotilla-core's verify gate compares them).
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+try:
+    _APP_VERSION = (_REPO_ROOT / "VERSION").read_text().strip()
+except OSError:
+    _APP_VERSION = "0.0.0"
+
+
 class RequestCodeBody(BaseModel):
     email: str
 
@@ -35,18 +46,19 @@ class VerifyBody(BaseModel):
     code: str
 
 
+class CreateStorefrontBody(BaseModel):
+    name: str | None = None
+
+
 def _error(status: int, code: str, message: str, **extra: Any) -> JSONResponse:
     """The shared §6.4 error envelope: {"error": {"code", "message", ...}}."""
     return JSONResponse(status_code=status, content={"error": {"code": code, "message": message, **extra}})
 
 
 def _storefront_for(conn: psycopg.Connection, account: accounts.Account) -> dict | None:
-    """The entry-routing answer: which storefront, if any, this account has (§6.5).
-
-    Hard-wired null in SLICE-2 (identity only). SLICE-3 replaces this with a storefronts
-    domain call; the verify/me responses already carry the field.
-    """
-    return None
+    """The entry-routing answer: which storefront, if any, this account has (§6.5)."""
+    sf = storefronts.storefront_for(conn, account.id)
+    return {"id": sf.id, "name": sf.name} if sf else None
 
 
 def _ensure_app_logging() -> None:
@@ -78,7 +90,7 @@ def _set_session_cookie(response: Response, account: accounts.Account) -> None:
     )
 
 
-def create_app(database_url: str | None = None) -> FastAPI:
+def create_app(database_url: str | None = None, static_dir: str | Path | None = None) -> FastAPI:
     _ensure_app_logging()
     dsn = database_url or config.database_url()
 
@@ -93,7 +105,7 @@ def create_app(database_url: str | None = None) -> FastAPI:
         finally:
             app.state.pool.close()
 
-    app = FastAPI(title="ecomm", version="0.2", lifespan=lifespan)
+    app = FastAPI(title="ecomm", version=_APP_VERSION, lifespan=lifespan)
 
     @app.get("/healthz")
     def healthz(response: Response, conn: psycopg.Connection = Depends(get_conn)):
@@ -107,7 +119,7 @@ def create_app(database_url: str | None = None) -> FastAPI:
         if pending:
             response.status_code = 503
             return {"status": "unavailable", "reason": "migrations_pending"}
-        return {"status": "ok"}
+        return {"status": "ok", "version": _APP_VERSION}
 
     @app.post("/api/auth/request-code")
     def request_code(
@@ -126,6 +138,11 @@ def create_app(database_url: str | None = None) -> FastAPI:
                 f"Please wait {exc.retry_after_s}s before requesting another code.",
                 retry_after_s=exc.retry_after_s,
             )
+        except accounts.DeliveryFailed:
+            return _error(
+                502, "delivery_failed",
+                "We couldn't send the code — try again in a moment.",
+            )
         return Response(status_code=204)
 
     @app.post("/api/auth/verify")
@@ -170,6 +187,34 @@ def create_app(database_url: str | None = None) -> FastAPI:
         resp.delete_cookie(SESSION_COOKIE, path="/")
         return resp
 
+    @app.post("/api/storefronts")
+    def create_storefront(
+        body: CreateStorefrontBody,
+        conn: psycopg.Connection = Depends(get_conn),
+        sess: dict | None = Depends(get_session),
+    ):
+        """Create the account's one storefront (§6.4; PUC-4, INV-4/PUC-7 on refusal)."""
+        if sess is None:
+            return _error(401, "unauthenticated", "You are not signed in.")
+        account = accounts.get_account(conn, sess["account_id"])
+        if account is None:
+            return _error(401, "unauthenticated", "You are not signed in.")
+        try:
+            sf = storefronts.create_storefront(conn, account.id, account.email, body.name)
+        except storefronts.AlreadyOwnsStorefront:
+            return _error(
+                409, "already_owns_storefront",
+                "Your account already has its storefront — ecomm is one storefront per account today.",
+            )
+        return JSONResponse(status_code=201, content={"id": sf.id, "name": sf.name})
+
+    # Deployed topology (launch-app SPEC §2): nginx proxies everything here, so the
+    # backend serves the built SPA. Mounted LAST so /healthz and /api/* win. In dev the
+    # dist dir doesn't exist (Vite serves the frontend) and the mount is skipped.
+    spa_dir = Path(static_dir) if static_dir is not None else _REPO_ROOT / "frontend" / "dist"
+    if (spa_dir / "index.html").is_file():
+        app.mount("/", StaticFiles(directory=spa_dir, html=True), name="spa")
+
     return app
 
 

backend/app/platform/config.py

@@ -36,5 +36,35 @@ def cookie_secure() -> bool:
 
 
 def mailer_kind() -> str:
-    """Which mailer adapter to build: 'log' (dev/tests) or 'smtp' (deployed; SLICE-4)."""
+    """Which mailer adapter to build: 'log' (dev/tests) or 'smtp' (deployed)."""
     return os.environ.get("ECOMM_MAILER") or "log"
+
+
+# SMTP relay coordinates (deployed envs only; INV-8 — host/port/user/from are non-secret
+# overlay values, the password is a Secret Manager reference resolved by the deploy).
+
+
+def smtp_host() -> str:
+    return os.environ.get("ECOMM_SMTP_HOST", "")
+
+
+def smtp_port() -> int:
+    return int(os.environ.get("ECOMM_SMTP_PORT") or "587")
+
+
+def smtp_user() -> str:
+    return os.environ.get("ECOMM_SMTP_USER", "")
+
+
+def smtp_password() -> str:
+    return os.environ.get("ECOMM_SMTP_PASSWORD", "")
+
+
+def smtp_from() -> str:
+    """The From header; defaults to the relay user."""
+    return os.environ.get("ECOMM_SMTP_FROM") or smtp_user()
+
+
+def smtp_starttls() -> bool:
+    """STARTTLS on the relay connection (default on; disable only for odd relays)."""
+    return os.environ.get("ECOMM_SMTP_STARTTLS", "1").strip().lower() not in {"0", "false", "no", "off"}

backend/app/platform/mailer.py

@@ -2,20 +2,30 @@
 
 A one-method port `send(to, subject, body)` with two adapters: `LogMailer` (dev/tests —
 the message lands in the app log and an in-memory outbox tests read back, §6.8) and the
-deployed `SmtpMailer` (SLICE-4). The adapter is chosen by configuration at startup
-(INV-8), so no deployment shape lives in the domain. LogMailer logs the full body on
-purpose: that is PUC-10's "local dev channel" — the one-time code reaches the developer in
-the terminal. The deployed mailer (SLICE-4) will NOT log the body (INV-3 / §6.6 log hygiene).
+deployed `SmtpMailer` (relay coordinates from configuration, INV-8). The adapter is chosen
+by configuration at startup, so no deployment shape lives in the domain. LogMailer logs the
+full body on purpose: that is PUC-10's "local dev channel" — the one-time code reaches the
+developer in the terminal. SmtpMailer never logs the body or the recipient (INV-3 / §6.6
+log hygiene) and raises MailerError on delivery failure (INV-9 → the §6.4 502).
 """
 from __future__ import annotations
 
+import hashlib
 import logging
+import smtplib
 from dataclasses import dataclass
+from email.message import EmailMessage
 from typing import Protocol
 
+from app.platform import config
+
 logger = logging.getLogger("ecomm.mailer")
 
 
+class MailerError(Exception):
+    """Delivery failed — the relay refused or was unreachable (INV-9)."""
+
+
 @dataclass(frozen=True)
 class SentMessage:
     to: str
@@ -41,10 +51,48 @@ class LogMailer:
         logger.info("LogMailer -> %s | %s\n%s", to, subject, body)
 
 
+class SmtpMailer:
+    """Deployed adapter: real mail over an SMTP relay (STARTTLS + login by default).
+
+    Logs only a hashed recipient — never the address, subject, or body (§6.6).
+    """
+
+    def __init__(self, host: str, port: int, user: str, password: str, sender: str, starttls: bool) -> None:
+        self._host, self._port = host, port
+        self._user, self._password = user, password
+        self._sender, self._starttls = sender, starttls
+
+    def send(self, to: str, subject: str, body: str) -> None:
+        msg = EmailMessage()
+        msg["To"] = to
+        msg["From"] = self._sender
+        msg["Subject"] = subject
+        msg.set_content(body)
+        to_hash = hashlib.sha256(to.encode("utf-8")).hexdigest()[:8]
+        try:
+            with smtplib.SMTP(self._host, self._port, timeout=10) as smtp:
+                if self._starttls:
+                    smtp.starttls()
+                if self._user:
+                    smtp.login(self._user, self._password)
+                smtp.send_message(msg)
+        except Exception as exc:
+            logger.warning("smtp send FAILED to=%s: %s", to_hash, type(exc).__name__)
+            raise MailerError(str(exc)) from exc
+        logger.info("smtp sent to=%s", to_hash)
+
+
 def build_mailer(kind: str) -> Mailer:
     """Select the mailer adapter by configured kind (config.mailer_kind(), INV-8)."""
     if kind == "log":
         return LogMailer()
     if kind == "smtp":
-        raise NotImplementedError("SmtpMailer arrives in SLICE-4 (deployed environments)")
+        return SmtpMailer(
+            host=config.smtp_host(),
+            port=config.smtp_port(),
+            user=config.smtp_user(),
+            password=config.smtp_password(),
+            sender=config.smtp_from(),
+            starttls=config.smtp_starttls(),
+        )
     raise ValueError(f"unknown mailer kind: {kind!r}")

backend/tests/test_accounts_request_code.py

@@ -64,3 +64,28 @@ def test_request_code_rejects_invalid_email(conn):
     with pytest.raises(accounts.InvalidEmail):
         accounts.request_code(conn, m, "not-an-email")
     assert m.outbox == []
+
+
+class _FailingMailer:
+    """A mailer whose relay always refuses — the INV-9 honest-failure path."""
+
+    def send(self, to: str, subject: str, body: str) -> None:
+        raise mailer.MailerError("relay refused")
+
+
+def test_delivery_failure_leaves_no_orphan_code(conn):
+    # ecomm#7: send happens BEFORE commit — a failed delivery must not strand an
+    # auth_code row (which would also trip the resend cooldown for 60s).
+    with pytest.raises(accounts.DeliveryFailed):
+        accounts.request_code(conn, _FailingMailer(), "merchant@example.com")
+    rows = conn.execute("SELECT count(*) FROM auth_code").fetchone()[0]
+    assert rows == 0
+
+
+def test_delivery_failure_does_not_trip_cooldown(conn):
+    with pytest.raises(accounts.DeliveryFailed):
+        accounts.request_code(conn, _FailingMailer(), "merchant@example.com")
+    # the immediate retry (relay back up) succeeds — no ResendCooldown
+    m = mailer.LogMailer()
+    accounts.request_code(conn, m, "merchant@example.com")
+    assert len(m.outbox) == 1

backend/tests/test_auth_endpoints.py

@@ -128,3 +128,19 @@ def test_puc_09_logout_clears_session(fresh_db_url):
         # after logout the cookie is cleared -> /me is unauthenticated again
         client.cookies.clear()
         assert client.get("/api/auth/me").status_code == 401
+
+
+def test_request_code_delivery_failure_is_502(fresh_db_url, monkeypatch):
+    # INV-9 honest failure over HTTP (§6.4): the relay refused -> 502 delivery_failed,
+    # never a fake 204. Force the app's mailer to fail after startup.
+    from app.platform import mailer as mailer_mod
+
+    class _FailingMailer:
+        def send(self, to, subject, body):
+            raise mailer_mod.MailerError("relay refused")
+
+    with _client(fresh_db_url) as client:
+        client.app.state.mailer = _FailingMailer()
+        resp = client.post("/api/auth/request-code", json={"email": "merchant@example.com"})
+    assert resp.status_code == 502
+    assert resp.json()["error"]["code"] == "delivery_failed"

backend/tests/test_bootstrap.py

@@ -0,0 +1,42 @@
+"""INV-1's enforcement (SD-0001 §6.8): from an empty database, one test walks the whole
+flow — request-code -> verify -> create-storefront -> /me — asserting no step needed
+seeded state. Migration idempotence (the second INV-1 test) lives in test_migrations.py."""
+import re
+
+from fastapi.testclient import TestClient
+
+from app.main import create_app
+
+
+def test_inv_1_bootstrap_whole_flow_from_empty(fresh_db_url):
+    # fresh_db_url is a brand-new empty database; create_app() self-migrates (INV-7).
+    with TestClient(create_app(database_url=fresh_db_url)) as client:
+        # a fresh deployment serves healthz green before any row exists
+        assert client.get("/healthz").json()["status"] == "ok"
+
+        # PUC-2: first visitor requests a code; it reaches them via the dev channel
+        assert client.post(
+            "/api/auth/request-code", json={"email": "first@example.com"}
+        ).status_code == 204
+        code = re.search(r"\b(\d{6})\b", client.app.state.mailer.outbox[-1].body).group(1)
+
+        # verify creates account #1 — the first row, through the product alone
+        verified = client.post(
+            "/api/auth/verify", json={"email": "first@example.com", "code": code}
+        )
+        assert verified.status_code == 200
+        assert verified.json()["created"] is True
+        assert verified.json()["storefront"] is None  # -> create-storefront (PUC-5)
+
+        # PUC-4: create the storefront (blank name -> generated default)
+        created = client.post("/api/storefronts", json={})
+        assert created.status_code == 201
+        assert created.json()["name"] == "first's storefront"
+
+        # PUC-6/PUC-8: the admin answer — storefront + email from /me alone
+        me = client.get("/api/auth/me")
+        assert me.status_code == 200
+        assert me.json() == {
+            "account": {"email": "first@example.com"},
+            "storefront": created.json(),
+        }

backend/tests/test_healthz.py

@@ -1,14 +1,20 @@
+from pathlib import Path
+
 from fastapi.testclient import TestClient
 
 from app.main import create_app
 
+# /healthz reports the VERSION file's value — the flotilla deploy gate compares
+# body.version against the pinned target (flotilla-core SPEC §8.1 phase 8).
+_VERSION = (Path(__file__).resolve().parents[2] / "VERSION").read_text().strip()
+
 
 def test_healthz_ok_on_migrated_empty_db(fresh_db_url):
     app = create_app(database_url=fresh_db_url)
     with TestClient(app) as client:
         resp = client.get("/healthz")
     assert resp.status_code == 200
-    assert resp.json() == {"status": "ok"}
+    assert resp.json() == {"status": "ok", "version": _VERSION}
 
 
 def test_startup_migrates_from_empty(fresh_db_url):

backend/tests/test_mailer.py

@@ -17,10 +17,95 @@ def test_build_mailer_log_kind():
     assert isinstance(m, mailer.LogMailer)
 
 
-def test_build_mailer_smtp_not_yet_available():
-    # SmtpMailer lands in SLICE-4; until then asking for it is an explicit error, not a
-    # silent fallback to LogMailer (which would send no real mail in a deployed env).
+class _FakeSMTP:
+    """Stand-in for smtplib.SMTP capturing the call sequence (no network)."""
+
+    instances: list["_FakeSMTP"] = []
+    fail_on_send = False
+
+    def __init__(self, host, port, timeout=None):
+        self.host, self.port, self.timeout = host, port, timeout
+        self.calls: list[str] = []
+        self.message = None
+        _FakeSMTP.instances.append(self)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+    def starttls(self):
+        self.calls.append("starttls")
+
+    def login(self, user, password):
+        self.calls.append(f"login:{user}")
+
+    def send_message(self, msg):
+        if _FakeSMTP.fail_on_send:
+            raise RuntimeError("relay refused")
+        self.calls.append("send_message")
+        self.message = msg
+
+
+def _smtp_env(monkeypatch):
+    monkeypatch.setattr(mailer.smtplib, "SMTP", _FakeSMTP)
+    _FakeSMTP.instances.clear()
+    _FakeSMTP.fail_on_send = False
+    monkeypatch.setenv("ECOMM_SMTP_HOST", "smtp.example.com")
+    monkeypatch.setenv("ECOMM_SMTP_PORT", "587")
+    monkeypatch.setenv("ECOMM_SMTP_USER", "sender@example.com")
+    monkeypatch.setenv("ECOMM_SMTP_PASSWORD", "not-a-real-password")
+    monkeypatch.setenv("ECOMM_SMTP_FROM", "ecomm <sender@example.com>")
+
+
+def test_build_mailer_smtp_builds_from_config(monkeypatch):
+    _smtp_env(monkeypatch)
+    m = mailer.build_mailer("smtp")
+    assert isinstance(m, mailer.SmtpMailer)
+
+
+def test_smtpmailer_sends_via_starttls_login(monkeypatch):
+    _smtp_env(monkeypatch)
+    m = mailer.build_mailer("smtp")
+    m.send("merchant@example.com", "Your ecomm code: 123456", "Code: 123456")
+    smtp = _FakeSMTP.instances[-1]
+    assert (smtp.host, smtp.port) == ("smtp.example.com", 587)
+    assert smtp.calls == ["starttls", "login:sender@example.com", "send_message"]
+    assert smtp.message["To"] == "merchant@example.com"
+    assert smtp.message["Subject"] == "Your ecomm code: 123456"
+    assert smtp.message["From"] == "ecomm <sender@example.com>"
+    assert "123456" in smtp.message.get_content()
+
+
+def test_smtpmailer_failure_raises_mailer_error(monkeypatch):
+    _smtp_env(monkeypatch)
+    _FakeSMTP.fail_on_send = True
     import pytest
 
-    with pytest.raises(NotImplementedError):
-        mailer.build_mailer("smtp")
+    m = mailer.build_mailer("smtp")
+    with pytest.raises(mailer.MailerError):
+        m.send("merchant@example.com", "subject", "body")
+
+
+def test_smtpmailer_never_logs_the_body(monkeypatch):
+    # §6.6 log hygiene: codes never appear in deployed logs. LogMailer logging the body
+    # is dev-only by configuration; the deployed adapter must not. The handler attaches
+    # directly to the ecomm.mailer logger (it doesn't propagate to root).
+    import logging
+
+    _smtp_env(monkeypatch)
+    records: list[str] = []
+    handler = logging.Handler()
+    handler.emit = lambda r: records.append(r.getMessage())  # type: ignore[method-assign]
+    lg = logging.getLogger("ecomm.mailer")
+    lg.addHandler(handler)
+    lg.setLevel(logging.DEBUG)
+    try:
+        mailer.build_mailer("smtp").send(
+            "merchant@example.com", "Your ecomm code: 123456", "Code: 123456"
+        )
+    finally:
+        lg.removeHandler(handler)
+    assert records, "the deployed adapter should log the send event (observability §6.6)"
+    assert all("123456" not in r and "merchant@example.com" not in r for r in records)

backend/tests/test_static_spa.py

@@ -0,0 +1,24 @@
+"""Deployed topology (launch-app SPEC §2): nginx proxies EVERYTHING to the backend, so
+the backend must serve the built SPA (frontend/dist) itself. Dev is unaffected — Vite
+serves the frontend and the default dist dir simply doesn't exist."""
+from fastapi.testclient import TestClient
+
+from app.main import create_app
+
+
+def test_spa_served_when_dist_present(fresh_db_url, tmp_path):
+    (tmp_path / "index.html").write_text("<!doctype html><title>ecomm spa</title>")
+    with TestClient(create_app(database_url=fresh_db_url, static_dir=tmp_path)) as client:
+        root = client.get("/")
+        assert root.status_code == 200
+        assert "ecomm spa" in root.text
+        # API + health still win over the mount
+        assert client.get("/healthz").json()["status"] == "ok"
+        assert client.get("/api/auth/me").status_code == 401
+
+
+def test_no_mount_when_dist_absent(fresh_db_url, tmp_path):
+    # An empty/missing dist (the dev case) must not 500 the app — / just 404s.
+    with TestClient(create_app(database_url=fresh_db_url, static_dir=tmp_path / "nope")) as client:
+        assert client.get("/").status_code == 404
+        assert client.get("/healthz").json()["status"] == "ok"

backend/tests/test_storefronts_create.py

@@ -0,0 +1,154 @@
+"""SLICE-3 storefront creation — service + endpoint scenario tests (SD-0001 §6.5 PUC-4/7)."""
+import re
+from contextlib import contextmanager
+
+import psycopg
+import pytest
+from fastapi.testclient import TestClient
+
+from app.main import create_app
+from app.domains import storefronts
+from app.platform import db
+
+
+@pytest.fixture()
+def migrated_conn(fresh_db_url):
+    with psycopg.connect(fresh_db_url) as conn:
+        db.migrate(conn)
+        yield conn
+
+
+def _account_id(conn, email="merchant@example.com"):
+    return conn.execute(
+        "INSERT INTO account (email) VALUES (%s) RETURNING id", (email,)
+    ).fetchone()[0]
+
+
+def test_create_storefront_with_name(migrated_conn):
+    acct = _account_id(migrated_conn)
+    sf = storefronts.create_storefront(migrated_conn, acct, "merchant@example.com", "Ben's Bets")
+    assert sf.name == "Ben's Bets"
+    assert storefronts.storefront_for(migrated_conn, acct) == sf
+
+
+def test_14_01_0026_blank_name_gets_generated_default(migrated_conn):
+    acct = _account_id(migrated_conn)
+    sf = storefronts.create_storefront(migrated_conn, acct, "merchant@example.com", None)
+    assert sf.name == "merchant's storefront"
+
+
+def test_whitespace_name_treated_as_blank(migrated_conn):
+    acct = _account_id(migrated_conn)
+    sf = storefronts.create_storefront(migrated_conn, acct, "ben@bensbets.com", "   ")
+    assert sf.name == "ben's storefront"
+
+
+def test_second_create_refused_inv_4(migrated_conn):
+    acct = _account_id(migrated_conn)
+    storefronts.create_storefront(migrated_conn, acct, "merchant@example.com", "First")
+    with pytest.raises(storefronts.AlreadyOwnsStorefront):
+        storefronts.create_storefront(migrated_conn, acct, "merchant@example.com", "Second")
+
+
+def test_membership_row_is_owner(migrated_conn):
+    acct = _account_id(migrated_conn)
+    sf = storefronts.create_storefront(migrated_conn, acct, "merchant@example.com", None)
+    role = migrated_conn.execute(
+        "SELECT role FROM storefront_membership WHERE account_id = %s AND storefront_id = %s",
+        (acct, sf.id),
+    ).fetchone()[0]
+    assert role == "owner"
+
+
+def test_storefront_for_none_when_absent(migrated_conn):
+    acct = _account_id(migrated_conn)
+    assert storefronts.storefront_for(migrated_conn, acct) is None
+
+
+# ── endpoint scenario tests (§6.4 POST /api/storefronts; corpus 14.01.*) ──────────
+
+
+@contextmanager
+def _signed_in_client(fresh_db_url, email="merchant@example.com"):
+    with TestClient(create_app(database_url=fresh_db_url)) as client:
+        client.post("/api/auth/request-code", json={"email": email})
+        code = re.search(r"\b(\d{6})\b", client.app.state.mailer.outbox[-1].body).group(1)
+        client.post("/api/auth/verify", json={"email": email, "code": code})
+        yield client
+
+
+def test_14_01_0013_create_storefront_with_name(fresh_db_url):
+    with _signed_in_client(fresh_db_url) as client:
+        resp = client.post("/api/storefronts", json={"name": "Ben's Bets"})
+    assert resp.status_code == 201
+    assert resp.json()["name"] == "Ben's Bets"
+    assert isinstance(resp.json()["id"], int)
+
+
+def test_14_01_0015_0016_nothing_but_a_name_is_asked(fresh_db_url):
+    # No payment method, plan, or commitment: the request body needs nothing at all and
+    # the response carries only the storefront — no plan/trial/billing fields.
+    with _signed_in_client(fresh_db_url) as client:
+        resp = client.post("/api/storefronts", json={})
+    assert resp.status_code == 201
+    assert set(resp.json().keys()) == {"id", "name"}
+
+
+def test_14_01_0025_create_lands_on_admin(fresh_db_url):
+    # After create, the entry-routing answer carries the storefront -> admin (PUC-6).
+    with _signed_in_client(fresh_db_url) as client:
+        created = client.post("/api/storefronts", json={"name": "Ben's Bets"}).json()
+        me = client.get("/api/auth/me").json()
+    assert me["storefront"] == created
+
+
+def test_puc_05_returning_without_storefront_routes_to_create(fresh_db_url):
+    with _signed_in_client(fresh_db_url) as client:
+        me = client.get("/api/auth/me").json()
+    assert me["storefront"] is None
+
+
+def test_14_01_0027_returning_with_storefront_straight_to_admin(fresh_db_url):
+    # PUC-6: a returning merchant's verify response already carries the storefront.
+    from datetime import datetime, timedelta, timezone
+
+    email = "returning@example.com"
+    with _signed_in_client(fresh_db_url, email) as client:
+        client.post("/api/storefronts", json={"name": "Ben's Bets"})
+        # fresh login: backdate the consumed code to clear the 60s resend cooldown
+        with psycopg.connect(fresh_db_url) as c:
+            c.execute(
+                "UPDATE auth_code SET created_at = %s WHERE email = %s",
+                (datetime.now(timezone.utc) - timedelta(minutes=2), email),
+            )
+            c.commit()
+        client.post("/api/auth/request-code", json={"email": email})
+        code = re.search(r"\b(\d{6})\b", client.app.state.mailer.outbox[-1].body).group(1)
+        resp = client.post("/api/auth/verify", json={"email": email, "code": code})
+    assert resp.status_code == 200
+    assert resp.json()["storefront"]["name"] == "Ben's Bets"
+    assert resp.json()["created"] is False
+
+
+def test_puc_07_second_create_refused_409(fresh_db_url):
+    with _signed_in_client(fresh_db_url) as client:
+        client.post("/api/storefronts", json={"name": "First"})
+        resp = client.post("/api/storefronts", json={"name": "Second"})
+    assert resp.status_code == 409
+    assert resp.json()["error"]["code"] == "already_owns_storefront"
+
+
+def test_puc_08_admin_shell_answer(fresh_db_url):
+    # The shell renders from /me alone: storefront name + signed-in email (§6.5 PUC-8).
+    with _signed_in_client(fresh_db_url) as client:
+        client.post("/api/storefronts", json={"name": "Ben's Bets"})
+        me = client.get("/api/auth/me").json()
+    assert me["account"]["email"] == "merchant@example.com"
+    assert me["storefront"]["name"] == "Ben's Bets"
+
+
+def test_create_storefront_requires_session(fresh_db_url):
+    with TestClient(create_app(database_url=fresh_db_url)) as client:
+        resp = client.post("/api/storefronts", json={"name": "Nope"})
+    assert resp.status_code == 401
+    assert resp.json()["error"]["code"] == "unauthenticated"

backend/tests/test_storefronts_invariants.py

@@ -0,0 +1,64 @@
+"""INV-4's sharp edges (SD-0001 §6.8): concurrent second-storefront refusal, and the
+membership schema staying many-capable (the rule is a deletable guard, not a schema law)."""
+import threading
+
+import psycopg
+import pytest
+
+from app.domains import storefronts
+from app.platform import db
+
+
+@pytest.fixture()
+def migrated_url(fresh_db_url):
+    with psycopg.connect(fresh_db_url) as conn:
+        db.migrate(conn)
+    return fresh_db_url
+
+
+def test_inv_4_concurrent_creates_exactly_one_wins(migrated_url):
+    with psycopg.connect(migrated_url) as setup:
+        acct = setup.execute(
+            "INSERT INTO account (email) VALUES ('racer@example.com') RETURNING id"
+        ).fetchone()[0]
+        setup.commit()
+
+    barrier = threading.Barrier(2)
+    results: list[str] = []
+
+    def racer():
+        with psycopg.connect(migrated_url) as conn:
+            barrier.wait()
+            try:
+                storefronts.create_storefront(conn, acct, "racer@example.com", None)
+                results.append("created")
+            except storefronts.AlreadyOwnsStorefront:
+                results.append("refused")
+
+    threads = [threading.Thread(target=racer) for _ in range(2)]
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join()
+
+    assert sorted(results) == ["created", "refused"]
+    with psycopg.connect(migrated_url) as check:
+        count = check.execute(
+            "SELECT count(*) FROM storefront_membership WHERE account_id = %s", (acct,)
+        ).fetchone()[0]
+    assert count == 1
+
+
+def test_inv_4_schema_stays_many_capable(migrated_url):
+    # No UNIQUE(account_id) anywhere in the storefront path: the only unique constraint on
+    # storefront_membership is its composite PK, so many-per-account stays a deletable
+    # service rule (R-5 mitigation).
+    with psycopg.connect(migrated_url) as conn:
+        uniques = conn.execute(
+            "SELECT i.indkey::text FROM pg_index i"
+            " JOIN pg_class c ON c.oid = i.indrelid"
+            " WHERE c.relname = 'storefront_membership' AND (i.indisunique OR i.indisprimary)"
+        ).fetchall()
+    # exactly one unique index (the composite PK over two columns)
+    assert len(uniques) == 1
+    assert len(uniques[0][0].split()) == 2

deployment.toml

@@ -0,0 +1,42 @@
+# deployment.toml — generated by define-deployment (launch-app SPEC §5.1, §6.6).
+# Derived from the One Name 'ecomm' (§3.3); edit the toml, re-import to reconcile (§3.2.1).
+
+[app]
+name          = "ecomm"
+repo          = "wiggleverse/wiggleverse-ecomm"
+gitea_host    = "https://git.wiggleverse.org"
+version_source = { kind = "file", path = "VERSION" }
+gitea_read_secret_ref = "wiggleverse-ecomm/ecomm-gitea-read-token"
+
+[vm]
+name          = "ecomm-ppe"
+zone          = "us-central1-a"
+project       = "wiggleverse-ecomm"
+machine_type  = "e2-micro"
+disk_gb       = 10
+service_user  = "ecomm"
+install_dir   = "/opt/ecomm"
+systemd_unit  = "ecomm.service"
+tunnel_through_iap = true
+gcloud_config = "wiggleverse-ecomm"
+
+[edge]
+domain        = "ecomm-ppe.wiggleverse.org"
+# ecomm's health endpoint is /healthz (SD-0001 §6.4); body carries {status, version}.
+health_url    = "https://ecomm-ppe.wiggleverse.org/healthz"
+
+# No DATABASE_PATH: ecomm runs Cloud SQL PostgreSQL (SD-0001 D-7/D-8) — the DSN is the
+# ECOMM_DATABASE_URL secret reference below, minted by launch-app's provision-datastore.
+[overlay]                              # non-secret env, plaintext (guide §8)
+APP_URL             = "https://ecomm-ppe.wiggleverse.org"
+ECOMM_MAILER        = "smtp"
+ECOMM_COOKIE_SECURE = "1"
+ECOMM_SMTP_HOST     = "smtp.gmail.com"
+ECOMM_SMTP_PORT     = "587"
+ECOMM_SMTP_USER     = "ben.stull@wiggleverse.org"
+ECOMM_SMTP_FROM     = "ecomm <ben.stull@wiggleverse.org>"
+
+[secrets]                              # REFERENCES only — never bytes (§8.3)
+ECOMM_SESSION_SECRET = "wiggleverse-ecomm/ecomm-ppe-session-secret"
+ECOMM_DATABASE_URL   = "wiggleverse-ecomm/ecomm-ppe-database-url"
+ECOMM_SMTP_PASSWORD  = "wiggleverse-ohm/ohm-rfc-app-smtp-password"

docs/BOOTSTRAP.md

@@ -4,8 +4,9 @@ Bringing an environment from **empty persistence** to "first merchant, first
 storefront" through the product flows alone (SD-0001 BUC-5). Empty is a working state
 (INV-1): the app applies its own schema migrations at startup; there is no seed step.
 
-This document grows per environment. SLICE-1 ships the **localhost** section; the
-pre-production and production sections land with SLICE-4.
+This document grows per environment. SLICE-1 shipped the **localhost** section;
+SLICE-4 adds **pre-production (PPE)**. The production section lands with the prod
+stand-up.
 
 ## Localhost
 
@@ -61,4 +62,79 @@ environment starts from (BUC-5a).
 `scripts/dev.sh` sets `ECOMM_DATABASE_URL` to the local compose DSN
 (`postgresql://ecomm:ecomm@localhost:5432/ecomm`). No deployment shape is baked into
 the app (INV-8); deployed environments supply this and other config from Secret
-Manager (SLICE-4).
+Manager (see PPE below).
+
+## Pre-production (PPE)
+
+PPE is stood up and deployed through the **launch-app / flotilla-core** suite only
+(handbook §8.5 — provisioning is an operator-run gesture). The app's deployment
+record is `deployment.toml` at this repo's root; flotilla-core consumes it.
+
+### One-time provisioning (operator-run, in order)
+
+1. **Cloud foundation** — `scaffold-gcp-project`: the GCP project, its dedicated
+   `--no-activate` gcloud config, billing, core APIs, ADC quota pin.
+2. **Managed database** — `provision-datastore` (launch-app §6.6a, built for ecomm's
+   D-7/D-8): Cloud SQL for PostgreSQL 16, private-IP-only, automated backups +
+   point-in-time recovery; writes the full DSN to Secret Manager as
+   `<project>/ecomm-ppe-database-url`. Bound on the deployment record as
+   `ECOMM_DATABASE_URL`.
+3. **Secrets** (references only — bytes go in via stdin, never through a session):
+   `ECOMM_SESSION_SECRET` (fresh random), `ECOMM_SMTP_PASSWORD` (the shared
+   Wiggleverse relay credential), and flotilla's own Gitea read token for this
+   private repo.
+4. **VM + edge** — `provision-vm`: the e2-micro, IAP-only SSH, nginx + Cloudflare
+   origin TLS, the systemd unit, DNS for `ecomm-ppe.wiggleverse.org`.
+5. **Deployment record** — `flotilla-core deployment scaffold ecomm … -o
+   deployment.toml`, validate, commit it here, `deployment import --reconcile`.
+
+### Deploy
+
+Each release is a git tag `v<VERSION>` matching the repo-root `VERSION` file (the
+pin). The one gesture, from the flotilla-core repo's venv:
+
+```bash
+CLOUDSDK_ACTIVE_CONFIG_NAME=ecomm .venv/bin/flotilla-core deploy ecomm
+```
+
+Nine phases, fail-stop; it ends by polling `https://ecomm-ppe.wiggleverse.org/healthz`
+and requiring `status == "ok"` and `version == <target>`. Watch it yourself the same
+way:
+
+```bash
+curl https://ecomm-ppe.wiggleverse.org/healthz
+```
+
+### Configuration surface (PPE values)
+
+| Env var | Kind | Value |
+| --- | --- | --- |
+| `ECOMM_DATABASE_URL` | secret ref | `<project>/ecomm-ppe-database-url` (from provision-datastore) |
+| `ECOMM_SESSION_SECRET` | secret ref | `<project>/ecomm-ppe-session-secret` |
+| `ECOMM_SMTP_PASSWORD` | secret ref | the shared Wiggleverse relay credential |
+| `ECOMM_MAILER` | overlay | `smtp` |
+| `ECOMM_COOKIE_SECURE` | overlay | `1` |
+| `ECOMM_SMTP_HOST` / `_PORT` / `_USER` / `_FROM` | overlay | the relay coordinates (non-secret) |
+
+### The rehearsal (PUC-11)
+
+From empty persistence: the deploy migrates the schema at startup (INV-7); then a
+real sign-up → one-time code arriving by **real email** → create storefront → admin,
+through the public flows alone. Record each rehearsal here when it happens.
+
+**Rehearsals:**
+
+- **2026-06-11 — PPE first bootstrap (v0.4.0, session 0024): ✅** First-ever ecomm
+  deploy (`flotilla-core deploy ecomm`, 9/9 phases green, deploys.id=40) onto a
+  freshly provisioned environment — project `wiggleverse-ecomm`, Cloud SQL
+  `ecomm-ppe-pg` (provisioned by launch-app `provision-datastore`, first run), VM
+  `ecomm-ppe`. The app self-migrated the empty database at startup; the operator
+  then walked sign-up → real emailed code (Gmail relay) → create storefront →
+  honestly-empty admin in a browser, through the public flows alone. Findings
+  captured: OTC email branding (#16); identity should outgrow ecomm
+  (engineering#49/#50).
+
+## Production
+
+Lands with the prod stand-up — the **identical gesture** on a prod deployment record
+(BUC-5a): same provisioning skills, same deploy, same rehearsal.

docs/superpowers/plans/2026-06-10-slice-4-deploy-contract.md

@@ -0,0 +1,55 @@
+# SLICE-4 (part 1) — Deploy-Contract Code Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make ecomm deployable by flotilla-core's 9-phase gesture and rehearsable on PPE: versioned health, SPA served by the backend, real `SmtpMailer` with honest delivery failure (closes ecomm#7), per SD-0001 §7.2 (SLICE-4) — the code half. Provisioning (Cloud SQL via the new launch-app `provision-datastore`, VM, deployment.toml) and the PPE rehearsal follow as operator gestures in the same session.
+
+**Anchor:** SD-0001 §7.2 SLICE-4 (R2a, checked this session). flotilla contract: flotilla-core SPEC §8.1 (checkout `v<VERSION>` tag → pip → `npm ci && npm run build` → write `backend/.env` → restart → verify `body.version == target && body.status == "ok"`); provision-vm: nginx proxies ALL routes to uvicorn `app.main:app` (WorkingDirectory `backend/`), so the backend must serve `frontend/dist`.
+
+**Architecture:** `VERSION` at repo root is the single version source (healthz body + FastAPI version + the deploy pin). `create_app()` mounts `frontend/dist` (when present) after all API routes — SPA fallback via `StaticFiles(html=True)`. `SmtpMailer` is the second adapter of the existing mailer port (STARTTLS smtplib, config from `ECOMM_SMTP_*`, INV-8); delivery failure raises `MailerError` → `accounts.request_code` sends **before** commit (rollback on failure — no orphan code, no tripped cooldown; ecomm#7) → BFF surfaces `502 delivery_failed` (INV-9).
+
+**Tech Stack:** stdlib `smtplib`/`email.message`; FastAPI `StaticFiles`; no new dependencies.
+
+---
+
+### Task 1: VERSION + versioned /healthz
+
+**Files:** Create `VERSION` (root). Modify `backend/app/main.py`, `backend/tests/test_healthz.py`.
+
+- [ ] Write `VERSION` containing `0.4.0`.
+- [ ] Test first: `test_healthz_ok_on_migrated_empty_db` asserts `{"status": "ok", "version": "0.4.0"}` read from the VERSION file (compare against `(repo_root/"VERSION").read_text().strip()`, not a literal). Run → FAIL.
+- [ ] `main.py`: add `_APP_VERSION = (Path(__file__).resolve().parents[2] / "VERSION").read_text().strip()` (fallback `"0.0.0"` when missing); healthz returns `{"status": "ok", "version": _APP_VERSION}`; `FastAPI(version=_APP_VERSION)`. Run → PASS. Commit.
+
+### Task 2: backend serves the SPA (deploy phase-8 contract)
+
+**Files:** Modify `backend/app/main.py`. Test `backend/tests/test_static_spa.py`.
+
+- [ ] Test first: `create_app(database_url=..., static_dir=tmp_path)` with a `tmp_path/index.html`; GET `/` → 200 + the html; GET `/healthz` and `/api/auth/me` still answer JSON (API wins over the mount). Default `static_dir=None` → resolves `repo_root/frontend/dist`, skipped silently when absent (dev: Vite serves). Run → FAIL.
+- [ ] `create_app(database_url=None, static_dir: str | Path | None = None)`; after the last route: resolve dir, `if dir/index.html exists: app.mount("/", StaticFiles(directory=dir, html=True), name="spa")`. Run → PASS (whole suite). Commit.
+
+### Task 3: SmtpMailer + config surface (INV-8)
+
+**Files:** Modify `backend/app/platform/{mailer,config}.py`. Test `backend/tests/test_mailer.py` (extend).
+
+- [ ] Config additions: `smtp_host()` (`ECOMM_SMTP_HOST`), `smtp_port()` (`ECOMM_SMTP_PORT`, 587), `smtp_user()`, `smtp_password()`, `smtp_from()` (default = user), `smtp_starttls()` (default on).
+- [ ] Tests first: `MailerError` exists; `build_mailer("smtp")` returns `SmtpMailer` wired from env (monkeypatched); `SmtpMailer.send` drives a monkeypatched `smtplib.SMTP` (starttls → login → send_message with To/Subject/From + body) and never logs the body; SMTP exception → `MailerError`. Run → FAIL.
+- [ ] Implement: `MailerError(Exception)`; `SmtpMailer` (EmailMessage; `smtplib.SMTP(host, port, timeout=10)`, STARTTLS per config, login when user set, `send_message`; `except Exception → raise MailerError`; logs only `smtp sent to=<sha256[:8] of recipient>` — §6.6 log hygiene); `build_mailer("smtp")` builds it from config. Run → PASS. Commit.
+
+### Task 4: honest delivery failure — send-before-commit + 502 (closes ecomm#7)
+
+**Files:** Modify `backend/app/domains/accounts/{errors,service,__init__}.py`, `backend/app/main.py`. Test `backend/tests/test_accounts_request_code.py` + `test_auth_endpoints.py` (extend).
+
+- [ ] Tests first: a mailer whose `send` raises `MailerError` → service raises `accounts.DeliveryFailed`, **no `auth_code` row remains**, and an immediate retry is **not** cooldown-blocked; endpoint test: 502 `{"error": {"code": "delivery_failed"}}`. Run → FAIL.
+- [ ] Implement: `DeliveryFailed(AccountsError)`; `request_code` moves `conn.commit()` **after** `mailer.send(...)`, wrapping send in `try/except MailerError → conn.rollback(); raise DeliveryFailed`; BFF maps it to `_error(502, "delivery_failed", "We couldn't send the code — try again.")`. Run → PASS (whole backend suite). Commit.
+
+### Task 5: BOOTSTRAP.md PPE section + housekeeping + gate
+
+**Files:** Modify `docs/BOOTSTRAP.md`, `README.md`, `frontend/package.json` (0.4.0).
+
+- [ ] BOOTSTRAP.md: replace the "land with SLICE-4" sentence; add **Pre-production (PPE)** section — prerequisites (suite-run provisioning: scaffold-gcp-project → provision-datastore (Cloud SQL, engineering#46) → provision-vm → define-deployment/import; secrets as references), the one deploy gesture (`CLOUDSDK_ACTIVE_CONFIG_NAME=<config> flotilla-core deploy <name>`), how to watch `/healthz`, the rehearsal walk (PUC-11), reset-to-empty note; Prod section: placeholder "lands with the prod stand-up" honestly.
+- [ ] README status: deploy contract in place; frontend package 0.4.0.
+- [ ] `./scripts/check.sh` → all green. Commit. Push, PR citing SD-0001 §7.2 SLICE-4 + ecomm#7, merge, **tag `v0.4.0` on the merge commit and push the tag** (the deploy pin).
+
+## Self-review
+
+Spec coverage: SmtpMailer + config wiring INV-8 ✓ (T3), §6.6 hardening — Secure cookies already config-driven, log hygiene ✓ (T3 no-body logging; LogMailer is dev-only by config), `deployment.toml` + provisioning deliberately deferred to the Phase-C suite gestures (needs the GCP project id that scaffold-gcp-project mints), BOOTSTRAP.md PPE ✓ (T5), versioned health for the §8.1 verify ✓ (T1), SPA serving for the §2 topology ✓ (T2), ecomm#7 ✓ (T4). E2E browser tests still deferred per §6.8. Type consistency: `MailerError` lives in platform/mailer; `DeliveryFailed` in accounts errors; both exported via package surfaces.

docs/superpowers/plans/2026-06-10-ui-designs-collection.md

@@ -0,0 +1,118 @@
+# ui/designs Content-Repo Collection Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Establish `ui/designs/` as a standard content-repo collection (alongside `specs/` and `plans/`) — concretely in `wiggleverse-ecomm-content`, and centrally in the engineering repo's schema docs so it binds all `*-content` repos.
+
+**Architecture:** Docs/convention change only, two repos, one PR each. The collection convention's canonical home is the engineering repo's `schemas/` docs (the `content` descriptor description strings in `app.schema.json` + `schemas/README.md` changelog), so the central change is a docs-only minor schema bump (1.2 → 1.3). No tooling changes: the spec-linkage gate, backfill verb, and GUIDE/TEMPLATE Design field are tracked separately as `wiggleverse-dev-claude-plugin#93`.
+
+**Tech Stack:** Markdown, JSON Schema (description strings only), git + Gitea PRs over SSH.
+
+**Anchor:** `wiggleverse/wiggleverse-ecomm#8` (type/task, ELIGIBLE R2b). Related: `wiggleverse/wiggleverse-dev-claude-plugin#93`.
+
+---
+
+### Task 1: `ui/designs/` collection in wiggleverse-ecomm-content
+
+**Files:**
+- Create: `/Users/benstull/git/wiggleverse.org/wiggleverse/wiggleverse-ecomm-content/ui/designs/README.md`
+- Modify: `/Users/benstull/git/wiggleverse.org/wiggleverse/wiggleverse-ecomm-content/README.md` (layout table, lines 10–14)
+
+- [ ] **Step 1: Branch**
+
+```bash
+git -C /Users/benstull/git/wiggleverse.org/wiggleverse/wiggleverse-ecomm-content checkout -b ui-designs-collection
+```
+
+- [ ] **Step 2: Create the collection README**
+
+`ui/designs/README.md`:
+
+```markdown
+# ui/designs — UI-design artifacts
+
+Standard content-repo collection (alongside `specs/` and `plans/`) holding this
+app's UI-design artifacts — primarily Claude Design outputs generated from a
+Solution Design (rubric: `engineering/solution-design/claude-design-vs-code.md`).
+
+A Solution Design with a UX-involving slice references its design artifact here
+by path. The spec-linkage gate and the backfill gesture for adding that
+reference once a design exists are tracked in
+`wiggleverse/wiggleverse-dev-claude-plugin#93`.
+
+Suggested layout: one subfolder per design, named for the spec/slice it serves,
+e.g. `ui/designs/SD-0001-slice-3-storefront/`.
+```
+
+- [ ] **Step 3: Add the layout-table row**
+
+In the top-level `README.md`, extend the table:
+
+```markdown
+| Path | Holds |
+| --- | --- |
+| `specs/` | reviewed Solution-Design specs (submitted at session finalize) |
+| `plans/` | archived implementation plans |
+| `ui/designs/` | UI-design artifacts (Claude Design outputs), referenced from specs |
+```
+
+- [ ] **Step 4: Commit, push, PR, merge**
+
+```bash
+git -C …/wiggleverse-ecomm-content add ui/designs/README.md README.md
+git -C …/wiggleverse-ecomm-content commit -m "content: add ui/designs/ collection (ecomm#8)"
+git -C …/wiggleverse-ecomm-content push -u origin ui-designs-collection
+```
+
+PR via Gitea API (default per-host token, NOT the issue-scoped one — TOKENS.md), then merge; body cites `wiggleverse/wiggleverse-ecomm#8` + plugin `#93`.
+
+### Task 2: Standardize centrally in engineering schemas docs
+
+**Files:**
+- Modify: `/Users/benstull/git/wiggleverse.org/wiggleverse/engineering/schemas/app.schema.json` (lines 13, 94, 181, 184)
+- Modify: `/Users/benstull/git/wiggleverse.org/wiggleverse/engineering/schemas/README.md` (repos[] bullets + changelog)
+
+- [ ] **Step 1: Branch**
+
+```bash
+git -C /Users/benstull/git/wiggleverse.org/wiggleverse/engineering checkout -b ui-designs-collection
+```
+
+- [ ] **Step 2: Schema description strings + enum**
+
+1. `schemaVersion.enum`: `["1.0", "1.1", "1.2"]` → `["1.0", "1.1", "1.2", "1.3"]`
+2. `content` property description (line 94): "…where this app's reviewed specs/ and archived plans/ collections live…" → "…where this app's reviewed specs/, archived plans/, and ui/designs/ collections live…"
+3. `$defs.content` description (line 181): "(reviewed specs/, archived plans/)" → "(reviewed specs/, archived plans/, ui/designs/ UI-design artifacts)"; and "The specs/ and plans/ collection subdirs are appended by the submit tooling" → "The specs/, plans/, and ui/designs/ collection subdirs are conventions (specs/ and plans/ are appended by the submit tooling; ui/designs/ holds Claude Design outputs referenced from specs)"
+4. `$defs.content.subdir` description (line 184): "under which the specs/ and plans/ collections live" → "under which the specs/, plans/, and ui/designs/ collections live"
+
+- [ ] **Step 3: schemas/README.md**
+
+Changelog entry above 1.2:
+
+```markdown
+- **1.3** — docs-only: the content-repo collection convention gains a third
+  standard collection, `ui/designs/` — UI-design artifacts (Claude Design
+  outputs generated from a Solution Design), referenced from specs. Like
+  `specs/`/`plans/`, the subdir is a convention, not a schema field; no
+  validation change (the spec-linkage gate/backfill tooling is
+  wiggleverse-dev-claude-plugin#93). Existing files stay valid.
+```
+
+If the repos[] bullet list documents the `content` descriptor, name the three collections there too; if 1.2 never added a `content` bullet, add one.
+
+- [ ] **Step 4: Validate JSON, commit, push, PR, merge**
+
+```bash
+python3 -m json.tool /Users/benstull/git/wiggleverse.org/wiggleverse/engineering/schemas/app.schema.json > /dev/null && echo OK
+git -C …/engineering add schemas/app.schema.json schemas/README.md
+git -C …/engineering commit -m "schemas: 1.3 — ui/designs/ standard content collection (ecomm#8, plugin#93)"
+git -C …/engineering push -u origin ui-designs-collection
+```
+
+PR + merge (default token for `/pulls`).
+
+### Task 3: Cross-link and close out
+
+- [ ] **Step 1: Comment on plugin #93** noting the location is now standard (link both merged PRs) — its gate/backfill work can assume `ui/designs/` exists.
+- [ ] **Step 2: Close ecomm#8** with a comment naming both merged PRs.
+- [ ] **Step 3: Checkpoint the transcript** (`publish-transcript.sh` on the `--INPROGRESS` file).

frontend/index.html

@@ -3,6 +3,9 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#0E1230" />
+    <style>html { background: #0E1230; }</style>
+    <link rel="icon" type="image/svg+xml" href="/brand/mark-tile.svg" />
     <title>ecomm</title>
   </head>
   <body>

frontend/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "wiggleverse-ecomm-frontend",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "wiggleverse-ecomm-frontend",
-      "version": "0.2.0",
+      "version": "0.4.0",
       "dependencies": {
         "react": "^18.3.1",
         "react-dom": "^18.3.1"

frontend/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wiggleverse-ecomm-frontend",
   "private": true,
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "scripts": {
     "dev": "vite",

frontend/public/brand/mark-mono-gold.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="120" height="120" viewBox="0 0 120 120" fill="none" role="img" aria-label="Wiggleverse">
+  <title>Wiggleverse — mono gold</title>
+  <path d="M98 60 Q105 86 79 93 Q60 82 41 93 Q15 86 22 60 Q41 49 41 27 Q60 8 79 27 Q79 49 98 60 Z" stroke="#F4C76B" stroke-width="2.4" fill="none" stroke-linejoin="round"></path>
+  <g fill="#F4C76B">
+    <circle cx="98" cy="60" r="4.5"></circle><circle cx="79" cy="93" r="4.5"></circle><circle cx="41" cy="93" r="4.5"></circle>
+    <circle cx="22" cy="60" r="4.5"></circle><circle cx="41" cy="27" r="4.5"></circle><circle cx="79" cy="27" r="4.5"></circle>
+  </g>
+</svg>

frontend/public/brand/mark-tile.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="120" height="120" viewBox="0 0 120 120" fill="none" role="img" aria-label="Wiggleverse">
+  <title>Wiggleverse</title>
+  <rect width="120" height="120" rx="26" fill="#0E1230"></rect>
+  <path d="M98 60 Q105 86 79 93 Q60 82 41 93 Q15 86 22 60 Q41 49 41 27 Q60 8 79 27 Q79 49 98 60 Z" stroke="#F4C76B" stroke-width="5" fill="none" stroke-linejoin="round"></path>
+  <g fill="#EDEAFF">
+    <circle cx="98" cy="60" r="7"></circle><circle cx="79" cy="93" r="7"></circle><circle cx="41" cy="93" r="7"></circle>
+    <circle cx="22" cy="60" r="7"></circle><circle cx="41" cy="27" r="7"></circle><circle cx="79" cy="27" r="7"></circle>
+  </g>
+</svg>

frontend/src/App.tsx

@@ -1,20 +1,22 @@
 // App shell — loads the session, applies the entry-routing rule (SD-0001 §6.5), and renders
-// the matching screen. SLICE-2 covers the unauthenticated doors (Landing/SignIn) and a
-// signed-in placeholder; the real create-storefront/admin screens land in SLICE-3.
+// the matching screen. The rule is exhaustive: no state lands nowhere (BUC-4). The verify
+// response carries the same shape as /me, so onAuthed feeds the session directly.
 import { useEffect, useState } from "react";
-import { getMe, type VerifyResult } from "./api";
+import { getMe, type StorefrontResult, type VerifyResult } from "./api";
 import { routeFor, type SessionState } from "./routing";
+import Admin from "./screens/Admin";
+import CreateStorefront from "./screens/CreateStorefront";
 import Landing from "./screens/Landing";
 import SignIn from "./screens/SignIn";
-import SignedIn from "./screens/SignedIn";
 
 type Door = "signup" | "login";
+type Welcome = "new" | "back" | null;
 
 export default function App() {
   const [session, setSession] = useState<SessionState | null>(null);
   const [loading, setLoading] = useState(true);
   const [door, setDoor] = useState<Door | null>(null);
-  const [justCreated, setJustCreated] = useState(false);
+  const [welcome, setWelcome] = useState<Welcome>(null);
 
   async function reload() {
     setLoading(true);
@@ -26,7 +28,15 @@ export default function App() {
     void reload();
   }, []);
 
-  if (loading) return <main>Loading…</main>;
+  if (loading) {
+    return (
+      <div className="screen screen--plain">
+        <main className="screen__main">
+          <p className="note">Loading…</p>
+        </main>
+      </div>
+    );
+  }
 
   const route = routeFor(session ?? { account: null, storefront: null });
 
@@ -35,13 +45,11 @@ export default function App() {
       return (
         <SignIn
           door={door}
-          onBack={() => {
-            setDoor(null);
-          }}
+          onBack={() => setDoor(null)}
           onAuthed={(result: VerifyResult) => {
-            setJustCreated(result.created);
+            setWelcome(result.created ? "new" : "back");
             setDoor(null);
-            void reload();
+            setSession({ account: result.account, storefront: result.storefront });
           }}
         />
       );
@@ -49,16 +57,35 @@ export default function App() {
     return <Landing onGetStarted={() => setDoor("signup")} onLogIn={() => setDoor("login")} />;
   }
 
-  // route is "create-storefront" or "admin" — both are SLICE-3 screens; SLICE-2 shows the
-  // signed-in placeholder so sign-out (PUC-9) is reachable.
+  const email = session!.account!.email;
+
+  function signedOut() {
+    setWelcome(null);
+    setDoor(null);
+    setSession(null);
+  }
+
+  if (route === "create-storefront") {
     return (
-    <SignedIn
-      email={session!.account!.email}
-      created={justCreated}
-      onSignedOut={() => {
-        setJustCreated(false);
-        void reload();
+      <CreateStorefront
+        email={email}
+        welcome={welcome}
+        onCreated={(sf: StorefrontResult) => {
+          setWelcome(null);
+          setSession({ account: { email }, storefront: sf });
         }}
+        onAlreadyOwns={() => void reload()}
+        onSignedOut={signedOut}
+      />
+    );
+  }
+
+  return (
+    <Admin
+      storefrontName={session!.storefront!.name}
+      email={email}
+      welcome={welcome}
+      onSignedOut={signedOut}
     />
   );
 }

frontend/src/api.ts

@@ -59,3 +59,21 @@ export async function verifyCode(
 export async function logout(): Promise<void> {
   await fetch("/api/auth/logout", { method: "POST", credentials: "include" });
 }
+
+export interface StorefrontResult {
+  id: number;
+  name: string;
+}
+
+export async function createStorefront(
+  name: string,
+): Promise<{ ok: true; storefront: StorefrontResult } | { ok: false; error: ApiError }> {
+  const resp = await fetch("/api/storefronts", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    credentials: "include",
+    body: JSON.stringify(name.trim() ? { name: name.trim() } : {}),
+  });
+  if (resp.ok) return { ok: true, storefront: (await resp.json()) as StorefrontResult };
+  return { ok: false, error: await errorOf(resp) };
+}

frontend/src/cooldown.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { cooldownAppliesTo } from "./cooldown";
+
+describe("resend cooldown keying (SD-0001 §5.2, INV-3; bug #20)", () => {
+  it("no cooldown running -> send not blocked", () => {
+    expect(cooldownAppliesTo("a@example.com", null, 0)).toBe(false);
+  });
+
+  it("cooldown running for the same address -> blocked", () => {
+    expect(cooldownAppliesTo("a@example.com", "a@example.com", 31)).toBe(true);
+  });
+
+  it("same address modulo case/whitespace -> still blocked", () => {
+    expect(cooldownAppliesTo("  A@Example.COM ", "a@example.com", 31)).toBe(true);
+  });
+
+  it("cooldown running but the input is a different address -> not blocked", () => {
+    expect(cooldownAppliesTo("right@example.com", "wrong@example.com", 31)).toBe(false);
+  });
+
+  it("cooldown expired -> not blocked even for the same address", () => {
+    expect(cooldownAppliesTo("a@example.com", "a@example.com", 0)).toBe(false);
+  });
+});

frontend/src/cooldown.ts

@@ -0,0 +1,17 @@
+// Resend-cooldown keying (SD-0001 §5.2, INV-3; bug #20). The server's cooldown is
+// per-address, so the client countdown must be too: it blocks sending only while it
+// is running AND the current input is the address it was set for. Normalization
+// mirrors the backend's normalize_email (lowercase + strip, INV-2).
+
+function normalize(email: string): string {
+  return email.trim().toLowerCase();
+}
+
+export function cooldownAppliesTo(
+  input: string,
+  cooldownEmail: string | null,
+  secondsLeft: number,
+): boolean {
+  if (secondsLeft <= 0 || cooldownEmail === null) return false;
+  return normalize(input) === normalize(cooldownEmail);
+}

frontend/src/main.tsx

@@ -1,3 +1,4 @@
+import "./styles/index.css";
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import App from "./App";

frontend/src/screens/Admin.tsx

@@ -0,0 +1,59 @@
+// Admin shell (SD-0001 §5.4) — the storefront's stable home; honestly empty this release
+// (PUC-8; PUC-9 sign-out). Renders from /me alone: storefront name + signed-in email. No
+// zeroed metric tiles, no locked-feature teasers (OHM: Agency & Anti-Manipulation).
+// Visuals per the ui/designs export (hf-admin).
+import { logout } from "../api";
+import { AccountChip, Banner, Eyebrow, Screen, TopBar } from "../ui/kit";
+
+interface Props {
+  storefrontName: string;
+  email: string;
+  welcome: "new" | "back" | null;
+  onSignedOut: () => void;
+}
+
+export default function Admin({ storefrontName, email, welcome, onSignedOut }: Props) {
+  async function signOut() {
+    await logout();
+    onSignedOut();
+  }
+
+  return (
+    <Screen plain>
+      <TopBar
+        left={
+          <span className="storeid">
+            <img src="/brand/mark-tile.svg" width={24} height={24} alt="" />
+            <span className="storeid__col">
+              <span className="storeid__name">{storefrontName}</span>
+              <span className="storeid__sub">ecomm storefront</span>
+            </span>
+          </span>
+        }
+        right={<AccountChip email={email} onSignOut={signOut} />}
+      />
+      <main className="screen__main">
+        <div className="empty">
+          {welcome && (
+            <div style={{ marginBottom: 24, width: "100%" }}>
+              <Banner tone="info" title={welcome === "new" ? "Welcome to ecomm" : "Welcome back"}>
+                {welcome === "new"
+                  ? "A new account was created for this email."
+                  : "Signed in to your existing account."}
+              </Banner>
+            </div>
+          )}
+          <div className="empty__seal" aria-hidden="true">
+            <img src="/brand/mark-mono-gold.svg" width={36} height={36} alt="" />
+          </div>
+          <Eyebrow>Your storefront</Eyebrow>
+          <h1>{storefrontName}</h1>
+          <p className="empty__copy">
+            There's nothing to manage yet — and that's a finished state, not a missing one.
+            Catalog, orders, and settings will appear here as ecomm grows.
+          </p>
+        </div>
+      </main>
+    </Screen>
+  );
+}

frontend/src/screens/CreateStorefront.tsx

@@ -0,0 +1,92 @@
+// Create storefront (SD-0001 §5.3) — a storefront-less Merchant establishes their one
+// storefront (PUC-4/5; PUC-7 defense-in-depth on 409). Visuals per the ui/designs export
+// (hf-storefront). The welcome banner carries PUC-3's honest copy from the verify step.
+import { useState } from "react";
+import { createStorefront, logout, type StorefrontResult } from "../api";
+import { AccountChip, AuthCard, Banner, Eyebrow, Field, Footer, PrimaryButton, Screen, TopBar, Wordmark } from "../ui/kit";
+
+interface Props {
+  email: string;
+  welcome: "new" | "back" | null;
+  onCreated: (storefront: StorefrontResult) => void;
+  onAlreadyOwns: () => void;
+  onSignedOut: () => void;
+}
+
+export default function CreateStorefront({ email, welcome, onCreated, onAlreadyOwns, onSignedOut }: Props) {
+  const [name, setName] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [alreadyOwns, setAlreadyOwns] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function signOut() {
+    await logout();
+    onSignedOut();
+  }
+
+  async function submit(e: React.FormEvent) {
+    e.preventDefault();
+    setBusy(true);
+    setError(null);
+    const res = await createStorefront(name);
+    setBusy(false);
+    if (res.ok) {
+      onCreated(res.storefront);
+      return;
+    }
+    if (res.error.code === "already_owns_storefront") setAlreadyOwns(true);
+    else setError(res.error.message);
+  }
+
+  return (
+    <Screen horizon>
+      <TopBar left={<Wordmark size={22} />} right={<AccountChip email={email} onSignOut={signOut} />} />
+      <main className="screen__main">
+        <AuthCard>
+          <form onSubmit={submit} style={{ display: "contents" }}>
+            <div>
+              <Eyebrow>One storefront, fully yours</Eyebrow>
+              <h1 style={{ marginTop: 12 }}>Create your storefront</h1>
+              <p className="card__sub">
+                This is the one thing to do right now. It costs nothing and commits you to nothing.
+              </p>
+            </div>
+            {welcome && (
+              <Banner tone="info" title={welcome === "new" ? "Welcome to ecomm" : "Welcome back"}>
+                {welcome === "new"
+                  ? "A new account was created for this email."
+                  : "Signed in to your existing account."}
+              </Banner>
+            )}
+            {alreadyOwns && (
+              <Banner title="Your account already has its storefront">
+                ecomm is one storefront per account today.{" "}
+                <button type="button" className="lk" onClick={onAlreadyOwns}>
+                  Go to your admin →
+                </button>
+              </Banner>
+            )}
+            {error && <Banner title="That didn't work">{error} Try again.</Banner>}
+            <Field
+              label="Storefront name"
+              optional
+              helper="You can leave this blank — we'll pick a placeholder name you can change any time."
+              inputProps={{
+                type: "text",
+                value: name,
+                placeholder: "e.g. Ben's Bets",
+                autoFocus: true,
+                onChange: (ev) => setName(ev.target.value),
+              }}
+            />
+            <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+              <PrimaryButton busy={busy}>{busy ? "Creating…" : "Create storefront"}</PrimaryButton>
+              <p className="note">You can rename, configure, or close your storefront whenever you like.</p>
+            </div>
+          </form>
+        </AuthCard>
+      </main>
+      <Footer />
+    </Screen>
+  );
+}

frontend/src/screens/Landing.tsx

@@ -1,27 +1,61 @@
 // Landing (SD-0001 §5.1) — a Visitor learns what ecomm is and picks a door. Honest voice,
 // no trial/pricing/fee (corpus 14.01.0011). Both doors open the same sign-in flow (§5.2);
-// they differ only in framing.
+// they differ only in framing. Visuals per the ui/designs export (hf-landing, Direction A).
+import { Eyebrow, Footer, PrimaryButton, Screen, TopBar, Wordmark } from "../ui/kit";
+
 interface Props {
   onGetStarted: () => void;
   onLogIn: () => void;
 }
 
+const PROMISES: Array<[string, string]> = [
+  ["No trial clock", "Your storefront never expires or locks."],
+  ["No plan wall", "We take only what it takes to run."],
+  ["Your data, yours", "Nothing collected you didn't agree to give."],
+];
+
 export default function Landing({ onGetStarted, onLogIn }: Props) {
   return (
-    <main>
-      <header>
-        <strong>ecomm</strong>
-        <button type="button" onClick={onLogIn}>
+    <Screen horizon>
+      <TopBar
+        left={<Wordmark />}
+        right={
+          <button type="button" className="lk lk--nav" onClick={onLogIn}>
             Log in
           </button>
-      </header>
-      <section>
-        <h1>Honest commerce. Your storefront is yours.</h1>
-        <p>Sell online on a platform that treats you straight — no dark patterns, no lock-in.</p>
-        <button type="button" onClick={onGetStarted}>
-          Create your storefront
+        }
+      />
+      <main className="screen__main">
+        <div className="hero">
+          <Eyebrow>One storefront, fully yours</Eyebrow>
+          <h1>
+            Sell online,
+            <br />
+            <em>honestly.</em>
+          </h1>
+          <p className="hero__lead">
+            Claim the one storefront that's yours on a platform that takes only what it takes
+            to run — no trial countdown, no plan wall, no data you didn't agree to give.
+          </p>
+          <div className="hero__actions">
+            <PrimaryButton type="button" onClick={onGetStarted}>
+              Create your storefront →
+            </PrimaryButton>
+            <button type="button" className="lk lk--mute" onClick={onLogIn}>
+              Already selling with us? <span style={{ color: "var(--wv-lilac)" }}>Log in</span>
             </button>
-      </section>
+          </div>
+          <div className="promises">
+            {PROMISES.map(([title, copy]) => (
+              <div key={title}>
+                <div className="promises__title">{title}</div>
+                <p>{copy}</p>
+              </div>
+            ))}
+          </div>
+        </div>
       </main>
+      <Footer />
+    </Screen>
   );
 }

frontend/src/screens/SignIn.tsx

@@ -1,9 +1,11 @@
 // Sign in (SD-0001 §5.2) — the single email + one-time-code flow behind both doors. Step 1
-// requests a code; step 2 verifies it. Honest copy states which door framing applies and,
-// after verify, whether the account was created or resumed (PUC-3). storefront routing is
-// handled by App on success.
-import { useState } from "react";
-import { requestCode, verifyCode, type VerifyResult } from "../api";
+// requests a code; step 2 verifies it. Honest copy for every §5.2 state; storefront routing
+// is handled by App on success. Visuals per the ui/designs export (hf-signin).
+import { useEffect, useState } from "react";
+import { requestCode, verifyCode, type ApiError, type VerifyResult } from "../api";
+import { cooldownAppliesTo } from "../cooldown";
+import CodeInput from "../ui/CodeInput";
+import { AuthCard, Banner, Field, Footer, PrimaryButton, Screen, TopBar, Wordmark } from "../ui/kit";
 
 type Door = "signup" | "login";
 
@@ -13,99 +15,184 @@ interface Props {
   onBack: () => void;
 }
 
+function useCooldown(): [number, (s: number) => void] {
+  const [left, setLeft] = useState(0);
+  const ticking = left > 0;
+  useEffect(() => {
+    if (!ticking) return;
+    const t = setInterval(() => setLeft((v) => Math.max(0, v - 1)), 1000);
+    return () => clearInterval(t);
+  }, [ticking]);
+  return [left, setLeft];
+}
+
 export default function SignIn({ door, onAuthed, onBack }: Props) {
   const [step, setStep] = useState<"email" | "code">("email");
   const [email, setEmail] = useState("");
   const [code, setCode] = useState("");
   const [busy, setBusy] = useState(false);
-  const [error, setError] = useState<string | null>(null);
+  const [fieldError, setFieldError] = useState<string | null>(null);
+  const [codeError, setCodeError] = useState<string | null>(null);
+  const [bannerError, setBannerError] = useState<ApiError | null>(null);
+  const [cooldown, setCooldown] = useCooldown();
+  // The address the running cooldown belongs to — the server's cooldown is per-address
+  // (INV-3), so a different address must not be blocked by it (bug #20).
+  const [cooldownFor, setCooldownFor] = useState<string | null>(null);
 
-  const heading = door === "signup" ? "Create your storefront" : "Log in";
+  function applyError(err: ApiError) {
+    setFieldError(null);
+    setCodeError(null);
+    setBannerError(null);
+    if (err.code === "invalid_email") setFieldError(err.message);
+    else if (err.code === "resend_cooldown") setCooldown(err.retry_after_s ?? 60);
+    else if (err.code === "code_mismatch" || err.code === "code_expired") setCodeError(err.message);
+    else setBannerError(err); // delivery_failed, code_exhausted, unexpected
+  }
 
-  async function submitEmail(e: React.FormEvent) {
-    e.preventDefault();
+  async function sendCode(): Promise<boolean> {
     setBusy(true);
-    setError(null);
+    setFieldError(null);
+    setBannerError(null);
     const err = await requestCode(email);
     setBusy(false);
     if (err) {
-      setError(err.message);
-      return;
+      applyError(err);
+      if (err.code === "resend_cooldown") setCooldownFor(email);
+      return err.code === "resend_cooldown"; // a cooldown still means a code is out there
     }
+    setCooldown(60);
+    setCooldownFor(email);
+    return true;
+  }
+
+  async function submitEmail(e: React.FormEvent) {
+    e.preventDefault();
+    if (await sendCode()) {
+      setCode("");
+      setCodeError(null);
       setStep("code");
     }
+  }
+
+  async function resend() {
+    setCodeError(null);
+    setCode("");
+    await sendCode();
+  }
 
   async function submitCode(e: React.FormEvent) {
     e.preventDefault();
     setBusy(true);
-    setError(null);
+    setCodeError(null);
+    setBannerError(null);
     const res = await verifyCode(email, code);
     setBusy(false);
     if (!res.ok) {
-      setError(res.error.message);
+      applyError(res.error);
       return;
     }
     onAuthed(res.result);
   }
 
-  if (step === "email") {
-    return (
-      <main>
-        <header>
-          <strong>ecomm</strong>
-          <button type="button" onClick={onBack}>
-            Back
-          </button>
-        </header>
-        <form onSubmit={submitEmail}>
-          <h1>{heading}</h1>
-          <label>
-            Email
-            <input
-              type="email"
-              value={email}
-              autoFocus
-              required
-              onChange={(ev) => setEmail(ev.target.value)}
-            />
-          </label>
-          <p>We'll email you a one-time code. That's all we need.</p>
-          {error && <p role="alert">{error}</p>}
-          <button type="submit" disabled={busy}>
-            {busy ? "Sending…" : "Send code"}
-          </button>
-        </form>
-      </main>
-    );
-  }
+  const heading = door === "signup" ? "Create your storefront" : "Log in";
+  const sub =
+    door === "signup"
+      ? "Enter your email to begin. There's no password to create."
+      : "Enter your email and we'll send a one-time code to sign in.";
 
   return (
-    <main>
-      <header>
-        <strong>ecomm</strong>
-        <button type="button" onClick={() => setStep("email")}>
+    <Screen horizon>
+      <TopBar
+        left={<Wordmark size={22} />}
+        right={
+          <button type="button" className="lk lk--mute" onClick={onBack}>
+            ← Back
+          </button>
+        }
+      />
+      <main className="screen__main">
+        <AuthCard>
+          {step === "email" ? (
+            <form onSubmit={submitEmail} style={{ display: "contents" }}>
+              <div>
+                <h1>{heading}</h1>
+                <p className="card__sub">{sub}</p>
+              </div>
+              {bannerError && (
+                <Banner title="We couldn't send the code">
+                  The email didn't go out. Try again in a moment — nothing was lost.
+                </Banner>
+              )}
+              <Field
+                label="Email"
+                error={fieldError}
+                inputProps={{
+                  type: "email",
+                  value: email,
+                  placeholder: "you@example.com",
+                  autoFocus: true,
+                  required: true,
+                  autoComplete: "email",
+                  onChange: (ev) => setEmail(ev.target.value),
+                }}
+              />
+              <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+                <PrimaryButton busy={busy} disabled={cooldownAppliesTo(email, cooldownFor, cooldown)}>
+                  {busy
+                    ? "Sending…"
+                    : cooldownAppliesTo(email, cooldownFor, cooldown)
+                      ? `Resend in ${cooldown}s`
+                      : "Send code"}
+                </PrimaryButton>
+                <p className="note">
+                  We'll email you a one-time code. That's all we need — no password, ever.
+                </p>
+              </div>
+            </form>
+          ) : (
+            <form onSubmit={submitCode} style={{ display: "contents" }}>
+              <div>
+                <h1>Check your email</h1>
+                <p className="card__sub">
+                  We sent a 6-digit code to <span style={{ color: "var(--wv-starlight)" }}>{email}</span>.{" "}
+                  <button type="button" className="lk" onClick={() => setStep("email")}>
                     Wrong address?
                   </button>
-      </header>
-      <form onSubmit={submitCode}>
-        <h1>Enter your code</h1>
-        <p>We sent a code to {email}.</p>
-        <label>
-          Code
-          <input
-            inputMode="numeric"
-            autoComplete="one-time-code"
-            value={code}
-            autoFocus
-            required
-            onChange={(ev) => setCode(ev.target.value)}
-          />
-        </label>
-        {error && <p role="alert">{error}</p>}
-        <button type="submit" disabled={busy}>
-          {busy ? "Checking…" : "Continue"}
+                </p>
+              </div>
+              {bannerError && (
+                <Banner title={bannerError.code === "code_exhausted" ? "Too many attempts" : "Something went wrong"}>
+                  {bannerError.code === "code_exhausted"
+                    ? "That code is no longer valid. Request a fresh one to keep going."
+                    : bannerError.message}
+                </Banner>
+              )}
+              <div style={{ display: "flex", flexDirection: "column", gap: 10 }}>
+                <CodeInput value={code} onChange={setCode} error={!!codeError} />
+                {codeError && (
+                  <p className="note note--attn" role="alert">
+                    {codeError}
+                  </p>
+                )}
+              </div>
+              <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+                <PrimaryButton busy={busy}>{busy ? "Checking…" : "Continue"}</PrimaryButton>
+                <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center" }}>
+                  <p className="note">Good for 10 minutes.</p>
+                  {cooldown > 0 ? (
+                    <span className="note">Resend in {cooldown}s</span>
+                  ) : (
+                    <button type="button" className="lk" onClick={resend}>
+                      Resend code
                     </button>
+                  )}
+                </div>
+              </div>
             </form>
+          )}
+        </AuthCard>
       </main>
+      <Footer />
+    </Screen>
   );
 }

frontend/src/screens/SignedIn.tsx

@@ -1,34 +0,0 @@
-// SLICE-2 placeholder for the signed-in surfaces (create-storefront, admin) that land in
-// SLICE-3. It honestly states what's next and makes PUC-9 sign-out reachable now. No
-// fabricated capability (INV-9).
-import { logout } from "../api";
-
-interface Props {
-  email: string;
-  created: boolean;
-  onSignedOut: () => void;
-}
-
-export default function SignedIn({ email, created, onSignedOut }: Props) {
-  async function signOut() {
-    await logout();
-    onSignedOut();
-  }
-
-  return (
-    <main>
-      <header>
-        <strong>ecomm</strong>
-        <span>{email}</span>
-        <button type="button" onClick={signOut}>
-          Sign out
-        </button>
-      </header>
-      <section>
-        <h1>{created ? "Welcome to ecomm" : "Welcome back"}</h1>
-        <p>You're signed in as {email}.</p>
-        <p>Creating your storefront arrives in the next slice. Nothing else is needed yet.</p>
-      </section>
-    </main>
-  );
-}

frontend/src/styles/app.css

@@ -0,0 +1,394 @@
+/* ecomm app chrome — the hf-kit primitives (Direction A · Quiet centered) as CSS.
+   Depth = layered surfaces + hairlines; hover = small lift, no new shadows. */
+
+* { box-sizing: border-box; }
+
+html, body, #root { height: 100%; }
+
+body {
+  margin: 0;
+  background: var(--wv-midnight);
+  color: var(--wv-starlight);
+  font-family: var(--wv-font-body);
+  -webkit-font-smoothing: antialiased;
+}
+
+/* ── screen ground: barely-there starfield + optional gold horizon ─────────── */
+.screen {
+  min-height: 100%;
+  display: flex;
+  flex-direction: column;
+  position: relative;
+  background:
+    radial-gradient(1.3px 1.3px at 16% 22%, rgba(237, 234, 255, .34), transparent),
+    radial-gradient(1.2px 1.2px at 78% 14%, rgba(237, 234, 255, .22), transparent),
+    radial-gradient(1.1px 1.1px at 88% 46%, rgba(155, 140, 255, .30), transparent),
+    radial-gradient(1.3px 1.3px at 30% 72%, rgba(237, 234, 255, .24), transparent),
+    radial-gradient(1.1px 1.1px at 62% 86%, rgba(237, 234, 255, .18), transparent),
+    radial-gradient(1.2px 1.2px at 7% 56%, rgba(155, 140, 255, .26), transparent),
+    var(--wv-midnight);
+}
+.screen--horizon {
+  background:
+    radial-gradient(120% 70% at 50% 142%, rgba(244, 199, 107, .16) 0%, rgba(244, 199, 107, .05) 38%, transparent 64%),
+    radial-gradient(1.3px 1.3px at 16% 22%, rgba(237, 234, 255, .34), transparent),
+    radial-gradient(1.2px 1.2px at 78% 14%, rgba(237, 234, 255, .22), transparent),
+    radial-gradient(1.1px 1.1px at 88% 46%, rgba(155, 140, 255, .30), transparent),
+    radial-gradient(1.3px 1.3px at 30% 72%, rgba(237, 234, 255, .24), transparent),
+    radial-gradient(1.1px 1.1px at 62% 86%, rgba(237, 234, 255, .18), transparent),
+    radial-gradient(1.2px 1.2px at 7% 56%, rgba(155, 140, 255, .26), transparent),
+    var(--wv-midnight);
+}
+.screen--plain { background: var(--wv-midnight); }
+
+.screen__main {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: 32px 24px;
+}
+
+/* ── top bar: glass chrome ──────────────────────────────────────────────────── */
+.topbar {
+  flex: 0 0 auto;
+  height: 68px;
+  padding: 0 36px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  border-bottom: 1px solid var(--border-soft);
+  background: var(--glass-sky);
+  backdrop-filter: blur(var(--glass-blur));
+  position: relative;
+  z-index: 5;
+}
+.topbar__side { display: flex; align-items: center; gap: 16px; min-width: 0; }
+
+/* ── wordmark ───────────────────────────────────────────────────────────────── */
+.wordmark { display: inline-flex; align-items: center; gap: 10px; }
+.wordmark img { display: block; border-radius: 6px; }
+.wordmark__name {
+  font-family: var(--wv-font-display);
+  font-weight: var(--weight-bold);
+  font-size: 22px;
+  letter-spacing: var(--tracking-display);
+  color: var(--wv-starlight);
+}
+
+/* ── links & text buttons ───────────────────────────────────────────────────── */
+.lk {
+  color: var(--wv-lilac);
+  text-decoration: none;
+  background: none;
+  border: none;
+  padding: 0;
+  font: inherit;
+  cursor: pointer;
+  transition: color var(--dur-fast) var(--ease);
+}
+.lk:hover { color: var(--wv-gold); }
+.lk--mute { color: var(--text-on-dark-mute); }
+.lk--nav {
+  font-family: var(--wv-font-display);
+  font-weight: var(--weight-medium);
+  font-size: 14px;
+  color: var(--wv-starlight);
+}
+
+.signout {
+  font-family: var(--wv-font-display);
+  font-weight: var(--weight-medium);
+  font-size: 14px;
+  color: var(--wv-starlight);
+  background: transparent;
+  border: none;
+  cursor: pointer;
+  padding: 0;
+  transition: color var(--dur-fast) var(--ease);
+}
+.signout:hover { color: var(--wv-gold); }
+
+/* ── account chip (top-bar right, signed in) ────────────────────────────────── */
+.chip { display: flex; align-items: center; gap: 14px; min-width: 0; }
+.chip__avatar {
+  width: 30px;
+  height: 30px;
+  border-radius: 15px;
+  background: var(--wv-lilac-16);
+  border: 1px solid var(--border-card);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-family: var(--wv-font-display);
+  font-weight: var(--weight-bold);
+  font-size: 13px;
+  flex: 0 0 auto;
+}
+.chip__email {
+  font-size: 14px;
+  color: var(--text-on-dark-soft);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.chip__divider { width: 1px; height: 18px; background: var(--border-soft); flex: 0 0 auto; }
+
+/* ── eyebrow ────────────────────────────────────────────────────────────────── */
+.eyebrow {
+  font-family: var(--wv-font-display);
+  font-weight: var(--weight-medium);
+  font-size: var(--text-eyebrow);
+  letter-spacing: var(--tracking-eyebrow);
+  text-transform: uppercase;
+  color: var(--wv-lilac);
+  margin: 0;
+}
+
+/* ── auth card — the one surface with a real shadow ─────────────────────────── */
+.card {
+  width: 440px;
+  max-width: 100%;
+  background: var(--surface-raised);
+  border: 1px solid var(--border-card);
+  border-radius: var(--radius-card);
+  padding: 40px 40px 34px;
+  display: flex;
+  flex-direction: column;
+  gap: 22px;
+  box-shadow: var(--shadow-soft);
+  position: relative;
+  z-index: 2;
+}
+.card h1 {
+  font-family: var(--wv-font-display);
+  font-weight: var(--weight-bold);
+  letter-spacing: var(--tracking-display);
+  font-size: 27px;
+  line-height: 1.08;
+  margin: 0 0 9px;
+}
+.card__sub { font-size: 14.5px; line-height: 1.55; color: var(--text-on-dark-soft); margin: 0; }
+
+/* ── fields ─────────────────────────────────────────────────────────────────── */
+.field { display: flex; flex-direction: column; gap: 8px; }
+.field__label {
+  font-weight: var(--weight-medium);
+  font-size: 13.5px;
+  color: var(--text-on-dark-soft);
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+}
+.field__optional { font-size: 12.5px; color: var(--text-on-dark-mute); font-weight: var(--weight-regular); }
+.field__input {
+  height: 52px;
+  border-radius: 10px;
+  padding: 0 16px;
+  background: rgba(237, 234, 255, .035);
+  border: 1.5px solid var(--border-soft);
+  font-family: var(--wv-font-body);
+  font-size: 16px;
+  color: var(--wv-starlight);
+  width: 100%;
+  transition: border-color var(--dur-fast) var(--ease), box-shadow var(--dur-fast) var(--ease);
+}
+.field__input::placeholder { color: var(--text-on-dark-mute); }
+.field__input:hover { border-color: var(--border-strong); }
+.field__input:focus {
+  outline: none;
+  border-color: var(--wv-gold);
+  box-shadow: 0 0 0 3px var(--wv-gold-28);
+  background: rgba(237, 234, 255, .06);
+}
+.field__input--error { border-color: var(--wv-gold); }
+
+.note { font-size: 13px; line-height: 1.45; color: var(--text-on-dark-mute); margin: 0; }
+.note--attn { color: var(--wv-gold); display: flex; gap: 7px; align-items: baseline; }
+.note--attn::before { content: "◆"; font-size: 11px; }
+
+/* ── primary button: gold pill ──────────────────────────────────────────────── */
+.btn-primary {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: .4em;
+  width: 100%;
+  font-family: var(--wv-font-display);
+  font-weight: var(--weight-medium);
+  font-size: 15.5px;
+  line-height: 1;
+  padding: .85rem 1.4rem;
+  border-radius: var(--radius-pill);
+  border: var(--btn-border-w) solid transparent;
+  background: var(--cta);
+  color: var(--cta-text);
+  cursor: pointer;
+  transition: transform var(--dur-fast) var(--ease), background var(--dur-fast) var(--ease);
+}
+.btn-primary:hover:not(:disabled) { background: var(--cta-hover); transform: var(--lift-1); }
+.btn-primary:disabled { opacity: .5; cursor: not-allowed; }
+.btn-primary--auto { width: auto; }
+.btn-primary:focus-visible { outline: 2px solid var(--focus-ring); outline-offset: 2px; }
+
+/* ── banner: gold attention / lilac info (no red in the palette) ────────────── */
+.banner {
+  display: flex;
+  gap: 12px;
+  padding: 14px 16px;
+  border-radius: 12px;
+  align-items: flex-start;
+  font-size: 14px;
+  line-height: 1.5;
+  color: var(--text-on-dark-soft);
+  text-align: left;
+}
+.banner--attn { background: rgba(244, 199, 107, .10); border: 1px solid var(--wv-gold-40); }
+.banner--info { background: var(--wv-lilac-08); border: 1px solid var(--wv-lilac-18); }
+.banner__icon { font-size: 13px; line-height: 22px; flex: 0 0 auto; }
+.banner--attn .banner__icon { color: var(--wv-gold); }
+.banner--info .banner__icon { color: var(--wv-lilac); }
+.banner__title { color: var(--wv-starlight); font-weight: var(--weight-semibold); margin-bottom: 2px; }
+
+/* ── code input: 6 cells over one invisible input ───────────────────────────── */
+.code { position: relative; display: flex; gap: 11px; justify-content: center; }
+.code__hidden {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  opacity: 0;
+  border: none;
+  font-size: 16px;
+  cursor: pointer;
+}
+.code__cell {
+  width: 52px;
+  height: 64px;
+  border-radius: 11px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: rgba(237, 234, 255, .035);
+  border: 1.5px solid var(--border-soft);
+  font-family: var(--wv-font-display);
+  font-weight: var(--weight-medium);
+  font-size: 26px;
+  transition: border-color var(--dur-fast) var(--ease), box-shadow var(--dur-fast) var(--ease);
+}
+.code--focus .code__cell--active {
+  border-color: var(--wv-gold);
+  box-shadow: 0 0 0 3px var(--wv-gold-28);
+}
+.code--error .code__cell { border-color: var(--wv-gold); }
+
+/* ── footer ─────────────────────────────────────────────────────────────────── */
+.footer {
+  flex: 0 0 auto;
+  padding: 20px 36px;
+  border-top: 1px solid var(--border-soft);
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 16px;
+  font-size: 12.5px;
+  color: var(--text-on-dark-mute);
+  background: rgba(9, 12, 34, .4);
+}
+.footer__id { display: inline-flex; align-items: center; gap: 9px; }
+.footer__id img { opacity: .85; }
+
+/* ── landing ────────────────────────────────────────────────────────────────── */
+.hero { max-width: 680px; display: flex; flex-direction: column; align-items: center; text-align: center; }
+.hero h1 {
+  font-family: var(--wv-font-display);
+  font-weight: var(--weight-bold);
+  letter-spacing: -0.02em;
+  line-height: 1.02;
+  font-size: clamp(36px, 6.5vw, 62px);
+  margin: 20px 0 22px;
+}
+.hero h1 em { font-style: normal; color: var(--wv-gold); }
+.hero__lead {
+  font-size: clamp(15.5px, 1.8vw, 18.5px);
+  line-height: 1.6;
+  color: var(--text-on-dark-soft);
+  max-width: 520px;
+  margin: 0 0 32px;
+  text-wrap: pretty;
+}
+.hero__actions { display: flex; gap: 14px; align-items: center; flex-wrap: wrap; justify-content: center; }
+.hero__actions .btn-primary { width: auto; }
+
+.promises {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  width: 100%;
+  margin-top: 44px;
+  border-top: 1px solid var(--border-soft);
+  padding-top: 24px;
+  text-align: left;
+}
+.promises > div { padding: 0 22px; }
+.promises > div + div { border-left: 1px solid var(--border-soft); }
+.promises__title {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-bottom: 5px;
+  font-family: var(--wv-font-display);
+  font-weight: var(--weight-medium);
+  font-size: 14.5px;
+}
+.promises__title::before { content: "◆"; color: var(--wv-gold); font-size: 10px; }
+.promises p { font-size: 13px; line-height: 1.5; color: var(--text-on-dark-mute); margin: 0; }
+
+/* ── admin shell ────────────────────────────────────────────────────────────── */
+.storeid { display: inline-flex; align-items: center; gap: 11px; min-width: 0; }
+.storeid img { display: block; border-radius: 7px; flex: 0 0 auto; }
+.storeid__col { display: inline-flex; flex-direction: column; line-height: 1.12; min-width: 0; }
+.storeid__name {
+  font-family: var(--wv-font-display);
+  font-weight: var(--weight-bold);
+  font-size: 17px;
+  letter-spacing: -0.01em;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.storeid__sub { font-size: 11px; color: var(--text-on-dark-mute); }
+
+.empty { display: flex; flex-direction: column; align-items: center; text-align: center; max-width: 560px; }
+.empty__seal {
+  width: 76px;
+  height: 76px;
+  border-radius: 50%;
+  border: 1px solid var(--border-card);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  margin-bottom: 26px;
+  background: var(--wv-lilac-08);
+}
+.empty h1 {
+  font-family: var(--wv-font-display);
+  font-weight: var(--weight-bold);
+  letter-spacing: var(--tracking-display);
+  line-height: 1.04;
+  font-size: clamp(30px, 4.5vw, 42px);
+  margin: 12px 0 16px;
+}
+.empty__copy { font-size: 17px; line-height: 1.6; color: var(--text-on-dark-soft); max-width: 460px; margin: 0; text-wrap: pretty; }
+
+/* ── small screens ──────────────────────────────────────────────────────────── */
+@media (max-width: 720px) {
+  .topbar { padding: 0 20px; }
+  .footer { padding: 16px 20px; flex-direction: column; }
+  .card { padding: 28px 22px 24px; }
+  .promises { grid-template-columns: 1fr; gap: 14px; }
+  .promises > div { padding: 0; }
+  .promises > div + div { border-left: none; }
+  .code__cell { width: 44px; height: 56px; font-size: 22px; }
+}

frontend/src/styles/fonts.css

@@ -0,0 +1,37 @@
+/* Wiggleverse webfonts (from the design-system export) — Space Grotesk (display) +
+   Inter (body/UI). Fraunces (human register) deliberately omitted: no screen uses it yet. */
+@font-face {
+  font-family: "Space Grotesk";
+  font-style: normal;
+  font-weight: 500;
+  font-display: swap;
+  src: url("/fonts/space-grotesk-v22-latin-500.woff2") format("woff2");
+}
+@font-face {
+  font-family: "Space Grotesk";
+  font-style: normal;
+  font-weight: 700;
+  font-display: swap;
+  src: url("/fonts/space-grotesk-v22-latin-700.woff2") format("woff2");
+}
+@font-face {
+  font-family: "Inter";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url("/fonts/inter-v20-latin-regular.woff2") format("woff2");
+}
+@font-face {
+  font-family: "Inter";
+  font-style: normal;
+  font-weight: 500;
+  font-display: swap;
+  src: url("/fonts/inter-v20-latin-500.woff2") format("woff2");
+}
+@font-face {
+  font-family: "Inter";
+  font-style: normal;
+  font-weight: 600;
+  font-display: swap;
+  src: url("/fonts/inter-v20-latin-600.woff2") format("woff2");
+}

frontend/src/styles/index.css

@@ -0,0 +1,7 @@
+/* Global style entry point — Wiggleverse design-system tokens (copied from the
+   ui/designs export) + the ecomm app chrome built on them. */
+@import "./fonts.css";
+@import "./tokens-colors.css";
+@import "./tokens-typography.css";
+@import "./tokens-spacing.css";
+@import "./app.css";

frontend/src/styles/tokens-colors.css

@@ -0,0 +1,60 @@
+/* Wiggleverse — Color tokens
+   Source of truth: wiggleverse-www/assets/tokens.css (brand BRAND.md §8–9).
+   Dark "sky" is the primary ground; Paper is for long reading. No-center motif. */
+
+:root {
+  /* ---- Brand palette (base values) ---- */
+  --wv-midnight: #0E1230;   /* sky / ground — primary dark background */
+  --wv-indigo:   #1C2150;   /* raised surfaces on dark (cards, mobile nav) */
+  --wv-indigo-2: #232A63;   /* hover state for raised surfaces */
+  --wv-lilac:    #9B8CFF;   /* accent — "the bonds between us"; links, nodes */
+  --wv-violet:   #7C6FE0;   /* secondary links / strokes (on light) */
+  --wv-gold:     #F4C76B;   /* warmth / horizon / primary CTAs */
+  --wv-gold-hi:  #F7D488;   /* gold hover */
+  --wv-starlight:#EDEAFF;   /* nodes / text on dark */
+  --wv-paper:    #F6F4FB;   /* light-mode background */
+  --wv-ink:      #3B2F7A;   /* text on light */
+  --wv-night:    #090C22;   /* footer / deepest ground */
+
+  /* CTA text-on-gold (very dark gold-brown, not pure black) */
+  --wv-gold-ink: #2A2003;
+  --wv-gold-ink-soft: #6B4E10; /* "soon" tag text on gold tint */
+
+  /* ---- Alpha derivations (lilac / gold / starlight washes) ---- */
+  --wv-lilac-08:  rgba(155, 140, 255, .08);
+  --wv-lilac-12:  rgba(155, 140, 255, .12);
+  --wv-lilac-16:  rgba(155, 140, 255, .16);
+  --wv-lilac-18:  rgba(155, 140, 255, .18);
+  --wv-lilac-32:  rgba(155, 140, 255, .32);
+  --wv-gold-28:   rgba(244, 199, 107, .28);
+  --wv-gold-40:   rgba(244, 199, 107, .40);
+  --wv-starlight-85: rgba(237, 234, 255, .85);
+  --wv-starlight-78: rgba(237, 234, 255, .78);
+  --wv-starlight-60: rgba(237, 234, 255, .60);
+  --wv-starlight-55: rgba(237, 234, 255, .55);
+
+  /* ---- Semantic aliases ---- */
+  --surface-sky:       var(--wv-midnight);  /* page ground (dark) */
+  --surface-raised:    var(--wv-indigo);    /* cards / panels on dark */
+  --surface-raised-hi: var(--wv-indigo-2);  /* raised hover */
+  --surface-paper:     var(--wv-paper);     /* long-reading light sections */
+  --surface-card-light:#FFFFFF;             /* build-cards on paper */
+  --surface-footer:    var(--wv-night);
+
+  --text-on-dark:      var(--wv-starlight);
+  --text-on-dark-soft: var(--wv-starlight-78);
+  --text-on-dark-mute: var(--wv-starlight-60);
+  --text-on-light:     var(--wv-ink);
+  --text-on-light-soft:#4B4170;
+
+  --accent:            var(--wv-lilac);     /* links + nodes on dark */
+  --accent-on-light:   var(--wv-violet);    /* links + strokes on light */
+  --cta:               var(--wv-gold);      /* primary action / horizon */
+  --cta-hover:         var(--wv-gold-hi);
+  --cta-text:          var(--wv-gold-ink);
+
+  --border-soft:       var(--wv-lilac-16);  /* hairlines on dark */
+  --border-card:       var(--wv-lilac-18);
+  --border-strong:     var(--wv-lilac-32);
+  --focus-ring:        var(--wv-gold);
+}

frontend/src/styles/tokens-spacing.css

@@ -0,0 +1,55 @@
+/* Wiggleverse — Spacing, radius, shadow, layout & motion tokens
+   Derived from the marketing-site CSS. The brand has almost no shadow system —
+   depth is carried by surface color + hairline borders, not drop shadows. */
+
+:root {
+  /* ---- Spacing scale (rem) ---- */
+  --space-0: 0;
+  --space-1: .25rem;
+  --space-2: .5rem;
+  --space-3: .7rem;
+  --space-4: 1rem;
+  --space-5: 1.2rem;
+  --space-6: 1.6rem;
+  --space-8: 2rem;
+  --space-10: 2.5rem;
+  --space-12: 3rem;
+
+  /* Section rhythm — fluid vertical padding for page bands */
+  --section-pad: clamp(3rem, 7vw, 5.5rem);
+  --page-hero-pad: clamp(2.8rem, 6vw, 4.5rem);
+
+  /* ---- Layout ---- */
+  --wrap-max: 1080px;     /* content column */
+  --wrap-gutter: 92vw;    /* width: min(--wrap-max, --wrap-gutter) */
+  --measure-prose: 68ch;  /* reading measure for prose blocks */
+
+  /* ---- Radii ---- */
+  --radius-card: 14px;    /* path-cards, build-cards */
+  --radius-panel: 12px;   /* principle tiles */
+  --radius-sm: 4px;       /* focus ring rounding */
+  --radius-pill: 999px;   /* buttons, tags, notices */
+  --radius-mark: 26px;    /* favicon tile rounding */
+
+  /* ---- Borders ---- */
+  --border-hair: 1px;     /* default hairline */
+  --border-card-w: 1px;
+  --btn-border-w: 1.5px;  /* ghost button / focus weight */
+
+  /* ---- Elevation ---- *
+   * The system avoids drop shadows. "Lift" on hover is a -1 to -3px translateY,
+   * not a shadow. These tokens exist for the rare card that needs real elevation. */
+  --shadow-none: none;
+  --shadow-soft: 0 8px 24px rgba(9, 12, 34, .28);
+  --lift-1: translateY(-1px); /* @kind other */ /* buttons */
+  --lift-3: translateY(-3px); /* @kind other */ /* cards */
+
+  /* ---- Glass (sticky header) ---- */
+  --glass-sky: rgba(14, 18, 48, .82);
+  --glass-blur: 10px;
+
+  /* ---- Motion ---- */
+  --ease: ease; /* @kind other */
+  --dur-fast: .15s; /* @kind other */ /* hover / press transitions */
+  --dur-mid: .25s; /* @kind other */ /* mobile nav reveal */
+}

frontend/src/styles/tokens-typography.css

@@ -0,0 +1,53 @@
+/* Wiggleverse — Typography tokens
+   Two registers, one meaning (BRAND.md):
+   • Machine register — Space Grotesk (display) + Inter (body/UI): precise, structural.
+   • Human register   — Fraunces, ITALIC ONLY: warm, literary, used sparingly
+                         for the lines that carry conscience ("the soul").
+   @font-face rules live in assets/fonts/fonts.css. */
+
+:root {
+  /* ---- Families ---- */
+  --wv-font-display: 'Space Grotesk', system-ui, sans-serif; /* headings, wordmark */
+  --wv-font-body:    'Inter', system-ui, sans-serif;          /* body / UI */
+  --wv-font-human:   'Fraunces', Georgia, serif;              /* pull-quotes — italic only */
+
+  /* semantic aliases */
+  --font-display: var(--wv-font-display);
+  --font-body:    var(--wv-font-body);
+  --font-soul:    var(--wv-font-human);
+
+  /* ---- Weights ---- */
+  --weight-regular: 400;  /* Inter body */
+  --weight-medium:  500;  /* nav, eyebrows, buttons, Space Grotesk text */
+  --weight-semibold:600;  /* Inter emphasis, ledger totals */
+  --weight-bold:    700;  /* Space Grotesk headings, wordmark */
+  --weight-soul:    500;  /* Fraunces italic pull-quotes */
+
+  /* ---- Fluid display sizes (clamp: min, vw, max) ---- */
+  --text-h1:   clamp(2.1rem, 5.2vw, 3.6rem);
+  --text-h2:   clamp(1.6rem, 3.4vw, 2.4rem);
+  --text-h3:   1.2rem;
+  --text-lead: clamp(1.05rem, 1.8vw, 1.3rem);  /* intro paragraph */
+  --text-soul: clamp(1.2rem, 2.4vw, 1.7rem);   /* hero pull-quote */
+
+  /* ---- Body / UI scale ---- */
+  --text-body:    1rem;     /* 16px base */
+  --text-small:   .95rem;
+  --text-fine:    .92rem;
+  --text-eyebrow: .8rem;    /* uppercase label */
+  --text-tag:     .72rem;   /* pill tags */
+
+  /* ---- Line heights ---- */
+  --leading-tight: 1.12;   /* headings */
+  --leading-body:  1.6;    /* paragraphs */
+
+  /* ---- Letter spacing ---- */
+  --tracking-display: -0.015em; /* headings + wordmark draw in slightly */
+  --tracking-eyebrow:  0.12em;  /* uppercase eyebrows open up */
+  --tracking-tag:      0.08em;
+  --tracking-notice:   0.06em;
+
+  /* ---- Measure ---- */
+  --measure-lead: 60ch;
+  --measure-prose:68ch;
+}

frontend/src/ui/CodeInput.tsx

@@ -0,0 +1,46 @@
+// Six-cell one-time-code input: one real <input> (invisible, full-bleed) carries the value
+// and the OTC autofill semantics; the cells are presentation. Click anywhere to focus;
+// paste works because the input is real.
+import { useState } from "react";
+
+const LENGTH = 6;
+
+export default function CodeInput({
+  value,
+  onChange,
+  error = false,
+}: {
+  value: string;
+  onChange: (code: string) => void;
+  error?: boolean;
+}) {
+  const [focused, setFocused] = useState(false);
+  const digits = value.slice(0, LENGTH).split("");
+  const active = Math.min(digits.length, LENGTH - 1);
+
+  return (
+    <div className={`code${focused ? " code--focus" : ""}${error ? " code--error" : ""}`}>
+      <input
+        className="code__hidden"
+        value={value}
+        inputMode="numeric"
+        autoComplete="one-time-code"
+        aria-label="One-time code"
+        autoFocus
+        maxLength={LENGTH}
+        onFocus={() => setFocused(true)}
+        onBlur={() => setFocused(false)}
+        onChange={(ev) => onChange(ev.target.value.replace(/\D/g, "").slice(0, LENGTH))}
+      />
+      {Array.from({ length: LENGTH }, (_, i) => (
+        <span
+          key={i}
+          aria-hidden="true"
+          className={`code__cell${i === active && focused ? " code__cell--active" : ""}`}
+        >
+          {digits[i] ?? ""}
+        </span>
+      ))}
+    </div>
+  );
+}

frontend/src/ui/kit.tsx

@@ -0,0 +1,150 @@
+// The ecomm UI kit — React faces of the app.css primitives, matching the Claude Design
+// export (ui/designs/ecomm-login-and-create-storefront-designs, hf-kit). Presentation
+// only: no business rules live here (§6.2 — the SPA renders what the BFF returns).
+import { useId } from "react";
+import type { ReactNode } from "react";
+
+export function Screen({
+  children,
+  horizon = false,
+  plain = false,
+}: {
+  children: ReactNode;
+  horizon?: boolean;
+  plain?: boolean;
+}) {
+  const cls = plain ? "screen screen--plain" : horizon ? "screen screen--horizon" : "screen";
+  return <div className={cls}>{children}</div>;
+}
+
+export function TopBar({ left, right }: { left: ReactNode; right?: ReactNode }) {
+  return (
+    <header className="topbar">
+      <div className="topbar__side">{left}</div>
+      <div className="topbar__side">{right}</div>
+    </header>
+  );
+}
+
+export function Wordmark({ size = 26 }: { size?: number }) {
+  return (
+    <span className="wordmark">
+      <img src="/brand/mark-tile.svg" width={size} height={size} alt="" />
+      <span className="wordmark__name" style={{ fontSize: size * 0.86 }}>
+        ecomm
+      </span>
+    </span>
+  );
+}
+
+export function Footer() {
+  return (
+    <footer className="footer">
+      <span className="footer__id">
+        <img src="/brand/mark-mono-gold.svg" width={16} height={16} alt="" />
+        ecomm · a Wiggleverse line
+      </span>
+    </footer>
+  );
+}
+
+export function AuthCard({ children }: { children: ReactNode }) {
+  return <div className="card">{children}</div>;
+}
+
+export function Eyebrow({ children }: { children: ReactNode }) {
+  return <p className="eyebrow">{children}</p>;
+}
+
+export function Banner({
+  tone = "attn",
+  title,
+  children,
+}: {
+  tone?: "attn" | "info";
+  title?: string;
+  children: ReactNode;
+}) {
+  return (
+    <div className={`banner banner--${tone}`} role={tone === "attn" ? "alert" : "status"}>
+      <span className="banner__icon" aria-hidden="true">
+        {tone === "attn" ? "◆" : "◇"}
+      </span>
+      <div>
+        {title && <div className="banner__title">{title}</div>}
+        {children}
+      </div>
+    </div>
+  );
+}
+
+export function PrimaryButton({
+  children,
+  busy = false,
+  disabled = false,
+  type = "submit",
+  onClick,
+}: {
+  children: ReactNode;
+  busy?: boolean;
+  disabled?: boolean;
+  type?: "submit" | "button";
+  onClick?: () => void;
+}) {
+  return (
+    <button className="btn-primary" type={type} disabled={disabled || busy} onClick={onClick}>
+      {children}
+    </button>
+  );
+}
+
+export function Field({
+  label,
+  optional = false,
+  error,
+  helper,
+  inputProps,
+}: {
+  label: string;
+  optional?: boolean;
+  error?: string | null;
+  helper?: string;
+  inputProps: React.InputHTMLAttributes<HTMLInputElement>;
+}) {
+  const id = useId();
+  return (
+    <div className="field">
+      <label className="field__label" htmlFor={id}>
+        <span>{label}</span>
+        {optional && <span className="field__optional">optional</span>}
+      </label>
+      <input
+        id={id}
+        className={`field__input${error ? " field__input--error" : ""}`}
+        aria-invalid={!!error}
+        {...inputProps}
+      />
+      {error && (
+        <p className="note note--attn" role="alert">
+          {error}
+        </p>
+      )}
+      {helper && !error && <p className="note">{helper}</p>}
+    </div>
+  );
+}
+
+export function AccountChip({ email, onSignOut }: { email: string; onSignOut: () => void }) {
+  return (
+    <div className="chip">
+      <span className="chip__avatar" aria-hidden="true">
+        {email[0]?.toUpperCase()}
+      </span>
+      <span className="chip__email">{email}</span>
+      <span className="chip__divider" aria-hidden="true" />
+      <button type="button" className="signout" onClick={onSignOut}>
+        Sign out
+      </button>
+    </div>
+  );
+}