create-ailk 0.1.1 → 0.3.0

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

@@ -1,807 +0,0 @@
----
-name: scaffold-commerce
-description: Wire up commerce on an AILK consumer site — either an external link to an existing storefront (Amazon, Etsy, Shopify, eBay, Gumroad, custom) via a `<MarketplaceCTA>` button, or direct payments via Stripe (test-mode only at v1). Use when the user says "let me sell something", "add a buy button", "wire up Stripe", "set up payments", "I have an Amazon store", or otherwise wants commerce wiring on their AILK site. Two-path branching — picks link vs direct first, never assumes Stripe.
----
-
-# scaffold-commerce
-
-Add commerce to an AILK site. The first question is always: **external
-link to an existing storefront, or direct payments on this site?** Both
-paths are conversational and emit minimal, consumer-owned source.
-
-This skill is the canonical "sell stuff" entry point. Pricing UI itself
-is `scaffold-page` (#362)'s lane (you scaffold a `/pricing` page with
-that skill, then wire `lookup_key`s into it). Production webhook setup
-is `provision-config` (#367)'s lane.
-
-## When to use
-
-The user wants to sell something — physical goods, digital goods,
-subscriptions, services, courses, anything with a price. Triggers:
-
-- "let me sell something" / "I want to sell"
-- "add a buy button" / "add a buy now"
-- "wire up Stripe" / "set up payments"
-- "I have an Amazon / Etsy / Shopify / eBay / Gumroad store, link it"
-- "what's the simplest way to charge for this?"
-
-Skip this skill when:
-
-- The user wants to _design_ a pricing page (lay out tiers, copy,
-  comparison table) — that's `scaffold-page` (#362) emitting a Product
-  page. Wire `lookup_key`s afterwards from this skill's output.
-- The user wants to set up production Stripe (live mode, real webhooks).
-  Hard-blocked at v1 — sandbox-only is hook-enforced globally. Defer
-  with the same answer regardless: "v1 is test-mode only; production
-  setup is `provision-config` (#367)'s lane."
-- The user is on a non-Stripe payment processor (Lemon Squeezy, Paddle,
-  Gumroad-as-payment-processor). v1 only supports Stripe for direct
-  payments. Acknowledge and stop; future PRs will add `--provider`
-  branches.
-
-## The first question (always asked)
-
-Greet the consumer with a clear two-path branch:
-
-> "Two ways to sell on your AILK site:
->
-> **Link to an existing store** — you already sell on Amazon, Etsy,
-> Shopify, eBay, Gumroad, or your own storefront. We add a 'Buy on
-> {marketplace}' button that links there.
->
-> **Direct payments via Stripe** — you don't have a storefront yet, or
-> you want checkout on your own site. We create products in your
-> Stripe (test mode), wire env vars, and point you at the next steps.
->
-> Which one?"
-
-Wait for the consumer's choice. Then run the matching path.
-
-## Link path
-
-The link path emits source the consumer owns — no env wiring, no API
-calls, no `@working-theory/ui` import.
-
-### Step 1 — Collect the inputs
-
-Ask conversationally for:
-
-1. **URL** — the storefront URL. Validate it parses as a URL. Don't
-   accept plain text; prompt again if input fails.
-2. **Button text** — defaults to "Buy on {marketplace}" where
-   `{marketplace}` is parsed from the URL hostname (e.g.,
-   `amazon.com` → "Amazon"). Consumer can override.
-3. **Optional `iconSrc`** — a path to an SVG/PNG of the marketplace
-   logo, e.g., `/logos/amazon.svg`. Optional — clean text-only buttons
-   are fine. If the consumer wants logos, point them at
-   `references/marketplace-brand-pages.md` for sourcing.
-
-### Step 2 — Emit the route template
-
-Use `templates/marketplace-cta-route.tsx.tmpl` as the starting source.
-The template defines `<MarketplaceCTA>` **inline** at the top of the
-emitted route file (not bundled in `@working-theory/ui`, not imported from a
-shared package). The consumer owns the component and can customize it.
-
-The emitted file path is the consumer's call — typical placement is
-`app/buy/page.tsx` for a dedicated landing, or inserted into an
-existing page (e.g., `app/products/[slug]/page.tsx`) as a `<MarketplaceCTA>`
-usage. Ask which.
-
-### Step 3 — Confirm and write
-
-Show the consumer the emitted file diff (or new file if standalone)
-in a single confirmation step. After approval, write.
-
-### Step 4 — No env wiring, no follow-up files
-
-The link path is self-contained. Nothing to add to `.env.local`. No
-references file write (the marketplace brand pages cheat-sheet ships
-in the skill folder; the skill points at it but doesn't copy it into
-the consumer's repo).
-
-## Direct payments path (Stripe, test-mode only at v1)
-
-The Stripe path uses the **Stripe MCP** (configured in the AILK
-consumer scaffold's `.claude/settings.json`) to create products with
-consumer-derived `lookup_key`s, writes test-mode env vars, and
-surfaces created keys for the consumer to grep when wiring pricing UI.
-
-### Step 1 — Defense-in-depth live-key check
-
-Before any other action:
-
-1. **Env detection.** Scan the consumer's `.env.local`, `.env`,
-   `.env.development`, and any `.env.example` for `sk_live_` or
-   `pk_live_`. If any match, refuse with:
-
-   > "AILK is sandbox-only at v1. I see a `sk_live_*` or `pk_live_*`
-   > value in your env files — replace it with a test-mode key from
-   > <https://dashboard.stripe.com/test/apikeys> before continuing.
-   > Production setup is `provision-config` (#367)'s lane and is
-   > deferred at v1."
-
-   Stop. No Stripe API calls fire.
-
-2. **Paste detection.** If the consumer pastes a `sk_live_` or
-   `pk_live_` value during the flow, refuse with the same message
-   and stop.
-
-This double-check is required by the brief and matches the global
-hook-enforced sandbox-only constraint.
-
-### Step 2 — Collect product inputs
-
-Ask the consumer to describe each product they want to sell. Per
-product:
-
-- **Name** — e.g., "Pro plan", "Pizza", "Online course".
-- **Price + interval** — e.g., "$29/month", "$15 one-time", "$199/year".
-- **Optional features bullet list** — surfaced in the dashboard, not
-  required for the API call.
-
-Loop until the consumer says "that's all" or equivalent.
-
-### Step 3 — Derive `lookup_key`s
-
-For each product, derive a stable, human-readable `lookup_key`:
-
-- Lowercase the name, replace spaces with underscores.
-- Append `_monthly` / `_yearly` / `_onetime` based on interval.
-- Examples:
-  - "Pro plan, $29/month" → `pro_monthly`
-  - "Annual subscription, $199/year" → `annual_yearly`
-  - "Pizza, $15 one-time" → `pizza_onetime`
-
-Show the derivations to the consumer and offer to override per-product
-before any API call.
-
-### Step 4 — Conflict handling (per product)
-
-For each product, before creating it, query the consumer's Stripe
-account for an existing product with the same `lookup_key` (use the
-Stripe MCP — `stripe.products.list({lookup_keys: [...]})` or equivalent).
-
-If one exists, **show + ask** (do not silently skip, do not refuse):
-
-```
-A product with lookup_key `pro_monthly` already exists:
-  Existing: "Pro plan" — $29/month — created 2026-04-15
-  Proposed: "Pro plan" — $29/month — new
-
-What would you like to do?
-  - Keep existing (no change)
-  - Overwrite amounts (update price, keep lookup_key)
-  - Pick a different lookup_key (e.g., `pro_monthly_v2`)
-```
-
-Wait for choice. Apply.
-
-### Step 5 — Create products + prices in Stripe
-
-For each product (after conflict resolution), use the Stripe MCP:
-
-1. **Create product:** `stripe.products.create({ name, ... })`.
-2. **Create price:** `stripe.prices.create({ product: <id>, unit_amount, currency: 'usd', recurring: { interval } | undefined, lookup_key })`.
-
-Surface created IDs in chat as you go so the consumer can verify in
-their Stripe dashboard alongside the run.
-
-### Step 6 — Write `.env.local`
-
-After all products are created, write to the consumer's `.env.local`:
-
-```
-STRIPE_SECRET_KEY=sk_test_...
-STRIPE_PUBLISHABLE_KEY=pk_test_...
-STRIPE_WEBHOOK_SECRET=
-```
-
-Use the test-mode keys from the consumer's Stripe account (the
-consumer pastes these from
-<https://dashboard.stripe.com/test/apikeys>). Leave
-`STRIPE_WEBHOOK_SECRET` empty — Step 7 fills it.
-
-### Step 7 — Webhook setup (dev-only)
-
-Tell the consumer to run, in a separate terminal:
-
-```bash
-stripe listen --forward-to localhost:3000/api/webhooks/stripe
-```
-
-The CLI prints a signing secret (`whsec_...`). Have the consumer paste
-it into `.env.local` as `STRIPE_WEBHOOK_SECRET`.
-
-Note: production webhook setup is **deferred to v2** — the consumer
-will register a permanent webhook endpoint in Stripe's dashboard
-during deploy. Point at `provision-config` (#367) or future deploy
-skill for the production handoff. Do not attempt to register a
-production webhook from this skill.
-
-### Step 8 — Write `references/lookup-keys.md`
-
-Use `references/lookup-keys-template.md` as the source. Instantiate
-with the products created this session:
-
-```markdown
-# Lookup Keys — generated by scaffold-commerce
-
-| Product  | Lookup key    | Amount | Interval |
-| -------- | ------------- | ------ | -------- |
-| Pro plan | `pro_monthly` | $29.00 | monthly  |
-| ...      | ...           | ...    | ...      |
-
-When wiring a pricing page (`scaffold-page` (#362) on a `Product` slug),
-import or reference these lookup keys. Stripe lookup keys are stable
-across price recreates — safe to hard-code in your app.
-```
-
-The consumer's filled-in `lookup-keys.md` lives in their repo (e.g.,
-project root or a `docs/` folder) — point them at `scaffold-page`
-(#362) for the pricing page that consumes these keys.
-
-### Step 9 — Closing summary
-
-Print:
-
-- Number of products created (with `lookup_key`s).
-- Path to `references/lookup-keys.md`.
-- Reminder: webhook setup is dev-only at v1; production webhook is
-  `provision-config` (#367)'s lane.
-- 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.
-- **Live-key checks happen first** for the Stripe path. Always.
-- **Show + ask on conflicts.** Never silently skip or auto-overwrite.
-- **Source the consumer owns.** The link path emits inline source, not
-  an `@working-theory/ui` import. The consumer can edit any of it post-emit.
-- **`lookup_key` derivations are visible.** Show the derivation; let
-  the consumer override before any API call.
-
-## What this skill does NOT do
-
-- Live-mode Stripe anything. Hook-blocked globally; SKILL refuses.
-- Bundle marketplace logos (Amazon, Etsy, Shopify, eBay, Gumroad).
-  AILK doesn't ship those SVGs (trademark-redistribution concern). The
-  consumer drops their own SVG into `public/logos/` and passes
-  `iconSrc` to `<MarketplaceCTA>`. See
-  `references/marketplace-brand-pages.md` for official brand-kit
-  sources.
-- Build a pricing page. That's `scaffold-page` (#362).
-- Register a production webhook endpoint. That's `provision-config`
-  (#367) or future deploy skill.
-- Use `pricebook.ts` or env-var price mapping. AILK uses
-  `lookup_key`s as the source of truth — they're stable across price
-  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
-
-- `references/marketplace-brand-pages.md` — links to official brand
-  kits (Amazon, Etsy, Shopify, eBay, Gumroad). Used by the link path
-  when the consumer wants logos. AILK does not bundle the SVGs.
-- `references/lookup-keys-template.md` — template the skill instantiates
-  per session, lists every product the consumer created with its
-  `lookup_key` and price.
-- `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
-
-- **`scaffold-page` (#362)** — pricing UI. After this skill creates
-  products and surfaces `lookup_key`s, the consumer scaffolds a
-  `/pricing` page that consumes them.
-- **`provision-config` (#367)** — production webhook setup, deploy
-  config, persistent leads (related infra). v1 is dev-mode only;
-  prod webhook lives there.
-- **Stripe MCP** — used for product/price/lookup_key creation. Should
-  already be configured in `.claude/settings.json` from the consumer
-  scaffold. If missing, surface a clear "Stripe MCP not configured"
-  error and stop; do not invent the configuration.
-- **`@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`
-  (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.