create-ailk 0.1.0 → 0.2.0

package/templates/.claude/skills/scaffold-commerce/SKILL.md

@@ -252,6 +252,437 @@ Print:
 - Pointer at `scaffold-page` (#362) for wiring pricing UI.
 - Reminder: sandbox-only at v1. Live keys are hook-blocked globally.
 
+### Step 10 — Surface-selection branch (`feature:commerce` only, FEAT-023 U1)
+
+This step is **additive** — it runs after Step 9's closing summary and
+never changes anything above it. A site without the `commerce`
+entitlement gets exactly today's flow (Steps 1–9) and stops there.
+
+**10a — Fail-closed entitlement check.** Determine whether this site is
+entitled to `feature:commerce` (the license-manifest feature added in
+FEAT-023 U1 — `commerce` is included in the `pro` / `pro_plus` /
+`enterprise` tiers, absent from `free`):
+
+- If the consumer's project has a resolvable license — a
+  `WT_LICENSE_KEY` (or equivalent) env var resolving to a
+  `@working-theory/license` `License` — call
+  `hasFeature("commerce", license)` (`@working-theory/license-client`,
+  static-mode: sync, no network). `true` → entitled; proceed to 10b.
+- **Any other case is NOT entitled — fail closed:** no license
+  configured, the license lacks `commerce`, or `hasFeature` throws.
+  Do nothing further. The consumer already has the full link path +
+  product-creation flow from Steps 1–9; there is no additional
+  action or message needed.
+
+Do not attempt to determine entitlement by asking the consumer their
+plan conversationally — the check is against the resolved license, not
+a verbal claim.
+
+**10b — Offer the surface-selection branch.** For an entitled site,
+ask:
+
+> "Want to scaffold a payment surface for these products? Pick one (or
+> 'skip' for now):
+>
+> - **Checkout** — a hosted or embedded checkout flow (one-time or
+>   subscription).
+> - **Pay-by-link** — a shareable payment link, no page to build.
+> - **Invoice** — send + track invoices with a status badge.
+> - **Subscription** — recurring billing with a status badge.
+> - **Portal** — a self-serve billing-management page for customers."
+
+**10c — Re-run the live-key check.** Before dispatching to any surface
+scaffolder, re-run Step 1's live-key check (env scan + paste
+detection) — belt-and-suspenders, since surface scaffolding may run in
+a session well after the original product-creation pass.
+
+**10d — Instantiate the shared config.** Copy
+`templates/stripe-config.template.ts` into the consumer's `apps/api`
+(or the surface's own route directory) as the shared
+`loadStripeSurfaceConfig()` the surface's route handler calls at
+request time. This carries the test-mode-only guard
+(`assertSandboxKey`, `@working-theory/stripe-client`) into the new
+surface entry point — the same belt-and-suspenders guard
+`getStripeClient()` already applies, so a live key is refused here too,
+not only at the shared Stripe client singleton.
+
+**10e — Dispatch to the matching surface scaffolder.** **Checkout
+(one-time)** (10e-i, FEAT-023 U2), **Pay by link** (10e-ii, FEAT-023 U3),
+**Invoice** (10g, FEAT-023 U4), **Subscription** (10h, FEAT-023 U5), and
+**Portal** (10i, FEAT-023 U6) are all available inline. If a future choice's
+matching skill is not installed, say so plainly:
+
+> "Payment-surface scaffolding for `<choice>` isn't available in this
+> AILK version yet — the foundation (entitlement gate + shared
+> config + UI primitives) is in place; the surface itself ships in a
+> later update."
+
+Do not attempt to hand-build the surface yourself when its scaffolder
+is missing — that would bypass the recomposition method (§8: capability
+checklist → `packages/ui` primitives, never a verbatim UI lift) every
+FEAT-023 UI surface must follow.
+
+**10e-i — Checkout (one-time), FEAT-023 U2.** When the consumer picks
+**Checkout** and wants a one-time payment (not a subscription — v1 only
+scaffolds one-time; acknowledge and stop if the consumer wants
+recurring billing, that's a future `mode: "subscription"` branch):
+
+1. **Pick the product(s).** Offer the `lookup_key`s already created this
+   session (Step 3/5) as the checkout's product choices. If none were
+   created yet, run Steps 2–5 first (or ask for at least one product).
+2. **Instantiate the route.** Copy
+   `templates/checkout-route.template.ts` next to the already-instantiated
+   `stripe-config.ts` (Step 10d) in the consumer's `apps/api/src/routes/checkout/`
+   (checkout creation is server-side only — `apps/web` may not import
+   `@working-theory/stripe-client`, architecture.yaml). Register its exported
+   `oneTimeCheckoutHandler` on a `POST` route, e.g.
+   `POST /api/checkout/one-time`, SCOPED BEHIND the shared per-IP rate-limit
+   middleware (`apps/api/src/middleware/rate-limit.ts`, already present in
+   every consumer's `apps/api` — the same one `server.ts` wires around the
+   anonymous "leads" routes). This is a public, unauthenticated, single-purpose
+   session-creation endpoint by design (see the template's own header comment)
+   — the rate limit is its abuse guard against unbounded session-creation /
+   card-testing attempts; do not register it unscoped. Ask the consumer to
+   confirm the route path if their `apps/api` layout differs from the default.
+
+   **Two edits are MANDATORY as you instantiate it. The route is fail-closed
+   until both are done — every request 404s or 500s. This is deliberate: a
+   checkout route that is wrong in either respect is exploitable by an
+   anonymous internet caller.**
+
+   **(a) Pin the purchasable-product allowlist.** Replace the placeholder in
+   the route's `ALLOWED_LOOKUP_KEYS` with EXACTLY the `lookup_key`s the
+   consumer selected at step 1 — nothing else:
+
+   ```ts
+   const ALLOWED_LOOKUP_KEYS: ReadonlySet<string> = new Set<string>([
+     "pizza_onetime", // ← the step-1 selection, verbatim
+     "combo_onetime",
+   ]);
+   ```
+
+   Why this is not optional: without it, the route resolves ANY
+   caller-supplied `lookupKey` against the merchant's ENTIRE Stripe account.
+   A merchant with a public `pizza_onetime` ($15) and a private
+   `enterprise_annual_90pct_off` in the same account is one guessed lookup
+   key away from selling the discounted price to an anonymous `curl`; any
+   `$0` comp/test price becomes a free-fulfillment endpoint. Pin the
+   products this surface sells — never the account. Do not offer to
+   "allow all keys", and do not read the allowlist from an env var or the
+   request: it is a source-pinned constant.
+
+   **(b) Set `FRONTEND_URL`.** The route locks every `successUrl` /
+   `cancelUrl` to the site's own origin, read from `FRONTEND_URL` (the same
+   env var the consumer's `apps/api` already uses for CORS —
+   `apps/api/src/config/index.ts`). Confirm it is set for each environment
+   (dev / preview / prod). If it is unset the route returns
+   `500 config-error` and refuses every checkout — fail-closed by design.
+   Without the origin lock, an anonymous caller can mint a REAL
+   `checkout.stripe.com` session for the real merchant whose success page is
+   an attacker's — the victim pays on Stripe's real domain and lands on the
+   attacker's "receipt".
+
+3. **Compose the checkout page.** In the consumer's `apps/web`, create a
+   page that renders `CheckoutForm` (`@working-theory/ui`) with the
+   session's products as `CheckoutProduct[]` (`lookupKey` + `name` + price).
+   Wire `onCheckout` to POST to the Step-2 route with `{ lookupKey,
+successUrl, cancelUrl }` and, on a `201` response, set
+   `window.location.href` to the returned `url`. Pass `testMode` (always
+   `true` at v1 — sandbox-only). Ask which page path to use (e.g.
+   `app/checkout/page.tsx`), mirroring the link path's "ask which"
+   convention. Send the redirects as RELATIVE PATHS (`/checkout/success`,
+   `/checkout/cancel`): the route composes them onto the site's own origin
+   server-side. A cross-origin absolute URL is refused with
+   `400 invalid-redirect-url`.
+4. **Compose the success/cancel pages.** Create two pages (e.g.
+   `app/checkout/success/page.tsx`, `app/checkout/cancel/page.tsx`) at the
+   `successUrl`/`cancelUrl` the checkout page passed, each rendering
+   `PaymentResult` (`@working-theory/ui`) with `outcome="success"` /
+   `outcome="cancel"` respectively and the consumer's own copy.
+
+   **Tell the consumer, in these words: the success page is a DISPLAY-ONLY
+   terminal state; it is NEVER proof of payment.** Anyone can navigate
+   straight to `/checkout/success` and be shown "Payment successful". So
+   never hang fulfillment, an entitlement grant, a license issue, or a file
+   download off that page. Real fulfillment must be driven by a verified
+   Stripe webhook (signature-checked) or a server-side
+   `stripe.checkout.sessions.retrieve(id)` whose `payment_status === "paid"`
+   — neither of which this v1 surface scaffolds. If the consumer asks for
+   fulfillment, that is the next unit of work, not a tweak to this page.
+
+5. **Surface the session id.** After the flow is wired, remind the
+   consumer that each created Checkout Session's id is logged (truncated,
+   no PII) by the route for verification in
+   <https://dashboard.stripe.com/test/payments>.
+6. **Closing note.** Confirm the surface is reachable only because
+   `feature:commerce` resolved entitled (10a) — a non-entitled site never
+   sees this branch. Note that this entitlement check is SCAFFOLD-TIME only:
+   the emitted route reads no license at runtime, so a lapsed
+   `feature:commerce` does not switch the endpoint off.
+
+   Remind the consumer this is test-mode only. Be precise about what the
+   live-key guard actually covers: `assertSandboxKey` (10d's
+   `loadStripeSurfaceConfig`, and the shared Stripe client singleton) is an
+   ALLOW-LIST as of AILK#3734 — it accepts only `sk_test_`, `pk_test_` and
+   `rk_test_`, and refuses everything else. A Stripe **restricted** live key
+   (`rk_live_…`) — the key type Stripe steers server-side integrations toward
+   — IS refused, along with any live prefix Stripe introduces later, because
+   it is absent from the allow-list rather than named on a ban-list.
+   So: "only recognized test-mode keys are accepted", not "these particular
+   live prefixes are blocked". Tell the consumer to use a test-mode key and to
+   keep live keys out of the environment entirely anyway — a working guard is
+   not a reason to point a live key at a non-production deployment.
+
+   Finally, confirm all three abuse guards are actually in place: the
+   rate-limit middleware is wired (step 2 — an unauthenticated checkout route
+   without it is a card-testing vector), `ALLOWED_LOOKUP_KEYS` is pinned to
+   the real selection (step 2a), and `FRONTEND_URL` is set for every
+   environment (step 2b).
+
+**10e-ii — Pay-by-link (payment-link management), FEAT-023 U3.** When
+the consumer picks **Pay by link**, instantiate
+`templates/payment-link-route.template.ts` next to the already-instantiated
+`stripe-config.ts` (Step 10d) in the consumer's
+`apps/api/src/routes/payment-links/` — server-side only, same reason as
+checkout (`apps/web` may not import `@working-theory/stripe-client`,
+architecture.yaml).
+
+This is a **MANAGEMENT** surface (list / create / archive payment objects),
+NOT a storefront "buy" action — so its auth posture is the OPPOSITE of the
+checkout route's. Register its three exported handlers INSIDE the
+authenticated scope, so `authPreHandlerPlugin` decorates `request.userId`
+(and applies its same-origin CSRF check) before any handler runs:
+
+```ts
+await fastify.register(async (authed) => {
+  authed.register(authPreHandlerPlugin, { frontendOrigin: config.frontendUrl });
+  authed.get("/api/payment-links", listPaymentLinksHandler);
+  authed.post("/api/payment-links", createPaymentLinkHandler);
+  authed.patch("/api/payment-links", updatePaymentLinkHandler);
+});
+```
+
+The registration is **load-bearing** — do not copy the checkout route's
+public, rate-limited registration here:
+
+1. **Authentication + authorization.** Each handler calls `requireSiteAdmin()`
+   FIRST — before the entitlement check and before any Stripe call. It
+   re-reads `User.role` from the database and admits only `admin` / `owner`.
+   Authentication alone is not the bar: on a site with open signup, "any
+   logged-in user" is "the whole internet with an extra step".
+2. **Entitlement is NOT authorization.** The `feature:commerce` check answers
+   "does this DEPLOYMENT have commerce?", never "may this CALLER manage
+   payment links?" — it reads the site's env license and returns the identical
+   answer to an anonymous caller. It is retained, layered UNDER the identity
+   gate, never as a substitute for it. (Shipping this surface with ONLY the
+   entitlement gate was AILK#3744: a P0 that let an anonymous caller list every
+   payment link, archive them all — total denial of revenue — and mint new ones
+   against the merchant's Stripe account.)
+3. **CSRF** is inherited from the auth scope's same-origin `Origin` check
+   (`apps/api/src/middleware/auth.ts`), which exists ONLY inside that scope.
+4. **Fail-closed by construction.** Mis-register the routes outside the auth
+   scope and `request.userId` is `undefined`, so every handler answers 401 — a
+   broken feature, never an open door.
+5. **Tenancy.** Deliberately NOT `tenantScope`. This surface manages the SITE
+   OWNER's single Stripe catalog (`packages/stripe-client` is single-tenant; a
+   Stripe Payment Link carries no org binding). Cross-account access is
+   structurally impossible — Stripe object ids are account-scoped, so a foreign
+   id returns `resource_missing`, which the route maps to the same 404 as an
+   unknown id (no enumeration oracle). The multi-tenant module's org-scoped
+   billing is a SEPARATE surface (`apps/api/src/routes/billing/`), which DOES
+   derive its org from `request.tenant.organizationId`.
+
+Test-mode-only caveats are identical to checkout's (step 10e-i) — state the
+`assertSandboxKey` allow-list (AILK#3734): only recognized test-mode prefixes
+are accepted, so every live key is refused by construction.
+
+**10f — Shared UI primitives.** Every surface scaffolder composes from
+`@working-theory/ui`'s `MoneyAmount` (primitive), `PaymentStatusBadge`
+(block), and `StripeActionButton` (block) — built once in FEAT-023 U1
+so no surface hand-rolls its own amount formatting, status chip, or
+checkout/portal button.
+
+**10g — Invoice surface, shipped (FEAT-023 U4).** When the consumer picks
+"Invoice" at 10b, this surface IS available (unlike the still-unshipped
+choices in 10e). Invoice management is an ADMIN action, never a customer-
+facing or anonymous one (a security review of the sibling U3 pay-by-link
+template found the entitlement check alone is NOT authentication — see
+`docs/research/commerce-template-audit/invoices.md` finding 7):
+
+1. Instantiate `templates/invoice-route.template.ts` into the consumer's
+   `apps/api` — mirrors 10d's `stripe-config.template.ts` instantiation. It
+   exports a Fastify plugin (`invoiceRoutes`: `GET` list/retrieve, `POST`
+   create-draft, `POST .../send` finalize+send) built on
+   `@working-theory/stripe-client`'s `createInvoice` / `sendInvoice` /
+   `listInvoices` / `retrieveInvoice`.
+2. **Register it inside the TENANT-GUARDED scope `apps/api`'s
+   `billingRoutes` use** — the inner `tenantScope` in `server.ts` that
+   registers `tenantPreHandlerPlugin` (itself nested inside `authScope`) —
+   e.g. `await tenantScope.register(invoiceRoutes);`. **NOT** the outer
+   `authScope`. This is REQUIRED, not optional, and it is a SECURITY
+   boundary, not a style preference:
+   - `authPreHandlerPlugin` (inherited from the enclosing `authScope`) gives
+     every handler an authenticated caller plus the cookie path's same-origin
+     CSRF check. The template then requires `User.role` in {`admin`,`owner`},
+     so anonymous and plain-authenticated callers are refused.
+   - `tenantPreHandlerPlugin` (default-deny) populates `request.tenant`, so
+     the org is **server-derived** and never client-supplied — the same
+     property `routes/billing/read.ts` relies on. Registering in `authScope`
+     instead leaves `request.tenant` undefined, and the template then fails
+     **closed** (403) rather than serving an unscoped admin surface.
+     Tell the consumer explicitly that this route is admin-only, and that a
+     Bearer-token caller is denied (a bearer token carries no workspace
+     binding) — this is a cookie-session admin-UI surface.
+3. Point the consumer at `@working-theory/ui`'s `InvoiceList` (block),
+   `InvoiceDetail` (panel), and `InvoiceForm` (block) to compose the
+   admin-facing management page — `InvoiceForm` posts directly to the
+   instantiated route; `InvoiceList`/`InvoiceDetail` render already-fetched
+   invoice records (reusing `PaymentStatusBadge` for status and
+   `MoneyAmount` for amounts, per 10f).
+4. Re-run 10c's live-key check before instantiating (already covered by
+   this step's ordering, restated for clarity). The guard has no remaining
+   gap: AILK#3734 converted `assertSandboxKey` to an allow-list, so a Stripe
+   RESTRICTED key is refused like every other non-test-mode key. Finding 10
+   in the audit log records the historical deny-list gap and is marked
+   resolved there.
+5. **Multi-tenant module — the surface REFUSES, it does not warn.** v1 has
+   ONE deployment-wide `STRIPE_SECRET_KEY` and no per-organization Stripe
+   customer namespace, so an invoice carries no org attribution and a
+   caller-supplied `invoiceId`/`customerId` cannot be honestly checked
+   against the caller's org (findings 7 + 9 in the audit log). The template's
+   `requireSingleTenantScope` guard therefore admits **only the deployment's
+   own operator org** — the fixed single-tenant sentinel `DEFAULT_ORG_ID`,
+   which an organization created through the multi-tenant module never
+   carries — and **hard-refuses every other org's admin with a 403
+   `tenancy_unsupported`**, before any Stripe call. That is what stops one
+   tenant's admin reading another tenant's customer PII (names, emails,
+   amounts, line items) out of the shared Stripe account. Tell the consumer
+   plainly: **invoice management is an OPERATOR surface at v1, not a
+   per-tenant self-service one.** The operator can still see every invoice in
+   the deployment-wide Stripe account — they hold the `STRIPE_SECRET_KEY` and
+   can read the same data from the Stripe dashboard, so this is not an
+   escalation — but per-tenant invoicing needs a per-org Stripe Connect /
+   customer-namespace model (tracked follow-up).
+
+   **`User.role` is DEPLOYMENT-OPERATOR-ONLY, and must not be widened to reach
+   this surface.** The `requireSiteAdmin` gate keys on `User.role` — a
+   per-deployment String (`"user" | "admin" | "owner"`), DISTINCT from the
+   org-membership `Role` enum the multi-tenant module uses. Do not grant
+   `User.role = "admin"` to an organization's admins as a way of giving them
+   invoice access: that is a site-wide operator grant, not an org-scoped one,
+   and until per-org Stripe namespacing exists it would turn the tenancy
+   refusal above into a cross-tenant PII leak (names, emails, amounts, line
+   items). The correct answer to "our org admins need invoices" at v1 is that
+   the surface does not support it yet — not a role change.
+
+**10h — Subscription surface, shipped (FEAT-023 U5).** When the consumer picks
+"Subscription" at 10b, this surface IS available. It splits into TWO handlers
+with DELIBERATELY OPPOSITE auth postures — the same split checkout (public)
+vs invoice (admin) already established:
+
+1. Instantiate `templates/subscription-route.template.ts` into the consumer's
+   `apps/api` — mirrors 10d's `stripe-config.template.ts` instantiation. It
+   exports `subscribeHandler` (a standalone Fastify handler) and
+   `subscriptionRoutes` (a Fastify plugin), built on
+   `@working-theory/stripe-client`'s `createCheckoutSession` (`mode:
+"subscription"`, pinned) and `retrieveSubscriptionStatus`.
+2. **Register `subscribeHandler` PUBLICLY, rate-limited — mirrors 10e-i's
+   checkout registration exactly.** It is a storefront "subscribe" action
+   (the recurring-price analog of the one-time checkout route): pin
+   `ALLOWED_LOOKUP_KEYS` to the RECURRING lookup_key(s) the consumer selected
+   (step 1's selection, verbatim — never "allow all"), confirm `FRONTEND_URL`
+   is set (the same origin-lock 10e-i requires), and scope it behind the
+   shared per-IP rate-limit middleware. Both edits are MANDATORY — the route
+   is fail-closed until they're done.
+3. **Register `subscriptionRoutes` inside the SAME tenant-guarded scope
+   10g's `invoiceRoutes` uses** — e.g. `await tenantScope.register(subscriptionRoutes);`.
+   NOT the outer `authScope`, and NOT the same public scope as
+   `subscribeHandler`. This is a READ of a specific subscription's status —
+   a MANAGEMENT-shaped action, so it inherits 10g's admin + tenancy guards
+   verbatim (`requireSiteAdmin` + `requireSingleTenantScope`, the fixed
+   single-tenant sentinel `DEFAULT_ORG_ID`). See the template's own header
+   comment for the full registration snippet.
+4. Point the consumer at `@working-theory/ui`'s `PricingTable` (section) and
+   `SubscriptionStatus` (block) to compose the subscribe + status pages —
+   `PricingTable`'s `onSubscribe` POSTs to step 2's route + redirects to the
+   returned Stripe Checkout URL (mirrors `CheckoutForm`'s `onCheckout`
+   shape); `SubscriptionStatus` renders an already-fetched status (step 3's
+   route) via `PaymentStatusBadge` (reused from U1) plus a portal "Manage"
+   action pointing at the U6 billing-portal surface — this surface never
+   builds self-service plan-change/cancel itself.
+5. Re-run 10c's live-key check before instantiating. State the CURRENT
+   behaviour to the consumer: `assertSandboxKey` is an ALLOW-LIST as of
+   AILK#3734 — only `sk_test_`, `pk_test_` and `rk_test_` are accepted, so
+   every live key including a restricted one is refused. No surface header
+   carries the pre-#3734 deny-list caveat any more (AILK#3765 retired the
+   last of them); if you find one, it is stale — fix it rather than repeat it.
+6. **Multi-tenant module — same refusal as invoices, same reason.** v1 has
+   ONE deployment-wide `STRIPE_SECRET_KEY` and no per-organization Stripe
+   customer namespace, so a subscription carries no org attribution.
+   `subscriptionRoutes`'s `requireSingleTenantScope` guard therefore admits
+   ONLY the deployment's own operator org and hard-refuses every other org's
+   admin with a 403 `tenancy_unsupported`, before any Stripe call. Tell the
+   consumer plainly: subscription-status reading is an OPERATOR surface at
+   v1, not a per-tenant self-service one — the same disclosed limitation as
+   10g's invoice surface (see
+   `docs/research/commerce-template-audit/subscriptions.md`).
+7. **No subscription webhook is scaffolded at v1** — the status read is
+   retrieve-on-view by the subscription's own Stripe id (mirrors 10g's
+   `?invoiceId=` shape with `?subscriptionId=`), not webhook-driven. If a
+   future need requires webhook-driven status (e.g. proactive
+   past-due notices), that is a new unit of work, not a tweak to this
+   surface.
+
+**10i — Portal surface, shipped (FEAT-023 U6).** When the consumer picks
+"Portal" at 10b, this surface IS available. It is the smallest FEAT-023
+surface (spec §1) — AILK owns only the entry, Stripe hosts the portal
+itself:
+
+1. Instantiate `templates/portal-route.template.ts` into the consumer's
+   `apps/api` — mirrors 10d's `stripe-config.template.ts` instantiation. It
+   exports `portalRoutes` (a Fastify plugin: a single `POST
+/v1/commerce/portal-session`), built on
+   `@working-theory/stripe-client`'s `createBillingPortalSession`.
+2. **Register `portalRoutes` inside the SAME tenant-guarded scope 10g's
+   `invoiceRoutes` uses** — e.g. `await tenantScope.register(portalRoutes);`.
+   NOT the outer `authScope`. Starting a billing-portal session hands the
+   caller a live link into a customer's full billing surface, so — like
+   10h's `subscriptionRoutes` status read — this is a MANAGEMENT-shaped
+   action, never public/anonymous: it inherits 10g's admin + tenancy guards
+   verbatim (`requireSiteAdmin` + `requireSingleTenantScope`, the fixed
+   single-tenant sentinel `DEFAULT_ORG_ID`). See the template's own header
+   comment for the full registration snippet.
+3. Point the consumer at `@working-theory/ui`'s `PortalEntry` (block) to
+   compose a standalone billing-management entry point, AND wire it as the
+   target of 10h's `SubscriptionStatus` `manageAction` (the U5↔U6 seam,
+   spec § design decision) — both `PortalEntry`'s `onManage` and
+   `SubscriptionStatus`'s `manageAction.onManage` POST to step 1's route
+   with `{ customerId }` and, on a `200` response, set
+   `window.location.href` to the returned `url`. Pass `testMode` (always
+   `true` at v1 — sandbox-only).
+4. Re-run 10c's live-key check before instantiating. Note the guard's
+   current state (AILK#3734, now an allow-list) — restate the CURRENT state
+   to the consumer, same as 10h.
+5. **Multi-tenant module — same refusal as invoices/subscriptions, same
+   reason.** v1 has ONE deployment-wide `STRIPE_SECRET_KEY` and no
+   per-organization Stripe customer namespace, so a `customerId` carries no
+   org attribution. `portalRoutes`'s `requireSingleTenantScope` guard
+   therefore admits ONLY the deployment's own operator org and hard-refuses
+   every other org's admin with a 403 `tenancy_unsupported`, before any
+   Stripe call. Tell the consumer plainly: billing-portal sessions are an
+   OPERATOR surface at v1, not a per-tenant self-service one — the same
+   disclosed limitation as 10g/10h (see
+   `docs/research/commerce-template-audit/portal.md`).
+6. **The return URL is fixed, server-derived, never caller-supplied** — a
+   single `PORTAL_RETURN_PATH` composed from `FRONTEND_URL` (the template's
+   own `SCAFFOLD-TIME EDIT` if the consumer's account/billing page lives
+   elsewhere), mirroring `apps/api/src/routes/billing/portal.ts`'s existing
+   convention. There is no caller-chosen destination to validate, unlike
+   checkout's `successUrl`/`cancelUrl`.
+7. **No portal-session webhook is scaffolded at v1** — mint-on-demand by
+   the caller-supplied `customerId`, not webhook-driven, mirroring 10h's
+   escalation-boundary posture.
+
 ## Output style
 
 - **Two questions, two paths.** Don't lead with Stripe assumptions.
@@ -279,6 +710,15 @@ Print:
   recreates.
 - Auto-invoke other skills. Always points at the next skill by name;
   consumer drives.
+- Guess entitlement conversationally. The `feature:commerce`
+  surface-selection branch (Step 10) checks the resolved license via
+  `hasFeature("commerce", license)` — never a verbal "I'm on Pro"
+  claim. No resolvable license → not entitled (fail-closed).
+- Build a payment surface itself for a choice OTHER than checkout
+  (U3–U6). This skill's Step 10 checks entitlement, offers the choice,
+  and dispatches — the surface scaffolders own the actual page/route.
+  Checkout (one-time) is the one exception: Step 10e-i wires it inline
+  (FEAT-023 U2).
 
 ## References
 
@@ -291,6 +731,31 @@ Print:
 - `templates/marketplace-cta-route.tsx.tmpl` — emitted route source
   the link path writes. Includes the inline `<MarketplaceCTA>`
   component definition (not a separate package).
+- `templates/stripe-config.template.ts` — shared Stripe surface config
+  (env contract + `assertSandboxKey` test-mode guard) every U2–U6
+  surface scaffolder instantiates (Step 10d, FEAT-023 U1).
+- `templates/checkout-route.template.ts` — the one-time checkout POST
+  route (`mode: "payment"`, `stripe-client/checkout.ts`), instantiated
+  by Step 10e-i (FEAT-023 U2).
+- `templates/payment-link-route.template.ts` — the payment-link
+  MANAGEMENT route (list / create / archive), instantiated by Step
+  10e-ii (FEAT-023 U3). Authenticated + site-admin only, registered
+  inside the auth scope — see 10e-ii; its posture is the opposite of
+  the public checkout route's.
+- `templates/invoice-route.template.ts` — the Invoice surface's admin-only
+  Fastify plugin (create/send/list/retrieve), instantiated at Step 10g
+  (FEAT-023 U4, shipped). Registration inside `apps/api`'s tenant-guarded
+  scope is REQUIRED — see the template's own header comment.
+- `templates/subscription-route.template.ts` — the Subscription surface's
+  `subscribeHandler` (public, rate-limited) + `subscriptionRoutes` (admin +
+  tenant-guarded status read), instantiated at Step 10h (FEAT-023 U5,
+  shipped). The two handlers have OPPOSITE auth postures — see the
+  template's own header comment for both registration points.
+- `templates/portal-route.template.ts` — the Portal surface's admin +
+  tenant-guarded `portalRoutes` (mints a billing-portal session for a
+  caller-supplied `customerId`), instantiated at Step 10i (FEAT-023 U6,
+  shipped). Registration inside `apps/api`'s tenant-guarded scope is
+  REQUIRED — see the template's own header comment.
 
 ## Coordination
 
@@ -307,4 +772,36 @@ Print:
 - **`@working-theory/stripe-client`** — wrapper for Stripe SDK. The skill does
   not import this directly (the skill is a prompt/template, not
   runtime code). The consumer's `apps/api/routes/checkout/sessions.ts`
-  uses it.
+  (generic primitive) and the Step-10e-i-instantiated
+  `checkout-route.template.ts` (one-time surface) use it.
+  `assertSandboxKey` is reused by `stripe-config.template.ts`.
+- **`@working-theory/license-client`** — `hasFeature("commerce", license)`
+  is the entitlement read Step 10a consults (static-mode, sync, no
+  network). The skill does not import this directly either — it
+  describes the check a consumer's own license-aware tooling performs.
+- **FEAT-023 U2–U6 (checkout · pay-by-link · invoice · subscription ·
+  portal)** — the five payment surfaces Step 10e dispatches to. Checkout
+  (one-time) shipped in U2 (10e-i); pay-by-link shipped in U3 (10e-ii);
+  invoice shipped in U4 (10g); subscription shipped in U5 (10h); portal
+  shipped in U6 (10i).
+- **FEAT-023 U4 (invoice)** — shipped (Step 10g). `@working-theory/stripe-client`'s
+  `invoice.ts` (create/send/list/retrieve) + `@working-theory/ui`'s
+  `InvoiceList`/`InvoiceDetail`/`InvoiceForm` compose the surface; the
+  route template lives at `templates/invoice-route.template.ts`.
+- **FEAT-023 U5 (subscription)** — shipped (Step 10h).
+  `@working-theory/stripe-client`'s `checkout.ts` (`createCheckoutSession`
+  `mode: "subscription"` + `retrieveSubscriptionStatus`) +
+  `@working-theory/ui`'s `PricingTable`/`SubscriptionStatus` compose the
+  surface; the route template lives at
+  `templates/subscription-route.template.ts`.
+- **FEAT-023 U6 (portal)** — shipped (Step 10i). `@working-theory/stripe-client`'s
+  `billing-portal.ts` (`createBillingPortalSession`) + `@working-theory/ui`'s
+  `PortalEntry` (reuses U1's `StripeActionButton`) compose the surface — the
+  target of U5's `SubscriptionStatus` "Manage" action; the route template
+  lives at `templates/portal-route.template.ts`.
+- **`@working-theory/ui`'s `MoneyAmount` / `PaymentStatusBadge` /
+  `StripeActionButton`** — the shared presentational components every
+  U2–U6 surface composes (Step 10f, FEAT-023 U1).
+- **`@working-theory/ui`'s `CheckoutForm` / `PaymentResult`** — the
+  one-time checkout surface's own capability-bearing blocks (FEAT-023
+  U2), composed at Step 10e-i steps 3–4.