@vxil/cli 0.1.0

package/dist/vxil.js

@@ -0,0 +1,4197 @@
+#!/usr/bin/env node
+
+// bin/vxil.ts
+import { writeFileSync as writeFileSync3, mkdirSync as mkdirSync2, existsSync as existsSync3, appendFileSync, readFileSync as readFileSync2, chmodSync as chmodSync2 } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { resolve as resolve4, dirname as dirname2 } from "node:path";
+import { createInterface } from "node:readline";
+import { watch } from "node:fs";
+import { createServer } from "node:http";
+import { hostname } from "node:os";
+
+// src/lib.ts
+import { pathToFileURL, fileURLToPath } from "node:url";
+import { resolve, dirname, basename } from "node:path";
+import { existsSync, writeFileSync, rmSync } from "node:fs";
+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") } : {} }];
+  if (t === "cmsHook" || t === "cms-hook") {
+    return [{
+      kind: "cmsHook",
+      ...str("collection") ? { collection: str("collection") } : {},
+      ...str("event") ? { event: str("event") } : {}
+    }];
+  }
+  if (t === "authHook" || t === "auth-hook") {
+    return [{ kind: "authHook", ...str("event") ? { event: str("event") } : {} }];
+  }
+  return [{ kind: "http", ...str("path") ? { path: str("path") } : {} }];
+}
+var CONFIG_FILENAMES = ["vxil.config.ts", "vxil.config.mjs", "vxil.config.js"];
+function monorepoConfigAlias() {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const src = resolve(here, "..", "..", "config", "src", "index.ts");
+    if (existsSync(src)) return { "vxil/config": src, "@vxil/config": src };
+  } catch {
+  }
+  return {};
+}
+async function importConfigModule(file) {
+  if (!file.endsWith(".ts")) {
+    return await import(pathToFileURL(file).href);
+  }
+  const esbuild = await import("esbuild");
+  const result = await esbuild.build({
+    entryPoints: [file],
+    bundle: true,
+    format: "esm",
+    platform: "node",
+    target: "es2022",
+    write: false,
+    packages: "external",
+    // keep vxil/config etc. external → resolved at runtime
+    alias: monorepoConfigAlias(),
+    // …except in-monorepo, where it is inlined
+    absWorkingDir: dirname(file)
+  });
+  const out = result.outputFiles?.[0];
+  if (!out) throw new Error("esbuild produced no output for the config");
+  const tmp = resolve(dirname(file), `.${basename(file, ".ts")}.${Date.now().toString(36)}.mjs`);
+  writeFileSync(tmp, out.text);
+  try {
+    return await import(pathToFileURL(tmp).href);
+  } finally {
+    rmSync(tmp, { force: true });
+  }
+}
+async function loadVxilConfig(cwd = process.cwd()) {
+  const found = CONFIG_FILENAMES.map((n) => resolve(cwd, n)).find((f) => existsSync(f));
+  if (!found) {
+    throw new Error(
+      "no vxil.config.ts (or .mjs/.js) found in this directory \u2014 run `vxil init` to scaffold one."
+    );
+  }
+  let mod;
+  try {
+    mod = await importConfigModule(found);
+  } catch (e) {
+    const msg = e.message;
+    let hint = "";
+    if (/Cannot find (package|module) '?(vxil\/config|@vxil\/config)/.test(msg)) {
+      hint = "\n  \u2192 install the CLI, which provides `vxil/config`: `npm i -D vxil` (or, in the monorepo, ensure the workspace is linked).";
+    } else if (/Unknown file extension ".ts"|ERR_UNKNOWN_FILE_EXTENSION/.test(msg)) {
+      hint = "\n  \u2192 vxil.config.ts needs the tsx runtime; run via `npx vxil` (the bin uses tsx) or rename to .mjs.";
+    } else if (/SyntaxError|is not defined|Unexpected/.test(msg)) {
+      hint = "\n  \u2192 vxil.config.ts has a syntax/reference error (it is executed to produce the manifest); fix it and retry.";
+    }
+    throw new Error(`failed to load ${found}: ${msg}${hint}`);
+  }
+  const def = mod.default;
+  if (!def || typeof def !== "object") {
+    throw new Error(
+      `${found} has no object default export. Expected:
+  import { defineConfig } from '@vxil/config';
+  export default defineConfig({ features: { \u2026 }, cms: { \u2026 }, functions: { \u2026 } });`
+    );
+  }
+  const cfg = def;
+  cfg.features ??= {};
+  if (typeof cfg.features !== "object") {
+    throw new Error(`${found}: \`features\` must be an object`);
+  }
+  if (typeof cfg.apiVersion === "string") loadedConfigApiVersion = cfg.apiVersion;
+  return cfg;
+}
+function diffManifest(prev, next, prefix = "") {
+  const out = [];
+  const keys = /* @__PURE__ */ new Set([...Object.keys(prev ?? {}), ...Object.keys(next ?? {})]);
+  for (const k of [...keys].sort()) {
+    const p = prev?.[k];
+    const n = next?.[k];
+    const path = prefix ? `${prefix}.${k}` : k;
+    const bothObjects = p && n && typeof p === "object" && typeof n === "object" && !Array.isArray(p) && !Array.isArray(n);
+    if (bothObjects) {
+      out.push(...diffManifest(p, n, path));
+    } else if (JSON.stringify(p) !== JSON.stringify(n)) {
+      out.push({ path, from: p, to: n });
+    }
+  }
+  return out;
+}
+function formatDiff(changes) {
+  if (!changes.length) return "  (no changes)";
+  return changes.map(({ path, from, to }) => {
+    if (from === void 0) return `  + ${path} = ${JSON.stringify(to)}`;
+    if (to === void 0) return `  - ${path} (was ${JSON.stringify(from)})`;
+    return `  ~ ${path}: ${JSON.stringify(from)} \u2192 ${JSON.stringify(to)}`;
+  }).join("\n");
+}
+var loadedConfigApiVersion;
+function resolveApiVersion(configVersion) {
+  const env = process.env.VXIL_API_VERSION?.trim();
+  return env || configVersion || loadedConfigApiVersion || "v1";
+}
+function applyApiVersion(path, version) {
+  if (version === "v1") return path;
+  const m = /^\/v1(\/.*)?$/.exec(path);
+  return m ? `/${version}${m[1] ?? ""}` : path;
+}
+function makeApi({ apiKey, baseUrl, fetchImpl = fetch, retries = 4, sleep, apiVersion }) {
+  const wait = sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  return async function api(method, path, body, headers = {}) {
+    const versionedPath = applyApiVersion(path, resolveApiVersion(apiVersion));
+    for (let attempt = 0; ; attempt++) {
+      const res = await fetchImpl(`${baseUrl.replace(/\/$/, "")}${versionedPath}`, {
+        method,
+        headers: {
+          authorization: `Bearer ${apiKey}`,
+          ...body !== void 0 ? { "content-type": "application/json" } : {},
+          "x-vxil-surface": "cli",
+          ...headers
+        },
+        ...body !== void 0 ? { body: JSON.stringify(body) } : {}
+      });
+      if (res.status === 429 && attempt < retries) {
+        const ra = Number(res.headers.get("retry-after"));
+        await wait((Number.isFinite(ra) && ra > 0 ? ra : Math.min(2 ** attempt, 8)) * 1e3);
+        continue;
+      }
+      const text = await res.text();
+      let json2;
+      try {
+        json2 = JSON.parse(text);
+      } catch {
+        json2 = { error: { code: `http_${res.status}`, message: text.slice(0, 200) } };
+      }
+      return { status: res.status, body: json2 };
+    }
+  };
+}
+async function mapPool(items, limit, fn) {
+  const out = new Array(items.length);
+  let next = 0;
+  const worker = async () => {
+    for (; ; ) {
+      const i = next++;
+      if (i >= items.length) return;
+      out[i] = await fn(items[i], i);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, worker));
+  return out;
+}
+function assembleApplyBundle(cfg, fnSources) {
+  const { functions: _fnFeature, ...configFeatures } = cfg.features;
+  void _fnFeature;
+  const functions = Object.entries(cfg.functions ?? {}).map(([name, def]) => {
+    const source = fnSources[name];
+    if (source === void 0) throw new Error(`functions: no bundled source for '${name}'`);
+    const bindings = lowerTriggerBindings(def.trigger);
+    return {
+      name,
+      source,
+      trigger: def.trigger?.kind ?? "http",
+      ...bindings.length ? { bindings } : {},
+      ...def.signature ? { signature: def.signature } : {},
+      ...def.scopes ? { scopes: def.scopes } : {},
+      ...def.egressAllow ? { egressAllow: def.egressAllow } : {},
+      ...def.secrets ? { secrets: def.secrets } : {}
+    };
+  });
+  return {
+    ...Object.keys(configFeatures).length ? { features: configFeatures } : {},
+    ...cfg.cms?.collections && Object.keys(cfg.cms.collections).length ? { cms: { collections: cfg.cms.collections } } : {},
+    ...functions.length ? { functions } : {}
+  };
+}
+var STEP_GLYPH = {
+  pending: "\xB7",
+  done: "\u2713",
+  failed: "\u2717",
+  skipped: "=",
+  rolled_back: "\u21A9",
+  kept: "\u2248"
+};
+function formatApplySteps(steps) {
+  if (!steps.length) return "  (no steps)";
+  return steps.map((s) => {
+    const tail = s.error ? ` \u2014 ${s.error}` : s.note ? ` \u2014 ${s.note}` : "";
+    return `  ${STEP_GLYPH[s.status] ?? "?"} [${s.status}] ${s.kind} ${s.target}${tail}`;
+  }).join("\n");
+}
+function applyEnvelope(r, what) {
+  if (r.body.error || r.status >= 400) {
+    const e = r.body.error ?? {};
+    throw new Error(`${what} failed: ${e.code ?? r.status} ${e.message ?? ""} ${e.hint ?? ""}`.trim());
+  }
+  return r.body.data;
+}
+async function serverApply({ api, bundle, resume, allowDestructive, onPlan }) {
+  if (resume) {
+    return applyEnvelope(await api("POST", "/v1/apply", { apply_id: resume, mode: "apply" }), "apply resume");
+  }
+  if (!bundle) throw new Error("serverApply needs a bundle (or a resume id)");
+  const plan = applyEnvelope(
+    await api("POST", "/v1/apply", { bundle, mode: "plan", ...allowDestructive ? { allow_destructive: true } : {} }),
+    "apply plan"
+  );
+  onPlan?.(plan);
+  return applyEnvelope(
+    await api("POST", "/v1/apply", { apply_id: plan.apply_id, mode: "apply" }),
+    `apply execute (resume with: vxil push --server --resume ${plan.apply_id})`
+  );
+}
+async function planOrPush({ api, features, apply }) {
+  const results = [];
+  for (const [feature, manifest] of Object.entries(features)) {
+    const dry = await api("PUT", `/v1/config/${feature}?dry_run=true`, manifest);
+    if (dry.status !== 200) {
+      const e = dry.body.error ?? {};
+      throw new Error(
+        `invalid config for ${feature}: ${e.code ?? dry.status} ${e.message ?? ""} ${e.hint ?? ""}`
+      );
+    }
+    const effective = dry.body.data?.manifest;
+    const cur = await api("GET", `/v1/config/${feature}`);
+    const exists = cur.status === 200;
+    const remote = exists ? cur.body.data?.manifest : {};
+    const version = exists ? cur.body.data?.version ?? 0 : 0;
+    const changes = diffManifest(remote, effective);
+    let applied = null;
+    if (apply && changes.length) {
+      const put = await api(
+        "PUT",
+        `/v1/config/${feature}`,
+        manifest,
+        exists ? { "if-match": String(version) } : {}
+      );
+      if (put.status !== 200) {
+        const e = put.body.error ?? {};
+        throw new Error(`push failed for ${feature}: ${e.code ?? put.status} ${e.message ?? ""} ${e.hint ?? ""}`);
+      }
+      applied = put.body.data?.version ?? null;
+    }
+    results.push({ feature, version, changes, applied });
+  }
+  return results;
+}
+
+// src/cms.ts
+function fieldToInput(name, def) {
+  const out = { field: name, type: def.type };
+  if (def.required !== void 0) out.required = def.required;
+  if (def.validation !== void 0) out.validation = def.validation;
+  if (def.indexSlot !== void 0) out.index_slot = def.indexSlot;
+  if (def.relationTo !== void 0) out.relation_to = def.relationTo;
+  if (def.computed !== void 0) out.computed = def.computed;
+  if (def.compute !== void 0) out.compute = def.compute;
+  return out;
+}
+async function readRemote(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 ?? [];
+  for (const c of cols) map.set(c.collection, { collection: c.collection, fields: c.fields ?? [] });
+  return map;
+}
+async function planCmsSchema({ api, collections, apply, allowDestructive = false }) {
+  const remote = await readRemote(api);
+  const changes = [];
+  for (const [name, def] of Object.entries(collections)) {
+    const declaredFields = Object.entries(def.fields ?? {});
+    const rc = remote.get(name);
+    if (!rc) {
+      changes.push({
+        collection: name,
+        kind: "create-collection",
+        detail: `collection ${name} (${declaredFields.length} fields)`
+      });
+      continue;
+    }
+    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})` });
+      } else if (existing.type !== fd.type) {
+        changes.push({
+          collection: name,
+          kind: "destructive",
+          op: "alter-field",
+          field: fn,
+          detail: `${name}.${fn} type ${existing.type} \u2192 ${fd.type} (destructive alter)`
+        });
+      }
+    }
+    for (const f of rc.fields) {
+      if (!Object.prototype.hasOwnProperty.call(def.fields ?? {}, f.field)) {
+        changes.push({
+          collection: name,
+          kind: "destructive",
+          op: "drop-field",
+          field: f.field,
+          detail: `${name}.${f.field} present remotely, absent in config (destructive drop)`
+        });
+      }
+    }
+  }
+  if (allowDestructive) {
+    for (const rname of remote.keys()) {
+      if (!Object.prototype.hasOwnProperty.call(collections, rname)) {
+        changes.push({
+          collection: rname,
+          kind: "destructive",
+          op: "drop-collection",
+          detail: `collection ${rname} present remotely, absent in config (destructive drop)`
+        });
+      }
+    }
+  }
+  const destructive = changes.filter((c) => c.kind === "destructive");
+  if (apply && destructive.length && !allowDestructive) {
+    throw new Error(
+      `cms: ${destructive.length} destructive schema change(s) refused \u2014 re-run with --allow-destructive to apply (stored item data is retained; only the definition is dropped):
+` + destructive.map((c) => `  ! ${c.detail}`).join("\n")
+    );
+  }
+  let applied = 0;
+  if (apply) {
+    for (const c of changes) {
+      if (c.kind === "create-collection") {
+        const def = collections[c.collection];
+        const fields = Object.entries(def.fields ?? {}).map(([fn, fd]) => fieldToInput(fn, fd));
+        const body = { collection: c.collection, fields };
+        if (def.singular) body.singular = def.singular;
+        if (def.ownerField) body.owner_field = def.ownerField;
+        const res = await api("POST", "/v1/cms/collections", body);
+        if (res.status !== 201 && res.status !== 200 && res.body.error?.code !== "collection_exists") {
+          const e = res.body.error ?? {};
+          throw new Error(`cms: create ${c.collection} failed: ${e.code ?? res.status} ${e.message ?? ""}`);
+        }
+        applied++;
+      } else if (c.kind === "add-field") {
+        const fd = collections[c.collection].fields[c.field];
+        const res = await api("POST", `/v1/cms/collections/${encodeURIComponent(c.collection)}/fields`, fieldToInput(c.field, fd));
+        if (res.status !== 201 && res.status !== 200 && res.body.error?.code !== "already_exists") {
+          const e = res.body.error ?? {};
+          throw new Error(`cms: add ${c.collection}.${c.field} failed: ${e.code ?? res.status} ${e.message ?? ""}`);
+        }
+        applied++;
+      } else if (c.kind === "destructive") {
+        applied += await applyDestructive(api, collections, c);
+      }
+    }
+  }
+  return { changes, applied };
+}
+async function applyDestructive(api, collections, c) {
+  const ok2xx = (status) => status >= 200 && status < 300;
+  if (c.op === "drop-collection") {
+    const res2 = await api("POST", "/v1/cms/collections", { drop_collection: c.collection, allow_destructive: true });
+    if (!ok2xx(res2.status) && res2.body.error?.code !== "not_found") {
+      const e = res2.body.error ?? {};
+      throw new Error(`cms: drop collection ${c.collection} failed: ${e.code ?? res2.status} ${e.message ?? ""}`);
+    }
+    return 1;
+  }
+  const path = `/v1/cms/collections/${encodeURIComponent(c.collection)}/fields`;
+  if (c.op === "drop-field") {
+    const res2 = await api("POST", path, { drop_field: c.field, allow_destructive: true });
+    if (!ok2xx(res2.status) && res2.body.error?.code !== "not_found") {
+      const e = res2.body.error ?? {};
+      throw new Error(`cms: drop ${c.collection}.${c.field} 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)) {
+    const e = res.body.error ?? {};
+    throw new Error(`cms: alter ${c.collection}.${c.field} failed: ${e.code ?? res.status} ${e.message ?? ""}`);
+  }
+  return 1;
+}
+function formatCmsChanges(changes) {
+  if (!changes.length) return "  (no cms-schema changes)";
+  return changes.map((c) => {
+    if (c.kind === "destructive") return `  ! ${c.detail}`;
+    return `  + ${c.detail}`;
+  }).join("\n");
+}
+
+// src/functions.ts
+import { resolve as resolve2, relative, isAbsolute, sep } from "node:path";
+import { createHash } from "node:crypto";
+var MAX_SOURCE_BYTES = 256e3;
+function sourceSha12(source) {
+  return createHash("sha256").update(source, "utf8").digest("hex").slice(0, 12);
+}
+function escapesRoot(root, path) {
+  const rel = relative(root, path);
+  return rel.startsWith("..") || isAbsolute(rel);
+}
+function assertBundleContained(projectRoot, inputs) {
+  const root = resolve2(projectRoot);
+  for (const input of inputs) {
+    const abs = resolve2(root, input);
+    if (!escapesRoot(root, abs)) continue;
+    if (abs.split(sep).includes("node_modules")) 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`
+    );
+  }
+}
+async function bundleFunction(entryPath, opts = {}) {
+  const root = resolve2(opts.projectRoot ?? process.cwd());
+  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`
+    );
+  }
+  const esbuild = await import("esbuild");
+  const result = await esbuild.build({
+    entryPoints: [entry],
+    bundle: true,
+    format: "esm",
+    platform: "browser",
+    // Workers runtime (Web-standard globals; no node builtins)
+    target: "es2022",
+    write: false,
+    legalComments: "none",
+    absWorkingDir: root,
+    metafile: true,
+    // drives the import-containment check below (non-executing)
+    plugins: []
+    // explicitly none — build plugins are code execution
+  });
+  const out = result.outputFiles?.[0];
+  if (!out) throw new Error(`esbuild produced no output for ${entryPath}`);
+  assertBundleContained(root, Object.keys(result.metafile?.inputs ?? {}));
+  const source = out.text;
+  const bytes = Buffer.byteLength(source, "utf8");
+  if (bytes > MAX_SOURCE_BYTES) {
+    throw new Error(`bundled ${entryPath} is ${Math.round(bytes / 1e3)} KB \u2014 exceeds the ${MAX_SOURCE_BYTES / 1e3} KB deploy cap`);
+  }
+  return { source, bytes };
+}
+function stableStringify(v) {
+  if (Array.isArray(v)) return `[${v.map(stableStringify).join(",")}]`;
+  if (v !== null && typeof v === "object") {
+    const o = v;
+    return `{${Object.keys(o).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(o[k])}`).join(",")}}`;
+  }
+  return JSON.stringify(v) ?? "undefined";
+}
+function normalizeSecretRefs(refs) {
+  const out = [];
+  for (const raw of refs ?? []) {
+    const s = String(raw);
+    const canonical = s.startsWith("secret:") ? s : `secret:${s}`;
+    if (!out.includes(canonical)) out.push(canonical);
+  }
+  return out;
+}
+async function readRemote2(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 ?? [];
+  for (const f of fns) {
+    map.set(f.name, {
+      scriptRef: f.scriptRef ?? "",
+      secrets: f.secrets ?? [],
+      bindings: f.bindings ?? [],
+      signature: f.signature ?? null
+    });
+  }
+  return map;
+}
+function sameSecretSet(a, b) {
+  return a.length === b.length && a.every((x) => b.includes(x));
+}
+async function planFunctions({ api, functions, cwd, apply }) {
+  const remote = await readRemote2(api);
+  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}$/)`);
+    }
+    const { source, bytes } = await bundleFunction(resolve2(cwd, def.entry), { projectRoot: cwd });
+    const triggerKind = def.trigger?.kind ?? "http";
+    const secrets = normalizeSecretRefs(def.secrets);
+    const bindings = lowerTriggerBindings(def.trigger);
+    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) && stableStringify(remoteFn.bindings) === stableStringify(bindings) && stableStringify(remoteFn.signature) === stableStringify(def.signature ?? null)) {
+      return { change: { name, kind: "unchanged", detail: label }, applied: 0, cmsHooks: null };
+    }
+    const change = { name, kind: remoteFn === void 0 ? "deploy-new" : "deploy-update", detail: label };
+    if (apply) {
+      const body = { source, trigger: triggerKind, secrets };
+      if (bindings.length) body.bindings = bindings;
+      if (def.signature) body.signature = def.signature;
+      if (def.scopes) body.scopes = def.scopes;
+      if (def.egressAllow) body.egressAllow = def.egressAllow;
+      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 };
+    }
+    return { change, applied: 0, cmsHooks: 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 };
+  }, null);
+  return { changes, applied, cmsHookSubscriptions };
+}
+function formatFnChanges(changes) {
+  const actionable = changes.filter((c) => c.kind !== "unchanged");
+  if (!actionable.length) return "  (no function changes)";
+  return actionable.map((c) => `  ${c.kind === "deploy-new" ? "+" : "~"} ${c.detail}`).join("\n");
+}
+function formatLogLines(lines) {
+  const out = [];
+  for (const l of lines) {
+    const wall = typeof l.wall_ms === "number" ? ` ${l.wall_ms}ms` : "";
+    if (!l.logs?.length && !l.exceptions?.length) {
+      out.push(`${l.ts}  ${l.outcome}${wall}`);
+      continue;
+    }
+    for (const g of l.logs ?? []) out.push(`${l.ts}  ${(g.level || "log").padEnd(5)} ${g.message}`);
+    for (const e of l.exceptions ?? []) out.push(`${l.ts}  error ${e.name}: ${e.message}`);
+  }
+  return out.length ? out.join("\n") : "  (no log lines)";
+}
+
+// ../runtime/src/egress.ts
+function isPrivateIPv4(host) {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  if (!m) return false;
+  const o = m.slice(1).map(Number);
+  if (o.some((n) => n > 255)) return false;
+  const [a, b] = o;
+  return a === 10 || // 10.0.0.0/8        RFC1918
+  a === 172 && b >= 16 && b <= 31 || // 172.16.0.0/12 RFC1918
+  a === 192 && b === 168 || // 192.168.0.0/16   RFC1918
+  a === 127 || // 127.0.0.0/8       loopback
+  a === 169 && b === 254 || // 169.254.0.0/16   link-local (incl. metadata)
+  a === 100 && b >= 64 && b <= 127 || // 100.64.0.0/10 CGNAT / shared
+  a === 0 || // 0.0.0.0/8         "this host"
+  a >= 224;
+}
+function expandIPv6(host) {
+  if (!/^[0-9a-f:.]+$/.test(host) || !host.includes(":")) return null;
+  let h = host;
+  let tail = [];
+  const lastColon = h.lastIndexOf(":");
+  const maybeV4 = h.slice(lastColon + 1);
+  if (maybeV4.includes(".")) {
+    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(maybeV4);
+    if (!m) return null;
+    const q = m.slice(1).map(Number);
+    if (q.some((n) => n > 255)) return null;
+    tail = [q[0] << 8 | q[1], q[2] << 8 | q[3]];
+    h = h.slice(0, lastColon + 1) + "0:0";
+  }
+  const parts = h.split("::");
+  if (parts.length > 2) return null;
+  const head = parts[0] ? parts[0].split(":") : [];
+  const rest2 = parts.length === 2 ? parts[1] ? parts[1].split(":") : [] : null;
+  let groups;
+  if (rest2 === null) {
+    groups = head;
+  } else {
+    const fill = 8 - head.length - rest2.length - tail.length;
+    if (fill < 0) return null;
+    groups = [...head, ...Array(fill).fill("0"), ...rest2];
+  }
+  const nums = groups.map((g) => g === "" ? 0 : parseInt(g, 16));
+  const all = [...nums, ...tail];
+  if (all.length !== 8 || all.some((n) => !Number.isFinite(n) || n < 0 || n > 65535)) {
+    return null;
+  }
+  return all.map((n) => n.toString(16));
+}
+function isPrivateIPv6(host) {
+  const hextets = expandIPv6(host);
+  if (!hextets) return false;
+  const n = hextets.map((x) => parseInt(x, 16));
+  const [h0, h1] = n;
+  if (n.every((x) => x === 0)) return true;
+  if (n.slice(0, 7).every((x) => x === 0) && n[7] === 1) return true;
+  if ((h0 & 65024) === 64512) return true;
+  if ((h0 & 65472) === 65152) return true;
+  if (n.slice(0, 5).every((x) => x === 0) && h0 === 0 && n[5] === 65535) {
+    const a = n[6] >> 8 & 255;
+    const b = n[6] & 255;
+    const c = n[7] >> 8 & 255;
+    const d = n[7] & 255;
+    return isPrivateIPv4(`${a}.${b}.${c}.${d}`);
+  }
+  if (h0 === 100 && h1 === 65435) {
+    const a = n[6] >> 8 & 255;
+    const b = n[6] & 255;
+    const c = n[7] >> 8 & 255;
+    const d = n[7] & 255;
+    return isPrivateIPv4(`${a}.${b}.${c}.${d}`);
+  }
+  return false;
+}
+var VXIL_API_HOSTS = /* @__PURE__ */ new Set(["api.vxil.com", "api.vxil.org"]);
+function egressDecision(targetUrl, allowHosts = []) {
+  let u;
+  try {
+    u = new URL(targetUrl);
+  } catch {
+    return { allow: false, reason: "invalid-url" };
+  }
+  if (u.protocol !== "https:") return { allow: false, reason: `non-https:${u.protocol}` };
+  if (u.username !== "" || u.password !== "") return { allow: false, reason: "embedded-credentials" };
+  const host = u.hostname.toLowerCase().replace(/^\[/, "").replace(/\]$/, "").replace(/\.$/, "");
+  if (host === "") return { allow: false, reason: "empty-host" };
+  if (isPrivateIPv4(host) || isPrivateIPv6(host)) return { allow: false, reason: `private-ip:${host}` };
+  if (host === "localhost" || host.endsWith(".localhost") || host === "metadata.google.internal" || host.endsWith(".internal") || host.endsWith(".local")) {
+    return { allow: false, reason: `internal-host:${host}` };
+  }
+  if (host.endsWith(".workers.dev")) return { allow: false, reason: `sibling-worker:${host}` };
+  if (VXIL_API_HOSTS.has(host)) return { allow: true, reason: "vxil-api" };
+  for (const a of allowHosts) {
+    const h = a.toLowerCase().trim();
+    if (h && (host === h || host.endsWith("." + h))) return { allow: true, reason: `allowlist:${h}` };
+  }
+  return { allow: false, reason: `not-allowlisted:${host}` };
+}
+
+// src/fnDev.ts
+var SCOPE_AUD = {
+  cms: "cms",
+  payments: "payments",
+  notifications: "notifications",
+  comments: "comments",
+  files: "files",
+  ai: "ai",
+  rag: "rag",
+  search: "vector-search",
+  vector: "vector-search",
+  feeds: "activity-feed",
+  orgs: "orgs",
+  auth: "auth",
+  jobs: "jobs",
+  realtime: "realtime",
+  "rate-limits": "rate-limits"
+};
+function audsForScopes(scopes) {
+  const auds = /* @__PURE__ */ new Set();
+  for (const s of scopes) {
+    const a = SCOPE_AUD[s.split(":")[0] ?? ""];
+    if (a) auds.add(a);
+  }
+  return auds;
+}
+var DEV_VXIL_BASE = "https://api.vxil.org";
+var PLACEHOLDER_PREFIX = "vxil-dev-placeholder.";
+function buildEnvelope(opts) {
+  const scopedJwts = {};
+  for (const aud of audsForScopes(opts.scopes)) scopedJwts[aud] = `${PLACEHOLDER_PREFIX}${aud}`;
+  return {
+    trigger: "http",
+    tenant_id: opts.tenantId,
+    request_id: opts.requestId,
+    idempotency_key: opts.idempotencyKey ?? opts.requestId,
+    vxil_base: DEV_VXIL_BASE,
+    scoped_jwts: scopedJwts,
+    secrets: opts.secrets ?? {},
+    payload: opts.payload
+  };
+}
+function audForPath(pathname) {
+  const seg = (p) => pathname === `/v1/${p}` || pathname.startsWith(`/v1/${p}/`);
+  if (seg("users") || seg("tenants") || seg("config") || pathname === "/v1/features" || pathname === "/v1/audit" || pathname.startsWith("/v1/audit/") || pathname.startsWith("/v1/webhooks/subscriptions") || seg("functions")) return "control-plane";
+  if (seg("fn")) return "functions";
+  if (seg("notifications")) return "notifications";
+  if (seg("jobs")) return "jobs";
+  if (seg("auth")) return "auth";
+  if (seg("rate-limits")) return "rate-limits";
+  if (seg("files")) return "files";
+  if (seg("comments")) return "comments";
+  if (seg("dm")) return "comments";
+  if (seg("cms")) return "cms";
+  if (seg("realtime")) return "realtime";
+  if (seg("orgs")) return "orgs";
+  if (seg("feeds")) return "activity-feed";
+  if (seg("search")) return "vector-search";
+  if (seg("ai")) return "ai";
+  if (seg("rag")) return "rag";
+  if (seg("payments")) return "payments";
+  if (pathname.startsWith("/v1/webhooks/sources") || pathname.startsWith("/v1/webhooks/events") || pathname.startsWith("/v1/webhooks/inbound/")) return "webhooks";
+  return null;
+}
+function resolveDevSecrets(refs, env) {
+  const secrets = {};
+  const missing = [];
+  for (const raw of refs ?? []) {
+    const name = String(raw).replace(/^secret:/, "");
+    const value = env[`VXIL_FN_SECRET_${name.toUpperCase()}`];
+    if (value === void 0) missing.push(name);
+    else secrets[name] = value;
+  }
+  return { secrets, missing };
+}
+function json(body, status, headers = {}) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json", ...headers }
+  });
+}
+var EDGE_FORWARD_HEADERS = ["content-type", "accept", "if-match", "idempotency-key"];
+function makeDevOutbound(opts) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const log = opts.log ?? (() => {
+  });
+  const impliedAuds = audsForScopes(opts.scopes);
+  return async (req) => {
+    let url;
+    try {
+      url = new URL(req.url);
+    } catch {
+      return json({ error: "egress_blocked", reason: "invalid-url", host: "", fn: opts.fnName }, 403, { "x-vxil-egress": "blocked" });
+    }
+    const decision = egressDecision(req.url, opts.egressAllow);
+    if (decision.allow && decision.reason === "vxil-api") {
+      const aud = audForPath(url.pathname);
+      if (!aud) {
+        return json({ error: { code: "not_found", message: `the edge does not route ${url.pathname}.` } }, 404);
+      }
+      if (!impliedAuds.has(aud)) {
+        log(`\u2717 scope clamp: ${url.pathname} needs the '${aud}' feature, but '${opts.fnName}' is scoped [${opts.scopes.join(", ") || "none"}]`);
+        return json({
+          error: {
+            code: "scope_clamp",
+            message: `function '${opts.fnName}' is not scoped for the '${aud}' feature (path ${url.pathname}).`,
+            hint: aud === "functions" ? "fn\u2192fn calls are never allowed (no recursion), locally or deployed." : `add a '${aud}'-implying scope to functions.${opts.fnName}.scopes in vxil.config.ts and redeploy \u2014 the deployed dispatcher enforces the same clamp.`
+          }
+        }, 403);
+      }
+      const target = `${opts.edgeUrl.replace(/\/$/, "")}${url.pathname}${url.search}`;
+      const headers = new Headers();
+      for (const h of EDGE_FORWARD_HEADERS) {
+        const v = req.headers.get(h);
+        if (v) headers.set(h, v);
+      }
+      headers.set("authorization", `Bearer ${opts.apiKey}`);
+      headers.set("x-vxil-surface", "cli-fn-dev");
+      const method2 = req.method.toUpperCase();
+      const body2 = method2 === "GET" || method2 === "HEAD" ? void 0 : await req.arrayBuffer();
+      return fetchImpl(target, { method: method2, headers, ...body2 !== void 0 ? { body: body2 } : {} });
+    }
+    if (!decision.allow) {
+      log(`\u2717 egress blocked: ${url.hostname} (${decision.reason}) \u2014 add it to functions.${opts.fnName}.egressAllow if intended`);
+      return json({
+        error: "egress_blocked",
+        reason: decision.reason,
+        host: url.hostname,
+        fn: opts.fnName,
+        hint: "A vxil function may only reach api.vxil.* or a host on its declared egressAllow."
+      }, 403, { "x-vxil-egress": "blocked" });
+    }
+    const method = req.method.toUpperCase();
+    const body = method === "GET" || method === "HEAD" ? void 0 : await req.arrayBuffer();
+    return fetchImpl(req.url, { method, headers: req.headers, ...body !== void 0 ? { body } : {} });
+  };
+}
+
+// src/gen.ts
+function tsTypeFor(fieldType) {
+  switch (fieldType) {
+    case "string":
+    case "text":
+      return "string";
+    case "int":
+    case "float":
+      return "number";
+    case "bool":
+      return "boolean";
+    case "datetime":
+      return "string";
+    // ISO-8601
+    case "relation":
+    case "file":
+      return "string";
+    // related item_id / file id
+    case "json":
+    default:
+      return "unknown";
+  }
+}
+var META_SORTABLE = ["created_at", "updated_at", "published_at"];
+var CMS_STATUS_VALUES = ["draft", "published", "archived"];
+function slottedFields(c) {
+  return c.fields.filter((f) => f.index_slot);
+}
+function isFilterableField(f) {
+  return !(f.computed && !f.index_slot);
+}
+function filterTypeFor(f) {
+  const slot = f.index_slot ?? "";
+  if (slot.startsWith("s")) return "VxilFilterRangeText";
+  if (slot.startsWith("n")) return "VxilFilterRange<number>";
+  if (slot.startsWith("t")) return "VxilFilterRangeDatetime";
+  switch (tsTypeFor(f.type)) {
+    case "string":
+      return "VxilFilterEqText";
+    case "number":
+      return "VxilFilterEq<number>";
+    case "boolean":
+      return "VxilFilterEq<boolean>";
+    default:
+      return "VxilFilterJson";
+  }
+}
+function quoteKey(k) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(k) ? k : JSON.stringify(k);
+}
+function unionOf(values) {
+  if (!values.length) return "never";
+  return values.map((v) => JSON.stringify(v)).join(" | ");
+}
+function collectionType(c) {
+  const lines = [];
+  const ind = "        ";
+  const rowFields = c.fields.map((f) => {
+    const t = tsTypeFor(f.type);
+    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);
+    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 slotted = slottedFields(c);
+  const sortable = unionOf([...slotted.map((f) => f.field), ...META_SORTABLE]);
+  const statusUnion = unionOf([...CMS_STATUS_VALUES]);
+  const filterLines = [
+    `${ind}/** reserved lifecycle filter (always available; 'archived' reserved by the DB CHECK; object form is $in-only \u2014 the server rejects {$eq: \u2026}) */`,
+    `${ind}$status: ${statusUnion} | { $in: (${statusUnion})[] };`,
+    ...c.fields.filter(isFilterableField).map((f) => `${ind}${quoteKey(f.field)}: ${filterTypeFor(f)};`)
+  ];
+  const filterable = `{
+${filterLines.join("\n")}
+      }`;
+  lines.push(`    ${quoteKey(c.collection)}: {`);
+  lines.push(`      Row: {
+${rowFields.join("\n")}
+      };`);
+  lines.push(`      Insert: {
+${insertFields.join("\n") || `${ind}/* (no insertable fields) */`}
+      };`);
+  lines.push(`      Patch: {
+${patchFields.join("\n") || `${ind}/* (no patchable fields) */`}
+      };`);
+  lines.push(`      Sortable: ${sortable};`);
+  lines.push(`      Filterable: ${filterable};`);
+  lines.push(`    };`);
+  return lines.join("\n");
+}
+function lowerSig(sig) {
+  if (sig == null) return "unknown";
+  if (typeof sig === "string") return sig.trim() || "unknown";
+  if (typeof sig === "object" && !Array.isArray(sig)) {
+    const fields = Object.entries(sig).map(([k, v]) => `${quoteKey(k)}: ${typeof v === "string" && v.trim() ? v.trim() : "unknown"}`);
+    return fields.length ? `{ ${fields.join("; ")} }` : "Record<string, never>";
+  }
+  return "unknown";
+}
+function functionType(f) {
+  return `    ${quoteKey(f.name)}: { Input: ${lowerSig(f.signature?.input)}; Output: ${lowerSig(f.signature?.output)} };`;
+}
+function apiVersionEntries(input) {
+  const map = input.apiVersions;
+  if (!map) return [];
+  return Object.entries(map).sort(([a], [b]) => a.localeCompare(b));
+}
+function generateTypes(input) {
+  const feats = [...input.features].sort();
+  const colls = [...input.collections].sort((a, b) => a.collection.localeCompare(b.collection));
+  const fns = [...input.functions].sort((a, b) => a.name.localeCompare(b.name));
+  const apiVers = apiVersionEntries(input);
+  const header = [
+    `// vxil.types.ts \u2014 GENERATED by \`vxil gen\`${input.generatedAt ? ` at ${input.generatedAt}` : ""}`,
+    `// Tenant: ${input.tenant ?? "(unknown)"}${input.env ? ` (${input.env})` : ""} \xB7 ${feats.length} features \xB7 ${colls.length} collections \xB7 ${fns.length} functions`,
+    // API-major line only when the backend reports api_versions (older backends
+    // omit it → header byte-identical). Compact `feature=major|major` list.
+    ...apiVers.length ? [`// API majors (pinned): ${apiVers.map(([f, v]) => `${f}=${v.join("|")}`).join(" \xB7 ")}`] : [],
+    "// DO NOT EDIT \u2014 re-run `vxil gen`.",
+    "/* eslint-disable */"
+  ].join("\n");
+  const apiVersionsBlock = apiVers.length ? `
+
+// The API majors this client was generated against (feature-versioning.md \xA7D10).
+// A new major on the backend surfaces here as \`vxil gen --check\` drift.
+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 fnBody = fns.length ? fns.map(functionType).join("\n") : "    // (no deployed functions)";
+  return `${header}
+
+export interface VxilSchema {
+  // (1) enabled features \u2192 the runtime narrows its namespaces to these keys
+  features: ${unionOf(feats)};
+
+  // (2) CMS collections, derived from GET /v1/cms/collections FieldDefs
+  cms: {
+${cmsBody}
+  };
+
+  // (3) deployed functions \u2192 typed invoke (Level 0: opaque until a signature is declared)
+  functions: {
+${fnBody}
+  };
+}${apiVersionsBlock}
+
+// Filter-operator aliases referenced by Filterable above. Ops mirror cms-v1
+// query.ts; multiple ops in one object AND-compose. Range ops ($ne/$gt/$gte/
+// $lt/$lte) require an index slot \u2014 the server leniently admits unslotted
+// ranges via unindexed JSONB scans, deliberately NOT typed here (escape hatch:
+// the untyped \`vx.cms.items.query\`). $in is typed on every slot family
+// (s*/n*/t*) \u2014 cms-v1 binds the bounded array with a per-family SQL cast.
+// Runtime caps not encodable in types:\u22648 filter terms, $in 1\u201350 elements, filter \u22642KB; $contains is an
+// ILIKE substring match. (Emitted BELOW the interface so \`vxil gen --check\`
+// drift-compares them; TS declarations hoist, so order never matters.)
+export type VxilFilterEq<T> = T | { $eq?: T; $in?: T[] };
+export type VxilFilterEqText = string | { $eq?: string; $in?: string[]; $contains?: string };
+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 };
+
+// Usage \u2014 narrow the client to THIS tenant's enabled features (a disabled feature
+// becomes a compile error):
+//   import { Vxil } from '@vxil/sdk';
+//   import type { VxilSchema } from './vxil.types';
+//   const vx = Vxil.connect<VxilSchema>({ apiKey: process.env.VXIL_API_KEY! });
+//   await vx.from('${colls[0]?.collection ?? "collection"}').create({ /* field-typed */ });
+`;
+}
+
+// ../../workers/mcp-v1/src/tools.ts
+var TOOLS = [
+  {
+    name: "users_upsert",
+    description: "Create or update an end-user in the tenant_users substrate. Call this before sending notifications to a new user. The id is your own opaque user identifier.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "Opaque end_user_id (your identifier, \u2264256 chars)." },
+        email: { type: "string", description: "Email address (required before email sends)." },
+        display_name: { type: "string" },
+        attributes: { type: "object", additionalProperties: true }
+      },
+      required: ["id"]
+    },
+    method: "POST",
+    path: "/v1/users"
+  },
+  {
+    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?).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        user_id: { type: "string", description: "Opaque end_user_id from tenant_users." },
+        template: { type: "string", enum: ["magic-link", "welcome", "transactional"] },
+        data: { type: "object", additionalProperties: true },
+        locale: { type: "string", default: "en-US" }
+      },
+      required: ["user_id", "template", "data"]
+    },
+    method: "POST",
+    path: "/v1/notifications/send"
+  },
+  {
+    name: "notifications_list_deliveries",
+    feature: "notifications",
+    description: "List recent notification deliveries with status (queued|sent|failed|suppressed). Filter by user_id or status.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        user_id: { type: "string" },
+        status: { type: "string", enum: ["queued", "sent", "failed", "suppressed"] },
+        limit: { type: "number", default: 20 }
+      }
+    },
+    method: "GET",
+    path: "/v1/notifications/deliveries",
+    queryArgs: ["user_id", "status", "limit"]
+  },
+  {
+    name: "jobs_enqueue",
+    feature: "jobs",
+    description: "Enqueue a background job: Vxil POSTs a signed callback to your https target_url with retries/backoff until 2xx. Verify X-Vxil-Jobs-Signature against jobs_get_signing_secret. idempotency_key dedups for 24h. deliver_after (ISO) / delay_seconds (\u2264 30 d, at most one) defer the first delivery; > 12 h returns state 'delayed'.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        job_name: { type: "string" },
+        target_url: { type: "string", description: "https:// endpoint Vxil will call" },
+        payload: { type: "object", additionalProperties: true },
+        idempotency_key: { type: "string" },
+        max_attempts: { type: "number", minimum: 1, maximum: 20 },
+        deliver_after: { type: "string", description: "future ISO timestamp (mutually exclusive with delay_seconds)" },
+        delay_seconds: { type: "number", minimum: 0, maximum: 2592e3 }
+      },
+      required: ["job_name", "target_url"]
+    },
+    method: "POST",
+    path: "/v1/jobs/enqueue"
+  },
+  {
+    name: "jobs_enqueue_batch",
+    feature: "jobs",
+    description: "Atomically enqueue up to 100 jobs in one call (one item invalid \u2192 422, nothing inserted). Each item = the jobs_enqueue input, incl. per-item idempotency_key and deliver_after/delay_seconds. Results align with input order.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        jobs: {
+          type: "array",
+          minItems: 1,
+          maxItems: 100,
+          items: {
+            type: "object",
+            properties: {
+              job_name: { type: "string" },
+              target_url: { type: "string" },
+              payload: { type: "object", additionalProperties: true },
+              idempotency_key: { type: "string" },
+              max_attempts: { type: "number", minimum: 1, maximum: 20 },
+              deliver_after: { type: "string" },
+              delay_seconds: { type: "number", minimum: 0, maximum: 2592e3 }
+            },
+            required: ["job_name", "target_url"]
+          }
+        }
+      },
+      required: ["jobs"]
+    },
+    method: "POST",
+    path: "/v1/jobs/enqueue-batch"
+  },
+  {
+    name: "jobs_list_runs",
+    feature: "jobs",
+    description: "List job runs (state machine: queued\u2192running\u2192succeeded | retrying\u2192dead | cancelled; delayed = scheduled future delivery, waiting = suspended on an event).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        job_name: { type: "string" },
+        state: { type: "string", enum: ["queued", "running", "retrying", "waiting", "delayed", "succeeded", "failed", "dead", "cancelled"] },
+        limit: { type: "number", default: 20 }
+      }
+    },
+    method: "GET",
+    path: "/v1/jobs/runs",
+    queryArgs: ["job_name", "state", "limit"]
+  },
+  {
+    name: "jobs_pause_schedule",
+    feature: "jobs",
+    description: "Pause an active schedule (stops firing; the row survives and can be resumed).",
+    inputSchema: {
+      type: "object",
+      properties: { schedule_id: { type: "string" } },
+      required: ["schedule_id"]
+    },
+    method: "POST",
+    path: (a) => `/v1/jobs/schedules/${encodeURIComponent(String(a.schedule_id))}/pause`
+  },
+  {
+    name: "jobs_resume_schedule",
+    feature: "jobs",
+    description: "Resume a paused schedule. Cron \u2192 next_run_at recomputes; one-shot with a lapsed run_at \u2192 409 run_at_passed. Re-checks the schedules.maxPerTenant cap.",
+    inputSchema: {
+      type: "object",
+      properties: { schedule_id: { type: "string" } },
+      required: ["schedule_id"]
+    },
+    method: "POST",
+    path: (a) => `/v1/jobs/schedules/${encodeURIComponent(String(a.schedule_id))}/resume`
+  },
+  {
+    name: "jobs_create_flow_rule",
+    feature: "jobs",
+    description: "Create a per-endpoint/job flow-control rule: rate_per_minute and/or max_parallel (at least one). match_kind 'endpoint' matches the target_url https ORIGIN (e.g. 'https://api.example.com'); 'job_name' matches exactly. Enforced by the executor; over-limit runs defer, never drop.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        match_kind: { type: "string", enum: ["endpoint", "job_name"] },
+        match_value: { type: "string" },
+        max_parallel: { type: "number", minimum: 1, maximum: 100 },
+        rate_per_minute: { type: "number", minimum: 1, maximum: 1e4 }
+      },
+      required: ["match_kind", "match_value"]
+    },
+    method: "POST",
+    path: "/v1/jobs/flow-rules"
+  },
+  {
+    name: "jobs_list_flow_rules",
+    feature: "jobs",
+    description: "List the tenant flow-control rules (rate + parallelism per endpoint/job).",
+    inputSchema: { type: "object", properties: {} },
+    method: "GET",
+    path: "/v1/jobs/flow-rules"
+  },
+  {
+    name: "jobs_delete_flow_rule",
+    feature: "jobs",
+    description: "Delete a flow-control rule (soft delete; enforcement stops within the executor round).",
+    inputSchema: {
+      type: "object",
+      properties: { rule_id: { type: "string" } },
+      required: ["rule_id"]
+    },
+    method: "DELETE",
+    path: (a) => `/v1/jobs/flow-rules/${encodeURIComponent(String(a.rule_id))}`
+  },
+  {
+    name: "jobs_create_schedule",
+    feature: "jobs",
+    description: "Create a recurring (5-field cron, UTC) or one-shot (run_at ISO) schedule that enqueues the job on the minute tick. Exactly one of cron/run_at.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        job_name: { type: "string" },
+        target_url: { type: "string" },
+        payload: { type: "object", additionalProperties: true },
+        cron: { type: "string", description: "e.g. '0 */6 * * *' (UTC)" },
+        run_at: { type: "string", description: "future ISO timestamp" }
+      },
+      required: ["job_name", "target_url"]
+    },
+    method: "POST",
+    path: "/v1/jobs/schedules"
+  },
+  {
+    name: "jobs_get_signing_secret",
+    feature: "jobs",
+    description: "Per-tenant secret your endpoints use to verify the X-Vxil-Jobs-Signature header on job callbacks.",
+    inputSchema: { type: "object", properties: {} },
+    method: "GET",
+    path: "/v1/jobs/signing-secret"
+  },
+  {
+    name: "rate_limits_create_policy",
+    feature: "rate-limits",
+    description: "Define a rate-limit policy. key_template vars like {ip} are supplied at check time; {tenant_id} is implicit. behavior 'block' \u2192 429 on exceed; 'shape' \u2192 200 with allowed=false.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        key_template: { type: "string", description: "e.g. '{tenant_id}:{ip}'" },
+        limit: { type: "number" },
+        window_seconds: { type: "number" },
+        behavior: { type: "string", enum: ["block", "shape"], default: "block" }
+      },
+      required: ["name", "key_template", "limit", "window_seconds"]
+    },
+    method: "POST",
+    path: "/v1/rate-limits/policies"
+  },
+  {
+    name: "rate_limits_list_policies",
+    feature: "rate-limits",
+    description: "List rate-limit policies.",
+    inputSchema: { type: "object", properties: {} },
+    method: "GET",
+    path: "/v1/rate-limits/policies"
+  },
+  {
+    name: "rate_limits_check",
+    feature: "rate-limits",
+    description: "Consume budget against a policy. Returns allowed/remaining/reset_seconds (429 on block-behavior exceed).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        policy_id: { type: "string" },
+        key_values: { type: "object", additionalProperties: { type: "string" } },
+        cost: { type: "number", default: 1 }
+      },
+      required: ["policy_id"]
+    },
+    method: "POST",
+    path: "/v1/rate-limits/check"
+  },
+  {
+    name: "rate_limits_create_override",
+    feature: "rate-limits",
+    description: "Add a per-identifier override on a policy. `pattern` matches the RENDERED key: an exact literal (e.g. 'tenant:user:42') wins outright; otherwise '*'-globs compete and the longest literal prefix wins (e.g. 'ip:10.*'). Unset fields fall through to the policy; an override may raise OR lower limit/window/behavior. Propagates to checks within \u226430s.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        policy_id: { type: "string" },
+        pattern: { type: "string", description: "rendered-key literal or '*'-glob, 1-300 chars" },
+        limit: { type: "number" },
+        window_seconds: { type: "number" },
+        behavior: { type: "string", enum: ["block", "shape"] },
+        note: { type: "string", description: "operator context, \u2264200 chars" }
+      },
+      required: ["policy_id", "pattern"]
+    },
+    method: "POST",
+    path: (a) => `/v1/rate-limits/policies/${encodeURIComponent(String(a.policy_id))}/overrides`
+  },
+  {
+    name: "rate_limits_list_overrides",
+    feature: "rate-limits",
+    description: "List a policy's per-identifier overrides (max 50 per policy).",
+    inputSchema: {
+      type: "object",
+      properties: { policy_id: { type: "string" } },
+      required: ["policy_id"]
+    },
+    method: "GET",
+    path: (a) => `/v1/rate-limits/policies/${encodeURIComponent(String(a.policy_id))}/overrides`
+  },
+  {
+    name: "files_create_upload_url",
+    feature: "files",
+    description: "Mint a presigned PUT URL for a new file (bytes go straight to storage, never through Vxil). After uploading, call files_complete to make the object available.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        user_id: { type: "string", description: "Owning end_user_id from tenant_users." },
+        filename: { type: "string" },
+        content_type: { type: "string" },
+        size_bytes: { type: "number" }
+      },
+      required: ["user_id", "filename", "content_type", "size_bytes"]
+    },
+    method: "POST",
+    path: "/v1/files/upload-url"
+  },
+  {
+    name: "files_complete",
+    feature: "files",
+    description: "Verify the uploaded bytes and flip the object pending\u2192available. Required before download URLs work.",
+    inputSchema: {
+      type: "object",
+      properties: { object_id: { type: "string" } },
+      required: ["object_id"]
+    },
+    method: "POST",
+    path: (a) => `/v1/files/${encodeURIComponent(String(a.object_id))}/complete`
+  },
+  {
+    name: "files_get_download_url",
+    feature: "files",
+    description: "Mint a short-lived presigned GET URL for an available object.",
+    inputSchema: {
+      type: "object",
+      properties: { object_id: { type: "string" } },
+      required: ["object_id"]
+    },
+    method: "GET",
+    path: (a) => `/v1/files/${encodeURIComponent(String(a.object_id))}/download-url`
+  },
+  {
+    name: "files_list",
+    feature: "files",
+    description: "List file objects (newest first; filter by user_id).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        user_id: { type: "string" },
+        limit: { type: "number", default: 20 }
+      }
+    },
+    method: "GET",
+    path: "/v1/files",
+    queryArgs: ["user_id", "limit"]
+  },
+  {
+    name: "files_delete",
+    feature: "files",
+    description: "Soft-delete a file object; bytes are hard-deleted after 30 days.",
+    inputSchema: {
+      type: "object",
+      properties: { object_id: { type: "string" } },
+      required: ["object_id"]
+    },
+    method: "DELETE",
+    path: (a) => `/v1/files/${encodeURIComponent(String(a.object_id))}`
+  },
+  {
+    name: "comments_create",
+    feature: "comments",
+    description: "Post a comment on a tenant-defined topic ('post:123'); parent_id makes it a threaded reply. author_id is the end-user posting.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        topic: { type: "string" },
+        body: { type: "string" },
+        author_id: { type: "string" },
+        parent_id: { type: "string" }
+      },
+      required: ["topic", "body", "author_id"]
+    },
+    method: "POST",
+    path: "/v1/comments"
+  },
+  {
+    name: "comments_list",
+    feature: "comments",
+    description: "List comments on a topic (newest first; deleted comments appear as tombstones).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        topic: { type: "string" },
+        cursor: { type: "string" },
+        limit: { type: "number", default: 50 }
+      },
+      required: ["topic"]
+    },
+    method: "GET",
+    path: "/v1/comments",
+    queryArgs: ["topic", "cursor", "limit"]
+  },
+  {
+    name: "comments_react",
+    feature: "comments",
+    description: "Toggle an emoji reaction on a comment for an author.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        comment_id: { type: "string" },
+        emoji: { type: "string" },
+        author_id: { type: "string" }
+      },
+      required: ["comment_id", "emoji", "author_id"]
+    },
+    method: "POST",
+    path: (a) => `/v1/comments/${encodeURIComponent(String(a.comment_id))}/reactions`
+  },
+  {
+    name: "cms_list_collections",
+    feature: "cms",
+    description: "List the tenant's content model: collections with their typed field definitions (the schema items are validated against).",
+    inputSchema: { type: "object", properties: {} },
+    method: "GET",
+    path: "/v1/cms/collections"
+  },
+  {
+    name: "cms_create_item",
+    feature: "cms",
+    description: "Create a content item in a collection. data must match the collection field defs (call cms_list_collections first). status draft|published.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        collection: { type: "string" },
+        data: { type: "object", additionalProperties: true },
+        status: { type: "string", enum: ["draft", "published"], default: "draft" }
+      },
+      required: ["collection", "data"]
+    },
+    method: "POST",
+    path: (a) => `/v1/cms/items/${encodeURIComponent(String(a.collection))}`
+  },
+  {
+    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).',
+    inputSchema: {
+      type: "object",
+      properties: {
+        collection: { type: "string" },
+        filter: { type: "string", description: "JSON filter object as a string" },
+        sort: { type: "string" },
+        limit: { type: "number", default: 25 },
+        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"]
+  },
+  {
+    name: "cms_inc_item",
+    feature: "cms",
+    description: 'Atomically increment numeric field(s) of a content item IN the database (one conditional UPDATE \u2014 safe under concurrency, unlike read-modify-write). $inc maps field \u2192 delta, e.g. {"views": 1} or {"stock": -2}. Refused (409 inc_out_of_bounds) if the result would leave the field outside its validation min/max \u2014 the quota/stock pattern.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        collection: { type: "string" },
+        item_id: { type: "string" },
+        $inc: {
+          type: "object",
+          additionalProperties: { type: "number" },
+          description: "field \u2192 numeric delta (1\u20134 int/float fields)"
+        }
+      },
+      required: ["collection", "item_id", "$inc"]
+    },
+    method: "PATCH",
+    path: (a) => `/v1/cms/items/${encodeURIComponent(String(a.collection))}/${encodeURIComponent(String(a.item_id))}`
+  },
+  {
+    name: "cms_publish_item",
+    feature: "cms",
+    description: "Promote a draft item to published (re-validates required fields).",
+    inputSchema: {
+      type: "object",
+      properties: { collection: { type: "string" }, item_id: { type: "string" } },
+      required: ["collection", "item_id"]
+    },
+    method: "POST",
+    path: (a) => `/v1/cms/items/${encodeURIComponent(String(a.collection))}/${encodeURIComponent(String(a.item_id))}/publish`
+  },
+  {
+    name: "cms_aggregate_items",
+    feature: "cms",
+    description: 'Bounded group-by aggregate over a collection (closed fn set: count sum min max avg \u2014 sum/avg need an index-slotted numeric field). groupBy: \u22642 slot-indexed fields. filter: the query DSL plus ONE-hop dotted join terms ({"channel.visibility":"public"} \u2014 the relation field must be slot-indexed). window: {field, sinceDays\u2264366}. Scan is capped at 50000 rows \u2014 a wider match returns 422 window_too_large (narrow it, or declare a materialized read-model). Returns { groups: [{key, <aliases>}], scanned }.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        collection: { type: "string" },
+        aggregates: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              fn: { type: "string", enum: ["count", "sum", "min", "max", "avg"] },
+              field: { type: "string" },
+              as: { type: "string" }
+            },
+            required: ["fn"]
+          },
+          description: "1\u20134 aggregate expressions"
+        },
+        groupBy: { type: "array", items: { type: "string" }, description: "\u22642 slot-indexed field names" },
+        filter: { type: "object", additionalProperties: true },
+        window: {
+          type: "object",
+          properties: {
+            field: { type: "string" },
+            sinceDays: { type: "number" },
+            since: { type: "string" },
+            until: { type: "string" }
+          },
+          required: ["field"]
+        },
+        sort: { type: "string", description: 'an aggregate alias or groupBy key; "-x" = desc' },
+        limit: { type: "number", default: 100, description: "group rows (\u2264500)" }
+      },
+      required: ["collection", "aggregates"]
+    },
+    method: "POST",
+    path: (a) => `/v1/cms/items/${encodeURIComponent(String(a.collection))}/aggregate`
+  },
+  {
+    name: "cms_rank_items",
+    feature: "cms",
+    description: "Window ranking over the bounded aggregate (never raw rows): rank each groupBy entity by a metric. rank \u2208 row_number|rank|percent_rank; optional partitionBy (second slot-indexed field). Same filter/window/scan-cap rules as cms_aggregate_items. Returns { entries: [{key, partition?, metric, rank}], scanned }.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        collection: { type: "string" },
+        groupBy: { type: "string", description: "the ranked entity \u2014 a slot-indexed field (often a relation)" },
+        metric: {
+          type: "object",
+          properties: {
+            fn: { type: "string", enum: ["count", "sum", "min", "max", "avg"] },
+            field: { type: "string" }
+          },
+          required: ["fn"],
+          description: 'default {fn:"count"}'
+        },
+        rank: { type: "string", enum: ["row_number", "rank", "percent_rank"] },
+        partitionBy: { type: "string" },
+        direction: { type: "string", enum: ["asc", "desc"], default: "desc" },
+        filter: { type: "object", additionalProperties: true },
+        window: {
+          type: "object",
+          properties: {
+            field: { type: "string" },
+            sinceDays: { type: "number" },
+            since: { type: "string" },
+            until: { type: "string" }
+          },
+          required: ["field"]
+        },
+        limit: { type: "number", default: 100 }
+      },
+      required: ["collection", "groupBy", "rank"]
+    },
+    method: "POST",
+    path: (a) => `/v1/cms/items/${encodeURIComponent(String(a.collection))}/rank`
+  },
+  {
+    name: "cms_run_transaction",
+    feature: "cms",
+    description: "Atomic multi-collection cms transaction: 1\u20135 steps over \u22643 collections, all-or-nothing. Step ops: insert {collection,data,status?}, update {collection,item_id,data,$where?}, delete {collection,item_id,$where?}. $where is a CAS precondition over the item's own fields (\u22644 terms; scalar / null / {$eq,$ne,$gt,$gte,$lt,$lte,$in}) \u2014 a non-matching $where rolls the WHOLE transaction back (409 names the step). Use for approve-and-upgrade / transfer-ownership patterns.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        steps: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              op: { type: "string", enum: ["insert", "update", "delete"] },
+              collection: { type: "string" },
+              item_id: { type: "string" },
+              data: { type: "object", additionalProperties: true },
+              status: { type: "string", enum: ["draft", "published"] },
+              $where: { type: "object", additionalProperties: true }
+            },
+            required: ["op", "collection"]
+          }
+        }
+      },
+      required: ["steps"]
+    },
+    method: "POST",
+    path: "/v1/cms/transactions"
+  },
+  {
+    name: "cms_list_read_models",
+    feature: "cms",
+    description: "List the tenant's declared cms read-models (config readModels bag): name, kind (aggregate|rank), source collection, cron/target when materialized, and the last run's status.",
+    inputSchema: { type: "object", properties: {} },
+    method: "GET",
+    path: "/v1/cms/read-models"
+  },
+  {
+    name: "cms_materialize_read_model",
+    feature: "cms",
+    description: "Run a declared read-model NOW and write its group rows into the rollup collection (replaces the model's previous rollup rows). Use for backfill/testing; the cron does this on schedule.",
+    inputSchema: {
+      type: "object",
+      properties: { name: { type: "string" } },
+      required: ["name"]
+    },
+    method: "POST",
+    path: (a) => `/v1/cms/read-models/${encodeURIComponent(String(a.name))}/materialize`
+  },
+  {
+    name: "orgs_create",
+    feature: "orgs",
+    description: "Create a workspace/org with a founding owner (end_user_id).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        slug: { type: "string" },
+        name: { type: "string" },
+        owner_user_id: { type: "string" }
+      },
+      required: ["slug", "name", "owner_user_id"]
+    },
+    method: "POST",
+    path: "/v1/orgs"
+  },
+  {
+    name: "orgs_add_member",
+    feature: "orgs",
+    description: "Add a member to an org (or change their role): owner|admin|member|viewer.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        org_id: { type: "string" },
+        user_id: { type: "string" },
+        role: { type: "string", enum: ["owner", "admin", "member", "viewer"] }
+      },
+      required: ["org_id", "user_id", "role"]
+    },
+    method: "POST",
+    path: (a) => `/v1/orgs/${encodeURIComponent(String(a.org_id))}/members`
+  },
+  {
+    name: "orgs_check_permission",
+    feature: "orgs",
+    description: "RBAC check: does the user hold the permission in this org? Built-in permissions map to a minimum role: org:read (viewer+), org:write (member+), members:manage (admin+), org:admin (owner); a custom role's permission-set also satisfies its keys. Pass resource to additionally consult per-resource ACL grants; the result's source marks whether a grant came from the role lattice or a resource ACL. Read-only \u2014 needs orgs:read.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        org_id: { type: "string" },
+        user_id: { type: "string" },
+        permission: { type: "string" },
+        resource: { type: "string", description: "Optional resource string \u2014 also consult per-resource ACL grants for it." }
+      },
+      required: ["org_id", "user_id", "permission"]
+    },
+    method: "GET",
+    path: (a) => `/v1/orgs/${encodeURIComponent(String(a.org_id))}/check`,
+    queryArgs: ["user_id", "permission", "resource"]
+  },
+  {
+    name: "orgs_session_claims",
+    feature: "orgs",
+    description: "The user's ACTIVE-ORG snapshot \u2014 the { org_id, role, perms[] } auth embeds as the session-JWT `org` claim when the tenant enables auth config orgClaims. Active org = the most recent membership (by joined_at); perms = the role's effective permission set (custom catalog entry wins, capped at 32). No membership \u2192 org_id null. EVENTUAL-CONSISTENT: JWTs recompute it only at mint/refresh \u2014 use orgs_check_permission for revocation-grade authz. Read-only \u2014 needs orgs:read.",
+    inputSchema: {
+      type: "object",
+      properties: { user_id: { type: "string", description: "The end_user_id to resolve." } },
+      required: ["user_id"]
+    },
+    method: "GET",
+    path: "/v1/orgs/session-claims",
+    queryArgs: ["user_id"]
+  },
+  {
+    name: "orgs_define_role",
+    feature: "orgs",
+    description: "Define (or upsert) a CUSTOM tenant role as a named permission-set (migration orgs/0019). role_key must not collide with a built-in (owner|admin|member|viewer); permissions is the set of permission keys the role grants (e.g. ['org:read','org:write']). Assign it to a member like any built-in via orgs_add_member. Needs orgs:write.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        role_key: { type: "string", description: "Custom role key (not a built-in)." },
+        name: { type: "string", description: "Human-readable role name." },
+        permissions: { type: "array", items: { type: "string" }, description: "Permission keys the role grants, e.g. ['org:read','org:write']." },
+        rank: { type: "number", description: "Optional ordering rank among roles." }
+      },
+      required: ["role_key", "name", "permissions"]
+    },
+    method: "POST",
+    path: "/v1/orgs/roles"
+  },
+  {
+    name: "orgs_list_roles",
+    feature: "orgs",
+    description: "List the tenant role catalog: builtin[] (the fixed owner>admin>member>viewer lattice as permission-sets) and custom[] (tenant-defined roles). Read-only \u2014 needs orgs:read.",
+    inputSchema: { type: "object", properties: {} },
+    method: "GET",
+    path: "/v1/orgs/roles"
+  },
+  {
+    name: "orgs_grant_acl",
+    feature: "orgs",
+    description: 'Grant a per-org/user RESOURCE ACL (migration orgs/0019): give user_id the permission on a specific resource string within the org. orgs_check_permission with the same resource then consults this grant (result source: "acl"). Needs orgs:write.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        org_id: { type: "string" },
+        user_id: { type: "string", description: "End-user the grant applies to." },
+        resource: { type: "string", description: 'Opaque resource string the grant covers, e.g. "doc:42".' },
+        permission: { type: "string", description: "Permission key granted on the resource." }
+      },
+      required: ["org_id", "user_id", "resource", "permission"]
+    },
+    method: "POST",
+    path: (a) => `/v1/orgs/${encodeURIComponent(String(a.org_id))}/acl`
+  },
+  {
+    name: "orgs_list_acl",
+    feature: "orgs",
+    description: "List an org's resource ACL grants (optionally scoped to one user_id). Read-only \u2014 needs orgs:read.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        org_id: { type: "string" },
+        user_id: { type: "string", description: "Optional end_user_id filter." }
+      },
+      required: ["org_id"]
+    },
+    method: "GET",
+    path: (a) => `/v1/orgs/${encodeURIComponent(String(a.org_id))}/acl`,
+    queryArgs: ["user_id"]
+  },
+  {
+    name: "realtime_publish",
+    feature: "realtime",
+    description: "Broadcast an event to every WebSocket subscriber on a channel (server-side publish; clients connect with tokens from /v1/realtime/tokens).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        channel: { type: "string", description: "e.g. 'room:42'" },
+        event: { type: "string" },
+        data: { type: "object", additionalProperties: true }
+      },
+      required: ["channel", "event"]
+    },
+    method: "POST",
+    path: (a) => `/v1/realtime/channels/${encodeURIComponent(String(a.channel))}/publish`
+  },
+  {
+    name: "webhooks_subscribe",
+    feature: "webhooks",
+    description: "Subscribe an https endpoint to this tenant\u2019s event stream (audit events like user.upserted, job.succeeded). event_prefixes filters by name prefix; empty = all. Deliveries are signed jobs callbacks (verify X-Vxil-Jobs-Signature via jobs_get_signing_secret). Requires the jobs feature.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target_url: { type: "string", description: "https:// endpoint to receive events" },
+        event_prefixes: { type: "array", items: { type: "string" }, description: "e.g. ['user.', 'job.']" }
+      },
+      required: ["target_url"]
+    },
+    method: "POST",
+    path: "/v1/webhooks/subscriptions"
+  },
+  {
+    name: "webhooks_list_subscriptions",
+    feature: "webhooks",
+    description: "List webhook subscriptions.",
+    inputSchema: { type: "object", properties: {} },
+    method: "GET",
+    path: "/v1/webhooks/subscriptions"
+  },
+  {
+    name: "webhooks_unsubscribe",
+    feature: "webhooks",
+    description: "Delete a webhook subscription.",
+    inputSchema: {
+      type: "object",
+      properties: { sub_id: { type: "string" } },
+      required: ["sub_id"]
+    },
+    method: "DELETE",
+    path: (a) => `/v1/webhooks/subscriptions/${encodeURIComponent(String(a.sub_id))}`
+  },
+  {
+    name: "webhooks_test_subscription",
+    feature: "webhooks",
+    description: "Send a synthetic 'webhooks.test' event to a subscription's endpoint through the REAL signing+delivery pipeline and wait inline (\u2264 ~8 s). 200 \u2192 { delivered, state, last_error_* }; 202 \u2192 still in flight ({ run_id, state } \u2014 poll jobs_list_runs). Never fans out to other subscriptions.",
+    inputSchema: {
+      type: "object",
+      properties: { sub_id: { type: "string" } },
+      required: ["sub_id"]
+    },
+    method: "POST",
+    path: (a) => `/v1/webhooks/subscriptions/${encodeURIComponent(String(a.sub_id))}/test`
+  },
+  {
+    name: "webhooks_test_source",
+    feature: "webhooks",
+    description: "Send a sample inbound envelope to a source's forward_url through the real delivery path (jobs signing + SSRF guard). 200 \u2192 inline outcome; 202 \u2192 still in flight; 409 no_forward_url when the source has no forward target.",
+    inputSchema: {
+      type: "object",
+      properties: { source_id: { type: "string" } },
+      required: ["source_id"]
+    },
+    method: "POST",
+    path: (a) => `/v1/webhooks/sources/${encodeURIComponent(String(a.source_id))}/test`
+  },
+  {
+    name: "webhooks_event_runs",
+    feature: "webhooks",
+    description: "Delivery visibility for an inbound webhook event: the jobs runs its forwards created, with state, attempts n/max, last error and DLQ flag (the message-attempt view).",
+    inputSchema: {
+      type: "object",
+      properties: { event_id: { type: "string" } },
+      required: ["event_id"]
+    },
+    method: "GET",
+    path: (a) => `/v1/webhooks/events/${encodeURIComponent(String(a.event_id))}/runs`
+  },
+  {
+    name: "feeds_add_activity",
+    feature: "activity-feed",
+    description: "Add an activity to a flat feed (group + feed_id, e.g. group 'user', feed_id 'u_42'). The actor/verb/object triple is the activity ('u_42' 'post' 'photo:1'); foreign_id+time make the write idempotent (re-sending the same pair updates, never duplicates). to:[] CCs the activity into other feeds ('group:feed_id'). Fans out to followers' timelines and pushes a realtime new-activity event.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        group: { type: "string", description: "Feed group (a feedGroups key, e.g. 'user' | 'timeline' | 'notification')." },
+        feed_id: { type: "string", description: "Feed instance id within the group, e.g. the user id 'u_42'." },
+        actor: { type: "string", description: "Who performed the activity (your opaque id)." },
+        verb: { type: "string", description: "The action, e.g. 'post' | 'like' | 'follow'." },
+        object: { type: "string", description: "What the verb acted on, e.g. 'photo:1'." },
+        target: { type: "string", description: "Optional secondary object the verb targets." },
+        foreign_id: { type: "string", description: "Your stable id for this activity; with time, makes the add idempotent." },
+        time: { type: "string", description: "ISO timestamp of the activity (defaults to now)." },
+        to: { type: "array", items: { type: "string" }, description: "Extra feeds to CC into, each 'group:feed_id'." },
+        extra: { type: "object", additionalProperties: true, description: "Arbitrary metadata stored with the activity." }
+      },
+      required: ["group", "feed_id", "actor", "verb", "object"]
+    },
+    method: "POST",
+    path: (a) => `/v1/feeds/${encodeURIComponent(String(a.group))}/${encodeURIComponent(String(a.feed_id))}/activities`
+  },
+  {
+    name: "feeds_read",
+    feature: "activity-feed",
+    description: "Read a feed (group + feed_id) newest-first with a keyset cursor. Pass id_lt (the last id you saw) to page older, id_gt to fetch newer. Flat feeds return the push\u222Apull union deduped on sort order; aggregated/notification feeds return grouped entries with a badge envelope. notification_state filters to unread|unseen|all; mark_seen/mark_read flip state as you read.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        group: { type: "string" },
+        feed_id: { type: "string" },
+        limit: { type: "number", default: 25 },
+        id_lt: { type: "string", description: "Keyset cursor: return activities with id < this (page older)." },
+        id_gt: { type: "string", description: "Keyset cursor: return activities with id > this (fetch newer)." },
+        notification_state: { type: "string", enum: ["unread", "unseen", "all"] },
+        mark_seen: { type: "boolean", description: "Mark the returned notification groups seen." },
+        mark_read: { type: "boolean", description: "Mark the returned notification groups read." }
+      },
+      required: ["group", "feed_id"]
+    },
+    method: "GET",
+    path: (a) => `/v1/feeds/${encodeURIComponent(String(a.group))}/${encodeURIComponent(String(a.feed_id))}`,
+    queryArgs: ["limit", "id_lt", "id_gt", "notification_state", "mark_seen", "mark_read"]
+  },
+  {
+    name: "feeds_follow",
+    feature: "activity-feed",
+    description: "Make a feed (group + feed_id) follow one source ({target}) or many ({targets:[...]}) in one transaction. A target is a source feed ref 'group:feed_id'. Backfills recent activities into the follower's timeline; rejected (all-or-nothing) if it would exceed the follow.maxFollowing cap.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        group: { type: "string" },
+        feed_id: { type: "string" },
+        target: { type: "string", description: "A single source feed to follow, e.g. 'user:u_7'." },
+        targets: { type: "array", items: { type: "string" }, description: "Follow many source feeds in one txn." }
+      },
+      required: ["group", "feed_id"]
+    },
+    method: "POST",
+    path: (a) => `/v1/feeds/${encodeURIComponent(String(a.group))}/${encodeURIComponent(String(a.feed_id))}/follows`
+  },
+  {
+    name: "feeds_mark_read",
+    feature: "activity-feed",
+    description: "Mark a user's notification groups read (read implies seen). Pass ids[] for specific groups, before (ISO ts) to mark everything older, or neither to mark all. Recomputes and publishes the live unread/unseen badge.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        user_id: { type: "string", description: "Opaque end_user_id whose notification feed to mark." },
+        ids: { type: "array", items: { type: "string" }, description: "Specific notification group ids to mark read." },
+        before: { type: "string", description: "ISO timestamp: mark all groups at or before this read." }
+      },
+      required: ["user_id"]
+    },
+    method: "POST",
+    path: (a) => `/v1/feeds/notification/${encodeURIComponent(String(a.user_id))}/read`
+  },
+  {
+    name: "feeds_unread_count",
+    feature: "activity-feed",
+    description: "Get a user's notification badge: { unseen, unread, total }. KV-cached over the notification_state authority with recompute-on-miss.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        user_id: { type: "string", description: "Opaque end_user_id to read the badge for." }
+      },
+      required: ["user_id"]
+    },
+    method: "GET",
+    path: (a) => `/v1/feeds/notification/${encodeURIComponent(String(a.user_id))}/count`
+  },
+  {
+    name: "search_query",
+    feature: "vector-search",
+    description: "Retrieve the top-k most relevant chunks from a vector-search collection. mode 'hybrid' (default) fuses semantic + keyword via RRF; 'vector' is pure semantic; 'keyword' is lexical. filter is a JSON object of equality constraints over chunk metadata. Returns scored results with document/chunk attribution.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        collection: { type: "string", description: "Collection (index) name to query." },
+        query: { type: "string", description: "Natural-language query text." },
+        top_k: { type: "number", minimum: 1, maximum: 100, default: 10 },
+        mode: { type: "string", enum: ["hybrid", "vector", "keyword"], default: "hybrid" },
+        filter: { type: "object", additionalProperties: true, description: 'Metadata equality filter, e.g. {"user_id":"u_42"}.' },
+        rerank: { type: "boolean", description: "Apply the configured BYO reranker (config rerank block) to the fused results before top-k. Fail-open: a provider fault returns the RRF order with reranked:false." }
+      },
+      required: ["collection", "query"]
+    },
+    method: "POST",
+    path: (a) => `/v1/search/${encodeURIComponent(String(a.collection))}/query`
+  },
+  {
+    name: "ai_generate",
+    feature: "ai",
+    description: "Generate a completion from a prompt or a named tenant template. Pass either prompt (raw text) or template + input (vars for a stored template). Defaults to the tenant-configured provider/model; override with provider/model. Returns the synchronous completion (set stream only via the REST API).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        prompt: { type: "string", description: "Raw prompt text (use this OR template)." },
+        template: { type: "string", description: "Name of a stored template (created via POST /v1/ai/templates)." },
+        input: { type: "object", additionalProperties: true, description: "Variables substituted into the template." },
+        provider: { type: "string", description: "Override the default provider (mock|openai|anthropic|gemini|azure|openrouter)." },
+        model: { type: "string" },
+        max_tokens: { type: "number", minimum: 1, maximum: 2e5 },
+        temperature: { type: "number", minimum: 0, maximum: 2 },
+        json_mode: { type: "boolean", description: "Constrain the output to JSON." },
+        images: {
+          type: "array",
+          items: { type: "string" },
+          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."
+        },
+        user_id: { type: "string", description: "Opaque end_user_id for per-user usage metering." }
+      }
+    },
+    method: "POST",
+    path: "/v1/ai/generate"
+  },
+  {
+    name: "rag_answer",
+    feature: "rag",
+    description: "Answer a question grounded in a vector-search collection: retrieve \u2192 budget context \u2192 generate \u2192 cite. Defaults the collection/template/top_k/mode from the rag config; override per call. Returns the answer plus citations to the source chunks that grounded it.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "The question to answer." },
+        collection: { type: "string", description: "Collection to ground on (defaults to rag config defaultCollection)." },
+        template: { type: "string", description: "Override the answer template (defaults to rag config defaultTemplate)." },
+        top_k: { type: "number", minimum: 1, maximum: 100, description: "Chunks to retrieve before budgeting." },
+        mode: { type: "string", enum: ["hybrid", "vector", "keyword"] },
+        filter: { type: "object", additionalProperties: true, description: "Metadata equality filter applied to retrieval." },
+        provider: { type: "string" },
+        model: { type: "string" },
+        input: { type: "object", additionalProperties: true, description: "Extra template vars beyond {{query}}/{{context}}." },
+        user_id: { type: "string", description: "Opaque end_user_id for per-user usage metering." }
+      },
+      required: ["query"]
+    },
+    method: "POST",
+    path: "/v1/rag/answer"
+  },
+  {
+    name: "rag_search",
+    feature: "rag",
+    description: "Retrieval-only grounding preview: the exact chunks rag_answer would ground on, with rerank + metadata boosts applied \u2014 no generation, no token spend. Use it to inspect/tune retrieval (boost weights, rerank, min_score) before paying for an answer.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "The retrieval query." },
+        collection: { type: "string", description: "Collection to search (defaults to rag config defaultCollection)." },
+        top_k: { type: "number", minimum: 1, maximum: 100, description: "Chunks to retrieve." },
+        mode: { type: "string", enum: ["hybrid", "vector", "keyword"] },
+        filter: { type: "object", additionalProperties: true, description: "Metadata equality filter applied to retrieval." },
+        rerank: { type: "boolean", description: "Forward rerank:true to vector-search's BYO rerank pass (inert until configured there)." },
+        boosts: { type: "object", additionalProperties: true, description: "Per-metadata-field boost specs: { field: { kind:'recency', halfLifeDays?, weight? } | { kind:'value', weights:{\u2026} } }." },
+        min_score: { type: "number", description: "Drop hits below this EFFECTIVE (post-boost) score." }
+      },
+      required: ["query"]
+    },
+    method: "POST",
+    path: "/v1/rag/search"
+  },
+  {
+    name: "payments_check_entitlement",
+    feature: "payments",
+    description: "Check whether an end-user holds a boolean entitlement (a feature flag from the tenant's tierMap, e.g. 'export', 'priority_support'). Returns granted plus the source (subscription/tier) and the resolved tier. Use this to gate access before doing privileged work. Read-only \u2014 needs payments:read.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        user_id: { type: "string", description: "Opaque end_user_id from tenant_users." },
+        entitlement: { type: "string", description: "Entitlement key to check, e.g. 'export' or 'seats'." }
+      },
+      required: ["user_id", "entitlement"]
+    },
+    method: "GET",
+    path: "/v1/payments/entitlements/check",
+    queryArgs: ["user_id", "entitlement"]
+  },
+  {
+    name: "payments_balance",
+    feature: "payments",
+    description: "Read an end-user's credit balance for a credit type (e.g. 'scans', 'tokens'): balance, held (provisional/in-flight), and available (= balance \u2212 held). Check available before consuming. Read-only \u2014 needs payments:read.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        user_id: { type: "string", description: "Opaque end_user_id from tenant_users." },
+        credit_type: { type: "string", description: "Credit type to read, e.g. 'scans'." }
+      },
+      required: ["user_id", "credit_type"]
+    },
+    method: "GET",
+    path: "/v1/payments/credits/balance",
+    queryArgs: ["user_id", "credit_type"]
+  },
+  {
+    name: "payments_consume",
+    feature: "payments",
+    description: "Debit credits from an end-user \u2014 idempotent (idempotency_key REQUIRED; the SAME key always returns the SAME result, never double-charges) and balance-guarded (never oversells; returns 402 INSUFFICIENT_CREDITS when available can't cover amount). Pass job_id to make the debit a PROVISIONAL hold tied to a background job: a linked jobs run that terminally fails auto-refunds the hold, a success settles it. amount must be >= 1. Needs payments:write.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        user_id: { type: "string", description: "Opaque end_user_id to debit." },
+        credit_type: { type: "string", description: "Credit type to debit, e.g. 'scans'." },
+        amount: { type: "number", minimum: 1, description: "Credits to consume (>= 1)." },
+        idempotency_key: { type: "string", description: "Unique key for this debit; reusing it replays the first result (no double-charge)." },
+        job_id: { type: "string", description: "Optional jobs run_id to link: makes the debit a provisional hold that auto-reverses if the job terminally fails." },
+        reason: { type: "string", description: "Optional human-readable reason recorded on the ledger row." }
+      },
+      required: ["user_id", "credit_type", "amount", "idempotency_key"]
+    },
+    method: "POST",
+    path: "/v1/payments/credits/consume",
+    idempotencyArg: "idempotency_key"
+  },
+  {
+    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), signature status, error, and timestamps per delivery. Use it to diagnose billing sync issues (e.g. an unmapped product, a misconfigured webhook secret producing sig_failed rows). Read-only \u2014 needs payments:read. Payloads are detail-only (console surface).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        provider: { type: "string", enum: ["mock", "stripe", "paddle", "revenuecat", "paypal"] },
+        event_type: { type: "string", description: "Exact event type filter, e.g. 'subscription.updated'." },
+        outcome: { type: "string", enum: ["received", "processed", "error", "sig_failed", "parse_failed", "reprocessed"] },
+        since: { type: "string", description: "ISO-8601 lower bound on received_at." },
+        cursor: { type: "string", description: "Opaque keyset cursor from a prior page (next_cursor)." },
+        limit: { type: "number", default: 50, description: "Page size, clamped 1..100." }
+      }
+    },
+    method: "GET",
+    path: "/v1/payments/webhook-events",
+    queryArgs: ["provider", "event_type", "outcome", "since", "cursor", "limit"]
+  },
+  {
+    name: "mcp_get_signing_secret",
+    description: 'Per-tenant secret your endpoints use to verify the X-Vxil-Mcp-Signature header on custom MCP tool calls (config mcp.customTools). Same recipe as jobs callbacks: t=<unix>,v1=<hmac-sha256-hex over "<toolName>.<tenantId>.<t>.<sha256hex(body)>">, 300s replay window. Needs features:read.',
+    inputSchema: { type: "object", properties: {} },
+    method: "GET",
+    path: "/v1/mcp/signing-secret"
+  },
+  {
+    name: "copilot_send_message",
+    feature: "copilot",
+    description: 'Send a message to a copilot AGENT (a configured AI assistant) and get its grounded answer. The agent retrieves from its knowledge collections, cites sources, and may PROPOSE a write action (returned as `proposal` with action_status "proposed") \u2014 proposals never auto-run; confirm them with copilot_confirm_action. Omit conversation_id to start a new conversation; pass the returned conversation_id to continue one. Needs copilot:write.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        agent_id: { type: "string", description: "The configured agent id (copilot.agents key)." },
+        message: { type: "string", description: "The end-user's message (1..32000 chars)." },
+        conversation_id: { type: "string", description: "Continue an existing conversation; omit to start a new one." },
+        user_id: { type: "string", description: "Opaque end_user_id to attribute the turn (for usage + rate limits)." }
+      },
+      required: ["agent_id", "message"]
+    },
+    method: "POST",
+    path: (a) => `/v1/copilot/${encodeURIComponent(String(a.agent_id))}/messages`
+  },
+  {
+    name: "copilot_list_conversations",
+    feature: "copilot",
+    description: "List a copilot agent's conversations, newest-updated first. Filter by user_id to scope to one end user. Read-only \u2014 needs copilot:read.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        agent_id: { type: "string", description: "The configured agent id." },
+        user_id: { type: "string", description: "Optional end_user_id filter." },
+        limit: { type: "number", description: "Max rows (1..200, default 50)." }
+      },
+      required: ["agent_id"]
+    },
+    method: "GET",
+    path: (a) => `/v1/copilot/${encodeURIComponent(String(a.agent_id))}/conversations`,
+    queryArgs: ["user_id", "limit"]
+  },
+  {
+    name: "copilot_confirm_action",
+    feature: "copilot",
+    description: 'Confirm a PROPOSED copilot action so it executes for real (the only way a write runs). Pass the conversation_id and the proposal message_id from a copilot_send_message result whose action_status was "proposed". idempotency_key makes a retried confirm a downstream no-op (reusing it replays the first result, never double-executing). Needs copilot:write. The action re-validates against the agent config + your scopes + live features before running.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        conversation_id: { type: "string", description: "The conversation holding the proposal." },
+        message_id: { type: "string", description: "The assistant message_id carrying the proposal." },
+        idempotency_key: { type: "string", description: "Unique key for this confirm; reusing it replays the first result (no double-execute)." }
+      },
+      required: ["conversation_id", "message_id"]
+    },
+    method: "POST",
+    path: (a) => `/v1/copilot/conversations/${encodeURIComponent(String(a.conversation_id))}/actions/${encodeURIComponent(String(a.message_id))}/confirm`,
+    idempotencyArg: "idempotency_key"
+  },
+  {
+    // Substrate meta-tool (no `feature` — always-on like users_upsert). Handled
+    // LOCALLY in rpc.ts tools/call (mcp.md §6.8) — the `local:` path marker is
+    // never fetched and deliberately non-/v1 so the trinity-drift scanner
+    // (extractMcpRoutes only harvests '/v1/…' literals) ignores it: there is no
+    // REST route behind this tool.
+    name: "vxil_tool_search",
+    description: `Search this server's tool catalog by keyword and get back the top-ranked matching tools WITH their input schemas. Use this instead of scanning the full tools/list when you need a capability (e.g. query "publish cms item" or "send email"). Only tools your key/tenant can actually call are returned.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: 'Keywords: feature, verb, noun (e.g. "cms publish", "signed upload url").' },
+        limit: { type: "number", default: 8, minimum: 1, maximum: 20 }
+      },
+      required: ["query"]
+    },
+    method: "GET",
+    // GET-class → stays visible under exposureLevel 'read-only'
+    path: "local:tool-search"
+  }
+];
+
+// src/mcp.ts
+function lowerPath(path, inputSchema) {
+  if (typeof path === "string") return path;
+  const props = Object.keys(inputSchema.properties ?? {});
+  const sentinels = {};
+  for (const p of props) sentinels[p] = `__${p}__`;
+  return path(sentinels).replace(/__([a-z0-9_]+)__/g, "{$1}");
+}
+function buildMcpCatalog(input, tools = TOOLS) {
+  const features = [...input.features].sort();
+  const featureSet = new Set(features);
+  const colls = [...input.collections].sort((a, b) => a.collection.localeCompare(b.collection));
+  const collNames = colls.map((c) => c.collection);
+  const fns = [...input.functions].sort((a, b) => a.name.localeCompare(b.name));
+  const catalogTools = tools.filter((t) => !t.feature || featureSet.has(t.feature)).sort((a, b) => a.name.localeCompare(b.name)).map((t) => {
+    let inputSchema = t.inputSchema;
+    const props = inputSchema.properties;
+    if (collNames.length && props && "collection" in props) {
+      inputSchema = structuredClone(t.inputSchema);
+      const cloned = inputSchema.properties;
+      cloned.collection.enum = collNames;
+    }
+    return {
+      name: t.name,
+      feature: t.feature ?? null,
+      method: t.method,
+      path: lowerPath(t.path, t.inputSchema),
+      description: t.description,
+      inputSchema,
+      ...t.queryArgs ? { queryArgs: t.queryArgs } : {},
+      ...t.idempotencyArg ? { idempotencyArg: t.idempotencyArg } : {}
+    };
+  });
+  const cmsCollections = {};
+  for (const c of colls) {
+    const slotted = slottedFields(c);
+    cmsCollections[c.collection] = {
+      fields: c.fields.map((f) => ({
+        field: f.field,
+        type: f.type,
+        required: f.required,
+        index_slot: f.index_slot
+      })),
+      // `$status` (draft|published|archived) is always filterable; every stored
+      // user field filters by equality/$in (+$contains on strings) — only an
+      // UNSLOTTED COMPUTED field is rejected. Range ops need an index slot
+      // (range_filterable ⊆ filterable). Meta columns are sortable-only — the
+      // exact server contract (cms-v1 query.ts), same as gen.ts's Filterable.
+      filterable: ["$status", ...c.fields.filter(isFilterableField).map((f) => f.field)],
+      range_filterable: slotted.map((f) => f.field),
+      sortable: [...slotted.map((f) => f.field), ...META_SORTABLE]
+    };
+  }
+  return {
+    catalog: "vxil.mcp/v1",
+    ...input.generatedAt ? { generated_at: input.generatedAt } : {},
+    ...input.tenant ? { tenant: input.tenant } : {},
+    ...input.env ? { env: input.env } : {},
+    features,
+    note: `feature-pruned gen-time snapshot; the live MCP server additionally applies the tenant exposure policy (exposureLevel/allowToolList from /v1/config/mcp) at tools/list. cms $status filter values: ${CMS_STATUS_VALUES.join("|")}. cms filter ops: equality/$eq/$in (+$contains on string fields) work on any filterable field; $ne/$gt/$gte/$lt/$lte only on range_filterable (index-slotted) fields.`,
+    tools: catalogTools,
+    cms_collections: cmsCollections,
+    functions_note: "deployed tenant functions are invoked via REST (POST /v1/fn/<name>) \u2014 the MCP server exposes no function-invoke tools",
+    functions: fns.map((f) => ({
+      name: f.name,
+      invoke: `POST /v1/fn/${f.name}`,
+      signature: f.signature ?? null
+    }))
+  };
+}
+
+// src/store.ts
+import { homedir } from "node:os";
+import { join, resolve as resolve3 } from "node:path";
+import { existsSync as existsSync2, mkdirSync, readFileSync, writeFileSync as writeFileSync2, chmodSync } from "node:fs";
+function credDir() {
+  return join(homedir(), ".vxil");
+}
+function credFile() {
+  return join(credDir(), "credentials.json");
+}
+function loadCredentials() {
+  try {
+    return JSON.parse(readFileSync(credFile(), "utf8"));
+  } catch {
+    return {};
+  }
+}
+function saveCredentials(c) {
+  mkdirSync(credDir(), { recursive: true });
+  writeFileSync2(credFile(), JSON.stringify(c, null, 2));
+  try {
+    chmodSync(credFile(), 384);
+  } catch {
+  }
+}
+function projectFile(cwd = process.cwd()) {
+  return resolve3(cwd, ".vxil", "project.json");
+}
+function loadProject(cwd = process.cwd()) {
+  try {
+    return JSON.parse(readFileSync(projectFile(cwd), "utf8"));
+  } catch {
+    return null;
+  }
+}
+function saveProject(binding, cwd = process.cwd()) {
+  const dir = resolve3(cwd, ".vxil");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync2(projectFile(cwd), JSON.stringify(binding, null, 2));
+}
+function resolve_target(opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  const proj = loadProject(cwd);
+  const creds = loadCredentials();
+  const envKey = process.env.VXIL_API_KEY;
+  const envBase = process.env.VXIL_BASE_URL;
+  if (opts.which === "dev" && proj?.dev) {
+    const devKey = process.env.VXIL_DEV_KEY ?? creds.keys?.[proj.dev.slug];
+    return { apiKey: devKey ?? envKey, baseUrl: envBase ?? proj.dev.edge_url ?? opts.defaultBase, tenantSlug: proj.dev.slug };
+  }
+  if (envKey) {
+    return { apiKey: envKey, baseUrl: envBase ?? proj?.edge_url ?? opts.defaultBase, tenantSlug: proj?.slug };
+  }
+  if (proj) {
+    const key = creds.keys?.[proj.slug];
+    return { apiKey: key, baseUrl: envBase ?? proj.edge_url ?? opts.defaultBase, tenantSlug: proj.slug };
+  }
+  return { apiKey: void 0, baseUrl: envBase ?? opts.defaultBase, tenantSlug: void 0 };
+}
+
+// src/link.ts
+function data(r) {
+  return r.json.data ?? r.json;
+}
+function errText(r) {
+  const e = r.json.error;
+  return e ? `${e.code ?? r.status}${e.message ? ` \u2014 ${e.message}` : ""}` : `${r.status}`;
+}
+async function linkViaSession(dash, cookie, slug, keyName) {
+  const list = await dash("GET", "/dashboard/tenants", void 0, cookie);
+  if (list.status === 401) return { unauthorized: true };
+  if (list.status !== 200) throw new Error(`could not list projects (${errText(list)})`);
+  const tenants = data(list).tenants ?? [];
+  const t = tenants.find((x) => x.slug === slug);
+  if (!t) {
+    throw new Error(
+      `no project '${slug}' on this account \u2014 run \`vxil quickstart\`, or ask an admin to add you as a member`
+    );
+  }
+  const mint = await dash("POST", `/dashboard/tenants/${t.id}/api-keys`, { name: keyName }, cookie);
+  if (mint.status === 401) return { unauthorized: true };
+  if (mint.status !== 201 && mint.status !== 200) {
+    throw new Error(`could not mint a key for '${slug}' (${errText(mint)})`);
+  }
+  const apiKey = data(mint).api_key;
+  if (!apiKey) throw new Error("mint returned no api_key");
+  return { result: { slug, tenant_id: t.id, api_key: apiKey } };
+}
+async function linkViaDeviceFlow(dash, slug, io) {
+  const now = io.now ?? Date.now;
+  const start = await dash("POST", "/dashboard/cli/link", { slug });
+  if (start.status !== 201 && start.status !== 200) {
+    throw new Error(`could not start the link (${errText(start)})`);
+  }
+  const d = data(start);
+  if (!d.device_code || !d.user_code) throw new Error("link start returned no device_code");
+  io.log("");
+  io.log(`To link '${slug}', approve this request in your browser:`);
+  io.log("");
+  io.log(`  ${d.verification_uri_complete ?? d.verification_uri ?? "(open the dashboard \u2192 CLI link)"}`);
+  io.log(`  code: ${d.user_code}`);
+  io.log("");
+  io.log("Waiting for approval (Ctrl-C to cancel)\u2026");
+  const intervalMs = Math.max(1, d.interval ?? 5) * 1e3;
+  const deadline = now() + Math.max(1, d.expires_in ?? 900) * 1e3;
+  while (now() < deadline) {
+    await io.sleep(intervalMs);
+    const poll = await dash("POST", "/dashboard/cli/link/token", { device_code: d.device_code });
+    if (poll.status === 428) continue;
+    if (poll.status === 200) {
+      const p = data(poll);
+      if (!p.api_key || !p.tenant_id) throw new Error("approval returned no api_key");
+      return { slug: p.slug || slug, tenant_id: p.tenant_id, api_key: p.api_key };
+    }
+    throw new Error(`link failed (${errText(poll)})`);
+  }
+  throw new Error("link timed out waiting for browser approval \u2014 run `vxil link <slug>` again");
+}
+
+// src/devLifecycle.ts
+async function devDown(dash, cookie, dev) {
+  const r = await dash("DELETE", `/dashboard/tenants/${dev.tenant_id}`, { confirm: dev.slug }, cookie);
+  if (r.status === 200) return { gone: true, alreadyGone: false };
+  if (r.status === 404) return { gone: true, alreadyGone: true };
+  const e = r.json.error;
+  throw new Error(
+    `dev down failed (${e?.code ?? r.status}${e?.message ? ` \u2014 ${e.message}` : ""})`
+  );
+}
+
+// src/envPull.ts
+var MANAGED_HEADER = "# vxil (managed by `vxil env pull`)";
+var MANAGED_LINE = /^(\s*(?:export\s+)?)(VXIL_[A-Z0-9_]+)\s*=/;
+function envUpdates(t) {
+  return {
+    VXIL_BASE_URL: t.baseUrl,
+    VXIL_API_KEY: t.apiKey,
+    ...t.tenantId ? { VXIL_TENANT_ID: t.tenantId } : {}
+  };
+}
+function mergeEnvFile(existing, updates) {
+  const pending = new Map(Object.entries(updates));
+  const lines = existing.length ? existing.split("\n") : [];
+  if (lines.length && lines[lines.length - 1] === "") lines.pop();
+  const out = lines.map((line) => {
+    const m = MANAGED_LINE.exec(line);
+    if (!m) return line;
+    const key = m[2];
+    const value = pending.get(key);
+    if (value === void 0) return line;
+    pending.delete(key);
+    return `${m[1] ?? ""}${key}=${value}`;
+  });
+  if (pending.size) {
+    if (out.length && out[out.length - 1] !== "") out.push("");
+    out.push(MANAGED_HEADER);
+    for (const [k, v] of pending) out.push(`${k}=${v}`);
+  }
+  return out.length ? `${out.join("\n")}
+` : "";
+}
+function gitignoreCovers(gitignoreText, filename) {
+  const base = filename.split("/").pop() ?? filename;
+  for (const raw of gitignoreText.split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#") || line.startsWith("!")) continue;
+    const pat = line.replace(/^\//, "").replace(/\/$/, "");
+    if (pat === filename || pat === base) return true;
+    if (pat.includes("*")) {
+      const rx = new RegExp(`^${pat.split("*").map(escapeRe).join("[^/]*")}$`);
+      if (rx.test(filename) || rx.test(base)) return true;
+    }
+  }
+  return false;
+}
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// src/devBranch.ts
+function sanitizeBranchName(raw) {
+  return raw.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40).replace(/-+$/, "");
+}
+function pickBranchSlot(binding, name, now, hasKey) {
+  const slot = binding?.branches?.[name];
+  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,
+    password: opts.password,
+    app_name: opts.appName,
+    features: opts.features.length ? opts.features : ["cms"],
+    kind: "dev",
+    ttl_hours: opts.ttlHours
+  });
+  if (r.status !== 201 && r.status !== 200) {
+    const e = r.json.error;
+    throw new Error(
+      `dev tenant create failed (${e?.code ?? r.status}${e?.message ? ` \u2014 ${e.message}` : ""}${e?.hint ? `; ${e.hint}` : ""})`
+    );
+  }
+  const d = r.json.data ?? r.json;
+  if (!d.api_key || !d.tenant_id || !d.app_slug) throw new Error("dev tenant create returned no api_key");
+  return {
+    tenant_id: d.tenant_id,
+    slug: d.app_slug,
+    api_key: d.api_key,
+    ...d.edge_url ? { edge_url: d.edge_url } : {},
+    ...d.expires_at ? { expires_at: d.expires_at } : {}
+  };
+}
+
+// src/try.ts
+async function mintTry(fetchImpl, base, opts = {}) {
+  const url = `${base.replace(/\/$/, "")}/v1/try`;
+  const body = opts.turnstileToken ? { turnstile_token: opts.turnstileToken } : {};
+  const r = await fetchImpl(url, body);
+  if (r.status === 201 || r.status === 200) {
+    const d = r.json.data ?? r.json;
+    if (!d.api_key || !d.tenant_id || !d.slug) {
+      return { ok: false, status: r.status, code: "bad_response", message: "/v1/try returned no api_key/tenant." };
+    }
+    return {
+      ok: true,
+      result: {
+        tenant_id: d.tenant_id,
+        slug: d.slug,
+        api_key: d.api_key,
+        expires_at: d.expires_at ?? "",
+        enabled_features: d.enabled_features ?? []
+      }
+    };
+  }
+  const e = r.json.error ?? {};
+  if (r.status === 404) {
+    return {
+      ok: false,
+      status: 404,
+      code: e.code ?? "not_found",
+      message: "the keyless sandbox is not enabled on this backend \u2014 use `vxil quickstart` (with an email) for a persistent project."
+    };
+  }
+  if (r.status === 429) {
+    return {
+      ok: false,
+      status: 429,
+      code: e.code ?? "rate_limited",
+      message: `${e.message ?? "the sandbox is rate-limited or at capacity"} \u2014 retry shortly, or \`vxil quickstart\` for a persistent project.`
+    };
+  }
+  return {
+    ok: false,
+    status: r.status,
+    code: e.code ?? "error",
+    message: e.message ?? `unexpected ${r.status} from /v1/try`
+  };
+}
+function renderTryReport(result, opts) {
+  const genOk = opts.genOk !== false;
+  const lines = [];
+  lines.push(`
+\u2713 sandbox backend '${result.slug}' is live \u2014 no account, no signup.`);
+  lines.push(`  enabled: ${result.enabled_features.join(", ") || "(none)"}`);
+  lines.push(`  api key (shown ONCE \u2014 not recoverable): ${result.api_key}`);
+  if (result.expires_at) {
+    lines.push(`  \u23F3 expires ${result.expires_at} (~2h) \u2014 the tenant, its data, AND this key are DELETED after. Nothing to clean up.`);
+  } else {
+    lines.push("  \u23F3 this sandbox self-expires in ~2h \u2014 the tenant, its data, and this key are deleted after.");
+  }
+  if (genOk) {
+    lines.push("\n  try it (types were generated in ./vxil.types.ts):");
+    lines.push("    import { Vxil } from '@vxil/sdk';");
+    lines.push("    import type { VxilSchema } from './vxil.types';");
+    lines.push(`    const vx = Vxil.connect<VxilSchema>({ apiKey: '${result.api_key}', baseUrl: '${opts.base}' });`);
+  } else {
+    lines.push("\n  try it (typed client skipped \u2014 `npm i -D vxil && npm i @vxil/sdk`, then `npx vxil gen`):");
+    lines.push("    import { Vxil } from '@vxil/sdk';");
+    lines.push(`    const vx = new Vxil({ apiKey: '${result.api_key}', baseUrl: '${opts.base}' });`);
+  }
+  lines.push(`    await vx.from('${opts.collection}').create({ /* field-typed */ }, { status: 'published' });`);
+  lines.push(`    const { items } = await vx.from('${opts.collection}').query();   // read it back`);
+  lines.push("    // (run `vxil push` first to materialize the collection server-side)");
+  lines.push("\n  cleanup: nothing to do \u2014 it self-expires (~2h) and the nightly reaper deletes it.");
+  lines.push("           (`vxil dev down` drops a linked dev tenant, if you make one.)");
+  return lines;
+}
+
+// src/generated/templates.ts
+var TEMPLATE_CATALOG = [
+  {
+    "id": "blog",
+    "title": "Blog / Publishing",
+    "vertical": "content",
+    "summary": "A publishing backend \u2014 authors, categories, and posts with a draft\u2192publish editorial lifecycle and threaded reader comments.",
+    "collections": [
+      "authors",
+      "categories",
+      "posts"
+    ],
+    "features": [
+      "cms",
+      "comments",
+      "notifications"
+    ],
+    "hasFunctions": false,
+    "byoKeys": [],
+    "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// \"Blog\" \u2014 a publishing / headless-CMS backend (authors, categories, posts with\n// a draft\u2192publish lifecycle), declared end-to-end in ONE typed file. A BLUEPRINT\n// composing shipped building blocks \u2014\n//   \u2022 cms      \u2192 authors \u2192 categories \u2192 posts (resolved by relation)\n//   \u2022 comments \u2192 threaded reader comments on posts\n// Everything here is DATA the tenant owns and edits after `vxil init`. The\n// editorial workflow migrates ~100%; the public reader tier arrives with the\n// cms public-delivery lane (docs/roadmap.md \xA74.4).\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    cms: {\n      draftPublish: true, // the editorial lifecycle: write as draft, publish live\n      hooks: {\n        // Every post needs a title \u2014 a pure function of the row (Lane-A validate).\n        post_title: {\n          collection: 'posts',\n          event: 'beforeWrite',\n          kind: 'validate',\n          expr: 'len(item.title) > 0',\n          message: 'a post needs a title',\n        },\n      },\n    },\n    comments: {}, // threaded reader comments on published posts\n    notifications: { provider: 'mock', fromEmail: 'noreply@blog.app' },\n  },\n\n  // \u2500\u2500 Schema-as-code: the cms collections (\u22648 index slots each: s1\u2013s4/n1\u2013n2/t1\u2013t2) \u2500\u2500\n  cms: {\n    collections: {\n      authors: {\n        singular: 'author',\n        fields: {\n          name: { type: 'string', required: true, indexSlot: 's1' },\n          slug: { type: 'string', indexSlot: 's2', validation: { unique: true } },\n          bio: { type: 'text' },\n        },\n      },\n      categories: {\n        singular: 'category',\n        fields: {\n          name: { type: 'string', required: true, indexSlot: 's1' },\n          slug: { type: 'string', indexSlot: 's2', validation: { unique: true } },\n        },\n      },\n      posts: {\n        singular: 'post',\n        fields: {\n          title: { type: 'string', required: true, indexSlot: 's1' },\n          slug: { type: 'string', required: true, indexSlot: 's2', validation: { unique: true } },\n          excerpt: { type: 'text' },\n          body: { type: 'text' },\n          author: { type: 'relation', relationTo: 'authors', indexSlot: 's3' },\n          category: { type: 'relation', relationTo: 'categories', indexSlot: 's4' },\n          published_at: { type: 'datetime', indexSlot: 't1' },\n          reading_minutes: { type: 'int', indexSlot: 'n1' },\n        },\n      },\n    },\n  },\n\n  seed: {\n    cms: [\n      {\n        collection: 'authors',\n        items: [{ name: 'Ada Lovelace', slug: 'ada', bio: 'Writes about computing.' }],\n      },\n    ],\n  },\n});\n",
+    "readme": "# Blog / Publishing template\n\nA publishing / headless-CMS backend \u2014 declared end-to-end in one typed `vxil.config.ts`.\n\n**Provisions:**\n- `authors` \u2014 name, unique slug, bio.\n- `categories` \u2014 name, unique slug.\n- `posts` \u2014 title, unique slug, excerpt, body, `author` + `category` relations (slot-bound for filtering),\n  `published_at`, `reading_minutes`. A Lane-A hook requires a title, and `draftPublish` gives you the\n  write-as-draft \u2192 publish-live editorial lifecycle.\n- `comments` \u2014 threaded reader comments on published posts.\n\n**Use it:**\n\n```bash\nvxil init --template blog\nvxil quickstart\nvxil push\nvxil gen\n```\n\n**The public reader tier** (unauthenticated, edge-cached post reads) arrives with the `cms` public-delivery lane\n(`docs/roadmap.md` \xA74.4) \u2014 until then, serve posts through your own frontend with a read key.\n\n**Own the shape.** The config is yours after `init` \u2014 nothing is locked.\n"
+  },
+  {
+    "id": "research-library",
+    "title": "Research Library",
+    "vertical": "content",
+    "summary": "A knowledge base for research and reference content \u2014 topics, sources, and cross-linked notes with a bounded citation graph.",
+    "collections": [
+      "topics",
+      "sources",
+      "notes"
+    ],
+    "features": [
+      "cms",
+      "notifications"
+    ],
+    "hasFunctions": false,
+    "byoKeys": [],
+    "configSrc": `import { defineConfig } from '@vxil/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\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
+// "Research Library" \u2014 a knowledge base for research/reference content, declared
+// end-to-end in ONE typed file. It is NOT a vxil "research feature" (there is
+// none): it is a BLUEPRINT that composes shipped building blocks \u2014
+//   \u2022 cms  \u2192 the content spine (topics \u2192 sources \u2192 notes, resolved by relation)
+//   \u2022 notifications \u2192 optional digests/alerts
+// Everything is DATA the tenant owns and edits after \`vxil init\`. There is no
+// platform lock over the shape \u2014 the invariants (a required title, a sane year)
+// ride as tenant-owned Lane-A validate hooks. See docs/cms-content-templates-analysis.md.
+// \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
+export default defineConfig({
+  env: 'staging',
+
+  features: {
+    cms: {
+      // Draft while researching; publish when a note/source is ready to share.
+      draftPublish: true,
+      // A Lane-A safe-expression hook \u2014 AST-validated at \`vxil push\` time, run in
+      // the write tx. Cross-row work would live in a function; this is one row.
+      hooks: {
+        // A source's year (if given) must be sane \u2014 pure function of the row.
+        source_year: {
+          collection: 'sources',
+          event: 'beforeWrite',
+          kind: 'validate',
+          expr: 'isNull(item.year) || (item.year >= 0 && item.year <= 2100)',
+          message: 'year must be between 0 and 2100',
+        },
+      },
+    },
+    notifications: { provider: 'mock', fromEmail: 'library@example.app' },
+  },
+
+  // \u2500\u2500 Schema-as-code: the cms collections (\u22648 index slots each: s1\u2013s4/n1\u2013n2/t1\u2013t2) \u2500\u2500
+  cms: {
+    collections: {
+      topics: {
+        singular: 'topic',
+        fields: {
+          name: { type: 'string', required: true, indexSlot: 's1' },
+          slug: { type: 'string', indexSlot: 's2', validation: { unique: true } },
+          description: { type: 'text' },
+        },
+      },
+      sources: {
+        singular: 'source',
+        fields: {
+          title: { type: 'string', required: true, indexSlot: 's1' },
+          url: { type: 'string', indexSlot: 's2' },
+          author: { type: 'string', indexSlot: 's3' },
+          kind: { type: 'string', indexSlot: 's4' }, // book | article | web | dataset
+          year: { type: 'int', indexSlot: 'n1' },
+          topic: { type: 'relation', relationTo: 'topics' },
+          added_at: { type: 'datetime', indexSlot: 't1' },
+        },
+      },
+      notes: {
+        singular: 'note',
+        fields: {
+          title: { type: 'string', required: true, indexSlot: 's1' },
+          body: { type: 'text' },
+          // Slot the relations so notes can be filtered by their source/topic
+          // (the \xA712.1 single-hop dotted-key join over a slot-bound relation).
+          source: { type: 'relation', relationTo: 'sources', indexSlot: 's2' },
+          topic: { type: 'relation', relationTo: 'topics', indexSlot: 's3' },
+          tags: { type: 'json' }, // ["method","open-question"] \u2014 $arrayContains-searchable
+        },
+      },
+    },
+  },
+
+  seed: {
+    cms: [
+      {
+        collection: 'topics',
+        items: [
+          { name: 'Distributed Systems', slug: 'distributed-systems', description: 'Consensus, replication, consistency.' },
+          { name: 'Databases', slug: 'databases', description: 'Storage engines, query planning, isolation.' },
+        ],
+      },
+    ],
+  },
+});
+`,
+    "readme": '# Research Library template\n\nA knowledge base for research/reference content \u2014 declared end-to-end in one typed `vxil.config.ts`.\n\n**Provisions (all `cms` collections you own and can edit):**\n- `topics` \u2014 subject areas (name, slug, description).\n- `sources` \u2014 cited works (title, url, author, kind, year \u2192 `topics`); a Lane-A hook keeps the year sane.\n- `notes` \u2014 your writing, cross-linked to a `source` and a `topic` (slot-bound so you can filter notes by either \u2014 the single-hop join in `docs/features/cms.md` \xA712.1). `tags` is a JSON array (`$arrayContains`-searchable).\n\n**Use it:**\n\n```bash\nvxil init --template research-library\nvxil quickstart        # a new backend (or `vxil link <slug>` for an existing one)\nvxil push              # apply the collections + hooks\nvxil gen               # typed SDK + MCP catalog\n```\n\n**Own the shape.** After `init` the config is yours \u2014 add fields, edit the hook, add collections. Nothing is\nlocked; the "required title / sane year" invariants ride as tenant-owned Lane-A `validate` hooks you can see and\nchange. To make more content publicly readable later, enable the `cms` public-delivery lane when it ships\n(`docs/roadmap.md` \xA74.4).\n'
+  },
+  {
+    "id": "gallery",
+    "title": "Gallery",
+    "vertical": "content",
+    "summary": "An image / media gallery \u2014 albums of photos with file-backed images, dimensions, and tags.",
+    "collections": [
+      "albums",
+      "photos"
+    ],
+    "features": [
+      "cms",
+      "files"
+    ],
+    "hasFunctions": false,
+    "byoKeys": [],
+    "configSrc": `import { defineConfig } from '@vxil/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\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
+// "Gallery" \u2014 an image / media gallery (albums of photos), declared end-to-end in
+// ONE typed file. A BLUEPRINT composing shipped building blocks \u2014
+//   \u2022 cms   \u2192 albums \u2192 photos (resolved by relation)
+//   \u2022 files \u2192 the actual image bytes (R2 + signed shared links)
+// The \`file\`-typed fields store a files-feature object ref; the item stays a
+// bounded JSONB document. Everything here is DATA the tenant owns and edits.
+// \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
+export default defineConfig({
+  env: 'staging',
+
+  features: {
+    cms: { draftPublish: true },
+    files: { enabled: true }, // R2-backed object store + shared links for the images
+  },
+
+  // \u2500\u2500 Schema-as-code: the cms collections (\u22648 index slots each: s1\u2013s4/n1\u2013n2/t1\u2013t2) \u2500\u2500
+  cms: {
+    collections: {
+      albums: {
+        singular: 'album',
+        fields: {
+          title: { type: 'string', required: true, indexSlot: 's1' },
+          slug: { type: 'string', indexSlot: 's2', validation: { unique: true } },
+          cover: { type: 'file' }, // a files-feature object ref (the album cover)
+          description: { type: 'text' },
+        },
+      },
+      photos: {
+        singular: 'photo',
+        fields: {
+          title: { type: 'string', indexSlot: 's1' },
+          image: { type: 'file', required: true }, // the photo bytes (via \`files\`)
+          album: { type: 'relation', relationTo: 'albums', indexSlot: 's2' },
+          taken_at: { type: 'datetime', indexSlot: 't1' },
+          width: { type: 'int', indexSlot: 'n1' },
+          height: { type: 'int', indexSlot: 'n2' },
+          tags: { type: 'json' }, // ["landscape","2024"] \u2014 $arrayContains-searchable
+        },
+      },
+    },
+  },
+
+  seed: {
+    cms: [
+      {
+        collection: 'albums',
+        items: [
+          { title: 'Travels', slug: 'travels', description: 'Photos from the road.' },
+        ],
+      },
+    ],
+  },
+});
+`,
+    "readme": "# Gallery template\n\nAn image / media gallery \u2014 declared end-to-end in one typed `vxil.config.ts`.\n\n**Provisions:**\n- `albums` \u2014 a titled, slugged collection with a `cover` image (a `files` object ref) and description.\n- `photos` \u2014 a `file`-typed `image` (the bytes live in `files` / R2), linked to an `album`, with `taken_at`,\n  `width`/`height`, and JSON `tags`. The `album` relation is slot-bound so you can list a single album's photos.\n\nThe `file`-typed fields hold a `files`-feature object ref; upload bytes through `files` (R2 + signed shared links)\nand store the returned `obj_\u2026` id on the item.\n\n**Use it:**\n\n```bash\nvxil init --template gallery\nvxil quickstart\nvxil push\nvxil gen\n```\n\n**Own the shape.** The config is yours after `init` \u2014 add EXIF fields, a `photographer` relation, more albums.\nNothing is locked.\n"
+  },
+  {
+    "id": "directory",
+    "title": "Listings Directory",
+    "vertical": "content",
+    "summary": "A categorized listings directory with user-submitted, owner-scoped entries and an admin publish step.",
+    "collections": [
+      "categories",
+      "listings"
+    ],
+    "features": [
+      "cms",
+      "auth"
+    ],
+    "hasFunctions": false,
+    "byoKeys": [],
+    "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// \"Directory\" \u2014 a listings directory (categorized listings people can submit),\n// declared end-to-end in ONE typed file. A BLUEPRINT composing shipped blocks \u2014\n//   \u2022 cms  \u2192 categories \u2192 listings (resolved by relation)\n//   \u2022 auth \u2192 accounts, so a submitter is a verified end-user\n// `listings.submitted_by` is the end-user OWNER field: in end-user mode a\n// submitter can only edit their OWN listing (a no-op for server callers). This\n// is one declarative flag, not a per-user policy. Everything here is DATA the\n// tenant owns and edits after `vxil init`.\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    cms: {\n      draftPublish: true, // submissions land as drafts; an admin publishes them\n      hooks: {\n        // Every listing needs a name \u2014 a pure function of the row (Lane-A validate).\n        listing_name: {\n          collection: 'listings',\n          event: 'beforeWrite',\n          kind: 'validate',\n          expr: 'len(item.name) > 0',\n          message: 'a listing needs a name',\n        },\n      },\n    },\n    auth: { methods: { emailPassword: true } }, // submitters sign in as end-users\n  },\n\n  // \u2500\u2500 Schema-as-code: the cms collections (\u22648 index slots each: s1\u2013s4/n1\u2013n2/t1\u2013t2) \u2500\u2500\n  cms: {\n    collections: {\n      categories: {\n        singular: 'category',\n        fields: {\n          name: { type: 'string', required: true, indexSlot: 's1' },\n          slug: { type: 'string', indexSlot: 's2', validation: { unique: true } },\n        },\n      },\n      listings: {\n        singular: 'listing',\n        // End-user owner-scope (docs/features/cms.md \xA715): a verified submitter may\n        // only read/edit their OWN listing. Server callers are unaffected.\n        ownerField: 'submitted_by',\n        fields: {\n          name: { type: 'string', required: true, indexSlot: 's1' },\n          slug: { type: 'string', indexSlot: 's2', validation: { unique: true } },\n          category: { type: 'relation', relationTo: 'categories', indexSlot: 's3' },\n          submitted_by: { type: 'string', indexSlot: 's4' }, // the owner (end-user) id\n          description: { type: 'text' },\n          website: { type: 'string' }, // stored, not indexed\n          location: { type: 'string' }, // stored, not indexed\n          featured: { type: 'bool' },\n          rating: { type: 'float', indexSlot: 'n1' },\n          submitted_at: { type: 'datetime', indexSlot: 't1' },\n        },\n      },\n    },\n  },\n\n  seed: {\n    cms: [\n      {\n        collection: 'categories',\n        items: [\n          { name: 'Restaurants', slug: 'restaurants' },\n          { name: 'Services', slug: 'services' },\n        ],\n      },\n    ],\n  },\n});\n",
+    "readme": "# Listings Directory template\n\nA categorized listings directory (people submit entries) \u2014 declared end-to-end in one typed `vxil.config.ts`.\n\n**Provisions:**\n- `categories` \u2014 name, unique slug.\n- `listings` \u2014 name, unique slug, `category` relation, `submitted_by` (the **owner field**), description,\n  website, location, `featured`, `rating`, `submitted_at`. A Lane-A hook requires a name; `draftPublish` lets\n  submissions land as drafts an admin publishes.\n- `auth` (email/password) \u2014 so a submitter is a **verified end-user**.\n\n**Owner-scoping.** `listings.ownerField = 'submitted_by'` means that in end-user mode a submitter can only\nread/edit their **own** listing (`docs/features/cms.md` \xA715) \u2014 one declarative flag, not a per-user policy, and a\nno-op for server callers.\n\n**Use it:**\n\n```bash\nvxil init --template directory\nvxil quickstart\nvxil push\nvxil gen\n```\n\n**Own the shape.** The config is yours after `init` \u2014 nothing is locked.\n"
+  },
+  {
+    "id": "catalog",
+    "title": "Product Catalog",
+    "vertical": "commerce",
+    "summary": "A content-only product catalog \u2014 browse/list products by category, with price, rating, and stock. (Checkout is the full examples/ecommerce blueprint.)",
+    "collections": [
+      "categories",
+      "products"
+    ],
+    "features": [
+      "cms"
+    ],
+    "hasFunctions": false,
+    "byoKeys": [],
+    "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// \"Catalog\" \u2014 a CONTENT-ONLY product catalog (browse/list products by category),\n// declared end-to-end in ONE typed file. A BLUEPRINT composing shipped blocks \u2014\n//   \u2022 cms \u2192 categories \u2192 products (resolved by relation)\n// This is the catalog CONTENT SHELL, not a storefront: checkout/inventory/orders\n// are the full `examples/ecommerce` blueprint (a reserve\u2192settle\u2192reverse saga in\n// tenant functions). Keep those in a function; a catalog is pure content.\n// Everything here is DATA the tenant owns and edits after `vxil init`.\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    cms: {\n      draftPublish: true, // draft products while staging; publish to list them\n      hooks: {\n        // Price (if given) can't be negative \u2014 a pure function of the row.\n        product_price: {\n          collection: 'products',\n          event: 'beforeWrite',\n          kind: 'validate',\n          expr: 'isNull(item.price_cents) || item.price_cents >= 0',\n          message: 'price_cents must be >= 0',\n        },\n      },\n    },\n  },\n\n  // \u2500\u2500 Schema-as-code: the cms collections (\u22648 index slots each: s1\u2013s4/n1\u2013n2/t1\u2013t2) \u2500\u2500\n  cms: {\n    collections: {\n      categories: {\n        singular: 'category',\n        fields: {\n          name: { type: 'string', required: true, indexSlot: 's1' },\n          slug: { type: 'string', indexSlot: 's2', validation: { unique: true } },\n        },\n      },\n      products: {\n        singular: 'product',\n        fields: {\n          title: { type: 'string', required: true, indexSlot: 's1' },\n          slug: { type: 'string', required: true, indexSlot: 's2', validation: { unique: true } },\n          category: { type: 'relation', relationTo: 'categories', indexSlot: 's3' },\n          brand: { type: 'string', indexSlot: 's4' },\n          price_cents: { type: 'int', indexSlot: 'n1', validation: { min: 0 } },\n          rating: { type: 'float', indexSlot: 'n2' },\n          description: { type: 'text' },\n          images: { type: 'json' }, // [\"obj_\u2026\", \u2026] file refs or urls\n          in_stock: { type: 'bool' },\n        },\n      },\n    },\n  },\n\n  seed: {\n    cms: [\n      {\n        collection: 'products',\n        items: [\n          { title: 'Aeron Chair', slug: 'aeron-chair', brand: 'Herman Miller', price_cents: 149900, rating: 4.8, in_stock: true },\n          { title: 'Standing Desk', slug: 'standing-desk', brand: 'Uplift', price_cents: 59900, rating: 4.6, in_stock: true },\n        ],\n      },\n    ],\n  },\n});\n",
+    "readme": "# Product Catalog template\n\nA **content-only** product catalog \u2014 declared end-to-end in one typed `vxil.config.ts`.\n\n**Provisions:**\n- `categories` \u2014 name + unique slug.\n- `products` \u2014 title, unique slug, `category` relation (slot-bound for filtering), brand, `price_cents`\n  (`min: 0`), rating, JSON `images`, `in_stock`. A Lane-A hook rejects a negative price.\n\n**This is the catalog shell, not a storefront.** Checkout, inventory, orders, and coupons \u2014 the transactional spine\n\u2014 are the full **`examples/ecommerce`** blueprint (a reserve\u2192settle\u2192reverse saga in tenant `functions`, plus the\noversell-safe `$inc` stock pattern and `guards[]` coupon caps). A catalog is pure content; add the commerce logic\nfrom that example when you need it.\n\n**Use it:**\n\n```bash\nvxil init --template catalog\nvxil quickstart\nvxil push\nvxil gen\n```\n\n**Own the shape.** The config is yours after `init` \u2014 nothing is locked.\n"
+  },
+  {
+    "id": "tasks",
+    "title": "Tasks (starter)",
+    "vertical": "starter",
+    "summary": "The minimal starter \u2014 one cms collection plus notifications. The default `vxil init` scaffold.",
+    "collections": [
+      "tasks"
+    ],
+    "features": [
+      "cms",
+      "notifications"
+    ],
+    "hasFunctions": false,
+    "byoKeys": [],
+    "configSrc": "import { defineConfig } from '@vxil/config';\n\n// \"Tasks\" \u2014 the minimal starter: one cms collection + notifications, declared\n// end-to-end in one typed file. The default `vxil init` scaffold. Everything\n// here is DATA you own and edit.\nexport default defineConfig({\n  env: 'staging',\n\n  // (a) per-feature config \u2014 the same TypeBox manifests, validated server-side.\n  features: {\n    cms: { draftPublish: true },\n    notifications: { provider: 'mock', fromEmail: 'noreply@example.app' },\n  },\n\n  // (b) CMS schema-as-code \u2014 collections + fields (reconciled by `vxil push`).\n  cms: {\n    collections: {\n      tasks: {\n        singular: 'task',\n        fields: {\n          title: { type: 'string', required: true, indexSlot: 's1' },\n          done: { type: 'bool' },\n          due: { type: 'datetime', indexSlot: 't1' },\n        },\n      },\n    },\n  },\n\n  // (c) functions \u2014 tenant code (\xA77.3, paid/opt-in). Uncomment to deploy.\n  // functions: {\n  //   hello: { entry: './functions/hello.ts', trigger: { kind: 'http' } },\n  // },\n});\n",
+    "readme": "# Tasks template (starter)\n\nThe minimal starter and the default `vxil init` scaffold \u2014 one `cms` collection (`tasks`) plus `notifications`.\n\n```bash\nvxil init            # scaffolds this template by default\nvxil quickstart\nvxil push\n```\n\nOwn the shape \u2014 add fields, add collections, uncomment the starter function. Nothing is locked.\n"
+  },
+  {
+    "id": "notes",
+    "title": "Notes (starter)",
+    "vertical": "starter",
+    "summary": "A single-collection notes app with no draft/publish lifecycle \u2014 the simplest possible backend.",
+    "collections": [
+      "notes"
+    ],
+    "features": [
+      "cms"
+    ],
+    "hasFunctions": false,
+    "byoKeys": [],
+    "configSrc": `import { defineConfig } from '@vxil/config';
+
+// "Notes" \u2014 a single-collection notes app (no draft/publish), declared end-to-end
+// in one typed file. A minimal starter. Everything here is DATA you own and edit.
+export default defineConfig({
+  env: 'staging',
+  features: { cms: { draftPublish: false } },
+  cms: {
+    collections: {
+      notes: {
+        singular: 'note',
+        fields: {
+          title: { type: 'string', required: true, indexSlot: 's1' },
+          body: { type: 'text' },
+          pinned: { type: 'bool' },
+        },
+      },
+    },
+  },
+});
+`,
+    "readme": "# Notes template (starter)\n\nThe simplest possible backend \u2014 one `cms` collection (`notes`), no draft/publish.\n\n```bash\nvxil init --template notes\nvxil quickstart\nvxil push\n```\n\nOwn the shape \u2014 nothing is locked.\n"
+  }
+];
+
+// bin/vxil.ts
+var DEFAULT_BASE = "https://api.vxil.com";
+var [, , cmd, ...rest] = process.argv;
+function flag(name) {
+  const i = rest.indexOf(`--${name}`);
+  return i >= 0 ? rest[i + 1] : void 0;
+}
+function hasFlag(name) {
+  return rest.includes(`--${name}`);
+}
+var jsonOut = rest.includes("--json");
+function fail(msg) {
+  console.error(`vxil: ${msg}`);
+  process.exit(1);
+}
+function positional(skip = 0) {
+  const out = [];
+  for (let i = 0; i < rest.length; i++) {
+    const t = rest[i];
+    if (t.startsWith("--")) {
+      if (rest[i + 1] && !rest[i + 1].startsWith("--")) i++;
+      continue;
+    }
+    out.push(t);
+  }
+  return out.slice(skip);
+}
+function printEnvelope({ status, body }) {
+  if (body.error) {
+    console.error(`error ${status}: ${body.error.code} \u2014 ${body.error.message}`);
+    if (body.error.hint) console.error(`hint: ${body.error.hint}`);
+    process.exit(1);
+  }
+  console.log(JSON.stringify(body.data, null, 2));
+}
+async function prompt(q, opts = {}) {
+  const stdin = process.stdin;
+  if (opts.hidden && stdin.isTTY && stdin.setRawMode) {
+    process.stdout.write(q);
+    return await new Promise((resolve5) => {
+      stdin.setRawMode(true);
+      stdin.resume();
+      let val = "";
+      const onData = (buf) => {
+        const ch = buf.toString("utf8");
+        if (ch === "\n" || ch === "\r" || ch === "") {
+          stdin.setRawMode(false);
+          stdin.pause();
+          stdin.removeListener("data", onData);
+          process.stdout.write("\n");
+          resolve5(val);
+        } else if (ch === "") {
+          stdin.setRawMode(false);
+          process.stdout.write("\n");
+          process.exit(130);
+        } else if (ch === "\x7F" || ch === "\b") {
+          val = val.slice(0, -1);
+        } else {
+          val += ch;
+        }
+      };
+      stdin.on("data", onData);
+    });
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return await new Promise((res) => rl.question(q, (a) => {
+    rl.close();
+    res(a.trim());
+  }));
+}
+function dashboardBase(edge) {
+  return process.env.VXIL_DASHBOARD_URL ?? edge.replace(/^https?:\/\/api\./, (m) => m.replace("api.", "app."));
+}
+async function dashFetch(base, method, path, body, cookie) {
+  const res = await fetch(`${base.replace(/\/$/, "")}${path}`, {
+    method,
+    headers: {
+      ...body !== void 0 ? { "content-type": "application/json" } : {},
+      ...cookie ? { cookie } : {},
+      "x-vxil-surface": "cli"
+    },
+    ...body !== void 0 ? { body: JSON.stringify(body) } : {}
+  });
+  const text = await res.text();
+  let json2 = {};
+  try {
+    json2 = JSON.parse(text);
+  } catch {
+    json2 = { raw: text.slice(0, 300) };
+  }
+  const setCookie = res.headers.get("set-cookie") ?? void 0;
+  return { status: res.status, json: json2, cookie: setCookie };
+}
+function makeDash(base) {
+  return (method, path, body, cookie) => dashFetch(base, method, path, body, cookie);
+}
+function persistLink(slug, tenantId, apiKey, base) {
+  const creds = loadCredentials();
+  creds.keys = { ...creds.keys, [slug]: apiKey };
+  saveCredentials(creds);
+  saveProject({ tenant_id: tenantId, slug, edge_url: base, env: flag("env") ?? "staging" });
+}
+async function resolveDashCookie(dash) {
+  const creds = loadCredentials();
+  if (creds.session) return creds.session;
+  const email = flag("email") ?? process.env.VXIL_DEV_EMAIL;
+  const password = flag("password") ?? process.env.VXIL_DEV_PASSWORD;
+  if (!email || !password) {
+    fail("need a dashboard session \u2014 run `vxil login`, or pass --email/--password (or set VXIL_DEV_EMAIL/VXIL_DEV_PASSWORD)");
+  }
+  const r = await dash("POST", "/dashboard/login", { email, password });
+  if (r.status !== 200) fail(`login failed: ${r.status} ${JSON.stringify(r.json).slice(0, 160)}`);
+  const cookie = r.cookie?.split(";")[0];
+  if (!cookie) fail("login succeeded but returned no session cookie");
+  return cookie;
+}
+function requireApi(which = "prod") {
+  const t = resolve_target({ which, defaultBase: DEFAULT_BASE });
+  if (!t.apiKey) {
+    fail("no API key \u2014 run `vxil quickstart` or `vxil link <slug>`, or set VXIL_API_KEY");
+  }
+  return { api: makeApi({ apiKey: t.apiKey, baseUrl: t.baseUrl }), baseUrl: t.baseUrl, slug: t.tenantSlug };
+}
+async function exportNdjson(feature) {
+  const t = resolve_target({ which: "prod", defaultBase: DEFAULT_BASE });
+  if (!t.apiKey) {
+    fail("no API key \u2014 run `vxil quickstart` or `vxil link <slug>`, or set VXIL_API_KEY");
+  }
+  const base = t.baseUrl.replace(/\/$/, "");
+  const get = async (path) => {
+    const res = await fetch(`${base}${path}`, {
+      headers: { authorization: `Bearer ${t.apiKey}`, "x-vxil-surface": "cli" }
+    });
+    const text = await res.text();
+    if (!res.ok) fail(`export failed (${res.status}): ${text.slice(0, 200)}`);
+    return {
+      lines: text.split("\n").filter((l) => l.length > 0),
+      nextAfter: res.headers.get("x-vxil-next-after")
+    };
+  };
+  const first = await get(`/v1/export/${feature}?format=ndjson`);
+  const lines = [...first.lines];
+  let truncated = [];
+  const last = lines.at(-1);
+  if (last) {
+    try {
+      const parsed = JSON.parse(last);
+      if (Array.isArray(parsed.truncated)) {
+        truncated = parsed.truncated;
+        lines.pop();
+      }
+    } catch {
+    }
+  }
+  for (const tr of truncated) {
+    if (!tr.after) {
+      console.error(`vxil: note \u2014 table '${tr.table}' hit the server row cap and has no resumable primary key; remaining rows not included`);
+      continue;
+    }
+    let after = tr.after;
+    while (after) {
+      const page = await get(
+        `/v1/export/${feature}?format=ndjson&table=${encodeURIComponent(tr.table)}&after=${encodeURIComponent(after)}`
+      );
+      lines.push(...page.lines.slice(1));
+      after = page.nextAfter;
+    }
+  }
+  const body = lines.join("\n") + "\n";
+  const out = flag("out");
+  if (out) {
+    writeFileSync3(resolve4(process.cwd(), out), body);
+    console.log(`exported ${feature} \u2192 ${out} (${lines.length} lines)`);
+  } else {
+    process.stdout.write(body);
+  }
+}
+async function runApply(apply, which = "prod") {
+  const { api } = requireApi(which);
+  const cfg = await loadVxilConfig();
+  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") });
+    console.log("\ncms.schema:");
+    console.log(formatCmsChanges(r.changes));
+    if (apply && r.applied) console.log(`  \u2713 applied ${r.applied} schema change(s)`);
+  }
+  const { functions: _fnFeature, ...configFeatures } = cfg.features;
+  void _fnFeature;
+  if (Object.keys(configFeatures).length) {
+    const results = await planOrPush({ api, features: configFeatures, apply });
+    for (const r of results) {
+      console.log(`
+${r.feature} (remote v${r.version}):`);
+      console.log(formatDiff(r.changes));
+      if (r.applied) console.log(`  \u2713 applied as v${r.applied}`);
+    }
+  }
+  if (cfg.functions && Object.keys(cfg.functions).length) {
+    const r = await planFunctions({ api, functions: cfg.functions, cwd, apply });
+    console.log("\nfunctions:");
+    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})`);
+    }
+  } 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).");
+  }
+  if (!apply) console.log("\n(run `vxil push` to apply)");
+  if (apply && !hasFlag("no-gen")) await runGen(which);
+}
+async function runServerApply(which) {
+  const { api } = requireApi(which);
+  const resume = flag("resume");
+  if (resume) {
+    const done2 = await serverApply({ api, resume });
+    console.log(formatApplySteps(done2.steps));
+    console.log(`
+apply ${done2.apply_id}: ${done2.status}`);
+    if (done2.status === "running") console.log(`resume with: vxil push --server --resume ${done2.apply_id}`);
+    if (done2.status !== "succeeded" && done2.status !== "running") process.exit(1);
+    if (done2.status === "succeeded" && !hasFlag("no-gen")) await runGen(which);
+    return;
+  }
+  const cfg = await loadVxilConfig();
+  const cwd = process.cwd();
+  const fnSources = {};
+  for (const [name, def] of Object.entries(cfg.functions ?? {})) {
+    fnSources[name] = (await bundleFunction(resolve4(cwd, def.entry), { projectRoot: cwd })).source;
+  }
+  const bundle = assembleApplyBundle(cfg, fnSources);
+  if (!Object.keys(bundle).length) fail("nothing to apply \u2014 vxil.config declares no features/cms/functions");
+  const done = await serverApply({
+    api,
+    bundle,
+    allowDestructive: hasFlag("allow-destructive"),
+    onPlan: (plan) => {
+      console.log(`plan (apply ${plan.apply_id}):`);
+      console.log(formatApplySteps(plan.steps));
+      for (const w of plan.warnings ?? []) console.log(`  ! ${w}`);
+      console.log("\napplying server-side\u2026");
+    }
+  });
+  console.log(formatApplySteps(done.steps));
+  console.log(`
+apply ${done.apply_id}: ${done.status}`);
+  if (done.status === "running") {
+    fail(`a transient step failure interrupted the apply \u2014 resume with: vxil push --server --resume ${done.apply_id}`);
+  }
+  if (done.status !== "succeeded") {
+    const f = done.failed_step;
+    fail(`apply ${done.status}${f ? ` \u2014 step ${f.seq} (${f.kind} ${f.target}): ${f.error}` : ""} (config/functions were rolled back to their pre-apply versions; cms schema additions were kept)`);
+  }
+  if (!hasFlag("no-gen")) await runGen(which);
+}
+async function runSeed(which, opts = {}) {
+  const { api } = requireApi(which);
+  const cfg = await loadVxilConfig();
+  const seed = cfg.seed;
+  if (!seed) {
+    if (opts.optional) return;
+    fail("no `seed` block in vxil.config");
+  }
+  let total = 0;
+  if (seed.users?.length) {
+    const res = await api("POST", "/v1/users/bulk", { users: seed.users });
+    if (res.status !== 200) printEnvelope(res);
+    total += seed.users.length;
+    console.log(`  \u2713 ${seed.users.length} users`);
+  }
+  for (const block of seed.cms ?? []) {
+    for (const item of block.items) {
+      const res = await api("POST", `/v1/cms/items/${encodeURIComponent(block.collection)}`, { data: item });
+      if (res.status !== 201 && res.status !== 200) printEnvelope(res);
+      total++;
+    }
+    console.log(`  \u2713 ${block.items.length} ${block.collection} items`);
+  }
+  console.log(`seeded ${total} record(s)`);
+}
+async function runGen(which = "prod", opts = {}) {
+  const offline = opts.offline ?? hasFlag("offline");
+  const out = flag("out") ?? "vxil.types.ts";
+  let features;
+  let collections;
+  let functions;
+  let tenant;
+  let env;
+  let apiVersions;
+  if (offline) {
+    const cfg = await loadVxilConfig();
+    env = cfg.env;
+    features = Object.keys(cfg.features);
+    collections = Object.entries(cfg.cms?.collections ?? {}).map(([collection, def]) => ({
+      collection,
+      ...def.singular ? { singular: def.singular } : {},
+      fields: Object.entries(def.fields).map(([field, f]) => ({
+        field,
+        type: f.type,
+        required: !!f.required,
+        index_slot: f.indexSlot ?? null,
+        ...f.relationTo ? { relation_to: f.relationTo } : {},
+        ...f.computed ? { computed: f.computed } : {}
+      }))
+    }));
+    functions = Object.entries(cfg.functions ?? {}).map(([name, def]) => ({
+      name,
+      ...def.signature ? { signature: def.signature } : {}
+    }));
+  } else {
+    const { api, slug } = requireApi(which);
+    tenant = slug;
+    const fres = await api("GET", "/v1/features");
+    features = fres.body.data?.features ?? [];
+    apiVersions = fres.body.data?.api_versions;
+    const cres = await api("GET", "/v1/cms/collections");
+    collections = cres.body.data?.collections ?? [];
+    const fnres = await api("GET", "/v1/functions");
+    functions = (fnres.body.data?.functions ?? []).map((f) => ({
+      name: f.name,
+      ...f.signature ? { signature: f.signature } : {},
+      ...f.trigger ? { trigger: f.trigger } : {}
+    }));
+  }
+  const genInput = {
+    ...tenant ? { tenant } : {},
+    ...env ? { env } : {},
+    features,
+    collections,
+    functions,
+    ...apiVersions ? { apiVersions } : {},
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  const src = generateTypes(genInput);
+  const emitMcp = !hasFlag("no-mcp");
+  const mcpOut = flag("mcp-out") ?? "vxil.mcp.json";
+  const catalog = emitMcp ? buildMcpCatalog(genInput) : void 0;
+  const mcpPath = resolve4(process.cwd(), mcpOut);
+  const outPath = resolve4(process.cwd(), out);
+  const body = (s) => {
+    const i = s.indexOf("export interface VxilSchema");
+    return i >= 0 ? s.slice(i) : s;
+  };
+  const counts = {
+    features: features.length,
+    collections: collections.length,
+    functions: functions.length,
+    ...catalog ? { tools: catalog.tools.length } : {}
+  };
+  if (hasFlag("check")) {
+    const existing = existsSync3(outPath) ? readFileSync2(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 (existsSync3(mcpPath)) {
+        try {
+          const cur = JSON.parse(readFileSync2(mcpPath, "utf8"));
+          const want = JSON.parse(JSON.stringify(catalog));
+          delete cur.generated_at;
+          delete want.generated_at;
+          upToDate = JSON.stringify(cur) === JSON.stringify(want);
+        } catch {
+          upToDate = false;
+        }
+      }
+      if (!upToDate) {
+        fail(`${mcpOut} is out of date (drift) \u2014 run \`vxil gen\` and commit. A collection/feature/function changed since it was generated.`);
+      }
+    }
+    if (jsonOut) console.log(JSON.stringify({ ok: true, check: "up-to-date", ...counts }));
+    else console.log(`vxil gen --check: ${out}${catalog ? ` + ${mcpOut}` : ""} is up to date.`);
+    return;
+  }
+  writeFileSync3(outPath, src);
+  if (catalog) writeFileSync3(mcpPath, `${JSON.stringify(catalog, null, 2)}
+`);
+  if (jsonOut) console.log(JSON.stringify({ ok: true, out, ...catalog ? { mcp_out: mcpOut } : {}, ...counts }));
+  else console.log(`vxil gen \u2192 ${out}${catalog ? ` + ${mcpOut}` : ""}  (${features.length} features \xB7 ${collections.length} collections \xB7 ${functions.length} functions${catalog ? ` \xB7 ${catalog.tools.length} mcp tools` : ""})`);
+}
+async function runWatch(which) {
+  const cwd = process.cwd();
+  console.log("vxil dev --watch: applying on save (Ctrl-C to stop)\u2026");
+  const apply = async () => {
+    try {
+      await runApply(true, which);
+    } catch (e) {
+      console.error("  apply error:", e.message.split("\n")[0]);
+    }
+  };
+  await apply();
+  let timer = null;
+  const trigger = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      const now = (/* @__PURE__ */ new Date()).toTimeString().slice(0, 8);
+      console.log(`
+[${now}] change detected \u2014 applying\u2026`);
+      void apply();
+    }, 300);
+  };
+  const watchers = [];
+  const cfgFile = CONFIG_FILENAMES.map((n) => resolve4(cwd, n)).find((f) => existsSync3(f));
+  if (cfgFile) watchers.push(watch(cfgFile, trigger));
+  for (const dir of ["functions", "cms"]) {
+    const d = resolve4(cwd, dir);
+    if (existsSync3(d)) watchers.push(watch(d, trigger));
+  }
+  process.on("SIGINT", () => {
+    for (const w of watchers) w.close();
+    console.log("\nvxil dev --watch stopped.");
+    process.exit(0);
+  });
+  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);
+}
+async function prodPromotionGate() {
+  const cfg = await loadVxilConfig();
+  const mocks = mockFeatures(cfg);
+  if (mocks.length && !hasFlag("allow-mock-in-prod")) {
+    fail(`refusing to push to PROD: 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.`);
+  }
+  if (!hasFlag("yes")) {
+    const proj = loadProject();
+    const ans = await prompt(`push to PROD tenant '${proj?.slug ?? "(linked)"}'? type the slug (or "yes") to confirm: `);
+    if (ans !== proj?.slug && ans !== "yes") fail("confirmation did not match \u2014 aborted.");
+  }
+}
+async function runDoctor() {
+  const checks = [];
+  let cfg = null;
+  try {
+    cfg = await loadVxilConfig();
+    checks.push({ name: "config loads", ok: true, detail: `${Object.keys(cfg.features).length} features \xB7 ${Object.keys(cfg.cms?.collections ?? {}).length} collections \xB7 ${Object.keys(cfg.functions ?? {}).length} functions` });
+  } catch (e) {
+    checks.push({ name: "config loads", ok: false, detail: e.message.split("\n")[0] ?? "load failed" });
+  }
+  const t = resolve_target({ defaultBase: DEFAULT_BASE });
+  checks.push({ name: "tenant binding", ok: !!t.apiKey, detail: t.apiKey ? `key resolved (${t.tenantSlug ?? "env"}) \xB7 edge ${t.baseUrl}` : "no key \u2014 run `vxil quickstart` or `vxil link <slug> --key <k>`" });
+  if (t.apiKey) {
+    const api = makeApi({ apiKey: t.apiKey, baseUrl: t.baseUrl });
+    const fres = await api("GET", "/v1/features");
+    if (fres.status === 200) {
+      const live = new Set(fres.body.data?.features ?? []);
+      checks.push({ name: "edge reachable", ok: true, detail: `${live.size} features enabled live` });
+      if (cfg) {
+        const declared = Object.keys(cfg.features).filter((f) => f !== "functions");
+        const missing = declared.filter((f) => !live.has(f));
+        checks.push({ name: "config\u2194live parity", ok: missing.length === 0, detail: missing.length ? `declared but not live: ${missing.join(", ")} (run \`vxil push\`)` : "in sync" });
+      }
+    } else {
+      checks.push({ name: "edge reachable", ok: false, detail: `GET /v1/features \u2192 ${fres.status}` });
+    }
+  }
+  if (cfg?.functions) {
+    for (const [n, def] of Object.entries(cfg.functions)) {
+      const ok = existsSync3(resolve4(process.cwd(), def.entry));
+      checks.push({ name: `function '${n}' entry`, ok, detail: ok ? def.entry : `missing file: ${def.entry}` });
+    }
+  }
+  if (cfg) {
+    const mocks = mockFeatures(cfg);
+    if (mocks.length) checks.push({ name: "mock providers", ok: true, detail: `mock on [${mocks.join(", ")}] \u2014 fine for dev; \`push --prod\` blocks these` });
+  }
+  if (jsonOut) {
+    console.log(JSON.stringify({ ok: checks.every((c) => c.ok), checks }));
+  } else {
+    for (const c of checks) console.log(`  ${c.ok ? "\u2713" : "\u2717"} ${c.name}: ${c.detail}`);
+  }
+  if (!checks.every((c) => c.ok)) process.exit(2);
+}
+var STARTER_FN = `// A vxil function \u2014 a Web-standard fetch handler. It receives the invocation
+// envelope { tenant_id, vxil_base, scoped_jwts, secrets, payload } and may call your
+// enabled features with the per-feature scoped tokens.
+export default {
+  async fetch(req: Request): Promise<Response> {
+    const env = await req.json().catch(() => ({})) as { payload?: { name?: string } };
+    return Response.json({ ok: true, hello: env.payload?.name ?? 'world' });
+  },
+};
+`;
+var TRY_CONFIG = `import { defineConfig } from '@vxil/config';
+
+// Scaffolded by \`vxil try\` \u2014 the keyless sandbox starter (cms + comments +
+// rate-limits, zero BYO keys). This backend self-expires in ~2h; run
+// \`vxil push\` to materialize the collections server-side.
+export default defineConfig({
+  env: 'staging',
+  features: {
+    cms: { draftPublish: true },
+    comments: {},
+    'rate-limits': {},
+  },
+  cms: {
+    collections: {
+      tasks: {
+        singular: 'task',
+        fields: {
+          title: { type: 'string', required: true, indexSlot: 's1' },
+          done:  { type: 'bool' },
+        },
+      },
+    },
+  },
+});
+`;
+function scaffoldProject(configSrc) {
+  const cwd = process.cwd();
+  writeFileSync3(resolve4(cwd, "vxil.config.ts"), configSrc);
+  mkdirSync2(resolve4(cwd, "functions"), { recursive: true });
+  if (!existsSync3(resolve4(cwd, "functions/hello.ts"))) writeFileSync3(resolve4(cwd, "functions/hello.ts"), STARTER_FN);
+  mkdirSync2(resolve4(cwd, ".vxil"), { recursive: true });
+  const gi = resolve4(cwd, ".gitignore");
+  const ignore = ["", "# vxil", ".vxil/", ".env.local", ""].join("\n");
+  if (!existsSync3(gi) || !readFileSync2(gi, "utf8").includes(".vxil/")) appendFileSync(gi, ignore);
+}
+function initProject() {
+  const cwd = process.cwd();
+  const cfgPath = resolve4(cwd, "vxil.config.ts");
+  if (existsSync3(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(", ")}`);
+  scaffoldProject(tpl.configSrc);
+  console.log(`scaffolded from template '${tpl.id}' (${tpl.title}):`);
+  console.log(`  vxil.config.ts     # ${tpl.summary}`);
+  console.log(`                     # collections: ${tpl.collections.join(", ")} \xB7 features: ${tpl.features.join(", ")}`);
+  console.log("  functions/hello.ts # a starter function (\xA77.3)");
+  console.log("  .vxil/             # project binding (gitignored)");
+  console.log("\nnext: `vxil quickstart` (new tenant) or `vxil link <slug>` (existing), then `vxil push`.");
+}
+function listTemplates() {
+  console.log("vxil templates \u2014 the Blueprint Gallery. Scaffold one with `vxil init --template <id>`.\n");
+  const pad = Math.max(...TEMPLATE_CATALOG.map((t) => t.id.length));
+  for (const t of TEMPLATE_CATALOG) {
+    const fns = t.hasFunctions ? " \xB7 +functions" : "";
+    console.log(`  ${t.id.padEnd(pad)}  ${t.title}  [${t.vertical}${fns}]`);
+    console.log(`  ${" ".repeat(pad)}  ${t.summary}`);
+  }
+  console.log("\nEach template is a typed vxil.config.ts you clone and OWN \u2014 no platform lock over the shape.");
+}
+try {
+  switch (cmd) {
+    case "init": {
+      initProject();
+      break;
+    }
+    case "templates": {
+      listTemplates();
+      break;
+    }
+    case "quickstart": {
+      const base = process.env.VXIL_BASE_URL ?? DEFAULT_BASE;
+      const dash = dashboardBase(base);
+      const email = flag("email") ?? await prompt("email: ");
+      const password = flag("password") ?? await prompt("password (>=10 chars): ", { hidden: true });
+      const featuresArg = flag("features") ?? "cms,notifications";
+      const appName = flag("name") ?? "vxil-app";
+      const body = {
+        email,
+        password,
+        app_name: appName,
+        features: featuresArg.split(",").map((s) => s.trim()).filter(Boolean),
+        // --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) } : {},
+        // --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") } : {}
+      };
+      const r = await dashFetch(dash, "POST", "/dashboard/quickstart", body);
+      if (r.status !== 201 && r.status !== 200) {
+        const e = r.json.error ?? {};
+        if (e.code === "invite_required") {
+          fail("quickstart: this backend is invite-only for NEW accounts \u2014 re-run with `--invite <code>` (existing accounts pass with just email+password).");
+        }
+        if (e.code === "invite_invalid") {
+          fail("quickstart: that invite code is invalid or already used \u2014 each code works once; ask for a fresh one.");
+        }
+        fail(`quickstart failed: ${e.code ?? r.status} ${e.message ?? JSON.stringify(r.json).slice(0, 200)}`);
+      }
+      const d = r.json.data ?? r.json;
+      if (!d.api_key || !d.tenant_id || !d.app_slug) fail("quickstart returned no api_key/tenant");
+      const creds = loadCredentials();
+      creds.keys = { ...creds.keys, [d.app_slug]: d.api_key };
+      saveCredentials(creds);
+      saveProject({ tenant_id: d.tenant_id, slug: d.app_slug, edge_url: d.edge_url ?? base, env: flag("env") ?? "staging" });
+      if (!existsSync3(resolve4(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)`);
+      if (!hasFlag("no-push")) {
+        console.log("\napplying your config (cms schema \u2192 config \u2192 functions) + generating types\u2026");
+        await runApply(true);
+      }
+      let firstCollection = "your-collection";
+      try {
+        const c = await loadVxilConfig();
+        firstCollection = Object.keys(c.cms?.collections ?? {})[0] ?? firstCollection;
+      } catch {
+      }
+      const spaOrigin = (() => {
+        try {
+          return d.sdk_url ? new URL(d.sdk_url).origin : base;
+        } catch {
+          return base;
+        }
+      })();
+      console.log(`
+  \u2728 your backend is live`);
+      console.log(`     dashboard:  ${spaOrigin}/dashboard`);
+      console.log(`     api:        ${d.edge_url ?? base}`);
+      console.log(`     types:      ./vxil.types.ts  (generated \u2014 re-run \`vxil gen\` after a schema change)`);
+      console.log(`     try it:`);
+      console.log(`       import { Vxil } from '@vxil/sdk';`);
+      console.log(`       import type { VxilSchema } from './vxil.types';`);
+      console.log(`       const vx = Vxil.connect<VxilSchema>({ apiKey });   // narrows to YOUR enabled features`);
+      console.log(`       await vx.from('${firstCollection}').create({ /* field-typed */ });`);
+      console.log(`
+  key stored in ~/.vxil/credentials.json \xB7 project bound in .vxil/project.json`);
+      break;
+    }
+    case "try": {
+      const base = process.env.VXIL_BASE_URL ?? DEFAULT_BASE;
+      const tfetch = async (url, reqBody) => {
+        const res = await fetch(url, {
+          method: "POST",
+          headers: { "content-type": "application/json", "x-vxil-surface": "cli" },
+          body: JSON.stringify(reqBody)
+        });
+        const text = await res.text();
+        let json2 = {};
+        try {
+          json2 = JSON.parse(text);
+        } catch {
+          json2 = { raw: text.slice(0, 300) };
+        }
+        return { status: res.status, json: json2 };
+      };
+      const turnstile = flag("turnstile");
+      const outcome = await mintTry(tfetch, base, turnstile ? { turnstileToken: turnstile } : {});
+      if (!outcome.ok) fail(`vxil try: ${outcome.message}`);
+      const { result } = outcome;
+      const creds = loadCredentials();
+      creds.keys = { ...creds.keys, [result.slug]: result.api_key };
+      saveCredentials(creds);
+      saveProject({
+        tenant_id: result.tenant_id,
+        slug: result.slug,
+        edge_url: base,
+        env: flag("env") ?? "staging",
+        ephemeral: true,
+        ...result.expires_at ? { expires_at: result.expires_at } : {}
+      });
+      if (!existsSync3(resolve4(process.cwd(), "vxil.config.ts"))) scaffoldProject(TRY_CONFIG);
+      let genOk = true;
+      try {
+        await runGen("prod", { offline: true });
+      } catch (e) {
+        genOk = false;
+        console.log(`  (typed-client generation skipped: ${String(e.message).split("\n")[0]})`);
+      }
+      let firstCollection = "your-collection";
+      try {
+        const c = await loadVxilConfig();
+        firstCollection = Object.keys(c.cms?.collections ?? {})[0] ?? firstCollection;
+      } catch {
+      }
+      for (const l of renderTryReport(result, { base, collection: firstCollection, genOk })) console.log(l);
+      break;
+    }
+    case "login": {
+      const base = process.env.VXIL_BASE_URL ?? DEFAULT_BASE;
+      const dash = dashboardBase(base);
+      const email = flag("email") ?? await prompt("email: ");
+      const password = flag("password") ?? await prompt("password: ", { hidden: true });
+      const r = await dashFetch(dash, "POST", "/dashboard/login", { email, password });
+      if (r.status !== 200) fail(`login failed: ${r.status} ${JSON.stringify(r.json).slice(0, 160)}`);
+      const cookie = r.cookie?.split(";")[0];
+      if (!cookie) fail("login succeeded but returned no session cookie");
+      const creds = loadCredentials();
+      creds.session = cookie;
+      saveCredentials(creds);
+      console.log("\u2713 logged in \u2014 session stored in ~/.vxil/credentials.json");
+      break;
+    }
+    case "link": {
+      const slug = positional(0)[0];
+      if (!slug) fail("usage: vxil link <slug> [--key <api_key>] [--tenant <id>]");
+      const base = process.env.VXIL_BASE_URL ?? DEFAULT_BASE;
+      const directKey = flag("key");
+      if (directKey) {
+        const tenantId = flag("tenant") ?? "(unknown)";
+        const creds2 = loadCredentials();
+        creds2.keys = { ...creds2.keys, [slug]: directKey };
+        saveCredentials(creds2);
+        saveProject({ tenant_id: tenantId, slug, edge_url: base, env: flag("env") ?? "staging" });
+        console.log(`\u2713 linked '${slug}' (using provided --key)`);
+        break;
+      }
+      const dash = makeDash(dashboardBase(base));
+      const creds = loadCredentials();
+      const keyName = `cli-${hostname()}`.slice(0, 100);
+      if (creds.session) {
+        const r = await linkViaSession(dash, creds.session, slug, keyName);
+        if ("result" in r) {
+          persistLink(r.result.slug, r.result.tenant_id, r.result.api_key, base);
+          console.log(`\u2713 linked '${slug}' (minted a key via your dashboard session)`);
+          break;
+        }
+        console.error("session expired \u2014 falling back to the browser link flow\u2026");
+      }
+      if (!process.stdout.isTTY && !process.stdin.isTTY) {
+        fail("link without --key needs an interactive terminal (browser approval) or a `vxil login` session; in CI pass --key <api_key> (or set VXIL_API_KEY)");
+      }
+      {
+        const linked = await linkViaDeviceFlow(dash, slug, {
+          log: (l) => console.log(l),
+          sleep: (ms) => new Promise((r) => setTimeout(r, ms))
+        });
+        persistLink(linked.slug, linked.tenant_id, linked.api_key, base);
+        console.log(`
+\u2713 linked '${linked.slug}' (approved in the browser)`);
+      }
+      break;
+    }
+    case "plan":
+    case "diff": {
+      await runApply(false);
+      break;
+    }
+    case "push": {
+      const dev = hasFlag("dev");
+      if (hasFlag("prod") && !dev) await prodPromotionGate();
+      if (hasFlag("server") || flag("resume") !== void 0) {
+        await runServerApply(dev ? "dev" : "prod");
+        break;
+      }
+      await runApply(true, dev ? "dev" : "prod");
+      break;
+    }
+    case "gen":
+    case "types": {
+      await runGen();
+      break;
+    }
+    case "doctor": {
+      await runDoctor();
+      break;
+    }
+    case "versions": {
+      const feature = positional(0)[0];
+      if (!feature) fail("usage: vxil versions <feature>");
+      const { api } = requireApi();
+      printEnvelope(await api("GET", `/v1/config/${feature}/versions`));
+      break;
+    }
+    case "rollback": {
+      const feature = positional(0)[0];
+      const to = flag("to");
+      if (!feature || !to) fail("usage: vxil rollback <feature> --to <version>");
+      const { api } = requireApi();
+      const res = await api("POST", `/v1/config/${feature}/versions/${to}/rollback`);
+      if (res.body.error) printEnvelope(res);
+      else console.log(`\u2713 rolled ${feature} back to v${to} (now v${res.body.data?.version ?? "?"}). Re-run \`vxil gen\` if the schema changed.`);
+      break;
+    }
+    case "pull": {
+      const { api } = requireApi();
+      const fres = await api("GET", "/v1/features");
+      const features = fres.body.data?.features ?? [];
+      const featBlocks = {};
+      for (const f of features) {
+        const c = await api("GET", `/v1/config/${f}`);
+        if (c.status === 200) featBlocks[f] = c.body.data?.manifest ?? {};
+      }
+      const cres = await api("GET", "/v1/cms/collections");
+      const collections = cres.body.data?.collections ?? [];
+      const cmsBlock = {};
+      for (const col of collections) {
+        const fields = {};
+        for (const fd of col.fields) {
+          const d = { type: fd.type };
+          if (fd.required) d.required = true;
+          if (fd.index_slot) d.indexSlot = fd.index_slot;
+          if (fd.relation_to) d.relationTo = fd.relation_to;
+          fields[fd.field] = d;
+        }
+        cmsBlock[col.collection] = { ...col.singular ? { singular: col.singular } : {}, fields };
+      }
+      const src = `import { defineConfig } from '@vxil/config';
+
+// Materialized from the live tenant by \`vxil pull\` on ${(/* @__PURE__ */ new Date()).toISOString()}.
+export default defineConfig(${JSON.stringify({ features: featBlocks, cms: { collections: cmsBlock } }, null, 2)});
+`;
+      const out = flag("out") ?? "vxil.config.ts";
+      if (existsSync3(resolve4(process.cwd(), out)) && !hasFlag("force")) fail(`${out} exists (use --force or --out <file>)`);
+      writeFileSync3(resolve4(process.cwd(), out), src);
+      console.log(`vxil pull \u2192 ${out}  (${features.length} features \xB7 ${collections.length} collections)`);
+      break;
+    }
+    case "env": {
+      const [sub] = positional(0);
+      if (sub !== "pull") fail("usage: vxil env pull [--dev] [--file <path=.env.local>] [--print] [--no-gitignore]");
+      runEnvPull(hasFlag("dev") ? "dev" : "prod");
+      break;
+    }
+    case "secrets": {
+      const [sub] = positional(0);
+      const { api } = requireApi();
+      if (sub === "set") {
+        const ref = positional(1)[0];
+        if (!ref) fail("usage: vxil secrets set <feature>/<name> [--value <v>]  (or set from vxil.config secrets)");
+        const [feature, name] = ref.includes("/") ? ref.split("/") : [void 0, ref];
+        let f = feature;
+        let n = name;
+        if (!feature) {
+          const cfg = await loadVxilConfig();
+          const decl = cfg.secrets?.[ref];
+          if (!decl) fail(`secret '${ref}' not declared in vxil.config (use <feature>/<name>)`);
+          f = decl.feature;
+          n = ref;
+        }
+        const value = flag("value") ?? await prompt(`value for ${f}/${n}: `, { hidden: true });
+        const res = await api("PUT", `/v1/secrets/${f}/${n}`, { value });
+        if (res.status !== 200) printEnvelope(res);
+        else {
+          console.log(`\u2713 secret ${f}/${n} set (ref: secret:${n})`);
+          const co = res.body.data?.co_rotate;
+          if (co?.message) console.log(`note: ${co.message}`);
+        }
+      } else if (sub === "list") {
+        const feature = flag("feature");
+        const res = await api("GET", `/v1/secrets${feature ? `?feature=${encodeURIComponent(feature)}` : ""}`);
+        if (res.body.error) printEnvelope(res);
+        else if (jsonOut) console.log(JSON.stringify(res.body.data, null, 2));
+        else {
+          const rows = res.body.data?.secrets ?? [];
+          if (!rows.length) console.log("(no secrets stored)");
+          for (const r of rows) {
+            console.log(`  ${r.feature}/${r.secret_name}  (ref secret:${r.secret_name} \xB7 rotated ${r.rotated_at})`);
+          }
+        }
+      } else if (sub === "rm") {
+        const ref = positional(1)[0];
+        if (!ref?.includes("/")) fail("usage: vxil secrets rm <feature>/<name> [--yes]");
+        const [feature, name] = ref.split("/");
+        if (!hasFlag("yes")) {
+          const ans = await prompt(`delete secret ${ref}? type the name to confirm: `);
+          if (ans !== name) fail("confirmation did not match \u2014 aborted.");
+        }
+        const res = await api("DELETE", `/v1/secrets/${encodeURIComponent(feature)}/${encodeURIComponent(name)}`);
+        if (res.body.error) printEnvelope(res);
+        else console.log(`\u2713 secret ${ref} deleted \u2014 configs still holding ref secret:${name} will fail until re-set`);
+      } else {
+        fail("usage: vxil secrets set|list|rm");
+      }
+      break;
+    }
+    case "seed": {
+      await runSeed(hasFlag("dev") ? "dev" : "prod");
+      break;
+    }
+    case "export": {
+      const feature = positional(0)[0];
+      if (!feature) fail("usage: vxil export <feature> [--out <file>] [--ndjson]");
+      if (hasFlag("ndjson")) {
+        await exportNdjson(feature);
+        break;
+      }
+      const { api } = requireApi();
+      const res = await api("GET", `/v1/export/${feature}`);
+      if (res.body.error) printEnvelope(res);
+      const out = flag("out");
+      const json2 = JSON.stringify(res.body.data ?? res.body, null, 2);
+      if (out) {
+        writeFileSync3(resolve4(process.cwd(), out), json2);
+        console.log(`exported ${feature} \u2192 ${out}`);
+      } else console.log(json2);
+      break;
+    }
+    case "import": {
+      const feature = positional(0)[0];
+      const file = flag("file");
+      if (!feature || !file) fail("usage: vxil import <feature> --file <bundle.json> [--mode merge|replace]");
+      const { api } = requireApi(hasFlag("dev") ? "dev" : "prod");
+      const bundle = JSON.parse(readFileSync2(resolve4(process.cwd(), file), "utf8"));
+      printEnvelope(await api("POST", `/v1/import/${feature}`, { bundle, mode: flag("mode") ?? "merge" }));
+      break;
+    }
+    case "functions": {
+      const [sub, name] = positional(0);
+      if (sub === "new") {
+        if (!name) fail("usage: vxil functions new <name>");
+        mkdirSync2(resolve4(process.cwd(), "functions"), { recursive: true });
+        const p = resolve4(process.cwd(), `functions/${name}.ts`);
+        if (existsSync3(p) && !hasFlag("force")) fail(`functions/${name}.ts exists`);
+        writeFileSync3(p, STARTER_FN);
+        console.log(`scaffolded functions/${name}.ts \u2014 declare it in vxil.config.ts \`functions\` and \`vxil push\``);
+      } else if (sub === "list") {
+        const { api } = requireApi();
+        printEnvelope(await api("GET", "/v1/functions"));
+      } else if (sub === "delete") {
+        if (!name) fail("usage: vxil functions delete <name>");
+        const { api } = requireApi();
+        printEnvelope(await api("DELETE", `/v1/functions/${encodeURIComponent(name)}`));
+      } else if (sub === "deploy") {
+        const { api } = requireApi();
+        const cfg = await loadVxilConfig();
+        const fns = cfg.functions ?? {};
+        const subset = name ? { [name]: fns[name] } : fns;
+        if (name && !fns[name]) fail(`function '${name}' not declared in vxil.config`);
+        const r = await planFunctions({ api, functions: subset, cwd: process.cwd(), apply: true });
+        console.log(formatFnChanges(r.changes));
+        console.log(`\u2713 deployed ${r.applied} function(s)`);
+      } else if (sub === "logs") {
+        if (!name) fail("usage: vxil functions logs <name> [--since <iso>] [--tail]");
+        const { api } = requireApi(hasFlag("dev") ? "dev" : "prod");
+        let since = flag("since");
+        const fetchPage = async () => {
+          const qs = since ? `?since=${encodeURIComponent(since)}` : "";
+          const res = await api("GET", `/v1/functions/${encodeURIComponent(name)}/logs${qs}`);
+          if (res.body.error) printEnvelope(res);
+          const data2 = res.body.data;
+          if (data2.lines.length) console.log(formatLogLines(data2.lines));
+          if (data2.next_since) since = data2.next_since;
+        };
+        await fetchPage();
+        if (hasFlag("tail")) {
+          console.error(`tailing '${name}' (Ctrl-C to stop)\u2026`);
+          while (true) {
+            await new Promise((r) => setTimeout(r, 3e3));
+            await fetchPage();
+          }
+        }
+      } else if (sub === "invoke") {
+        if (!name) fail("usage: vxil functions invoke <name> [--data '<json>'] [--async]");
+        const which = hasFlag("dev") ? "dev" : "prod";
+        const { api, baseUrl } = requireApi(which);
+        let payload = {};
+        const raw = flag("data");
+        if (raw !== void 0) {
+          try {
+            payload = JSON.parse(raw);
+          } catch {
+            fail("--data must be valid JSON");
+          }
+        }
+        if (hasFlag("async")) {
+          const proj = loadProject();
+          const tenantId = which === "dev" ? proj?.dev?.tenant_id : proj?.tenant_id;
+          if (!tenantId) fail("`--async` needs a linked tenant (run `vxil link <slug>` or `vxil quickstart`)");
+          printEnvelope(await api("POST", "/v1/jobs/enqueue", {
+            job_name: `fn-queue:${name}`,
+            target_url: `${baseUrl.replace(/\/$/, "")}/v1/internal/fn/trigger/${encodeURIComponent(name)}?tenant=${tenantId}`,
+            payload: { trigger: "queue", payload },
+            idempotency_key: `fnq:${name}:${Date.now()}`
+          }));
+        } else {
+          const res = await api("POST", `/v1/fn/${encodeURIComponent(name)}`, payload);
+          if (res.body.error) printEnvelope(res);
+          else console.log(JSON.stringify(res.body.data ?? res.body, null, 2));
+        }
+      } else if (sub === "dev") {
+        if (!name) fail("usage: vxil functions dev <name> [--port <n>]");
+        await runFunctionsDev(name);
+      } else {
+        fail("usage: vxil functions new|deploy|list|delete|invoke|logs|dev <name>");
+      }
+      break;
+    }
+    case "cms": {
+      const [sub] = positional(0);
+      const { api } = requireApi();
+      if (sub === "status") {
+        printEnvelope(await api("GET", "/v1/cms/collections"));
+      } else if (sub === "pull") {
+        printEnvelope(await api("GET", "/v1/cms/collections"));
+      } else {
+        fail("usage: vxil cms status|pull");
+      }
+      break;
+    }
+    case "dev": {
+      const [sub] = positional(0);
+      if (hasFlag("watch") || sub === "watch") {
+        await runWatch("dev");
+        break;
+      }
+      await runDev(sub);
+      break;
+    }
+    // ── existing day-to-day helpers (unchanged) ──────────────────────────────
+    case "config": {
+      const [sub, feature] = rest;
+      if (sub !== "get" || !feature) fail("usage: vxil config get <feature>");
+      const { api } = requireApi();
+      printEnvelope(await api("GET", `/v1/config/${feature}`));
+      break;
+    }
+    case "users": {
+      const { api } = requireApi();
+      const [sub, id] = rest;
+      if (sub === "add") {
+        if (!id) fail("usage: vxil users add <id> --email <email>");
+        printEnvelope(await api("POST", "/v1/users", { id, email: flag("email") }));
+      } else if (sub === "list") {
+        const email = flag("email");
+        printEnvelope(await api("GET", `/v1/users${email ? `?email=${encodeURIComponent(email)}` : ""}`));
+      } else fail("usage: vxil users add|list");
+      break;
+    }
+    case "send": {
+      const { api } = requireApi();
+      const [userId, template] = rest;
+      if (!userId || !template) fail("usage: vxil send <user_id> <template> --data '<json>'");
+      let data2 = {};
+      const raw = flag("data");
+      try {
+        data2 = raw ? JSON.parse(raw) : {};
+      } catch {
+        fail("--data must be valid JSON");
+      }
+      printEnvelope(await api("POST", "/v1/notifications/send", { user_id: userId, template, data: data2 }));
+      break;
+    }
+    case "deliveries": {
+      const { api } = requireApi();
+      const qs = new URLSearchParams();
+      const user = flag("user");
+      if (user) qs.set("user_id", user);
+      const status = flag("status");
+      if (status) qs.set("status", status);
+      const s = qs.toString();
+      printEnvelope(await api("GET", `/v1/notifications/deliveries${s ? `?${s}` : ""}`));
+      break;
+    }
+    case "api": {
+      const { api } = requireApi();
+      const [method, path] = rest;
+      if (!method || !path?.startsWith("/")) fail("usage: vxil api <GET|POST|PUT|PATCH|DELETE> </v1/...> [--data '<json>']");
+      let body;
+      const raw = flag("data");
+      if (raw !== void 0) {
+        try {
+          body = JSON.parse(raw);
+        } catch {
+          fail("--data must be valid JSON");
+        }
+      }
+      printEnvelope(await api(method.toUpperCase(), path, body));
+      break;
+    }
+    default:
+      console.log(`vxil \u2014 a Supabase-grade code-first CLI for the whole platform
+  init [--template <id>] \xB7 templates \xB7 try (keyless sandbox) \xB7 quickstart [--dev --ttl <h>] \xB7 login \xB7 link <slug>
+  plan \xB7 push [--dev|--prod] [--server [--resume <apply_id>]] [--no-gen] \xB7 pull \xB7 diff \xB7 gen [--check] [--offline] [--out <f>] [--no-mcp] [--mcp-out <f>]
+  doctor \xB7 versions <feature> \xB7 rollback <feature> --to <v>
+  secrets set|list|rm \xB7 seed \xB7 export|import <feature>
+  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
+  dev branch [<name>] [--ttl <h=24>] [--no-env] [--print] | --list | --rm <name> [--yes]
+  config get \xB7 users \xB7 send \xB7 deliveries \xB7 api <METHOD> <path>
+  global: --json (machine-readable + exit codes)`);
+      process.exit(cmd ? 1 : 0);
+  }
+} catch (e) {
+  fail(e.message);
+}
+async function devUpCreate(dashBase, appName, ttlHours) {
+  const cfg = await loadVxilConfig();
+  const feats = Object.keys(cfg.features);
+  const email = flag("email") ?? process.env.VXIL_DEV_EMAIL;
+  const password = flag("password") ?? process.env.VXIL_DEV_PASSWORD;
+  if (!email || !password) fail("creating a dev tenant needs --email/--password (or VXIL_DEV_EMAIL/VXIL_DEV_PASSWORD)");
+  const d = await createBranchTenant(makeDash(dashBase), {
+    email,
+    password,
+    appName,
+    features: feats,
+    ttlHours
+  });
+  const creds = loadCredentials();
+  creds.keys = { ...creds.keys, [d.slug]: d.api_key };
+  saveCredentials(creds);
+  return d;
+}
+async function runDev(sub) {
+  const base = process.env.VXIL_BASE_URL ?? loadProject()?.edge_url ?? DEFAULT_BASE;
+  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).`);
+  } else if (sub === "branch") {
+    await runDevBranch(dash, base);
+  } else if (sub === "seed") {
+    fail("run `vxil seed --dev` to seed the dev tenant from the config `seed` block.");
+  } else if (sub === "down") {
+    await devTeardown(dash, { confirm: true });
+  } else if (sub === "reset") {
+    await devTeardown(dash, { confirm: false }).catch((e) => {
+      if (!/no dev tenant bound/.test(e.message)) throw e;
+    });
+    await runDev("up");
+    await runApply(true, "dev");
+    await runSeed("dev", { optional: true });
+    console.log("\u2713 dev reset complete (torn down \u2192 recreated \u2192 pushed \u2192 seeded)");
+  } else {
+    fail("usage: vxil dev up|down|seed|reset|branch");
+  }
+}
+async function runDevBranch(dash, base) {
+  const proj = loadProject();
+  if (hasFlag("list")) {
+    const branches = proj?.branches ?? {};
+    const names = Object.keys(branches);
+    if (jsonOut) {
+      console.log(JSON.stringify({ branches, selected: proj?.dev?.slug ?? null }, null, 2));
+      return;
+    }
+    if (!names.length) {
+      console.log("(no dev branches \u2014 create one with `vxil dev branch <name>`)");
+      return;
+    }
+    for (const n of names.sort()) {
+      const s = branches[n];
+      const sel = proj?.dev?.tenant_id === s.tenant_id ? "  \u2190 selected" : "";
+      console.log(`  ${n}  \xB7  ${s.slug}  \xB7  expires ${s.expires_at ?? "(none)"}${sel}`);
+    }
+    return;
+  }
+  if (hasFlag("rm")) {
+    const name2 = flag("rm") ?? positional(1)[0];
+    if (!name2) fail("usage: vxil dev branch --rm <name> [--yes]");
+    await devTeardown(dash, { confirm: true, branch: name2 });
+    return;
+  }
+  const raw = positional(1)[0] ?? currentGitBranch();
+  if (!raw) fail("not on a git branch \u2014 pass a name: vxil dev branch <name>");
+  const name = sanitizeBranchName(raw);
+  if (!name) fail(`branch name '${raw}' sanitizes to empty \u2014 pass an explicit name`);
+  const creds = loadCredentials();
+  const decision = pickBranchSlot(proj, name, /* @__PURE__ */ new Date(), (slug) => Boolean(creds.keys?.[slug]));
+  let slot;
+  if ("reuse" in decision) {
+    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));
+    slot = {
+      tenant_id: d.tenant_id,
+      slug: d.slug,
+      edge_url: d.edge_url ?? base,
+      ...d.expires_at ? { expires_at: d.expires_at } : {}
+    };
+    console.log(`\u2713 dev branch '${name}' created (tenant '${slot.slug}'${slot.expires_at ? ` \xB7 expires ${slot.expires_at}` : ""})`);
+  }
+  const binding = loadProject() ?? { tenant_id: slot.tenant_id, slug: slot.slug, edge_url: slot.edge_url };
+  binding.branches = { ...binding.branches, [name]: slot };
+  binding.dev = { tenant_id: slot.tenant_id, slug: slot.slug, edge_url: slot.edge_url };
+  saveProject(binding);
+  console.log(`  selected \u2014 \`vxil push --dev\` / \`vxil gen\` / \`vxil functions dev\` now target '${slot.slug}'`);
+  if (hasFlag("print")) {
+    const key = loadCredentials().keys?.[slot.slug];
+    if (key) {
+      console.log(`export VXIL_API_KEY=${key}`);
+      console.log(`export VXIL_BASE_URL=${slot.edge_url}`);
+      console.log(`export VXIL_TENANT_ID=${slot.tenant_id}`);
+    }
+  }
+  if (!hasFlag("no-env") && !hasFlag("print")) runEnvPull("dev");
+  console.log("  note: re-run `vxil gen` \u2014 generated types drift across branch schemas.");
+}
+function currentGitBranch() {
+  const r = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" });
+  if (r.status !== 0 || r.error) return null;
+  const name = r.stdout.trim();
+  return name && name !== "HEAD" ? name : null;
+}
+async function devTeardown(dashBase, opts) {
+  const proj = loadProject();
+  let slot;
+  if (opts.branch !== void 0) {
+    const s = proj?.branches?.[opts.branch];
+    if (!s) throw new Error(`no dev branch '${opts.branch}' bound \u2014 see \`vxil dev branch --list\``);
+    slot = s;
+  } else {
+    if (!proj?.dev) throw new Error("no dev tenant bound \u2014 run `vxil dev up` first");
+    slot = proj.dev;
+  }
+  if (opts.confirm && !hasFlag("yes")) {
+    const ans = await prompt(`tear down dev tenant '${slot.slug}'? type the slug to confirm: `);
+    if (ans !== slot.slug) fail("confirmation did not match \u2014 aborted.");
+  }
+  const dash = makeDash(dashBase);
+  const cookie = await resolveDashCookie(dash);
+  const { alreadyGone } = await devDown(dash, cookie, { tenant_id: slot.tenant_id, slug: slot.slug });
+  const creds = loadCredentials();
+  if (creds.keys?.[slot.slug]) {
+    delete creds.keys[slot.slug];
+    saveCredentials(creds);
+  }
+  const cur = loadProject();
+  if (cur) {
+    let changed = false;
+    if (opts.branch !== void 0 && cur.branches?.[opts.branch]) {
+      delete cur.branches[opts.branch];
+      if (!Object.keys(cur.branches).length) delete cur.branches;
+      changed = true;
+    }
+    if (cur.dev && cur.dev.tenant_id === slot.tenant_id) {
+      delete cur.dev;
+      changed = true;
+    }
+    if (changed) saveProject(cur);
+  }
+  const what = opts.branch !== void 0 ? `dev branch '${opts.branch}' (tenant '${slot.slug}')` : `dev tenant '${slot.slug}'`;
+  console.log(alreadyGone ? `\u2713 ${what} was already gone \u2014 cleared the local binding` : `\u2713 ${what} torn down`);
+}
+function runEnvPull(which) {
+  const t = resolve_target({ which, defaultBase: DEFAULT_BASE });
+  if (!t.apiKey) {
+    fail(which === "dev" ? "no dev API key \u2014 run `vxil dev up` or `vxil dev branch <name>` first (or set VXIL_DEV_KEY)" : "no API key \u2014 run `vxil quickstart` or `vxil link <slug>`, or set VXIL_API_KEY");
+  }
+  const proj = loadProject();
+  const tenantId = which === "dev" ? proj?.dev?.tenant_id : proj?.tenant_id;
+  const updates = envUpdates({
+    apiKey: t.apiKey,
+    baseUrl: t.baseUrl,
+    ...tenantId && tenantId !== "(unknown)" ? { tenantId } : {}
+  });
+  if (hasFlag("print")) {
+    for (const [k, v] of Object.entries(updates)) console.log(`${k}=${v}`);
+    return;
+  }
+  const fileArg = flag("file") ?? ".env.local";
+  const file = resolve4(process.cwd(), fileArg);
+  const note = guardEnvFile(fileArg);
+  const existing = existsSync3(file) ? readFileSync2(file, "utf8") : "";
+  writeFileSync3(file, mergeEnvFile(existing, updates));
+  try {
+    chmodSync2(file, 384);
+  } catch {
+  }
+  console.log(`\u2713 wrote ${fileArg} (${Object.keys(updates).join(", ")})${note ? `
+  ${note}` : ""}`);
+}
+function guardEnvFile(fileArg) {
+  const cwd = process.cwd();
+  const git = (args) => {
+    const r = spawnSync("git", args, { cwd, stdio: "ignore" });
+    if (r.error && r.error.code === "ENOENT") return "no-git";
+    if (r.error) return "error";
+    return r.status ?? 1;
+  };
+  const appendOrWarn = (covered) => {
+    if (covered) return void 0;
+    if (hasFlag("no-gitignore")) {
+      return `! ${fileArg} is NOT gitignored and holds your API key \u2014 add it to .gitignore before committing`;
+    }
+    const gi = resolve4(cwd, ".gitignore");
+    appendFileSync(gi, ["", "# vxil", fileArg, ""].join("\n"));
+    return `note: appended '${fileArg}' to .gitignore (it holds your API key)`;
+  };
+  const inRepo = git(["rev-parse", "--is-inside-work-tree"]);
+  if (inRepo === "no-git") {
+    const gi = resolve4(cwd, ".gitignore");
+    const text = existsSync3(gi) ? readFileSync2(gi, "utf8") : "";
+    return appendOrWarn(gitignoreCovers(text, fileArg));
+  }
+  if (inRepo !== 0) return void 0;
+  if (git(["ls-files", "--error-unmatch", "--", fileArg]) === 0) {
+    fail(`${fileArg} is TRACKED by git \u2014 writing your API key into it would commit a secret. Run \`git rm --cached ${fileArg}\` (and gitignore it) first.`);
+  }
+  return appendOrWarn(git(["check-ignore", "-q", "--", fileArg]) === 0);
+}
+async function runFunctionsDev(name) {
+  const cfg = await loadVxilConfig();
+  const def = cfg.functions?.[name];
+  if (!def) fail(`function '${name}' not declared in vxil.config`);
+  const t = resolve_target({ which: "dev", defaultBase: DEFAULT_BASE });
+  if (!t.apiKey) fail("no API key \u2014 run `vxil quickstart`, `vxil link <slug>`, or `vxil dev up` (or set VXIL_API_KEY)");
+  const proj = loadProject();
+  const tenantId = (proj?.dev && proj.dev.slug === t.tenantSlug ? proj.dev.tenant_id : proj?.tenant_id) ?? "dev-tenant";
+  let Miniflare;
+  try {
+    const mod = await import("miniflare");
+    Miniflare = mod.Miniflare;
+  } catch {
+    fail("`vxil functions dev` runs your function under miniflare (the local Workers runtime), an optional dependency of the CLI \u2014 install it with `npm i -D miniflare` (or pnpm/yarn) and re-run.");
+  }
+  const cwd = process.cwd();
+  const entry = resolve4(cwd, def.entry);
+  const scopes = def.scopes ?? [];
+  const egressAllow = def.egressAllow ?? [];
+  const outbound = makeDevOutbound({
+    fnName: name,
+    scopes,
+    egressAllow,
+    edgeUrl: t.baseUrl,
+    apiKey: t.apiKey,
+    log: (line) => console.log(`  ${line}`)
+  });
+  const mfOptions = (source) => ({
+    modules: [{ type: "ESModule", path: "fn.mjs", contents: source }],
+    compatibilityDate: "2025-09-01",
+    // parity with the deploy pipeline's metadata
+    outboundService: (req) => outbound(req)
+  });
+  const first = await bundleFunction(entry, { projectRoot: cwd });
+  const mf = new Miniflare(mfOptions(first.source));
+  const { secrets, missing } = resolveDevSecrets(def.secrets, process.env);
+  for (const m of missing) {
+    console.log(`  ! secret '${m}' not resolved locally \u2014 export VXIL_FN_SECRET_${m.toUpperCase()}=\u2026 (deployed invokes read tenant_secrets)`);
+  }
+  const port = Number(flag("port") ?? 8788);
+  let seq = 0;
+  const server = createServer((req, res) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => {
+      void (async () => {
+        seq += 1;
+        const requestId = `dev-${seq}`;
+        const reqUrl = new URL(req.url ?? "/", `http://localhost:${port}`);
+        let payload = Object.fromEntries(reqUrl.searchParams);
+        if ((req.method ?? "GET") !== "GET") {
+          try {
+            payload = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+          } catch {
+            payload = {};
+          }
+        }
+        const idem = req.headers["idempotency-key"];
+        const envelope = buildEnvelope({
+          fnName: name,
+          scopes,
+          payload,
+          tenantId,
+          requestId,
+          ...typeof idem === "string" ? { idempotencyKey: idem } : {},
+          secrets
+        });
+        const t0 = Date.now();
+        try {
+          const out = await mf.dispatchFetch("https://fn.vxil.internal/invoke", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(envelope)
+          });
+          const text = await out.text();
+          console.log(`  [${requestId}] ${req.method} ${reqUrl.pathname} \u2192 ${out.status} (${Date.now() - t0} ms)`);
+          res.writeHead(out.status, { "content-type": out.headers.get("content-type") ?? "application/json" });
+          res.end(text);
+        } catch (e) {
+          console.error(`  [${requestId}] isolate error: ${String(e.message).split("\n")[0]}`);
+          res.writeHead(502, { "content-type": "application/json" });
+          res.end(JSON.stringify({ error: { code: "function_unavailable", message: String(e.message).slice(0, 200) } }));
+        }
+      })();
+    });
+  });
+  let timer = null;
+  const watcher = watch(dirname2(entry), () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      void (async () => {
+        try {
+          const rebuilt = await bundleFunction(entry, { projectRoot: cwd });
+          await mf.setOptions(mfOptions(rebuilt.source));
+          console.log(`  \u21BB rebuilt '${name}' (${Math.round(rebuilt.bytes / 100) / 10} KB) \u2014 hot-swapped`);
+        } catch (e) {
+          console.error(`  \u2717 rebuild failed: ${String(e.message).split("\n")[0]}`);
+        }
+      })();
+    }, 300);
+  });
+  server.listen(port, () => {
+    const auds = [...audsForScopes(scopes)];
+    console.log(`vxil functions dev '${name}' \u2014 local isolate, remote edge (design \xA75.1-C)`);
+    console.log(`  tenant:  ${t.tenantSlug ?? "(env key)"} \xB7 edge ${t.baseUrl}`);
+    console.log(`  bundle:  ${def.entry} (${Math.round(first.bytes / 100) / 10} KB) \u2014 rebuilds on save`);
+    console.log(`  invoke:  curl -X POST http://localhost:${port}/ -d '{"name":"world"}'`);
+    console.log(`  scopes:  [${scopes.join(", ") || "none"}] \u2192 features [${auds.join(", ") || "none"}] (clamp reproduced locally)`);
+    console.log(`  egress:  deny-by-default, same egressDecision as deployed \xB7 allowed: ${egressAllow.join(", ") || "(none beyond api.vxil.*)"}`);
+    console.log("  caveat:  local edge calls use YOUR API key, not per-invoke scoped JWTs \u2014 the aud-level");
+    console.log("           feature clamp is reproduced, but per-scope (read/write) enforcement, breaker,");
+    console.log("           metering, CPU/mem limits, and tenant_secrets only exist on deploy.");
+    console.log("           Deploy is the contract; this loop is for iteration. Ctrl-C to stop.");
+  });
+  process.on("SIGINT", () => {
+    watcher.close();
+    server.close();
+    void mf.dispose().finally(() => {
+      console.log(`
+vxil functions dev '${name}' stopped.`);
+      process.exit(0);
+    });
+  });
+  await new Promise(() => {
+  });
+}