@tokenoftrust/storefront-runner 1.3.2

package/apps/storefront/src/components/plp/SortSelect.astro

@@ -0,0 +1,64 @@
+---
+/**
+ * Sort control. A plain <form> select that auto-submits on change — works without
+ * a framework, stays URL-addressable. The current query's other params ride
+ * along as hidden inputs so sort doesn't drop active filters.
+ *
+ * Auto-submit is wired by a nonce'd `is:inline` <script> rather than an inline
+ * `onchange=` handler, so a strict, ENFORCED CSP allows it without 'unsafe-inline'
+ * / 'unsafe-hashes' (Epic S2). The <noscript> Apply button covers the no-JS case.
+ */
+import type { ListProductsQuery } from "@tot/public-runtime";
+
+interface Props {
+  query: ListProductsQuery;
+  basePath: string;
+}
+const { query, basePath } = Astro.props;
+
+const OPTIONS: { value: NonNullable<ListProductsQuery["sort"]>; label: string }[] = [
+  { value: "featured", label: "Featured" },
+  { value: "newest", label: "Newest" },
+  { value: "price-asc", label: "Price: Low to High" },
+  { value: "price-desc", label: "Price: High to Low" },
+  { value: "title-asc", label: "Alphabetical (A–Z)" },
+];
+const current = query.sort ?? "featured";
+---
+
+<form method="get" action={basePath} class="flex items-center gap-2 text-sm">
+  {/* Preserve filters/price/availability/q across a sort change. */}
+  {query.q && <input type="hidden" name="q" value={query.q} />}
+  {query.availability && query.availability !== "all" && (
+    <input type="hidden" name="availability" value={query.availability} />
+  )}
+  {query.priceMin != null && <input type="hidden" name="priceMin" value={query.priceMin} />}
+  {query.priceMax != null && <input type="hidden" name="priceMax" value={query.priceMax} />}
+  {Object.entries(query.filters ?? {}).flatMap(([name, values]) =>
+    values.map((v) => (
+      <input type="hidden" name={name === "tags" ? "tag" : `opt.${name}`} value={v} />
+    )),
+  )}
+
+  <label for="sort" class="text-[var(--color-muted)]">Sort</label>
+  <select
+    id="sort"
+    name="sort"
+    data-sort-autosubmit
+    class="rounded-[var(--radius-sm)] border border-[var(--color-border)] bg-[var(--color-surface)] px-3 py-1.5 font-display"
+  >
+    {OPTIONS.map((o) => (
+      <option value={o.value} selected={o.value === current}>{o.label}</option>
+    ))}
+  </select>
+  <noscript><button type="submit" class="underline">Apply</button></noscript>
+</form>
+
+<script is:inline nonce={Astro.locals.cspNonce}>
+  // Progressive enhancement: submit the form when the sort changes. Nonce'd
+  // inline (the platform pattern for app-authored inline JS) so a strict,
+  // ENFORCED CSP allows it without 'unsafe-inline'.
+  for (const el of document.querySelectorAll("select[data-sort-autosubmit]")) {
+    el.addEventListener("change", () => el.form && el.form.submit());
+  }
+</script>

package/apps/storefront/src/components/style-guide/StyleGuideNav.astro

@@ -0,0 +1,95 @@
+---
+/**
+ * Persistent left-hand navigation for the preview/dev style-guide surfaces.
+ *
+ * Markup-only (no <style>): the host page owns the `.sg-nav*` styles inside its
+ * nonce'd <style> block, so this component stays CSP-clean under the strict
+ * inline-style policy (build.inlineStylesheets:"never"). Rendered on the tenant
+ * hub, the widget-library guide, and any per-theme guide that wants a persistent
+ * rail so the Widget Library Guide is one click away from the top page.
+ *
+ * Accessibility: every entry is a real <a>; the active entry carries
+ * aria-current="page". When `headings` is supplied (the guide's H2 outline) a
+ * nested table of contents is rendered as in-page anchor links.
+ */
+type Active = "index" | "tenant" | "components" | "chrome" | "guide";
+
+interface Heading {
+  depth: number;
+  slug: string;
+  text: string;
+}
+
+interface Props {
+  tenant: string;
+  /** Current theme id — needed to build the per-theme component/chrome/guide links. */
+  theme?: string;
+  active: Active;
+  /** Optional H2 outline of the guide, rendered as an in-page TOC under the guide entry. */
+  headings?: Heading[];
+}
+
+const { tenant, theme, active, headings = [] } = Astro.props;
+
+const base = `/_style-guide`;
+// Per-theme surfaces only resolve when we know which theme to skin with.
+const componentsHref = theme ? `${base}/${tenant}/${theme}/` : undefined;
+const chromeHref = theme ? `${base}/${tenant}/chrome/${theme}/` : undefined;
+const guideHref = theme ? `${base}/${tenant}/guide/${theme}/` : undefined;
+
+const toc = headings.filter((h) => h.depth === 2);
+---
+
+<nav class="sg-nav" aria-label="Style guide">
+  <p class="sg-nav__eyebrow">Style guide</p>
+  <ul class="sg-nav__list">
+    <li>
+      <a
+        href={`${base}/`}
+        class:list={["sg-nav__link", { "is-active": active === "index" }]}
+        aria-current={active === "index" ? "page" : undefined}
+      >All client guides</a>
+    </li>
+    <li>
+      <a
+        href={`${base}/${tenant}/`}
+        class:list={["sg-nav__link", { "is-active": active === "tenant" }]}
+        aria-current={active === "tenant" ? "page" : undefined}
+      >{tenant} — overview</a>
+    </li>
+    {componentsHref && (
+      <li>
+        <a
+          href={componentsHref}
+          class:list={["sg-nav__link", "sg-nav__link--sub", { "is-active": active === "components" }]}
+          aria-current={active === "components" ? "page" : undefined}
+        >Components</a>
+      </li>
+    )}
+    {chromeHref && (
+      <li>
+        <a
+          href={chromeHref}
+          class:list={["sg-nav__link", "sg-nav__link--sub", { "is-active": active === "chrome" }]}
+          aria-current={active === "chrome" ? "page" : undefined}
+        >Shared chrome</a>
+      </li>
+    )}
+    {guideHref && (
+      <li>
+        <a
+          href={guideHref}
+          class:list={["sg-nav__link", "sg-nav__link--sub", { "is-active": active === "guide" }]}
+          aria-current={active === "guide" ? "page" : undefined}
+        >Widget Library Guide</a>
+        {active === "guide" && toc.length > 0 && (
+          <ul class="sg-nav__toc">
+            {toc.map((h) => (
+              <li><a class="sg-nav__toc-link" href={`#${h.slug}`}>{h.text}</a></li>
+            ))}
+          </ul>
+        )}
+      </li>
+    )}
+  </ul>
+</nav>

package/apps/storefront/src/components/subscription/HowItWorksSteps.astro

@@ -0,0 +1,67 @@
+---
+/**
+ * <HowItWorksSteps> — the Autopilot/subscription "how it works" explainer
+ * (e.g. Choose products → Set your schedule → We ship on autopilot → Pause or
+ * cancel anytime). Presentational + EDUCATION ONLY: it walks through the
+ * concept, but ships NO scheduling, billing, or subscription mechanics — a
+ * tenant wires the real subscribe flow in the product/commerce layer.
+ *
+ * Token-styled only — re-skins entirely from the theme's contract tokens
+ * (--color-…, --radius-…); no hardcoded brand color.
+ * data-widget="subscription-how-it-works" is the audit/test hook.
+ */
+import type { SubscriptionStep } from "@/lib/subscription/model";
+
+interface Props {
+  steps: SubscriptionStep[];
+  /** Optional small eyebrow above the heading. */
+  eyebrow?: string;
+  /** Optional section heading. */
+  heading?: string;
+  /** Optional supporting sentence under the heading. */
+  subhead?: string;
+}
+
+const { steps, eyebrow, heading, subhead } = Astro.props;
+---
+
+{
+  steps.length > 0 && (
+    <section class="container-prose" data-widget="subscription-how-it-works">
+      {(eyebrow || heading || subhead) && (
+        <header class="mb-8 text-center">
+          {eyebrow && (
+            <p class="mb-2 text-xs font-semibold uppercase tracking-[0.12em] text-[var(--color-accent-ink)]">
+              {eyebrow}
+            </p>
+          )}
+          {heading && (
+            <h2 class="font-display text-2xl font-bold text-[var(--color-text)] sm:text-3xl">
+              {heading}
+            </h2>
+          )}
+          {subhead && (
+            <p class="mx-auto mt-3 max-w-[60ch] text-[var(--color-muted)]">{subhead}</p>
+          )}
+        </header>
+      )}
+
+      <ol class="grid gap-6 sm:grid-cols-2 lg:grid-cols-4">
+        {steps.map((step, i) => (
+          <li class="flex flex-col rounded-[var(--radius-lg)] border border-[var(--color-border)] bg-[var(--color-surface)] p-5">
+            <span
+              class="mb-3 flex h-8 w-8 items-center justify-center rounded-[var(--radius-full)] bg-[var(--color-primary)] text-sm font-bold text-[var(--color-primary-contrast)]"
+              aria-hidden="true"
+            >
+              {i + 1}
+            </span>
+            <h3 class="font-display text-base font-semibold text-[var(--color-text)]">
+              {step.title}
+            </h3>
+            <p class="mt-1.5 text-sm text-[var(--color-muted)]">{step.description}</p>
+          </li>
+        ))}
+      </ol>
+    </section>
+  )
+}

package/apps/storefront/src/components/subscription/ManageSubscriptionEntry.astro

@@ -0,0 +1,67 @@
+---
+/**
+ * <ManageSubscriptionEntry> — a set of manage-subscription entry points (e.g.
+ * "Update delivery date", "Pause or cancel anytime"). Presentational +
+ * EDUCATION/HANDOFF ONLY: each entry is a plain link into the tenant's own
+ * (product-owned) manage-subscription flow — the widget never renders
+ * scheduling, billing, or cancellation controls of its own.
+ *
+ * Token-styled only; data-widget="subscription-manage-entry" is the
+ * audit/test hook.
+ */
+import type { SubscriptionManageEntry } from "@/lib/subscription/model";
+
+interface Props {
+  entries: SubscriptionManageEntry[];
+  /** Optional small eyebrow above the heading. */
+  eyebrow?: string;
+  /** Optional section heading. */
+  heading?: string;
+  /** Optional supporting sentence under the heading. */
+  subhead?: string;
+}
+
+const { entries, eyebrow, heading, subhead } = Astro.props;
+---
+
+{
+  entries.length > 0 && (
+    <section class="container-prose" data-widget="subscription-manage-entry">
+      {(eyebrow || heading || subhead) && (
+        <header class="mb-8 text-center">
+          {eyebrow && (
+            <p class="mb-2 text-xs font-semibold uppercase tracking-[0.12em] text-[var(--color-accent-ink)]">
+              {eyebrow}
+            </p>
+          )}
+          {heading && (
+            <h2 class="font-display text-2xl font-bold text-[var(--color-text)] sm:text-3xl">
+              {heading}
+            </h2>
+          )}
+          {subhead && (
+            <p class="mx-auto mt-3 max-w-[60ch] text-[var(--color-muted)]">{subhead}</p>
+          )}
+        </header>
+      )}
+
+      <ul class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+        {entries.map((entry) => (
+          <li>
+            <a
+              href={entry.href}
+              class="flex min-h-[44px] flex-col rounded-[var(--radius-lg)] border border-[var(--color-border)] bg-[var(--color-surface)] p-4 transition-colors hover:border-[var(--color-primary)]"
+            >
+              <span class="font-display text-base font-semibold text-[var(--color-text)]">
+                {entry.label}
+              </span>
+              {entry.description && (
+                <span class="mt-1 text-sm text-[var(--color-muted)]">{entry.description}</span>
+              )}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </section>
+  )
+}

package/apps/storefront/src/components/subscription/SavingsExplainer.astro

@@ -0,0 +1,101 @@
+---
+/**
+ * <SavingsExplainer> — the Autopilot/subscription savings headline (e.g.
+ * "Save 15% — vs. one-time purchase") with supporting bullets and a plain
+ * handoff CTA. Presentational + EDUCATION ONLY: no pricing, billing, or
+ * subscription mechanics — the CTA is a link into the tenant's own
+ * (product-owned) subscribe/learn flow.
+ *
+ * Illustrative-figure affordance (decision compliance-widgets-platform-owned):
+ * the figure is treated as an EXAMPLE by default (isIllustrative). When
+ * illustrative, the figure carries an "e.g." affordance + a first-class
+ * <IllustrativeLabel> badge/footnote so an example number is never presented
+ * as a live offer. A tenant opts out only by asserting `real: true` on a
+ * confirmed live value.
+ *
+ * Token-styled only; data-widget="subscription-savings-explainer" is the
+ * audit/test hook.
+ */
+import type { SubscriptionFigure } from "@/lib/subscription/model";
+import { isIllustrative } from "@/lib/subscription/model";
+import IllustrativeLabel from "@/components/membership/IllustrativeLabel.astro";
+
+interface Props {
+  figure: SubscriptionFigure;
+  /** Optional small eyebrow above the heading. */
+  eyebrow?: string;
+  /** Optional section heading. */
+  heading?: string;
+  /** Supporting bullets, e.g. "Free shipping on every order". */
+  bullets?: string[];
+  /** Education/handoff CTA (never a checkout mechanic). */
+  cta?: { label: string; href: string };
+}
+
+const { figure, eyebrow, heading, bullets, cta } = Astro.props;
+const illustrative = isIllustrative(figure);
+---
+
+<section class="container-prose" data-widget="subscription-savings-explainer">
+  <div class="flex flex-col items-center rounded-[var(--radius-lg)] border border-[var(--color-border)] bg-[var(--color-surface)] p-8 text-center">
+    {eyebrow && (
+      <p class="mb-2 text-xs font-semibold uppercase tracking-[0.12em] text-[var(--color-accent-ink)]">
+        {eyebrow}
+      </p>
+    )}
+    {heading && (
+      <h2 class="font-display text-2xl font-bold text-[var(--color-text)] sm:text-3xl">
+        {heading}
+      </h2>
+    )}
+
+    <p
+      class="mt-4 flex items-baseline gap-1.5"
+      data-illustrative={illustrative ? "figure" : undefined}
+    >
+      {illustrative && (
+        <span class="text-xs font-medium text-[var(--color-muted)]" title="Illustrative example">
+          e.g.
+        </span>
+      )}
+      <span class="font-display text-4xl font-bold leading-none text-[var(--color-text)]">
+        {figure.value}
+      </span>
+      {figure.caption && (
+        <span class="text-sm text-[var(--color-muted)]">{figure.caption}</span>
+      )}
+    </p>
+
+    {illustrative && (
+      <div class="mt-3">
+        <IllustrativeLabel as="badge" />
+      </div>
+    )}
+
+    {bullets && bullets.length > 0 && (
+      <ul class="mt-6 space-y-2 text-left">
+        {bullets.map((b) => (
+          <li class="flex items-start gap-2.5 text-sm text-[var(--color-text)]">
+            <span aria-hidden="true" class="mt-0.5 text-[var(--color-success)]">✓</span>
+            <span>{b}</span>
+          </li>
+        ))}
+      </ul>
+    )}
+
+    {cta && (
+      <a
+        href={cta.href}
+        class="mt-6 inline-flex min-h-[44px] items-center justify-center rounded-[var(--radius-full)] bg-[var(--color-primary)] px-5 py-2.5 text-sm font-semibold text-[var(--color-primary-contrast)]"
+      >
+        {cta.label}
+      </a>
+    )}
+
+    {illustrative && (
+      <div class="mt-5">
+        <IllustrativeLabel as="note" />
+      </div>
+    )}
+  </div>
+</section>

package/apps/storefront/src/config/adminTargetTenant.ts

@@ -0,0 +1,28 @@
+/**
+ * Resolve an admin console TARGET tenant's full config through the sanctioned
+ * TenantResolver seam.
+ *
+ * The admin console can operate on a target tenant that differs from the routed
+ * (adminApp) tenant on `Astro.locals.tenant` — a real ToT-staff session may point
+ * `targetTenant` at another tenant it has access to (see lib/adminTenantEnvelope).
+ * Panels that need the target's real config (e.g. the FoxyCart cart-appearance
+ * panel, which derives from `theme_tokens` + `commerce.foxy`) resolve it HERE,
+ * in the config layer, rather than reaching into the static tenant map — so they
+ * stay behind the `tenancy-resolver-fence` (.dependency-cruiser.cjs) and a
+ * single-tenant extraction stays a drop-in (the concrete resolver is swapped, not
+ * the callers). Mirrors the config-layer `previewTenantLookup` seam.
+ *
+ * Resolution is by the tenant's canonical host: the envelope's `targetTenant` is
+ * an appDomain, which the registered tenants also claim in `domains`, so
+ * `resolveStrict` matches it and never falls back to a default (an id owning no
+ * tenant returns null — the panel then renders its inert "no store" state).
+ */
+import type { TenantConfig } from "@tot/public-runtime";
+import { getTenantResolver } from "@/config/resolver";
+
+export async function resolveAdminTargetTenant(
+  targetTenant: string,
+): Promise<TenantConfig | null> {
+  const resolver = await getTenantResolver();
+  return resolver.resolveStrict(targetTenant);
+}

package/apps/storefront/src/config/devTenantSeed.ts

@@ -0,0 +1,78 @@
+/**
+ * Dev-loop tenant synthesis (LOCAL dev only).
+ *
+ * The local dev loop (`tot dev` — scripts/tot-dev.mjs) serves a developer's OWN
+ * checked-out tenant by grafting the checkout into the colocated `tenants/<id>/`
+ * layout the app globs (content/, public/, theme.json). But the tenant RESOLVER
+ * only knows the hardcoded `staticTenants` registry — so an ARBITRARY invited
+ * developer's tenant (never in that list) 404s at `/<appDomain>/`, even though
+ * its content + theme are already on disk. That coupling is wrong for the dev
+ * loop: staticTenants is for the bundled demos, not for whoever runs `tot dev`.
+ *
+ * This synthesizes a MINIMAL, servable TenantConfig for each local tenant DIR
+ * that isn't already a static tenant, so the dev resolver seeds + resolves it.
+ * The tenant's identity IS its dir name (the colocation convention: dir ==
+ * tenant_id == appDomain == tot_data_scope). Content (content/home.html) and
+ * theme (theme.json) come straight from the checkout via the existing dir globs;
+ * catalog/compliance data it lacks DEGRADES to empty — siteType "marketing"
+ * means no catalog is required, and index.astro serves the raw home.html before
+ * any product resolution, so the tenant root renders instead of 404ing.
+ *
+ * DEV ONLY: in prod the TENANT_CACHE KV drives the resolver and staticTenants is
+ * the seed; this path is never taken. Kept inside `src/config` per the
+ * tenancy-resolver-fence — the concrete registry stays behind the config boundary.
+ */
+import type { DeepPartial, TenantConfig, ThemeTokens } from "@tot/public-runtime";
+
+/**
+ * A minimal servable TenantConfig whose identity is its colocated dir name.
+ * No Storyblok space (a "PLACEHOLDER" token → LocalContentProvider serves the
+ * checkout's content/), no catalog/compliance (siteType "marketing" degrades
+ * commerce to empty). Theme tokens come from the checkout's theme.json.
+ */
+export function synthesizeDevTenant(
+  id: string,
+  themeTokens: DeepPartial<ThemeTokens>,
+): TenantConfig {
+  return {
+    tenant_id: id,
+    appDomain: id,
+    domains: [id],
+    canonicalDomain: id,
+    displayName: id,
+    // Contains "PLACEHOLDER" → createContentProvider picks LocalContentProvider,
+    // which serves the checkout's content/home.html (globbed by dir == this id).
+    storyblok_space_token: "STORYBLOK_DEV_TENANT_TOKEN_PLACEHOLDER",
+    tot_data_scope: id,
+    currency: "USD",
+    locale: "en-US",
+    theme_tokens: themeTokens,
+    // No bundled catalog for an arbitrary dev tenant → serve the raw marketing
+    // home and degrade commerce to empty rather than 404 the tenant root.
+    siteType: "marketing",
+  };
+}
+
+/**
+ * The dev tenants to seed ALONGSIDE staticTenants: one synthesized config per
+ * local tenant dir that isn't already a static tenant (those keep their richer
+ * hardcoded config). `themeFor` supplies each dir's theme tokens.
+ *
+ * @param localDirIds dir names discovered under `tenants/*` (dir == tenant id)
+ * @param staticIds   tenant_ids already in the static registry (skipped)
+ * @param themeFor    theme-token lookup by dir/tenant id
+ */
+export function devTenantsToSeed(
+  localDirIds: Iterable<string>,
+  staticIds: ReadonlySet<string>,
+  themeFor: (id: string) => DeepPartial<ThemeTokens>,
+): TenantConfig[] {
+  const out: TenantConfig[] = [];
+  const seen = new Set<string>();
+  for (const id of localDirIds) {
+    if (!id || staticIds.has(id) || seen.has(id)) continue;
+    seen.add(id);
+    out.push(synthesizeDevTenant(id, themeFor(id)));
+  }
+  return out;
+}

package/apps/storefront/src/config/devTenants.ts

@@ -0,0 +1,16 @@
+/**
+ * Dev-only tenant-registry seam for the localhost sign-in bypass.
+ *
+ * `lib/auth/devAuth` can't import the concrete static tenant map directly
+ * (tenancy-resolver-fence — the registry stays behind the `config` boundary so a
+ * single-tenant extraction stays a drop-in). This exposes exactly the one thing
+ * that bypass needs: the resources a local dev session is granted membership on.
+ * In a single-tenant extraction this collapses to that one tenant with no change
+ * to devAuth. Same shape of config seam as {@link ./previewTenantLookup}.
+ */
+import { staticTenants } from "@/config/tenants";
+
+/** Every registered tenant's resource id (appDomain, falling back to tenant_id). */
+export function devTenantResources(): string[] {
+  return staticTenants.map((t) => t.appDomain ?? t.tenant_id);
+}

package/apps/storefront/src/config/kvTenantResolver.ts

@@ -0,0 +1,87 @@
+/**
+ * KV-backed tenant resolver — the many-tenant path documented in
+ * src/config/tenants.ts and wrangler.toml ([[kv_namespaces]] TENANT_CACHE).
+ *
+ * It implements the SAME `TenantResolver` interface as StaticTenantResolver, so
+ * middleware, pages, and the /<domain>/* path routing are untouched — only the
+ * backing store changes. Tenants are added by WRITING to KV (see putTenant),
+ * not by editing code, so onboarding/migration can register a store at runtime.
+ *
+ * KV layout:
+ *   domain:<host>          -> tenant_id        (one per claimed hostname)
+ *   tenant:<tenant_id>     -> JSON TenantConfig
+ *   config:default_tenant  -> tenant_id        (unknown-host fallback)
+ *
+ * A static `fallback` resolver is consulted when KV has no entry, so the system
+ * keeps working before KV is seeded and during a gradual cutover from static.
+ */
+import type { TenantConfig, TenantResolver } from "@tot/public-runtime";
+
+const DOMAIN_PREFIX = "domain:";
+const TENANT_PREFIX = "tenant:";
+const DEFAULT_KEY = "config:default_tenant";
+// Edge-cache KV reads briefly; tenant config changes are rare and propagate
+// within this window. Bump down if you need faster propagation after a write.
+const CACHE_TTL = 300;
+
+function cleanHost(host: string): string {
+  return host.toLowerCase().split(":")[0]?.trim() ?? "";
+}
+
+export class KvTenantResolver implements TenantResolver {
+  constructor(
+    private readonly kv: KVNamespace,
+    /** Consulted when KV has no record (pre-seed / gradual cutover). */
+    private readonly fallback?: TenantResolver,
+  ) {}
+
+  private async readTenant(id: string): Promise<TenantConfig | null> {
+    const raw = await this.kv.get(TENANT_PREFIX + id, { cacheTtl: CACHE_TTL });
+    if (!raw) return null;
+    try {
+      return JSON.parse(raw) as TenantConfig;
+    } catch {
+      return null;
+    }
+  }
+
+  async resolveStrict(host: string): Promise<TenantConfig | null> {
+    const clean = cleanHost(host);
+    if (!clean) return null;
+    const id = await this.kv.get(DOMAIN_PREFIX + clean, { cacheTtl: CACHE_TTL });
+    if (id) {
+      const tenant = await this.readTenant(id);
+      if (tenant) return tenant;
+    }
+    return this.fallback ? this.fallback.resolveStrict(host) : null;
+  }
+
+  async resolveByHost(host: string): Promise<TenantConfig | null> {
+    const strict = await this.resolveStrict(host);
+    if (strict) return strict;
+    const defaultId = await this.kv.get(DEFAULT_KEY, { cacheTtl: CACHE_TTL });
+    if (defaultId) {
+      const tenant = await this.readTenant(defaultId);
+      if (tenant) return tenant;
+    }
+    return this.fallback ? this.fallback.resolveByHost(host) : null;
+  }
+}
+
+/**
+ * Register (or update) a tenant in KV. Idempotent: writes the config blob and a
+ * domain->id index entry for each claimed hostname. Pass `makeDefault` to point
+ * the unknown-host fallback at this tenant. Call this from onboarding/migration.
+ */
+export async function putTenant(
+  kv: KVNamespace,
+  config: TenantConfig,
+  opts: { makeDefault?: boolean } = {},
+): Promise<void> {
+  await kv.put(TENANT_PREFIX + config.tenant_id, JSON.stringify(config));
+  for (const domain of config.domains) {
+    const host = cleanHost(domain);
+    if (host) await kv.put(DOMAIN_PREFIX + host, config.tenant_id);
+  }
+  if (opts.makeDefault) await kv.put(DEFAULT_KEY, config.tenant_id);
+}