@tokenoftrust/cli 1.3.3 → 1.3.4-rc.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.3.3",
+  "version": "1.3.4-rc.0",
   "description": "Token of Trust developer CLI — check out a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/auth.mjs

@@ -31,13 +31,74 @@ import { recordServerPolicy } from "./update-check.mjs";
 
 /** Thrown when no provider can authenticate — carries actionable guidance. */
 export class AuthUnavailableError extends Error {
-  constructor(message, { hint } = {}) {
+  constructor(message, { hint, reason } = {}) {
     super(message);
     this.name = "AuthUnavailableError";
     this.hint = hint || null;
+    this.reason = reason || null;
   }
 }
 
+const FULL_EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const SAFE_EMAIL_HINT_RE = /^[a-z0-9._%+\-]{1,96}@[a-z0-9.-]{1,96}\.[a-z]{2,63}$/i;
+
+function maskEmailPart(part) {
+  if (part.length <= 2) return `${part.slice(0, 1)}...`;
+  return `${part.slice(0, 1)}...${part.slice(-1)}`;
+}
+
+/** Display-only email hint for URLs/log-safe UX. Never returns the full address. */
+export function redactEmailForHint(email) {
+  const raw = String(email || "").trim().toLowerCase();
+  const at = raw.indexOf("@");
+  if (at <= 0) return null;
+  const local = raw.slice(0, at);
+  const domain = raw.slice(at + 1);
+  const parts = domain.split(".").filter(Boolean);
+  if (parts.length < 2) return null;
+  const suffix = parts.pop();
+  const registrable = parts.join(".");
+  if (!suffix || !registrable) return null;
+  return `${maskEmailPart(local)}@${maskEmailPart(registrable)}.${suffix}`;
+}
+
+export function normalizeEmailHint(input) {
+  const raw = String(input || "").trim().toLowerCase();
+  if (!raw || raw.length > 160 || /\s/.test(raw) || !raw.includes("@")) return null;
+  if (FULL_EMAIL_RE.test(raw) && !raw.includes("...")) return redactEmailForHint(raw);
+  return SAFE_EMAIL_HINT_RE.test(raw) ? raw : null;
+}
+
+export function credentialEmailHint(creds) {
+  return (
+    normalizeEmailHint(creds?.emailHint) ||
+    normalizeEmailHint(creds?.email) ||
+    redactEmailForHint(emailFromJwt(creds?.accessToken || "") || "")
+  );
+}
+
+/** Hosted cockpit URL for regenerating local CLI credentials, when we cached one. */
+export function cockpitRecoveryUrl(activityUrl, emailHint = null) {
+  if (!activityUrl) return null;
+  try {
+    const url = new URL("/cockpit?recover=cli", String(activityUrl));
+    const hint = normalizeEmailHint(emailHint);
+    if (hint) url.searchParams.set("email_hint", hint);
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+
+/** Next-step copy for a stale local developer credential. */
+export function developerCredentialRecoveryHint(creds) {
+  const url = cockpitRecoveryUrl(creds?.activityUrl, credentialEmailHint(creds));
+  if (url) {
+    return `open ${url}, sign in if prompted, click "Generate a fresh setup command", then paste it into your terminal.`;
+  }
+  return "run `tot login` to sign in again.";
+}
+
 /** True when a full operator credential triple is present in the environment. */
 export function hasOperatorCreds(env = process.env) {
   return Boolean(env.TOT_API_KEY && env.TOT_SECRET_KEY && env.TOT_APP_DOMAIN);
@@ -95,7 +156,10 @@ export async function resolveDeveloperSession(client, env, deps = {}) {
   if (!creds || !creds.accessToken) {
     throw new AuthUnavailableError(
       "you're not signed in to Token of Trust.",
-      { hint: "run `tot login` to sign in (or `tot login --code <token>` to paste your invite token), then re-run." },
+      {
+        reason: "missing",
+        hint: "run `tot login` to sign in (or `tot login --code <token>` to paste your invite token), then re-run.",
+      },
     );
   }
 
@@ -103,7 +167,7 @@ export async function resolveDeveloperSession(client, env, deps = {}) {
     if (!creds.refreshToken || !creds.tokenEndpoint) {
       throw new AuthUnavailableError(
         "your Token of Trust session has expired.",
-        { hint: "run `tot login` to sign in again." },
+        { reason: "expired", hint: developerCredentialRecoveryHint(creds) },
       );
     }
     let refreshed;
@@ -116,7 +180,7 @@ export async function resolveDeveloperSession(client, env, deps = {}) {
     } catch (e) {
       throw new AuthUnavailableError(
         `couldn't refresh your Token of Trust session: ${e?.message || e}`,
-        { hint: "run `tot login` to sign in again." },
+        { reason: "refreshFailed", hint: developerCredentialRecoveryHint(creds) },
       );
     }
     const prior = creds;
@@ -138,6 +202,9 @@ export async function resolveDeveloperSession(client, env, deps = {}) {
       creds.activityToken = prior.activityToken;
       creds.activityUrl = prior.activityUrl;
     }
+    if (prior.traceId) creds.traceId = prior.traceId;
+    const priorEmailHint = credentialEmailHint(prior);
+    if (priorEmailHint) creds.emailHint = priorEmailHint;
     writeCredentials(path, creds);
   }
 

package/src/commands/feedback.mjs

@@ -24,6 +24,7 @@ import { createInterface } from "node:readline/promises";
 import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { readActivity, formatActivity } from "../activity-log.mjs";
+import { defaultCredentialsPath, readCredentials } from "../token-store.mjs";
 import { fail } from "../errors.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
@@ -50,6 +51,30 @@ const USAGE = `tot feedback — send a note to Token of Trust (with your recent
 
 Requires a signed-in session — run \`tot login\` first if needed.`;
 
+/**
+ * Assemble the `feedback_submit` payload. Pure + exported so the wire shape
+ * (including the additive `sensitive` activity attachment and the invite→problem
+ * `traceId` link) is unit-testable without driving the MCP handshake. Both extras
+ * are OMITTED when their source is absent — never sent as null/empty.
+ * @param {{ type: string, category: string, severity: string, title: string,
+ *   description: string, activityText?: string|null, traceId?: string|null }} f
+ */
+export function buildFeedbackPayload({ type, category, severity, title, description, activityText, traceId }) {
+  return {
+    type,
+    category,
+    severity,
+    title,
+    description,
+    scenario: "tot-cli",
+    // Activity → `sensitive` (ToT-admins-only, never clustered/shared). It's already
+    // secret-redacted; `sensitive` is the belt-and-suspenders home for it.
+    ...(activityText ? { sensitive: `tot CLI activity (most recent last):\n${activityText}` } : {}),
+    // Invite→terminal→problem trace link (omitted when this wasn't an invite login).
+    ...(traceId ? { traceId } : {}),
+  };
+}
+
 function parseArgs(argv) {
   const a = {
     mcp: null, type: "improvement", category: "product-ux", severity: "medium",
@@ -115,6 +140,14 @@ export async function run(argv) {
   const activityText = entries.length ? formatActivity(entries) : null;
   const title = message.length > 80 ? `${message.slice(0, 79)}…` : message;
 
+  // The invite→terminal→problem trace id `tot login` cached from the pasted invite
+  // command (see commands/login.mjs `cacheTraceId`). Stamping it onto the report lets
+  // triage join this problem back to the developer's invite + their live heartbeat
+  // session. Read it BEFORE establishSession — a silent token refresh rewrites the
+  // credential file, so read the cached value first. Absent for a bare (non-invite)
+  // login; omitted from the payload then.
+  const traceId = readCredentials(defaultCredentialsPath(env))?.traceId || null;
+
   // Preview — sending publishes to Token of Trust, so show exactly what goes out.
   console.error("\nAbout to send to Token of Trust:");
   console.error(`  ${args.type} · ${args.category} · ${args.severity}`);
@@ -152,17 +185,15 @@ export async function run(argv) {
       env,
       initialize: () => client.initialize({ name: "tot-cli", version: "feedback" }),
     });
-    const payload = {
+    const payload = buildFeedbackPayload({
       type: args.type,
       category: args.category,
       severity: args.severity,
       title,
       description: message,
-      scenario: "tot-cli",
-      // Activity → `sensitive` (ToT-admins-only, never clustered/shared). It's already
-      // secret-redacted; `sensitive` is the belt-and-suspenders home for it.
-      ...(activityText ? { sensitive: `tot CLI activity (most recent last):\n${activityText}` } : {}),
-    };
+      activityText,
+      traceId,
+    });
     const res = await client.callTool("feedback_submit", payload);
     const id = res?.reportId || res?.id || null;
     console.log(`\n+ sent — thank you.${id ? ` (report ${id})` : ""}`);

package/src/commands/login.mjs

@@ -23,13 +23,14 @@ import { loginFlow, deviceLoginFlow, redeemCodeFlow, NoOpenerError } from "../oa
 import { defaultCredentialsPath, readCredentials, writeCredentials } from "../token-store.mjs";
 import { openBrowser } from "../open.mjs";
 import { fail } from "../errors.mjs";
+import { cockpitRecoveryUrl, normalizeEmailHint } from "../auth.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
 function parseArgs(argv) {
   const a = {
     mcp: null, device: false, code: null, help: false,
-    activityToken: null, activityUrl: null,
+    activityToken: null, activityUrl: null, traceId: null, emailHint: null,
   };
   for (let i = 0; i < argv.length; i++) {
     const t = argv[i];
@@ -38,11 +39,44 @@ function parseArgs(argv) {
     else if (t === "--code" || t === "--token") a.code = argv[++i];
     else if (t === "--activity-token") a.activityToken = argv[++i];
     else if (t === "--activity-url") a.activityUrl = argv[++i];
+    else if (t === "--trace-id") a.traceId = argv[++i];
+    else if (t === "--email-hint") a.emailHint = argv[++i];
+    else if (t === "--email") a.emailHint = argv[++i]; // legacy pasted commands
     else if (t === "--help" || t === "-h") a.help = true;
   }
   return a;
 }
 
+/** Canonical UUID (8-4-4-4-12 hex). Used to reject a malformed --trace-id paste. */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Cache the invite→terminal→problem trace id (storefront mints it when it issues
+ * the developer's CLI sign-in code and appends it to the pasted login command as
+ * `--trace-id <uuid>` — see apps/storefront/src/lib/dev/cliSignInCode.ts) alongside
+ * the MCP creds `tot login` just wrote, so `tot feedback` can stamp a later problem
+ * report with it and triage can join the report to the invite + live heartbeat
+ * session. Additive, and mirrors cacheActivityBridge. A no-op when the flag is
+ * absent (older pastes / a bare `tot login`) or malformed (defensive — skip rather
+ * than persist junk that would break the join).
+ */
+export function cacheTraceId(env, traceId) {
+  if (!traceId || !UUID_RE.test(traceId)) return;
+  const path = defaultCredentialsPath(env);
+  const current = readCredentials(path) || {};
+  writeCredentials(path, { ...current, traceId });
+}
+
+/** Cache a display-only email hint from the setup command for later recovery UX. */
+export function cacheEmailHint(env, emailHint) {
+  const normalized = normalizeEmailHint(emailHint);
+  if (!normalized) return;
+  const path = defaultCredentialsPath(env);
+  const current = readCredentials(path) || {};
+  const { email: _legacyEmail, ...safeCurrent } = current;
+  writeCredentials(path, { ...safeCurrent, emailHint: normalized });
+}
+
 /**
  * Cache the local→hosted activity-bridge credential (storefront's
  * cli-signin-code mint, piggybacked as two extra login flags — see
@@ -68,9 +102,10 @@ const USAGE = `tot login — sign in to Token of Trust
                             browser opener exists on this box)
   tot login --mcp <url>     MCP base URL (default: env MCP_BASE_URL / TOT_MCP_URL)
 
-  --activity-token/--activity-url are set automatically by the pasted invite
-  command (report local dev-loop activity to your hosted /dev panel) — not
-  meant to be typed by hand.
+  --activity-token/--activity-url/--trace-id/--email-hint are set automatically by the pasted
+  invite command (report local dev-loop activity to your hosted /dev panel, and
+  link a later \`tot feedback\` report to your invite + session) — not meant to be
+  typed by hand.
 
 After signing in, run \`tot whoami\` to confirm, then \`tot checkout\` / \`tot submit\`.`;
 
@@ -128,15 +163,31 @@ export async function redeemAndCache(mcpUrl, code, env = process.env) {
  * prior --code sign-in would otherwise silently drop it on the next `writeCredentials`
  * (a full-object overwrite, not a merge) — carry it forward when re-authing against
  * the SAME mcpUrl (a different MCP means a different session; the old bridge
- * credential no longer applies).
+ * credential and trace no longer apply).
  */
 export function mergeActivityBridge(prior, mcpUrl, creds) {
-  if (prior?.mcpUrl === mcpUrl && prior.activityToken && prior.activityUrl) {
-    return { ...creds, activityToken: prior.activityToken, activityUrl: prior.activityUrl };
+  if (prior?.mcpUrl === mcpUrl) {
+    const emailHint = normalizeEmailHint(prior.emailHint) || normalizeEmailHint(prior.email);
+    return {
+      ...creds,
+      ...(prior.activityToken && prior.activityUrl
+        ? { activityToken: prior.activityToken, activityUrl: prior.activityUrl }
+        : {}),
+      ...(prior.traceId ? { traceId: prior.traceId } : {}),
+      ...(emailHint ? { emailHint } : {}),
+    };
   }
   return creds;
 }
 
+export function inviteCodeRecoveryNext(activityUrl, emailHint = null) {
+  const url = cockpitRecoveryUrl(activityUrl, emailHint);
+  if (url) {
+    return `open ${url}, sign in if prompted, click "Generate a fresh setup command", then paste it into your terminal.`;
+  }
+  return 'open your developer invite again. If the link has expired, use "Send a fresh link", then generate a new setup command from cockpit.';
+}
+
 /** @param {string[]} argv @param {any} _ctx */
 export async function run(argv, _ctx) {
   const env = process.env;
@@ -153,6 +204,8 @@ export async function run(argv, _ctx) {
     try {
       await redeemAndCache(mcpUrl, args.code, env);
       cacheActivityBridge(env, args.activityToken, args.activityUrl);
+      cacheTraceId(env, args.traceId);
+      cacheEmailHint(env, args.emailHint);
       console.log(`\n+ signed in. Session cached to ${defaultCredentialsPath(env)}.`);
       console.log("  Next: `tot whoami` to confirm, or `tot checkout` / `tot submit` to build.");
       return 0;
@@ -160,7 +213,7 @@ export async function run(argv, _ctx) {
       console.error(
         fail(
           `sign-in didn't complete: ${e?.message || e}`,
-          "double-check the sign-in token from your invite — it's single-use and expires, so ask for a fresh invite if needed.",
+          inviteCodeRecoveryNext(args.activityUrl, args.emailHint),
         ),
       );
       return 1;
@@ -170,6 +223,7 @@ export async function run(argv, _ctx) {
   console.error(`~ signing in to Token of Trust (${mcpUrl})`);
   try {
     await loginAndCache(mcpUrl, env, { log: (m) => console.error(m), device: args.device });
+    cacheTraceId(env, args.traceId);
     console.log(`\n+ signed in. Session cached to ${defaultCredentialsPath(env)}.`);
     console.log("  Next: `tot whoami` to confirm, or `tot checkout` / `tot submit` to build.");
     return 0;

package/src/commands/start.mjs

@@ -374,7 +374,7 @@ async function tryResolveSession(client, env, args) {
   try {
     return await loginStep(client, env, args);
   } catch (e) {
-    if (e instanceof AuthUnavailableError) return null;
+    if (e instanceof AuthUnavailableError && e.reason === "missing") return null;
     if (e instanceof CliError && /can't reach the Token of Trust MCP/.test(e.message)) return null;
     throw e;
   }

package/src/token-store.mjs

@@ -7,7 +7,7 @@
  *
  *   { mcpUrl, clientId, tokenEndpoint, scope,
  *     accessToken, refreshToken, expiresAt (epoch ms), obtainedAt,
- *     activityToken, activityUrl }
+ *     activityToken, activityUrl, traceId, emailHint }
  *
  * We persist `clientId` + `tokenEndpoint` so a refresh needs no re-discovery /
  * re-registration, and `mcpUrl` so we never present a token minted for one MCP
@@ -16,7 +16,16 @@
  * invite paste carries it — see commands/login.mjs `cacheActivityBridge` and
  * commands/dev.mjs `activityBridgeEnv`, which every runner-spawning path (native
  * monorepo, native standalone, Docker) threads in so the local dev-loop process
- * can report file saves to the developer's hosted /dev panel.
+ * can report file saves to the developer's hosted /dev panel. `traceId` is the
+ * storefront-minted invite→terminal→problem trace id (cached by `tot login`'s
+ * `--trace-id` flag, see commands/login.mjs `cacheTraceId`); `tot feedback`
+ * stamps it onto a problem report so triage can join it to the invite + the live
+ * heartbeat session. `emailHint` is masked, display-only recovery context from
+ * the setup command, used to orient cockpit/login after a local credential
+ * expires without persisting a raw address.
+ *
+ * The read/write is a plain JSON pass-through (no schema) — new fields like
+ * `traceId` ride along additively; readers simply pick the keys they need.
  * Dependency-free (node:fs/os/path).
  *
  * `TOT_HOME` overrides the home dir (used by tests to point at a temp dir).

package/src/validate.mjs

@@ -119,6 +119,195 @@ function providesChrome(contentDir) {
   return true;
 }
 
+const CAPABILITY_KEYS = new Set(["cartCheckout", "ageVerification", "exciseTax"]);
+
+function complianceObligations(config) {
+  const compliance = config?.compliance || {};
+  return {
+    ageVerification: !!compliance.minAge,
+    exciseTax: !!compliance.nicotineWarning,
+  };
+}
+
+function rawHtmlAllowed(config) {
+  const obligations = complianceObligations(config);
+  const regulated = obligations.ageVerification || obligations.exciseTax;
+  return !regulated;
+}
+
+function validateCapabilitiesDoc(doc, file, config) {
+  const out = [];
+  if (doc == null || typeof doc !== "object" || Array.isArray(doc)) {
+    return [mk(ERROR, "capabilities-root", file, "capabilities must be a JSON object")];
+  }
+  for (const [key, value] of Object.entries(doc)) {
+    if (!CAPABILITY_KEYS.has(key)) {
+      out.push(mk(ERROR, "capability-unknown", file, `unknown capability "${key}"`));
+      continue;
+    }
+    if (value == null || typeof value !== "object" || typeof value.enabled !== "boolean") {
+      out.push(mk(ERROR, "capability-shape", file, `${key} must be an object with boolean "enabled"`));
+    }
+  }
+  const obligations = complianceObligations(config);
+  if (obligations.ageVerification && doc.ageVerification?.enabled === false) {
+    out.push(mk(ERROR, "capability-compliance-floor", file, "ageVerification cannot be disabled for a tenant with compliance.minAge"));
+  }
+  if (obligations.exciseTax && doc.exciseTax?.enabled === false) {
+    out.push(mk(ERROR, "capability-compliance-floor", file, "exciseTax cannot be disabled for a tenant with compliance.nicotineWarning"));
+  }
+  return out;
+}
+
+function validateScriptsDoc(doc, file, config) {
+  const out = [];
+  if (doc == null || typeof doc !== "object" || !Array.isArray(doc.scripts)) {
+    return [mk(ERROR, "scripts-root", file, 'scripts.json must have a "scripts" array')];
+  }
+  const regulated = !rawHtmlAllowed(config);
+  for (const [i, entry] of doc.scripts.entries()) {
+    const at = `${file} scripts[${i}]`;
+    if (entry == null || typeof entry !== "object") {
+      out.push(mk(ERROR, "script-entry", at, "script entry must be an object"));
+      continue;
+    }
+    if (entry.isolation === "inline") {
+      out.push(
+        regulated
+          ? mk(ERROR, "script-inline-regulated", at, 'inline scripts are not allowed for regulated tenants; use isolation:"sandbox"')
+          : mk(WARN, "script-inline", at, 'inline scripts run same-origin; prefer isolation:"sandbox"'),
+      );
+    }
+  }
+  return out;
+}
+
+const SUPPORTED_BLOCK_CONTRACTS = new Set(["block-palette@1", "block-palette@2", "block-palette@3"]);
+const KNOWN_BLOCKS = new Set([
+  "hero",
+  "promo_tiles",
+  "featured_collections",
+  "featured_products",
+  "editorial",
+  "newsletter",
+  "marketing_hero",
+  "trust_bar",
+  "split_compare",
+  "steps",
+  "card_grid",
+  "integrations",
+  "proof_strip",
+  "testimonials",
+  "faq",
+  "cta_band",
+]);
+const REQUIRED_BLOCK_PROPS = {
+  hero: ["headline"],
+  promo_tiles: ["tiles"],
+  featured_collections: ["handles"],
+  editorial: ["title"],
+  newsletter: ["title"],
+  marketing_hero: ["headline"],
+  trust_bar: ["items"],
+  split_compare: ["title", "before", "after"],
+  steps: ["title", "steps"],
+  card_grid: ["title", "cards"],
+  integrations: ["title", "platforms"],
+  proof_strip: ["title"],
+  testimonials: ["quotes"],
+  faq: ["title", "items"],
+  cta_band: ["title"],
+};
+const PRODUCT_SOURCE_KEYS = new Set([
+  "collection",
+  "tag",
+  "featured",
+  "newest",
+  "bestSelling",
+  "onSale",
+  "handles",
+  "related",
+  "recentlyViewed",
+]);
+const PRODUCT_SOURCE_SHORTCUTS = new Set(["featured", "newest", "bestSelling", "onSale"]);
+
+function validateProductSource(value, file, at) {
+  const out = [];
+  if (typeof value === "string") {
+    if (!PRODUCT_SOURCE_SHORTCUTS.has(value)) {
+      out.push(mk(ERROR, "product-source", file, `${at}.source must be one of featured, newest, bestSelling, onSale or a source object`));
+    }
+    return out;
+  }
+  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+    out.push(mk(ERROR, "product-source", file, `${at}.source must be a source string or object`));
+    return out;
+  }
+  const keys = Object.keys(value).filter((k) => value[k] !== undefined);
+  const recognized = keys.filter((k) => PRODUCT_SOURCE_KEYS.has(k));
+  if (keys.length !== 1 || recognized.length !== 1) {
+    out.push(mk(ERROR, "product-source", file, `${at}.source must declare exactly one recognized source key`));
+    return out;
+  }
+  const key = recognized[0];
+  const got = value[key];
+  if (key === "handles") {
+    if (!Array.isArray(got) || !got.every((v) => typeof v === "string")) {
+      out.push(mk(ERROR, "product-source", file, `${at}.source.handles must be a string array`));
+    }
+  } else if (key === "collection" || key === "tag" || key === "related") {
+    if (typeof got !== "string") {
+      out.push(mk(ERROR, "product-source", file, `${at}.source.${key} must be a string`));
+    }
+  } else if (got !== true) {
+    out.push(mk(ERROR, "product-source", file, `${at}.source.${key} must be true`));
+  }
+  return out;
+}
+
+function validateHomeDoc(doc, file) {
+  const out = [];
+  if (doc == null || typeof doc !== "object" || Array.isArray(doc)) {
+    return [mk(ERROR, "home-root", file, "home.json must be a JSON object")];
+  }
+  if (doc.contract !== undefined && (typeof doc.contract !== "string" || !SUPPORTED_BLOCK_CONTRACTS.has(doc.contract))) {
+    out.push(mk(ERROR, "home-contract", file, `unsupported block contract "${String(doc.contract)}"`));
+  }
+  if (!Array.isArray(doc.blocks)) {
+    out.push(mk(ERROR, "home-blocks", file, "`blocks` must be an array"));
+    return out;
+  }
+  doc.blocks.forEach((block, i) => {
+    const at = `blocks[${i}]`;
+    if (block == null || typeof block !== "object" || Array.isArray(block)) {
+      out.push(mk(ERROR, "block-shape", file, `${at} must be an object`));
+      return;
+    }
+    const component = block.component;
+    if (typeof component !== "string") {
+      out.push(mk(ERROR, "block-component", file, `${at}.component is required`));
+      return;
+    }
+    if (!KNOWN_BLOCKS.has(component)) {
+      out.push(mk(ERROR, "block-unknown", file, `${at}.component "${component}" is not in the supported block palette`));
+      return;
+    }
+    for (const prop of REQUIRED_BLOCK_PROPS[component] || []) {
+      if (block[prop] === undefined) out.push(mk(ERROR, "block-required", file, `${at} (${component}) is missing "${prop}"`));
+    }
+    if (component === "featured_products") {
+      if (block.source !== undefined) out.push(...validateProductSource(block.source, file, at));
+      if (block.handles !== undefined && (!Array.isArray(block.handles) || !block.handles.every((v) => typeof v === "string"))) {
+        out.push(mk(ERROR, "block-prop", file, `${at}.handles must be a string array`));
+      }
+      if (block.limit !== undefined && typeof block.limit !== "number") {
+        out.push(mk(ERROR, "block-prop", file, `${at}.limit must be a number`));
+      }
+    }
+  });
+  return out;
+}
+
 // --- filesystem helpers ------------------------------------------------------
 function readJsonSafe(path) {
   try {
@@ -181,6 +370,9 @@ export function validateTenant(tenantDir, opts = {}) {
     );
   }
   const scope = opts.scope || config?.scope;
+  if (config?.capabilities) {
+    findings.push(...validateCapabilitiesDoc(config.capabilities, ".tot/config.json capabilities", config));
+  }
 
   // 2. theme.json — parse (a malformed one is a WHOLE-APP BUILD FAILURE)
   const themePath = join(tenantDir, "theme.json");
@@ -194,6 +386,26 @@ export function validateTenant(tenantDir, opts = {}) {
     }
   }
 
+  const capabilitiesPath = join(tenantDir, "capabilities.json");
+  if (existsSync(capabilitiesPath)) {
+    const { value, error } = readJsonSafe(capabilitiesPath);
+    if (error) {
+      findings.push(mk(ERROR, "capabilities-parse", "capabilities.json", `invalid JSON: ${error}`));
+    } else {
+      findings.push(...validateCapabilitiesDoc(value, "capabilities.json", config));
+    }
+  }
+
+  const scriptsPath = join(tenantDir, "scripts.json");
+  if (existsSync(scriptsPath)) {
+    const { value, error } = readJsonSafe(scriptsPath);
+    if (error) {
+      findings.push(mk(ERROR, "scripts-parse", "scripts.json", `invalid JSON: ${error}`));
+    } else {
+      findings.push(...validateScriptsDoc(value, "scripts.json", config));
+    }
+  }
+
   // 3. content JSON — parse + blocks shape
   for (const name of ["home.json", "chrome.json"]) {
     const p = join(contentDir, name);
@@ -201,8 +413,8 @@ export function validateTenant(tenantDir, opts = {}) {
       const { value, error } = readJsonSafe(p);
       if (error) {
         findings.push(mk(ERROR, "content-json-parse", `content/${name}`, `invalid JSON: ${error} (fails the build)`));
-      } else if (name === "home.json" && value && "blocks" in value && !Array.isArray(value.blocks)) {
-        findings.push(mk(ERROR, "home-blocks", "content/home.json", "`blocks` must be an array (index.astro throws otherwise)"));
+      } else if (name === "home.json") {
+        findings.push(...validateHomeDoc(value, "content/home.json"));
       }
     }
   }
@@ -222,6 +434,12 @@ export function validateTenant(tenantDir, opts = {}) {
       findings.push(mk(ERROR, "html-invalid", r, `not a servable document: ${bad}`));
       continue;
     }
+    if (config && !rawHtmlAllowed(config)) {
+      findings.push(
+        mk(ERROR, "raw-html-compliance-bypass", r,
+          "raw HTML bypasses platform Layout compliance; regulated commerce tenants must use block composition or an extracted runtime"),
+      );
+    }
     if (!base && !isFullDocument(html) && !hasChrome) {
       findings.push(
         mk(ERROR, "html-fragment", r,