@tokenoftrust/storefront-runner 1.3.2 → 1.3.4-rc.2

package/apps/storefront/src/lib/admin/services/orders.ts

@@ -1,7 +1,7 @@
 /**
  * REAL orders view model (card 8585 / U3) — replaces the deterministic mock as
- * the Orders tab's data source. Fetches the tenant's orders from tot-foxycart via
- * U2's order client and maps the frozen DTO (`@tot/public-runtime` foxy-orders)
+ * the Orders tab's data source. Fetches the tenant's checkout orders via U2's
+ * order client and maps the frozen DTO (`@tot/public-runtime` checkout-orders)
  * into the EXISTING `OrdersViewModel` shape, so `OrdersWorkspace.astro` renders
  * unchanged. Read-only (scope-locks) — no write paths.
  *
@@ -19,11 +19,11 @@
  * `verificationDetail` slots — no shape change needed.
  */
 import type {
-  FoxyOrderDetail,
-  FoxyOrderListFilters,
-  FoxyOrderPage,
-  FoxyOrderSummary,
-  FoxyOrderVerification,
+  CheckoutOrderDetail,
+  CheckoutOrderListFilters,
+  CheckoutOrderPage,
+  CheckoutOrderSummary,
+  CheckoutOrderVerification,
 } from "@tot/public-runtime";
 import type {
   OrderDetail,
@@ -34,7 +34,7 @@ import type {
   OrderShipState,
   OrdersViewModel,
 } from "../viewmodels/orders";
-import type { FoxyOrderClient } from "../orderClient";
+import type { CheckoutOrderClient } from "../orderClient";
 
 /** Next-step label, mirroring the mock's queue semantics. */
 function deriveNextStep(fulfillment: OrderShipState, blocker: string | null): string {
@@ -47,7 +47,7 @@ function deriveNextStep(fulfillment: OrderShipState, blocker: string | null): st
 
 /** Provisional risk until U4 fills `verification`. Prefer a real riskLevel when present. */
 function deriveRisk(
-  verification: FoxyOrderVerification | null,
+  verification: CheckoutOrderVerification | null,
   blocker: string | null,
 ): OrderRow["riskLevel"] {
   const r = verification?.riskLevel;
@@ -57,7 +57,7 @@ function deriveRisk(
 }
 
 /** Map a DTO summary to the view model's OrderRow. */
-export function mapSummaryToRow(s: FoxyOrderSummary): OrderRow {
+export function mapSummaryToRow(s: CheckoutOrderSummary): OrderRow {
   return {
     id: s.id,
     placedAt: s.placedAt,
@@ -76,7 +76,7 @@ export function mapSummaryToRow(s: FoxyOrderSummary): OrderRow {
 }
 
 /** Commerce-derived readiness checks (U4 enriches the identity dimension). */
-function deriveReadinessChecks(d: FoxyOrderDetail): OrderReadinessCheck[] {
+function deriveReadinessChecks(d: CheckoutOrderDetail): OrderReadinessCheck[] {
   const ageHold = d.blocker === "Age verification hold";
   return [
     {
@@ -119,7 +119,7 @@ function deriveReadinessChecks(d: FoxyOrderDetail): OrderReadinessCheck[] {
 }
 
 /** Base commerce evidence events (U4 replaces with the real verification timeline). */
-function deriveEvidenceTimeline(d: FoxyOrderDetail): OrderEvidenceEvent[] {
+function deriveEvidenceTimeline(d: CheckoutOrderDetail): OrderEvidenceEvent[] {
   const events: OrderEvidenceEvent[] = [
     { title: "Order imported", detail: "Storefront order became available in the admin queue.", at: d.placedAt },
     { title: "Payment authorized", detail: "The customer completed checkout and payment was authorized.", at: d.placedAt },
@@ -131,7 +131,7 @@ function deriveEvidenceTimeline(d: FoxyOrderDetail): OrderEvidenceEvent[] {
 }
 
 /** Map a DTO detail (its summary already mapped to `row`) to the view model's OrderDetail. */
-export function mapDetailToDetail(d: FoxyOrderDetail, row: OrderRow): OrderDetail {
+export function mapDetailToDetail(d: CheckoutOrderDetail, row: OrderRow): OrderDetail {
   return {
     ...row,
     lineItems: d.lineItems.map((li) => ({
@@ -168,8 +168,8 @@ function buildQueues(rows: OrderRow[]): OrderQueueSummary[] {
  */
 export function mapOrdersToViewModel(
   targetTenant: string,
-  summaries: FoxyOrderSummary[],
-  details: Record<string, FoxyOrderDetail>,
+  summaries: CheckoutOrderSummary[],
+  details: Record<string, CheckoutOrderDetail>,
 ): OrdersViewModel {
   const rows = summaries.map(mapSummaryToRow);
 
@@ -214,9 +214,9 @@ export function emptyOrdersViewModel(targetTenant: string): OrdersViewModel {
 
 export interface GetOrdersViewModelOptions {
   targetTenant: string;
-  client: FoxyOrderClient;
+  client: CheckoutOrderClient;
   /** List filters (queue/status/pagination); passed through to the order client. */
-  filters?: Parameters<FoxyOrderClient["listOrders"]>[0];
+  filters?: Parameters<CheckoutOrderClient["listOrders"]>[0];
 }
 
 /**
@@ -236,7 +236,7 @@ export type OrdersLoadStatus = "loaded" | "empty" | "error" | "not_configured";
 export interface OrdersLoadResult {
   status: OrdersLoadStatus;
   vm: OrdersViewModel;
-  page: FoxyOrderPage | null;
+  page: CheckoutOrderPage | null;
 }
 
 /**
@@ -245,8 +245,8 @@ export interface OrdersLoadResult {
  * `payment`/search are NOT here — they are client-side refinements (the DTO list
  * API has no payment filter, per contract §9).
  */
-export function parseOrderFilters(params: URLSearchParams): FoxyOrderListFilters {
-  const f: FoxyOrderListFilters = {};
+export function parseOrderFilters(params: URLSearchParams): CheckoutOrderListFilters {
+  const f: CheckoutOrderListFilters = {};
   const queue = params.get("queue");
   if (queue && queue !== "all") f.queue = queue;
   const status = params.get("status");
@@ -272,7 +272,7 @@ export async function getOrdersViewModelResult(
 ): Promise<OrdersLoadResult> {
   try {
     const { orders, page } = await opts.client.listOrders(opts.filters);
-    const details: Record<string, FoxyOrderDetail> = {};
+    const details: Record<string, CheckoutOrderDetail> = {};
     await Promise.all(
       orders.map(async (o) => {
         try {

package/apps/storefront/src/lib/admin/viewmodels/subscriptions.ts

@@ -0,0 +1,106 @@
+/**
+ * Subscriptions view model (read-only v1). The source of truth is catalog
+ * purchase options; active lifecycle actions require a later subscription API
+ * and audited mutation gates.
+ */
+
+export type SubscriptionProgramReadiness = "ready" | "needs_setup" | "blocked";
+
+export type SubscriptionAttentionKind =
+  | "setup_gap"
+  | "verification_hold"
+  | "payment_attention"
+  | "product_blocker";
+
+export type SubscriptionSubscriberStatus =
+  | "active"
+  | "paused"
+  | "payment_attention"
+  | "verification_hold";
+
+export type SubscriptionRenewalState = "scheduled" | "attention" | "held";
+
+export interface SubscriptionSummary {
+  subscriptionProducts: number;
+  activeSubscribers: number;
+  upcomingRenewalValue: number;
+  needsAttention: number;
+}
+
+export interface SubscriptionCheckoutField {
+  name: string;
+  value: string;
+}
+
+export interface SubscriptionSubscriberRow {
+  id: string;
+  programId: string;
+  customerId: string;
+  customerName: string;
+  email: string;
+  status: SubscriptionSubscriberStatus;
+  verificationState: "verified" | "pending" | "blocked" | "not_required";
+  paymentState: "current" | "attention";
+  nextRenewalAt: string;
+  renewalValue: number;
+}
+
+export interface SubscriptionAttentionRow {
+  id: string;
+  kind: SubscriptionAttentionKind;
+  programId: string;
+  productId: string;
+  customerId: string | null;
+  label: string;
+  detail: string;
+  action: string;
+  tone: "amber" | "red" | "blue";
+  blocking: boolean;
+}
+
+export interface SubscriptionRenewalEvent {
+  id: string;
+  customerId: string;
+  customerName: string;
+  at: string;
+  amount: number;
+  state: SubscriptionRenewalState;
+}
+
+export interface SubscriptionEvidenceEvent {
+  title: string;
+  detail: string;
+  at: string;
+}
+
+export interface SubscriptionProgramRow {
+  id: string;
+  productId: string;
+  productName: string;
+  optionId: string;
+  optionLabel: string;
+  frequency: string;
+  savingsLabel: string | null;
+  priceAdjustmentLabel: string | null;
+  readiness: SubscriptionProgramReadiness;
+  readinessDetail: string;
+  subscriberCount: number;
+  upcomingRenewalValue: number;
+  needsAttentionCount: number;
+}
+
+export interface SubscriptionProgramDetail extends SubscriptionProgramRow {
+  checkoutFields: SubscriptionCheckoutField[];
+  subscribers: SubscriptionSubscriberRow[];
+  upcomingRenewals: SubscriptionRenewalEvent[];
+  evidenceTimeline: SubscriptionEvidenceEvent[];
+  attention: SubscriptionAttentionRow[];
+}
+
+export interface SubscriptionsViewModel {
+  targetTenant: string;
+  summary: SubscriptionSummary;
+  programs: SubscriptionProgramRow[];
+  detailsById: Record<string, SubscriptionProgramDetail>;
+  attention: SubscriptionAttentionRow[];
+}

package/apps/storefront/src/lib/auth/loginGate.ts

@@ -64,11 +64,22 @@ export function parseGateMode(raw: string | null | undefined): GateMode {
 
 /**
  * Paths that MUST stay reachable without a session, or the visitor could never
- * authenticate: the login page and the send/verify endpoints. Everything else on
- * a login-gated host requires a session.
+ * authenticate: the login page, the GET-safe magic-link confirm landing, the
+ * send/verify endpoints, and the exact unauthenticated magic-link resend endpoint.
+ * Everything else on a login-gated host requires a session.
+ *
+ * `/auth/magic` is a PRE-auth entry point — an invitee arrives here with no session
+ * to confirm sign-in. Gating it hands the invitee a "Coming soon" holding page and
+ * dead-ends the onboarding flow (the exact bug when a magic link lands on a gated
+ * host). `/api/auth/magic-exchange` is already covered by the `/api/auth/` prefix.
  */
 export function isAuthPath(pathname: string): boolean {
-  return pathname === "/auth/login" || pathname.startsWith("/api/auth/");
+  return (
+    pathname === "/auth/login" ||
+    pathname === "/auth/magic" ||
+    pathname.startsWith("/api/auth/") ||
+    pathname === "/api/grants/magic-resend"
+  );
 }
 
 /**

package/apps/storefront/src/lib/{foxyCommerce.ts → checkoutCommerce.ts}

@@ -1,39 +1,41 @@
 /**
- * Request-scoped FoxyCart commerce resolution (Track A).
+ * Request-scoped checkout commerce resolution (Track A).
  *
- * Bridges the tenant's static `commerce.foxy` config with runtime env so the
+ * Bridges the tenant's static `commerce.checkout` config with runtime env so the
  * demo store can be swapped without a code change and the signing secret stays
- * out of source:
- *   - `FOXY_STORE_SUBDOMAIN` overrides the tenant's default subdomain (one env
- *     var points every commerce tenant at our shared demo store).
+ * out of source. The env binding names intentionally remain `FOXY_*` because
+ * existing internal developer secrets and provider setup use those operational
+ * names:
+ *   - `FOXY_STORE_SUBDOMAIN` overrides the tenant's default subdomain (one
+ *     env var points every commerce tenant at our shared demo store).
  *   - `FOXY_CART_SECRET` is the cart-validation secret used only in `signed`
  *     mode; the `unsigned-demo` mode never reads it (validation is OFF), which
  *     is what lets a developer run the whole cart locally with zero secrets.
  */
-import type { TenantConfig, ResolvedFoxyCommerce } from "@tot/public-runtime";
-import { resolveFoxyCommerce } from "@tot/public-runtime";
+import type { TenantConfig, ResolvedManagedCheckout } from "@tot/public-runtime";
+import { resolveManagedCheckout } from "@tot/public-runtime";
 import { readEnv } from "@/lib/env";
 
 /**
- * Resolve the effective FoxyCart facts for a tenant, or null when the tenant has
- * no store configured. Applies the `FOXY_STORE_SUBDOMAIN` override.
+ * Resolve the effective checkout facts for a tenant, or null when the tenant has
+ * no store configured. Applies the checkout env overrides.
  */
 export async function resolveTenantCommerce(
   tenant: TenantConfig,
-): Promise<ResolvedFoxyCommerce | null> {
-  const foxy = tenant.commerce?.foxy;
-  if (!foxy) return null;
+): Promise<ResolvedManagedCheckout | null> {
+  const checkout = tenant.commerce?.checkout;
+  if (!checkout) return null;
   // Per-environment overrides so the SAME tenant can point at different stores /
-  // checkout hosts by env: FOXY_STORE_SUBDOMAIN picks the Foxy store; FOXY_STORE_
-  // DOMAIN sets a branded custom checkout domain (e.g. checkout.preview.
+  // checkout hosts by env: FOXY_STORE_SUBDOMAIN picks the checkout store;
+  // FOXY_STORE_DOMAIN sets a branded custom checkout domain (e.g. checkout.preview.
   // tokenoftrust.com on the shared test env, secure.<merchant>.com on live).
   const subOverride = await readEnv("FOXY_STORE_SUBDOMAIN");
   const domainOverride = await readEnv("FOXY_STORE_DOMAIN");
   const storeSubDomain =
-    subOverride && subOverride.length ? subOverride : foxy.storeSubDomain;
+    subOverride && subOverride.length ? subOverride : checkout.storeSubDomain;
   const storeDomain =
-    domainOverride && domainOverride.length ? domainOverride : foxy.storeDomain;
-  return resolveFoxyCommerce({ ...foxy, storeSubDomain, storeDomain });
+    domainOverride && domainOverride.length ? domainOverride : checkout.storeDomain;
+  return resolveManagedCheckout({ ...checkout, storeSubDomain, storeDomain });
 }
 
 /**
@@ -42,7 +44,7 @@ export async function resolveTenantCommerce(
  * no secret is a misconfiguration the caller must handle (fall back to no cart).
  */
 export async function readCartSecret(
-  commerce: ResolvedFoxyCommerce,
+  commerce: ResolvedManagedCheckout,
 ): Promise<string | undefined> {
   if (commerce.mode !== "signed") return undefined;
   return readEnv("FOXY_CART_SECRET");

package/apps/storefront/src/lib/commerce/{foxyCartSettings.ts → checkoutSettings.ts}

@@ -1,17 +1,16 @@
 /**
- * FoxyCart settings model — the admin "Cart & Checkout appearance" section.
+ * Managed checkout settings model — the admin "Cart & Checkout appearance" section.
  *
- * Mirrors the settings surface that the **tot-foxycart** service actually manages
- * (verified against that repo), and defines how each field is PREPOPULATED from
- * the tenant's theme (the style-guide), OVERRIDDEN, and RESET.
+ * Mirrors the settings surface that the commerce service actually manages, and
+ * defines how each field is PREPOPULATED from the tenant's theme (the
+ * style-guide), OVERRIDDEN, and RESET.
  *
- * tot-foxycart's real settings are three groups:
- *   1. `colors`   — Foxy's native `template_config.colors` (primary/secondary/
- *                   tertiary + usage). The only named brand-color fields in the
- *                   Foxy model; documented in tot-foxycart, applied via the theme.
+ * The remote settings are three groups:
+ *   1. `colors`   — provider-native brand colors (primary/secondary/tertiary +
+ *                   usage), applied via the hosted checkout theme.
  *   2. `templates`— per-template-type `contentUrl` pointers (checkout / cart /
- *                   cart_include[sidecart] / receipt / email), set via
- *                   `PUT /theme/foxy` then published via `POST /theme/foxy/refresh`.
+ *                   cart_include[drawer] / receipt / email), set and refreshed
+ *                   through the commerce service.
  *                   The colors/fonts/logo live INSIDE the hosted template file.
  *   3. `store`    — storeSubDomain + loader feature toggles (excise tax, age/ID
  *                   verification). Non-visual; no theme default.
@@ -20,21 +19,21 @@
  * the template pointers (defaulted to a ToT-hosted, theme-derived template URL).
  * The feature toggles are mirrored as plain config (no default → not resettable).
  *
- * The ACTUAL persistence — PATCHing Foxy's colors + PUT/refresh of the template
- * URLs — is the tot-foxycart HTTP seam (`/theme/foxy`), intentionally NOT wired
- * here; this module is the pure model the admin renders and edits.
+ * The ACTUAL persistence — PATCHing provider colors + PUT/refresh of template
+ * URLs — is the commerce-service seam, intentionally NOT wired here; this module
+ * is the pure model the admin renders and edits.
  */
-import type { ResolvedFoxyCommerce, ThemeTokens } from "@tot/public-runtime";
+import type { ResolvedManagedCheckout, ThemeTokens } from "@tot/public-runtime";
 
-/** Foxy template types (tot-foxycart `TEMPLATE_TYPES`). */
-export type FoxyTemplateType =
+/** Checkout template types exposed by the commerce service. */
+export type CheckoutTemplateType =
   | "checkout"
   | "cart"
   | "cart_include"
   | "receipt"
   | "email";
 
-export const FOXY_TEMPLATE_TYPES: readonly FoxyTemplateType[] = [
+export const CHECKOUT_TEMPLATE_TYPES: readonly CheckoutTemplateType[] = [
   "checkout",
   "cart",
   "cart_include",
@@ -42,60 +41,60 @@ export const FOXY_TEMPLATE_TYPES: readonly FoxyTemplateType[] = [
   "email",
 ] as const;
 
-export const FOXY_TEMPLATE_LABELS: Record<FoxyTemplateType, string> = {
+export const CHECKOUT_TEMPLATE_LABELS: Record<CheckoutTemplateType, string> = {
   checkout: "Checkout page",
   cart: "Full cart page",
-  cart_include: "Sidecart (slide-out)",
+  cart_include: "Cart drawer (slide-out)",
   receipt: "Receipt page",
   email: "Order email",
 };
 
-/** Foxy native `template_config.colors` — the only named brand-color fields. */
-export interface FoxyBrandColors {
+/** Hosted checkout brand-color fields. */
+export interface CheckoutBrandColors {
   primary: string;
   secondary: string;
   tertiary: string;
-  /** Foxy's `usage`: how broadly the colors apply. "none" = Foxy default look. */
+  /** How broadly the colors apply. "none" keeps the provider default look. */
   usage: "none" | "all";
 }
 
-/** A per-template-type pointer (mirrors `PUT /theme/foxy`). */
-export interface FoxyTemplatePointer {
+/** A per-template-type pointer managed by the commerce service. */
+export interface CheckoutTemplatePointer {
   contentUrl: string;
   templateSet: string;
 }
 
-/** Store + loader feature config (foxyCartOptions + totOpts). Non-visual. */
-export interface FoxyStoreConfig {
+/** Store + loader feature config. Non-visual. */
+export interface CheckoutStoreConfig {
   storeSubDomain: string;
   exciseTaxCollectionEnabled: boolean;
   verificationEnabled: boolean;
 }
 
-/** The full tot-foxycart settings mirror. */
-export interface FoxyCartSettings {
-  colors: FoxyBrandColors;
-  templates: Record<FoxyTemplateType, FoxyTemplatePointer>;
-  store: FoxyStoreConfig;
+/** The full checkout settings mirror. */
+export interface CheckoutSettings {
+  colors: CheckoutBrandColors;
+  templates: Record<CheckoutTemplateType, CheckoutTemplatePointer>;
+  store: CheckoutStoreConfig;
 }
 
 /** Overrides are a deep-partial of the mirror; anything unset falls back to the
  *  theme-derived default. Reset === delete the key here. */
-export type FoxyCartSettingsOverrides = {
-  colors?: Partial<FoxyBrandColors>;
-  templates?: Partial<Record<FoxyTemplateType, Partial<FoxyTemplatePointer>>>;
-  store?: Partial<FoxyStoreConfig>;
+export type CheckoutSettingsOverrides = {
+  colors?: Partial<CheckoutBrandColors>;
+  templates?: Partial<Record<CheckoutTemplateType, Partial<CheckoutTemplatePointer>>>;
+  store?: Partial<CheckoutStoreConfig>;
 };
 
 // ---------------------------------------------------------------------------
-// Prepopulation: theme (style-guide) → FoxyCart settings defaults.
+// Prepopulation: theme (style-guide) → checkout settings defaults.
 // ---------------------------------------------------------------------------
 
 export interface DeriveOptions {
   /**
    * Absolute origin the ToT-hosted, theme-derived templates are served from —
    * the tenant's own storefront origin (e.g. `https://sample-store.example`). Templates
-   * live at `${originBase}/foxy-templates/<type>.html`.
+   * live at `${originBase}/checkout-templates/<type>.html`.
    */
   originBase: string;
 }
@@ -105,25 +104,25 @@ export interface DeriveOptions {
  * step: brand colors come straight from the theme tokens; each template pointer
  * defaults to a stable ToT-hosted URL for that tenant's theme-derived template.
  */
-export function deriveFoxyCartSettings(
+export function deriveCheckoutSettings(
   theme: ThemeTokens,
-  commerce: ResolvedFoxyCommerce | null,
+  commerce: ResolvedManagedCheckout | null,
   opts: DeriveOptions,
-): FoxyCartSettings {
+): CheckoutSettings {
   const base = opts.originBase.replace(/\/$/, "");
-  const templateUrl = (type: FoxyTemplateType) =>
-    `${base}/foxy-templates/${type}.html`;
+  const templateUrl = (type: CheckoutTemplateType) =>
+    `${base}/checkout-templates/${type}.html`;
 
   const templates = Object.fromEntries(
-    FOXY_TEMPLATE_TYPES.map((type) => [
+    CHECKOUT_TEMPLATE_TYPES.map((type) => [
       type,
       { contentUrl: templateUrl(type), templateSet: "DEFAULT" },
     ]),
-  ) as Record<FoxyTemplateType, FoxyTemplatePointer>;
+  ) as Record<CheckoutTemplateType, CheckoutTemplatePointer>;
 
   return {
     colors: {
-      // Foxy primary/secondary/tertiary ← the tenant's brand tokens.
+      // Checkout primary/secondary/tertiary ← the tenant's brand tokens.
       primary: theme.color.primary,
       secondary: theme.color.accent,
       tertiary: theme.color.sale,
@@ -143,16 +142,16 @@ export function deriveFoxyCartSettings(
 // Resolve with provenance: defaults + overrides → renderable field descriptors.
 // ---------------------------------------------------------------------------
 
-export type FoxyFieldKind = "color" | "url" | "text" | "boolean" | "select";
-export type FoxyFieldGroup = "colors" | "templates" | "store";
+export type CheckoutFieldKind = "color" | "url" | "text" | "boolean" | "select";
+export type CheckoutFieldGroup = "colors" | "templates" | "store";
 
 /** One renderable settings row: resolved value + provenance + reset affordance. */
-export interface FoxySettingsField {
-  group: FoxyFieldGroup;
-  /** Dot path into FoxyCartSettings, e.g. "colors.primary" / "templates.checkout.contentUrl". */
+export interface CheckoutSettingsField {
+  group: CheckoutFieldGroup;
+  /** Dot path into CheckoutSettings, e.g. "colors.primary" / "templates.checkout.contentUrl". */
   key: string;
   label: string;
-  kind: FoxyFieldKind;
+  kind: CheckoutFieldKind;
   value: string | boolean;
   /** The theme-derived default; undefined when the field has no theme default. */
   default?: string | boolean;
@@ -178,17 +177,17 @@ function readPath(obj: unknown, path: string): unknown {
  * path, else "theme". `resettable` marks fields with a real theme default (the
  * visual ones) so the UI can show/hide the "Reset to theme" control.
  */
-export function buildFoxySettingsFields(
-  defaults: FoxyCartSettings,
-  overrides: FoxyCartSettingsOverrides,
-): FoxySettingsField[] {
+export function buildCheckoutSettingsFields(
+  defaults: CheckoutSettings,
+  overrides: CheckoutSettingsOverrides,
+): CheckoutSettingsField[] {
   const field = (
-    group: FoxyFieldGroup,
+    group: CheckoutFieldGroup,
     key: string,
     label: string,
-    kind: FoxyFieldKind,
+    kind: CheckoutFieldKind,
     opts: { resettable?: boolean; options?: string[]; help?: string } = {},
-  ): FoxySettingsField => {
+  ): CheckoutSettingsField => {
     const def = readPath(defaults, key);
     const ov = readPath(overrides, key);
     const overridden = ov !== undefined;
@@ -207,7 +206,7 @@ export function buildFoxySettingsFields(
     };
   };
 
-  const fields: FoxySettingsField[] = [
+  const fields: CheckoutSettingsField[] = [
     // Group 1 — brand colors (theme-derived; the "make it look bigd" surface).
     field("colors", "colors.primary", "Primary color", "color", {
       help: "Checkout/cart primary buttons and accents. From --color-primary.",
@@ -220,28 +219,28 @@ export function buildFoxySettingsFields(
     }),
     field("colors", "colors.usage", "Apply brand colors", "select", {
       options: ["all", "none"],
-      help: '"all" applies the brand palette to Foxy; "none" keeps Foxy defaults.',
+      help: '"all" applies the brand palette to hosted checkout; "none" keeps checkout defaults.',
     }),
   ];
 
   // Group 2 — template pointers (default = ToT-hosted theme-derived template).
-  for (const type of FOXY_TEMPLATE_TYPES) {
+  for (const type of CHECKOUT_TEMPLATE_TYPES) {
     fields.push(
-      field("templates", `templates.${type}.contentUrl`, FOXY_TEMPLATE_LABELS[type], "url", {
-        help: `Hosted template URL for the ${FOXY_TEMPLATE_LABELS[type].toLowerCase()}. Defaults to the ToT theme-derived template; override with a custom URL.`,
+      field("templates", `templates.${type}.contentUrl`, CHECKOUT_TEMPLATE_LABELS[type], "url", {
+        help: `Hosted template URL for the ${CHECKOUT_TEMPLATE_LABELS[type].toLowerCase()}. Defaults to the ToT theme-derived template; override with a custom URL.`,
       }),
     );
   }
 
   // Group 3 — store/feature config (no theme default → not resettable).
   fields.push(
-    field("store", "store.storeSubDomain", "Foxy store subdomain", "text", {
+    field("store", "store.storeSubDomain", "Checkout store subdomain", "text", {
       resettable: false,
-      help: "The <sub>.foxycart.com store this tenant checks out through.",
+      help: "Internal checkout store identifier for this tenant.",
     }),
     field("store", "store.exciseTaxCollectionEnabled", "Collect excise tax", "boolean", {
       resettable: false,
-      help: "tot-foxycart pre-cart excise tax collection.",
+      help: "Managed pre-cart excise tax collection.",
     }),
     field("store", "store.verificationEnabled", "Age / identity verification", "boolean", {
       resettable: false,

package/apps/storefront/src/lib/dev/activityIngestToken.ts

@@ -25,6 +25,15 @@ export interface ActivityIngestClaims {
   email: string;
   tenant: string;
   capability: string;
+  /**
+   * The invite→terminal→problem TRACE id, minted once when this developer's
+   * sign-in code was issued (see api/dev/cli-signin-code.ts). It rides in the
+   * claims so every runtime/activity write the local loop makes with this token
+   * is stampable with the same id — support looks a live session up by it.
+   * Optional so tokens minted before this field existed still verify (they just
+   * carry no trace); every freshly-minted token sets it.
+   */
+  traceId?: string;
 }
 
 function newToken(): string {

package/apps/storefront/src/lib/dev/activityStore.ts

@@ -14,6 +14,12 @@ export interface ActivityEvent {
   event: ActivityEventKind;
   /** Epoch ms, as reported by the local loop. */
   at: number;
+  /**
+   * The invite→terminal→problem TRACE id, stamped from the ingest-token claims
+   * (never the body) so a file save is attributable to the same span as the
+   * runtime record. Absent on events written by tokens minted before tracing.
+   */
+  traceId?: string;
 }
 
 const KEY_PREFIX = "dev-activity:";
@@ -48,6 +54,12 @@ export async function appendActivity(
   await kv.put(key(appDomain), JSON.stringify(next), { expirationTtl: TTL_SECONDS });
 }
 
+/** Delete the vendor's activity ring buffer — part of a "true reset" so stale saves
+ * don't re-complete Step 1 after the developer stops their local loop. */
+export async function clearActivity(kv: KVNamespace, appDomain: string): Promise<void> {
+  await kv.delete(key(appDomain));
+}
+
 /**
  * Business-readable translation of a reported file path + event, for the
  * activity log. File-level only — no per-line diff enrichment (Darrin,