@vxil/cli 0.18.0 → 0.19.0

package/dist/_vxil-feature-configs-hooks.d.ts

@@ -10,12 +10,16 @@ export declare const HOOK_LIMITS: {
     readonly maxReadHooksPerCollection: 10;
 };
 /** The ONLY root variables an expression may reference. `caller` is the VERIFIED
- *  end-user principal (https://vxil.com/docs/guide/09-security-and-multitenancy) — read-only and
- *  populated ONLY on the READ path (runReadHooks); on the write path and in
- *  server-caller mode it is null, exactly like `before` on a create. It carries
- *  `caller.endUserId` (the verified session sub, or null) and `caller.principal`
- *  ('end_user' | 'tenant'). It is the missing "caller/session context" a read
- *  hook keys on to redact/derive per-viewer. */
+ *  end-user principal (https://vxil.com/docs/guide/09-security-and-multitenancy) — read-only.
+ *  It carries `caller.endUserId` (the verified session sub, or null),
+ *  `caller.principal` ('end_user' | 'tenant') and `caller.roles` (the VERIFIED
+ *  session role claims of the signed-in session — never a body or header
+ *  value; null in server-caller mode). READ hooks always get it
+ *  (server mode: `{ endUserId: null, principal: 'tenant', roles: null }`).
+ *  WRITE hooks get it in verified end-user mode only; on a
+ *  server write it is null, exactly like `before` on a create — so a role rule
+ *  reads `isNull(caller) || contains(caller.roles, 'manager')`. `contains` on
+ *  an array is exact element membership. */
 export declare const HOOK_ROOT_VARS: readonly ["item", "before", "now", "caller"];
 /** The ONLY callable functions. Each is pure + deterministic + bounded. */
 export declare const HOOK_FUNCTIONS: readonly ["min", "max", "abs", "round", "floor", "ceil", "sqrt", "pow", "sign", "len", "lower", "upper", "trim", "substr", "contains", "startsWith", "endsWith", "concat", "coalesce", "ifNull", "not", "isNull", "number", "string", "bool", "daysBetween", "yearsBetween"];
@@ -80,20 +84,25 @@ export declare function parseExpr(src: string): Node;
 /** Walk the AST and reject anything outside the allow-list, plus depth bounds.
  *  Returns an array of human-readable errors (empty = safe). Pure, no eval. */
 export declare function validateAst(root: Node): string[];
-/** The VERIFIED caller/session context for read hooks (guide ch. 7). Read-only;
- *  present only on the read path in end-user mode. In server mode / write path
- *  the whole object is null. */
+/** The VERIFIED caller/session context for Lane-A hooks (guide ch. 7).
+ *  Read-only. Read hooks always get it; write hooks get it in verified end-user
+ *  mode only (a server write passes null — see HOOK_ROOT_VARS). */
 export interface HookCaller {
     /** the verified end-user session sub, or null in server-caller mode. */
     endUserId: string | null;
     /** 'end_user' when a session was verified at the edge, else 'tenant'. */
     principal: 'end_user' | 'tenant';
+    /** the VERIFIED session role claims of the signed-in session; `[]` for a
+     *  session without roles, null in server-caller mode. Optional so an older
+     *  caller object still reads
+     *  as "no roles". */
+    roles?: readonly string[] | null;
 }
 export interface HookContext {
     item: Record<string, unknown>;
     before: Record<string, unknown> | null;
     now: string;
-    /** verified caller/session context (read path only); null otherwise. */
+    /** verified caller/session context; null on a server write. */
     caller?: HookCaller | null;
 }
 /** A mutable step counter SHARED across many evalExpr calls (the read path's
@@ -127,7 +136,10 @@ export interface HookRunResult {
  *  Mutates a CLONE: derive hooks set fields; a validate hook that returns falsy
  *  throws HookRejection (→ the caller maps to a 422 and the tx rolls back).
  *  Throws HookEvalError on a runtime fault (also a clean 422, never a 500). */
-export declare function runWriteHooks(hooks: Record<string, HookDef> | undefined, collection: string, phase: 'create' | 'update', data: Record<string, unknown>, before: Record<string, unknown> | null, now: string): HookRunResult;
+export declare function runWriteHooks(hooks: Record<string, HookDef> | undefined, collection: string, phase: 'create' | 'update', data: Record<string, unknown>, before: Record<string, unknown> | null, now: string, 
+/** the VERIFIED end-user caller (endUserId + principal + roles) in
+ *  end-user mode; omitted / null on a server write (expressions see null). */
+caller?: HookCaller | null): HookRunResult;
 export interface ReadHookResult {
     /** Surviving rows in input order. Each is a SHALLOW COPY with a copied `data`
      *  bag — the caller's rows are never mutated and nothing here is persisted. */
@@ -154,8 +166,8 @@ export interface ReadHookResult {
  *  fire here, and read events never fire in runWriteHooks. */
 export declare function runReadHooks(hooks: Record<string, HookDef> | undefined, collection: string, rows: ReadonlyArray<Record<string, unknown>>, now: string, 
 /** verified caller/session context (guide ch. 7) — read-only, exposed to
- *  expressions as `caller.endUserId` / `caller.principal`. Omitted ⇒ null
- *  (server-caller mode). */
+ *  expressions as `caller.endUserId` / `caller.principal` / `caller.roles`.
+ *  Omitted ⇒ null (server-caller mode). */
 caller?: HookCaller | null): ReadHookResult;
 export interface ExprRef {
     root: 'item' | 'before' | 'now' | 'caller';

package/dist/_vxil-feature-configs-readmodels.d.ts

@@ -35,4 +35,22 @@ interface CdcRuleLike {
 }
 /** Cross-field rule for CmsConfig.cdc (called from validateFeatureConfig). */
 export declare function validateCdcConfig(cdc: Record<string, CdcRuleLike> | undefined): string[];
+/** What a payload:'full' change-data rule must know about its target
+ *  collection's read gates. `readRoleFields`: fields with a non-empty
+ *  `readRoles`; `endUserAccess`: the collection's end-user access mode. */
+export interface CdcCollectionGates {
+    readRoleFields?: readonly string[];
+    endUserAccess?: 'readwrite' | 'read' | 'none';
+}
+/**
+ * A `payload: 'full'` change-data rule inlines the stored row into a realtime
+ * frame that every subscriber of the channel receives — it does not go through
+ * the read projection. So it must never target a collection whose reads are
+ * gated: a field with `readRoles` (the frame would carry the gated value), or
+ * an `endUserAccess` of 'read' / 'none' (the frame would bypass the
+ * collection's end-user gate). Pure; one problem line per offending ENABLED
+ * rule (an unknown collection is skipped). The safe shape is `payload: 'ids'`
+ * and a re-read through the cms, where every gate applies.
+ */
+export declare function cdcFullFramesOverGatedCollections(cdc: unknown, collections: Record<string, CdcCollectionGates>): string[];
 export {};

package/dist/_vxil-feature-configs.d.ts

@@ -218,6 +218,7 @@ declare const OidcProviderSchema: import("@sinclair/typebox").TObject<{
         email: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         roles: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        rolePrefix: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     }>>;
     allowedDomains: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
     autoLink: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
@@ -275,6 +276,7 @@ export declare const AuthConfigSchema: import("@sinclair/typebox").TObject<{
                 email: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
                 name: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
                 roles: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+                rolePrefix: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
             }>>;
             allowedDomains: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
             autoLink: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
@@ -319,6 +321,8 @@ export declare const AuthConfigSchema: import("@sinclair/typebox").TObject<{
         breachedPasswords: import("@sinclair/typebox").TBoolean;
         captchaSecretRef: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         allowedRedirectOrigins: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+        inviteOnly: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+        allowedEmailDomains: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
     }>>;
 }>;
 /** The security bag as persisted (present ⇒ leaf defaults applied). */
@@ -633,6 +637,7 @@ export declare const RagConfigSchema: import("@sinclair/typebox").TObject<{
         topK: import("@sinclair/typebox").TInteger;
         mode: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"hybrid">, import("@sinclair/typebox").TLiteral<"vector">, import("@sinclair/typebox").TLiteral<"keyword">]>;
         minScore: import("@sinclair/typebox").TNumber;
+        minSimilarity: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
         rerank: import("@sinclair/typebox").TBoolean;
     }>;
     boosts: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{

package/dist/config.d.ts

@@ -121,6 +121,17 @@ export interface CollectionDef {
      *  `vxil push --allow-destructive`. Any other value fails `vxil plan` /
      *  `vxil push` (it never falls back to 'readwrite'). */
     endUserAccess?: 'readwrite' | 'read' | 'none';
+    /** Role slugs one of which a VERIFIED end user must hold to WRITE this
+     *  collection (create, update, $inc, delete, publish, transaction step,
+     *  filtered delete, batch write, and an end-user delete's cascade into it) —
+     *  otherwise `403 role_required`. Reads are unaffected. Roles are the
+     *  session's verified role claims (its orgs roles — the
+     *  same ones `readRoles` and `caller.roles` in hooks see). Server keys are
+     *  never affected. Absent / `[]` = ungated. Up to 16 slugs
+     *  (`^[a-z0-9][a-z0-9_-]{0,31}$`). Stored on the collection (model data, not
+     *  a config leaf) and carried by BOTH push paths; widening (clearing, or
+     *  adding a role) needs `vxil push --allow-destructive`. */
+    writeRoles?: string[];
     /** Per-record action buttons (guide ch. 4): `[{ key, label, fn }]`, stored on
      *  the collection (model data, not a config leaf). The dashboard renders one
      *  button per action on each record row; `POST /v1/cms/items/:coll/:id/actions/

package/dist/vxil.js

@@ -3705,7 +3705,16 @@ var OidcProviderSchema = Type.Object({
   claims: Type.Optional(Type.Object({
     email: Type.Optional(Type.String({ minLength: 1, maxLength: 64 })),
     name: Type.Optional(Type.String({ minLength: 1, maxLength: 64 })),
-    roles: Type.Optional(Type.String({ minLength: 1, maxLength: 64 }))
+    roles: Type.Optional(Type.String({ minLength: 1, maxLength: 64 })),
+    // G-38b: an optional namespace prepended to every mapped IdP role (e.g.
+    // `idp-`), so an IdP group named like an app role (`finance`, `owner`)
+    // arrives as `idp-finance` and cannot pass a `readRoles: ['finance']`
+    // gate. Absent = the raw group names (the shipped behaviour). The prefixed
+    // role still obeys the 32-char role bound (longer ones are dropped).
+    // The alphabet is the cms readRoles / orgs role slug alphabet
+    // (`^[a-z0-9][a-z0-9_-]*$`, cms-v1 READ_ROLE_RE), so a prefixed role can
+    // itself be named in a gate — a `:`/`.`/uppercase prefix never could.
+    rolePrefix: Type.Optional(Type.String({ minLength: 1, maxLength: 16, pattern: "^[a-z0-9][a-z0-9_-]{0,15}$" }))
   })),
   // when non-empty, the asserted email's domain MUST be listed (fail-closed:
   // no email ⇒ refused) → 403 oidc_domain_not_allowed; a listed domain also
@@ -3895,6 +3904,26 @@ var AuthConfigSchema = Type.Object({
     allowedRedirectOrigins: Type.Optional(Type.Array(
       Type.String({ minLength: 8, maxLength: 253, pattern: REDIRECT_ORIGIN_PATTERN }),
       { maxItems: 32 }
+    )),
+    // G-3 sign-up gating (2026-10-05). Both Optional with NO default, so an
+    // existing manifest folds byte-identically and the gate is opt-in. When
+    // EITHER is set, every self-service account-create path (password sign-up,
+    // magic-link / OTP pre-register, the guest → email claim, social sign-in
+    // with google/github/apple/facebook) is checked, fail-closed:
+    //   • inviteOnly — a new account only for an address the tenant already
+    //     put in its user registry server-side (POST /v1/users, an import);
+    //   • allowedEmailDomains — otherwise, only for an address at one of these
+    //     domains (exact, lowercase; a provider must assert the address
+    //     VERIFIED).
+    // With either set, password sign-up is refused (it proves nothing about
+    // the address — a stranger could squat an invitee's address), guest
+    // sign-in is refused (a guest is nobody's invitee), and an existing
+    // account is never affected. The generic OIDC issuer keeps its own gate
+    // (providers.oidc.allowedDomains + IdP assignment). auth-v1 signupGate.ts.
+    inviteOnly: Type.Optional(Type.Boolean()),
+    allowedEmailDomains: Type.Optional(Type.Array(
+      Type.String({ minLength: 3, maxLength: 253, pattern: "^[a-z0-9][a-z0-9.-]*\\.[a-z]{2,}$" }),
+      { maxItems: 32 }
     ))
   }))
 });
@@ -4494,6 +4523,12 @@ var RagConfigSchema = Type.Object({
       ),
       // drop retrieved chunks below this score BEFORE budgeting (0 = keep all).
       minScore: Type.Number({ default: 0 }),
+      // drop retrieved chunks whose cosine `similarity` to the query is
+      // below this floor (-1..1). Unlike minScore (a floor on the RRF rank
+      // value, ~0.016-0.033 at the top) this is the relevance threshold a RAG
+      // app means. Absent = no floor; a hit with no measured similarity (no
+      // query vector: keyword mode) is never dropped by it.
+      minSimilarity: Type.Optional(Type.Number({ minimum: -1, maximum: 1 })),
       // forward rerank:true to vector-search's post-RRF BYO rerank pass (it owns
       // the provider + key); inert until that pass exists/is configured there.
       rerank: Type.Boolean({ default: false })
@@ -5030,9 +5065,9 @@ function lowerAllTriggerBindings(def, name) {
   return bindings;
 }
 var CONFIG_FILENAMES = ["vxil.config.ts", "vxil.config.mjs", "vxil.config.js"];
-var VXIL_CONFIG_PKG_VERSION = "0.12.0";
-var VXIL_SDK_PKG_VERSION = "0.18.0";
-var VXIL_CLI_PKG_VERSION = "0.18.0";
+var VXIL_CONFIG_PKG_VERSION = "0.13.0";
+var VXIL_SDK_PKG_VERSION = "0.19.0";
+var VXIL_CLI_PKG_VERSION = "0.19.0";
 function ensureScaffoldPackageJson(cwd, opts = {}) {
   const file = resolve(cwd, "package.json");
   const wanted = {
@@ -7617,6 +7652,15 @@ var KNOWN_SCOPES = [
   // so pre-existing keys keep working; mint this when a key should see usage
   // and nothing else.
   "usage:read",
+  // Narrow READ-ONLY scope for the audit stream (G-15, 2026-10-05): GET
+  // /v1/audit and GET /v1/audit/export accept it alongside 'features:read'
+  // (any-of), so an ops/admin function or a dedicated key reads the audit log
+  // WITHOUT holding features:read — which is also the door of
+  // GET /v1/export/:feature (a whole-project export credential). Both routes
+  // stay server-only; a public / thin-client key can never carry it
+  // (PUBLIC_KEY_DENY_SCOPES), and a function receives it on its confined
+  // control-plane callback token (CONTROL_PLANE_FUNCTION_SCOPES).
+  "audit:read",
   "admin"
 ];
 var FUNCTION_SCOPE_AUDIENCE = {
@@ -7645,7 +7689,14 @@ var FUNCTION_SCOPE_AUDIENCE = {
   // CONTROL_PLANE_FUNCTION_SCOPES (scopesForFunctionAudience) so the same token
   // can never satisfy any other scope-gated control-plane route.
   users: "control-plane",
-  usage: "control-plane"
+  usage: "control-plane",
+  // G-15: the audit stream (/v1/audit, /v1/audit/export) is a control-plane
+  // route too; `audit:read` joins the confined claim below
+  audit: "control-plane",
+  // webhooks-in (the inbound receiver's READ routes); the token is confined to
+  // WEBHOOKS_FUNCTION_SCOPES, and webhooks:write stays in SCOPES_NOT_FOR_FUNCTIONS
+  // (which wins over the prefix — see functionScopeAudience).
+  webhooks: "webhooks"
 };
 var FUNCTION_SCOPE_PREFIX_ALIASES = {
   "rate-limits": "ratelimits",
@@ -7653,7 +7704,20 @@ var FUNCTION_SCOPE_PREFIX_ALIASES = {
   vector: "vector-search",
   feeds: "activity-feed"
 };
-var CONTROL_PLANE_FUNCTION_SCOPES = ["users:read", "users:write", "usage:read"];
+var SCOPES_NOT_FOR_FUNCTIONS = {
+  admin: "never grantable to a function (DENY_FUNCTION_SCOPES strips it at deploy)",
+  "secrets:write": "never grantable to a function (self-integrity: DENY_FUNCTION_SCOPES strips it at deploy)",
+  "features:write": "never grantable to a function (self-integrity: DENY_FUNCTION_SCOPES strips it at deploy)",
+  "functions:write": "never grantable to a function (self-integrity: DENY_FUNCTION_SCOPES strips it at deploy)",
+  "features:read": "GET /v1/features is privilege-independent (any authenticated principal) and no other route needs it from a function \u2014 the control-plane callback token is confined to users:*/usage:read",
+  "functions:invoke": "there is no function\u2192function lane by design (no aud=functions token is ever minted) \u2014 chain work through a cms/webhook/queue trigger instead",
+  "functions:read": "GET /v1/functions is privilege-independent and the manifest is deploy-time data \u2014 read your own config from vxil.config.ts, not at invoke",
+  "webhooks:write": "webhook subscriptions are deploy-managed trigger wiring (auto-wired from bindings) \u2014 a function must not rewrite its own triggers (self-integrity, same class as functions:write)",
+  "copilot:read": "copilot is an agent surface that acts on your features through its own typed tool routes; a function-driven copilot turn is not a supported callback lane \u2014 invoke copilot from your app, not from a function",
+  "copilot:write": "copilot is an agent surface that acts on your features through its own typed tool routes; a function-driven copilot turn is not a supported callback lane \u2014 invoke copilot from your app, not from a function"
+};
+var CONTROL_PLANE_FUNCTION_SCOPES = ["users:read", "users:write", "usage:read", "audit:read"];
+var WEBHOOKS_FUNCTION_SCOPES = ["webhooks:read"];
 function canonicalFunctionScope(scope) {
   const i = scope.indexOf(":");
   if (i <= 0) return scope;
@@ -7663,6 +7727,7 @@ function canonicalFunctionScope(scope) {
 }
 function functionScopeAudience(scope) {
   const c = canonicalFunctionScope(scope);
+  if (c in SCOPES_NOT_FOR_FUNCTIONS) return null;
   const i = c.indexOf(":");
   if (i <= 0) return null;
   return FUNCTION_SCOPE_AUDIENCE[c.slice(0, i)] ?? null;
@@ -7678,8 +7743,30 @@ function functionCallbackAudiences(scopes) {
 function scopesForFunctionAudience(aud, scopes) {
   const canon = [...new Set(scopes.map(canonicalFunctionScope))];
   if (aud === "control-plane") return canon.filter((s) => CONTROL_PLANE_FUNCTION_SCOPES.includes(s));
+  if (aud === "webhooks") return canon.filter((s) => WEBHOOKS_FUNCTION_SCOPES.includes(s));
   return canon;
 }
+var PUBLIC_KEY_DENY_SCOPES = /* @__PURE__ */ new Set([
+  "admin",
+  "*",
+  "users:read",
+  "users:write",
+  "features:read",
+  "features:write",
+  "secrets:write",
+  // G-15: the tenant-wide audit stream has no end-user owner dimension
+  "audit:read",
+  "functions:read",
+  "functions:write",
+  "jobs:read",
+  "jobs:write",
+  "webhooks:read",
+  "webhooks:write",
+  "ratelimits:write",
+  "payments:write",
+  "notifications:send",
+  "auth:write"
+]);
 var TENANT_SLUG_RE = /^[a-z0-9][a-z0-9-]{1,62}$/;
 var FUNCTION_SOURCE_MAX_BYTES = 512e3;
 var FN_PLATFORM_DEFAULT_CPU_MS = 3e4;
@@ -8727,6 +8814,15 @@ function indexArmNote(rows) {
   if (rows === null) return "arms inline or through the re-index push runs (live row count unavailable)";
   return rows <= EQ_INDEX_INLINE_MAX_ROWS ? `arms inline (${rows} rows)` : `needs reindex (${rows} rows; push runs it)`;
 }
+function writeRolesOf(v) {
+  if (!Array.isArray(v)) return [];
+  return [...new Set(v.filter((r) => typeof r === "string"))].sort();
+}
+function writeRolesWidens(declared, remote) {
+  if (remote.length === 0) return false;
+  if (declared.length === 0) return true;
+  return declared.some((r) => !remote.includes(r));
+}
 function endUserAccessOf(v) {
   return v === "read" || v === "none" ? v : "readwrite";
 }
@@ -8828,6 +8924,7 @@ async function readRemote2(api) {
       ownerField: c.owner_field ?? null,
       public: c.public === true,
       endUserAccess: endUserAccessOf(c.end_user_access),
+      writeRoles: writeRolesOf(c.write_roles),
       actions: normalizeActions(c.actions),
       fields: Array.isArray(c.fields) ? c.fields : []
     });
@@ -8881,6 +8978,10 @@ async function planCmsSchema({ api, collections, apply, allowDestructive = false
     if (v !== void 0 && v !== "readwrite" && v !== "read" && v !== "none") {
       throw new Error(`cms.collections.${name}.endUserAccess must be 'readwrite' | 'read' | 'none' (got ${JSON.stringify(v)})`);
     }
+    const wr = def.writeRoles;
+    if (wr !== void 0 && (!Array.isArray(wr) || wr.some((r) => typeof r !== "string"))) {
+      throw new Error(`cms.collections.${name}.writeRoles must be an array of role slugs (got ${JSON.stringify(wr)})`);
+    }
   }
   const read = await readRemote2(api);
   if (read.unavailable) {
@@ -9043,6 +9144,24 @@ async function planCmsSchema({ api, collections, apply, allowDestructive = false
         });
       }
     }
+    const declaredRoles = writeRolesOf(def.writeRoles);
+    if (stableStringify(declaredRoles) !== stableStringify(rc.writeRoles)) {
+      const widens = writeRolesWidens(declaredRoles, rc.writeRoles);
+      const fmt = (r) => r.length ? `[${r.join(", ")}]` : "none (ungated)";
+      if (!widens || allowDestructive) {
+        collChanges.push({
+          collection: name,
+          kind: "set-write-roles",
+          detail: `${name} writeRoles \u2192 ${fmt(declaredRoles)} (was ${fmt(rc.writeRoles)})` + (widens ? " \u2014 WIDENS who may write (full-config reconciliation)" : " (narrows end-user writes)")
+        });
+      } else {
+        collChanges.push({
+          collection: name,
+          kind: "warn",
+          detail: `${name}: writeRoles are ${fmt(rc.writeRoles)} remotely but ${fmt(declaredRoles)} in config \u2014 that WIDENS which end users may write, so it is NOT applied. Declare the remote roles to keep them, or re-run with --allow-destructive to widen.`
+        });
+      }
+    }
     const declaredActions = normalizeActions(def.actions);
     if (stableStringify(declaredActions) !== stableStringify(rc.actions)) {
       collChanges.push({
@@ -9116,6 +9235,8 @@ async function planCmsSchema({ api, collections, apply, allowDestructive = false
         if (def.public === true) body.public = true;
         const access = endUserAccessOf(def.endUserAccess);
         if (access !== "readwrite") body.end_user_access = access;
+        const roles = writeRolesOf(def.writeRoles);
+        if (roles.length > 0) body.write_roles = roles;
         if (def.actions && def.actions.length > 0) body.actions = normalizeActions(def.actions);
         const res = await api("POST", "/v1/cms/collections", body);
         if (res.status !== 201 && res.status !== 200 && res.body.error?.code !== "collection_exists") {
@@ -9163,6 +9284,14 @@ async function planCmsSchema({ api, collections, apply, allowDestructive = false
           throw new Error(`cms: set endUserAccess on ${c.collection} failed: ${e.code ?? res.status} ${e.message ?? ""}`);
         }
         applied++;
+      } else if (c.kind === "set-write-roles") {
+        const target = writeRolesOf(collections[c.collection].writeRoles);
+        const res = await api("POST", `/v1/cms/collections/${encodeURIComponent(c.collection)}/fields`, { write_roles: target });
+        if (res.status !== 200 && res.status !== 201) {
+          const e = res.body.error ?? {};
+          throw new Error(`cms: set writeRoles on ${c.collection} failed: ${e.code ?? res.status} ${e.message ?? ""}`);
+        }
+        applied++;
       } else if (c.kind === "set-actions") {
         const target = normalizeActions(collections[c.collection].actions);
         const res = await api("POST", `/v1/cms/collections/${encodeURIComponent(c.collection)}/fields`, { actions: target });
@@ -9228,7 +9357,7 @@ function formatCmsChanges(changes) {
     if (c.kind === "destructive") return `  ! ${c.detail}`;
     if (c.kind === "warn") return `  \u26A0 ${c.detail}`;
     if (c.kind === "reindex") return `  \u21BB ${c.detail}`;
-    if (c.kind === "alter-flags" || c.kind === "set-owner-field" || c.kind === "set-end-user-access") return `  ~ ${c.detail}`;
+    if (c.kind === "alter-flags" || c.kind === "set-owner-field" || c.kind === "set-end-user-access" || c.kind === "set-write-roles") return `  ~ ${c.detail}`;
     return `  + ${c.detail}`;
   }).join("\n");
 }
@@ -9407,7 +9536,7 @@ var API_CHEATSHEET = [
   // realtime
   { feature: "realtime", what: "publish an event to a channel", cmd: `vxil api POST /v1/realtime/channels/<channel>/publish '{"event":"ping","data":{}}'` },
   // webhooks
-  { feature: "webhooks", what: "inbound sources add / list / rm / test", cmd: "vxil webhooks sources add --provider stripe --name prod [--forward-url https://\u2026]   \xB7 sources list \xB7 sources rm <id> [--yes] \xB7 sources test <id>" },
+  { feature: "webhooks", what: "inbound sources add / list / rm / test", cmd: "vxil webhooks sources add --provider stripe --name prod [--forward-url https://\u2026 | --target-function <fn>] [--provider hmac --verify <json>]   \xB7 sources list \xB7 sources rm <id> [--yes] \xB7 sources test <id>" },
   { feature: "webhooks", what: "replay an inbound event / see its delivery runs", cmd: "vxil webhooks events replay <event_id>   \xB7 vxil webhooks events runs <event_id>" },
   { feature: "webhooks", what: "declare outbound subscriptions in vxil.config (converged by push)", cmd: "features.webhooks.subscriptions[] in vxil.config.ts \u2192 vxil push" },
   { feature: "webhooks", what: "add an outbound subscription by hand (undeclared \u2014 `vxil diff --strict-api-state` reports it)", cmd: `vxil api POST /v1/webhooks/subscriptions '{"target_url":"https://\u2026","event_prefixes":["cms."]}'` },
@@ -10789,7 +10918,8 @@ async function filesRm(api, objectId) {
   if (!ok2xx(r)) throw new Error(`could not delete '${objectId}' (${apiErrText(r)})`);
   return { object_id: objectId, deleted: true };
 }
-var WEBHOOK_PROVIDERS = ["stripe", "paddle", "github", "slack", "revenuecat", "generic"];
+var WEBHOOK_PROVIDERS = ["stripe", "paddle", "github", "slack", "revenuecat", "generic", "hmac"];
+var TARGET_FUNCTION_RE = /^[a-z][a-z0-9-]{0,47}$/;
 function parseSourceAdd(f) {
   const provider = (f.provider ?? "").trim();
   if (!WEBHOOK_PROVIDERS.includes(provider)) {
@@ -10800,14 +10930,48 @@ function parseSourceAdd(f) {
   if (name.length > 200) return { error: `--name is at most 200 characters (got ${name.length})` };
   const fwd = f.forwardUrl?.trim();
   if (fwd !== void 0 && fwd !== "" && !/^https:\/\//i.test(fwd)) return { error: "--forward-url must be an https:// URL" };
-  return { body: { provider, name, ...fwd ? { forward_url: fwd } : {} } };
+  const fn = f.targetFunction?.trim();
+  if (fn !== void 0 && fn !== "") {
+    if (!TARGET_FUNCTION_RE.test(fn)) return { error: `--target-function must be a function name matching ${TARGET_FUNCTION_RE.source}` };
+    if (fwd) return { error: "set --forward-url OR --target-function, not both (one source, one destination)" };
+  }
+  let verify;
+  const rawVerify = f.verify?.trim();
+  if (provider === "hmac") {
+    if (!rawVerify) {
+      return { error: `--provider hmac needs --verify '<json>', e.g. --verify '{"header":"X-Shopify-Hmac-Sha256","encoding":"base64"}'` };
+    }
+    try {
+      const v = JSON.parse(rawVerify);
+      if (!v || typeof v !== "object" || Array.isArray(v)) return { error: "--verify must be a JSON object" };
+      verify = v;
+    } catch {
+      return { error: "--verify must be valid JSON (a single-quoted object)" };
+    }
+  } else if (rawVerify) {
+    return { error: "--verify is accepted only with --provider hmac" };
+  }
+  return {
+    body: {
+      provider,
+      name,
+      ...fwd ? { forward_url: fwd } : {},
+      ...fn ? { target_function: fn } : {},
+      ...verify ? { verify } : {}
+    }
+  };
 }
 async function sourcesAdd(api, body) {
   const r = await api("POST", "/v1/webhooks/sources", body);
   if (!ok2xx(r)) throw new Error(`could not register the source (${apiErrText(r)})`);
   const d = dataOf(r);
   if (!d.source_id || !d.receiver_url_path) throw new Error("the source route returned no source_id/receiver_url_path");
-  return { source_id: d.source_id, receiver_url_path: d.receiver_url_path, provider: d.provider ?? body.provider };
+  return {
+    source_id: d.source_id,
+    receiver_url_path: d.receiver_url_path,
+    provider: d.provider ?? body.provider,
+    ...body.target_function ? { target_function: d.target_function ?? body.target_function } : {}
+  };
 }
 function sourceAddStdout(s, edgeBase, json2) {
   if (json2) return JSON.stringify({ source_id: s.source_id, provider: s.provider, receiver_url_path: s.receiver_url_path, receiver_url: `${edgeBase.replace(/\/$/, "")}${s.receiver_url_path}` });
@@ -10816,9 +10980,14 @@ function sourceAddStdout(s, edgeBase, json2) {
 function sourceAddNotices(s) {
   return [
     `\u2713 registered ${s.provider} source ${s.source_id} \u2014 the receiver URL above is shown ONCE; paste it into the provider's webhook settings`,
-    `a signing secret goes in \`vxil secrets set webhooks/source_${s.source_id}\` (a 'generic' source needs none); \`vxil listen --source ${s.source_id} --forward-to <url>\` forwards its events locally`
+    `a signing secret goes in \`vxil secrets set webhooks/source_${s.source_id.toLowerCase()}\` (a 'generic' source needs none); \`vxil listen --source ${s.source_id} --forward-to <url>\` forwards its events locally`,
+    ...s.target_function ? [`verified events are delivered to function ${s.target_function}: it needs a bare webhook binding (triggers: [{ kind: 'webhook' }]); a cron-only function is woken as a cron tick WITHOUT the event, and a function with neither binding skips it`] : []
   ];
 }
+function sourceDestination(s) {
+  if (s.target_function) return `fn:${s.target_function}`;
+  return s.forward_url || null;
+}
 async function sourcesList(api) {
   const r = await api("GET", "/v1/webhooks/sources");
   if (!ok2xx(r)) throw new Error(`could not list the sources (${apiErrText(r)})`);
@@ -11107,10 +11276,20 @@ function boundedData(data2, maxBytes, onTruncate) {
   const bytes = new TextEncoder().encode(text).length;
   if (bytes > maxBytes) {
     onTruncate?.(bytes);
-    return { truncated: true };
+    return truncatedStub(data2);
   }
   return data2;
 }
+function truncatedStub(data2) {
+  const stub = { truncated: true };
+  if (data2 && typeof data2 === "object" && !Array.isArray(data2)) {
+    for (const k of ["vxil_event_id", "source_id"]) {
+      const v = data2[k];
+      if (typeof v === "string" && /^[A-Za-z0-9_]{1,64}$/.test(v)) stub[k] = v;
+    }
+  }
+  return stub;
+}
 function webhookPayload(inner, maxBytes = WEBHOOK_PAYLOAD_MAX_BYTES) {
   return {
     event: inner.webhook_event,
@@ -11361,6 +11540,7 @@ function controlPlaneFunctionScope(method, pathname) {
   const read = m === "GET" || m === "HEAD";
   if (pathname === "/v1/users" || pathname.startsWith("/v1/users/")) return read ? "users:read" : "users:write";
   if (pathname === "/v1/usage") return read ? "usage:read" : null;
+  if (pathname === "/v1/audit" || pathname === "/v1/audit/export") return read ? "audit:read" : null;
   return null;
 }
 function json(body, status, headers = {}) {
@@ -11774,6 +11954,16 @@ export type VxilFilterJson = string | number | boolean | { $eq?: string | number
 }
 
 // ../../workers/mcp-v1/src/tools.ts
+function auditExportQuery(a) {
+  const qs = new URLSearchParams();
+  for (const k of ["subject", "since", "until", "after_id"]) {
+    const v = a[k];
+    if (typeof v === "string" && v) qs.set(k, v);
+  }
+  const n = Number(a.limit);
+  qs.set("limit", String(Number.isFinite(n) ? Math.min(Math.max(Math.trunc(n), 1), 1e3) : 500));
+  return qs.toString();
+}
 var TOOLS = [
   {
     name: "users_upsert",
@@ -12278,7 +12468,7 @@ var TOOLS = [
   {
     name: "jobs_replay_run",
     feature: "jobs",
-    description: "Replay a finished plain run (dead / failed / cancelled / succeeded): a NEW run with the same job, target and payload is queued (replayed_from names the original). The target receives it like any delivery \u2014 dedupe on run_id if it must not act twice. A generation run is not replayable (409 not_replayable): enqueue the generation again.",
+    description: "Replay a finished plain run (dead / failed / cancelled / succeeded): a NEW run with the same job, target and payload is queued (replayed_from names the original). The target receives it like any delivery \u2014 dedupe on run_id if it must not act twice. A generation run is not replayable (409 not_replayable): enqueue the generation again. A redacted or erased run is not replayable either (409 run_redacted): its payload is gone.",
     inputSchema: {
       type: "object",
       properties: { run_id: { type: "string" } },
@@ -12287,6 +12477,20 @@ var TOOLS = [
     method: "POST",
     path: (a) => `/v1/jobs/runs/${encodeURIComponent(String(a.run_id))}/replay`
   },
+  {
+    name: "jobs_redact_runs",
+    feature: "jobs",
+    description: "Redact FINISHED runs that hold personal data (a privacy request for runs nothing links to a user, e.g. a plain queue run or an async function call): payload becomes { erased: true }; result, progress, callback body and error text are cleared; a generation's provider request body/headers are dropped and its credit hold's user id is pseudonymized (unless its settle is still owed). The run row stays (state, timings, job_name). Send EXACTLY ONE of run_ids (\u2264500; open runs are left alone and counted in skipped_open) or user_id (the generation runs whose credit hold names that user \u2014 one page of \u2264500 per call; done:false \u2192 call again). Idempotent; irreversible; a redacted run no longer replays. concurrency_key, debounce_key, idempotency_key and target_url are NOT cleared \u2014 keep user ids out of them. Answers { redacted, skipped_open, done }.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        run_ids: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 500, description: "Finished runs to redact." },
+        user_id: { type: "string", description: "Redact the finished generation runs whose credit hold names this end-user." }
+      }
+    },
+    method: "POST",
+    path: "/v1/jobs/runs/redact"
+  },
   {
     name: "jobs_emit_event",
     feature: "jobs",
@@ -12645,7 +12849,7 @@ var TOOLS = [
   {
     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). Each field row carries its attributes \u2014 required, validation, index_slot, relation_to, computed/compute, is_unique, on_delete, read_roles (the end-user org roles allowed to READ that field; null = ungated), and on an equality-indexed field indexed: true + index_ready (equality filters on it are index-served once ready; until then, and on unindexed unslotted fields, they are a bounded scan \u2014 same results). A field with read_roles is omitted from end-user reads without a matching role and is never served on the public lane, so a missing key in an item's data may be a read gate rather than an unset value. Each collection row also carries end_user_access: 'readwrite' (default), 'read' (a verified end user \u2014 a thin-client key with a session \u2014 may read but every write answers 403 server_only) or 'none' (end-user reads and writes are 403 server_only); server keys are never affected.",
+    description: "List the tenant's content model: collections with their typed field definitions (the schema items are validated against). Each field row carries its attributes \u2014 required, validation, index_slot, relation_to, computed/compute, is_unique, on_delete, read_roles (the end-user org roles allowed to READ that field; null = ungated), and on an equality-indexed field indexed: true + index_ready (equality filters on it are index-served once ready; until then, and on unindexed unslotted fields, they are a bounded scan \u2014 same results). A field with read_roles is omitted from end-user reads without a matching role and is never served on the public lane, so a missing key in an item's data may be a read gate rather than an unset value. Each collection row also carries end_user_access: 'readwrite' (default), 'read' (a verified end user \u2014 a thin-client key with a session \u2014 may read but every write answers 403 server_only) or 'none' (end-user reads and writes are 403 server_only), and write_roles: the roles a verified end user must hold to WRITE the collection (null = ungated; without one every end-user write answers 403 role_required, reads are unaffected); server keys are never affected. retain_days (null = keep) is the collection's retention: the nightly platform sweep soft-deletes live items created more than that many days ago.",
     inputSchema: { type: "object", properties: {} },
     method: "GET",
     path: "/v1/cms/collections"
@@ -12653,13 +12857,23 @@ var TOOLS = [
   {
     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.",
+    description: "Create a content item in a collection. data must match the collection field defs (call cms_list_collections first). status draft|published. Upsert: pass onConflict {field, patch} where field is a unique field present in data \u2014 if a live item already holds that value, patch is merged into it instead (200, audited and hooked as an update; null clears a field), else the item is created (201).",
     inputSchema: {
       type: "object",
       properties: {
         collection: { type: "string" },
         data: { type: "object", additionalProperties: true },
-        status: { type: "string", enum: ["draft", "published"], default: "draft" }
+        status: { type: "string", enum: ["draft", "published"], default: "draft" },
+        onConflict: {
+          type: "object",
+          description: "Upsert by a declared unique field: { field: <unique field in data>, patch: { \u2026merge-patch applied to the existing item } }.",
+          properties: {
+            field: { type: "string" },
+            patch: { type: "object", additionalProperties: true }
+          },
+          required: ["field", "patch"],
+          additionalProperties: false
+        }
       },
       required: ["collection", "data"]
     },
@@ -12669,7 +12883,7 @@ var TOOLS = [
   {
     name: "cms_query_items",
     feature: "cms",
-    description: 'Query content items with the bounded DSL. filter is a JSON object (\u22648 terms): {"price":{"$gte":10},"status":"published"}; ops $eq $ne $gt $gte $lt $lte $in $contains $startsWith (substring/prefix, LIKE-escaped) $arrayContains/$anyOf (array fields: all-of / any-of). Equality ($eq / bare value / $in) is index-served on slot-indexed and `indexed` fields; on other fields it is a bounded scan (same results). sort: "-field" (slot-indexed fields + created_at/updated_at/published_at). Paging: pass the returned next_cursor back as cursor WITH THE SAME filter and sort (works for the default order and for any slot/timestamp sort; not for a dotted join sort). $expand inlines relation/file fields. count=true returns {count} instead of a page (filter only \u2014 no sort/limit/cursor/$expand).',
+    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 ($ne counts an absent/null field as not equal) $contains $startsWith (substring/prefix, LIKE-escaped) $arrayContains/$anyOf (array fields: all-of / any-of). Equality ($eq / bare value / $in) is index-served on slot-indexed and `indexed` fields; on other fields it is a bounded scan (same results). sort: "-field" (slot-indexed fields + created_at/updated_at/published_at). Paging: pass the returned next_cursor back as cursor WITH THE SAME filter and sort (works for the default order and for any slot/timestamp sort; not for a dotted join sort). $expand inlines relation/file fields. count=true returns {count} instead of a page (filter only \u2014 no sort/limit/cursor/$expand).',
     inputSchema: {
       type: "object",
       properties: {
@@ -13140,6 +13354,46 @@ var TOOLS = [
     method: "DELETE",
     path: (a) => `/v1/functions/${encodeURIComponent(String(a.name))}`
   },
+  {
+    name: "functions_list",
+    feature: "functions",
+    description: "The project's deployed functions: name, endpoint (/v1/fn/<name>), trigger bindings, scopes, limits and the runtime each runs under, plus `enabled` (false while the project's functions are paused as a whole \u2014 invokes then answer 404) and `cpuMsCeiling`. Read-only; any authenticated key may read it. Use it before functions_invoke or functions_logs to get the exact names.",
+    inputSchema: { type: "object", properties: {} },
+    method: "GET",
+    path: "/v1/functions"
+  },
+  {
+    name: "functions_invoke",
+    feature: "functions",
+    description: "Invoke ONE deployed function synchronously (POST /v1/fn/<name>) and return its own response verbatim (not a {data, meta} envelope). Every argument other than `name` is sent as the JSON request body, which the function reads as its payload. At-least-once semantics are the function's own: send an `idempotency_key` argument only if the function reads one from its payload. 404 when the name is not deployed; 403 without functions:invoke. Runs tenant code \u2014 it is metered like any invoke.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "The deployed function name (lowercase, e.g. on-payment)." }
+      },
+      required: ["name"],
+      additionalProperties: true
+    },
+    method: "POST",
+    path: (a) => `/v1/fn/${encodeURIComponent(String(a.name))}`,
+    pathArgs: ["name"]
+  },
+  {
+    name: "functions_logs",
+    feature: "functions",
+    description: "Log records of ONE deployed function, one per invocation (ts, outcome, wall_ms, cpu_ms, console lines, exceptions), oldest first, with `next_since` \u2014 pass it back as `since` to read only newer records (a tail). Without `since`: the most recent records of the last 24 hours. Kept 14 days. Needs functions:read.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "The deployed function name." },
+        since: { type: "string", description: "ISO timestamp: only lines after it (the previous call's next_since)." }
+      },
+      required: ["name"]
+    },
+    method: "GET",
+    path: (a) => `/v1/functions/${encodeURIComponent(String(a.name))}/logs`,
+    queryArgs: ["since"]
+  },
   {
     name: "webhooks_test_subscription",
     feature: "webhooks",
@@ -13155,7 +13409,7 @@ var TOOLS = [
   {
     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.",
+    description: "Send a sample inbound envelope to a source's destination (its forward_url, or its target_function) 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 neither.",
     inputSchema: {
       type: "object",
       properties: { source_id: { type: "string" } },
@@ -13184,6 +13438,25 @@ var TOOLS = [
     method: "GET",
     path: "/v1/webhooks/events/catalog"
   },
+  {
+    name: "webhooks_list_events",
+    feature: "webhooks",
+    description: "Received INBOUND webhook events (what providers POSTed to your sources): event id, source, provider, provider event id, type, payload, whether the signature verified, and the forward status. Newest first, paged with `cursor` (next_cursor); or pass `after` (an event id \u2014 your watermark) to read OLDEST first from just after it, storing `next_after` (has_more says another page waits; the after drain answers only events at least 10 s old, so a stored watermark never skips a late-committing event). `event_id` reads exactly one event. Filter by source_id and status. Needs webhooks:read.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        source_id: { type: "string" },
+        status: { type: "string", enum: ["received", "forwarding", "forwarded"] },
+        cursor: { type: "string", description: "next_cursor of the previous (newest-first) page." },
+        after: { type: "string", description: "An event id: answer the events after it, oldest first. Exclusive with cursor." },
+        event_id: { type: "string", description: "Exactly this event." },
+        limit: { type: "number", default: 50, description: "1..200" }
+      }
+    },
+    method: "GET",
+    path: "/v1/webhooks/events",
+    queryArgs: ["source_id", "status", "cursor", "after", "event_id", "limit"]
+  },
   {
     name: "feeds_add_activity",
     feature: "activity-feed",
@@ -13452,7 +13725,8 @@ var TOOLS = [
         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." }
+        user_id: { type: "string", description: "Opaque end_user_id for per-user usage metering." },
+        min_similarity: { type: "number", minimum: -1, maximum: 1, description: "Ground only on chunks whose cosine similarity to the query is at least this (-1..1). Overrides rag config retrieval.minSimilarity." }
       },
       required: ["query"]
     },
@@ -13462,7 +13736,7 @@ var TOOLS = [
   {
     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.",
+    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_similarity) before paying for an answer.",
     inputSchema: {
       type: "object",
       properties: {
@@ -13473,7 +13747,8 @@ var TOOLS = [
         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. score is a rank value (about 0.016-0.033 at the top), so a floor above ~0.033 drops every hit; judge relevance by each hit's similarity instead." }
+        min_score: { type: "number", description: "Drop hits below this EFFECTIVE (post-boost) score. score is a rank value (about 0.016-0.033 at the top), so a floor above ~0.033 drops every hit; use min_similarity for a relevance threshold." },
+        min_similarity: { type: "number", minimum: -1, maximum: 1, description: "Drop hits whose cosine similarity to the query is below this (-1..1), e.g. 0.5. Overrides rag config retrieval.minSimilarity; a hit with no measured similarity (keyword mode) is kept." }
       },
       required: ["query"]
     },
@@ -13594,6 +13869,41 @@ var TOOLS = [
     method: "GET",
     path: "/v1/usage"
   },
+  {
+    name: "audit_query",
+    description: "The project's audit trail, newest first: every write and lifecycle event (id, event, actor, surface, request_id, payload, created_at), paged with `cursor` (next_cursor). `subject` narrows to the events about ONE thing: a user id (payload.user_id / payload.id), a cms record (payload.item_id \u2014 the record's history), a verified end user (payload.end_user_id \u2014 what that person changed through a thin-client key or a function acting for them, and their payments events), or a principal (actor). Read-only; server keys only (refused in end-user mode). Needs audit:read or features:read.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        subject: { type: "string", description: "A user id, cms item id, end-user id or actor to filter by." },
+        since: { type: "string", description: "ISO timestamp lower bound." },
+        cursor: { type: "string", description: "next_cursor of the previous page." },
+        limit: { type: "number", default: 50, description: "1..200" }
+      }
+    },
+    method: "GET",
+    path: "/v1/audit",
+    queryArgs: ["subject", "since", "cursor", "limit"]
+  },
+  {
+    name: "audit_export",
+    description: "Export the audit trail OLDEST first as NDJSON (one event per line) for a window \u2014 the evidence/compliance read. Resume with `after_id` = the id of the last line. Same `subject` filter as audit_query. At most 1000 rows per call from this tool (default 500) so the answer fits an agent's context; page with after_id. Read-only; server keys only. Needs audit:read or features:read.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        subject: { type: "string", description: "A user id, cms item id, end-user id or actor to filter by." },
+        since: { type: "string", description: "ISO timestamp lower bound (inclusive)." },
+        until: { type: "string", description: "ISO timestamp upper bound (exclusive)." },
+        after_id: { type: "string", description: "Continue after this audit id (the last line of the previous call)." },
+        limit: { type: "number", default: 500, description: "1..1000" }
+      }
+    },
+    method: "GET",
+    // The REST route allows 10 000 rows; an MCP answer is model context, so
+    // the tool clamps the page (auditExportQuery builds the whole query; the
+    // path stays one literal so the trinity-drift scanner reads the route).
+    path: (a) => `/v1/audit/export?${auditExportQuery(a)}`
+  },
   {
     name: "copilot_send_message",
     feature: "copilot",
@@ -14289,6 +14599,22 @@ function parseKeyEnv(raw) {
   if (raw === "live" || raw === "test") return { env: raw };
   return { error: `--env must be 'live' or 'test' (got '${raw}') \u2014 this is the key's env prefix, not the project's environment label` };
 }
+function parseKeyClass(rawClass, endUserRequired) {
+  if (rawClass !== void 0 && rawClass !== "server" && rawClass !== "public") {
+    return { error: `--class must be 'server' or 'public' (got '${rawClass}') \u2014 public = a thin-client key for a browser / mobile app (end_user_required)` };
+  }
+  if (rawClass === "server" && endUserRequired) {
+    return { error: "--end-user-required makes a public (thin-client) key \u2014 drop it, or use --class public" };
+  }
+  return { keyClass: endUserRequired ? "public" : rawClass ?? "server" };
+}
+function checkPublicKeyScopes(scopes) {
+  const denied = scopes.filter((s) => PUBLIC_KEY_DENY_SCOPES.has(s));
+  if (!denied.length) return null;
+  return {
+    error: `a public (thin-client) key cannot carry server-only scope${denied.length > 1 ? "s" : ""}: ${denied.join(", ")} \u2014 keep the public key to end-user data scopes (e.g. cms:read,cms:write,files:write,realtime:write,auth:signin) and mint a separate server key for your backend`
+  };
+}
 function parseKeyName(raw) {
   const name = (raw ?? "").trim();
   if (!name) return { error: "--name is required \u2014 a label for this key, e.g. --name web-worker" };
@@ -14299,7 +14625,7 @@ async function mintKeyViaSession(dash, cookie, tenantId, req) {
   const r = await dash(
     "POST",
     `/dashboard/tenants/${tenantId}/api-keys`,
-    { name: req.name, scopes: req.scopes, env: req.env },
+    { name: req.name, scopes: req.scopes, env: req.env, ...req.keyClass === "public" ? { end_user_required: true } : {} },
     cookie
   );
   if (r.status === 401) return { unauthorized: true };
@@ -14315,7 +14641,10 @@ async function mintKeyViaSession(dash, cookie, tenantId, req) {
       scopes: d.scopes ?? req.scopes,
       env: d.env ?? req.env,
       name: req.name,
-      ...d.prefix ? { prefix: d.prefix } : {}
+      ...d.prefix ? { prefix: d.prefix } : {},
+      // report ONLY what the server says it minted: a stale server that
+      // ignored the flag (and so omits the field) must not read as public
+      ...d.end_user_required === true ? { end_user_required: true } : {}
     }
   };
 }
@@ -14386,7 +14715,7 @@ function revokeGuard(args) {
   return { ok: true, row: row2, isCurrent };
 }
 function mintStdout(r, json2) {
-  return json2 ? JSON.stringify({ api_key: r.api_key, key_id: r.key_id, scopes: r.scopes }) : r.api_key;
+  return json2 ? JSON.stringify({ api_key: r.api_key, key_id: r.key_id, scopes: r.scopes, ...r.end_user_required ? { end_user_required: true } : {} }) : r.api_key;
 }
 function mintNotices(r, json2, opts = {}) {
   const storage = opts.stored ? "It was stored as this project's CLI key (~/.vxil/credentials.json), replacing the previous one." : "It was NOT stored on this machine (pass --store to make it this project's CLI key).";
@@ -14398,7 +14727,8 @@ function mintNotices(r, json2, opts = {}) {
     ];
   }
   return [
-    `\u2713 minted '${r.name}' (${r.key_id}, env ${r.env}) with scopes [${r.scopes.join(", ")}]`,
+    `\u2713 minted '${r.name}' (${r.key_id}, env ${r.env}${r.end_user_required ? ", public / end_user_required" : ""}) with scopes [${r.scopes.join(", ")}]`,
+    ...r.end_user_required ? ["A public key belongs in your browser / mobile app: every request must carry the signed-in user's session (X-Vxil-End-User), and it acts only as that user."] : [],
     `This key is shown ONCE and is not retrievable again \u2014 copy it now. ${storage} Revoke with \`vxil keys revoke ${r.key_id}\`.`,
     ...storeWarn
   ];
@@ -14904,7 +15234,7 @@ var VERB_USAGE = {
   projects: "usage: vxil projects [list] [--json] \xB7 projects create <slug> [--name <display>] [--workload production|staging|development] [--json] \xB7 projects workload <slug> production|staging|development [--json] \xB7 projects rm <slug> [--yes] [--json]",
   billing: "usage: vxil billing [status] [--json] \xB7 vxil billing upgrade --tier <free|developer|team|business> [--yes] [--json]   (upgrade also downgrades: --tier free)",
   files: "usage: vxil files put <path> --user <user_id> [--content-type <type>] [--json] \xB7 vxil files rm <object_id> [--yes] [--json]",
-  webhooks: "usage: vxil webhooks sources add --provider <stripe|paddle|github|slack|revenuecat|generic> --name <n> [--forward-url <https>] \xB7 sources list \xB7 sources rm <source_id> [--yes] \xB7 sources test <source_id> \xB7 vxil webhooks events replay <event_id> \xB7 events runs <event_id>",
+  webhooks: "usage: vxil webhooks sources add --provider <stripe|paddle|github|slack|revenuecat|generic|hmac> --name <n> [--forward-url <https> | --target-function <fn>] [--verify <json> (hmac)] \xB7 sources list \xB7 sources rm <source_id> [--yes] \xB7 sources test <source_id> \xB7 vxil webhooks events replay <event_id> \xB7 events runs <event_id>",
   search: "usage: vxil search sync run <sourceKey> [--sweep] [--json] \xB7 vxil search sync reset <sourceKey> [--purge] [--yes] [--json]",
   listen: "usage: vxil listen --forward-to <url> [--dev] [--source <id>] [--events <prefix,\u2026>] [--replay-last <n>] [--interval <s>] [--show-runs] [--raw]  \u2014 forward inbound webhook events to a local server",
   mcp: "usage: vxil mcp install [--client cursor|claude|vscode] [--project] [--print] [--key <api_key>] [--scopes a,b] [--name <server>]",
@@ -18054,12 +18384,13 @@ async function runListen(deps, opts) {
   if (sres.body.error || sres.status >= 400) throw envelopeError(sres, "list webhook sources");
   let tenantId = sres.body.meta?.tenant_id;
   const sources = sres.body.data?.sources ?? [];
+  const destOf = new Map(sources.map((s) => [s.source_id, s.target_function ? `fn:${s.target_function}` : s.forward_url || null]));
   if (sources.length === 0) {
     deps.err("no webhook sources yet \u2014 create one (dashboard \u2192 Webhooks, or POST /v1/webhooks/sources) and point the provider at its receiver URL; waiting for events anyway\u2026");
   } else {
     deps.err(`sources (${sources.length}):`);
     for (const s of sources) {
-      deps.err(`  ${s.source_id}  ${s.provider}  ${s.name}${s.forward_url ? "" : "  (no forward_url \u2014 this listener is the only delivery)"}`);
+      deps.err(`  ${s.source_id}  ${s.provider}  ${s.name}${destOf.get(s.source_id)?.startsWith("fn:") ? `  \u2192 ${destOf.get(s.source_id)}` : ""}${destOf.get(s.source_id) ? "" : "  (no forward_url \u2014 this listener is the only delivery)"}`);
     }
   }
   let signingSecret;
@@ -18105,7 +18436,8 @@ async function runListen(deps, opts) {
       } else {
         const runs = rr.body.data?.runs ?? [];
         if (runs.length === 0) {
-          deps.err("   runs: none (the source has no forward_url \u2014 this listener is the only delivery)");
+          const dest = ev.source_id ? destOf.get(ev.source_id) : void 0;
+          deps.err(dest ? `   runs: none yet (the source delivers to ${dest})` : "   runs: none (the source has no forward_url \u2014 this listener is the only delivery)");
         } else {
           for (const r of runs) {
             deps.err(`   run ${r.run_id}: ${r.state} (attempt ${r.attempt_number ?? 0}/${r.max_attempts ?? "?"}${r.dead_lettered ? ", DLQ" : ""})`);
@@ -22191,12 +22523,15 @@ try {
     }
     case "keys": {
       const [sub, arg] = positional(0);
-      const KEYS_USAGE = "usage: vxil keys mint --name <name> --scopes <a,b,c> [--env live|test] [--store] [--json] \xB7 vxil keys list [--json] \xB7 vxil keys revoke <key_id> [--yes] \xB7 vxil keys perms <key_id> [--allow <a,b> | --clear-allow] [--deny <c> | --clear-deny] [--json]";
+      const KEYS_USAGE = "usage: vxil keys mint --name <name> --scopes <a,b,c> [--env live|test] [--class server|public] [--end-user-required] [--store] [--json] \xB7 vxil keys list [--json] \xB7 vxil keys revoke <key_id> [--yes] \xB7 vxil keys perms <key_id> [--allow <a,b> | --clear-allow] [--deny <c> | --clear-deny] [--json]";
       if (sub === "help" || hasFlag("help")) {
         console.log(`${KEYS_USAGE}
   mint    a NARROW scoped key for a server on the linked project \u2014 scopes are validated
           locally (admin refused); the key prints ONCE on stdout (--json \u2192 { api_key, key_id,
-          scopes }) and is stored as this machine's CLI key only under --store
+          scopes }) and is stored as this machine's CLI key only under --store.
+          --class public (or --end-user-required) mints the thin-client key for a browser /
+          mobile app \u2014 the dashboard's "Public" class: it only works with a signed-in
+          user's session, server-only scopes are refused, and it cannot be --store'd
   list    names, ids, scopes, env, created, last-used \u2014 never a secret; * marks the CLI's key
   revoke  type the key id to confirm (--yes for scripts); refuses the CLI's own key unless --yes
   perms   the key's MCP tool permissions: with no flag, shows them; --allow / --deny set a
@@ -22226,7 +22561,14 @@ try {
         if ("error" in scopes) fail(scopes.error);
         const env = parseKeyEnv(flag("env"));
         if ("error" in env) fail(env.error);
-        return { name: name.name, scopes: scopes.scopes, env: env.env };
+        const cls = parseKeyClass(flag("class"), hasFlag("end-user-required"));
+        if ("error" in cls) fail(cls.error);
+        if (cls.keyClass === "public") {
+          const bad = checkPublicKeyScopes(scopes.scopes);
+          if (bad) fail(bad.error);
+          if (hasFlag("store")) fail("--store refused for a public key \u2014 it cannot drive the CLI (every request needs an end-user session); copy it into your app instead");
+        }
+        return { name: name.name, scopes: scopes.scopes, env: env.env, keyClass: cls.keyClass };
       })() : void 0;
       const t = resolveTargetOrFail(selector());
       if (!t.tenantSlug) fail("no linked project \u2014 run `vxil link <slug>` (or `vxil quickstart`) first; keys are minted on the bound project");
@@ -22640,10 +22982,16 @@ try {
     }
     case "webhooks": {
       const [sub, verb, arg] = positional(0);
-      const WEBHOOKS_USAGE = "usage: vxil webhooks sources add --provider <stripe|paddle|github|slack|revenuecat|generic> --name <n> [--forward-url <https>] \xB7 sources list \xB7 sources rm <source_id> [--yes] \xB7 sources test <source_id> \xB7 vxil webhooks events replay <event_id> \xB7 events runs <event_id>";
+      const WEBHOOKS_USAGE = "usage: vxil webhooks sources add --provider <stripe|paddle|github|slack|revenuecat|generic|hmac> --name <n> [--forward-url <https> | --target-function <fn>] [--verify <json> (hmac)] \xB7 sources list \xB7 sources rm <source_id> [--yes] \xB7 sources test <source_id> \xB7 vxil webhooks events replay <event_id> \xB7 events runs <event_id>";
       if (sub === "sources") {
         if (verb === "add") {
-          const p = parseSourceAdd({ provider: flag("provider"), name: flag("name"), forwardUrl: flag("forward-url") });
+          const p = parseSourceAdd({
+            provider: flag("provider"),
+            name: flag("name"),
+            forwardUrl: flag("forward-url"),
+            targetFunction: flag("target-function"),
+            verify: flag("verify")
+          });
           if ("error" in p) fail(p.error);
           const { api, baseUrl } = requireApi(selector(), { write: `webhooks sources add ${p.body.name}` });
           const s = await sourcesAdd(api, p.body);
@@ -22656,7 +23004,10 @@ try {
           const rows = await sourcesList(api);
           if (jsonOut) console.log(JSON.stringify({ sources: rows }, null, 2));
           else if (!rows.length) console.log("(no inbound sources \u2014 `vxil webhooks sources add --provider \u2026 --name \u2026`)");
-          else for (const r of rows) console.log(`${r.source_id}  ${String(r.provider).padEnd(10)} ${r.name}`);
+          else for (const r of rows) {
+            const dest = sourceDestination(r);
+            console.log(`${r.source_id}  ${String(r.provider).padEnd(10)} ${r.name}${dest ? `  \u2192 ${dest}` : ""}`);
+          }
           break;
         }
         if (verb === "rm") {
@@ -23398,7 +23749,7 @@ export default defineConfig(${JSON.stringify({ features: featBlocks, cms: { coll
     default:
       console.log(`vxil \u2014 a Supabase-grade code-first CLI for the whole platform
   --version \xB7 init [--template <id>] \xB7 templates \xB7 try (keyless sandbox) \xB7 quickstart [--features a,b] [--invite <code>] [--env <label>] [--dev [--ttl <h>]] [--no-push] \xB7 login \xB7 link <slug> [--key <k> [--tenant <id>]] [--as dev|<name>] [--env <label>] [--mint]
-  keys mint --name <n> --scopes <a,b,c> [--env live|test] [--store] \xB7 keys list \xB7 keys revoke <key_id> [--yes]  \u2014 a NARROW scoped key for a server (shown once; needs a vxil login session)
+  keys mint --name <n> --scopes <a,b,c> [--env live|test] [--class server|public] [--store] \xB7 keys list \xB7 keys revoke <key_id> [--yes]  \u2014 a NARROW scoped key for a server (shown once; needs a vxil login session)
   keys perms <key_id> [--allow <a,b> | --clear-allow] [--deny <c> | --clear-deny]  \u2014 a key's MCP tool permissions (admin+)
   account [show] \xB7 account set [--locale <code>] [--display-name <n>] \xB7 account password \xB7 logout \xB7 invites [list] \xB7 invites generate [--count <n>] \xB7 invites accept <token|url>
   members [list] \xB7 members invite <email> --role <r> \xB7 members add <email> --role <r> \xB7 members rm <user_id|email> [--yes] \xB7 members uninvite <email|id> [--yes]  \u2014 the bound project's team (session)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/cli",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "private": false,
   "description": "The vxil CLI — init, quickstart, push, gen, secrets, keys, migrate, doctor, diff, functions, payments; installs the `vxil` command (npm i -g @vxil/cli).",
   "license": "MIT",
@@ -46,10 +46,10 @@
   },
   "devDependencies": {
     "miniflare": "^4.20260611.0",
-    "@vxil/config": "0.12.0",
+    "@vxil/config": "0.13.0",
+    "@vxil/feature-configs": "0.11.0",
     "@vxil/runtime": "0.0.1",
-    "@vxil/types": "0.0.1",
-    "@vxil/feature-configs": "0.10.0"
+    "@vxil/types": "0.0.1"
   },
   "scripts": {
     "build": "pnpm --filter @vxil/feature-configs run build && pnpm --filter @vxil/config run build && esbuild bin/vxil.ts --bundle --platform=node --format=esm --target=node24 --outfile=dist/vxil.js --banner:js='#!/usr/bin/env node' --external:esbuild --external:miniflare && esbuild src/config-entry.ts --bundle --platform=node --format=esm --target=node24 --outfile=dist/config.js && pnpm exec tsx scripts/build-config-dts.ts",