@vxil/cli 0.4.3 → 0.5.1

package/dist/vxil.js

@@ -1,38 +1,53 @@
 #!/usr/bin/env node
 
 // bin/vxil.ts
-import { writeFileSync as writeFileSync6, mkdirSync as mkdirSync5, existsSync as existsSync7, appendFileSync as appendFileSync2, readFileSync as readFileSync7, chmodSync as chmodSync2 } from "node:fs";
+import { writeFileSync as writeFileSync6, mkdirSync as mkdirSync5, existsSync as existsSync8, appendFileSync as appendFileSync2, readFileSync as readFileSync8, chmodSync as chmodSync2 } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { resolve as resolve7, dirname as dirname4 } from "node:path";
+import { resolve as resolve7, dirname as dirname5 } from "node:path";
 import { createInterface } from "node:readline";
 import { watch } from "node:fs";
 import { createServer } from "node:http";
-import { homedir as homedir2, hostname } from "node:os";
+import { homedir as homedir3, hostname } from "node:os";
 
 // src/lib.ts
 import { pathToFileURL, fileURLToPath } from "node:url";
 import { resolve, dirname, basename, join } from "node:path";
 import { existsSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+var FN_LIMIT_BOUNDS = {
+  cpuMs: { min: 5, max: 3e5 },
+  timeoutMs: { min: 1e3, max: 12e4 }
+};
+function normalizeFnLimits(raw) {
+  if (!raw || typeof raw !== "object") return void 0;
+  const out = {};
+  for (const k of ["cpuMs", "timeoutMs"]) {
+    const v = raw[k];
+    if (typeof v !== "number" || !Number.isFinite(v)) continue;
+    const b2 = FN_LIMIT_BOUNDS[k];
+    out[k] = Math.min(b2.max, Math.max(b2.min, Math.floor(v)));
+  }
+  return Object.keys(out).length ? out : void 0;
+}
 function lowerTriggerBindings(trigger) {
   const t = trigger?.kind ?? "http";
-  const str = (k) => typeof trigger?.[k] === "string" ? trigger[k] : void 0;
-  if (t === "cron") return [{ kind: "cron", ...str("schedule") ? { schedule: str("schedule") } : {} }];
-  if (t === "queue") return [{ kind: "queue", ...str("source") ? { source: str("source") } : {} }];
-  if (t === "webhook") return [{ kind: "webhook", ...str("source") ? { source: str("source") } : {} }];
+  const str2 = (k) => typeof trigger?.[k] === "string" ? trigger[k] : void 0;
+  if (t === "cron") return [{ kind: "cron", ...str2("schedule") ? { schedule: str2("schedule") } : {} }];
+  if (t === "queue") return [{ kind: "queue", ...str2("source") ? { source: str2("source") } : {} }];
+  if (t === "webhook") return [{ kind: "webhook", ...str2("source") ? { source: str2("source") } : {} }];
   if (t === "cmsHook" || t === "cms-hook") {
     return [{
       kind: "cmsHook",
-      ...str("collection") ? { collection: str("collection") } : {},
-      ...str("event") ? { event: str("event") } : {}
+      ...str2("collection") ? { collection: str2("collection") } : {},
+      ...str2("event") ? { event: str2("event") } : {}
     }];
   }
   if (t === "authHook" || t === "auth-hook") {
-    return [{ kind: "authHook", ...str("event") ? { event: str("event") } : {} }];
+    return [{ kind: "authHook", ...str2("event") ? { event: str2("event") } : {} }];
   }
-  return [{ kind: "http", ...str("path") ? { path: str("path") } : {} }];
+  return [{ kind: "http", ...str2("path") ? { path: str2("path") } : {} }];
 }
 var CONFIG_FILENAMES = ["vxil.config.ts", "vxil.config.mjs", "vxil.config.js"];
-var VXIL_CONFIG_PKG_VERSION = "0.3.1";
+var VXIL_CONFIG_PKG_VERSION = "0.4.0";
 function ensureScaffoldPackageJson(cwd) {
   const file = resolve(cwd, "package.json");
   const spec = `^${VXIL_CONFIG_PKG_VERSION}`;
@@ -253,6 +268,7 @@ function assembleApplyBundle(cfg, fnSources) {
     const source = fnSources[name];
     if (source === void 0) throw new Error(`functions: no bundled source for '${name}'`);
     const bindings = lowerTriggerBindings(def.trigger);
+    const limits = normalizeFnLimits(def.limits);
     return {
       name,
       source,
@@ -261,7 +277,8 @@ function assembleApplyBundle(cfg, fnSources) {
       ...def.signature ? { signature: def.signature } : {},
       ...def.scopes ? { scopes: def.scopes } : {},
       ...def.egressAllow ? { egressAllow: def.egressAllow } : {},
-      ...def.secrets ? { secrets: def.secrets } : {}
+      ...def.secrets ? { secrets: def.secrets } : {},
+      ...limits ? { limits } : {}
     };
   });
   return {
@@ -319,6 +336,16 @@ async function planOrPush({ api, features, apply }) {
     }
     const effective = dry.body.data?.manifest;
     const cur = await api("GET", `/v1/config/${feature}`);
+    const unavailable = readUnavailable(`GET /v1/config/${feature}`, cur);
+    if (unavailable) {
+      if (apply) {
+        throw new Error(
+          `config: cannot read ${unavailable.route} (${unavailable.code ?? unavailable.status}${unavailable.message ? ` \u2014 ${unavailable.message}` : ""}) \u2014 refusing to push ${feature} against a remote it could not read`
+        );
+      }
+      results.push({ feature, version: 0, changes: [], applied: null, remoteUnavailable: unavailable });
+      continue;
+    }
     const exists = cur.status === 200;
     const remote = exists ? cur.body.data?.manifest : {};
     const version = exists ? cur.body.data?.version ?? 0 : 0;
@@ -341,9 +368,188 @@ async function planOrPush({ api, features, apply }) {
   }
   return results;
 }
+function classifyRead(status, code) {
+  if (status === 200) return "ok";
+  if (status === 404) return "empty";
+  if (status === 501 && (code === void 0 || code === "capability_not_enabled")) return "empty";
+  return "unavailable";
+}
+function readUnavailable(route, res) {
+  const e = res.body?.error ?? {};
+  if (classifyRead(res.status, e.code) !== "unavailable") return null;
+  return {
+    route,
+    status: res.status,
+    ...e.code ? { code: e.code } : {},
+    ...e.message ? { message: e.message } : {}
+  };
+}
+function formatNotCompared(u, hint) {
+  return `  ! not compared: ${u.route} \u2192 ${u.code ?? u.status}${u.message ? ` \u2014 ${u.message}` : ""}${hint ? ` (${hint})` : ""}`;
+}
+
+// src/apiState.ts
+var POLICY_LIST_CAP = 100;
+var CAMPAIGN_LIST_CAP = 200;
+var LEGACY_POLICY_ALGORITHM = "sliding_window";
+var DEFAULT_SUBSCRIPTION_STATE = "active";
+var FN_TRIGGER_TARGET_MARKERS = [
+  "/v1/internal/fn/cms-hook/",
+  "/v1/internal/fn/auth-hook/",
+  "/v1/internal/fn/trigger/"
+];
+function isFnTriggerSubscription(targetUrl) {
+  return FN_TRIGGER_TARGET_MARKERS.some((m) => targetUrl.includes(m));
+}
+function str(v) {
+  return typeof v === "string" ? v : void 0;
+}
+function num(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : void 0;
+}
+function strList(v) {
+  return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+}
+function defined(o) {
+  const out = {};
+  for (const [k, v] of Object.entries(o)) if (v !== void 0) out[k] = v;
+  return out;
+}
+async function fetchApiState(api) {
+  const snap = { policies: [], subscriptions: [], campaigns: [], unavailable: [], truncated: [] };
+  const read = async (route, take) => {
+    let res;
+    try {
+      res = await api("GET", route);
+    } catch (e) {
+      snap.unavailable.push({ route: `GET ${route}`, status: 0, code: "network_error", message: e.message.split("\n")[0] ?? "" });
+      return;
+    }
+    const u = readUnavailable(`GET ${route}`, res);
+    if (u) {
+      snap.unavailable.push(u);
+      return;
+    }
+    if (classifyRead(res.status, res.body.error?.code) !== "ok") return;
+    take(res.body.data ?? {});
+  };
+  await read("/v1/rate-limits/policies", (d) => {
+    const rows = Array.isArray(d.policies) ? d.policies : [];
+    for (const raw of rows) {
+      const p = raw;
+      const name = str(p.name);
+      if (!name) continue;
+      snap.policies.push(defined({
+        name,
+        limit: num(p.limit),
+        window_seconds: num(p.window_seconds),
+        behavior: str(p.behavior),
+        key_template: str(p.key_template),
+        algorithm: str(p.algorithm) ?? LEGACY_POLICY_ALGORITHM
+      }));
+    }
+    if (rows.length >= POLICY_LIST_CAP) snap.truncated.push("policy");
+  });
+  await read("/v1/webhooks/subscriptions", (d) => {
+    for (const raw of Array.isArray(d.subscriptions) ? d.subscriptions : []) {
+      const s = raw;
+      const url = str(s.target_url);
+      if (!url) continue;
+      if (isFnTriggerSubscription(url)) continue;
+      snap.subscriptions.push({
+        target_url: url,
+        event_prefixes: strList(s.event_prefixes),
+        state: str(s.state) ?? DEFAULT_SUBSCRIPTION_STATE
+      });
+    }
+  });
+  await read("/v1/notifications/campaigns", (d) => {
+    const rows = Array.isArray(d.campaigns) ? d.campaigns : [];
+    for (const raw of rows) {
+      const c = raw;
+      const name = str(c.name);
+      if (name) snap.campaigns.push({ name });
+    }
+    if (rows.length >= CAMPAIGN_LIST_CAP) snap.truncated.push("campaign");
+  });
+  return snap;
+}
+function apiStateDriftKey(row2) {
+  return `api:${row2.section}:${row2.key}`;
+}
+function sameSet(a, b2) {
+  const A = new Set(a);
+  const B = new Set(b2);
+  return A.size === B.size && [...A].every((x) => B.has(x));
+}
+function diffBy(section, target, against, keyOf, fields) {
+  const rows = [];
+  const A = new Map(target.map((t) => [keyOf(t), t]));
+  const B = new Map(against.map((t) => [keyOf(t), t]));
+  for (const key of [.../* @__PURE__ */ new Set([...A.keys(), ...B.keys()])].sort()) {
+    const a = A.get(key);
+    const b2 = B.get(key);
+    if (a && !b2) {
+      rows.push({ section, key, kind: "only_in_target", detail: `${section} '${key}' exists on the target, not on --against` });
+      continue;
+    }
+    if (!a && b2) {
+      rows.push({ section, key, kind: "only_in_against", detail: `${section} '${key}' exists on --against, not on the target` });
+      continue;
+    }
+    for (const f of fields) {
+      const av = f.of(a);
+      const bv = f.of(b2);
+      const equal = Array.isArray(av) && Array.isArray(bv) ? sameSet(av, bv) : JSON.stringify(av ?? null) === JSON.stringify(bv ?? null);
+      if (equal) continue;
+      rows.push({
+        section,
+        key,
+        kind: "differs",
+        detail: `${section} '${key}' ${f.name}: ${JSON.stringify(av ?? null)} \u2192 ${JSON.stringify(bv ?? null)}` + (f.note ? ` ${f.note}` : "")
+      });
+    }
+  }
+  return rows;
+}
+function diffApiState(target, against) {
+  return [
+    ...diffBy("policy", target.policies, against.policies, (p) => p.name, [
+      { name: "limit", of: (p) => p.limit },
+      { name: "window_seconds", of: (p) => p.window_seconds },
+      { name: "behavior", of: (p) => p.behavior },
+      // PUT /v1/rate-limits/policies/:id cannot repair a key_template (the
+      // update body omits it) — the only fix is delete-and-recreate.
+      { name: "key_template", of: (p) => p.key_template, note: "(recreate to fix)" },
+      // Normalized at the accessor too, so a projection built by hand (or by an
+      // older CLI) can never compare `undefined` against the default.
+      { name: "algorithm", of: (p) => p.algorithm ?? LEGACY_POLICY_ALGORITHM }
+    ]),
+    ...diffBy("subscription", target.subscriptions, against.subscriptions, (s) => s.target_url, [
+      { name: "event_prefixes", of: (s) => s.event_prefixes },
+      { name: "state", of: (s) => s.state ?? DEFAULT_SUBSCRIPTION_STATE }
+    ]),
+    // Campaigns compare by PRESENCE only: everything else about a campaign
+    // (its schedule, its audience, its run state) is operational state that
+    // legitimately differs between a staging and a production tenant.
+    ...diffBy("campaign", target.campaigns, against.campaigns, (c) => c.name, [])
+  ];
+}
+function truncationWarnings(snap, side) {
+  return snap.truncated.map((s) => {
+    const cap = s === "policy" ? POLICY_LIST_CAP : CAMPAIGN_LIST_CAP;
+    return `  ! ${s} list on ${side} returned ${cap} rows \u2014 that is the route's HARD cap (no cursor), so the remainder cannot be diffed at all`;
+  });
+}
+function formatApiStateRows(rows) {
+  if (!rows.length) return "  (api state in sync)";
+  return rows.map((r) => `  ${r.kind === "differs" ? "~" : r.kind === "only_in_target" ? "+" : "-"} ${r.detail}`).join("\n");
+}
 
 // src/functions.ts
-import { resolve as resolve2, relative, isAbsolute, sep } from "node:path";
+import { existsSync as existsSync2, readFileSync as readFileSync2, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname as dirname2, resolve as resolve2, relative, isAbsolute, sep } from "node:path";
 import { createHash } from "node:crypto";
 var MAX_SOURCE_BYTES = 256e3;
 function sourceSha12(source) {
@@ -353,25 +559,89 @@ function escapesRoot(root, path) {
   const rel = relative(root, path);
   return rel.startsWith("..") || isAbsolute(rel);
 }
-function assertBundleContained(projectRoot, inputs) {
+function realpathSafe(p) {
+  try {
+    return realpathSync.native(resolve2(p));
+  } catch {
+    return resolve2(p);
+  }
+}
+function isWorkspaceMarker(dir) {
+  if (existsSync2(resolve2(dir, "pnpm-workspace.yaml"))) return true;
+  if (existsSync2(resolve2(dir, "turbo.json"))) return true;
+  if (existsSync2(resolve2(dir, "lerna.json"))) return true;
+  const pkg = resolve2(dir, "package.json");
+  if (!existsSync2(pkg)) return false;
+  try {
+    return JSON.parse(readFileSync2(pkg, "utf8")).workspaces !== void 0;
+  } catch {
+    return false;
+  }
+}
+function workspaceRootFor(projectRoot) {
+  const start = realpathSafe(projectRoot);
+  const home = realpathSafe(homedir());
+  const underHome = !escapesRoot(home, start);
+  let gitRoot = null;
+  let dir = start;
+  for (; ; ) {
+    if (isWorkspaceMarker(dir)) return dir;
+    if (existsSync2(resolve2(dir, ".git")) && existsSync2(resolve2(dir, "package.json"))) gitRoot = dir;
+    if (underHome && dir === home) break;
+    const up = dirname2(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return gitRoot ?? start;
+}
+var WORKSPACE_ROOTS = /* @__PURE__ */ new Map();
+function workspaceRootCached(projectRoot) {
+  const key = resolve2(projectRoot);
+  let v = WORKSPACE_ROOTS.get(key);
+  if (v === void 0) {
+    v = workspaceRootFor(key);
+    WORKSPACE_ROOTS.set(key, v);
+  }
+  return v;
+}
+function assertBundleContained(projectRoot, inputs, opts = {}) {
+  const what = opts.what ?? "bundled import";
   const root = resolve2(projectRoot);
+  const rootReal = realpathSafe(root);
+  const wsReal = realpathSafe(opts.workspaceRoot ?? workspaceRootCached(root));
+  const note = opts.onEscape ?? ((msg) => console.log(msg));
   for (const input of inputs) {
     const abs = resolve2(root, input);
-    if (!escapesRoot(root, abs)) continue;
-    if (abs.split(sep).includes("node_modules")) continue;
+    const absReal = realpathSafe(abs);
+    if (!escapesRoot(rootReal, absReal) || !escapesRoot(root, abs)) continue;
+    if (absReal.split(sep).includes("node_modules") || abs.split(sep).includes("node_modules")) continue;
+    const pkg = workspacePackageFor(wsReal, absReal);
+    if (pkg !== null) {
+      note(`! ${what} '${input}' comes from the workspace package ${pkg}`);
+      continue;
+    }
     throw new Error(
-      `functions: bundled import '${input}' resolves outside the project root (${root}) \u2014 function source (and everything it imports) must live inside the project or node_modules`
+      `functions: ${what} '${input}' resolves outside the project root (${rootReal})${wsReal === rootReal ? "" : ` and outside any package of its workspace (${wsReal})`} \u2014 function source (and everything it imports) must live inside the project, a workspace PACKAGE (a directory with its own package.json), or node_modules${wsReal === rootReal ? "" : " (run `vxil push` from the workspace root if the import is a sibling package)"}`
     );
   }
 }
+function workspacePackageFor(workspaceRoot, path) {
+  const wsReal = realpathSafe(workspaceRoot);
+  if (escapesRoot(wsReal, path)) return null;
+  let dir = dirname2(path);
+  for (; ; ) {
+    if (dir === wsReal || !dir.startsWith(wsReal + sep)) return null;
+    if (existsSync2(resolve2(dir, "package.json"))) return dir;
+    const up = dirname2(dir);
+    if (up === dir) return null;
+    dir = up;
+  }
+}
 async function bundleFunction(entryPath, opts = {}) {
   const root = resolve2(opts.projectRoot ?? process.cwd());
+  const workspaceRoot = workspaceRootCached(root);
   const entry = resolve2(entryPath);
-  if (escapesRoot(root, entry)) {
-    throw new Error(
-      `functions: entry '${entryPath}' resolves outside the project root (${root}) \u2014 declare function entries as paths inside the project`
-    );
-  }
+  assertBundleContained(root, [entry], { workspaceRoot, what: "entry" });
   const esbuild = await import("esbuild");
   const result = await esbuild.build({
     entryPoints: [entry],
@@ -390,7 +660,7 @@ async function bundleFunction(entryPath, opts = {}) {
   });
   const out = result.outputFiles?.[0];
   if (!out) throw new Error(`esbuild produced no output for ${entryPath}`);
-  assertBundleContained(root, Object.keys(result.metafile?.inputs ?? {}));
+  assertBundleContained(root, Object.keys(result.metafile?.inputs ?? {}), { workspaceRoot });
   const source = out.text;
   const bytes = Buffer.byteLength(source, "utf8");
   if (bytes > MAX_SOURCE_BYTES) {
@@ -418,8 +688,9 @@ function normalizeSecretRefs(refs) {
 async function readRemote(api) {
   const res = await api("GET", "/v1/functions");
   const map = /* @__PURE__ */ new Map();
-  if (res.status !== 200) return map;
-  const fns = res.body.data?.functions ?? [];
+  const unavailable = readUnavailable("GET /v1/functions", res);
+  if (res.status !== 200) return { map, unavailable };
+  const fns = Array.isArray(res.body.data?.functions) ? res.body.data.functions : [];
   for (const f of fns) {
     map.set(f.name, {
       scriptRef: f.scriptRef ?? "",
@@ -427,10 +698,11 @@ async function readRemote(api) {
       scopes: f.scopes ?? [],
       egressAllow: f.egressAllow ?? [],
       bindings: f.bindings ?? [],
-      signature: f.signature ?? null
+      signature: f.signature ?? null,
+      limits: f.limits ?? null
     });
   }
-  return map;
+  return { map, unavailable: null };
 }
 function sameSecretSet(a, b2) {
   return a.length === b2.length && a.every((x) => b2.includes(x));
@@ -445,7 +717,16 @@ function clampFunctionScopes(scopes) {
   return (scopes ?? []).map(String).filter((s) => s && !DENY_FUNCTION_SCOPES.has(s));
 }
 async function planFunctions({ api, functions, cwd, apply }) {
-  const remote = await readRemote(api);
+  const read = await readRemote(api);
+  if (read.unavailable) {
+    if (apply) {
+      throw new Error(
+        `functions: cannot read ${read.unavailable.route} (${read.unavailable.code ?? read.unavailable.status}${read.unavailable.message ? ` \u2014 ${read.unavailable.message}` : ""}) \u2014 refusing to deploy a plan computed against an unread target`
+      );
+    }
+    return { changes: [], applied: 0, cmsHookSubscriptions: null, webhookSubscriptions: null, remoteUnavailable: read.unavailable };
+  }
+  const remote = read.map;
   const results = await mapPool(Object.entries(functions), 1, async ([name, def]) => {
     if (!/^[a-z][a-z0-9-]{0,47}$/.test(name)) {
       throw new Error(`functions: invalid name '${name}' (must match /^[a-z][a-z0-9-]{0,47}$/)`);
@@ -454,11 +735,12 @@ async function planFunctions({ api, functions, cwd, apply }) {
     const triggerKind = def.trigger?.kind ?? "http";
     const secrets = normalizeSecretRefs(def.secrets);
     const bindings = lowerTriggerBindings(def.trigger);
+    const limits = normalizeFnLimits(def.limits);
     const remoteFn = remote.get(name);
     const sha = sourceSha12(source);
-    const label = `${name} (${Math.round(bytes / 100) / 10} KB) [${triggerKind}${def.scopes?.length ? " \xB7 " + def.scopes.join(",") : ""}${secrets.length ? " \xB7 secrets:" + secrets.map((s) => s.slice("secret:".length)).join(",") : ""}]`;
-    if (remoteFn !== void 0 && remoteFn.scriptRef.endsWith(`-${sha}`) && sameSecretSet(remoteFn.secrets, secrets) && sameStringSet(clampFunctionScopes(def.scopes), remoteFn.scopes) && sameStringSet(def.egressAllow ?? [], remoteFn.egressAllow) && stableStringify(remoteFn.bindings) === stableStringify(bindings) && stableStringify(remoteFn.signature) === stableStringify(def.signature ?? null)) {
-      return { change: { name, kind: "unchanged", detail: label }, applied: 0, cmsHooks: null };
+    const label = `${name} (${Math.round(bytes / 100) / 10} KB) [${triggerKind}${def.scopes?.length ? " \xB7 " + def.scopes.join(",") : ""}${secrets.length ? " \xB7 secrets:" + secrets.map((s) => s.slice("secret:".length)).join(",") : ""}${limits?.cpuMs !== void 0 ? " \xB7 cpu:" + limits.cpuMs + "ms" : ""}${limits?.timeoutMs !== void 0 ? " \xB7 egress:" + limits.timeoutMs + "ms" : ""}]`;
+    if (remoteFn !== void 0 && remoteFn.scriptRef.endsWith(`-${sha}`) && sameSecretSet(remoteFn.secrets, secrets) && sameStringSet(clampFunctionScopes(def.scopes), remoteFn.scopes) && sameStringSet(def.egressAllow ?? [], remoteFn.egressAllow) && stableStringify(remoteFn.bindings) === stableStringify(bindings) && stableStringify(remoteFn.signature) === stableStringify(def.signature ?? null) && stableStringify(remoteFn.limits ?? null) === stableStringify(limits ?? null)) {
+      return { change: { name, kind: "unchanged", detail: label }, applied: 0, cmsHooks: null, webhooks: null };
     }
     const change = { name, kind: remoteFn === void 0 ? "deploy-new" : "deploy-update", detail: label };
     if (apply) {
@@ -467,23 +749,29 @@ async function planFunctions({ api, functions, cwd, apply }) {
       if (def.signature) body.signature = def.signature;
       if (def.scopes) body.scopes = def.scopes;
       if (def.egressAllow) body.egressAllow = def.egressAllow;
+      if (limits) body.limits = limits;
       const res = await api("POST", `/v1/functions/${encodeURIComponent(name)}`, body);
       if (res.status !== 200 && res.status !== 201) {
         const e = res.body.error ?? {};
         throw new Error(`functions: deploy ${name} failed: ${e.code ?? res.status} ${e.message ?? ""} ${e.hint ?? ""}`);
       }
-      const cmsHooks = res.body.data?.cms_hook_subscriptions ?? null;
-      return { change, applied: 1, cmsHooks };
+      const data2 = res.body.data;
+      const cmsHooks = data2?.cms_hook_subscriptions ?? null;
+      const webhooks = data2?.webhook_subscriptions ?? null;
+      return { change, applied: 1, cmsHooks, webhooks };
     }
-    return { change, applied: 0, cmsHooks: null };
+    return { change, applied: 0, cmsHooks: null, webhooks: null };
   });
   const changes = results.map((r) => r.change);
   const applied = results.reduce((s, r) => s + r.applied, 0);
-  const cmsHookSubscriptions = results.reduce((acc, r) => {
-    if (!r.cmsHooks) return acc;
-    return { created: (acc?.created ?? 0) + r.cmsHooks.created, deleted: (acc?.deleted ?? 0) + r.cmsHooks.deleted };
+  const sum = (pick) => results.reduce((acc, r) => {
+    const v = pick(r);
+    if (!v) return acc;
+    return { created: (acc?.created ?? 0) + v.created, deleted: (acc?.deleted ?? 0) + v.deleted };
   }, null);
-  return { changes, applied, cmsHookSubscriptions };
+  const cmsHookSubscriptions = sum((r) => r.cmsHooks);
+  const webhookSubscriptions = sum((r) => r.webhooks);
+  return { changes, applied, cmsHookSubscriptions, webhookSubscriptions };
 }
 function formatFnChanges(changes) {
   const actionable = changes.filter((c) => c.kind !== "unchanged");
@@ -510,21 +798,21 @@ function normalizeActions(raw) {
   return raw.filter((a) => !!a && typeof a === "object").map((a) => ({ key: String(a.key), label: String(a.label), fn: String(a.fn) }));
 }
 var FIELD_ATTRS = [
-  { config: "required", wire: "required", remote: "required", blank: false, alterable: false },
-  { config: "validation", wire: "validation", remote: "validation", blank: {}, alterable: false },
-  { config: "indexSlot", wire: "index_slot", remote: "index_slot", blank: null, alterable: false },
-  { config: "relationTo", wire: "relation_to", remote: "relation_to", blank: null, alterable: false },
-  { config: "computed", wire: "computed", remote: "computed", blank: false, alterable: false },
-  { config: "compute", wire: "compute", remote: "compute", blank: null, alterable: false },
-  { config: "unique", wire: "unique", remote: "is_unique", blank: false, alterable: true },
-  { config: "onDelete", wire: "on_delete", remote: "on_delete", blank: null, alterable: true },
+  { config: "required", wire: "required", remote: "required", blank: false, alter: "in-place" },
+  { config: "validation", wire: "validation", remote: "validation", blank: {}, alter: "in-place" },
+  { config: "indexSlot", wire: "index_slot", remote: "index_slot", blank: null, alter: "reindex" },
+  { config: "relationTo", wire: "relation_to", remote: "relation_to", blank: null, alter: "destructive" },
+  { config: "computed", wire: "computed", remote: "computed", blank: false, alter: "in-place" },
+  { config: "compute", wire: "compute", remote: "compute", blank: null, alter: "in-place" },
+  { config: "unique", wire: "unique", remote: "is_unique", blank: false, alter: "tighten-only" },
+  { config: "onDelete", wire: "on_delete", remote: "on_delete", blank: null, alter: "tighten-only" },
   // cms.md §18 (RB-3) field-level read security. ALTERABLE: cms-v1 rewrites the
   // gate in place on a same-type re-POST (the unique/on_delete flag-alter path),
   // so config-as-code can TIGHTEN a gate on an existing field. Blank is `null`
   // (the server stores NULL for "ungated" and normalizes `[]` to NULL), so an
   // omitted attribute diffs clean; CLEARING it WIDENS access and therefore rides
   // the same --allow-destructive gate as clearing unique/on_delete/owner_field.
-  { config: "readRoles", wire: "read_roles", remote: "read_roles", blank: null, alterable: true }
+  { config: "readRoles", wire: "read_roles", remote: "read_roles", blank: null, alter: "tighten-only" }
 ];
 function fieldToInput(name, def) {
   const out = { field: name, type: def.type };
@@ -547,41 +835,110 @@ function remoteFieldToConfig(rf) {
 function fieldAttrDelta(def, rf) {
   const d = def;
   const r = rf;
-  const flags = [];
-  const clearing = [];
-  const drift = [];
+  const out = { flags: [], clearing: [], inPlace: [], reindex: [], retarget: [], drift: [] };
   for (const a of FIELD_ATTRS) {
     const wantBlank = stableStringify(a.blank);
     const want = stableStringify(d[a.config] ?? a.blank);
     const have = stableStringify(r[a.remote] ?? a.blank);
     if (want === have) continue;
-    if (!a.alterable) {
-      drift.push(`${a.config} ${have} \u2192 ${want}`);
+    const line = `${a.config} ${have} \u2192 ${want}`;
+    if (a.alter === "tighten-only") {
+      (want === wantBlank ? out.clearing : out.flags).push(line);
+      continue;
+    }
+    if (d[a.config] === void 0) {
+      out.drift.push(line);
       continue;
     }
-    if (want === wantBlank) clearing.push(`${a.config} ${have} \u2192 ${want}`);
-    else flags.push(`${a.config} ${have} \u2192 ${want}`);
+    if (a.alter === "reindex") out.reindex.push(line);
+    else if (a.alter === "destructive") out.retarget.push(line);
+    else out.inPlace.push(line);
+  }
+  return out;
+}
+function vacateSlotBody(rf) {
+  const out = { field: rf.field, type: rf.type, index_slot: null };
+  if (rf.is_unique) out.unique = true;
+  if (rf.on_delete) out.on_delete = rf.on_delete;
+  if (rf.read_roles && rf.read_roles.length > 0) out.read_roles = rf.read_roles;
+  return out;
+}
+async function liveRowCount(api, collection) {
+  try {
+    const res = await api("GET", `/v1/cms/items/${encodeURIComponent(collection)}?count=true`);
+    const n = res.body.data?.count;
+    return typeof n === "number" ? n : null;
+  } catch {
+    return null;
   }
-  return { flags, clearing, drift };
 }
 async function readRemote2(api) {
   const res = await api("GET", "/v1/cms/collections");
   const map = /* @__PURE__ */ new Map();
-  if (res.status !== 200) return map;
-  const cols = res.body.data?.collections ?? [];
+  const unavailable = readUnavailable("GET /v1/cms/collections", res);
+  if (res.status !== 200) return { map, unavailable };
+  const cols = Array.isArray(res.body.data?.collections) ? res.body.data.collections : [];
   for (const c of cols) {
     map.set(c.collection, {
       collection: c.collection,
       ownerField: c.owner_field ?? null,
       public: c.public === true,
       actions: normalizeActions(c.actions),
-      fields: c.fields ?? []
+      fields: Array.isArray(c.fields) ? c.fields : []
     });
   }
-  return map;
+  return { map, unavailable: null };
+}
+var REINDEX_PAGE_CAP = 1e4;
+async function reindexCollection({ api, collection, field, onProgress }) {
+  const rerun = ` \u2014 re-run \`vxil cms reindex ${collection}${field ? ` --field ${field}` : ""}\` (the alter is applied; only the projection lags)`;
+  let cursor;
+  let scanned = 0;
+  let updated = 0;
+  let pages = 0;
+  let skipped = 0;
+  const page = async () => {
+    const res = await api("POST", `/v1/cms/collections/${encodeURIComponent(collection)}/reindex`, {
+      ...field ? { field } : {},
+      ...cursor ? { cursor } : {}
+    });
+    if (res.status < 200 || res.status >= 300) {
+      const e = res.body.error ?? {};
+      throw new Error(`cms: re-index ${collection} failed: ${e.code ?? res.status} ${e.message ?? ""}`.trimEnd() + rerun);
+    }
+    const d = res.body.data ?? {};
+    scanned += d.scanned ?? 0;
+    updated += d.updated ?? 0;
+    pages++;
+    return d;
+  };
+  for (; ; ) {
+    let d = await page();
+    if ((d.skipped ?? 0) > 0) d = await page();
+    skipped += d.skipped ?? 0;
+    onProgress?.({ scanned, updated, pages, skipped });
+    if (d.complete === true || !d.next_cursor) break;
+    if (d.next_cursor === cursor) {
+      throw new Error(`cms: re-index ${collection} stalled \u2014 the server returned the same cursor twice after ${scanned} row(s)${rerun}`);
+    }
+    if (pages >= REINDEX_PAGE_CAP) {
+      throw new Error(`cms: re-index ${collection} exceeded ${REINDEX_PAGE_CAP} pages (${scanned} row(s) scanned) without completing${rerun}`);
+    }
+    cursor = d.next_cursor;
+  }
+  return { scanned, updated, pages, skipped };
 }
-async function planCmsSchema({ api, collections, apply, allowDestructive = false }) {
-  const remote = await readRemote2(api);
+async function planCmsSchema({ api, collections, apply, allowDestructive = false, onProgress }) {
+  const read = await readRemote2(api);
+  if (read.unavailable) {
+    if (apply) {
+      throw new Error(
+        `cms: cannot read ${read.unavailable.route} (${read.unavailable.code ?? read.unavailable.status}${read.unavailable.message ? ` \u2014 ${read.unavailable.message}` : ""}) \u2014 refusing to apply a schema plan computed against an unread target`
+      );
+    }
+    return { changes: [], applied: 0, remoteUnavailable: read.unavailable };
+  }
+  const remote = read.map;
   const changes = [];
   for (const [name, def] of Object.entries(collections)) {
     const declaredFields = Object.entries(def.fields ?? {});
@@ -594,13 +951,30 @@ async function planCmsSchema({ api, collections, apply, allowDestructive = false
       });
       continue;
     }
+    const pre = [];
+    const collChanges = [];
+    const post = [];
+    const slotMoved = [];
     const remoteByName = new Map(rc.fields.map((f) => [f.field, f]));
     for (const [fn, fd] of declaredFields) {
       const existing = remoteByName.get(fn);
       if (!existing) {
-        changes.push({ collection: name, kind: "add-field", field: fn, detail: `${name}.${fn} (${fd.type})` });
+        collChanges.push({ collection: name, kind: "add-field", field: fn, detail: `${name}.${fn} (${fd.type})` });
       } else if (existing.type !== fd.type) {
-        changes.push({
+        if (allowDestructive && (fd.indexSlot ?? null) !== (existing.index_slot ?? null)) {
+          if (existing.index_slot) {
+            pre.push({
+              collection: name,
+              kind: "destructive",
+              op: "vacate-slot",
+              field: fn,
+              remote: existing,
+              detail: `${name}.${fn} vacate index_slot ${existing.index_slot} (two-pass: vacate \u2192 claim)`
+            });
+          }
+          slotMoved.push(fn);
+        }
+        collChanges.push({
           collection: name,
           kind: "destructive",
           op: "alter-field",
@@ -608,61 +982,73 @@ async function planCmsSchema({ api, collections, apply, allowDestructive = false
           detail: `${name}.${fn} type ${existing.type} \u2192 ${fd.type} (destructive alter)`
         });
       } else {
-        const { flags, clearing, drift } = fieldAttrDelta(fd, existing);
-        if (flags.length && clearing.length === 0) {
-          changes.push({
-            collection: name,
-            kind: "alter-flags",
-            field: fn,
-            detail: `${name}.${fn} ${flags.join(", ")} (non-destructive in-place alter)`
-          });
-        }
-        if (clearing.length) {
-          const both = [...clearing, ...flags];
+        const { flags, clearing, inPlace, reindex, retarget, drift } = fieldAttrDelta(fd, existing);
+        const destructiveAttrs = [...clearing, ...reindex, ...retarget];
+        if (destructiveAttrs.length) {
+          const all = [...destructiveAttrs, ...flags, ...inPlace];
           if (allowDestructive) {
-            changes.push({
+            if (reindex.length && existing.index_slot) {
+              pre.push({
+                collection: name,
+                kind: "destructive",
+                op: "vacate-slot",
+                field: fn,
+                remote: existing,
+                detail: `${name}.${fn} vacate index_slot ${existing.index_slot} (two-pass: vacate \u2192 claim)`
+              });
+            }
+            collChanges.push({
               collection: name,
               kind: "destructive",
               op: "alter-field",
               field: fn,
-              detail: `${name}.${fn} ${both.join(", ")} \u2014 clearing a live invariant (unique claims / on_delete cascade) (full-config reconciliation)`
+              detail: `${name}.${fn} ${all.join(", ")}` + (clearing.length ? " \u2014 clearing a live invariant (unique claims / on_delete cascade / read_roles gate)" : "") + (reindex.length ? " \u2014 an index_slot move: stored rows keep the OLD projection until the re-index runs" : "") + (retarget.length ? " \u2014 a relation retarget: every stored id now names a different collection" : "") + " (full-config reconciliation)"
             });
+            if (reindex.length) slotMoved.push(fn);
           } else {
-            changes.push({
+            collChanges.push({
               collection: name,
               kind: "warn",
               field: fn,
-              detail: `${name}.${fn} ${both.join(", ")}: this CLEARS a live invariant \u2014 clearing unique DROPS the uniqueness claims (duplicates then accepted, unrecoverable) and clearing on_delete stops cascades, so it is NOT applied (nor is any co-declared tightening on this field). Declare the attribute to keep it, or re-run with --allow-destructive to clear.`
+              detail: `${name}.${fn} ${all.join(", ")}: this is DESTRUCTIVE-SHAPED \u2014 ` + (clearing.length ? "it CLEARS a live invariant (clearing unique DROPS the uniqueness claims \u2014 duplicates then accepted, unrecoverable; clearing on_delete stops cascades; clearing read_roles WIDENS the field to every end-user); " : "") + (reindex.length ? "an index_slot move leaves stored rows on the OLD projection until a re-index, so queries on the field return the WRONG rows; " : "") + (retarget.length ? "a relation retarget repoints every stored id at another collection; " : "") + "it is NOT applied (nor is any co-declared in-place change on this field). Re-run with --allow-destructive to apply."
             });
           }
+        } else if (flags.length || inPlace.length) {
+          collChanges.push({
+            collection: name,
+            kind: "alter-flags",
+            field: fn,
+            detail: `${name}.${fn} ${[...flags, ...inPlace].join(", ")} (non-destructive in-place alter)`
+          });
         }
         if (drift.length) {
-          changes.push({
+          collChanges.push({
             collection: name,
             kind: "warn",
             field: fn,
-            detail: `${name}.${fn} drift: ${drift.join("; ")} \u2014 cms-v1 has no same-type in-place alter for these (only unique/on_delete alter in place); the difference is NOT applied. Match the config to the live definition, or re-create the field.`
+            detail: `${name}.${fn} drift: ${drift.join("; ")} \u2014 the config does NOT declare these, so they are left exactly as the live schema has them (an omitted attribute is never blanked). Declare them in vxil.config.ts to make config authoritative.`
           });
         }
+        continue;
       }
     }
     const declaredOwner = def.ownerField ?? null;
     const remoteOwner = rc.ownerField;
     if (declaredOwner !== remoteOwner) {
       if (declaredOwner !== null) {
-        changes.push({
+        collChanges.push({
           collection: name,
           kind: "set-owner-field",
           detail: `${name} owner_field \u2192 '${declaredOwner}'${remoteOwner ? ` (was '${remoteOwner}')` : ""} (end-user owner-scoping, non-destructive)`
         });
       } else if (allowDestructive) {
-        changes.push({
+        collChanges.push({
           collection: name,
           kind: "set-owner-field",
           detail: `${name} owner_field cleared (was '${remoteOwner}') \u2014 end-user owner-scoping OFF (full-config reconciliation)`
         });
       } else {
-        changes.push({
+        collChanges.push({
           collection: name,
           kind: "warn",
           detail: `${name}: owner_field '${remoteOwner}' is set remotely but absent in config \u2014 clearing it WIDENS access to every same-tenant end user, so it is NOT applied. Declare ownerField to keep it, or re-run with --allow-destructive to clear.`
@@ -671,7 +1057,7 @@ async function planCmsSchema({ api, collections, apply, allowDestructive = false
     }
     const declaredPublic = def.public === true;
     if (declaredPublic !== rc.public) {
-      changes.push({
+      collChanges.push({
         collection: name,
         kind: "set-public",
         detail: `${name} public \u2192 ${declaredPublic} (keyless public delivery ${declaredPublic ? "ON" : "OFF"})`
@@ -679,7 +1065,7 @@ async function planCmsSchema({ api, collections, apply, allowDestructive = false
     }
     const declaredActions = normalizeActions(def.actions);
     if (stableStringify(declaredActions) !== stableStringify(rc.actions)) {
-      changes.push({
+      collChanges.push({
         collection: name,
         kind: "set-actions",
         detail: `${name} actions \u2192 [${declaredActions.map((a) => `${a.key}\u2192${a.fn}`).join(", ")}] (was [${rc.actions.map((a) => `${a.key}\u2192${a.fn}`).join(", ")}])`
@@ -687,7 +1073,7 @@ async function planCmsSchema({ api, collections, apply, allowDestructive = false
     }
     for (const f of rc.fields) {
       if (!Object.prototype.hasOwnProperty.call(def.fields ?? {}, f.field)) {
-        changes.push({
+        collChanges.push({
           collection: name,
           kind: "destructive",
           op: "drop-field",
@@ -696,6 +1082,15 @@ async function planCmsSchema({ api, collections, apply, allowDestructive = false
         });
       }
     }
+    if (slotMoved.length) {
+      const n = await liveRowCount(api, name);
+      post.push({
+        collection: name,
+        kind: "reindex",
+        detail: `${name} re-index ${n === null ? "live rows" : `${n} live rows`} after the index_slot move on ${slotMoved.join(", ")}`
+      });
+    }
+    changes.push(...pre, ...collChanges, ...post);
   }
   if (allowDestructive) {
     for (const rname of remote.keys()) {
@@ -773,6 +1168,16 @@ async function planCmsSchema({ api, collections, apply, allowDestructive = false
           throw new Error(`cms: set actions on ${c.collection} failed: ${e.code ?? res.status} ${e.message ?? ""}`);
         }
         applied++;
+      } else if (c.kind === "reindex") {
+        const done = await reindexCollection({
+          api,
+          collection: c.collection,
+          onProgress: (p) => onProgress?.(`  \u2026 re-indexed ${p.scanned} row(s) of ${c.collection}` + (p.skipped > 0 ? ` (${p.skipped} skipped \u2014 written concurrently)` : ""))
+        });
+        if (done.skipped > 0) {
+          onProgress?.(`  \u26A0 ${done.skipped} row(s) of ${c.collection} were written while the re-index ran and were NOT re-projected \u2014 re-run \`vxil cms reindex ` + c.collection + "` when writes are quiet");
+        }
+        applied++;
       } else if (c.kind === "destructive") {
         applied += await applyDestructive(api, collections, c);
       }
@@ -799,6 +1204,15 @@ async function applyDestructive(api, collections, c) {
     }
     return 1;
   }
+  if (c.op === "vacate-slot") {
+    const rf = c.remote;
+    const res2 = await api("POST", path, vacateSlotBody(rf));
+    if (!ok2xx(res2.status) && res2.body.error?.code !== "already_exists") {
+      const e = res2.body.error ?? {};
+      throw new Error(`cms: vacate ${c.collection}.${c.field} slot failed: ${e.code ?? res2.status} ${e.message ?? ""}`);
+    }
+    return 1;
+  }
   const fd = collections[c.collection].fields[c.field];
   const res = await api("POST", path, { ...fieldToInput(c.field, fd), allow_destructive: true });
   if (!ok2xx(res.status)) {
@@ -812,6 +1226,7 @@ function formatCmsChanges(changes) {
   return changes.map((c) => {
     if (c.kind === "destructive") return `  ! ${c.detail}`;
     if (c.kind === "warn") return `  \u26A0 ${c.detail}`;
+    if (c.kind === "reindex") return `  \u21BB ${c.detail}`;
     if (c.kind === "alter-flags" || c.kind === "set-owner-field") return `  ~ ${c.detail}`;
     return `  + ${c.detail}`;
   }).join("\n");
@@ -1334,8 +1749,8 @@ function typeHandlers(types2) {
 function escapeIdentifiers(xs, { transform: { column } }) {
   return xs.map((x) => escapeIdentifier(column.to ? column.to(x) : x)).join(",");
 }
-var escapeIdentifier = function escape(str) {
-  return '"' + str.replace(/"/g, '""').replace(/\./g, '"."') + '"';
+var escapeIdentifier = function escape(str2) {
+  return '"' + str2.replace(/"/g, '""').replace(/\./g, '"."') + '"';
 };
 var inferType = function inferType2(x) {
   return x instanceof Parameter ? x.type : x instanceof Date ? 1184 : x instanceof Uint8Array ? 17 : x === true || x === false ? 16 : typeof x === "bigint" ? 20 : Array.isArray(x) ? inferType2(x[0]) : 0;
@@ -1410,16 +1825,16 @@ function arrayParserLoop(s, x, parser, typarray) {
   return xs;
 }
 var toCamel = (x) => {
-  let str = x[0];
+  let str2 = x[0];
   for (let i = 1; i < x.length; i++)
-    str += x[i] === "_" ? x[++i].toUpperCase() : x[i];
-  return str;
+    str2 += x[i] === "_" ? x[++i].toUpperCase() : x[i];
+  return str2;
 };
 var toPascal = (x) => {
-  let str = x[0].toUpperCase();
+  let str2 = x[0].toUpperCase();
   for (let i = 1; i < x.length; i++)
-    str += x[i] === "_" ? x[++i].toUpperCase() : x[i];
-  return str;
+    str2 += x[i] === "_" ? x[++i].toUpperCase() : x[i];
+  return str2;
 };
 var toKebab = (x) => x.replace(/_/g, "-");
 var fromCamel = (x) => x.replace(/([A-Z])/g, "_$1").toLowerCase();
@@ -2330,8 +2745,8 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
     bytes_default.i16(0);
     return bytes_default.end();
   }
-  function Parse(str, parameters, types2, name = "") {
-    bytes_default().P().str(name + bytes_default.N).str(str + bytes_default.N).i16(parameters.length);
+  function Parse(str2, parameters, types2, name = "") {
+    bytes_default().P().str(name + bytes_default.N).str(str2 + bytes_default.N).i16(parameters.length);
     parameters.forEach((x, i) => bytes_default.i32(types2[i] || 0));
     return bytes_default.end();
   }
@@ -3282,8 +3697,28 @@ function slottedFields(c) {
 function isFilterableField(f) {
   return !(f.computed && !f.index_slot);
 }
+var MAX_ENUM_UNION = 50;
+function enumUnionFor(f) {
+  const raw = f.validation?.enum;
+  if (!Array.isArray(raw) || raw.length === 0 || raw.length > MAX_ENUM_UNION) return null;
+  const base = tsTypeFor(f.type);
+  if (base !== "string" && base !== "number" && base !== "boolean") return null;
+  const members = [];
+  for (const v of raw) {
+    const t = typeof v;
+    if (t !== "string" && t !== "number" && t !== "boolean") return null;
+    if (t !== base) return null;
+    members.push(JSON.stringify(v));
+  }
+  return members.join(" | ");
+}
+function hasEnumFilter(c) {
+  return c.fields.some((f) => isFilterableField(f) && enumUnionFor(f) !== null);
+}
 function filterTypeFor(f) {
   const slot = f.index_slot ?? "";
+  const u = enumUnionFor(f);
+  if (u) return slot ? `VxilFilterRangeEnum<${u}>` : `VxilFilterEnum<${u}>`;
   if (slot.startsWith("s")) return "VxilFilterRangeText";
   if (slot.startsWith("n")) return "VxilFilterRange<number>";
   if (slot.startsWith("t")) return "VxilFilterRangeDatetime";
@@ -3308,15 +3743,16 @@ function unionOf(values2) {
 function collectionType(c) {
   const lines = [];
   const ind = "        ";
+  const typeOf = (f) => enumUnionFor(f) ?? tsTypeFor(f.type);
   const rowFields = c.fields.map((f) => {
-    const t = tsTypeFor(f.type);
+    const t = typeOf(f);
     return f.required ? `${ind}${quoteKey(f.field)}: ${t};` : `${ind}${quoteKey(f.field)}: ${t} | null;`;
   });
   const insertFields = c.fields.filter((f) => !f.computed).map((f) => {
-    const t = tsTypeFor(f.type);
+    const t = typeOf(f);
     return f.required ? `${ind}${quoteKey(f.field)}: ${t};` : `${ind}${quoteKey(f.field)}?: ${t} | null;`;
   });
-  const patchFields = c.fields.filter((f) => !f.computed).map((f) => `${ind}${quoteKey(f.field)}?: ${tsTypeFor(f.type)} | null;`);
+  const patchFields = c.fields.filter((f) => !f.computed).map((f) => `${ind}${quoteKey(f.field)}?: ${typeOf(f)} | null;`);
   const slotted = slottedFields(c);
   const sortable = unionOf([...slotted.map((f) => f.field), ...META_SORTABLE]);
   const statusUnion = unionOf([...CMS_STATUS_VALUES]);
@@ -3340,6 +3776,10 @@ ${patchFields.join("\n") || `${ind}/* (no patchable fields) */`}
       };`);
   lines.push(`      Sortable: ${sortable};`);
   lines.push(`      Filterable: ${filterable};`);
+  const relLines = c.fields.filter((f) => f.type === "relation" || f.type === "file").map((f) => `${ind}${quoteKey(f.field)}: ${f.type === "file" ? "'files'" : JSON.stringify(f.relation_to ?? null)};`);
+  lines.push(`      Relations: ${relLines.length ? `{
+${relLines.join("\n")}
+      }` : "{}"};`);
   lines.push(`    };`);
   return lines.join("\n");
 }
@@ -3382,6 +3822,9 @@ export const API_VERSIONS = {
 ` + apiVers.map(([f, v]) => `  ${quoteKey(f)}: [${v.map((x) => JSON.stringify(x)).join(", ")}],`).join("\n") + `
 } as const;` : "";
   const cmsBody = colls.length ? colls.map(collectionType).join("\n") : "    // (no collections \u2014 `vx.from(...)` is empty until you declare one)";
+  const enumAliases = colls.some(hasEnumFilter) ? `
+export type VxilFilterEnum<U extends string | number | boolean> = U | { $eq?: U; $in?: U[]; $contains?: string };
+export type VxilFilterRangeEnum<U extends string | number | boolean> = U | { $eq?: U; $ne?: U; $gt?: U; $gte?: U; $lt?: U; $lte?: U; $in?: U[]; $contains?: string };` : "";
   const fnBody = fns.length ? fns.map(functionType).join("\n") : "    // (no deployed functions)";
   return `${header}
 
@@ -3414,7 +3857,7 @@ export type VxilFilterEqText = string | { $eq?: string; $in?: string[]; $contain
 export type VxilFilterRange<T> = T | { $eq?: T; $ne?: T; $gt?: T; $gte?: T; $lt?: T; $lte?: T; $in?: T[] };
 export type VxilFilterRangeText = string | { $eq?: string; $ne?: string; $gt?: string; $gte?: string; $lt?: string; $lte?: string; $in?: string[]; $contains?: string };
 export type VxilFilterRangeDatetime = string | { $eq?: string; $ne?: string; $gt?: string; $gte?: string; $lt?: string; $lte?: string; $in?: string[]; $contains?: string };
-export type VxilFilterJson = string | number | boolean | { $eq?: string | number | boolean; $in?: (string | number | boolean)[]; $contains?: string };
+export type VxilFilterJson = string | number | boolean | { $eq?: string | number | boolean; $in?: (string | number | boolean)[]; $contains?: string };${enumAliases}
 
 // Usage \u2014 narrow the client to THIS tenant's enabled features (a disabled feature
 // becomes a compile error):
@@ -3446,12 +3889,12 @@ var TOOLS = [
   {
     name: "notifications_send",
     feature: "notifications",
-    description: "Send a transactional email to an end-user by ID. Returns a delivery_id immediately (202); delivery is asynchronous. Templates: magic-link (data: url, expires_minutes), welcome (data: app_name, first_name?), transactional (data: subject, paragraph, cta_label?, cta_url?).",
+    description: "Send a transactional email to an end-user by ID. Returns a delivery_id immediately (202); delivery is asynchronous. Templates: magic-link (data: url, expires_minutes), otp-code (data: code, expires_minutes), welcome (data: app_name, first_name?), transactional (data: subject, paragraph, cta_label?, cta_url?).",
     inputSchema: {
       type: "object",
       properties: {
         user_id: { type: "string", description: "Opaque end_user_id (your user id)." },
-        template: { type: "string", enum: ["magic-link", "welcome", "transactional"] },
+        template: { type: "string", enum: ["magic-link", "otp-code", "welcome", "transactional"] },
         data: { type: "object", additionalProperties: true },
         locale: {
           type: "string",
@@ -3537,6 +3980,42 @@ var TOOLS = [
     path: "/v1/notifications/deliveries",
     queryArgs: ["user_id", "status", "engagement", "limit"]
   },
+  {
+    name: "notifications_get_preferences",
+    feature: "notifications",
+    description: "Read one end-user's notification mutes. Returns { preferences: [{ user_id, template_id, muted, effective, updated_at }], count } \u2014 the all-templates row (template_id null) first. NO row means NOT muted. MUTE WINS: the all-templates row SHADOWS a per-template muted:false, and `effective` is what enforcement actually does with that row (render `effective`, not `muted`). A mute suppresses the user on EVERY channel before the send leaves vxil (the delivery is recorded with status 'suppressed' and last_error_code 'muted'), except auth mail (magic-link, otp-code), which is never muteable. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        user_id: { type: "string", description: "Opaque end_user_id (your user id)." }
+      },
+      required: ["user_id"]
+    },
+    method: "GET",
+    path: "/v1/notifications/preferences",
+    queryArgs: ["user_id"]
+  },
+  {
+    name: "notifications_set_preference",
+    feature: "notifications",
+    description: "Mute or un-mute an end-user's notifications. OMIT template_id to mute every MUTEABLE template for that user (welcome, transactional); pass one of those ids to mute just that one. Auth mail (magic-link, otp-code) is NEVER muteable \u2014 passing it is a 422, and the all-templates row does not cover it, so a user can never mute itself out of sign-in. MUTE WINS: the all-templates row shadows a per-template muted:false, so clear it before re-enabling one template. Idempotent upsert \u2014 there is no delete route, muted:false is the un-mute. 404 if the user id has no live record. Needs notifications:send (a server key writing another principal's row).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        user_id: { type: "string", description: "Opaque end_user_id (your user id)." },
+        template_id: {
+          type: "string",
+          // MUTEABLE ids only — auth mail is rejected by the route (422).
+          enum: ["welcome", "transactional"],
+          description: "Omit for the ALL-templates row (muteable templates only)."
+        },
+        muted: { type: "boolean" }
+      },
+      required: ["user_id", "muted"]
+    },
+    method: "PUT",
+    path: "/v1/notifications/preferences"
+  },
   {
     name: "notifications_campaign_run",
     feature: "notifications",
@@ -3997,7 +4476,7 @@ var TOOLS = [
   {
     name: "cms_query_items",
     feature: "cms",
-    description: 'Query content items with the bounded DSL. filter is a JSON object (\u22648 terms): {"price":{"$gte":10},"status":"published"}; ops $eq $ne $gt $gte $lt $lte $in $contains $startsWith (substring/prefix, LIKE-escaped) $arrayContains/$anyOf (array fields: all-of / any-of). sort: "-field" (slot-indexed fields + created_at/updated_at/published_at). count=true returns {count} instead of a page (filter only \u2014 no sort/limit).',
+    description: 'Query content items with the bounded DSL. filter is a JSON object (\u22648 terms): {"price":{"$gte":10},"status":"published"}; ops $eq $ne $gt $gte $lt $lte $in $contains $startsWith (substring/prefix, LIKE-escaped) $arrayContains/$anyOf (array fields: all-of / any-of). sort: "-field" (slot-indexed fields + created_at/updated_at/published_at). $expand inlines relation/file fields. count=true returns {count} instead of a page (filter only \u2014 no sort/limit/$expand).',
     inputSchema: {
       type: "object",
       properties: {
@@ -4005,13 +4484,17 @@ var TOOLS = [
         filter: { type: "string", description: "JSON filter object as a string" },
         sort: { type: "string" },
         limit: { type: "number", default: 25 },
+        $expand: {
+          type: "string",
+          description: "comma-separated relation/file field names to inline (bounded depth; see cms_list_collections for relation_to). Cannot be combined with count=true."
+        },
         count: { type: "boolean", description: "true \u2192 return { count } only (no items/paging)" }
       },
       required: ["collection"]
     },
     method: "GET",
     path: (a) => `/v1/cms/items/${encodeURIComponent(String(a.collection))}`,
-    queryArgs: ["filter", "sort", "limit", "count"]
+    queryArgs: ["filter", "sort", "limit", "$expand", "count"]
   },
   {
     name: "cms_inc_item",
@@ -4575,6 +5058,22 @@ var TOOLS = [
           maxItems: 8,
           description: "Vision inputs: a public https URL, a data:image/...;base64 URL, or file:<object_id> (a files object). Provider must support the 'vision' capability."
         },
+        documents: {
+          type: "array",
+          items: { type: "string" },
+          maxItems: 8,
+          description: "Document inputs (pdf / plain text): a public https URL, a data:application/pdf;base64 URL, or file:<object_id>. Fetched and inlined server-side. Provider must support the 'documents' capability (anthropic)."
+        },
+        cache: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            system: { type: "boolean" },
+            messages: { type: "boolean" },
+            ttl: { type: "string", enum: ["5m", "1h"] }
+          },
+          description: "Prompt-cache breakpoints (anthropic; ignored elsewhere): system caches the system prompt, messages caches the transcript prefix, ttl picks 5m (default) or 1h. A cache hit only lowers input_tokens."
+        },
         user_id: { type: "string", description: "Opaque end_user_id for per-user usage metering." }
       }
     },
@@ -4740,7 +5239,7 @@ var TOOLS = [
   {
     name: "payments_list_webhook_events",
     feature: "payments",
-    description: "List provider webhook deliveries from the event log, newest-first: outcome (received|processed|error|sig_failed|parse_failed|reprocessed|ignored|unowned|rejected_environment), the provider-reported environment (production|sandbox), signature status, error, and timestamps per delivery. Use it to diagnose billing sync issues (e.g. an unmapped price or product \u2192 outcome error, a misconfigured webhook secret producing sig_failed rows, sandbox deliveries landing as rejected_environment). Read-only \u2014 needs payments:read. Payloads are detail-only (console surface).",
+    description: "List provider webhook deliveries from the event log, newest-first: outcome (received|processed|error|sig_failed|parse_failed|reprocessed|ignored|unowned|rejected_environment), the provider-reported environment (production|sandbox), signature status, error, and timestamps per delivery. Use it to diagnose billing sync issues (e.g. an unmapped price or product \u2192 outcome error, a misconfigured webhook secret producing sig_failed rows, sandbox deliveries landing as rejected_environment). An unmapped one-off product lands `error` unless you set ledger.unmappedProduct:'ignore', which lands it `ignored` instead. Read-only \u2014 needs payments:read. Server-side key only (403 server_only on a thin-client/end-user key) \u2014 the log is tenant-wide and carries provider payloads. Payloads are detail-only (console surface).",
     inputSchema: {
       type: "object",
       properties: {
@@ -4768,7 +5267,7 @@ var TOOLS = [
     // Substrate tool (no `feature` — always-on like users_upsert): usage is a
     // platform property, not a feature you enable.
     name: "usage_current",
-    description: "Current-month usage for this project: requests used, the plan's included quota, remaining (null when the plan has no fixed cap), and month-to-date per-feature metered detail (may lag \u2014 it is aggregated periodically). Read-only. Call this before a bulk run to self-check remaining quota: the Free tier is hard-capped (429 quota_exceeded when exhausted); paid tiers are never cut off mid-month. Needs usage:read or features:read.",
+    description: "Current-month usage for this project: requests used, the plan's included quota, remaining (null when the plan has no fixed cap), month-to-date per-feature metered detail (may lag \u2014 it is aggregated periodically), and `routes` \u2014 the same request count split by the surface that served it (the resolved upstream; /v1/fn/* reports as 'fn-invoke', busiest first, observational only). Read-only. Call this before a bulk run to self-check remaining quota: the Free tier is hard-capped (429 quota_exceeded when exhausted); paid tiers are never cut off mid-month. Needs usage:read or features:read.",
     inputSchema: { type: "object", properties: {} },
     method: "GET",
     path: "/v1/usage"
@@ -4828,12 +5327,13 @@ var TOOLS = [
     // Substrate meta-tool (no `feature` — always-on, subject to the caller's
     // scopes). Maps to POST /v1/plan (features:read). Advisory: proposes, never applies.
     name: "plan_backend",
-    description: 'Describe an app in plain English and get an ADVISORY vxil plan: which features to enable, a materialized config draft, and which truly-unique logic needs a tenant function. Read-only \u2014 it proposes a plan; you review and apply it via config push. e.g. "a marketplace where sellers list products and buyers leave reviews, emailing both on a sale".',
+    description: 'Describe an app in plain English and get an ADVISORY vxil plan: which features to enable, a materialized config draft, and which truly-unique logic needs a tenant function. Read-only \u2014 it proposes a plan; you review and apply it via config push. e.g. "a marketplace where sellers list products and buyers leave reviews, emailing both on a sale". The response also carries an architecture brief: the platform rules this plan implies (identity, data, money path, background work, limits) and the older patterns they replace.',
     inputSchema: {
       type: "object",
       properties: {
         description: { type: "string", description: "Plain-English description of the app you want to build." },
-        name: { type: "string", description: "Optional app name for the plan." }
+        name: { type: "string", description: "Optional app name for the plan." },
+        brief: { type: "boolean", description: "Include the architecture brief (identity, data, money path, background work, limits, and the old patterns vxil replaces). Default true; pass false for the plan alone." }
       },
       required: ["description"]
     },
@@ -4934,18 +5434,18 @@ function buildMcpCatalog(input, tools = TOOLS) {
 }
 
 // src/store.ts
-import { homedir } from "node:os";
+import { homedir as homedir2 } from "node:os";
 import { join as join2, resolve as resolve3 } from "node:path";
-import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, writeFileSync as writeFileSync2, chmodSync } from "node:fs";
+import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync3, writeFileSync as writeFileSync2, chmodSync } from "node:fs";
 function credDir() {
-  return join2(homedir(), ".vxil");
+  return join2(homedir2(), ".vxil");
 }
 function credFile() {
   return join2(credDir(), "credentials.json");
 }
 function loadCredentials() {
   try {
-    return JSON.parse(readFileSync2(credFile(), "utf8"));
+    return JSON.parse(readFileSync3(credFile(), "utf8"));
   } catch {
     return {};
   }
@@ -4963,7 +5463,7 @@ function projectFile(cwd = process.cwd()) {
 }
 function loadProject(cwd = process.cwd()) {
   try {
-    return JSON.parse(readFileSync2(projectFile(cwd), "utf8"));
+    return JSON.parse(readFileSync3(projectFile(cwd), "utf8"));
   } catch {
     return null;
   }
@@ -4999,7 +5499,15 @@ function bindNamedSlot(existing, name, slot) {
     );
   }
   if (name === "dev") {
-    return { ...existing, dev: { tenant_id: slot.tenant_id, slug: slot.slug, edge_url: slot.edge_url } };
+    return {
+      ...existing,
+      dev: {
+        tenant_id: slot.tenant_id,
+        slug: slot.slug,
+        edge_url: slot.edge_url,
+        ...slot.expires_at ? { expires_at: slot.expires_at } : {}
+      }
+    };
   }
   const { expires_at: _x, ...permanent } = slot;
   void _x;
@@ -5265,6 +5773,28 @@ function driftExitCode(r) {
   if (r.errors > 0) return 2;
   return r.drift > 0 ? 1 : 0;
 }
+function newComparedCounts(opts = {}) {
+  const base = { features: 0, collections: 0, functions: 0, secrets: 0 };
+  return opts.apiState ? { ...base, policies: 0, subscriptions: 0, campaigns: 0 } : base;
+}
+var COMPARED_LABELS = [
+  ["features", "feature"],
+  ["collections", "collection"],
+  ["functions", "function"],
+  ["secrets", "secret ref"],
+  ["policies", "policy"],
+  ["subscriptions", "subscription"],
+  ["campaigns", "campaign"]
+];
+function formatCompared(c) {
+  const parts = [];
+  for (const [key, label] of COMPARED_LABELS) {
+    const v = c[key];
+    if (v === void 0) continue;
+    parts.push(label === "policy" ? `${v} policy(ies)` : `${v} ${label}(s)`);
+  }
+  return parts.join(" \xB7 ");
+}
 
 // src/doctor.ts
 var SECRETS_ADVISORY_NOTE = "advisory only: a config push with an unstored `secret:<name>` ref is a WARNING, never a 422 \u2014 vxil's promotion order sets production secrets AFTER the config push (`vxil secrets set <feature>/<name>`); doctor never deletes a stored secret";
@@ -5307,6 +5837,17 @@ function notificationsProviderChecks(manifest) {
   }
   return [{ name: "notifications provider", ok: true, warn: true, detail: MOCK_PROVIDER_NOTE }];
 }
+var PAYMENTS_WEBHOOK_SECRET_NOTE = "payments provider is real but no per-tenant webhook secret is declared: every inbound provider delivery will be rejected 401 bad_signature and recorded as a sig_failed row (those rows can never be reprocessed, so the money events behind them are lost). There is NO platform-wide fallback. Declare <provider>.webhookSecretRef in your payments config and store the value with `vxil secrets set payments/<name>`";
+function paymentsWebhookSecretChecks(manifest) {
+  if (!manifest || manifest.enabled === false) return [];
+  const provider = String(manifest.provider ?? "");
+  if (provider === "mock" || provider === "") return [];
+  const declared = provider === "paypal" ? !!manifest.paypal?.webhookId && !!manifest.paypal?.clientIdRef && !!manifest.paypal?.secretRef : provider === "stripe" ? !!manifest.stripe?.webhookSecretRef : provider === "paddle" ? !!manifest.paddle?.webhookSecretRef : provider === "revenuecat" ? !!manifest.revenuecat?.webhookSecretRef : true;
+  if (declared) {
+    return [{ name: "payments webhook secret", ok: true, detail: `${provider} \xB7 webhook credential declared` }];
+  }
+  return [{ name: "payments webhook secret", ok: true, warn: true, detail: `${provider}: ${PAYMENTS_WEBHOOK_SECRET_NOTE}` }];
+}
 function sha12Of(scriptRef) {
   if (!scriptRef) return void 0;
   const m = /-([0-9a-f]{12})$/.exec(scriptRef);
@@ -5353,6 +5894,36 @@ function functionChecks(rows) {
     ...r.verdict === "local-changed" || r.verdict === "not-deployed" || r.verdict === "remote-only" || r.verdict === "served-unpublished" ? { warn: true } : {}
   }));
 }
+function devSlotExpiryCheck(dev, now) {
+  if (!dev) return null;
+  if (!dev.expires_at) {
+    return {
+      name: "dev slot expiry",
+      ok: true,
+      warn: true,
+      detail: `unknown for '${dev.slug}' \u2014 run \`vxil dev up\` to refresh it (a slot bound with \`vxil link --as dev\`, or written before the CLI tracked TTLs, carries none)`
+    };
+  }
+  const ms = new Date(dev.expires_at).getTime();
+  if (!Number.isFinite(ms)) {
+    return { name: "dev slot expiry", ok: true, warn: true, detail: `unreadable expiry '${dev.expires_at}' on '${dev.slug}' \u2014 run \`vxil dev up\`` };
+  }
+  const hours = Math.round((ms - now.getTime()) / 36e5);
+  if (hours <= 0) {
+    return {
+      name: "dev slot expiry",
+      ok: true,
+      warn: true,
+      detail: `'${dev.slug}' EXPIRED ${dev.expires_at} (${Math.abs(hours)}h ago) \u2014 the nightly reaper deletes it; run \`vxil dev up\``
+    };
+  }
+  return {
+    name: "dev slot expiry",
+    ok: true,
+    ...hours < 72 ? { warn: true } : {},
+    detail: `'${dev.slug}' expires ${dev.expires_at} (in ${hours}h)` + (hours < 72 ? " \u2014 run `vxil dev up` to extend" : "")
+  };
+}
 
 // src/link.ts
 function data(r) {
@@ -5441,6 +6012,37 @@ async function devDown(dash, cookie, dev) {
     `dev down failed (${e?.code ?? r.status}${e?.message ? ` \u2014 ${e.message}` : ""})`
   );
 }
+async function devExtend(dash, cookie, dev, ttlHours) {
+  const r = await dash(
+    "POST",
+    `/dashboard/tenants/${dev.tenant_id}/extend`,
+    ttlHours === void 0 ? {} : { ttl_hours: ttlHours },
+    cookie
+  );
+  if (r.status === 200) {
+    const d = r.json.data ?? r.json;
+    return { extended: true, ...d.expires_at ? { expires_at: d.expires_at } : {} };
+  }
+  if (r.status === 404) return { gone: true };
+  const e = r.json.error;
+  if (r.status === 409 && e?.code === "not_a_dev_tenant") return { notDev: true };
+  throw new Error(
+    `dev tenant extend failed (${e?.code ?? r.status}${e?.message ? ` - ${e.message}` : ""})`
+  );
+}
+var TTL_MIN_HOURS = 1;
+var TTL_MAX_HOURS = 720;
+function parseTtlFlag(raw, fallback) {
+  if (raw === void 0) return { hours: fallback };
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < TTL_MIN_HOURS || n > TTL_MAX_HOURS) {
+    return { error: `--ttl '${raw}': expected a whole number of HOURS, ${TTL_MIN_HOURS}..${TTL_MAX_HOURS} (default ${fallback})` };
+  }
+  return { hours: n };
+}
+function haveDashSession(creds, email, password) {
+  return Boolean(creds.session) || Boolean(email && password);
+}
 
 // src/envPull.ts
 var MANAGED_HEADER = "# vxil (managed by `vxil env pull`)";
@@ -5502,6 +6104,13 @@ function pickBranchSlot(binding, name, now, hasKey) {
   if (!hasKey(slot.slug)) return { create: true };
   return { reuse: slot };
 }
+function pickDevSlot(binding, now, hasKey) {
+  const slot = binding?.dev;
+  if (!slot) return { create: true };
+  if (slot.expires_at && new Date(slot.expires_at).getTime() <= now.getTime()) return { create: true };
+  if (!hasKey(slot.slug)) return { create: true };
+  return { reuse: slot };
+}
 async function createBranchTenant(dash, opts) {
   const r = await dash("POST", "/dashboard/quickstart", {
     email: opts.email,
@@ -5528,6 +6137,159 @@ async function createBranchTenant(dash, opts) {
   };
 }
 
+// src/promotionGate.ts
+var NON_PRODUCTION_ENV_LABELS = /* @__PURE__ */ new Set([
+  "staging",
+  "stage",
+  "dev",
+  "development",
+  "test",
+  "qa",
+  "preview",
+  "sandbox",
+  "local"
+]);
+function normalizeLabel(label) {
+  return label.trim().toLowerCase();
+}
+function isNonProductionLabel(label) {
+  return NON_PRODUCTION_ENV_LABELS.has(normalizeLabel(label));
+}
+function isDevSlot(t) {
+  return t.slot === "dev" || t.slot === "named" && t.selector.kind === "named" && t.selector.name === "dev";
+}
+function isProductionTarget(t) {
+  if (isDevSlot(t)) return false;
+  if (normalizeLabel(t.envLabel) === "production") return true;
+  return envLabelFor(t.baseUrl) === "production" && !isNonProductionLabel(t.envLabel);
+}
+function hostOf(baseUrl) {
+  try {
+    return new URL(baseUrl).host;
+  } catch {
+    return baseUrl;
+  }
+}
+function unrecognizedLabelNotice(t) {
+  if (isDevSlot(t)) return null;
+  if (normalizeLabel(t.envLabel) === "production") return null;
+  if (envLabelFor(t.baseUrl) !== "production") return null;
+  if (isNonProductionLabel(t.envLabel)) return null;
+  return `env label '${t.envLabel}' is not a recognized environment and the host is ${hostOf(t.baseUrl)} \u2014 treating this target as PRODUCTION (use --env staging|dev|test|qa|preview|sandbox|local to say otherwise)`;
+}
+function envLabelWarning(label, baseUrl) {
+  const l = normalizeLabel(label);
+  const host = hostOf(baseUrl);
+  if (envLabelFor(baseUrl) === "production") {
+    if (l === "production") return null;
+    if (isNonProductionLabel(l)) {
+      return `slot labelled '${label}' on the PRODUCTION host ${host} \u2014 the push promotion gate will NOT fire for it (the documented staging-twin pattern; re-link with --env production if this IS a production tenant)`;
+    }
+    return `env label '${label}' is not a recognized environment \u2014 on the PRODUCTION host ${host} it is treated as PRODUCTION (the push promotion gate WILL fire). Use production|staging|dev|test|qa|preview|sandbox|local.`;
+  }
+  if (l === "production") {
+    return `slot labelled 'production' on the non-production host ${host} \u2014 the push promotion gate WILL fire for it`;
+  }
+  return null;
+}
+function isPlainObject2(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function leafAt(manifest, dotted) {
+  let cur = manifest;
+  for (const seg of dotted.split(".")) {
+    if (!isPlainObject2(cur)) return void 0;
+    cur = cur[seg];
+  }
+  return cur;
+}
+function mockFeatures(cfg) {
+  return Object.entries(cfg.features ?? {}).filter(([, conf]) => {
+    if (!isPlainObject2(conf)) return false;
+    const c = conf;
+    return c.provider === "mock" || c.defaultProvider === "mock" || (isPlainObject2(c.embed) ? c.embed.provider === "mock" : false);
+  }).map(([f]) => f);
+}
+var SANDBOX_LEAVES = [
+  { feature: "payments", path: "paddle.sandbox" },
+  { feature: "payments", path: "paypal.sandbox" },
+  { feature: "payments", path: "revenuecat.acceptSandbox" }
+];
+function sandboxFeatures(cfg) {
+  const out = [];
+  for (const leaf of SANDBOX_LEAVES) {
+    const manifest = (cfg.features ?? {})[leaf.feature];
+    if (leafAt(manifest, leaf.path) === true) out.push(`${leaf.feature}.${leaf.path}`);
+  }
+  return out;
+}
+function isDevHost(host) {
+  const h = host.toLowerCase().replace(/:\d+$/, "").replace(/^\[|\]$/g, "");
+  if (h === "localhost" || h.endsWith(".localhost")) return true;
+  if (h === "127.0.0.1" || h.startsWith("127.")) return true;
+  if (h === "::1") return true;
+  if (h === "local" || h.endsWith(".local")) return true;
+  if (/^10\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(h)) return true;
+  if (/^192\.168\.\d{1,3}\.\d{1,3}$/.test(h)) return true;
+  if (/^172\.(1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}$/.test(h)) return true;
+  return false;
+}
+function devRedirectOrigins(origins = []) {
+  const out = [];
+  for (const raw of origins) {
+    if (typeof raw !== "string" || !raw) continue;
+    if (/^http:\/\//i.test(raw)) {
+      out.push(raw);
+      continue;
+    }
+    const host = raw.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "").replace(/[/?#].*$/, "");
+    if (host && isDevHost(host)) out.push(raw);
+  }
+  return out;
+}
+function redirectOrigins(cfg) {
+  const v = leafAt((cfg.features ?? {}).auth, "security.allowedRedirectOrigins");
+  return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+}
+var PROMOTION_OVERRIDE_FLAGS = {
+  mock: "allow-mock-in-prod",
+  sandbox: "allow-sandbox-in-prod",
+  origins: "allow-dev-origins-in-prod"
+};
+function promotionRefusals(cfg, allowed) {
+  const out = [];
+  const mocks = mockFeatures(cfg);
+  if (mocks.length && !allowed(PROMOTION_OVERRIDE_FLAGS.mock)) {
+    out.push({
+      kind: "mock",
+      flag: PROMOTION_OVERRIDE_FLAGS.mock,
+      message: `mock providers on [${mocks.join(", ")}] would ship to production (mock email/payments silently no-op). Set a real provider, or override with --${PROMOTION_OVERRIDE_FLAGS.mock}.`
+    });
+  }
+  const sandboxes = sandboxFeatures(cfg);
+  if (sandboxes.length && !allowed(PROMOTION_OVERRIDE_FLAGS.sandbox)) {
+    out.push({
+      kind: "sandbox",
+      flag: PROMOTION_OVERRIDE_FLAGS.sandbox,
+      message: `sandbox provider flags [${sandboxes.join(", ")}] would ship to a live money path (a sandbox key signs with the wrong secret; RevenueCat folds test purchases as outcome rejected_environment). Set them false, or override with --${PROMOTION_OVERRIDE_FLAGS.sandbox}.`
+    });
+  }
+  const devOrigins = devRedirectOrigins(redirectOrigins(cfg));
+  if (devOrigins.length && !allowed(PROMOTION_OVERRIDE_FLAGS.origins)) {
+    out.push({
+      kind: "origins",
+      flag: PROMOTION_OVERRIDE_FLAGS.origins,
+      message: `auth.security.allowedRedirectOrigins contains non-production origin(s) [${devOrigins.join(", ")}] \u2014 a loopback / .local / http:// redirect target on a production auth tenant is a token-exfiltration footgun. Remove them, or override with --${PROMOTION_OVERRIDE_FLAGS.origins}.`
+    });
+  }
+  return out;
+}
+function redirectOriginNotice(cfg) {
+  const origins = redirectOrigins(cfg);
+  if (!origins.length) return null;
+  return `auth.security.allowedRedirectOrigins (${origins.length}): ${origins.join(", ")}`;
+}
+
 // src/try.ts
 async function mintTry(fetchImpl, base, opts = {}) {
   const url = `${base.replace(/\/$/, "")}/v1/try`;
@@ -5649,11 +6411,11 @@ function formatSimulate(r) {
 }
 
 // src/migrate/paymentsSync.ts
-import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync5 } from "node:fs";
-import { dirname as dirname3, resolve as resolve5 } from "node:path";
+import { existsSync as existsSync6, mkdirSync as mkdirSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync5 } from "node:fs";
+import { dirname as dirname4, resolve as resolve5 } from "node:path";
 
 // src/migrate/commands.ts
-import { appendFileSync, existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "node:fs";
+import { appendFileSync, existsSync as existsSync5, mkdirSync as mkdirSync3, readFileSync as readFileSync5, writeFileSync as writeFileSync4 } from "node:fs";
 import { basename as basename2, resolve as resolve4 } from "node:path";
 
 // src/migrate/inference.ts
@@ -5742,7 +6504,7 @@ function detectOwner(table, source, authTable, opts) {
   for (const p of source.rlsPolicies ?? []) {
     if (lastSeg(p.table) !== table.name) continue;
     const m = /auth\.uid\(\)\s*=\s*(?:[\w"]+\.)?"?([A-Za-z_]\w*)"?/.exec(p.definition) ?? /(?:[\w"]+\.)?"?([A-Za-z_]\w*)"?\s*=\s*auth\.uid\(\)/.exec(p.definition);
-    if (m && cols.has(m[1])) return { column: m[1], via: `RLS policy${p.name ? ` '${p.name}'` : ""}` };
+    if (m && cols.has(m[1])) return { column: m[1], via: `row-level access rule${p.name ? ` '${p.name}'` : ""}` };
   }
   for (const fk of source.foreignKeys) {
     if (fk.childTable !== table.name || fk.childColumns.length !== 1) continue;
@@ -6081,7 +6843,7 @@ function inferMapping(source, opts = {}) {
   }
   if ((source.rlsPolicies?.length ?? 0) > 0) {
     residuals.push(
-      `R15: ${source.rlsPolicies.length} RLS policies are NOT recreated \u2014 they become per-collection ownerField + an end_user_required key + the X-Vxil-End-User principal (R6/R7); raw policies are listed in the plan for review`
+      `R15: ${source.rlsPolicies.length} row-level access rules are NOT recreated \u2014 they become per-collection ownerField + an end_user_required key + the X-Vxil-End-User principal (R6/R7); raw policies are listed in the plan for review`
     );
   }
   if ((source.buckets?.length ?? 0) > 0) {
@@ -6135,8 +6897,8 @@ function topoOrder(cmsNames, fks, profileTable, warnings) {
 }
 
 // src/migrate/loaders/index.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
-import { dirname as dirname2 } from "node:path";
+import { existsSync as existsSync4, mkdirSync as mkdirSync2, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "node:fs";
+import { dirname as dirname3 } from "node:path";
 
 // src/migrate/types.ts
 function newMigrateState() {
@@ -6949,10 +7711,10 @@ async function verifyMigration({ deps, plan, adapter, state }) {
 
 // src/migrate/loaders/index.ts
 function loadMigrateState(stateFile) {
-  if (!existsSync3(stateFile)) return newMigrateState();
+  if (!existsSync4(stateFile)) return newMigrateState();
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync3(stateFile, "utf8"));
+    parsed = JSON.parse(readFileSync4(stateFile, "utf8"));
   } catch (e) {
     throw new Error(
       `migrate state ${stateFile} is not parseable JSON (${e.message.split("\n")[0]}) \u2014 fix or delete the file (deleting restarts the migration; loaded cms rows are still deduped only if the id-map inside it is preserved).`
@@ -6970,7 +7732,7 @@ function loadMigrateState(stateFile) {
   };
 }
 function saveMigrateState(stateFile, state) {
-  mkdirSync2(dirname2(stateFile), { recursive: true });
+  mkdirSync2(dirname3(stateFile), { recursive: true });
   writeFileSync3(stateFile, JSON.stringify(state, null, 2) + "\n");
 }
 function guardReadOnly(api) {
@@ -7098,7 +7860,7 @@ function writeMigrateArtifact(path, content) {
 function ensureStateIgnored(cwd, log) {
   const entry = `${MIGRATE_DIR}/state.json`;
   const gi = resolve4(cwd, ".gitignore");
-  const existing = existsSync4(gi) ? readFileSync4(gi, "utf8") : "";
+  const existing = existsSync5(gi) ? readFileSync5(gi, "utf8") : "";
   if (gitignoreCovers(existing, entry)) return;
   const sep2 = existing === "" || existing.endsWith("\n") ? "" : "\n";
   appendFileSync(gi, `${sep2}
@@ -7126,7 +7888,7 @@ var STANDING_CAVEATS = [
   "Passwords: never imported (auth is scrypt-locked; the foreign-hash import is signal-gated, not built) \u2014 users re-auth via magic-link/OTP/social/reset on first sign-in.",
   "Push device tokens: no vxil landing (no push channel) \u2014 clients re-enroll post-cutover.",
   "Subscriptions / entitlements / tier: NEVER seeded (provider-derived truth) \u2014 rebuild from your live provider webhooks after cutover.",
-  "DB triggers / RPCs / pg_cron / RLS: not auto-migrated \u2014 hand-wire as vxil functions (cms-hook/cron/http triggers; cms-hooks are async post-commit, never in-transaction) + per-collection ownerField.",
+  "DB triggers / RPCs / pg_cron / row-level access rules: not auto-migrated \u2014 hand-wire as vxil functions (cms-hook/cron/http triggers; cms-hooks are async post-commit, never in-transaction) + per-collection ownerField.",
   "File objects: re-keyed (new object_id; source paths/URLs not preserved) \u2014 mint downloadUrl at read time, never persist it."
 ];
 function emitResidualsMd(plan, sourceLabel) {
@@ -7196,12 +7958,12 @@ async function runMigratePlan({ adapter, cwd, log, sourceLabel, infer }) {
 }
 function readPlanFile(cwd) {
   const p = migratePaths(cwd);
-  if (!existsSync4(p.planFile)) {
+  if (!existsSync5(p.planFile)) {
     throw new Error(`no ${MIGRATE_DIR}/plan.json \u2014 run \`vxil migrate plan --from <provider> \u2026\` first.`);
   }
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync4(p.planFile, "utf8"));
+    parsed = JSON.parse(readFileSync5(p.planFile, "utf8"));
   } catch (e) {
     throw new Error(`${MIGRATE_DIR}/plan.json is not parseable JSON (${e.message.split("\n")[0]}) \u2014 re-run \`vxil migrate plan\`.`);
   }
@@ -7219,10 +7981,10 @@ function readPlanFile(cwd) {
 }
 function readPaymentsSpecs(cwd) {
   const p = migratePaths(cwd);
-  if (!existsSync4(p.paymentsFile)) return void 0;
+  if (!existsSync5(p.paymentsFile)) return void 0;
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync4(p.paymentsFile, "utf8"));
+    parsed = JSON.parse(readFileSync5(p.paymentsFile, "utf8"));
   } catch (e) {
     throw new Error(`${MIGRATE_DIR}/payments.json is not parseable JSON (${e.message.split("\n")[0]})`);
   }
@@ -7304,10 +8066,10 @@ function paymentsSyncStatePath(cwd) {
   return resolve5(cwd, MIGRATE_DIR, "payments-sync.state.json");
 }
 function loadPaymentsSyncState(path, provider) {
-  if (!existsSync5(path)) return { version: 1, provider, done: {} };
+  if (!existsSync6(path)) return { version: 1, provider, done: {} };
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync5(path, "utf8"));
+    parsed = JSON.parse(readFileSync6(path, "utf8"));
   } catch (e) {
     throw new Error(`${path} is not parseable JSON (${e.message.split("\n")[0]}) \u2014 fix or delete it (deleting re-syncs every customer; the server fold is idempotent).`);
   }
@@ -7319,7 +8081,7 @@ function loadPaymentsSyncState(path, provider) {
   return { version: 1, provider, done: s.done ?? {}, ...s.usersCursor !== void 0 ? { usersCursor: s.usersCursor } : {} };
 }
 function savePaymentsSyncState(path, state) {
-  mkdirSync4(dirname3(path), { recursive: true });
+  mkdirSync4(dirname4(path), { recursive: true });
   writeFileSync5(path, JSON.stringify(state, null, 2) + "\n");
 }
 function parseCustomersCsv(text) {
@@ -8000,7 +8762,7 @@ export default defineConfig({
     "readme": '# AI Journal template\n\nAn AI-powered private journal \u2014 declared end-to-end in one typed `vxil.config.ts`. Every saved entry is\nenriched by a function (one-sentence summary + one-word mood via the `ai` feature) and indexed for retrieval,\nso you can literally *ask your journal* and get grounded, cited answers back.\n\n**What it provisions:**\n- `entries` \u2014 title, body, AI-derived `mood`/`summary`, `written_at`, tags, and `user_id` as the **owner field**\n  (a verified end-user only sees their own journal). Lane-A hooks require a title and stamp `written_at`.\n- Features: `cms` + `ai` + `rag` + `vector-search` (rag\'s retrieval leg) + `notifications` + `functions`.\n- Functions: `on-entry-written` (cmsHook: enrich + ingest), `ask-journal` (http: grounded Q&A),\n  `weekly-digest` (cron: Monday digest per writer).\n\n**Apply it:**\n\n```bash\nvxil init --template ai-journal\nvxil quickstart --invite <code>   # only when the email is new (or `vxil link` an existing tenant)\nvxil push\nvxil gen\n# one-time: create the retrieval index (dimensions/embedder come from config defaults)\ncurl -X POST https://api.vxil.com/v1/search/collections \\\n  -H "Authorization: Bearer $VXIL_KEY" -H "Content-Type: application/json" \\\n  -d \'{"collection":"journal"}\'\n```\n\n**What to learn from this:**\n1. **AI enrichment on write** \u2014 a `cmsHook` function re-fetches the entry by `item_id` (never trusts inline\n   fields), calls `POST /v1/ai/generate` (raw-prompt mode), PATCHes `summary`/`mood` back, and latches on\n   `summary` so its own write-back never re-enriches.\n2. **Retrieval-augmented "ask your journal"** \u2014 `POST /v1/rag/answer` retrieves top-k from the `journal`\n   index and returns the answer *with citations* (`doc_id` = the entry\'s `item_id`); the prompt stays yours.\n3. **BYO AI key via encrypted secrets** \u2014 config carries only the reference (`providers.openaiKeyRef`);\n   `vxil secrets set ai/openai_key` stores the value envelope-encrypted, then flip `defaultProvider`/`model`.\n   Until then the deterministic `mock` provider (and mock embedder) run the whole loop keyless.\n\n```bash\ncurl -X POST https://api.vxil.com/v1/fn/ask-journal \\\n  -H "Authorization: Bearer $VXIL_KEY" -H "Content-Type: application/json" \\\n  -d \'{"question":"what made me happy this month?"}\'\n```\n\n**Go deeper:** vxil.com/docs/guide/06-feature-catalog (ai, rag) \xB7 vxil.com/docs/guide/08-running-your-code-functions \xB7\nvxil.com/docs/guide/07-validation-and-hooks \xB7 vxil.com/docs/guide/04-data-with-cms (owner-scope) \xB7 `examples/ecommerce/` (a bigger functions saga).\n\n**Own the shape.** The config is yours after `init` \u2014 nothing is locked.\n',
     "functions": {
       "ask-journal.ts": "// ask-journal.ts \u2014 \"ASK YOUR JOURNAL\" (a vxil function, \xA77.3).\n//\n// Trigger: http \u2014 POST /v1/fn/ask-journal { question, user_id? }. Runs ONE\n// retrieval-augmented call: POST /v1/rag/answer over the `journal` index the\n// on-entry-written function keeps fed. rag retrieves top-k chunks from\n// vector-search, grounds the tenant-owned prompt, generates via the ai feature,\n// and returns the answer WITH citations pointing at the exact entries used \u2014\n// this function is a thin, scoped wrapper (rag:write only).\n//\n// In end-user mode the verified principal is propagated automatically into the\n// scoped token, so retrieval is owner-scoped; in server mode an optional\n// `user_id` rides along for per-user metering.\n\ninterface Env {\n  vxil_base?: string;\n  scoped_jwts?: Record<string, string>;\n  // http-trigger: the caller's JSON body lands under `payload`.\n  payload?: { question?: string; user_id?: string };\n}\ninterface Citation { chunk_id?: string; doc_id?: string; score?: number }\ninterface AnswerRes { data?: { answer?: string; citations?: Citation[]; usage?: Record<string, unknown> } }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const rag = env.scoped_jwts?.rag;\n    if (!rag) return json({ error: 'missing rag scope' }, 403);\n\n    const question = String(env.payload?.question ?? '').trim();\n    if (!question) return json({ error: 'question required', example: { question: 'what made me happy last month?' } }, 400);\n\n    const res = await fetch(`${base}/v1/rag/answer`, {\n      method: 'POST',\n      headers: { authorization: `Bearer ${rag}`, 'content-type': 'application/json' },\n      body: JSON.stringify({\n        query: question.slice(0, 2000),\n        collection: 'journal', // = rag config defaultCollection; explicit for clarity\n        ...(env.payload?.user_id ? { user_id: env.payload.user_id } : {}),\n      }),\n    });\n    if (!res.ok) {\n      // A missing index is NOT a 404 here: rag's retrieve leg wraps a\n      // vector-search failure as 502 retrieval_failed and attaches the\n      // downstream error under error.upstream (only a 501 passes through),\n      // so detect collection_not_found in the BODY, not the status. The\n      // index is a one-time setup (see the template README).\n      const errBody = (await res.json().catch(() => null)) as\n        { error?: { code?: string; upstream?: { code?: string } } } | null;\n      const code = errBody?.error?.upstream?.code ?? errBody?.error?.code;\n      if (res.status === 404 || code === 'collection_not_found') {\n        return json({ error: 'journal index not found', hint: 'POST /v1/search/collections {\"collection\":\"journal\"} once, then write an entry' }, 404);\n      }\n      return json({ error: 'answer_failed', status: res.status }, 502);\n    }\n\n    const body = (await res.json()) as AnswerRes;\n    return json({\n      answer: body.data?.answer ?? '',\n      // provenance: which entries grounded the answer (doc_id = the entry's item_id)\n      sources: (body.data?.citations ?? []).map((c) => ({ entry_id: c.doc_id, score: c.score })),\n    }, 200);\n  },\n};\n\n// \u2500\u2500 tiny helper \u2500\u2500\nconst json = (o: unknown, status: number) => Response.json(o, { status });\n",
-      "on-entry-written.ts": "// on-entry-written.ts \u2014 AI ENRICHMENT ON WRITE (a vxil function, \xA77.3).\n//\n// Trigger: cmsHook \u2014 fires on cms.item.* for `entries`. The hook payload is\n// { event, collection, item_id } \u2014 NOT the row \u2014 so the function RE-FETCHES the\n// entry by id (through the edge, tenant-scoped), then:\n//   1. asks the ai feature (POST /v1/ai/generate, raw-prompt mode) for a\n//      ONE-sentence summary and a ONE-word mood,\n//   2. PATCHes them back onto the entry (merge-patch; the summary-present LATCH\n//      keeps our own write-back from re-enriching \u2014 clear `summary` to redo),\n//   3. ingests title+body into the rag retrieval index (POST /v1/rag/ingest/\n//      journal \u2014 the vector-search passthrough) so ask-journal can ground on it.\n// At-least-once delivery is safe to redeliver: the summary latch skips a\n// re-enrich, the PATCH is idempotent by content, and the ingest converges \u2014\n// vector-search upserts by doc_id, so re-ingesting the same entry re-indexes\n// in place rather than duplicating.\n\ninterface Env {\n  vxil_base?: string;\n  scoped_jwts?: Record<string, string>;\n  payload?: { event?: string; collection?: string; item_id?: string };\n}\ninterface EntryData { title?: string; body?: string; summary?: string; mood?: string; written_at?: string; user_id?: string }\ninterface Item { data?: { data?: EntryData } }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const ai = env.scoped_jwts?.ai;\n    const rag = env.scoped_jwts?.rag;\n    const itemId = env.payload?.item_id;\n    if (env.payload?.collection !== 'entries' || !cms || !ai || !rag || !itemId) {\n      return Response.json({ skipped: true });\n    }\n\n    // Re-fetch the entry (the payload carries only the id \u2014 never trust inline fields).\n    const res = await fetch(`${base}/v1/cms/items/entries/${itemId}`, { headers: H(cms) });\n    if (!res.ok) return Response.json({ skipped: true, reason: `fetch ${res.status}` });\n    const entry = ((await res.json()) as Item).data?.data ?? {};\n    if (entry.summary) return Response.json({ skipped: true, reason: 'already enriched' });\n    if (!entry.body) return Response.json({ skipped: true, reason: 'no body yet' });\n\n    // 1. AI enrichment \u2014 two small raw-prompt generations ({ data: { text } }).\n    const text = entry.body.slice(0, 6000);\n    const summary = clip(await generate(base, ai,\n      `Summarize this journal entry in exactly one sentence, first person:\\n\\n${text}`, 80, entry.user_id), 400);\n    const moodRaw = await generate(base, ai,\n      `Answer with ONE lowercase word (e.g. joyful, anxious, calm, tired) naming the dominant mood of this journal entry:\\n\\n${text}`, 8, entry.user_id);\n    const mood = (moodRaw.trim().split(/\\s+/)[0] ?? '').toLowerCase().replace(/[^a-z-]/g, '').slice(0, 24);\n    if (!summary) return Response.json({ skipped: true, reason: 'ai unavailable' });\n\n    // 2. PATCH the derived fields back (merge-patch keys; bumps `version`).\n    const patch = await fetch(`${base}/v1/cms/items/entries/${itemId}`, {\n      method: 'PATCH',\n      headers: H(cms),\n      body: JSON.stringify({ data: { summary, ...(mood ? { mood } : {}) } }),\n    });\n\n    // 3. Ingest into the retrieval index (rag \u2192 vector-search passthrough, 202).\n    // Idempotent by doc_id: vector-search UPSERTs on (collection, doc_id), so a\n    // redelivered hook (or an edited entry) re-indexes in place.\n    const ing = await fetch(`${base}/v1/rag/ingest/journal`, {\n      method: 'POST',\n      headers: H(rag),\n      body: JSON.stringify({\n        doc_id: itemId,\n        ...(entry.user_id ? { user_id: entry.user_id } : {}),\n        text: `${entry.title ?? ''}\\n\\n${entry.body}`,\n        metadata: { ...(mood ? { mood } : {}), ...(entry.written_at ? { written_at: entry.written_at } : {}) },\n      }),\n    });\n    return Response.json({\n      enriched: patch.ok,\n      mood,\n      ingested: ing.ok,\n      // the index is a one-time setup: POST /v1/search/collections {\"collection\":\"journal\"}\n      ...(ing.status === 404 ? { hint: 'create the journal index first (see the template README)' } : {}),\n    });\n  },\n};\n\n// \u2500\u2500 tiny helpers \u2500\u2500\nconst H = (jwt: string) => ({ authorization: `Bearer ${jwt}`, 'content-type': 'application/json' });\n/** One raw-prompt sync generation; '' on any failure (enrichment is best-effort). */\nasync function generate(base: string, jwt: string, prompt: string, maxTokens: number, userId?: string): Promise<string> {\n  const r = await fetch(`${base}/v1/ai/generate`, {\n    method: 'POST',\n    headers: H(jwt),\n    body: JSON.stringify({ prompt, max_tokens: maxTokens, ...(userId ? { user_id: userId } : {}) }),\n  }).catch(() => null);\n  if (!r || !r.ok) return '';\n  return String(((await r.json()) as { data?: { text?: string } }).data?.text ?? '');\n}\nconst clip = (s: string, n: number) => (s.length > n ? s.slice(0, n - 1) + '\u2026' : s);\n",
+      "on-entry-written.ts": "// on-entry-written.ts \u2014 AI ENRICHMENT ON WRITE (a vxil function, \xA77.3).\n//\n// Trigger: cmsHook \u2014 fires on cms.item.* for `entries`. The hook payload is\n// { event, collection, item_id } \u2014 NOT the row \u2014 so the function RE-FETCHES the\n// entry by id (through the edge, tenant-scoped), then:\n//   1. asks the ai feature (POST /v1/ai/generate, raw-prompt mode) for a\n//      ONE-sentence summary and a ONE-word mood,\n//   2. PATCHes them back onto the entry (merge-patch; the summary-present LATCH\n//      keeps our own write-back from re-enriching \u2014 clear `summary` to redo),\n//   3. ingests title+body into the rag retrieval index (POST /v1/rag/ingest/\n//      journal \u2014 the vector-search passthrough) so ask-journal can ground on it.\n// At-least-once delivery is safe to redeliver: the summary latch skips a\n// re-enrich, the PATCH is idempotent by content, and the ingest converges \u2014\n// vector-search upserts by doc_id, so re-ingesting the same entry re-indexes\n// in place rather than duplicating.\n\ninterface Env {\n  vxil_base?: string;\n  scoped_jwts?: Record<string, string>;\n  payload?: { event?: string; collection?: string; item_id?: string };\n}\ninterface EntryData { title?: string; body?: string; summary?: string; mood?: string; written_at?: string; user_id?: string }\ninterface Item { data?: { data?: EntryData } }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const ai = env.scoped_jwts?.ai;\n    const rag = env.scoped_jwts?.rag;\n    const itemId = env.payload?.item_id;\n    // The platform now filters cms-hook deliveries on the binding's collection/event\n    // server-side (functions.md \xA73); this guard stays as belt-and-braces.\n    if (env.payload?.collection !== 'entries' || !cms || !ai || !rag || !itemId) {\n      return Response.json({ skipped: true });\n    }\n\n    // Re-fetch the entry (the payload carries only the id \u2014 never trust inline fields).\n    const res = await fetch(`${base}/v1/cms/items/entries/${itemId}`, { headers: H(cms) });\n    if (!res.ok) return Response.json({ skipped: true, reason: `fetch ${res.status}` });\n    const entry = ((await res.json()) as Item).data?.data ?? {};\n    if (entry.summary) return Response.json({ skipped: true, reason: 'already enriched' });\n    if (!entry.body) return Response.json({ skipped: true, reason: 'no body yet' });\n\n    // 1. AI enrichment \u2014 two small raw-prompt generations ({ data: { text } }).\n    const text = entry.body.slice(0, 6000);\n    const summary = clip(await generate(base, ai,\n      `Summarize this journal entry in exactly one sentence, first person:\\n\\n${text}`, 80, entry.user_id), 400);\n    const moodRaw = await generate(base, ai,\n      `Answer with ONE lowercase word (e.g. joyful, anxious, calm, tired) naming the dominant mood of this journal entry:\\n\\n${text}`, 8, entry.user_id);\n    const mood = (moodRaw.trim().split(/\\s+/)[0] ?? '').toLowerCase().replace(/[^a-z-]/g, '').slice(0, 24);\n    if (!summary) return Response.json({ skipped: true, reason: 'ai unavailable' });\n\n    // 2. PATCH the derived fields back (merge-patch keys; bumps `version`).\n    const patch = await fetch(`${base}/v1/cms/items/entries/${itemId}`, {\n      method: 'PATCH',\n      headers: H(cms),\n      body: JSON.stringify({ data: { summary, ...(mood ? { mood } : {}) } }),\n    });\n\n    // 3. Ingest into the retrieval index (rag \u2192 vector-search passthrough, 202).\n    // Idempotent by doc_id: vector-search UPSERTs on (collection, doc_id), so a\n    // redelivered hook (or an edited entry) re-indexes in place.\n    const ing = await fetch(`${base}/v1/rag/ingest/journal`, {\n      method: 'POST',\n      headers: H(rag),\n      body: JSON.stringify({\n        doc_id: itemId,\n        ...(entry.user_id ? { user_id: entry.user_id } : {}),\n        text: `${entry.title ?? ''}\\n\\n${entry.body}`,\n        metadata: { ...(mood ? { mood } : {}), ...(entry.written_at ? { written_at: entry.written_at } : {}) },\n      }),\n    });\n    return Response.json({\n      enriched: patch.ok,\n      mood,\n      ingested: ing.ok,\n      // the index is a one-time setup: POST /v1/search/collections {\"collection\":\"journal\"}\n      ...(ing.status === 404 ? { hint: 'create the journal index first (see the template README)' } : {}),\n    });\n  },\n};\n\n// \u2500\u2500 tiny helpers \u2500\u2500\nconst H = (jwt: string) => ({ authorization: `Bearer ${jwt}`, 'content-type': 'application/json' });\n/** One raw-prompt sync generation; '' on any failure (enrichment is best-effort). */\nasync function generate(base: string, jwt: string, prompt: string, maxTokens: number, userId?: string): Promise<string> {\n  const r = await fetch(`${base}/v1/ai/generate`, {\n    method: 'POST',\n    headers: H(jwt),\n    body: JSON.stringify({ prompt, max_tokens: maxTokens, ...(userId ? { user_id: userId } : {}) }),\n  }).catch(() => null);\n  if (!r || !r.ok) return '';\n  return String(((await r.json()) as { data?: { text?: string } }).data?.text ?? '');\n}\nconst clip = (s: string, n: number) => (s.length > n ? s.slice(0, n - 1) + '\u2026' : s);\n",
       "weekly-digest.ts": "// weekly-digest.ts \u2014 THE WEEKLY DIGEST (a vxil function, \xA77.3).\n//\n// Trigger: cron ('0 8 * * 1' \u2014 Mondays 08:00 UTC, delivered via the jobs\n// schedule the control-plane reconciles per cron binding). Lists the last 7\n// days of entries (written_at rides the t1 index slot, so the $gte range +\n// sort=-written_at are index-served), groups them per writer, and sends each\n// writer ONE notifications digest ({ subject, paragraph } on the built-in\n// 'transactional' template).\n//\n// Delivery notes: notifications resolves user_id against your end users \u2014 a\n// writer with no email fails that ONE send (user_email_missing) and the loop\n// continues. The per-user Idempotency-Key (envelope key + user id) makes the\n// at-least-once cron redelivery never double-send.\n\ninterface Env {\n  vxil_base?: string;\n  scoped_jwts?: Record<string, string>;\n  idempotency_key?: string;\n}\ninterface EntryData { title?: string; mood?: string; user_id?: string; written_at?: string }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const notif = env.scoped_jwts?.notifications;\n    if (!cms || !notif) return Response.json({ skipped: true, reason: 'missing cms/notifications scope' });\n\n    // 1. the week's entries, newest first (t1-slotted range + sort).\n    const since = new Date(Date.now() - 7 * 24 * 3600 * 1000).toISOString();\n    const filter = encodeURIComponent(JSON.stringify({ written_at: { $gte: since } }));\n    const res = await fetch(`${base}/v1/cms/items/entries?filter=${filter}&sort=-written_at&limit=100`, {\n      headers: { authorization: `Bearer ${cms}` },\n    });\n    if (!res.ok) return Response.json({ skipped: true, reason: `list ${res.status}` });\n    const body = (await res.json()) as { data?: { items?: { id: string; data: EntryData }[] } };\n    const items = body.data?.items ?? [];\n\n    // 2. group per writer.\n    const byUser = new Map<string, EntryData[]>();\n    for (const it of items) {\n      const uid = it.data.user_id;\n      if (!uid) continue;\n      const list = byUser.get(uid) ?? [];\n      list.push(it.data);\n      byUser.set(uid, list);\n    }\n\n    // 3. one digest send per writer (best-effort per user; the loop never aborts).\n    let sent = 0;\n    for (const [uid, entries] of byUser) {\n      const lines = entries\n        .slice(0, 10)\n        .map((e) => `\u2022 ${e.title ?? 'Untitled'}${e.mood ? ` (${e.mood})` : ''}`)\n        .join('\\n');\n      const ok = await fetch(`${base}/v1/notifications/send`, {\n        method: 'POST',\n        headers: {\n          authorization: `Bearer ${notif}`,\n          'content-type': 'application/json',\n          'idempotency-key': `${env.idempotency_key ?? 'weekly-digest'}:${uid}`,\n        },\n        body: JSON.stringify({\n          user_id: uid,\n          template: 'transactional',\n          data: {\n            subject: `Your journal week \u2014 ${entries.length} ${entries.length === 1 ? 'entry' : 'entries'}`,\n            paragraph: `You wrote ${entries.length} ${entries.length === 1 ? 'entry' : 'entries'} this week:\\n${lines}`,\n          },\n        }),\n      }).then((r) => r.ok).catch(() => false);\n      if (ok) sent += 1;\n    }\n\n    return Response.json({ entries: items.length, writers: byUser.size, sent });\n  },\n};\n"
     }
   },
@@ -8008,7 +8770,7 @@ export default defineConfig({
     "id": "agent-desk",
     "title": "Agent Desk (mcp \xB7 copilot \xB7 classify \xB7 judge \xB7 rag)",
     "vertical": "ai",
-    "summary": "The whole AI half on a deliberately small support desk \u2014 forced-label classification on every new ticket, a grounded and cited draft scored by a second judging pass, a knowledge index kept in step with a cms collection, an in-app assistant whose writes are proposed and human-confirmed, the same backend exposed as a narrowed MCP tool set for a least-privilege agent key, and a capability probe that reads the 170-event catalog so an agent can discover what it is able to react to.",
+    "summary": "The whole AI half on a deliberately small support desk \u2014 forced-label classification on every new ticket, a grounded and cited draft scored by a second judging pass, a knowledge index kept in step with a cms collection, an in-app assistant whose writes are proposed and human-confirmed, the same backend exposed as a narrowed MCP tool set for a least-privilege agent key, and a capability probe that reads the platform event catalog so an agent can discover what it is able to react to.",
     "collections": [
       "tickets",
       "kb"
@@ -8031,8 +8793,8 @@ export default defineConfig({
     "readme": '# Agent Desk (ai)\n\nThe whole AI half of vxil on a deliberately small support desk \u2014 two collections, three functions,\nand one idea per feature. If you have been trying to work out where `ai`, `rag`, `vector-search`,\n`copilot` and `mcp` differ, this is the blueprint that answers it by making each one do exactly its\nown job.\n\n```bash\nvxil init --template agent-desk\nvxil quickstart                                     # or `vxil link <slug>`\nprintf \'%s\' "$READ_KEY" | vxil secrets set functions/vxil_read_key\nvxil push                                           # collections + the three functions\n```\n\nEverything runs on the deterministic **`mock`** model provider, so the walkthrough below is\nreproducible with no provider account and no spend. Swapping in a real model is one config line and\none secret \u2014 nothing else in this blueprint changes.\n\n`vxil_read_key` is a key **of this same backend** carrying only `features:read` and `webhooks:read`;\nthe capability probe uses it (dashboard \u2192 API keys \u2192 create, tick those two and nothing else).\n\n## One idea per feature\n\n| Feature | The one thing it does here | Why it is not one of the others |\n|---|---|---|\n| `ai` classify | pick exactly one label from a fixed set | a chat prompt can return a paragraph; a classifier cannot |\n| `ai` judge | score a draft as an integer on a fixed scale | the model that writes is not the authority on whether the writing is good |\n| `vector-search` | hold the knowledge index, synced from `kb` | retrieval, not generation \u2014 no prompt lives here |\n| `rag` | answer **only** from what was retrieved, with citations | the pipeline; the *prompt* is a template you own |\n| `copilot` | the in-app assistant: propose a write, a human confirms | it is a composition over the four above, not a fifth model |\n| `mcp` | the same backend, as tools, narrowed per key | an agent\'s *interface*, not an agent |\n| `functions` | the deterministic steps around the model calls | the parts that must not be creative |\n\n## Prompts are yours, not config\n\n`rag.defaultTemplate: \'support-answer\'` names a **prompt template**, which is a versioned row you\ncreate over the API \u2014 deliberately not a config leaf, because a prompt is the part of the product\nyou iterate on hourly. Create it before the first answer:\n\n```bash\nvxil api POST /v1/ai/templates --data \'{\n  "template": "support-answer",\n  "system": "You are a support agent. Answer ONLY from the context. If the context does not contain the answer, say you do not know.",\n  "user": "Context:\\n{{context}}\\n\\nCustomer question:\\n{{query}}\\n\\nWrite a short, direct reply."\n}\'\n# 201 { "data": { "template": "support-answer", "version": 1 } }\n```\n\nRe-POST the same name and you get version 2 \u2014 old versions stay pinnable. `{{query}}` and\n`{{context}}` are what the retrieval step fills in. **A grounded answer with no template is a 404**,\nso this is step zero, not an optional flourish.\n\n## The 10-minute walkthrough\n\n`$KEY` is a server key with `ai:read ai:write rag:read rag:write vector-search:read\nvector-search:write cms:read cms:write copilot:read copilot:write webhooks:read functions:invoke\nfeatures:read`.\n\n**1. The index.** The `kb` cms collection is what you author in; the `kb` vector collection is what\nretrieval reads. Create the index, then push an article into it:\n\n```bash\nvxil api POST /v1/search/collections --data \'{"collection":"kb","dimensions":1536}\'\n# 201 { "data": { "collection": "kb", "dimensions": 1536, "backend": "\u2026" } }\n#     (`vector-search.sync` also reconciles one scheduled job per entry \u2014 you can see it in\n#      `GET /v1/jobs/schedules` as `vs-sync:cms~kb~kb`, on the cron you declared.)\n\nvxil api POST /v1/rag/ingest/kb --data \'{\n  "doc_id": "how-refunds-work",\n  "text": "A refund is issued to the original payment method within 14 days of purchase. Ask the customer for the order id, confirm the purchase date, then issue the refund from the billing screen. Refunds are not available after 14 days.",\n  "metadata": { "topic": "billing" }\n}\'\n# 202 { "data": { "doc_id": "how-refunds-work", "status": "indexed", "chunks": 1, "embedding_tokens": \u2026 } }\n```\n\n`POST /v1/rag/ingest/{collection}` is a convenience: a key holding only `rag:write` can fill the\nindex without also holding a vector-search scope.\n\nYou do not have to remember to do that twice, though \u2014 `vector-search.sync` in `vxil.config.ts`\ndeclares the `kb` cms collection as a source, so published articles are embedded on a schedule and\nthe index never silently drifts from the content. The direct ingest above just saves you the wait.\n\n**2. Classification, on every new ticket.** Create one and watch the hook:\n\n```bash\nvxil api POST /v1/cms/items/tickets --data \'{"data":{"subject":"Billing: charged twice this month","requester":"u_ana","state":"open","body":"My card was charged twice on the 3rd. Can I get one of them back?"}}\'\n# 201 { "data": { "item_id": "itm_\u2026", \u2026 } }\n\n# a moment later\nvxil api GET /v1/cms/items/tickets/itm_\u2026\n# 200 \u2026 "data": { "subject": "Billing: charged twice this month", "category": "billing", "state": "open", \u2026 }\n```\n\n`triage-ticket` fired on the write, re-fetched the row (a hook delivery carries ids, not the\ndocument), and asked for a **forced-label verdict**:\n\n```bash\nvxil api POST /v1/ai/classify --data \'{"input":"Billing: charged twice this month","labels":["billing","bug","how_to","other"]}\'\n# 200 { "data": { "generation_id": "gen_\u2026", "label": "billing", "confidence": 0.9,\n#                 "rationale": "\u2026", "usage": { \u2026 }, "cached": false } }\n```\n\nThe label set is part of the request, so the answer is constrained to it by the schema \u2014 the model\ncannot invent a fifth category or reply with a sentence. The function is also idempotent by\ninspection: a ticket that already has a `category` is skipped, because hook delivery is\nat-least-once and a redelivery should not cost another model call.\n\n**3. A grounded, cited draft \u2014 and a second opinion on it.** Press the record\'s button:\n\n```bash\nvxil api POST /v1/cms/items/tickets/itm_\u2026/actions/draft_reply\n# 200 { "data": { "collection": "tickets", "item_id": "itm_\u2026", "action": "draft_reply",\n#                 "fn": "draft-reply",\n#                 "result": { "draft": "\u2026", "score": 10, "verdict": "pass",\n#                             "citations": [ { "chunk_id": "how-refunds-work#0",\n#                                              "doc_id": "how-refunds-work", "score": 0.0164 } ],\n#                             "written": true } } }\n```\n\nTwo calls happened inside, and the split is the lesson:\n\n```bash\nvxil api POST /v1/rag/answer --data \'{"query":"My card was charged twice. Can I get one back?","collection":"kb","top_k":5,"stream":false}\'\n# 200 { "data": { "answer": "\u2026",\n#                 "citations": [ { "chunk_id": "how-refunds-work#0", "doc_id": "how-refunds-work", "score": 0.0164 } ],\n#                 "usage": { "retrieval_ms": 21, "retrieved": 1, "used": 1, \u2026 }, "finish": "stop" } }\n\nvxil api POST /v1/ai/judge --data \'{\n  "input": "My card was charged twice. Can I get one back?",\n  "candidate": "Refunds go back to the original payment method within 14 days of purchase.",\n  "criteria": [ { "name": "answers the question asked", "weight": 2 },\n                { "name": "is supported by the cited text", "weight": 2 } ],\n  "scale": { "min": 0, "max": 10 } }\'\n# 200 { "data": { "generation_id": "gen_\u2026", "score": 10, "verdict": "pass", "rationale": "\u2026", \u2026 } }\n```\n\n`stream: false` is load-bearing. With streaming on (the default), this route answers with a\n`generation_id`, a channel, a token and a `resume_path` for a browser to attach to \u2014 the citations\narrive immediately and the text streams. A server-side step wants the finished text, so it asks for\nit. Getting this wrong is a silent empty draft, not an error.\n\n`citations` are the chunks that actually **survived the context budget** \u2014 not everything retrieved.\nThat distinction is what makes them auditable: every sentence in the draft is traceable to text in\nthe list. And the score is a forced integer on a fixed scale, so drafts are comparable to each\nother rather than each getting its own adjective.\n\nNothing was sent to a customer. The action writes `draft` and `draft_score` onto the ticket and\nstops \u2014 the last step is a person.\n\n**4. The assistant: propose, then confirm.** The copilot answers from the same index and, when a\nturn would *write*, stops and asks:\n\n```bash\nvxil api POST /v1/copilot/desk/messages --data \'{"user_id":"u_agent","message":"What is our refund window?"}\'\n# 200 { "data": { "conversation_id": "cnv_\u2026", "message_id": "msg_\u2026",\n#                 "answer": "Refunds are available within 14 days of purchase\u2026",\n#                 "action_status": "none", "citations": [ \u2026 ], \u2026 } }\n\nvxil api POST /v1/copilot/desk/messages --data \'{"conversation_id":"cnv_\u2026","user_id":"u_agent","message":"Open a ticket for Ana about the double charge."}\'\n# 200 { "data": { "message_id": "msg_\u2026", "action_status": "proposed",\n#                 "proposal": { "message_id": "msg_\u2026", "tool": "cms_create_item",\n#                               "args": { "collection": "tickets", "data": { "subject": "\u2026", \u2026 } },\n#                               "feature": "cms", "proposed_at": "\u2026", "require_confirm": true,\n#                               "confirm_path": "/v1/copilot/conversations/cnv_\u2026/actions/msg_\u2026/confirm" },\n#                 \u2026 } }\n```\n\nOn the **mock** provider that second turn answers `action_status: "none"` \u2014 the mock does not decide\nto call a tool on its own. Steer it with the marker the platform\'s own end-to-end tests use, and the\nturn produces a real proposal you can confirm:\n\n```text\nOpen a ticket for Ana about the double charge.\n[[tool_call:cms_create_item {"collection":"tickets","data":{"subject":"Double charge for Ana","requester":"u_ana","state":"open"}}]]\n```\n\nNothing has been written yet. The proposal names the tool and the exact arguments, and hands you\nthe confirm path. Commit it:\n\n```bash\nvxil api POST /v1/copilot/conversations/cnv_\u2026/actions/msg_\u2026/confirm\n# 200 { "data": { "message_id": "msg_\u2026", "proposal_message_id": "msg_\u2026", "action_status": "confirmed",\n#                 "confirmed_at": "\u2026", "result": { "data": { "item_id": "itm_\u2026", \u2026 } } } }\n```\n\nConfirm takes **no body** \u2014 the ids in the path are the whole request, which is what makes the\nlatch tamper-proof: you cannot confirm a *different* write than the one you were shown. Call it\ntwice and the second answers `already: true`. Wait fifteen minutes and it is\n`410 proposal_expired`. And the permission check runs **again at confirm time**, so a scope revoked\nbetween proposal and confirm stops the write.\n\nThe keys under `copilot.agents.desk.actions.allow` are tool names from the catalog \u2014\n`cms_query_items` (a read, run inline) and `cms_create_item` / `cms_run_item_action` (writes,\nproposed). An unknown key there is inert, never invented.\n\n**5. The same backend, as tools.** Point an agent at it:\n\n```bash\nvxil mcp install --client claude --scopes features:read,cms:read,ai:write,rag:read,vector-search:read,webhooks:read\n```\n\nThat mints a dedicated, `agent`-tagged, revocable key and writes the MCP server entry for your\nclient. Three layers decide what the agent can do, and they compose:\n\n1. **`mcp.exposureLevel: \'custom\'` + `allowToolList`** in this config \u2014 the tenant-wide surface.\n2. **the key\'s scopes** \u2014 what the underlying REST route will accept.\n3. **the key\'s `allowed_tools` / `denied_tools`** \u2014 a per-key narrowing on top, editable after\n   minting without rotating the key.\n\n`features:read` is load-bearing: without it the policy probe (`GET /v1/config/mcp`) is refused and\nthe agent sees **zero** tools with no obvious error. Mint least privilege, but not less than that.\n\n**6. What can I react to here?** The last function answers the question an agent always has to ask\na human today:\n\n```bash\nvxil functions invoke agent-capabilities\n# { "catalog_events": 170,\n#   "enabled_features": [ "ai", "cms", "copilot", "functions", "mcp", "rag", "vector-search", "webhooks" ],\n#   "reactable_prefixes": [ { "prefix": "cms.item.", "count": \u2026 }, { "prefix": "ai.", "count": \u2026 }, \u2026 ],\n#   "failure_events": [ "job.dead_lettered", "jobs.schedule.missed",\n#                       "webhooks.delivery.dead_lettered", \u2026 ],\n#   "how_to_subscribe": "POST /v1/webhooks/subscriptions \u2026" }\n```\n\nIt reads `GET /v1/webhooks/events/catalog` \u2014 the machine-readable list of every lifecycle and\nfailure event the platform writes, with a prefix roll-up \u2014 and folds it against the features this\nbackend actually has on. The agent can call the catalog itself, too: `webhooks_event_catalog` is in\nthe tool list above, which is the difference between an agent that *has* tools and one that can\n**discover** what the system will tell it.\n\nActing on that discovery is one call with a key that carries `webhooks:write` \u2014 deliberately not\nthe read-only key this function holds:\n\n```bash\nvxil api POST /v1/webhooks/subscriptions --data \'{"target_url":"https://ops.example.com/vxil","event_prefixes":["cms.item.","ai."]}\'\n```\n\n## What to learn from this\n\n- **Forcing the shape is the feature.** Classify returns one of *your* labels; judge returns an\n  integer in *your* range. Most "the model went off the rails" problems are a missing schema, not a\n  missing instruction.\n- **Two passes beat one long prompt.** Writing and evaluating are different jobs, and separating\n  them gives you a number you can threshold, chart and regress against.\n- **Grounding is a pipeline, not a prompt trick.** Retrieval, a context budget, and citations of\n  the chunks that survived it \u2014 the answer is auditable because the pipeline kept the receipts.\n- **Propose \u2192 confirm is where agent safety actually lives.** Not in a system prompt asking the\n  model to be careful: in a latch that persists the exact arguments, re-checks permission at commit\n  time, expires, and executes at most once.\n- **Least privilege for an agent is three layers, not one.** The tenant\'s exposure list, the key\'s\n  scopes, and the key\'s per-tool narrowing \u2014 each can be tightened without touching the others.\n- **An agent should be able to ask the backend what it can do.** A tool catalog and an event\n  catalog are both machine-readable for the same reason: the alternative is a prompt that goes stale\n  the next time you ship.\n\n**Pairs with:** `templates/ai-journal/` (enrichment on write, and asking your own data questions)\nand `templates/helpdesk/` (the same desk without the AI half).\n',
     "functions": {
       "agent-capabilities.ts": "// agent-capabilities.ts \u2014 \"WHAT CAN I REACT TO HERE?\" (a vxil function).\n//\n// Trigger: http. An agent (or your own onboarding screen) calls this once and\n// learns, from the backend itself, what this workspace can emit \u2014 instead of a\n// human pasting a list into a prompt that goes stale the next release.\n//\n// Two reads, folded together:\n//   \u2022 `GET /v1/webhooks/events/catalog` \u2014 the machine-readable list of every\n//     lifecycle and failure event the platform writes, with a `prefixes` roll-up\n//     you can subscribe to directly.\n//   \u2022 `GET /v1/features` \u2014 which features THIS backend actually has on.\n// The answer is the intersection: the prefixes worth subscribing to here.\n//\n// WHY A KEY AND NOT THE FUNCTION'S OWN CALLBACK: a function's scoped callback\n// covers the feature APIs (cms, ai, rag, \u2026). The event catalog and the feature\n// list are platform reads, so this uses the narrowest key that can reach them \u2014\n// one holding only `features:read` and `webhooks:read`, stored as a secret,\n// resolved per invocation, revocable in one click without a redeploy.\n//\n// To actually SUBSCRIBE, POST to /v1/webhooks/subscriptions with\n// { target_url, event_prefixes } using a key that carries `webhooks:write` \u2014\n// deliberately NOT this one (see the README).\n\n/** prefix segment \u2192 the feature key it belongs to, where the names differ. */\nconst PREFIX_FEATURE: Record<string, string> = {\n  job: 'jobs', jobs: 'jobs', user: 'auth', auth: 'auth', session: 'auth',\n  org: 'orgs', orgs: 'orgs', rate_limits: 'rate-limits', feeds: 'activity-feed',\n  'vector-search': 'vector-search', functions: 'functions',\n};\n\ninterface Env {\n  vxil_base?: string;\n  secrets?: Record<string, string>;\n  payload?: { all?: boolean };\n}\ninterface CatalogEvent { name?: string; feature?: string; level?: string }\ninterface Prefix { prefix?: string; count?: number }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const key = env.secrets?.vxil_read_key;\n    if (!key) {\n      return Response.json(\n        { error: 'missing_secret', message: 'set the vxil_read_key secret first' },\n        { status: 503 },\n      );\n    }\n    const h = { authorization: `Bearer ${key}` };\n\n    const [catRes, featRes] = await Promise.all([\n      fetch(`${base}/v1/webhooks/events/catalog`, { headers: h }),\n      fetch(`${base}/v1/features`, { headers: h }),\n    ]);\n    if (!catRes.ok) {\n      return Response.json({ error: 'catalog_unavailable', status: catRes.status }, { status: 502 });\n    }\n    const cat = ((await catRes.json()) as {\n      data?: { count?: number; events?: CatalogEvent[]; prefixes?: Prefix[] };\n    }).data ?? {};\n    const enabled = new Set(\n      featRes.ok\n        ? ((await featRes.json()) as { data?: { features?: string[] } }).data?.features ?? []\n        : [],\n    );\n\n    const all = env.payload?.all === true;\n    const prefixes = (cat.prefixes ?? []).filter((p) => {\n      if (all || enabled.size === 0) return true;\n      const head = String(p.prefix ?? '').replace(/\\.$/, '');\n      return enabled.has(PREFIX_FEATURE[head] ?? head);\n    });\n\n    // The failure half is the half worth wiring first: it is what tells you the\n    // backend is unhappy before a customer does.\n    const failures = (cat.events ?? [])\n      .filter((e) => e.level === 'failure')\n      .map((e) => e.name)\n      .filter((n): n is string => typeof n === 'string')\n      .sort();\n\n    return Response.json({\n      catalog_events: cat.count ?? (cat.events ?? []).length,\n      enabled_features: [...enabled].sort(),\n      reactable_prefixes: prefixes,\n      failure_events: failures,\n      how_to_subscribe:\n        'POST /v1/webhooks/subscriptions { \"target_url\": \"https://\u2026\", \"event_prefixes\": [\"job.\", \"cms.item.\"] } '\n        + 'with a key carrying webhooks:write',\n    });\n  },\n};\n",
-      "draft-reply.ts": "// draft-reply.ts \u2014 RETRIEVE \u2192 GROUND \u2192 SCORE (a vxil function).\n//\n// Trigger: the per-record action `draft_reply` on `tickets`. The action envelope\n// carries the WHOLE row, so this step needs no re-fetch:\n//   { collection, item_id, action, actor, item: { item_id, status, version, data } }\n//\n// Three calls, three jobs, in order:\n//   1. `POST /v1/rag/answer` \u2014 retrieve from the `kb` index and answer ONLY from\n//      what came back, returning the chunks it used as citations. A grounded\n//      answer you can audit beats a confident one you cannot.\n//   2. `POST /v1/ai/judge` \u2014 score that draft against a rubric, as an integer on\n//      a fixed scale. The model that writes is not the authority on whether the\n//      writing is good; a second, schema-forced pass is.\n//   3. one PATCH \u2014 persist the draft + its score so a human decides what to send.\n//\n// Nothing here sends anything to a customer. The last step is always a person.\n\nconst CRITERIA = [\n  { name: 'answers the question asked', weight: 2 },\n  { name: 'is supported by the cited knowledge-base text', weight: 2 },\n  { name: 'is concise and free of speculation', weight: 1 },\n];\n\ninterface Env {\n  vxil_base?: string;\n  scoped_jwts?: Record<string, string>;\n  payload?: {\n    collection?: string;\n    item_id?: string;\n    item?: { data?: { subject?: string; body?: string; category?: string } };\n  };\n}\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const rag = env.scoped_jwts?.rag;\n    const ai = env.scoped_jwts?.ai;\n    const itemId = env.payload?.item_id;\n    if (!cms || !rag || !ai || !itemId || env.payload?.collection !== 'tickets') {\n      return Response.json({ error: 'bad_request', message: 'not a tickets action' }, { status: 400 });\n    }\n\n    const t = env.payload?.item?.data ?? {};\n    const question = `${t.subject ?? ''}\\n\\n${t.body ?? ''}`.trim();\n    if (!question) return Response.json({ error: 'empty_ticket' }, { status: 422 });\n\n    // 1. GROUNDED ANSWER. `template` falls back to the rag config's\n    //    `defaultTemplate`, so the call stays this short. `stream: false` is\n    //    load-bearing: with streaming enabled (the default) this route answers\n    //    with a channel + resume path for a browser to attach to, NOT the text.\n    //    A server-side step wants the text, so it says so.\n    const answered = await fetch(`${base}/v1/rag/answer`, {\n      method: 'POST',\n      headers: { authorization: `Bearer ${rag}`, 'content-type': 'application/json' },\n      body: JSON.stringify({ query: question, collection: 'kb', top_k: 5, stream: false }),\n    });\n    if (!answered.ok) {\n      const detail = await answered.text();\n      return Response.json(\n        { error: 'retrieval_failed', status: answered.status, detail: detail.slice(0, 300) },\n        { status: 502 },\n      );\n    }\n    const grounded = ((await answered.json()) as {\n      data?: { answer?: string; citations?: unknown[]; usage?: unknown };\n    }).data ?? {};\n    const draft = String(grounded.answer ?? '').trim();\n    const citations = Array.isArray(grounded.citations) ? grounded.citations : [];\n    if (!draft) return Response.json({ error: 'empty_draft' }, { status: 502 });\n\n    // 2. SCORE IT. A forced integer on a fixed scale \u2014 comparable across drafts,\n    //    unlike \"this looks good\".\n    const scored = await fetch(`${base}/v1/ai/judge`, {\n      method: 'POST',\n      headers: { authorization: `Bearer ${ai}`, 'content-type': 'application/json' },\n      body: JSON.stringify({\n        input: question,\n        candidate: draft,\n        criteria: CRITERIA,\n        scale: { min: 0, max: 10 },\n      }),\n    });\n    const verdict = scored.ok\n      ? ((await scored.json()) as { data?: { score?: number; verdict?: string; rationale?: string } }).data ?? {}\n      : {};\n    const score = typeof verdict.score === 'number' ? Math.round(verdict.score) : null;\n\n    // 3. PERSIST. A human reads it, edits it, and decides whether it is sent.\n    const patch = await fetch(`${base}/v1/cms/items/tickets/${itemId}`, {\n      method: 'PATCH',\n      headers: { authorization: `Bearer ${cms}`, 'content-type': 'application/json' },\n      body: JSON.stringify({\n        data: { draft, ...(score === null ? {} : { draft_score: score }), state: 'drafted' },\n      }),\n    });\n\n    return Response.json({\n      item_id: itemId,\n      draft,\n      score,\n      verdict: verdict.verdict ?? null,\n      rationale: verdict.rationale ?? null,\n      citations,\n      written: patch.ok,\n    });\n  },\n};\n",
-      "triage-ticket.ts": "// triage-ticket.ts \u2014 CLASSIFY EVERY NEW TICKET (a vxil function).\n//\n// Trigger: cmsHook on `tickets`. A hook delivery carries ids, not the row\n// ({ event, collection, item_id }), so the function RE-FETCHES the ticket\n// rather than trusting inline fields \u2014 and delivery is at-least-once, so it\n// skips a ticket that already carries a category instead of re-billing a model\n// call on a redelivery.\n//\n// The one model call is a FORCED-LABEL verdict: `POST /v1/ai/classify` takes the\n// label set and returns exactly one of them (plus a confidence and a one-line\n// rationale). That is the difference between a classifier and a chat prompt \u2014\n// the answer cannot be a paragraph, a new label, or an apology.\n\nconst LABELS = ['billing', 'bug', 'how_to', 'other'];\n\ninterface Env {\n  vxil_base?: string;\n  scoped_jwts?: Record<string, string>;\n  payload?: { event?: string; collection?: string; item_id?: string };\n}\ninterface TicketData { subject?: string; body?: string; category?: string }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const ai = env.scoped_jwts?.ai;\n    const itemId = env.payload?.item_id;\n    if (!cms || !ai || !itemId || env.payload?.collection !== 'tickets') {\n      return Response.json({ skipped: true, reason: 'not a tickets hook' });\n    }\n    // The cms.item.* subscription also delivers updates \u2014 only triage a create.\n    if (!String(env.payload?.event ?? '').endsWith('.created')) {\n      return Response.json({ skipped: true, event: env.payload?.event });\n    }\n\n    const read = await fetch(`${base}/v1/cms/items/tickets/${itemId}`, {\n      headers: { authorization: `Bearer ${cms}` },\n    });\n    if (!read.ok) return Response.json({ skipped: true, reason: `fetch ${read.status}` });\n    const ticket = ((await read.json()) as { data?: { data?: TicketData } }).data?.data ?? {};\n    // Already triaged \u21D2 this is a redelivery. Do nothing (and pay for nothing).\n    if (ticket.category) {\n      return Response.json({ skipped: true, reason: 'already triaged', category: ticket.category });\n    }\n\n    const input = `${ticket.subject ?? ''}\\n\\n${ticket.body ?? ''}`.trim();\n    if (!input) return Response.json({ skipped: true, reason: 'empty ticket' });\n\n    const verdict = await fetch(`${base}/v1/ai/classify`, {\n      method: 'POST',\n      headers: { authorization: `Bearer ${ai}`, 'content-type': 'application/json' },\n      body: JSON.stringify({\n        input,\n        labels: LABELS,\n        rubric:\n          'billing = money, invoices, refunds or subscriptions. '\n          + 'bug = something is broken or behaves incorrectly. '\n          + 'how_to = the customer is asking how to do something. '\n          + 'other = anything else.',\n      }),\n    });\n    if (!verdict.ok) {\n      const detail = await verdict.text();\n      return Response.json(\n        { error: 'classify_failed', status: verdict.status, detail: detail.slice(0, 300) },\n        { status: 502 },\n      );\n    }\n    const v = ((await verdict.json()) as {\n      data?: { label?: string; confidence?: number; rationale?: string };\n    }).data ?? {};\n    const label = LABELS.includes(String(v.label)) ? String(v.label) : 'other';\n\n    const patch = await fetch(`${base}/v1/cms/items/tickets/${itemId}`, {\n      method: 'PATCH',\n      headers: { authorization: `Bearer ${cms}`, 'content-type': 'application/json' },\n      body: JSON.stringify({ data: { category: label, state: 'open' } }),\n    });\n\n    return Response.json({\n      item_id: itemId,\n      category: label,\n      confidence: v.confidence ?? null,\n      rationale: v.rationale ?? null,\n      written: patch.ok,\n    });\n  },\n};\n"
+      "draft-reply.ts": "// draft-reply.ts \u2014 RETRIEVE \u2192 GROUND \u2192 SCORE (a vxil function).\n//\n// Trigger: the per-record action `draft_reply` on `tickets`. The action envelope\n// carries the WHOLE row, so this step needs no re-fetch:\n//   { collection, item_id, action, actor, item: { item_id, status, version, data } }\n//\n// Three calls, three jobs, in order:\n//   1. `POST /v1/rag/answer` \u2014 retrieve from the `kb` index and answer ONLY from\n//      what came back, returning the chunks it used as citations. A grounded\n//      answer you can audit beats a confident one you cannot.\n//   2. `POST /v1/ai/judge` \u2014 score that draft against a rubric, as an integer on\n//      a fixed scale. The model that writes is not the authority on whether the\n//      writing is good; a second, schema-forced pass is.\n//   3. one PATCH \u2014 persist the draft + its score so a human decides what to send.\n//\n// Nothing here sends anything to a customer. The last step is always a person.\n\nconst CRITERIA = [\n  { name: 'answers the question asked', weight: 2 },\n  { name: 'is supported by the cited knowledge-base text', weight: 2 },\n  { name: 'is concise and free of speculation', weight: 1 },\n];\n\ninterface Env {\n  vxil_base?: string;\n  scoped_jwts?: Record<string, string>;\n  payload?: {\n    collection?: string;\n    item_id?: string;\n    item?: { data?: { subject?: string; body?: string; category?: string } };\n  };\n}\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const rag = env.scoped_jwts?.rag;\n    const ai = env.scoped_jwts?.ai;\n    const itemId = env.payload?.item_id;\n    // The platform now filters cms-hook deliveries on the binding's collection/event\n    // server-side (functions.md \xA73); this guard stays as belt-and-braces.\n    if (!cms || !rag || !ai || !itemId || env.payload?.collection !== 'tickets') {\n      return Response.json({ error: 'bad_request', message: 'not a tickets action' }, { status: 400 });\n    }\n\n    const t = env.payload?.item?.data ?? {};\n    const question = `${t.subject ?? ''}\\n\\n${t.body ?? ''}`.trim();\n    if (!question) return Response.json({ error: 'empty_ticket' }, { status: 422 });\n\n    // 1. GROUNDED ANSWER. `template` falls back to the rag config's\n    //    `defaultTemplate`, so the call stays this short. `stream: false` is\n    //    load-bearing: with streaming enabled (the default) this route answers\n    //    with a channel + resume path for a browser to attach to, NOT the text.\n    //    A server-side step wants the text, so it says so.\n    const answered = await fetch(`${base}/v1/rag/answer`, {\n      method: 'POST',\n      headers: { authorization: `Bearer ${rag}`, 'content-type': 'application/json' },\n      body: JSON.stringify({ query: question, collection: 'kb', top_k: 5, stream: false }),\n    });\n    if (!answered.ok) {\n      const detail = await answered.text();\n      return Response.json(\n        { error: 'retrieval_failed', status: answered.status, detail: detail.slice(0, 300) },\n        { status: 502 },\n      );\n    }\n    const grounded = ((await answered.json()) as {\n      data?: { answer?: string; citations?: unknown[]; usage?: unknown };\n    }).data ?? {};\n    const draft = String(grounded.answer ?? '').trim();\n    const citations = Array.isArray(grounded.citations) ? grounded.citations : [];\n    if (!draft) return Response.json({ error: 'empty_draft' }, { status: 502 });\n\n    // 2. SCORE IT. A forced integer on a fixed scale \u2014 comparable across drafts,\n    //    unlike \"this looks good\".\n    const scored = await fetch(`${base}/v1/ai/judge`, {\n      method: 'POST',\n      headers: { authorization: `Bearer ${ai}`, 'content-type': 'application/json' },\n      body: JSON.stringify({\n        input: question,\n        candidate: draft,\n        criteria: CRITERIA,\n        scale: { min: 0, max: 10 },\n      }),\n    });\n    const verdict = scored.ok\n      ? ((await scored.json()) as { data?: { score?: number; verdict?: string; rationale?: string } }).data ?? {}\n      : {};\n    const score = typeof verdict.score === 'number' ? Math.round(verdict.score) : null;\n\n    // 3. PERSIST. A human reads it, edits it, and decides whether it is sent.\n    const patch = await fetch(`${base}/v1/cms/items/tickets/${itemId}`, {\n      method: 'PATCH',\n      headers: { authorization: `Bearer ${cms}`, 'content-type': 'application/json' },\n      body: JSON.stringify({\n        data: { draft, ...(score === null ? {} : { draft_score: score }), state: 'drafted' },\n      }),\n    });\n\n    return Response.json({\n      item_id: itemId,\n      draft,\n      score,\n      verdict: verdict.verdict ?? null,\n      rationale: verdict.rationale ?? null,\n      citations,\n      written: patch.ok,\n    });\n  },\n};\n",
+      "triage-ticket.ts": "// triage-ticket.ts \u2014 CLASSIFY EVERY NEW TICKET (a vxil function).\n//\n// Trigger: cmsHook on `tickets`. A hook delivery carries ids, not the row\n// ({ event, collection, item_id }), so the function RE-FETCHES the ticket\n// rather than trusting inline fields \u2014 and delivery is at-least-once, so it\n// skips a ticket that already carries a category instead of re-billing a model\n// call on a redelivery.\n//\n// The one model call is a FORCED-LABEL verdict: `POST /v1/ai/classify` takes the\n// label set and returns exactly one of them (plus a confidence and a one-line\n// rationale). That is the difference between a classifier and a chat prompt \u2014\n// the answer cannot be a paragraph, a new label, or an apology.\n\nconst LABELS = ['billing', 'bug', 'how_to', 'other'];\n\ninterface Env {\n  vxil_base?: string;\n  scoped_jwts?: Record<string, string>;\n  payload?: { event?: string; collection?: string; item_id?: string };\n}\ninterface TicketData { subject?: string; body?: string; category?: string }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const ai = env.scoped_jwts?.ai;\n    const itemId = env.payload?.item_id;\n    // The platform now filters cms-hook deliveries on the binding's collection/event\n    // server-side (functions.md \xA73); this guard stays as belt-and-braces.\n    if (!cms || !ai || !itemId || env.payload?.collection !== 'tickets') {\n      return Response.json({ skipped: true, reason: 'not a tickets hook' });\n    }\n    // The cms.item.* subscription also delivers updates \u2014 only triage a create.\n    if (!String(env.payload?.event ?? '').endsWith('.created')) {\n      return Response.json({ skipped: true, event: env.payload?.event });\n    }\n\n    const read = await fetch(`${base}/v1/cms/items/tickets/${itemId}`, {\n      headers: { authorization: `Bearer ${cms}` },\n    });\n    if (!read.ok) return Response.json({ skipped: true, reason: `fetch ${read.status}` });\n    const ticket = ((await read.json()) as { data?: { data?: TicketData } }).data?.data ?? {};\n    // Already triaged \u21D2 this is a redelivery. Do nothing (and pay for nothing).\n    if (ticket.category) {\n      return Response.json({ skipped: true, reason: 'already triaged', category: ticket.category });\n    }\n\n    const input = `${ticket.subject ?? ''}\\n\\n${ticket.body ?? ''}`.trim();\n    if (!input) return Response.json({ skipped: true, reason: 'empty ticket' });\n\n    const verdict = await fetch(`${base}/v1/ai/classify`, {\n      method: 'POST',\n      headers: { authorization: `Bearer ${ai}`, 'content-type': 'application/json' },\n      body: JSON.stringify({\n        input,\n        labels: LABELS,\n        rubric:\n          'billing = money, invoices, refunds or subscriptions. '\n          + 'bug = something is broken or behaves incorrectly. '\n          + 'how_to = the customer is asking how to do something. '\n          + 'other = anything else.',\n      }),\n    });\n    if (!verdict.ok) {\n      const detail = await verdict.text();\n      return Response.json(\n        { error: 'classify_failed', status: verdict.status, detail: detail.slice(0, 300) },\n        { status: 502 },\n      );\n    }\n    const v = ((await verdict.json()) as {\n      data?: { label?: string; confidence?: number; rationale?: string };\n    }).data ?? {};\n    const label = LABELS.includes(String(v.label)) ? String(v.label) : 'other';\n\n    const patch = await fetch(`${base}/v1/cms/items/tickets/${itemId}`, {\n      method: 'PATCH',\n      headers: { authorization: `Bearer ${cms}`, 'content-type': 'application/json' },\n      body: JSON.stringify({ data: { category: label, state: 'open' } }),\n    });\n\n    return Response.json({\n      item_id: itemId,\n      category: label,\n      confidence: v.confidence ?? null,\n      rationale: v.rationale ?? null,\n      written: patch.ok,\n    });\n  },\n};\n"
     }
   },
   {
@@ -8303,7 +9065,7 @@ export default defineConfig({
     "functions": {
       "abandoned-cart.ts": "// abandoned-cart.ts \u2014 RETENTION CRON (a vxil function, \xA77.3).\n//\n// Trigger: cron `0 * * * *` (hourly). Sweep open carts that went stale (last_activity\n// older than 1h) using the slot-indexed range filter, and nudge the shopper. This is the\n// jobs-cron pattern \u2014 no new primitive, just a scheduled function.\n\ninterface Env { vxil_base?: string; scoped_jwts?: Record<string, string> }\ninterface Cart { status: string; last_activity: string; end_user?: string }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const notif = env.scoped_jwts?.notifications;\n    if (!cms) return Response.json({ error: 'missing cms scope' }, { status: 403 });\n\n    // carts still `open` whose last_activity is > 1h ago (t1 range filter, index-served)\n    const cutoff = new Date(Date.now() - 60 * 60 * 1000).toISOString();\n    const filter = enc({ status: 'open', last_activity: { $lt: cutoff } });\n    const res = await fetch(`${base}/v1/cms/items/carts?filter=${filter}&limit=100`, {\n      headers: { authorization: `Bearer ${cms}` },\n    });\n    const body = (await res.json()) as { data?: { items?: { item_id: string; data: Cart }[] } };\n    const carts = body.data?.items ?? [];\n\n    // POST /v1/notifications/send is { user_id, template, data } \u2014 `transactional` is the\n    // shipped generic template (requires data.subject + data.paragraph, notifications.md \xA77).\n    let nudged = 0;\n    for (const c of carts) {\n      if (!notif || !c.data.end_user) continue;\n      await fetch(`${base}/v1/notifications/send`, {\n        method: 'POST',\n        headers: { authorization: `Bearer ${notif}`, 'content-type': 'application/json' },\n        body: JSON.stringify({\n          user_id: c.data.end_user,\n          template: 'transactional',\n          data: {\n            subject: 'You left items in your cart',\n            paragraph: `Your cart (${c.item_id}) is still waiting \u2014 come back and finish checkout any time.`,\n          },\n        }),\n      });\n      nudged++;\n    }\n    return Response.json({ scanned: carts.length, nudged });\n  },\n};\n\nconst enc = (o: unknown) => encodeURIComponent(JSON.stringify(o));\n",
       "checkout.ts": "// checkout.ts \u2014 THE CHECKOUT SAGA (a vxil function, \xA77.3).\n//\n// The hard part of e-commerce: \"reserve N SKUs + capture payment + create the order,\n// all-or-nothing\" \u2014 which is the deliberately-REJECTED cross-feature-ACID case. The\n// doctrinal (and incumbent-identical) answer is a reserve\u2192settle\u2192reverse SAGA, and it\n// is exactly-once under any concurrency. Shopify+Stripe do the same thing (Stripe is a\n// physically separate system reconciled by webhook); nothing here is a platform gap.\n//\n// Invoke it SERVER-SIDE (your backend POSTs /v1/fn/checkout with a server key):\n// under cms.strictEndUserScope an end-user-mode invocation is correctly denied on\n// the shared collections this saga touches (cart_items/variants) \u2014 inventory is a\n// tenant-wide surface, so the reserve step is server work by design.\n//\n// Steps:\n//   1. read the cart (owner + currency) + its lines (cms:read)\n//   2. RESERVE each line: PATCH variant {$inc:{stock:-qty}} \u2014 validation.min:0 makes it a\n//      single-statement oversell-safe decrement (409 inc_out_of_bounds if insufficient).\n//      On any failure \u2192 COMPENSATE (re-$inc the ones already reserved) \u2192 409 out_of_stock.\n//   3. create the ORDER with a unique cart_ref \u2192 EXACTLY-ONCE (409 on a racing duplicate).\n//   4. open a payments checkout-session (mode:payment, Idempotency-Key = order number).\n//   5. return { order_id, checkout_url }. Capture completes async \u2192 functions/on-order-paid.ts.\n//      (Not shipped here: if payment never completes, schedule a jobs `deliver_after`\n//      release that re-$inc's the reserve.)\n\ninterface Env {\n  vxil_base?: string;\n  scoped_jwts?: Record<string, string>;\n  end_user?: { id: string };\n  // the caller's HTTP body rides the invocation envelope under `payload` (functions.md \xA72)\n  payload?: { cart_id?: string; success_url?: string; cancel_url?: string };\n}\ninterface Line { variant: string; qty: number; unit_price_cents: number; price_ref: string }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const pay = env.scoped_jwts?.payments;\n    if (!cms || !pay) return json({ error: 'missing cms/payments scope' }, 403);\n    const { cart_id, success_url, cancel_url } = env.payload ?? {};\n    if (!cart_id) return json({ error: 'cart_id required' }, 400);\n\n    const H = (jwt: string) => ({ authorization: `Bearer ${jwt}`, 'content-type': 'application/json' });\n\n    // 1. read the cart (its end_user owner + currency), then its lines\n    const cartRes = await fetch(`${base}/v1/cms/items/carts/${cart_id}`, { headers: { authorization: `Bearer ${cms}` } });\n    if (!cartRes.ok) return json({ error: 'cart_not_found' }, 404);\n    const cart = ((await cartRes.json()) as { data?: { data?: { end_user?: string; currency?: string } } }).data?.data ?? {};\n    const shopper = env.end_user?.id ?? cart.end_user;\n    if (!shopper) return json({ error: 'cart has no owner (end_user)' }, 400);\n    const lines = await get<Line>(`${base}/v1/cms/items/cart_items?filter=${enc({ cart: cart_id })}&limit=100`, cms);\n    if (lines.length === 0) return json({ error: 'empty cart' }, 400);\n\n    // 2. RESERVE inventory line-by-line (oversell-safe $inc). Track for compensation.\n    const reserved: Line[] = [];\n    for (const ln of lines) {\n      const r = await fetch(`${base}/v1/cms/items/variants/${ln.variant}`, {\n        method: 'PATCH', headers: H(cms), body: JSON.stringify({ $inc: { stock: -ln.qty } }),\n      });\n      if (!r.ok) {\n        // compensate everything reserved so far, then fail cleanly\n        await Promise.all(reserved.map((p) =>\n          fetch(`${base}/v1/cms/items/variants/${p.variant}`, {\n            method: 'PATCH', headers: H(cms), body: JSON.stringify({ $inc: { stock: p.qty } }),\n          })));\n        return json({ error: 'out_of_stock', variant: ln.variant }, 409);\n      }\n      reserved.push(ln);\n    }\n\n    // 3. create the ORDER \u2014 unique cart_ref makes placement exactly-once under concurrency.\n    const total = lines.reduce((s, l) => s + l.unit_price_cents * l.qty, 0);\n    const number = `ORD-${cart_id.slice(0, 8)}`;\n    const orderRes = await fetch(`${base}/v1/cms/items/orders`, {\n      method: 'POST', headers: H(cms),\n      body: JSON.stringify({\n        data: {\n          number, cart_ref: cart_id, status: 'pending', end_user: shopper,\n          total_cents: total, placed_at: new Date().toISOString(), lines,\n        },\n      }),\n    });\n    if (orderRes.status === 409) {\n      // a concurrent checkout already placed this cart \u2192 idempotent: report it placed\n      return json({ status: 'already_placed', number }, 200);\n    }\n    if (!orderRes.ok) {\n      await Promise.all(reserved.map((p) =>\n        fetch(`${base}/v1/cms/items/variants/${p.variant}`, {\n          method: 'PATCH', headers: H(cms), body: JSON.stringify({ $inc: { stock: p.qty } }),\n        })));\n      return json({ error: 'order_create_failed' }, 502);\n    }\n    const order = (await orderRes.json()) as { data?: { item_id?: string } };\n\n    // 4. open the hosted payment (one-time). Idempotency-Key = order number \u21D2 safe to retry.\n    // The documented checkout-sessions contract (payments.md \xA73): user_id + line_items\n    // [{ price_ref, quantity, amount_cents?, currency? }] + mode + success/cancel URLs.\n    // price_ref is the PROVIDER's price id (a Stripe Price) snapshot on the cart line \u2014\n    // Stripe's adapter charges by price id; amount_cents/currency serve amount-based\n    // providers (PayPal payment mode). NOTE: the shipped Stripe adapter charges\n    // line_items[0] only \u2014 for multi-line carts on Stripe, collapse to one provider\n    // line (or one order-total price) before opening the session.\n    const currency = cart.currency ?? 'usd';\n    const sess = await fetch(`${base}/v1/payments/checkout-sessions`, {\n      method: 'POST',\n      headers: { ...H(pay), 'idempotency-key': number },\n      body: JSON.stringify({\n        user_id: shopper,\n        mode: 'payment',\n        line_items: lines.map((l) => ({ price_ref: l.price_ref, quantity: l.qty, amount_cents: l.unit_price_cents, currency })),\n        success_url: success_url ?? 'https://storefront.example/checkout/success',\n        cancel_url: cancel_url ?? 'https://storefront.example/checkout/cancel',\n      }),\n    });\n    if (!sess.ok) {\n      // the order stays placed (pending) \u2014 surface the payment error so the caller can\n      // retry the session (same Idempotency-Key) after fixing price_refs / provider keys.\n      return json({ order_id: order.data?.item_id, number, error: 'payment_session_failed' }, 502);\n    }\n    const s = (await sess.json()) as { data?: { url?: string } };\n\n    return json({ order_id: order.data?.item_id, number, checkout_url: s.data?.url }, 201);\n  },\n};\n\n// \u2500\u2500 tiny helpers (the vxil REST envelope is { data: { items }, meta }; items carry item_id) \u2500\u2500\nasync function get<T>(url: string, jwt: string): Promise<T[]> {\n  const res = await fetch(url, { headers: { authorization: `Bearer ${jwt}` } });\n  const body = (await res.json()) as { data?: { items?: { item_id: string; data: T }[] } };\n  return (body.data?.items ?? []).map((i) => ({ id: i.item_id, ...i.data } as T));\n}\nconst enc = (o: unknown) => encodeURIComponent(JSON.stringify(o));\nconst json = (o: unknown, status: number) => Response.json(o, { status });\n",
-      "on-order-paid.ts": "// on-order-paid.ts \u2014 SETTLEMENT SIDE-EFFECTS (a vxil function, \xA77.3).\n//\n// Trigger: cmsHook \u2014 fires on cms.item.updated for `orders`. When the order flips to\n// `paid` \u2014 YOUR payment-success handler PATCHes it (e.g. a function subscribed to the\n// payments `payments.charge.succeeded` event via a webhooks-out subscription on the\n// `payments.` prefix, or your backend after the hosted checkout returns); the\n// order_transition hook validates the flip \u2014 fan out the side-effects:\n// email the receipt (notifications) and POST the fulfillment webhook to the tenant's\n// 3PL/warehouse over the egress allowlist. Delivery is at-least-once with retry/DLQ \u2014\n// identical semantics to Shopify Flow / a Stripe webhook fan-out.\n//\n// The cms-hook payload is { event, collection, item_id } \u2014 NOT the row \u2014 so the\n// function RE-FETCHES the order by id (through the edge, tenant-scoped). notifications:send\n// is a legitimate function scope (allowed by the deploy; https://vxil.com/docs/guide/08-running-your-code-functions).\n//\n// (Inventory was already reserved atomically at checkout, so there is no decrement here \u2014\n// the reservation simply becomes permanent. A payment FAILURE path compensates instead.)\n\ninterface Env { vxil_base?: string; scoped_jwts?: Record<string, string>; payload?: { collection?: string; item_id?: string } }\ninterface OrderData { number?: string; status?: string; total_cents?: number; end_user?: string }\ninterface Item { data?: { data?: OrderData } }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const notif = env.scoped_jwts?.notifications;\n    const itemId = env.payload?.item_id;\n    if (env.payload?.collection !== 'orders' || !cms || !itemId) return Response.json({ skipped: true });\n\n    // Re-fetch the order (the payload carries only the id) and act only on pending\u2192paid.\n    const res = await fetch(`${base}/v1/cms/items/orders/${itemId}`, { headers: { authorization: `Bearer ${cms}` } });\n    if (!res.ok) return Response.json({ skipped: true, reason: `fetch ${res.status}` });\n    const order = ((await res.json()) as Item).data?.data ?? {};\n    if (order.status !== 'paid') return Response.json({ skipped: true, status: order.status });\n\n    // 1. receipt email (in-app inbox + email via the configured provider).\n    if (notif && order.end_user) {\n      await fetch(`${base}/v1/notifications/send`, {\n        method: 'POST',\n        headers: { authorization: `Bearer ${notif}`, 'content-type': 'application/json' },\n        body: JSON.stringify({\n          user_id: order.end_user,\n          template: 'transactional',\n          data: { subject: `Receipt for order ${order.number}`, paragraph: `Thanks! Your order ${order.number} totalling ${order.total_cents} cents is confirmed.` },\n        }),\n      }).catch(() => { /* the jobs/webhooks retry+DLQ engine owns durability */ });\n    }\n\n    // 2. fulfillment webhook to the tenant's warehouse (egress-guarded to fulfillment.example.com).\n    await fetch('https://fulfillment.example.com/orders', {\n      method: 'POST',\n      headers: { 'content-type': 'application/json' },\n      body: JSON.stringify({ number: order.number, total_cents: order.total_cents }),\n    }).catch(() => { /* best-effort here */ });\n\n    return Response.json({ settled: order.number });\n  },\n};\n",
+      "on-order-paid.ts": "// on-order-paid.ts \u2014 SETTLEMENT SIDE-EFFECTS (a vxil function, \xA77.3).\n//\n// Trigger: cmsHook \u2014 fires on cms.item.updated for `orders`. When the order flips to\n// `paid` \u2014 YOUR payment-success handler PATCHes it (e.g. a function subscribed to the\n// payments `payments.charge.succeeded` event via a webhooks-out subscription on the\n// `payments.` prefix, or your backend after the hosted checkout returns); the\n// order_transition hook validates the flip \u2014 fan out the side-effects:\n// email the receipt (notifications) and POST the fulfillment webhook to the tenant's\n// 3PL/warehouse over the egress allowlist. Delivery is at-least-once with retry/DLQ \u2014\n// identical semantics to Shopify Flow / a Stripe webhook fan-out.\n//\n// The cms-hook payload is { event, collection, item_id } \u2014 NOT the row \u2014 so the\n// function RE-FETCHES the order by id (through the edge, tenant-scoped). notifications:send\n// is a legitimate function scope (allowed by the deploy; https://vxil.com/docs/guide/08-running-your-code-functions).\n//\n// (Inventory was already reserved atomically at checkout, so there is no decrement here \u2014\n// the reservation simply becomes permanent. A payment FAILURE path compensates instead.)\n\ninterface Env { vxil_base?: string; scoped_jwts?: Record<string, string>; payload?: { collection?: string; item_id?: string } }\ninterface OrderData { number?: string; status?: string; total_cents?: number; end_user?: string }\ninterface Item { data?: { data?: OrderData } }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const notif = env.scoped_jwts?.notifications;\n    const itemId = env.payload?.item_id;\n    // The platform now filters cms-hook deliveries on the binding's collection/event\n    // server-side (functions.md \xA73); this guard stays as belt-and-braces.\n    if (env.payload?.collection !== 'orders' || !cms || !itemId) return Response.json({ skipped: true });\n\n    // Re-fetch the order (the payload carries only the id) and act only on pending\u2192paid.\n    const res = await fetch(`${base}/v1/cms/items/orders/${itemId}`, { headers: { authorization: `Bearer ${cms}` } });\n    if (!res.ok) return Response.json({ skipped: true, reason: `fetch ${res.status}` });\n    const order = ((await res.json()) as Item).data?.data ?? {};\n    if (order.status !== 'paid') return Response.json({ skipped: true, status: order.status });\n\n    // 1. receipt email (in-app inbox + email via the configured provider).\n    if (notif && order.end_user) {\n      await fetch(`${base}/v1/notifications/send`, {\n        method: 'POST',\n        headers: { authorization: `Bearer ${notif}`, 'content-type': 'application/json' },\n        body: JSON.stringify({\n          user_id: order.end_user,\n          template: 'transactional',\n          data: { subject: `Receipt for order ${order.number}`, paragraph: `Thanks! Your order ${order.number} totalling ${order.total_cents} cents is confirmed.` },\n        }),\n      }).catch(() => { /* the jobs/webhooks retry+DLQ engine owns durability */ });\n    }\n\n    // 2. fulfillment webhook to the tenant's warehouse (egress-guarded to fulfillment.example.com).\n    await fetch('https://fulfillment.example.com/orders', {\n      method: 'POST',\n      headers: { 'content-type': 'application/json' },\n      body: JSON.stringify({ number: order.number, total_cents: order.total_cents }),\n    }).catch(() => { /* best-effort here */ });\n\n    return Response.json({ settled: order.number });\n  },\n};\n",
       "price-cart.ts": "// price-cart.ts \u2014 THE PRICING ENGINE (a vxil function, \xA77.3).\n//\n// This is the module people assume needs a \"promotions feature\". It does NOT \u2014 and it\n// deliberately is NOT a cms lifecycle hook: hooks are single-row and cross-row aggregation\n// is forbidden by design (hooks.ts), so a hook can't sum a cart, apply BOGO across items,\n// or evaluate cart-level thresholds. That is arbitrary domain logic \u2192 a FUNCTION with full\n// JS expressiveness (exactly how Shopify Functions / Scripts run tenant discount code) \u2192 [B].\n//\n// It reads the cart lines + coupon (cms:read) and returns the priced cart. Like checkout,\n// invoke it SERVER-SIDE: under cms.strictEndUserScope the shared collections it reads\n// (cart_items/coupons) are correctly denied to an end-user-mode invocation. checkout.ts\n// recomputes its total from the same server-held snapshots \u2014 never trust a client total;\n// to honor promotions at capture time, apply this function's output there the same way.\n\ninterface Env {\n  vxil_base?: string;\n  scoped_jwts?: Record<string, string>;\n  // the caller's HTTP body rides the invocation envelope under `payload` (functions.md \xA72)\n  payload?: { cart_id?: string; coupon_code?: string };\n}\ninterface Line { variant: string; qty: number; unit_price_cents: number }\ninterface Coupon { code: string; kind: string; value: number; max_uses: number }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    if (!cms) return Response.json({ error: 'missing cms scope' }, { status: 403 });\n    const { cart_id, coupon_code } = env.payload ?? {};\n    if (!cart_id) return Response.json({ error: 'cart_id required' }, { status: 400 });\n\n    const lines = await get<Line>(`${base}/v1/cms/items/cart_items?filter=${enc({ cart: cart_id })}&limit=100`, cms);\n\n    // subtotal (cross-row sum \u2014 the thing a hook can't do)\n    const subtotal = lines.reduce((s, l) => s + l.unit_price_cents * l.qty, 0);\n\n    // \u2500\u2500 arbitrary promotion rules, plain JS \u2500\u2500\n    let discount = 0;\n    const applied: string[] = [];\n\n    // BOGO on any 2+ identical lines: cheapest unit free per pair\n    for (const l of lines) {\n      if (l.qty >= 2) { discount += Math.floor(l.qty / 2) * l.unit_price_cents; applied.push('bogo'); }\n    }\n\n    // tiered cart threshold: 5% over $100, 10% over $250\n    if (subtotal >= 25000) { discount += Math.round(subtotal * 0.10); applied.push('tier-10'); }\n    else if (subtotal >= 10000) { discount += Math.round(subtotal * 0.05); applied.push('tier-5'); }\n\n    // coupon (percent or fixed) \u2014 stacks on top, capped so total never goes below 0\n    if (coupon_code) {\n      const [c] = await get<Coupon>(`${base}/v1/cms/items/coupons?filter=${enc({ code: coupon_code })}&limit=1`, cms);\n      if (c) {\n        discount += c.kind === 'percent' ? Math.round(subtotal * (c.value / 100)) : c.value;\n        applied.push(`coupon:${c.code}`);\n      }\n    }\n\n    const total = Math.max(0, subtotal - discount);\n    return Response.json({ subtotal_cents: subtotal, discount_cents: subtotal - total, total_cents: total, applied });\n  },\n};\n\nasync function get<T>(url: string, jwt: string): Promise<T[]> {\n  const res = await fetch(url, { headers: { authorization: `Bearer ${jwt}` } });\n  const body = (await res.json()) as { data?: { items?: { item_id: string; data: T }[] } };\n  return (body.data?.items ?? []).map((i) => ({ id: i.item_id, ...i.data } as T));\n}\nconst enc = (o: unknown) => encodeURIComponent(JSON.stringify(o));\n"
     }
   },
@@ -8584,7 +9346,7 @@ export default defineConfig({
 `,
     "readme": "# Helpdesk / Support Ticketing template\n\nA support-ticketing backend \u2014 requester-owned tickets with a hook-enforced status state machine,\nthreaded conversation messages, an acknowledgement send on every new ticket, and an hourly\nSLA-escalation cron \u2014 declared end-to-end in one typed `vxil.config.ts`.\n\n**What it provisions:**\n- `tickets` \u2014 subject, `status` (state machine below), priority, `requester` (the **owner field**),\n  `opened_at`, `sla_due`, body. Every queue-driving field is slot-indexed for filter/sort.\n- `ticket_messages` \u2014 the conversation thread: `ticket` relation, author, body, `sent_at`.\n- Features: `cms` + `auth` (email/password end-users) + `notifications` (mock provider) + `functions`.\n- Functions: `on-ticket-created` (cmsHook \u2192 acknowledgement send) and `sla-sweep` (hourly cron).\n\n**Apply it:**\n\n```bash\nvxil init --template helpdesk\nvxil quickstart\nvxil push\nvxil gen\n```\n\n**What to learn from this:**\n- **A status state machine in a Lane-A hook** \u2014 the `beforeUpdate` validate allows only\n  `open\u2192pending|resolved`, `pending\u2192open|resolved`, `resolved\u2192closed`; any other transition is a\n  clean 422, atomically, in the write itself (vxil.com/docs/guide/07-validation-and-hooks).\n- **SLA automation as a cron function** \u2014 `sla-sweep` queries breached tickets with the \xA73 filter DSL\n  (`status $in` + `sla_due $lt`, slot-indexed) and PATCHes `priority: 'urgent'`; the `$ne: 'urgent'`\n  term makes re-runs idempotent.\n- **Requester-scoped end-user access** \u2014 `tickets.ownerField = 'requester'`: a signed-in requester\n  sees and edits only their **own** tickets (vxil.com/docs/guide/04-data-with-cms); server keys see the queue.\n\n```ts\nconst { item_id } = await vx.from('tickets').create({\n  subject: 'Cannot sign in on mobile', status: 'open', priority: 'normal',\n  requester: 'user_demo', opened_at: new Date().toISOString(),\n  sla_due: new Date(Date.now() + 8 * 3600e3).toISOString(), body: 'Steps to reproduce\u2026',\n});\n\n// the agent queue, most-overdue first (slot-indexed \u2192 typed filter/sort, index-served)\nconst { items } = await vx.from('tickets').query({\n  filter: { status: { $in: ['open', 'pending'] } }, sort: 'sla_due', limit: 25,\n});\n```\n\n**Go deeper:** vxil.com/docs/guide/04-data-with-cms (query DSL \xB7 owner-scoping) \xB7 vxil.com/docs/guide/07-validation-and-hooks \xB7\nvxil.com/docs/guide/08-running-your-code-functions \xB7 vxil.com/docs/guide/06-feature-catalog (notifications) \xB7 `examples/ecommerce/`.\n\n**Own the shape.** The config is yours after `init` \u2014 nothing is locked.\n",
     "functions": {
-      "on-ticket-created.ts": "// on-ticket-created.ts \u2014 the ACKNOWLEDGEMENT hook (a vxil function, \xA77.3).\n//\n// Trigger: cmsHook \u2014 fires on cms.item.* for `tickets`. On a CREATE, send the\n// requester an acknowledgement through notifications. The cms-hook payload is\n// { event, collection, item_id } \u2014 NOT the row \u2014 so the function RE-FETCHES the\n// ticket by id (through the edge, tenant-scoped) rather than trusting inline fields.\n// Delivery is at-least-once: the envelope idempotency_key rides the send as its\n// Idempotency-Key header, so a redelivered hook never double-sends.\n\ninterface Env {\n  vxil_base?: string;\n  scoped_jwts?: Record<string, string>;\n  idempotency_key?: string;\n  payload?: { event?: string; collection?: string; item_id?: string };\n}\ninterface TicketData { subject?: string; status?: string; requester?: string; sla_due?: string }\ninterface Item { data?: { data?: TicketData } }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const notif = env.scoped_jwts?.notifications;\n    const itemId = env.payload?.item_id;\n    if (env.payload?.collection !== 'tickets' || !cms || !notif || !itemId) {\n      return Response.json({ skipped: true });\n    }\n    // acknowledge only the CREATE (the cms.item.* subscription also delivers updates)\n    if (!String(env.payload?.event ?? '').endsWith('.created')) {\n      return Response.json({ skipped: true, event: env.payload?.event });\n    }\n\n    // Re-fetch the ticket (the payload carries only the id).\n    const res = await fetch(`${base}/v1/cms/items/tickets/${itemId}`, {\n      headers: { authorization: `Bearer ${cms}` },\n    });\n    if (!res.ok) return Response.json({ skipped: true, reason: `fetch ${res.status}` });\n    const ticket = ((await res.json()) as Item).data?.data ?? {};\n    if (!ticket.requester) return Response.json({ skipped: true, reason: 'no requester' });\n\n    // Acknowledge to the requester (email/inbox via the configured provider).\n    const send = await fetch(`${base}/v1/notifications/send`, {\n      method: 'POST',\n      headers: {\n        authorization: `Bearer ${notif}`,\n        'content-type': 'application/json',\n        ...(env.idempotency_key ? { 'idempotency-key': env.idempotency_key } : {}),\n      },\n      body: JSON.stringify({\n        user_id: ticket.requester,\n        template: 'transactional',\n        data: {\n          subject: `We got your ticket: ${ticket.subject ?? itemId}`,\n          paragraph:\n            `Your ticket is ${ticket.status ?? 'open'} and in our queue` +\n            `${ticket.sla_due ? ` (response due by ${ticket.sla_due})` : ''}. ` +\n            'Reply in the app to add details.',\n        },\n      }),\n    });\n    return Response.json({ acknowledged: itemId, delivery: send.status });\n  },\n};\n",
+      "on-ticket-created.ts": "// on-ticket-created.ts \u2014 the ACKNOWLEDGEMENT hook (a vxil function, \xA77.3).\n//\n// Trigger: cmsHook \u2014 fires on cms.item.* for `tickets`. On a CREATE, send the\n// requester an acknowledgement through notifications. The cms-hook payload is\n// { event, collection, item_id } \u2014 NOT the row \u2014 so the function RE-FETCHES the\n// ticket by id (through the edge, tenant-scoped) rather than trusting inline fields.\n// Delivery is at-least-once: the envelope idempotency_key rides the send as its\n// Idempotency-Key header, so a redelivered hook never double-sends.\n\ninterface Env {\n  vxil_base?: string;\n  scoped_jwts?: Record<string, string>;\n  idempotency_key?: string;\n  payload?: { event?: string; collection?: string; item_id?: string };\n}\ninterface TicketData { subject?: string; status?: string; requester?: string; sla_due?: string }\ninterface Item { data?: { data?: TicketData } }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const notif = env.scoped_jwts?.notifications;\n    const itemId = env.payload?.item_id;\n    // The platform now filters cms-hook deliveries on the binding's collection/event\n    // server-side (functions.md \xA73); this guard stays as belt-and-braces.\n    if (env.payload?.collection !== 'tickets' || !cms || !notif || !itemId) {\n      return Response.json({ skipped: true });\n    }\n    // acknowledge only the CREATE (the cms.item.* subscription also delivers updates)\n    if (!String(env.payload?.event ?? '').endsWith('.created')) {\n      return Response.json({ skipped: true, event: env.payload?.event });\n    }\n\n    // Re-fetch the ticket (the payload carries only the id).\n    const res = await fetch(`${base}/v1/cms/items/tickets/${itemId}`, {\n      headers: { authorization: `Bearer ${cms}` },\n    });\n    if (!res.ok) return Response.json({ skipped: true, reason: `fetch ${res.status}` });\n    const ticket = ((await res.json()) as Item).data?.data ?? {};\n    if (!ticket.requester) return Response.json({ skipped: true, reason: 'no requester' });\n\n    // Acknowledge to the requester (email/inbox via the configured provider).\n    const send = await fetch(`${base}/v1/notifications/send`, {\n      method: 'POST',\n      headers: {\n        authorization: `Bearer ${notif}`,\n        'content-type': 'application/json',\n        ...(env.idempotency_key ? { 'idempotency-key': env.idempotency_key } : {}),\n      },\n      body: JSON.stringify({\n        user_id: ticket.requester,\n        template: 'transactional',\n        data: {\n          subject: `We got your ticket: ${ticket.subject ?? itemId}`,\n          paragraph:\n            `Your ticket is ${ticket.status ?? 'open'} and in our queue` +\n            `${ticket.sla_due ? ` (response due by ${ticket.sla_due})` : ''}. ` +\n            'Reply in the app to add details.',\n        },\n      }),\n    });\n    return Response.json({ acknowledged: itemId, delivery: send.status });\n  },\n};\n",
       "sla-sweep.ts": "// sla-sweep.ts \u2014 SLA ESCALATION CRON (a vxil function, \xA77.3).\n//\n// Trigger: cron `0 * * * *` (hourly). Sweep tickets whose sla_due has passed and\n// that are still open/pending \u2014 the cms filter DSL (vxil.com/docs/guide/04-data-with-cms):\n// `status $in` on the s2 slot, `sla_due $lt` on the t2 slot, `priority $ne` on\n// s3 \u2014 all index-served. Each breach is escalated with a PATCH to priority\n// 'urgent'; the $ne term makes re-runs idempotent (an escalated ticket falls out\n// of the filter). The Lane-A state-machine hook still runs on every PATCH; a\n// priority-only write keeps item.status == before.status, so it always passes.\n\ninterface Env { vxil_base?: string; scoped_jwts?: Record<string, string> }\ninterface Ticket { id: string; data: { subject?: string; priority?: string } }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    if (!cms) return Response.json({ error: 'missing cms scope' }, { status: 403 });\n\n    // breached = still open/pending, past its sla_due, not yet urgent\n    const filter = enc({\n      status: { $in: ['open', 'pending'] },\n      sla_due: { $lt: new Date().toISOString() },\n      priority: { $ne: 'urgent' },\n    });\n    const res = await fetch(`${base}/v1/cms/items/tickets?filter=${filter}&limit=100`, {\n      headers: { authorization: `Bearer ${cms}` },\n    });\n    if (!res.ok) return Response.json({ error: `query ${res.status}` }, { status: 502 });\n    const body = (await res.json()) as { data?: { items?: Ticket[] } };\n    const breached = body.data?.items ?? [];\n\n    let escalated = 0;\n    for (const t of breached) {\n      const r = await fetch(`${base}/v1/cms/items/tickets/${t.id}`, {\n        method: 'PATCH',\n        headers: { authorization: `Bearer ${cms}`, 'content-type': 'application/json' },\n        body: JSON.stringify({ data: { priority: 'urgent' } }),\n      });\n      if (r.ok) escalated++;\n    }\n    return Response.json({ scanned: breached.length, escalated });\n  },\n};\n\n// \u2500\u2500 tiny helper (the vxil REST list envelope is { data: { items } }) \u2500\u2500\nconst enc = (o: unknown) => encodeURIComponent(JSON.stringify(o));\n"
     }
   },
@@ -8631,7 +9393,7 @@ export default defineConfig({
     "configSrc": "import { defineConfig } from '@vxil/config';\n\n// \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n// \"Team Workspace\" \u2014 the ENTERPRISE blueprint: many companies inside one\n// backend, each with its own members and roles, signing in through the\n// company's own identity provider, reading a document set where ONE field is\n// visible only to finance. Declared end-to-end in ONE typed file.\n//\n//   \u2022 orgs   \u2192 organizations + memberships + a tenant-defined `finance` role\n//   \u2022 auth   \u2192 email/password or magic link today, a generic OIDC issuer as a\n//              config swap; account-security controls; a 3-device session cap\n//   \u2022 cms    \u2192 projects \u2192 documents, owner-scoped, `restrict`-protected, with\n//              ONE per-record action button and ONE role-gated field\n//   \u2022 functions \u2192 the single step the Archive button runs\n//\n// The one thing that is NOT in this file: inviting a teammate to the vxil\n// PROJECT itself (the dashboard's pending-email invite). That is an operator\n// flow, not app config \u2014 see the README.\n// \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nexport default defineConfig({\n  env: 'staging',\n\n  features: {\n    // \u2500\u2500 Workspaces for YOUR customers' teams \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n    // An organization is a customer company; a membership carries a role. The\n    // built-in lattice is owner > admin > member > viewer; `finance` below is a\n    // CUSTOM role you define once over the API (see the README) and then assign\n    // like any built-in one.\n    orgs: {\n      enabled: true,\n      maxMembersPerOrg: 200,\n      invitationTtlHours: 72, // an org invitation token is single-use + TTL-bound\n    },\n\n    auth: {\n      // The demo path: email+password (and magic link) so the walkthrough runs\n      // with no identity provider at all.\n      methods: { emailPassword: true, magicLink: true },\n\n      // \u2500\u2500 SSO: the generic OIDC issuer, as a CONFIG SWAP \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n      // Uncomment this block, store the client secret once, and every member of\n      // the workspace signs in through the company's IdP instead. The endpoints\n      // and signing keys are discovered from the issuer \u2014 nothing else changes\n      // in this file, and no code changes at all. `clientId` is not a secret\n      // (it rides every authorize URL); the secret stays a REFERENCE.\n      //\n      // providers: {\n      //   oidc: {\n      //     issuer: 'https://login.example-idp.com',       // https, no query/fragment\n      //     clientId: 'vxil-team-workspace',\n      //     clientSecretRef: 'secret:oidc_client_secret',  // the `secrets` block below\n      //     scopes: ['email', 'profile'],                  // `openid` is always added\n      //     claims: { email: 'email', name: 'name', roles: 'groups' },\n      //     allowedDomains: ['example.com'],               // fail-closed domain fence\n      //     autoLink: true,                                // link to a matching verified email\n      //   },\n      // },\n\n      // Roles ride the SESSION. With this on, the member's active-org role is\n      // embedded in the session at sign-in and refresh, so a read can be gated\n      // on it without a round-trip. It is a SNAPSHOT (refreshed with the\n      // session) \u2014 use the orgs permission check for revocation-grade calls.\n      orgClaims: { enabled: true },\n\n      // A member may hold at most three live sessions; a fourth sign-in takes\n      // over the oldest (it is revoked, and the sign-in reports which).\n      session: { ttlMinutes: 60, refreshTtlDays: 30, maxConcurrent: 3 },\n\n      // \u2500\u2500 Account-security controls (all opt-in, all off by default) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n      security: {\n        // repeated bad passwords on one identifier \u2192 locked, with a retry hint\n        lockout: { maxFailures: 5, windowMinutes: 15, lockMinutes: 15 },\n        // refuse a sign-up / reset whose password appears in a breach corpus\n        breachedPasswords: true,\n        // EVERY caller-supplied return URL must match one of these exactly \u2014\n        // the anti-open-redirect fence for magic links, resets and SSO returns.\n        allowedRedirectOrigins: ['https://app.example.com'],\n        // captchaSecretRef: 'turnstile_secret', // add to require a captcha token\n      },\n    },\n\n    cms: {\n      hooks: {\n        // The DOCUMENT lifecycle, enforced atomically inside the same write.\n        // `archived` is terminal; the Archive button below is just the last\n        // legal transition, so the button and the API agree by construction.\n        document_stage: {\n          collection: 'documents',\n          event: 'beforeUpdate',\n          kind: 'validate',\n          expr:\n            'item.state == before.state'\n            + \" || (before.state == 'draft' && (item.state == 'in_review' || item.state == 'archived'))\"\n            + \" || (before.state == 'in_review' && (item.state == 'draft' || item.state == 'approved'))\"\n            + \" || (before.state == 'approved' && item.state == 'archived')\",\n          message: 'illegal document state transition',\n        },\n      },\n    },\n\n    functions: { enabled: true },\n  },\n\n  // \u2500\u2500 Schema-as-code (\u22648 index slots per collection: s1\u2013s4/n1\u2013n2/t1\u2013t2) \u2500\u2500\u2500\u2500\u2500\u2500\n  cms: {\n    collections: {\n      projects: {\n        singular: 'project',\n        fields: {\n          name: { type: 'string', required: true, indexSlot: 's1' },\n          // one project code per workspace \u2014 a duplicate is a clean 409\n          code: { type: 'string', unique: true, indexSlot: 's2' },\n          stage: { type: 'string', indexSlot: 's3' }, // discovery | active | closed\n          created_at: { type: 'datetime', indexSlot: 't1' },\n          summary: { type: 'text' },\n        },\n      },\n\n      documents: {\n        singular: 'document',\n        // Owner-scoping: a signed-in member reads/edits only their OWN\n        // documents. A no-op for server callers \u2014 your own backend still sees\n        // the whole set.\n        ownerField: 'author',\n\n        // ONE human-initiated step per record. The dashboard renders a button\n        // on every row; pressing it invokes the named function ONCE with\n        // { collection, item_id, action, actor, item }. No conditions, no\n        // chaining, no scheduling \u2014 the moment it needs branches it is a\n        // function of your own, not a button.\n        actions: [{ key: 'archive', label: 'Archive', fn: 'archive-document' }],\n\n        fields: {\n          title: { type: 'string', required: true, indexSlot: 's1' },\n          author: { type: 'string', indexSlot: 's2' }, // the owner (end-user id)\n          // `restrict`: while a live document points at a project, deleting\n          // that project is REFUSED (409) instead of silently orphaning or\n          // cascading. The reverse read (`\u2026/backlinks`) tells you who holds it.\n          project: { type: 'relation', relationTo: 'projects', onDelete: 'restrict', indexSlot: 's3' },\n          state: { type: 'string', indexSlot: 's4' }, // draft | in_review | approved | archived\n          // \u2500\u2500 FIELD-LEVEL READ SECURITY \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n          // Only a signed-in member whose session carries the `finance` role\n          // ever receives this field. Everyone else gets the document WITHOUT\n          // it \u2014 absent, not null \u2014 and cannot filter or sort on it either, so\n          // it can never be read one bit at a time. Your own server key still\n          // sees it: this gates END USERS, not you.\n          budget_usd: { type: 'int', indexSlot: 'n1', readRoles: ['finance'] },\n          updated_at: { type: 'datetime', indexSlot: 't1' },\n          body: { type: 'text' },\n        },\n      },\n    },\n  },\n\n  // \u2500\u2500 The one step that isn't config \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n  functions: {\n    // The Archive button. Invoked through the per-record action route with the\n    // pressing member's verified principal carried whole, so the write it makes\n    // is owner-scoped exactly as if the member had made it themselves.\n    'archive-document': {\n      entry: './functions/archive-document.ts',\n      trigger: { kind: 'http' },\n      scopes: ['cms:read', 'cms:write'],\n      egressAllow: [], // nothing external; it only talks back to your own backend\n    },\n  },\n\n  // References only \u2014 values are stored once and never appear in this file.\n  secrets: {\n    oidc_client_secret: { feature: 'auth', description: 'OIDC client secret for the workspace identity provider' },\n  },\n\n  seed: {\n    cms: [\n      {\n        collection: 'projects',\n        items: [\n          {\n            name: 'Northwind Rollout',\n            code: 'NW-2026',\n            stage: 'active',\n            created_at: '2026-01-06T09:00:00Z',\n            summary: 'Migration of the Northwind account onto the new platform.',\n          },\n        ],\n      },\n    ],\n  },\n});\n",
     "readme": '# Team Workspace (saas)\n\nThe **B2B** blueprint: many customer companies inside one backend, each with its own members\nand roles, signing in through the company\'s own identity provider \u2014 and a document set where\none field is visible only to finance.\n\nFive things most "add multi-tenancy to my SaaS" projects end up building by hand, declared here\ninstead: **organizations**, **roles that ride the session**, **SSO as a config swap**,\n**field-level read security**, and **one button per record**.\n\n```bash\nvxil init --template team-workspace\nvxil quickstart                       # or `vxil link <slug>` for an existing backend\nvxil push                             # collections + hooks + the archive function\n```\n\n## The five things, and where each one lives\n\n| What | Where it is declared | What it buys you |\n|---|---|---|\n| Customer companies + memberships | `features.orgs` | `POST /v1/orgs`, members, invitations, a permission check \u2014 no membership table of your own |\n| A `finance` role | **not config** \u2014 `POST /v1/orgs/roles` | roles are rows, so you add one without a deploy |\n| Roles on the session | `features.auth.orgClaims.enabled` | the member\'s active-org role rides the session token; a read can be gated on it with no round-trip |\n| SSO | `features.auth.providers.oidc` (commented) | one block swaps email+password for the customer\'s identity provider |\n| Lockout / breach / redirect fence | `features.auth.security` | the account-security controls, all opt-in, all off until you ask |\n| A 3-device cap | `features.auth.session.maxConcurrent` | a fourth sign-in takes over the oldest session and tells you which |\n| Hiding `budget_usd` | `readRoles: [\'finance\']` on the field | the field is **absent** for everyone else \u2014 and unfilterable, so it cannot be read one bit at a time |\n| Refusing an orphaning delete | `onDelete: \'restrict\'` on the relation | deleting a project that still holds documents is a clean 409, not a cascade you did not ask for |\n| The Archive button | `actions: [{ key, label, fn }]` | one human-initiated step, one function, no workflow engine |\n\n## SSO \u2014 the config swap\n\nThe blueprint ships with email + password so the walkthrough runs with no identity provider.\nTo move a workspace onto its company\'s IdP, uncomment the `providers.oidc` block in\n`vxil.config.ts`, fill in three values, store one secret, and push:\n\n```ts\nproviders: {\n  oidc: {\n    issuer: \'https://login.example-idp.com\',      // https, no query or fragment\n    clientId: \'vxil-team-workspace\',              // not a secret \u2014 it rides every authorize URL\n    clientSecretRef: \'secret:oidc_client_secret\', // a REFERENCE; the value never enters this file\n    scopes: [\'email\', \'profile\'],                 // `openid` is always added\n    claims: { email: \'email\', name: \'name\', roles: \'groups\' },\n    allowedDomains: [\'example.com\'],              // fail-closed: an unlisted domain is refused\n    autoLink: true,                               // link to an existing verified email\n  },\n},\n```\n\n```bash\nprintf \'%s\' "$OIDC_SECRET" | vxil secrets set auth/oidc_client_secret\nvxil push\n```\n\nThen send people to `GET /v1/auth/oauth/oidc/start?redirect_uri=https://app.example.com/callback`.\nThe authorize endpoint, token endpoint and signing keys are **discovered from the issuer** \u2014 there\nis nothing else to configure and no code change at all. The presence of the block is the opt-in;\nthere is no separate toggle.\n\nTwo claims feed the session\'s role list: the member\'s **active-org role** (from `orgClaims`) and\nwhatever claim you name in `claims.roles` (from the IdP). Either one alone is enough to satisfy\n`readRoles: [\'finance\']`, which is why the same config works before and after SSO.\n\nAny broker that speaks OIDC \u2014 Okta, Entra, Auth0, WorkOS \u2014 puts a SAML customer behind this same\nblock. There is deliberately no separate SAML surface to learn.\n\n## Inviting people: two different invitations\n\nThey are easy to confuse, so name them apart:\n\n- **Your customers\' teammates** \u2192 `POST /v1/orgs/{org_id}/invitations` with `{ email, role }`,\n  where `role` is `admin`, `member` or `viewer`. The single-use token comes back **once**, in that\n  response \u2014 it is deliberately never emailed, so your app builds its own accept link and controls\n  the wording. Accept with `POST /v1/orgs/invitations/accept`; list pending ones with\n  `GET /v1/orgs/{org_id}/invitations`; revoke with `DELETE /v1/orgs/invitations/{invite_id}`.\n  To land someone on a custom role such as `finance`, invite them as `member` and then\n  `POST /v1/orgs/{org_id}/members` with the role. There is no resend \u2014 issue a new invitation and\n  revoke the old one.\n- **Your own colleagues, on the vxil project itself** \u2192 the dashboard\'s **Members \u2192 Invite by\n  email**. Type an address and it becomes a *pending* row with Resend and Revoke beside it; when\n  they accept, they get a dashboard seat on this backend. That one is pure operator flow \u2014 no code,\n  nothing in this config.\n\n## The 10-minute walkthrough\n\nEvery response below is the real shape. `$KEY` is a server key with `cms:read cms:write orgs:read\norgs:write auth:signin auth:write features:read`; `$API` is `https://api.vxil.com`.\n\n**1. Define the `finance` role.** Roles are rows, so this needs no deploy.\n\n```bash\nvxil api POST /v1/orgs/roles --data \'{"role_key":"finance","name":"Finance","permissions":["budgets.approve","reports.export"],"rank":2}\'\n# 201 { "data": { "role_key": "finance", "name": "Finance", "permissions": [...], "rank": 2, ... } }\n```\n\nA custom role is a named **permission set**, and the permission strings are yours \u2014 vxil never\ninterprets them, it only answers whether this member holds one. The four built-in roles\n(`owner > admin > member > viewer`) keep working alongside it.\n\n**2. Create a workspace and two members.**\n\n```bash\nvxil api POST /v1/orgs --data \'{"slug":"northwind","name":"Northwind","owner_user_id":"u_owner"}\'\n# 201 { "data": { "org_id": "org_\u2026", "slug": "northwind", "name": "Northwind", "created_at": "\u2026" } }\n```\n\nSign two people up, then seat them \u2014 one plain `member`, one on `finance`:\n\n```bash\nvxil api POST /v1/auth/sign-up --data \'{"email":"alice@example.com","password":"<a strong one>"}\'\nvxil api POST /v1/auth/sign-up --data \'{"email":"dana@example.com","password":"<a strong one>"}\'\nvxil api POST /v1/orgs/org_\u2026/members --data \'{"user_id":"<alice>","role":"member"}\'\nvxil api POST /v1/orgs/org_\u2026/members --data \'{"user_id":"<dana>","role":"finance"}\'\n# 201 { "data": { "org_id": "org_\u2026", "user_id": "\u2026", "role": "finance" } }\n```\n\nCheck what the session will carry:\n\n```bash\nvxil api GET "/v1/orgs/session-claims?user_id=<dana>"\n# 200 { "data": { "user_id": "\u2026", "org_id": "org_\u2026", "role": "finance", "perms": [...] } }\n```\n\n**3. Sign in \u2014 and watch the device cap.** Sign the same person in four times:\n\n```bash\ncurl -s -X POST "$API/v1/auth/sign-in" -H "authorization: Bearer $KEY" \\\n  -H \'content-type: application/json\' \\\n  -d \'{"email":"dana@example.com","password":"<a strong one>"}\'\n# 200 { "data": { "user_id": "\u2026",\n#                 "session": { "token": "\u2026", "refresh_token": "\u2026", "expires_at": "\u2026" },\n#                 "took_over": [ "sess_\u2026" ] } }\n```\n\nThe fourth sign-in reports the session it revoked in `took_over`. That array only appears because\n`session.maxConcurrent` is set \u2014 leave it out and responses are byte-identical to a backend that\nnever heard of the cap.\n\nRepeated wrong passwords stop being cheap after five: `429 account_locked` with a `Retry-After`\nheader, for fifteen minutes. Because the counter is keyed on a hash of the identifier, an unknown\naddress locks out exactly like a real one \u2014 no probing for which emails exist.\n\n**4. Write a document with a budget.** As the server key (no end-user session):\n\n```bash\nvxil api POST /v1/cms/items/projects --data \'{"data":{"name":"Northwind Rollout","code":"NW-2026","stage":"active"}}\'\nvxil api POST /v1/cms/items/documents --data \'{"data":{"title":"Statement of work","author":"<dana>","project":"<project item_id>","state":"draft","budget_usd":240000}}\'\n# 201 { "data": { "item_id": "itm_\u2026", "collection": "documents", "status": "draft",\n#                 "data": { "title": "\u2026", "budget_usd": 240000, \u2026 }, "version": 1, \u2026 } }\n```\n\nThe server key sees `budget_usd`. That is the point: the gate is for **end users**, not for you.\n\n**5. The gate, live.** Read the same document as a signed-in member, by sending the session\'s\n`token` in the `X-Vxil-End-User` header:\n\n```bash\n# dana \u2014 role `finance`\ncurl -s "$API/v1/cms/items/documents/<id>" \\\n  -H "authorization: Bearer $KEY" -H "x-vxil-end-user: <dana\'s session token>"\n# 200 \u2026 "data": { "title": "Statement of work", "budget_usd": 240000, "state": "draft", \u2026 }\n\n# alice \u2014 role `member`\ncurl -s "$API/v1/cms/items/documents/<her own document\'s id>" \\\n  -H "authorization: Bearer $KEY" -H "x-vxil-end-user: <alice\'s session token>"\n# 200 \u2026 "data": { "title": "\u2026", "state": "draft", \u2026 }        \u2190 budget_usd is ABSENT\n```\n\nAbsent, not `null` \u2014 a `null` would itself be an answer. And it cannot be reached sideways either:\n\n```bash\ncurl -s "$API/v1/cms/items/documents?filter=%7B%22budget_usd%22%3A%7B%22%24gt%22%3A0%7D%7D" \\\n  -H "authorization: Bearer $KEY" -H "x-vxil-end-user: <alice\'s session token>"\n# 422 { "error": { "code": "invalid_query", "message": "unknown field \'budget_usd\' \u2026" } }\n```\n\nTo a member without the role the field does not exist \u2014 not in the document, not in a filter, not\nin a sort, not through an expanded relation. Promote alice to `finance`, have her sign in again,\nand the field is simply there: the role travels on the session, so a new session is all it takes.\n\n**6. A delete that refuses.** The project still has a document pointing at it:\n\n```bash\nvxil api DELETE /v1/cms/items/projects/<project item_id>\n# 409 { "error": { "code": "referenced",\n#        "message": "this item is still referenced by 1 live item(s) through an on_delete: \'restrict\' relation \u2026; nothing was deleted.",\n#        "referencing": [ { "collection": "documents", "field": "project", "item_id": "itm_\u2026", "status": "draft" } ],\n#        "has_more": false } }\n```\n\nAsk who is holding it, the same way the 409 did:\n\n```bash\nvxil api GET /v1/cms/items/projects/<project item_id>/backlinks\n# 200 { "data": { "collection": "projects", "item_id": "itm_\u2026",\n#                 "backlinks": [ { "collection": "documents", "field": "project", "item_id": "itm_\u2026", "status": "draft" } ],\n#                 "count": 1, "has_more": false, "limit": 25 } }\n```\n\n**7. The button.** One action, one function, one step:\n\n```bash\ncurl -s -X POST "$API/v1/cms/items/documents/<id>/actions/archive" \\\n  -H "authorization: Bearer $KEY" -H "x-vxil-end-user: <dana\'s session token>"\n# 200 { "data": { "collection": "documents", "item_id": "itm_\u2026", "action": "archive",\n#                 "fn": "archive-document",\n#                 "result": { "archived": "itm_\u2026", "from": "draft", "state": "archived" } } }\n```\n\nThe function receives `{ collection, item_id, action, actor, item }` and runs with **the pressing\nmember\'s** verified identity, so its write is owner-scoped exactly as if they had made it. Press it\nagain and it answers `already: true` \u2014 a button a human can double-click needs to be idempotent.\n\nTry an illegal jump instead (`archived \u2192 draft`) and the collection\'s lifecycle hook rejects it\ninside the same write, so the button and the API can never disagree:\n\n```bash\nvxil api PATCH /v1/cms/items/documents/<id> --data \'{"data":{"state":"draft"}}\'\n# 422 \u2026 "illegal document state transition"\n```\n\n**8. Real authorization, when advisory is not enough.** The session role is a *snapshot*, refreshed\nwith the session. For anything that must reflect a revocation immediately, ask:\n\n```bash\nvxil api GET "/v1/orgs/org_\u2026/check?user_id=<dana>&permission=budgets.approve"\n# 200 { "data": { "org_id": "org_\u2026", "user_id": "\u2026", "permission": "budgets.approve",\n#                 "role": "finance", "allowed": true, "source": "role" } }\n```\n\n## What to learn from this\n\n- **Roles are data; the gate is config.** `finance` is a row you can create at 4pm on a Friday.\n  `readRoles: [\'finance\']` is one field attribute. Neither is a code path you maintain.\n- **Field-level security has to be fail-safe in every direction, or it is theatre.** A gated field\n  is removed from the document, from filters, from sorts, from expanded relations, and it is never\n  served on a public read lane. The only caller that still sees it is your own backend.\n- **Owner-scoping and role-gating answer different questions.** `ownerField` decides *which rows*\n  a member can see. `readRoles` decides *which fields* inside a row they get. You usually want both.\n- **`restrict` beats a cascade you did not think about.** Refusing the delete and naming the\n  holders turns a data-loss bug into a 409 your UI can explain.\n- **An action is one step, on purpose.** The moment a button needs conditions or a second step, it\n  is a function of yours, not a config entry \u2014 and that boundary is what keeps this from becoming a\n  workflow engine.\n\n**Pairs with:** `templates/crm/` (the same relational spine without the org layer) and\n`templates/helpdesk/` (owner-scoped records with a state machine).\n',
     "functions": {
-      "archive-document.ts": "// archive-document.ts \u2014 the ARCHIVE BUTTON (a vxil function).\n//\n// Trigger: the per-record action `archive` declared on the `documents`\n// collection. Pressing the button POSTs\n//   /v1/cms/items/documents/<id>/actions/archive\n// and the platform invokes THIS function once with the action envelope as its\n// payload:\n//   { collection, item_id, action, actor, item: { item_id, status, version, data } }\n//\n// The pressing member's verified principal is carried into the scoped token, so\n// the PATCH below is owner-scoped exactly as if the member had written it \u2014 a\n// member can archive their own document and nobody else's, with no check here.\n//\n// It writes ONE transition (\u2192 'archived'). The collection's lifecycle hook is\n// still the authority: an illegal transition is rejected in the same write, and\n// this function reports that rejection instead of pretending it succeeded.\n\ninterface ActionPayload {\n  collection?: string;\n  item_id?: string;\n  action?: string;\n  actor?: { principal?: string; end_user_id?: string };\n  item?: { status?: string; version?: number; data?: Record<string, unknown> };\n}\ninterface Env {\n  vxil_base?: string;\n  scoped_jwts?: Record<string, string>;\n  payload?: ActionPayload;\n}\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const itemId = env.payload?.item_id;\n    if (!cms || !itemId || env.payload?.collection !== 'documents') {\n      return Response.json({ skipped: true, reason: 'not a documents action' });\n    }\n\n    // Already archived \u2192 nothing to do. The action is human-initiated and can be\n    // pressed twice; make the second press a no-op rather than an error.\n    const was = String(env.payload?.item?.data?.state ?? '');\n    if (was === 'archived') {\n      return Response.json({ archived: itemId, already: true, state: 'archived' });\n    }\n\n    const res = await fetch(`${base}/v1/cms/items/documents/${itemId}`, {\n      method: 'PATCH',\n      headers: { authorization: `Bearer ${cms}`, 'content-type': 'application/json' },\n      body: JSON.stringify({\n        data: { state: 'archived', updated_at: new Date().toISOString() },\n      }),\n    });\n\n    if (!res.ok) {\n      // The lifecycle hook refuses an illegal transition in-transaction (422).\n      // Surface the real reason \u2014 the action route relays this class straight\n      // back to the caller as `action_failed`.\n      const detail = await res.text();\n      return Response.json(\n        { error: 'archive_refused', from: was, status: res.status, detail: detail.slice(0, 300) },\n        { status: res.status === 422 ? 422 : 502 },\n      );\n    }\n\n    return Response.json({ archived: itemId, from: was || 'draft', state: 'archived' });\n  },\n};\n"
+      "archive-document.ts": "// archive-document.ts \u2014 the ARCHIVE BUTTON (a vxil function).\n//\n// Trigger: the per-record action `archive` declared on the `documents`\n// collection. Pressing the button POSTs\n//   /v1/cms/items/documents/<id>/actions/archive\n// and the platform invokes THIS function once with the action envelope as its\n// payload:\n//   { collection, item_id, action, actor, item: { item_id, status, version, data } }\n//\n// The pressing member's verified principal is carried into the scoped token, so\n// the PATCH below is owner-scoped exactly as if the member had written it \u2014 a\n// member can archive their own document and nobody else's, with no check here.\n//\n// It writes ONE transition (\u2192 'archived'). The collection's lifecycle hook is\n// still the authority: an illegal transition is rejected in the same write, and\n// this function reports that rejection instead of pretending it succeeded.\n\ninterface ActionPayload {\n  collection?: string;\n  item_id?: string;\n  action?: string;\n  actor?: { principal?: string; end_user_id?: string };\n  item?: { status?: string; version?: number; data?: Record<string, unknown> };\n}\ninterface Env {\n  vxil_base?: string;\n  scoped_jwts?: Record<string, string>;\n  payload?: ActionPayload;\n}\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const itemId = env.payload?.item_id;\n    // The platform now filters cms-hook deliveries on the binding's collection/event\n    // server-side (functions.md \xA73); this guard stays as belt-and-braces.\n    if (!cms || !itemId || env.payload?.collection !== 'documents') {\n      return Response.json({ skipped: true, reason: 'not a documents action' });\n    }\n\n    // Already archived \u2192 nothing to do. The action is human-initiated and can be\n    // pressed twice; make the second press a no-op rather than an error.\n    const was = String(env.payload?.item?.data?.state ?? '');\n    if (was === 'archived') {\n      return Response.json({ archived: itemId, already: true, state: 'archived' });\n    }\n\n    const res = await fetch(`${base}/v1/cms/items/documents/${itemId}`, {\n      method: 'PATCH',\n      headers: { authorization: `Bearer ${cms}`, 'content-type': 'application/json' },\n      body: JSON.stringify({\n        data: { state: 'archived', updated_at: new Date().toISOString() },\n      }),\n    });\n\n    if (!res.ok) {\n      // The lifecycle hook refuses an illegal transition in-transaction (422).\n      // Surface the real reason \u2014 the action route relays this class straight\n      // back to the caller as `action_failed`.\n      const detail = await res.text();\n      return Response.json(\n        { error: 'archive_refused', from: was, status: res.status, detail: detail.slice(0, 300) },\n        { status: res.status === 422 ? 422 : 502 },\n      );\n    }\n\n    return Response.json({ archived: itemId, from: was || 'draft', state: 'archived' });\n  },\n};\n"
     }
   },
   {
@@ -9125,7 +9887,7 @@ export default defineConfig({
 ];
 
 // src/migrate/adapters/csv-json.ts
-import { readFileSync as readFileSync6, readdirSync, existsSync as existsSync6, statSync } from "node:fs";
+import { readFileSync as readFileSync7, readdirSync, existsSync as existsSync7, statSync } from "node:fs";
 import { basename as basename3, extname, join as join3, resolve as resolve6 } from "node:path";
 function parseCsv(text) {
   const src = text.charCodeAt(0) === 65279 ? text.slice(1) : text;
@@ -9244,11 +10006,11 @@ var CsvJsonAdapter = class {
   }
   load() {
     if (this.cache) return this.cache;
-    if (!existsSync6(this.dir)) throw new Error(`csv-json: directory not found: ${this.dir}`);
+    if (!existsSync7(this.dir)) throw new Error(`csv-json: directory not found: ${this.dir}`);
     let overrides = {};
     const schemaFile = join3(this.dir, "_schema.json");
-    if (existsSync6(schemaFile)) {
-      overrides = JSON.parse(readFileSync6(schemaFile, "utf8"));
+    if (existsSync7(schemaFile)) {
+      overrides = JSON.parse(readFileSync7(schemaFile, "utf8"));
     }
     const warnings = [
       `csv-json: column types inferred from a \u2264${this.sampleSize}-row value sample \u2014 confirm the plan before load`
@@ -9301,7 +10063,7 @@ var CsvJsonAdapter = class {
       warnings
     };
     const objectsRoot = join3(this.dir, OBJECTS_DIR);
-    if (existsSync6(objectsRoot)) {
+    if (existsSync7(objectsRoot)) {
       const buckets = readdirSync(objectsRoot, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => ({ name: e.name, objectCount: walkFiles(join3(objectsRoot, e.name)).length })).sort((a, b2) => a.name.localeCompare(b2.name));
       if (buckets.length > 0) schema.buckets = buckets;
     }
@@ -9324,7 +10086,7 @@ var CsvJsonAdapter = class {
     return this.cache;
   }
   loadCsv(file, schemaName, tableName, overrides, warnings) {
-    const parsed = parseCsv(readFileSync6(file, "utf8"));
+    const parsed = parseCsv(readFileSync7(file, "utf8"));
     const header = parsed[0];
     if (!header || header.length === 0) {
       warnings.push(`csv-json: ${basename3(file)} is empty (no header row) \u2014 skipped`);
@@ -9362,7 +10124,7 @@ var CsvJsonAdapter = class {
     return { schema: schemaName, name: tableName, columns, rows };
   }
   loadJson(file, schemaName, tableName, overrides, warnings) {
-    const parsed = JSON.parse(readFileSync6(file, "utf8"));
+    const parsed = JSON.parse(readFileSync7(file, "utf8"));
     if (!Array.isArray(parsed)) {
       warnings.push(`csv-json: ${basename3(file)} is not a JSON array of row objects \u2014 skipped`);
       return void 0;
@@ -9436,7 +10198,7 @@ var CsvJsonAdapter = class {
    *  read LAZILY per object via stream() — a dry-run never opens them. */
   async *readObjects(bucket) {
     const root = join3(this.dir, OBJECTS_DIR, bucket);
-    if (!existsSync6(root)) {
+    if (!existsSync7(root)) {
       throw new Error(`csv-json: unknown bucket '${bucket}' \u2014 no ${OBJECTS_DIR}/${bucket}/ directory in the export`);
     }
     for (const rel of walkFiles(root)) {
@@ -9446,7 +10208,7 @@ var CsvJsonAdapter = class {
         path: rel,
         contentType: EXT_CONTENT_TYPES[ext] ?? "application/octet-stream",
         size: statSync(abs).size,
-        stream: async () => readFileSync6(abs)
+        stream: async () => readFileSync7(abs)
       };
     }
   }
@@ -9629,7 +10391,7 @@ var catalogSql = {
       ORDER BY cl.relname, c.conname`,
     params: [schemas]
   }),
-  /** RLS policies verbatim (R15 residual; R6 owner-column grep source). */
+  /** Source row-level access rules verbatim (R15 residual; R6 owner-column grep source). */
   rlsPolicies: (schemas) => ({
     text: `
       SELECT schemaname AS table_schema, tablename AS table_name,
@@ -10212,6 +10974,11 @@ function hasFlag(name) {
   return rest.includes(`--${name}`);
 }
 var jsonOut = rest.includes("--json");
+function ttlFlag(fallback) {
+  const parsed = parseTtlFlag(flag("ttl"), fallback);
+  if ("error" in parsed) fail(parsed.error);
+  return parsed.hours;
+}
 function fail(msg, code = 1) {
   console.error(`vxil: ${msg}`);
   process.exit(code);
@@ -10303,6 +11070,8 @@ function persistLink(slug, tenantId, apiKey, base) {
   saveCredentials(creds);
   const as = flag("as");
   const env = flag("env") ?? envLabelFor(base);
+  const envWarn = envLabelWarning(env, base);
+  if (envWarn) console.error(`vxil: ${envWarn}`);
   const existing = loadProject();
   if (as !== void 0) {
     if (!TARGET_NAME_RE.test(as)) fail(`--as '${as}': a target name is 1\u201340 chars of [a-z0-9-], starting with a letter`);
@@ -10416,7 +11185,7 @@ function againstSelector(name) {
 }
 function loadDriftIgnore() {
   const f = resolve7(process.cwd(), ".vxil", "drift-ignore");
-  return parseIgnorePatterns(flag("ignore"), existsSync7(f) ? readFileSync7(f, "utf8") : void 0);
+  return parseIgnorePatterns(flag("ignore"), existsSync8(f) ? readFileSync8(f, "utf8") : void 0);
 }
 async function runApply(apply, sel = "prod", opts = {}) {
   const gate = !apply && !!opts.gate;
@@ -10424,6 +11193,7 @@ async function runApply(apply, sel = "prod", opts = {}) {
   const { api, target } = requireApi(sel, apply ? { write: "push" } : gate ? { exitCode: 2 } : {});
   if (!apply) console.error(targetBanner(target, gate ? "diff" : "plan"));
   const report = { drift: 0, ignored: 0, errors: 0 };
+  const compared = newComparedCounts({ apiState: !!opts.apiState });
   const ignore = apply ? [] : loadDriftIgnore();
   const ignoredKeys = [];
   const count = (key) => {
@@ -10441,18 +11211,55 @@ async function runApply(apply, sel = "prod", opts = {}) {
     process.exit(2);
   }
   const cwd = process.cwd();
-  if (cfg.cms?.collections && Object.keys(cfg.cms.collections).length) {
-    const r = await planCmsSchema({ api, collections: cfg.cms.collections, apply, allowDestructive: hasFlag("allow-destructive") });
+  const notCompared = (u, hint) => {
+    console.log(formatNotCompared(u, hint));
+    if (gate) report.errors++;
+  };
+  const runSection = async (label, fn) => {
+    if (!gate) {
+      await fn();
+      return;
+    }
+    try {
+      await fn();
+    } catch (e) {
+      console.log(`  ! not compared: ${label} \u2192 ${e.message.split("\n")[0]}`);
+      report.errors++;
+    }
+  };
+  await runSection("cms.schema", async () => {
+    if (!cfg.cms?.collections || !Object.keys(cfg.cms.collections).length) return;
+    const r = await planCmsSchema({
+      api,
+      collections: cfg.cms.collections,
+      apply,
+      allowDestructive: hasFlag("allow-destructive"),
+      // the C-1 re-index loop can take several pages on a big collection —
+      // print progress so a long push is never a silent stall
+      onProgress: (line) => console.log(line)
+    });
     console.log("\ncms.schema:");
+    if (r.remoteUnavailable) {
+      notCompared(r.remoteUnavailable, "needs cms:read, features:read or admin");
+      return;
+    }
     console.log(formatCmsChanges(r.changes));
     if (apply && r.applied) console.log(`  \u2713 applied ${r.applied} schema change(s)`);
     for (const c of r.changes) count(`cms:${c.collection}${c.field ? `.${c.field}` : ""}`);
-  }
+    compared.collections += Object.keys(cfg.cms.collections).length;
+  });
   const { functions: _fnFeature, ...configFeatures } = cfg.features;
   void _fnFeature;
-  if (Object.keys(configFeatures).length) {
+  await runSection("config", async () => {
+    if (!Object.keys(configFeatures).length) return;
     const results = await planOrPush({ api, features: configFeatures, apply });
     for (const r of results) {
+      if (r.remoteUnavailable) {
+        console.log(`
+${r.feature}:`);
+        notCompared(r.remoteUnavailable, "needs features:read or admin");
+        continue;
+      }
       console.log(`
 ${r.feature} (remote v${r.version}):`);
       const { kept, ignored } = partitionConfigChanges(r.feature, r.changes, ignore);
@@ -10464,29 +11271,45 @@ ${r.feature} (remote v${r.version}):`);
         console.log("  provenance (declared in vxil.config vs schema default):");
         console.log(formatExplain(r.feature, explainLeaves(configFeatures[r.feature], r.effective), new Set(r.changes.map((c) => c.path))));
       }
+      compared.features++;
+    }
+  });
+  await runSection("functions", async () => {
+    if (!cfg.functions || !Object.keys(cfg.functions).length) {
+      if (cfg.features.functions) {
+        console.log("\nfunctions: features.functions is declared but no functions/ are defined to deploy \u2014 the feature enables per-function on deploy (no feature-level config namespace).");
+      }
+      return;
     }
-  }
-  if (cfg.functions && Object.keys(cfg.functions).length) {
     const r = await planFunctions({ api, functions: cfg.functions, cwd, apply });
     console.log("\nfunctions:");
+    if (r.remoteUnavailable) {
+      notCompared(r.remoteUnavailable, "needs functions:read, features:read or admin");
+      return;
+    }
     console.log(formatFnChanges(r.changes));
     if (apply && r.applied) console.log(`  \u2713 deployed ${r.applied} function(s)`);
     if (apply && r.cmsHookSubscriptions && (r.cmsHookSubscriptions.created || r.cmsHookSubscriptions.deleted)) {
       console.log(`  \u2713 cms-hook subscription reconciled (+${r.cmsHookSubscriptions.created} / -${r.cmsHookSubscriptions.deleted})`);
     }
+    if (apply && r.webhookSubscriptions && (r.webhookSubscriptions.created || r.webhookSubscriptions.deleted)) {
+      console.log(`  \u2713 webhook-trigger subscription reconciled (+${r.webhookSubscriptions.created} / -${r.webhookSubscriptions.deleted})`);
+    }
     for (const c of r.changes) if (c.kind !== "unchanged") count(`function:${c.name}`);
-  } else if (cfg.features.functions) {
-    console.log("\nfunctions: features.functions is declared but no functions/ are defined to deploy \u2014 the feature enables per-function on deploy (no feature-level config namespace).");
-  }
+    compared.functions += Object.keys(cfg.functions).length;
+  });
   if (!apply && (gate || explain)) {
-    const refs = collectSecretRefs(cfg);
-    const res = await api("GET", "/v1/secrets");
-    console.log("\nsecrets (names only \u2014 values are never read or compared):");
-    if (res.status !== 200) {
-      const e = res.body.error ?? {};
-      console.log(`  ! not compared: GET /v1/secrets \u2192 ${e.code ?? res.status}${e.message ? ` \u2014 ${e.message}` : ""} (needs features:write, secrets:write or admin)`);
-      if (gate) report.errors++;
-    } else {
+    await runSection("secrets", async () => {
+      const refs = collectSecretRefs(cfg);
+      const res = await api("GET", "/v1/secrets");
+      console.log("\nsecrets (names only \u2014 values are never read or compared):");
+      if (res.status !== 200) {
+        notCompared(
+          { route: "GET /v1/secrets", status: res.status, ...res.body.error?.code ? { code: res.body.error.code } : {}, ...res.body.error?.message ? { message: res.body.error.message } : {} },
+          "needs features:write, secrets:write or admin"
+        );
+        return;
+      }
       const stored = res.body.data?.secrets ?? [];
       const cmp = compareSecretNames(refs, stored);
       if (!cmp.missing.length && !cmp.unreferenced.length) console.log(`  (in sync \u2014 ${cmp.present.length} ref(s), all stored)`);
@@ -10497,15 +11320,61 @@ ${r.feature} (remote v${r.version}):`);
       }
       for (const u of cmp.unreferenced) console.log(`  \xB7 ${u.feature}/${u.secret_name} stored but not referenced by this config (informational)`);
       if (cmp.missing.length) console.log("  note: a push with an unstored ref is a WARNING, never a 422 \u2014 set values after the push with `vxil secrets set <feature>/<name>`");
-    }
+      compared.secrets += refs.length;
+    });
+  }
+  const apiStateCounts = {
+    policies: { compared: 0, drift: 0 },
+    subscriptions: { compared: 0, drift: 0 },
+    campaigns: { compared: 0, drift: 0 }
+  };
+  if (opts.apiState) {
+    await runSection("api-state", async () => {
+      const self = requireApi(opts.apiState.self, { exitCode: 2 });
+      const other = requireApi(opts.apiState.against, { exitCode: 2 });
+      console.log(`
+api state \u2014 ${self.target.tenantSlug ?? "(env key)"} vs ${other.target.tenantSlug ?? "(env key)"} (read-only: \`vxil push\` does NOT converge API state, and a config rollback does not restore it):`);
+      const [a, b2] = await Promise.all([fetchApiState(self.api), fetchApiState(other.api)]);
+      for (const u of a.unavailable) notCompared(u, `target ${self.target.tenantSlug ?? ""}`.trim());
+      for (const u of b2.unavailable) notCompared(u, `--against ${other.target.tenantSlug ?? ""}`.trim());
+      for (const w of [...truncationWarnings(a, "the target"), ...truncationWarnings(b2, "--against")]) {
+        console.log(w);
+        if (gate) report.errors++;
+      }
+      if (a.unavailable.length || b2.unavailable.length) return;
+      const rows = diffApiState(a, b2);
+      console.log(formatApiStateRows(rows));
+      for (const r of rows) count(apiStateDriftKey(r));
+      const union = (x, y, k) => (/* @__PURE__ */ new Set([...x.map(k), ...y.map(k)])).size;
+      apiStateCounts.policies.compared = union(a.policies, b2.policies, (p) => p.name);
+      apiStateCounts.subscriptions.compared = union(a.subscriptions, b2.subscriptions, (x) => x.target_url);
+      apiStateCounts.campaigns.compared = union(a.campaigns, b2.campaigns, (c) => c.name);
+      for (const r of rows) {
+        if (r.section === "policy") apiStateCounts.policies.drift++;
+        else if (r.section === "subscription") apiStateCounts.subscriptions.drift++;
+        else apiStateCounts.campaigns.drift++;
+      }
+      compared.policies = apiStateCounts.policies.compared;
+      compared.subscriptions = apiStateCounts.subscriptions.compared;
+      compared.campaigns = apiStateCounts.campaigns.compared;
+    });
   }
   if (gate) {
     const code = driftExitCode(report);
     if (jsonOut) {
-      console.log(JSON.stringify({ ok: code === 0, exit_code: code, target: target.tenantSlug ?? null, env: target.envLabel, ...report, ignored_keys: ignoredKeys }));
+      console.log(JSON.stringify({
+        ok: code === 0,
+        exit_code: code,
+        target: target.tenantSlug ?? null,
+        env: target.envLabel,
+        ...report,
+        compared,
+        ignored_keys: ignoredKeys,
+        ...opts.apiState ? { api_state: apiStateCounts } : {}
+      }));
     } else {
       console.log(`
-vxil diff \u2192 ${report.drift} drift item(s), ${report.ignored} ignored, ${report.errors} error(s) \u2014 exit ${code}`);
+vxil diff \u2192 ${report.drift} drift item(s), ${report.ignored} ignored, ${report.errors} error(s) \u2014 compared ${formatCompared(compared)} \u2014 exit ${code}`);
     }
     process.exit(code);
   }
@@ -10603,7 +11472,12 @@ async function runGen(sel = "prod", opts = {}) {
         required: !!f.required,
         index_slot: f.indexSlot ?? null,
         ...f.relationTo ? { relation_to: f.relationTo } : {},
-        ...f.computed ? { computed: f.computed } : {}
+        ...f.computed ? { computed: f.computed } : {},
+        // `validation.enum` becomes a string-literal union in the generated
+        // types, so the OFFLINE collector must carry it too (the online path
+        // gets it from GET /v1/cms/collections, which returns the whole row) —
+        // else `vxil gen --offline` and `vxil gen` would disagree.
+        ...f.validation ? { validation: f.validation } : {}
       }))
     }));
     functions = Object.entries(cfg.functions ?? {}).map(([name, def]) => ({
@@ -10651,15 +11525,15 @@ async function runGen(sel = "prod", opts = {}) {
     ...catalog ? { tools: catalog.tools.length } : {}
   };
   if (hasFlag("check")) {
-    const existing = existsSync7(outPath) ? readFileSync7(outPath, "utf8") : "";
+    const existing = existsSync8(outPath) ? readFileSync8(outPath, "utf8") : "";
     if (body(existing) !== body(src)) {
       fail(`${out} is out of date (drift) \u2014 run \`vxil gen\` and commit. A collection/feature/function changed since it was generated.`);
     }
     if (catalog) {
       let upToDate = false;
-      if (existsSync7(mcpPath)) {
+      if (existsSync8(mcpPath)) {
         try {
-          const cur = JSON.parse(readFileSync7(mcpPath, "utf8"));
+          const cur = JSON.parse(readFileSync8(mcpPath, "utf8"));
           const want = JSON.parse(JSON.stringify(catalog));
           delete cur.generated_at;
           delete want.generated_at;
@@ -10684,6 +11558,7 @@ async function runGen(sel = "prod", opts = {}) {
 }
 async function runWatch(sel) {
   const cwd = process.cwd();
+  await promotionGate(resolveTargetOrFail(sel), false);
   console.log("vxil dev --watch: applying on save (Ctrl-C to stop)\u2026");
   const apply = async () => {
     try {
@@ -10704,11 +11579,11 @@ async function runWatch(sel) {
     }, 300);
   };
   const watchers = [];
-  const cfgFile = CONFIG_FILENAMES.map((n) => resolve7(cwd, n)).find((f) => existsSync7(f));
+  const cfgFile = CONFIG_FILENAMES.map((n) => resolve7(cwd, n)).find((f) => existsSync8(f));
   if (cfgFile) watchers.push(watch(cfgFile, trigger));
   for (const dir of ["functions", "cms"]) {
     const d = resolve7(cwd, dir);
-    if (existsSync7(d)) watchers.push(watch(d, trigger));
+    if (existsSync8(d)) watchers.push(watch(d, trigger));
   }
   process.on("SIGINT", () => {
     for (const w of watchers) w.close();
@@ -10718,22 +11593,19 @@ async function runWatch(sel) {
   await new Promise(() => {
   });
 }
-function mockFeatures(cfg) {
-  return Object.entries(cfg.features).filter(([, conf]) => {
-    const c = conf;
-    return c.provider === "mock" || c.defaultProvider === "mock" || c.embed?.provider === "mock";
-  }).map(([f]) => f);
-}
-function isProductionTarget(t) {
-  return t.envLabel === "production" && t.slot !== "dev" && !(t.slot === "named" && t.selector.kind === "named" && t.selector.name === "dev");
-}
 async function promotionGate(t, explicitProd) {
   const resolvedProd = isProductionTarget(t);
   if (!resolvedProd && !explicitProd) return;
+  const labelNotice = unrecognizedLabelNotice(t);
+  if (labelNotice) console.error(`vxil: ${labelNotice}`);
   const cfg = await loadVxilConfig();
-  const mocks = mockFeatures(cfg);
-  if (mocks.length && !hasFlag("allow-mock-in-prod")) {
-    fail(`refusing to push to PRODUCTION tenant '${t.tenantSlug ?? "(env key)"}' (${t.envLabel} \xB7 resolved via ${describeSelector(t.selector)}): mock providers on [${mocks.join(", ")}] would ship to production (mock email/payments silently no-op). Set a real provider, or override with --allow-mock-in-prod.`);
+  const where = `'${t.tenantSlug ?? "(env key)"}' (${t.envLabel} \xB7 resolved via ${describeSelector(t.selector)})`;
+  const notice = redirectOriginNotice(cfg);
+  if (notice) console.error(`vxil: production review \u2014 ${notice}`);
+  const refusals = promotionRefusals(cfg, hasFlag);
+  if (refusals.length) {
+    fail(`refusing to push to PRODUCTION tenant ${where}:
+` + refusals.map((r) => `  - ${r.message}`).join("\n"));
   }
   if (hasFlag("yes")) return;
   if (!process.stdin.isTTY && !explicitProd) {
@@ -10771,6 +11643,8 @@ async function runDoctor() {
   if (proj) {
     const slots = bindingSlots(proj).map((s) => `${s.label}=${s.slug}`);
     checks.push({ name: "bound slots", ok: true, detail: `${slots.join(" \xB7 ")}${proj.dev ? "" : " (no dev slot: `--dev` fails closed until `vxil dev up` / `vxil link <slug> --as dev`)"}` });
+    const expiry = devSlotExpiryCheck(proj.dev, /* @__PURE__ */ new Date());
+    if (expiry) checks.push(expiry);
   }
   if (t?.apiKey) {
     const api = makeApi({ apiKey: t.apiKey, baseUrl: t.baseUrl });
@@ -10791,6 +11665,12 @@ async function runDoctor() {
           ));
         }
       }
+      if (live.has("payments")) {
+        const pres = await api("GET", "/v1/config/payments");
+        if (pres.status === 200) {
+          checks.push(...paymentsWebhookSecretChecks(pres.body.data?.manifest));
+        }
+      }
     } else {
       checks.push({ name: "edge reachable", ok: false, detail: `GET /v1/features \u2192 ${fres.status}` });
     }
@@ -10836,7 +11716,7 @@ async function runDoctor() {
   }
   if (cfg?.functions) {
     for (const [n, def] of Object.entries(cfg.functions)) {
-      const ok = existsSync7(resolve7(process.cwd(), def.entry));
+      const ok = existsSync8(resolve7(process.cwd(), def.entry));
       checks.push({ name: `function '${n}' entry`, ok, detail: ok ? def.entry : `missing file: ${def.entry}` });
     }
   }
@@ -10894,13 +11774,13 @@ function scaffoldProject(configSrc, fns) {
   const entries = Object.entries(fns ?? {});
   if (entries.length > 0) {
     for (const [file, src] of entries) writeFileSync6(resolve7(cwd, "functions", file), src);
-  } else if (!existsSync7(resolve7(cwd, "functions/hello.ts"))) {
+  } else if (!existsSync8(resolve7(cwd, "functions/hello.ts"))) {
     writeFileSync6(resolve7(cwd, "functions/hello.ts"), STARTER_FN);
   }
   mkdirSync5(resolve7(cwd, ".vxil"), { recursive: true });
   const gi = resolve7(cwd, ".gitignore");
   const ignore = ["", "# vxil", ".vxil/", ".env.local", ""].join("\n");
-  if (!existsSync7(gi) || !readFileSync7(gi, "utf8").includes(".vxil/")) appendFileSync2(gi, ignore);
+  if (!existsSync8(gi) || !readFileSync8(gi, "utf8").includes(".vxil/")) appendFileSync2(gi, ignore);
   const pkg = ensureScaffoldPackageJson(cwd);
   if (pkg.action === "skipped") console.log(`  ! package.json not patched: ${pkg.reason}`);
   return pkg;
@@ -10908,7 +11788,7 @@ function scaffoldProject(configSrc, fns) {
 function initProject() {
   const cwd = process.cwd();
   const cfgPath = resolve7(cwd, "vxil.config.ts");
-  if (existsSync7(cfgPath) && !hasFlag("force")) fail("vxil.config.ts already exists (use --force to overwrite)");
+  if (existsSync8(cfgPath) && !hasFlag("force")) fail("vxil.config.ts already exists (use --force to overwrite)");
   const template = flag("template") ?? "tasks";
   const tpl = TEMPLATE_CATALOG.find((t) => t.id === template);
   if (!tpl) fail(`unknown template '${template}' \u2014 run \`vxil templates\` to list the gallery, or choose: ${TEMPLATE_CATALOG.map((t) => t.id).join(", ")}`);
@@ -10950,7 +11830,7 @@ try {
       const base = process.env.VXIL_BASE_URL ?? DEFAULT_BASE;
       const dash = dashboardBase(base);
       const featuresFlag = flag("features");
-      const hasConfig = CONFIG_FILENAMES.some((n) => existsSync7(resolve7(process.cwd(), n)));
+      const hasConfig = CONFIG_FILENAMES.some((n) => existsSync8(resolve7(process.cwd(), n)));
       const features = quickstartFeatures(featuresFlag, featuresFlag === void 0 && hasConfig ? await loadVxilConfig() : null);
       const email = flag("email") ?? await prompt("email: ");
       const password = flag("password") ?? await prompt("password (>=10 chars): ", { hidden: true });
@@ -10962,7 +11842,7 @@ try {
         features,
         // --dev mints an ephemeral preview tenant the server-side TTL reaper
         // tears down after --ttl hours (default 72) — the per-PR CI backend.
-        ...hasFlag("dev") ? { kind: "dev", ttl_hours: Number(flag("ttl") ?? 72) } : {},
+        ...hasFlag("dev") ? { kind: "dev", ttl_hours: ttlFlag(72) } : {},
         // --invite: required for ACCOUNT CREATION while the backend runs the
         // invite-only launch gate (existing accounts sign in ungated).
         ...flag("invite") ? { invite_code: flag("invite") } : {}
@@ -10986,7 +11866,7 @@ try {
       const slot = { tenant_id: d.tenant_id, slug: d.app_slug, edge_url: d.edge_url ?? base, env: flag("env") ?? envLabelFor(base) };
       const merged = mergePrimaryBinding(loadProject(), slot);
       saveProject(hasFlag("dev") ? { ...merged, dev: { tenant_id: slot.tenant_id, slug: slot.slug, edge_url: slot.edge_url } } : merged);
-      if (!existsSync7(resolve7(process.cwd(), "vxil.config.ts"))) initProject();
+      if (!existsSync8(resolve7(process.cwd(), "vxil.config.ts"))) initProject();
       console.log(`
 \u2713 tenant '${d.app_slug}' created \xB7 enabled: ${(d.enabled ?? []).join(", ")}`);
       if (d.expires_at) console.log(`  dev tenant \u2014 expires ${d.expires_at} (the nightly reaper tears it down; extend by recreating)`);
@@ -11054,7 +11934,7 @@ try {
         ephemeral: true,
         ...result.expires_at ? { expires_at: result.expires_at } : {}
       });
-      if (!existsSync7(resolve7(process.cwd(), "vxil.config.ts"))) scaffoldProject(TRY_CONFIG);
+      if (!existsSync8(resolve7(process.cwd(), "vxil.config.ts"))) scaffoldProject(TRY_CONFIG);
       let genOk = true;
       try {
         await runGen("prod", { offline: true });
@@ -11175,7 +12055,14 @@ ${formatSummary(state)}`);
     case "diff": {
       const against = flag("against");
       const sel = against !== void 0 ? againstSelector(against) : selector();
-      await runApply(false, sel, { explain: hasFlag("explain"), gate: against !== void 0 || hasFlag("exit-code") });
+      if (hasFlag("api-state") && against === void 0) {
+        fail("--api-state has no local source of truth \u2014 compare two live targets: `vxil diff --api-state --against <name>`", 2);
+      }
+      await runApply(false, sel, {
+        explain: hasFlag("explain"),
+        gate: against !== void 0 || hasFlag("exit-code"),
+        ...hasFlag("api-state") ? { apiState: { self: selector(), against: againstSelector(against) } } : {}
+      });
       break;
     }
     case "push": {
@@ -11277,7 +12164,7 @@ ${plan.rationale}`);
 export default defineConfig(${JSON.stringify({ features: featBlocks, cms: { collections: cmsBlock } }, null, 2)});
 `;
       const out = flag("out") ?? "vxil.config.ts";
-      if (existsSync7(resolve7(process.cwd(), out)) && !hasFlag("force")) fail(`${out} exists (use --force or --out <file>)`);
+      if (existsSync8(resolve7(process.cwd(), out)) && !hasFlag("force")) fail(`${out} exists (use --force or --out <file>)`);
       writeFileSync6(resolve7(process.cwd(), out), src);
       const pkgRes = ensureScaffoldPackageJson(process.cwd());
       if (pkgRes.action === "created" || pkgRes.action === "added") {
@@ -11387,7 +12274,7 @@ export default defineConfig(${JSON.stringify({ features: featBlocks, cms: { coll
       const file = flag("file");
       if (!feature || !file) fail("usage: vxil import <feature> --file <bundle.json> [--mode merge|replace]");
       const { api } = requireApi(selector(), { write: `import ${feature}` });
-      const bundle = JSON.parse(readFileSync7(resolve7(process.cwd(), file), "utf8"));
+      const bundle = JSON.parse(readFileSync8(resolve7(process.cwd(), file), "utf8"));
       printEnvelope(await api("POST", `/v1/import/${feature}`, { bundle, mode: flag("mode") ?? "merge" }));
       break;
     }
@@ -11401,7 +12288,7 @@ export default defineConfig(${JSON.stringify({ features: featBlocks, cms: { coll
         if (!name) fail("usage: vxil functions new <name>");
         mkdirSync5(resolve7(process.cwd(), "functions"), { recursive: true });
         const p = resolve7(process.cwd(), `functions/${name}.ts`);
-        if (existsSync7(p) && !hasFlag("force")) fail(`functions/${name}.ts exists`);
+        if (existsSync8(p) && !hasFlag("force")) fail(`functions/${name}.ts exists`);
         writeFileSync6(p, STARTER_FN);
         console.log(`scaffolded functions/${name}.ts \u2014 declare it in vxil.config.ts \`functions\` and \`vxil push\``);
       } else if (sub === "list") {
@@ -11481,8 +12368,22 @@ export default defineConfig(${JSON.stringify({ features: featBlocks, cms: { coll
         printEnvelope(await api("GET", "/v1/cms/collections"));
       } else if (sub === "pull") {
         printEnvelope(await api("GET", "/v1/cms/collections"));
+      } else if (sub === "reindex") {
+        const [collection] = positional(1);
+        if (!collection) fail("usage: vxil cms reindex <collection> [--field <field>]");
+        const field = flag("field");
+        const done = await reindexCollection({
+          api,
+          collection,
+          ...field ? { field } : {},
+          onProgress: (p) => console.log(`  \u2026 scanned ${p.scanned}, re-projected ${p.updated}` + (p.skipped > 0 ? `, ${p.skipped} skipped (written concurrently)` : ""))
+        }).catch((e) => fail(e.message));
+        console.log(`\u2713 re-indexed ${collection}${field ? `.${field}` : ""}: ${done.scanned} row(s) scanned, ${done.updated} re-projected` + (done.skipped > 0 ? `, ${done.skipped} skipped` : ""));
+        if (done.skipped > 0) {
+          console.log(`  \u26A0 ${done.skipped} row(s) were written while the re-index ran and were NOT re-projected \u2014 re-run \`vxil cms reindex ${collection}\` when writes are quiet`);
+        }
       } else {
-        fail("usage: vxil cms status|pull");
+        fail("usage: vxil cms status|pull|reindex <collection> [--field <field>]");
       }
       break;
     }
@@ -11578,7 +12479,8 @@ export default defineConfig(${JSON.stringify({ features: featBlocks, cms: { coll
   init [--template <id>] \xB7 templates \xB7 try (keyless sandbox) \xB7 quickstart [--dev --ttl <h>] \xB7 login \xB7 link <slug> [--as dev|<name>]
   architect "<describe your app>" \u2014 plain English in, a reviewed vxil.config.ts draft out
   plan [--explain] \xB7 push [--dev|--target <name>|--prod] [--server [--resume <apply_id>]] [--no-gen] \xB7 pull \xB7 gen [--check] [--offline] [--out <f>] [--no-mcp] [--mcp-out <f>]
-  diff [--against <target>|--exit-code] [--explain] [--ignore <k,\u2026>]  \u2014 CI gate: exit 0 no drift \xB7 1 drift \xB7 2 error (secrets by name only)
+    push production overrides: --allow-mock-in-prod \xB7 --allow-sandbox-in-prod \xB7 --allow-dev-origins-in-prod \xB7 --yes
+  diff [--against <target>|--exit-code] [--explain] [--ignore <k,\u2026>] [--api-state]  \u2014 CI gate: exit 0 no drift \xB7 1 drift \xB7 2 error (an unreadable remote is 2; secrets by name only)
   doctor [--dev|--target <name>]  \u2014 + secrets referenced-vs-stored (advisory) + per-function served/published/local hash
   versions <feature> \xB7 rollback <feature> --to <v>
   secrets set|list [--all-projects]|rm \xB7 seed \xB7 export|import <feature>
@@ -11587,7 +12489,7 @@ export default defineConfig(${JSON.stringify({ features: featBlocks, cms: { coll
   migrate payments --from-provider stripe|paddle|paypal|revenuecat (--customers <f.csv> | --all) [--dry-run]  \u2014 backfill subscriptions via the server sync leg (resumable)
   payments simulate --scenario refund-pair|cross-platform-unlock|renewal|expiry|past-due-grace|transfer --user <id> [--tier <t>]  \u2014 mock/dev projects only
   env pull [--dev] [--file <f>] [--print] [--no-gitignore]
-  functions new|deploy|list|delete|invoke [--async]|logs [--tail]|dev <name> [--port <n>] \xB7 cms status|pull \xB7 dev up [--ttl <h>]|down [--yes]|seed|reset
+  functions new|deploy|list|delete|invoke [--async]|logs [--tail]|dev <name> [--port <n>] \xB7 cms status|pull|reindex <collection> \xB7 dev up [--ttl <h>] [--new]|down [--yes]|seed|reset
   listen --forward-to <url> [--dev] [--source <id>] [--events <prefix,\u2026>] [--replay-last <n>] [--interval <s>] [--show-runs] [--raw]  \u2014 forward inbound webhook events to a local server
   mcp install [--client cursor|claude|vscode] [--project] [--print] [--key <k>] [--scopes a,b] [--name <server>]  \u2014 connect your editor's agent to this backend's MCP server
   dev branch [<name>] [--ttl <h=24>] [--no-env] [--print] | --list | --rm <name> [--yes]
@@ -11621,13 +12523,7 @@ async function runDev(sub) {
   const dash = dashboardBase(base);
   const proj = loadProject();
   if (sub === "up") {
-    const name = flag("name") ?? `${proj?.slug ?? "app"}-dev`;
-    const d = await devUpCreate(dash, name, Number(flag("ttl") ?? 72));
-    const binding = proj ?? { tenant_id: d.tenant_id, slug: d.slug, edge_url: d.edge_url ?? base };
-    binding.dev = { tenant_id: d.tenant_id, slug: d.slug, edge_url: d.edge_url ?? base };
-    saveProject(binding);
-    console.log(`\u2713 dev tenant '${d.slug}' ready (keyless mock providers). Use \`vxil push --dev\` / \`vxil gen\` against it.`);
-    if (d.expires_at) console.log(`  expires ${d.expires_at} \u2014 the nightly reaper deletes it then (re-run \`vxil dev up\` to extend).`);
+    await runDevUp(dash, base, proj);
   } else if (sub === "branch") {
     await runDevBranch(dash, base);
   } else if (sub === "seed") {
@@ -11646,6 +12542,61 @@ async function runDev(sub) {
     fail("usage: vxil dev up|down|seed|reset|branch");
   }
 }
+async function runDevUp(dash, base, proj) {
+  const ttlHours = ttlFlag(72);
+  const creds = loadCredentials();
+  const decision = hasFlag("new") ? { create: true } : pickDevSlot(proj, /* @__PURE__ */ new Date(), (slug) => Boolean(creds.keys?.[slug]));
+  if ("reuse" in decision) {
+    const slot = decision.reuse;
+    let expiresAt = slot.expires_at;
+    let reaped = false;
+    try {
+      const dashFn = makeDash(dash);
+      if (!haveDashSession(creds, flag("email") ?? process.env.VXIL_DEV_EMAIL, flag("password") ?? process.env.VXIL_DEV_PASSWORD)) {
+        throw new Error("no dashboard session \u2014 run `vxil login` (or pass --email/--password) to extend the TTL");
+      }
+      const cookie = await resolveDashCookie(dashFn);
+      const r = await devExtend(dashFn, cookie, { tenant_id: slot.tenant_id }, ttlHours);
+      if ("gone" in r) {
+        console.log(`  ! dev tenant '${slot.slug}' is gone (already reaped) \u2014 creating a fresh one`);
+        reaped = true;
+      } else if ("notDev" in r) {
+        console.log(`\u2713 reusing '${slot.slug}' as the dev slot \u2014 it is a STANDARD project (bound with vxil link --as dev), so it has no TTL to extend`);
+      } else {
+        expiresAt = r.expires_at ?? expiresAt;
+        console.log(`\u2713 reusing dev tenant '${slot.slug}'${expiresAt ? ` \u2014 TTL extended to ${expiresAt}` : " \u2014 TTL extended"}`);
+      }
+    } catch (e) {
+      console.log(`  ! could not extend the dev TTL (${e.message.split("\n")[0]}) \u2014 reusing '${slot.slug}' as-is`);
+    }
+    if (!reaped) {
+      const kept = loadProject() ?? { tenant_id: slot.tenant_id, slug: slot.slug, edge_url: slot.edge_url };
+      kept.dev = {
+        tenant_id: slot.tenant_id,
+        slug: slot.slug,
+        edge_url: slot.edge_url,
+        ...expiresAt ? { expires_at: expiresAt } : {}
+      };
+      saveProject(kept);
+      console.log("  use `vxil push --dev` / `vxil gen` against it; --new forces a fresh tenant.");
+      return;
+    }
+  }
+  const name = flag("name") ?? `${proj?.slug ?? "app"}-dev`;
+  const d = await devUpCreate(dash, name, ttlHours);
+  const binding = loadProject() ?? { tenant_id: d.tenant_id, slug: d.slug, edge_url: d.edge_url ?? base };
+  binding.dev = {
+    tenant_id: d.tenant_id,
+    slug: d.slug,
+    edge_url: d.edge_url ?? base,
+    ...d.expires_at ? { expires_at: d.expires_at } : {}
+  };
+  saveProject(binding);
+  console.log(`\u2713 dev tenant '${d.slug}' ready (keyless mock providers). Use \`vxil push --dev\` / \`vxil gen\` against it.`);
+  if (d.expires_at) {
+    console.log(`  expires ${d.expires_at} \u2014 the nightly reaper deletes it then; re-run \`vxil dev up\` to extend the TTL (the same tenant is reused; --new forces a fresh one).`);
+  }
+}
 async function runDevBranch(dash, base) {
   const proj = loadProject();
   if (hasFlag("list")) {
@@ -11683,7 +12634,7 @@ async function runDevBranch(dash, base) {
     slot = decision.reuse;
     console.log(`\u2713 reusing dev branch '${name}' (tenant '${slot.slug}'${slot.expires_at ? ` \xB7 expires ${slot.expires_at}` : ""})`);
   } else {
-    const d = await devUpCreate(dash, `${proj?.slug ?? "app"}-${name}`, Number(flag("ttl") ?? 24));
+    const d = await devUpCreate(dash, `${proj?.slug ?? "app"}-${name}`, ttlFlag(24));
     slot = {
       tenant_id: d.tenant_id,
       slug: d.slug,
@@ -11771,7 +12722,7 @@ function runEnvPull(sel) {
   const fileArg = flag("file") ?? ".env.local";
   const file = resolve7(process.cwd(), fileArg);
   const note = guardEnvFile(fileArg);
-  const existing = existsSync7(file) ? readFileSync7(file, "utf8") : "";
+  const existing = existsSync8(file) ? readFileSync8(file, "utf8") : "";
   writeFileSync6(file, mergeEnvFile(existing, updates));
   try {
     chmodSync2(file, 384);
@@ -11853,7 +12804,7 @@ function guardEnvFile(fileArg) {
   const inRepo = git(["rev-parse", "--is-inside-work-tree"]);
   if (inRepo === "no-git") {
     const gi = resolve7(cwd, ".gitignore");
-    const text = existsSync7(gi) ? readFileSync7(gi, "utf8") : "";
+    const text = existsSync8(gi) ? readFileSync8(gi, "utf8") : "";
     return appendOrWarn(gitignoreCovers(text, fileArg));
   }
   if (inRepo !== 0) return void 0;
@@ -11874,9 +12825,9 @@ async function runMcpInstall() {
     client = clientFlag;
   } else {
     const hits = [];
-    if (existsSync7(resolve7(cwd, ".cursor"))) hits.push("cursor");
-    if (existsSync7(resolve7(cwd, ".vscode"))) hits.push("vscode");
-    if (existsSync7(resolve7(cwd, ".claude")) || existsSync7(resolve7(cwd, ".mcp.json"))) hits.push("claude");
+    if (existsSync8(resolve7(cwd, ".cursor"))) hits.push("cursor");
+    if (existsSync8(resolve7(cwd, ".vscode"))) hits.push("vscode");
+    if (existsSync8(resolve7(cwd, ".claude")) || existsSync8(resolve7(cwd, ".mcp.json"))) hits.push("claude");
     if (hits.length !== 1) {
       fail(hits.length === 0 ? "could not detect an editor in this directory \u2014 pass --client cursor|claude|vscode" : `multiple editor markers found (${hits.join(", ")}) \u2014 pass --client cursor|claude|vscode`);
     }
@@ -11889,7 +12840,7 @@ async function runMcpInstall() {
   }
   const t = resolve_target({ which: "prod", defaultBase: DEFAULT_BASE });
   const url = mcpUrlFor(t.baseUrl, process.env.VXIL_MCP_URL);
-  const target = configTarget(client, scope, { home: homedir2(), cwd, platform: process.platform });
+  const target = configTarget(client, scope, { home: homedir3(), cwd, platform: process.platform });
   const explicitKey = flag("key");
   const inline = needsInlineKey(client, scope);
   if (hasFlag("print")) {
@@ -11977,7 +12928,7 @@ hint: ${e.hint}` : ""}`);
     return;
   }
   const ref = keyRef(client, scope, key);
-  const existing = existsSync7(target.path) ? readFileSync7(target.path, "utf8") : null;
+  const existing = existsSync8(target.path) ? readFileSync8(target.path, "utf8") : null;
   let merged;
   try {
     merged = mergeMcpConfig(existing, { url, header: ref.header, ...ref.inputs ? { inputs: ref.inputs } : {} }, target.format, serverName);
@@ -11987,7 +12938,7 @@ hint: ${e.hint}` : ""}`);
   }
   let guardNote;
   if (client === "cursor" && scope === "project") guardNote = guardEnvFile(".cursor/mcp.json");
-  mkdirSync5(dirname4(target.path), { recursive: true });
+  mkdirSync5(dirname5(target.path), { recursive: true });
   writeFileSync6(target.path, merged);
   if (inline) {
     try {
@@ -12106,7 +13057,7 @@ async function runFunctionsDev(name) {
     });
   });
   let timer2 = null;
-  const watcher = watch(dirname4(entry), () => {
+  const watcher = watch(dirname5(entry), () => {
     if (timer2) clearTimeout(timer2);
     timer2 = setTimeout(() => {
       void (async () => {
@@ -12211,7 +13162,7 @@ ${migrateUsage()}`);
     const { api } = requireApi(selector(), dryRun ? {} : { write: `migrate payments --from-provider ${provider}` });
     const report = await runPaymentsSync({ api, cwd, log }, {
       provider,
-      ...customersFile ? { customers: parseCustomersCsv(readFileSync7(resolve7(cwd, customersFile), "utf8")) } : {},
+      ...customersFile ? { customers: parseCustomersCsv(readFileSync8(resolve7(cwd, customersFile), "utf8")) } : {},
       ...all ? { all: true } : {},
       ...dryRun ? { dryRun: true } : {}
     });