@vxil/feature-configs 0.7.0 → 0.8.0

package/dist/index.js

@@ -1,32 +1,37 @@
 // Per-feature TypeBox config schemas + the 15-leaf cap analyzer.
-// Location note (journaled deviation): the docs place each schema inside its
-// feature Worker; the control plane must validate writes against the same
-// schema (architecture §7.1 stage 2), so schemas live in this shared package
+// Location note: each schema belongs to its feature, but the config-write
+// path must validate writes against the same schema, so schemas live in this
+// shared package
 // and feature Workers import from here — one definition, two consumers.
 import { FormatRegistry, OptionalKind, Type } from '@sinclair/typebox';
 import { Value } from '@sinclair/typebox/value';
 import { validateHooksConfig } from './hooks.js';
 import { validateCdcConfig, validateReadModelsConfig } from './readmodels.js';
 import { isFnTriggerSubscriptionUrl } from './apiState.js';
+import { PublicAssetsConfigSchema, VARIANT_PRESET_NAME_PATTERN } from './publicAssets.js';
 // Re-export the CMS lifecycle-hook engine so feature workers (cms-v1, runtime
 // eval) and the control plane (config-time validation) share one definition.
 export * from './hooks.js';
 // Re-export the cms-rel read-model/cdc config gates (the pure-mirror split:
 // grammar validated here at config-write; field existence at runtime).
 export * from './readmodels.js';
-// Re-export the DECLARED API STATE planner (roadmap §4.11 P0-3): pure
+// Re-export the DECLARED API STATE planner: pure
 // declared-vs-live reconciliation, shared by the control-plane apply path and
 // the CLI (`vxil plan/diff/push`), so the two push paths can never diverge.
 export * from './apiState.js';
 // Key-order-insensitive JSON: the one declared-vs-stored manifest compare
 // (control-plane shallowDiff, CLI diffManifest).
 export * from './canonicalJson.js';
+// Public asset delivery (files.publicAssets): the publishable content-type
+// allowlist, the URL/key shape and the variant presets — shared by files-v1
+// (publish) and files-cdn (serve), which never import each other.
+export * from './publicAssets.js';
 // TypeBox validates `format:` only for registered formats — register the ones
 // our schemas use (pragmatic RFC-lite email check; providers do the real one).
 if (!FormatRegistry.Has('email')) {
     FormatRegistry.Set('email', (v) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v));
 }
-// ── RESERVED (vxil-COGS) CREDIT TYPES — single source of truth (audit F2) ─────
+// ── RESERVED (vxil-COGS) CREDIT TYPES — single source of truth ─────────────────
 // `fn_cpu_ms` funds vxil's OWN function-compute cost-of-goods (the
 // functions "recover-by-price" meter). It must NEVER be grantable or consumable
 // by a tenant's own `payments:write` key, NOR mapped-in via ledger config — a
@@ -36,7 +41,7 @@ if (!FormatRegistry.Has('email')) {
 // config-write gate AND payments-v1 import) so the runtime choke point and the
 // config-write refusal share ONE list. payments-v1/core.ts re-exports these.
 export const RESERVED_CREDIT_TYPES = new Set(['fn_cpu_ms']);
-/** F33 (2026-09-25): a function binding's `retry.maxAttempts` ceiling, and the
+/** A function binding's `retry.maxAttempts` ceiling, and the
  *  binding kinds that may carry `retry` — the platform-delivered event lanes
  *  (an http invoke returns its own status; a cron tick's retry would overlap
  *  the next tick). Read by the schema, the deploy clamp and the CLI. */
@@ -47,7 +52,7 @@ export const FN_RETRY_BINDING_KINDS = new Set(['queue', 'webhook', 'cmsHook', 'a
 export function isReservedCreditType(creditType) {
     return RESERVED_CREDIT_TYPES.has(creditType);
 }
-// ── notifications template catalog (D4 per-locale overrides) ─────────────────
+// ── notifications template catalog (per-locale overrides) ────────────────────
 // The SHIPPED template ids and the placeholders each body may interpolate. The
 // renderer itself lives in workers/notifications-v1/src/templates.ts (templates
 // are code, not rows); this table is the CONFIG-TIME half so a `vxil push` that
@@ -72,7 +77,7 @@ export const NOTIFICATION_TEMPLATE_PLACEHOLDERS = {
 export const NOTIFICATION_TEMPLATE_SLOT_PLACEHOLDERS = {
     transactional: ['cta'],
 };
-/** Per-override caps (D4). Bodies are emails, not documents. */
+/** Per-override caps. Bodies are emails, not documents. */
 export const NOTIF_OVERRIDE_SUBJECT_MAX = 500;
 export const NOTIF_OVERRIDE_BODY_MAX = 20_000;
 /** Whole-map caps: keeps one manifest (and the KV row every send reads) small. */
@@ -84,7 +89,7 @@ const NOTIF_PLACEHOLDER_RE = /\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g;
 /** Same permissive BCP-47-ish shape the worker's auto-locale resolver accepts. */
 const NOTIF_LOCALE_RE = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8}){0,3}$/;
 /**
- * D4 — validate `templates.overrides` at CONFIG-WRITE time. Returns [] when the
+ * Validate `templates.overrides` at CONFIG-WRITE time. Returns [] when the
  * bag is absent or clean. Every rule fails LOUD rather than shipping something
  * that silently renders wrong in a customer's inbox:
  *   • overrides present with `allowOverride:false` → rejected (never inert);
@@ -173,12 +178,12 @@ export const NotificationsConfigSchema = Type.Object({
     // need no email account, so the mock path is zero-config. A cross-field
     // check in validateFeatureConfig requires it only when provider === 'resend'.
     resendApiKeyRef: Type.Optional(Type.String()),
-    // Optional per-tenant Resend/Svix ENDPOINT secret ref (public.tenant_secrets,
-    // envelope-encrypted under KEK_NOTIFICATIONS — same store as resendApiKeyRef).
+    // Optional per-tenant Resend/Svix ENDPOINT secret ref (a pointer into the
+    // tenant's encrypted secret store — same store as resendApiKeyRef).
     // When set, inbound Resend webhooks are verified with THIS tenant's secret
     // instead of the platform-wide PROVIDER_WEBHOOK_SECRET, binding the signature
     // to the tenant so a signed event for tenant A can never validate at tenant
-    // B's webhook URL (audit H6 — mirrors payments revenuecat.webhookSecretRef).
+    // B's webhook URL (mirrors payments revenuecat.webhookSecretRef).
     webhookSecretRef: Type.Optional(Type.String()),
     // 'mock' exists for staging/e2e (deterministic provider); 'resend' is MVP;
     // 'ses' (2026-09-19) is the second real provider — Amazon SES v2, BYO IAM
@@ -190,7 +195,7 @@ export const NotificationsConfigSchema = Type.Object({
     // cap rule — funded by folding `rateLimit` into an Optional bag below);
     // NO `default: {}` so an absent bag stays absent (the auth `security`
     // precedent). Both refs are `secret:<name>` POINTERS into
-    // public.tenant_secrets (feature='notifications', KEK_NOTIFICATIONS) —
+    // the tenant's encrypted secret store (feature='notifications') —
     // exactly how resendApiKeyRef resolves; the region is plain config (not a
     // secret) and is pattern-pinned to the AWS region grammar so a typo fails
     // at `vxil push` instead of as a DNS error on the first send. Required
@@ -212,7 +217,7 @@ export const NotificationsConfigSchema = Type.Object({
     // nested objects carry `default: {}` so Value.Default can materialize them
     // and then recurse into the leaf defaults.
     // `retry` became an OPTIONAL bag (2 leaves → 1, countLeaves counts an
-    // Optional object as ONE) to fund `broadcast` below (M21/#4, 2026-07-18).
+    // Optional object as ONE) to fund `broadcast` below (2026-07-18).
     // It KEEPS `default: {}`, which Value.Default still materializes — so every
     // persisted manifest carries retry.{maxAttempts,backoff} exactly as before
     // (zero behavioral delta); only the TS type is now optional (workers read
@@ -224,7 +229,7 @@ export const NotificationsConfigSchema = Type.Object({
         }),
     }, { default: {} })),
     suppression: Type.Object({ softBounceThreshold: Type.Integer({ default: 3 }) }, { default: {} }),
-    // `rateLimit` became an OPTIONAL bag (2 leaves → 1, the M21 `retry` trick)
+    // `rateLimit` became an OPTIONAL bag (2 leaves → 1, the `retry` trick)
     // on 2026-09-19 to fund the `ses` credential bag above. It KEEPS
     // `default: {}`, so Value.Default still materializes
     // rateLimit.{perDay,perTenantSec} into every persisted manifest exactly as
@@ -234,15 +239,15 @@ export const NotificationsConfigSchema = Type.Object({
         perDay: Type.Integer({ default: 100000 }),
         perTenantSec: Type.Integer({ default: 50 }),
     }, { default: {} })),
-    // `templates` became an OPTIONAL bag (1 leaf, the same M21 trick `retry`
-    // uses) to fund the D4 per-locale `overrides` map WITHOUT moving the count:
+    // `templates` became an OPTIONAL bag (1 leaf, the same trick `retry`
+    // uses) to fund the per-locale `overrides` map WITHOUT moving the count:
     // countLeaves scores an Optional object as ONE. `default: {}` is KEPT, so
     // Value.Default still materializes `templates.allowOverride` into every
     // persisted manifest exactly as before — zero behavioral delta; only the TS
     // type is optional (workers read via core.ts `templatesOf()`).
     templates: Type.Optional(Type.Object({
         allowOverride: Type.Boolean({ default: false }),
-        // D4 (2026-09-10) — TENANT-AUTHORED PER-LOCALE OVERRIDES of the SHIPPED
+        // (2026-09-10) TENANT-AUTHORED PER-LOCALE OVERRIDES of the SHIPPED
         // template ids, as config DATA (a Record = 1 leaf, catalog size never
         // moves the count). Shape: { [templateId]: { [locale]: { subject?,
         // html?, text? } } }. Same escaped `{{placeholder}}` grammar as the
@@ -267,10 +272,10 @@ export const NotificationsConfigSchema = Type.Object({
     }, { default: {} })),
     /** in-app inbox channel (send with channel: 'inbox' | 'both') */
     inboxEnabled: Type.Boolean({ default: false }),
-    /** §11b.5 broadcast campaigns channel. Optional bag (= 1 leaf): absent means
+    /** Broadcast campaigns channel. Optional bag (= 1 leaf): absent means
      * disabled; per-campaign quiet_hours / freq_cap overrides live on the
      * notifications.campaigns ROW (tenant data), not here. Folded into the
-     * canonical schema 2026-07-18 (M21/#4 — Value.Clean previously STRIPPED the
+     * canonical schema 2026-07-18 (Value.Clean previously STRIPPED the
      * worker-local extension, so campaigns 403'd via the real config path). */
     broadcast: Type.Optional(Type.Object({
         enabled: Type.Boolean({ default: false }),
@@ -290,16 +295,14 @@ export const NotificationsConfigSchema = Type.Object({
     })),
 });
 // ── jobs `generation` block: the ONE declaration of its defaults and bounds ──
-// (roadmap §4.10, 2026-09-25 — "dropping the jobs-v1 GENERATION_DEFAULTS
-// copy"). The JobsConfigSchema `generation` leaf reads these for its
+// (2026-09-25 — one copy of the generation defaults, not two). The JobsConfigSchema `generation` leaf reads these for its
 // `default` / `minimum` / `maximum`, and workers/jobs-v1/src/generation.ts
 // imports them (jobs-v1 already depends on @vxil/feature-configs; this package
 // has no @vxil/types dependency, so the shared value lives here — the
 // RESERVED_CREDIT_TYPES precedent). A future edit changes one object; the
-// feature-configs unit test pins schema ↔ constant, and the CI gate
-// tests/ci/src/generation-defaults-single-source.test.ts pins that no second
-// object-literal declaration of the constant reappears anywhere.
-/** Generation-lifecycle config defaults (jobs.md §11 / §5 ≤15-flag budget). */
+// feature-configs unit test pins schema ↔ constant, and a CI gate pins that no
+// second object-literal declaration of the constant reappears anywhere.
+/** Generation-lifecycle config defaults (guide ch. 6, jobs). */
 export const GENERATION_DEFAULTS = {
     /** per-tenant in-flight generation cap (separate budget from queue jobs) */
     maxConcurrent: 20,
@@ -339,7 +342,7 @@ export const JobsConfigSchema = Type.Object({
     dlqDailyQuota: Type.Integer({ default: 0, minimum: 0, maximum: 100_000 }),
     schedules: Type.Object({ maxPerTenant: Type.Integer({ default: 50, minimum: 1, maximum: 1000 }) }, { default: {} }),
     concurrency: Type.Object({ maxConcurrent: Type.Integer({ default: 10, minimum: 1, maximum: 100 }) }, { default: {} }),
-    // 2.F6 generation lifecycle knobs (jobs.md §11). The defaults and bounds are
+    // Generation lifecycle knobs (guide ch. 6, jobs). The defaults and bounds are
     // declared ONCE, as GENERATION_DEFAULTS / GENERATION_BOUNDS below this schema
     // (2026-09-25): jobs-v1's resolveGenerationConfig imports them and clamps a
     // pre-fold manifest to the same numbers — a hand-mirrored copy used to live
@@ -353,14 +356,14 @@ export const JobsConfigSchema = Type.Object({
         maxTimeoutMs: Type.Integer({ default: GENERATION_DEFAULTS.maxTimeoutMs, minimum: GENERATION_BOUNDS.maxTimeoutMs.min, maximum: GENERATION_BOUNDS.maxTimeoutMs.max }),
         /** poll-mode: how many poll cycles before giving up (→ terminal-fail) */
         pollMaxAttempts: Type.Integer({ default: GENERATION_DEFAULTS.pollMaxAttempts, minimum: GENERATION_BOUNDS.pollMaxAttempts.min, maximum: GENERATION_BOUNDS.pollMaxAttempts.max }),
-        /** MANDATORY per-hold cap on a generation `reserve_credits.amount` (jobs.md
-         * §11.8). Every requested amount is CLAMPED to this (never rejected) — a
+        /** MANDATORY per-hold cap on a generation `reserve_credits.amount`
+         * (guide ch. 6, jobs). Every requested amount is CLAMPED to this (never rejected) — a
          * conservative default so an untrusted deployed function that carries a
          * reserve block can never hold more than a bounded amount per run without
          * any tenant action. */
         maxReserveCredits: Type.Integer({ default: GENERATION_DEFAULTS.maxReserveCredits, minimum: GENERATION_BOUNDS.maxReserveCredits.min, maximum: GENERATION_BOUNDS.maxReserveCredits.max }),
         /** MANDATORY per-tenant ceiling on the SUM of un-settled provisional
-         * reserve holds across all in-flight generation runs (jobs.md §11.8): a
+         * reserve holds across all in-flight generation runs (guide ch. 6, jobs): a
          * reserve whose amount would push the tenant's outstanding-holds total over
          * this is rejected 429, so a runaway function cannot hold every user at
          * once. Defaulted so no tenant action is required to be safe. */
@@ -368,43 +371,42 @@ export const JobsConfigSchema = Type.Object({
     }, { default: {} }),
 });
 // One social-provider's BYO credential block. The *Ref fields are POINTERS into
-// public.tenant_secrets (envelope-encrypted) — never raw secrets (features/auth.md
-// §6.5). google/github/facebook share the clientId/secret shape; apple is distinct
+// the tenant's encrypted secret store — never raw secrets (guide ch. 6, auth).
+// google/github/facebook share the clientId/secret shape; apple is distinct
 // (Sign in with Apple has no static secret — it mints an ES256 client_secret from
-// the .p8, so it carries servicesId/teamId/keyId + a p8 keyRef, §6.4).
+// the .p8, so it carries servicesId/teamId/keyId + a p8 keyRef).
 const OAuthRefsSchema = Type.Object({
     // clientId/secret refs are OPTIONAL at the schema layer: a tenant may stage a
     // partial block, and the worker enforces presence at use (→ 501 if missing),
     // matching the worker's OAuthProviderRefs shape (core.ts). They stay POINTERS
-    // into tenant_secrets — never raw secrets (features/auth.md §6.5).
+    // into the tenant's secret store — never raw secrets (guide ch. 6, auth).
     clientIdRef: Type.Optional(Type.String()),
     clientSecretRef: Type.Optional(Type.String()),
     // extra native-aud allow-list entries (iOS/web client ids that differ from the
-    // primary clientIdRef) — also tenant_secrets refs (features/auth.md §6.4).
+    // primary clientIdRef) — also secret-store refs (guide ch. 6, auth).
     audRefs: Type.Optional(Type.Array(Type.String(), { maxItems: 16 })),
 });
 const AppleRefsSchema = Type.Object({
     servicesId: Type.String(), // the OAuth client_id / native aud (NOT a secret)
     teamId: Type.String(),
     keyId: Type.String(),
-    p8KeyRef: Type.String(), // tenant_secrets ref → envelope-encrypted .p8 PEM
+    p8KeyRef: Type.String(), // secret-store ref → the encrypted .p8 PEM
     // extra native-aud allow-list entries: genuine iOS ASAuthorization id_tokens
-    // carry the app BUNDLE ID as aud, not the Services ID (auth.md §6.4). Plain
+    // carry the app BUNDLE ID as aud, not the Services ID (guide ch. 6, auth). Plain
     // config values — bundle ids are not secrets. The worker already honors them
     // (oauthCore.ts nativeAudAllowList); declaring them here is what stops
     // Value.Clean stripping the field out of PUT /v1/config/auth.
     bundleIds: Type.Optional(Type.Array(Type.String(), { maxItems: 16 })),
 });
-// RB-2 — the generic OIDC / SSO bridge (roadmap §4.6.B, §1B.5; features/auth.md
-// §6.7). ONE tenant-supplied issuer, declared INSIDE the existing `providers`
+// The generic OIDC / SSO bridge (guide ch. 6, auth). ONE tenant-supplied issuer, declared INSIDE the existing `providers`
 // bag so it spends NO leaf (an Optional object bag = ONE leaf; auth stays 11).
 // Declarative + opt-in: the block's PRESENCE enables the `oidc` provider (no
 // methods.* toggle — a `default:false` flag would re-materialize every published
-// manifest, breaking the D3 byte-identical fold). The worker discovers the
+// manifest, breaking the byte-identical fold). The worker discovers the
 // endpoints + JWKS from `{issuer}/.well-known/openid-configuration` and verifies
 // iss (byte-equal) / aud (= clientId) / nonce / exp / iat strictly, fail-closed.
 // `clientId` is NOT a secret (it rides every authorize URL); `clientSecretRef`
-// is a tenant_secrets POINTER (feature 'auth'), never the value. A SAML IdP
+// is a secret-store POINTER (feature 'auth'), never the value. A SAML IdP
 // plugs in through a broker (Okta / Entra / Auth0 / WorkOS) that speaks OIDC —
 // there is deliberately NO native SAML.
 const OidcProviderSchema = Type.Object({
@@ -428,7 +430,7 @@ const OidcProviderSchema = Type.Object({
     // marks the email verified (the tenant declared the issuer authoritative).
     allowedDomains: Type.Optional(Type.Array(Type.String({ minLength: 3, maxLength: 253, pattern: '^[a-z0-9][a-z0-9.-]*\\.[a-z]{2,}$' }), { maxItems: 32 })),
     // default true: an identity whose VERIFIED email matches an existing user is
-    // linked to it (the shipped §6.4 rule). false: link only by the stable
+    // linked to it (the shipped social sign-in rule). false: link only by the stable
     // (issuer, sub) anchor; a matching email that is not yet linked → 409.
     autoLink: Type.Optional(Type.Boolean()),
 });
@@ -437,7 +439,7 @@ const OidcProviderSchema = Type.Object({
 // on every caller-supplied `redirect_url` / `redirect_uri` (core.ts
 // `isAllowedRedirectUrl`) must agree on WHICH schemes a sign-in link may be
 // delivered to, or a tenant could allow-list an origin the worker then refuses
-// (or the reverse). The rule (cvskit gap 7, 2026-09-19): `https://` on any
+// (or the reverse). The rule (2026-09-19): `https://` on any
 // host, plus PLAIN `http://` ONLY on the two loopback names — `localhost` and
 // `127.0.0.1`, any port — so a local dev server can complete a magic link
 // without a staging origin. Any other `http://` (a LAN host, `*.local`, a
@@ -448,7 +450,7 @@ const OidcProviderSchema = Type.Object({
 // with THIS predicate, and auth-v1 calls it on the parsed URL — the parity test
 // in index.test.ts / redirectRule.test.ts holds the two together. The CLI's
 // production promotion gate still refuses any `http://` origin on a
-// production push (cli-sdk.md), so a loopback entry is a DEV-tenant affair.
+// production push, so a loopback entry is a DEV-tenant affair.
 export const REDIRECT_ORIGIN_PATTERN = '^(https://[^/?#\\s]+|http://(localhost|127\\.0\\.0\\.1)(:[0-9]{1,5})?)$';
 /** THE scheme rule for a redirect/return URL: https anywhere, http on loopback
  *  only. Takes the parsed URL (or any {protocol, hostname} pair) so the config
@@ -473,13 +475,13 @@ export function isAllowedRedirectOriginEntry(entry) {
 }
 export const AuthConfigSchema = Type.Object({
     enabled: Type.Boolean({ default: true }),
-    // D3 (auth wave 2026-09-10): the six method toggles collapsed into ONE
+    // (2026-09-10) the six method toggles collapsed into ONE
     // Optional bag (6 leaves → 1, countLeaves counts an Optional object as ONE) —
     // the notifications `retry`/`broadcast` precedent. It KEEPS `default: {}`,
     // which Value.Default still materializes, so every persisted manifest carries
     // methods.{emailPassword,magicLink,google,github,apple,facebook} with the
     // SAME keys and defaults as before — byte-identical folds for existing
-    // tenants (index.test.ts "D3 fold bytes"). Only the TS type is now optional;
+    // tenants (index.test.ts pins the fold bytes). Only the TS type is now optional;
     // the worker's gate() normalizes an absent bag to the defaults so every
     // reader (config.methods.<flag>) is unchanged.
     methods: Type.Optional(Type.Object({
@@ -494,12 +496,12 @@ export const AuthConfigSchema = Type.Object({
     // rule) keyed by provider, so the four provider blocks (and any future one)
     // never inflate the flag count — the prior shape spent a leaf per top-level
     // google/github block. This bag REPLACES those two top-level blocks (−2, +1
-    // for the bag) and EXTENDS the accepted providers to apple + facebook (§6):
+    // for the bag) and EXTENDS the accepted providers to apple + facebook:
     //   • google/github/facebook → { clientIdRef, clientSecretRef, audRefs? }
     //   • apple                  → { servicesId, teamId, keyId, p8KeyRef }
-    // All *Ref fields are tenant_secrets POINTERS, never raw secrets (§6.5). The
+    // All *Ref fields are secret-store POINTERS, never raw secrets. The
     // worker reads config.providers?.{google,github,apple,facebook} (oauthCore.ts).
-    // The §6.4 runtime sign-in flow for apple/facebook is SHIPPED in oauthCore.ts
+    // The runtime sign-in flow for apple/facebook is SHIPPED in oauthCore.ts
     // (id_token/access_token verification + ES256 Apple client_secret minting);
     // methods.{apple,facebook} above are the enable toggles it gates on.
     providers: Type.Optional(Type.Object({
@@ -507,18 +509,18 @@ export const AuthConfigSchema = Type.Object({
         github: Type.Optional(OAuthRefsSchema),
         apple: Type.Optional(AppleRefsSchema),
         facebook: Type.Optional(OAuthRefsSchema),
-        // RB-2: the generic OIDC / SSO issuer (presence = enabled; see above)
+        // the generic OIDC / SSO issuer (presence = enabled; see above)
         oidc: Type.Optional(OidcProviderSchema),
     })),
     // session/password are OPTIONAL bags (= ONE leaf each per the cap rule) since
-    // the OTP/anonymous/orgClaims wave — the `{ default: {} }` keeps the inner
+    // the OTP/anonymous/orgClaims release — the `{ default: {} }` keeps the inner
     // defaults materializing on publish, so the worker still reads fully-populated
     // manifests; its `config.session?.ttlMinutes ?? 60` fallbacks cover sparse
     // hand-built manifests only.
     session: Type.Optional(Type.Object({
         ttlMinutes: Type.Integer({ default: 60, minimum: 5, maximum: 1440 }),
         refreshTtlDays: Type.Integer({ default: 30, minimum: 1, maximum: 365 }),
-        // A1 (auth wave 2026-09-10): concurrent-session cap per user with
+        // (2026-09-10) concurrent-session cap per user with
         // TAKE-OVER — a new sign-in revokes the OLDEST sessions past the cap
         // (revoked_reason 'device_cap', edge cache written) and reports them as
         // `took_over: [session_id…]`. Optional WITHOUT a default so existing
@@ -529,12 +531,12 @@ export const AuthConfigSchema = Type.Object({
         minLength: Type.Integer({ default: 8, minimum: 6, maximum: 128 }),
         requireMixed: Type.Boolean({ default: false }),
     }, { default: {} })),
-    // Deviation (journaled): emailVerification.tokenTtlHours was DROPPED —
+    // Note: emailVerification.tokenTtlHours was DROPPED —
     // consumer-less (grep-verified: only this schema + dist mentioned it; the
     // verify-email token flow it would bound was never built). Same precedent as
-    // the removed `redirects` block below. Its leaf funds the OTP wave.
+    // the removed `redirects` block below. Its leaf funds the OTP sign-in bag.
     emailVerification: Type.Object({ required: Type.Boolean({ default: false }) }, { default: {} }),
-    // P1-16 (2026-09-18): magicLink is now an OPTIONAL bag (= ONE leaf however
+    // (2026-09-18) magicLink is now an OPTIONAL bag (= ONE leaf however
     // many knobs it holds — the methods/session/password precedent) so the
     // request cooldown could land without spending a second leaf. It KEEPS
     // `default: {}`, so Value.Default still materializes
@@ -542,7 +544,7 @@ export const AuthConfigSchema = Type.Object({
     // folds byte-identically.
     magicLink: Type.Optional(Type.Object({
         tokenTtlMinutes: Type.Integer({ default: 15, minimum: 5, maximum: 60 }),
-        // P1-16: the per-(tenant, identifier) magic-link REQUEST cooldown — the
+        // the per-(tenant, identifier) magic-link REQUEST cooldown — the
         // `otp.resendCooldownSec` twin, same bounds so the two knobs read the
         // same. A second request for the same address inside the window is a 429
         // `magic_link_rate_limited` with a Retry-After header. Type.Optional with
@@ -551,19 +553,19 @@ export const AuthConfigSchema = Type.Object({
         // auth feature at read time. 0 disables the cooldown.
         resendCooldownSec: Type.Optional(Type.Integer({ minimum: 0, maximum: 600 })),
     }, { default: {} })),
-    // P1-5 identity continuity (2026-09-18) — OPT-IN registry adoption. When
+    // Identity continuity (2026-09-18) — OPT-IN registry adoption. When
     // true, a sign-in by a method that PROVES control of the address — magic
     // link, email OTP, or OAuth with a provider-verified address — reuses the id
     // of the one matching pre-registered end-user (POST /v1/users) that has no
     // account yet, instead of minting a fresh `user_<ulid>` and leaving the
     // tenant with two records for one person. Password SIGN-UP never adopts: it
-    // proves nothing about the address (auth.md §8.1 PROVEN_ADOPT_METHODS).
+    // proves nothing about the address (guide ch. 6, auth).
     // OFF by default, and Type.Optional with NO default: adoption means whoever
     // proves control of a pre-registered address becomes that record — a change
     // of security semantics for a tenant that bulk-imports contacts, whose
     // addresses vxil never verified.
     registryAdopt: Type.Optional(Type.Boolean()),
-    // Email OTP sign-in (roadmap Tier-0) + the knobs step-up re-auth shares.
+    // Email OTP sign-in + the knobs step-up re-auth shares.
     // OPTIONAL bag = 1 leaf; absent ⇒ disabled (the worker gates on
     // otp?.enabled === true).
     otp: Type.Optional(Type.Object({
@@ -571,7 +573,7 @@ export const AuthConfigSchema = Type.Object({
         codeTtlMinutes: Type.Integer({ default: 10, minimum: 1, maximum: 60 }),
         maxAttempts: Type.Integer({ default: 5, minimum: 3, maximum: 10 }),
         resendCooldownSec: Type.Integer({ default: 60, minimum: 0, maximum: 600 }),
-        // F4-29 (auth wave 2026-09-10): test recipients — an OTP / step-up / email-
+        // (2026-09-10) test recipients — an OTP / step-up / email-
         // claim request whose address matches an entry sends NO mail and returns
         // the code as `test_code` (audit auth.otp.test_issued). Entries: an exact
         // email, a `*@domain` glob, or a +E.164 number (accepted for the SMS
@@ -580,11 +582,11 @@ export const AuthConfigSchema = Type.Object({
         // only — never a real user's address.
         testRecipients: Type.Optional(Type.Array(Type.String({ minLength: 3, maxLength: 320 }), { maxItems: 20 })),
     })),
-    // Anonymous (guest) sign-in (roadmap Tier-0). OPTIONAL bag = 1 leaf.
+    // Anonymous (guest) sign-in. OPTIONAL bag = 1 leaf.
     anonymous: Type.Optional(Type.Object({
         enabled: Type.Boolean({ default: false }),
     })),
-    // Org claims embedded in session JWTs at mint/refresh (roadmap Tier-1C):
+    // Org claims embedded in session JWTs at mint/refresh:
     // when enabled, auth-v1 fetches the user's active-org membership from orgs
     // over the EDGE and embeds { org_id, role, perms[] } as the `org` claim.
     // Fail-open: an orgs outage mints WITHOUT claims (sign-in never breaks).
@@ -593,23 +595,22 @@ export const AuthConfigSchema = Type.Object({
     orgClaims: Type.Optional(Type.Object({
         enabled: Type.Boolean({ default: false }),
     })),
-    // Deviation (journaled): the doc's §4 `redirects` block was DROPPED entirely —
+    // Note: the earlier `redirects` block was DROPPED entirely —
     // it had zero consumers (grep-verified: no worker reads config.redirects) and
     // its leaf was spent on the methods.{apple,facebook} toggles the shipped
-    // §6.4 sign-in flow actually gates on. Re-adding it requires headroom or a
+    // social sign-in flow actually gates on. Re-adding it requires headroom or a
     // collapse elsewhere.
     //
-    // Account-security controls (auth wave 2026-09-10, P0-3; features/auth.md
-    // §4b). ONE optional bag = 1 leaf; NO `default: {}` so an absent bag stays
+    // Account-security controls (2026-09-10; guide ch. 6, auth). ONE optional bag = 1 leaf; NO `default: {}` so an absent bag stays
     // absent (existing manifests fold byte-identically) and every control is
     // opt-in:
     //   • lockout — present ⇒ per-(tenant, identifier) failure lockout on password
     //     sign-in + OTP verify (429 account_locked + Retry-After); a bounded
-    //     counter row in auth.lockouts (migration 0088) survives restarts.
+    //     stored counter survives restarts.
     //   • breachedPasswords — HIBP k-anonymity range check (first 5 SHA-1 hex
     //     chars leave the worker, never the password) at sign-up / reset-confirm;
     //     fail-OPEN on network error → 422 password_breached.
-    //   • captchaSecretRef — a tenant_secrets ref (feature 'auth') holding the
+    //   • captchaSecretRef — a secret-store ref (feature 'auth') holding the
     //     Turnstile secret; when set, sign-up / OTP request / magic-link request
     //     require `captcha_token` (403 captcha_failed otherwise).
     //   • allowedRedirectOrigins — when non-empty, EVERY caller-supplied
@@ -629,10 +630,10 @@ export const AuthConfigSchema = Type.Object({
         allowedRedirectOrigins: Type.Optional(Type.Array(Type.String({ minLength: 8, maxLength: 253, pattern: REDIRECT_ORIGIN_PATTERN }), { maxItems: 32 })),
     })),
 });
-// ── DECLARED API STATE (roadmap §4.11 P0-3, 2026-09-23) ──────────────────────
+// ── DECLARED API STATE (2026-09-23) ──────────────────────────────────────────
 // A rate-limit policy is a ROW in the feature's own KV store, written by
 // POST/PUT/DELETE /v1/rate-limits/policies. It used to be API state OUTSIDE
-// vxil.config (a journaled deviation: "one writer per datum, and the writer is
+// vxil.config (by the old rule "one writer per datum, and the writer is
 // the route"), which made a second environment non-reproducible — every tenant
 // ended up with an `ensure-rate-limit-policies.ts` + a nightly assert. The
 // rule is unchanged — one writer per datum — but the writer is now THE
@@ -670,7 +671,7 @@ export const RateLimitsConfigSchema = Type.Object({
 });
 export const FilesConfigSchema = Type.Object({
     enabled: Type.Boolean({ default: true }),
-    // (F8-54) `bucketRef` was DELETED: the object-storage bucket is a platform
+    // `bucketRef` was DELETED (2026-09-11): the object-storage bucket is a platform
     // binding on files-v1, never tenant-selectable, and no code ever read the
     // leaf — declaring it invited "point files at my own bucket", which vxil does
     // not offer. A persisted manifest that still carries it folds (Value.Clean).
@@ -678,8 +679,8 @@ export const FilesConfigSchema = Type.Object({
     downloadUrlTtl: Type.Integer({ default: 900, minimum: 60, maximum: 86400 }),
     quotas: Type.Object({
         // maximum caps are a defense-in-depth ceiling on tenant-editable storage —
-        // object storage is cheap but the SQL-database-resident metadata + abuse aren't (pricing re-audit
-        // 2026-07-10). 5 GiB/object, 1 TiB/tenant absolute; true PER-TIER clamps
+        // object storage is cheap but the database-resident metadata + abuse aren't
+        // (pricing review 2026-07-10). 5 GiB/object, 1 TiB/tenant absolute; true PER-TIER clamps
         // (Free/Dev 10 GB · Team 50 GB · Business 256 GB) are a follow-up needing the
         // tenant tier threaded to files-v1 (plan tiers).
         maxObjectBytes: Type.Integer({ default: 100 * 1024 * 1024, minimum: 1, maximum: 5 * 1024 * 1024 * 1024 }),
@@ -687,7 +688,7 @@ export const FilesConfigSchema = Type.Object({
         maxObjectCount: Type.Integer({ default: 100000, minimum: 1, maximum: 100_000_000 }),
     }, { default: {} }),
     allowedContentTypes: Type.Array(Type.String(), { default: ['*'], maxItems: 100 }),
-    // (F8-54) the `contentScan` bag ({enabled, quarantineOnFail}) was DELETED:
+    // (2026-09-11) the `contentScan` bag ({enabled, quarantineOnFail}) was DELETED:
     // there is no malware/content scanner in files-v1 (it was a "V1.5" placeholder
     // neither leaf was ever read), so the knob promised quarantine that never
     // happened. Re-declare it in the same change as a real scanner, not before.
@@ -695,7 +696,7 @@ export const FilesConfigSchema = Type.Object({
         enabled: Type.Boolean({ default: true }),
         maxTtl: Type.Integer({ default: 7 * 24 * 3600 }),
     }, { default: {} }),
-    // Wave-2 extensions (features/files.md §1.1 OCR + §1.2 TTL) — the merge of
+    // Wave-2 extensions (guide ch. 6, files: OCR + TTL) — the merge of
     // workers/files-v1/src/ext.ts FilesExtensionsConfigSchema promised by its
     // 'wiring phase' comment. Each is an OPTIONAL bag (= ONE leaf per the cap
     // rule); files-v1 already reads both defensively (FilesConfigWithExt), so
@@ -710,16 +711,20 @@ export const FilesConfigSchema = Type.Object({
     extractText: Type.Optional(Type.Object({
         enabled: Type.Boolean({ default: false }),
         provider: Type.Union([Type.Literal('gcv'), Type.Literal('textract'), Type.Literal('azure-di'), Type.Literal('mock')], { default: 'mock' }),
-        // provider key is BYO + envelope-encrypted in public.tenant_secrets — NOT a
-        // config flag. keyRef names the tenant_secrets row (like ai's keyRefs).
+        // provider key is BYO + encrypted in the tenant's secret store — NOT a
+        // config flag. keyRef names the stored secret (like ai's keyRefs).
         keyRef: Type.Optional(Type.String()),
         asyncOverJobs: Type.Boolean({ default: true }), // large/multi-page → jobs
         boundingBoxes: Type.Boolean({ default: false }),
     })),
+    // Public asset delivery (2026-10-03, guide ch. 6 files): publish
+    // an object to the cache-forever public host (POST /v1/files/{id}/publish).
+    // ONE optional bag: { enabled, corsOrigins, variants }. The published-bytes
+    // ceiling is a PLAN line (control-plane plans.ts), never a tenant knob.
+    publicAssets: Type.Optional(PublicAssetsConfigSchema),
 });
 // webhooks-out (wishlist feature): outbound event fan-out over the jobs delivery
-// engine. Subscriptions live in their own table (§1 contract — one writer
-// per datum); config is just the capability gate + a cap.
+// engine. Subscriptions live in their own store (one writer per datum); config is just the capability gate + a cap.
 export const DeclaredWebhookSubscriptionSchema = Type.Object({
     target_url: Type.String({ minLength: 9, maxLength: 2000 }),
     event_prefixes: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 100 }), { maxItems: 20 })),
@@ -728,14 +733,14 @@ export const WebhooksConfigSchema = Type.Object({
     enabled: Type.Boolean({ default: true }),
     maxSubscriptions: Type.Integer({ default: 20, minimum: 1, maximum: 200 }),
     maxSources: Type.Integer({ default: 20, minimum: 1, maximum: 200 }),
-    // FAILURE-ALERT DIGEST (P0-2). Outbound subscriptions are the real-time
+    // FAILURE-ALERT DIGEST. Outbound subscriptions are the real-time
     // channel; this is the "nobody is consuming them yet" fallback — a periodic
     // e-mail summary of the tenant's FAILURE-class audit events (the level:
     // 'failure' rows of the generated event catalog). Read by
     // workers/control-plane/src/alertDigest.ts on the minute cron.
     //
-    // RECIPIENTS ARE DELIBERATELY NOT CONFIGURABLE, and this deviation is
-    // journaled here the way RateLimitsConfigSchema journals its own: an
+    // RECIPIENTS ARE DELIBERATELY NOT CONFIGURABLE, and this decision is
+    // recorded here the way RateLimitsConfigSchema records its own: an
     // arbitrary `to` would turn vxil's own sending identity into a relay for
     // tenant-authored content and open a PII egress path out of the audit trail.
     // The digest goes to the OWNER-role dashboard accounts of the project (cap
@@ -745,7 +750,7 @@ export const WebhooksConfigSchema = Type.Object({
     //
     // An Optional object bag counts as ONE leaf (the countLeaves rule).
     //
-    // `digestMinutes: 0` is IMMEDIATE (roadmap §4.11 P0-4c, 2026-09-23): the
+    // `digestMinutes: 0` is IMMEDIATE (2026-09-23): the
     // pass runs every minute for the tenant and mails the `error`-level failure
     // rows that landed since its last mail — at most one mail per minute, still
     // to the owner accounts. 1–4 are clamped up to 5 by the reader.
@@ -754,11 +759,11 @@ export const WebhooksConfigSchema = Type.Object({
         minLevel: Type.Union([Type.Literal('warn'), Type.Literal('error')], { default: 'error' }),
         digestMinutes: Type.Integer({ default: 15, minimum: 0, maximum: 1440 }),
     })),
-    // DECLARED API STATE (roadmap §4.11 P0-3, 2026-09-23): the tenant's OUTBOUND
+    // DECLARED API STATE (2026-09-23): the tenant's OUTBOUND
     // subscriptions as config. Keyed by `target_url` — the only stable identity a
     // subscription has (there is no name column). A changed prefix set is an
     // in-place update — PATCH /v1/webhooks/subscriptions/:subId, same sub_id and
-    // cursor (2026-09-25). `vxil push` / `POST /v1/apply` converge public.webhook_subscriptions
+    // cursor (2026-09-25). `vxil push` / `POST /v1/apply` converge the live subscriptions
     // onto this list (handlers/apiState.ts); undeclared live rows are LEFT and
     // reported (deleted only under --allow-destructive). Rows on the platform's
     // signed function-delivery lanes (/v1/internal/fn/…) are NEVER declared here
@@ -775,16 +780,16 @@ export const CommentsConfigSchema = Type.Object({
     /** Author edits allowed this long after posting; 0 disables editing. */
     editWindowMinutes: Type.Integer({ default: 15, minimum: 0, maximum: 10_080 }),
 });
-// content feature (cms-feature-analysis.md §4.2): flags govern LIMITS, never the
+// content feature (guide ch. 4): flags govern LIMITS, never the
 // content model — the model itself is data (cms.collections / cms.fields via
-// the REST surface). versioning/localization/publicRead land later waves.
+// the REST surface). versioning/localization/publicRead land later.
 export const CmsConfigSchema = Type.Object({
     enabled: Type.Boolean({ default: true }),
     draftPublish: Type.Boolean({ default: true }),
-    // cms end-user default-deny fail-safe (path-to-100 §3.2, Feature B). When ON,
+    // cms end-user default-deny fail-safe (guide ch. 4). When ON,
     // a VERIFIED end-user key (owner-scope mode) is DENIED access to any
     // collection that declares no owner_field — `403 server_only` on read AND
-    // write (finding 29, 2026-09-20; reads used to be a 404) — instead of the
+    // write (2026-09-20; reads used to be a 404) — instead of the
     // default tenant-wide-shared behavior. Server-caller mode is a
     // byte-for-byte no-op. Default OFF preserves today's shared semantics
     // (owner.int.test.ts's shared-collection invariant). A collection that DOES
@@ -800,7 +805,7 @@ export const CmsConfigSchema = Type.Object({
         maxPageSize: Type.Integer({ default: 100, minimum: 1, maximum: 500 }),
         defaultPageSize: Type.Integer({ default: 25, minimum: 1, maximum: 500 }),
     }, { default: {} }),
-    // cms ENRICHMENT (cms.md §6.4): the read-time relation budget. The worker
+    // cms ENRICHMENT (guide ch. 4): the read-time relation budget. The worker
     // clamps via resolveRelationsConfig (enrich.ts) with the SAME defaults +
     // hard ceilings, so an out-of-range value can never widen the bound.
     relations: Type.Object({
@@ -832,7 +837,7 @@ export const CmsConfigSchema = Type.Object({
         message: Type.Optional(Type.String({ maxLength: 200 })),
         enabled: Type.Optional(Type.Boolean()),
     }))),
-    // Declarative relational read-models (cms-relational-depth §3 B2/B3/B5).
+    // Declarative relational read-models (guide ch. 4).
     // Each is a NAMED, closed-grammar aggregate/rank spec, optionally
     // materialized to a rollup collection on the EXISTING jobs cron (the
     // fn-cron:* reconciler idiom → cms-rollup:* schedules). Grammar is validated
@@ -841,7 +846,7 @@ export const CmsConfigSchema = Type.Object({
     readModels: Type.Optional(Type.Record(Type.String({ maxLength: 64 }), Type.Object({
         collection: Type.String({ maxLength: 64 }),
         kind: Type.Union([Type.Literal('aggregate'), Type.Literal('rank')]),
-        // the §3.1/§4.1 body minus limit — Type.Unknown so Value.Clean keeps it
+        // the aggregate/rank query body minus limit — Type.Unknown so Value.Clean keeps it
         // (the functions `signature` idiom); shape checked by the cross-field rule.
         spec: Type.Unknown(),
         materialize: Type.Optional(Type.Object({
@@ -865,13 +870,13 @@ export const CmsConfigSchema = Type.Object({
         enabled: Type.Optional(Type.Boolean()),
     }))),
 });
-// mcp feature (mcp.md §5): the aggregation surface's own knobs. Default-enabled —
+// mcp feature (guide ch. 10): the aggregation surface's own knobs. Default-enabled —
 // a tenant with no mcp config row still gets the aggregated tool list.
 export const McpConfigSchema = Type.Object({
     enabled: Type.Boolean({ default: true }),
     exposureLevel: Type.Union([Type.Literal('all'), Type.Literal('read-only'), Type.Literal('custom')], { default: 'all' }),
     allowToolList: Type.Optional(Type.Array(Type.String(), { maxItems: 200 })),
-    // (F8-54) the `scopedKey.perAgentKeys` leaf was DELETED: it was documented as
+    // (2026-09-11) the `scopedKey.perAgentKeys` leaf was DELETED: it was documented as
     // a "dashboard-UI hint only" that no dashboard ever read, and key minting is a
     // control-plane concern independent of MCP exposure — per-agent keys already
     // work for every tenant, gated by nothing here.
@@ -880,7 +885,7 @@ export const McpConfigSchema = Type.Object({
         serverName: Type.String({ default: 'Vxil' }),
         serverInstructions: Type.Optional(Type.String({ maxLength: 4000 })),
     }, { default: {} }),
-    // Tenant-authored CUSTOM tools (mcp.md §6.5): name → tenant-owned https
+    // Tenant-authored CUSTOM tools (guide ch. 10): name → tenant-owned https
     // endpoint. mcp-v1 lists each as `custom_<name>` and POSTs the tool
     // arguments to `url`, HMAC-signed with the per-tenant key from
     // GET /v1/mcp/signing-secret (X-Vxil-Mcp-Signature; the caller's vxil bearer
@@ -896,7 +901,7 @@ export const McpConfigSchema = Type.Object({
         inputSchema: Type.Optional(Type.Unknown()),
         timeoutMs: Type.Optional(Type.Integer({ minimum: 1000, maximum: 20_000 })),
     }))),
-    // Config-declared MCP PROMPTS (mcp.md §11 closure): name → template with
+    // Config-declared MCP PROMPTS (guide ch. 10): name → template with
     // {{placeholder}} interpolation. Served verbatim by mcp-v1 prompts/list +
     // prompts/get. ONE Type.Record leaf; placeholder ↔ arguments consistency is
     // a cross-field rule below.
@@ -926,7 +931,7 @@ export const OrgsConfigSchema = Type.Object({
     maxMembersPerOrg: Type.Integer({ default: 1000, minimum: 1, maximum: 100_000 }),
     invitationTtlHours: Type.Integer({ default: 168, minimum: 1, maximum: 720 }),
 });
-// activity-feed feature (features/activity-feed.md §3): a GetStream-class activity-
+// activity-feed feature (guide ch. 6, activity-feed): a GetStream-class activity-
 // streams engine + a Knock/Novu-class in-app notification FEED. Flags govern
 // the fan-out throttle, the follow/aggregation caps, and the cross-channel /
 // realtime gates — NEVER the verb vocabulary or the personalized ranker (the
@@ -943,8 +948,8 @@ export const ActivityFeedConfigSchema = Type.Object({
             Type.Literal('aggregated'),
             Type.Literal('notification'),
         ]),
-        aggregation: Type.Optional(Type.String()), // group-format rule (§7); required for aggregated/notification
-        ranking: Type.Optional(Type.String()), // 'chronological' | 'decay' (§8); flat-only; default chronological
+        aggregation: Type.Optional(Type.String()), // group-format rule; required for aggregated/notification
+        ranking: Type.Optional(Type.String()), // 'chronological' | 'decay'; flat-only; default chronological
     }), {
         default: {
             user: { type: 'flat' },
@@ -958,14 +963,14 @@ export const ActivityFeedConfigSchema = Type.Object({
     fanout: Type.Object({
         celebrityThreshold: Type.Integer({ default: 10_000, minimum: 0 }), // ≥ → pull (read-side); < → push (write-side)
         maxFanoutPerJob: Type.Integer({ default: 1000, minimum: 1, maximum: 10_000 }), // follower batch size per jobs task
-        maxConcurrentTasks: Type.Integer({ default: 20, minimum: 1, maximum: 1000 }), // per-tenant in-flight cap (LOCAL throttle §5)
+        maxConcurrentTasks: Type.Integer({ default: 20, minimum: 1, maximum: 1000 }), // per-tenant in-flight cap (local throttle)
         pendingCeiling: Type.Integer({ default: 50_000, minimum: 1 }), // pending-fan-out-depth back-pressure ceiling
     }, { default: {} }),
     follow: Type.Object({
         copyLimit: Type.Integer({ default: 100, minimum: 0, maximum: 1000 }), // backfill budget on follow
         maxFollowing: Type.Integer({ default: 10_000, minimum: 0 }), // per-feed following cap
     }, { default: {} }),
-    // (F8-54) the `aggregation.maxGroupActivities` leaf was DELETED: nothing kept
+    // (2026-09-11) the `aggregation.maxGroupActivities` leaf was DELETED: nothing kept
     // or returned a per-group activity LIST — an aggregated read returns the group
     // rollup (activity_count/actor_count/last_actor), so there was never an N to
     // bound and no code read the leaf. Re-declare it with a group-detail route.
@@ -973,16 +978,16 @@ export const ActivityFeedConfigSchema = Type.Object({
         enabled: Type.Boolean({ default: true }), // live new-activity + count push over the realtime ChannelDO
     }, { default: {} }),
     crossChannel: Type.Object({
-        enabled: Type.Boolean({ default: false }), // master gate for the notifications push/email trigger (§10)
+        enabled: Type.Boolean({ default: false }), // master gate for the notifications push/email trigger
         digestCadence: Type.Union([Type.Literal('off'), Type.Literal('hourly'), Type.Literal('daily')], { default: 'off' }), // digest roll-up window (feed owns the roll-up, rides notifications' live single-send)
     }, { default: {} }),
-    // (F8-54) the `rateLimit.addPerSec` leaf was DELETED: activity-feed-v1 has no
+    // (2026-09-11) the `rateLimit.addPerSec` leaf was DELETED: activity-feed-v1 has no
     // rate-limiter binding and never read it, so the declared per-tenant write
     // burst was enforced by nothing (the edge front-door limiter and the
     // per-tenant request meter are the real bounds). Re-declare it together with
     // the binding that enforces it.
 });
-// vector-search feature (features/vector-search.md §4). Re-declared here to match the
+// vector-search feature (guide ch. 6, vector-search). Re-declared here to match the
 // schema the worker EXPORTS from workers/vector-search-v1/src/config.ts — the
 // control plane validates writes against this shared copy (the same
 // one-definition / two-consumers note as the other features above; this package owns
@@ -991,7 +996,7 @@ export const ActivityFeedConfigSchema = Type.Object({
 // synthesis / relevance tuning (the tenant's moat). An OPTIONAL leaf = ONE flag.
 export const VectorSearchConfigSchema = Type.Object({
     enabled: Type.Boolean({ default: true }),
-    // 'auto' resolves to the default managed vector backend for the tier (#147).
+    // 'auto' resolves to the default managed vector backend for the tier.
     backend: Type.Union([Type.Literal('auto'), Type.Literal('lakebase'), Type.Literal('pgvector')], { default: 'auto' }),
     // 'byov'/'mock' need NO provider key (zero-config default); openai/cohere read a
     // BYO key from tenant secrets via apiKeyRef (encrypted at rest).
@@ -1025,7 +1030,7 @@ export const VectorSearchConfigSchema = Type.Object({
         provider: Type.Union([Type.Literal('mock'), Type.Literal('cohere'), Type.Literal('voyage')]),
         model: Type.Optional(Type.String({ maxLength: 128 })), // cohere 'rerank-v3.5' / voyage 'rerank-2'
         topN: Type.Optional(Type.Integer({ default: 50, minimum: 1, maximum: 200 })),
-        apiKeyRef: Type.Optional(Type.String({ maxLength: 128 })), // 'secret:<name>' under KEK_VECTOR_SEARCH
+        apiKeyRef: Type.Optional(Type.String({ maxLength: 128 })), // 'secret:<name>' in the tenant's secret store
     })),
     // Config-driven auto-embedding sync from cms collections: the control plane
     // reconciles one `vs-sync:` jobs schedule per entry on every config commit;
@@ -1042,12 +1047,12 @@ export const VectorSearchConfigSchema = Type.Object({
         cron: Type.Optional(Type.String({ pattern: '^\\S+ \\S+ \\S+ \\S+ \\S+$' })),
     }), { maxItems: 8 })),
 });
-// ai feature (features/ai.md §4). Re-declared to match workers/ai-v1/src/core.ts's
+// ai feature (guide ch. 6, ai). Re-declared to match workers/ai-v1/src/core.ts's
 // exported AiConfigSchema. vxil owns the call SCAFFOLDING (routing, streaming,
 // token accounting, caching, the reserve→settle budget); the tenant owns the
 // intelligence (prompt TEMPLATES are config-as-code, stored/rendered but never
 // authored). 'mock' is the deterministic default until a BYO key is provisioned;
-// the real providers route via tenant_secrets keyRefs.
+// the real providers route via secret-store keyRefs.
 export const AI_TEMPLATE_NAME_PATTERN = '^[a-zA-Z0-9_.\\-]+$';
 export const AI_MAX_DECLARED_TEMPLATES = 50;
 export const DeclaredAiTemplateSchema = Type.Object({
@@ -1063,7 +1068,7 @@ export const AiConfigSchema = Type.Object({
     // meta-provider (BYO key under providers.compat.openrouterKeyRef).
     defaultProvider: Type.Union([Type.Literal('mock'), Type.Literal('openai'), Type.Literal('anthropic'),
         Type.Literal('gemini'), Type.Literal('azure'), Type.Literal('openrouter')], { default: 'mock' }),
-    // BYO keyRefs → public.tenant_secrets (envelope-encrypted). The block is NOT
+    // BYO keyRefs → the tenant's encrypted secret store. The block is NOT
     // optional (the worker declares it plain), so its three optional refs each count
     // as a leaf. The nested blocks carry `default: {}` (this package's convention)
     // so Value.Default materializes them + recurses into the leaf defaults when a
@@ -1075,7 +1080,7 @@ export const AiConfigSchema = Type.Object({
         geminiKeyRef: Type.Optional(Type.String()),
         // The openai-compatible extension surface — ONE optional object = ONE config
         // leaf (countLeaves collapses optional objects; 15-leaf cap discipline).
-        // compat.openrouterKeyRef: BYO OpenRouter key (tenant_secrets ref, KEK_AI).
+        // compat.openrouterKeyRef: BYO OpenRouter key (a secret-store ref).
         // compat.openaiBaseUrl: point the openai adapter at ANY openai-compatible
         // host (DeepSeek, vLLM, an Azure-compatible proxy). Public-https validated
         // at config WRITE (publicHttpsUrlError below) AND at USE (@vxil/runtime
@@ -1095,7 +1100,7 @@ export const AiConfigSchema = Type.Object({
         tokensPerUserPerDay: Type.Integer({ default: 0, minimum: 0 }), // 0 = unlimited
         consumeCredits: Type.Boolean({ default: false }), // LIVE: reserve→settle against the payments credit ledger (a job-routed generation reserves pre-generation and 402s insufficient_credits)
     }, { default: {} }),
-    // `streaming` became an OPTIONAL bag (3 leaves → 1, the M21 `retry` trick)
+    // `streaming` became an OPTIONAL bag (3 leaves → 1, the `retry` trick)
     // on 2026-09-23 to fund the declared `templates[]` below. It KEEPS
     // `default: {}`, so Value.Default still materializes
     // streaming.{enabled,replayBufferFrames,flushMs} into every persisted
@@ -1104,12 +1109,11 @@ export const AiConfigSchema = Type.Object({
     // here is optional.
     streaming: Type.Optional(Type.Object({
         enabled: Type.Boolean({ default: true }),
-        replayBufferFrames: Type.Integer({ default: 256, minimum: 1 }), // §2a ring-buffer depth
-        flushMs: Type.Integer({ default: 50, minimum: 0 }), // §2a/#148 token→frame coalesce window
+        replayBufferFrames: Type.Integer({ default: 256, minimum: 1 }), // replay ring-buffer depth
+        flushMs: Type.Integer({ default: 50, minimum: 0 }), // token→frame coalesce window
     }, { default: {} })),
-    // DECLARED API STATE (roadmap §4.11 P0-3, 2026-09-23): the tenant's stored
-    // prompt templates as config. vxil STORES + versions, never authors (ai.md
-    // §0) — declaring them here changes WHO writes the row (the repository, via
+    // DECLARED API STATE (2026-09-23): the tenant's stored
+    // prompt templates as config. vxil STORES + versions, never authors — declaring them here changes WHO writes the row (the repository, via
     // `vxil push`), not what vxil does with it. Converged by CONTENT: the
     // control-plane hashes each declared entry (@vxil/runtime
     // aiTemplateContentSha256) against the `content_sha256` GET /v1/ai/templates
@@ -1118,11 +1122,11 @@ export const AiConfigSchema = Type.Object({
     // Item shape mirrors ai-v1 core.ts TemplateBody exactly (`template` is the
     // name). Stored templates the config does not declare are reported and left
     // in place — RETIRED (soft: hidden from list + render, history kept) only
-    // under --allow-destructive (cvskit F67, 2026-10-01). Bounded to 50 entries: the
+    // under --allow-destructive (2026-10-01). Bounded to 50 entries: the
     // manifest rides the 1 MiB config body cap. An Optional ARRAY is ONE leaf.
     templates: Type.Optional(Type.Array(DeclaredAiTemplateSchema, { maxItems: AI_MAX_DECLARED_TEMPLATES })),
 });
-// rag feature (features/rag.md §2). Re-declared to match workers/rag-v1/src/config.ts's
+// rag feature (guide ch. 6, rag). Re-declared to match workers/rag-v1/src/config.ts's
 // exported RagConfigSchema. rag owns the PIPELINE knobs only — retrieval budget,
 // context budget + strategy + tokenizer, the citation/stream gates — NEVER the
 // prompt, the synthesis, or relevance tuning (the tenant's `ai` template owns those).
@@ -1140,7 +1144,7 @@ export const RagConfigSchema = Type.Object({
         rerank: Type.Boolean({ default: false }),
     }, { default: {} }),
     // declarative per-metadata-field relevance boosts applied in rag AFTER
-    // retrieval, BEFORE minScore/budget/grounding (rag.md §2f). ONE Type.Record
+    // retrieval, BEFORE minScore/budget/grounding (guide ch. 6, rag). ONE Type.Record
     // leaf (the activity-feed feedGroups precedent).
     boosts: Type.Record(Type.String(), Type.Union([
         Type.Object({
@@ -1154,13 +1158,13 @@ export const RagConfigSchema = Type.Object({
         }),
     ]), { default: {} }),
     context: Type.Object({
-        // bounded context budget — enforced via the §2c tokenizer, BEFORE the ai call.
+        // bounded context budget — enforced via the tokenizer, BEFORE the ai call.
         maxTokens: Type.Integer({ default: 4000, minimum: 1, maximum: 1_000_000 }),
         strategy: Type.Union([Type.Literal('topk'), Type.Literal('mmr')], {
             default: 'topk',
         }),
         // 'provider' = the resolved ai provider's tokenizer; 'heuristic' = portable
-        // ~chars/4 with a safety margin (§2c, #149).
+        // ~chars/4 with a safety margin.
         tokenizer: Type.Union([Type.Literal('provider'), Type.Literal('heuristic')], {
             default: 'provider',
         }),
@@ -1170,7 +1174,7 @@ export const RagConfigSchema = Type.Object({
     citations: Type.Boolean({ default: true }),
     streaming: Type.Boolean({ default: true }),
 });
-// payments feature (features/payments.md §5). Re-declared to match the schema the
+// payments feature (guide ch. 6, payments). Re-declared to match the schema the
 // worker EXPORTS from workers/payments-v1/src/core.ts — the control plane
 // validates writes against this shared copy (one-definition / two-consumers,
 // like the other features). Two co-equal pillars: (A) provider payments (the
@@ -1186,9 +1190,9 @@ export const PaymentsConfigSchema = Type.Object({
     // events) so the ENTIRE ledger path is testable WITHOUT real provider keys.
     provider: Type.Union([Type.Literal('mock'), Type.Literal('stripe'), Type.Literal('paddle'),
         Type.Literal('revenuecat'), Type.Literal('paypal')], { default: 'mock' }),
-    // BYO-key credential blocks → public.tenant_secrets (envelope-encrypted).
+    // BYO-key credential blocks → the tenant's encrypted secret store.
     // Each OPTIONAL object counts as ONE leaf (the tenant's decision is
-    // "configure it or not", not each inner ref — features/auth.md §4).
+    // "configure it or not", not each inner ref — guide ch. 6, auth).
     stripe: Type.Optional(Type.Object({
         secretKeyRef: Type.String(),
         webhookSecretRef: Type.String(),
@@ -1203,25 +1207,24 @@ export const PaymentsConfigSchema = Type.Object({
         projectId: Type.String(),
         publicSdkKey: Type.String(),
         secretApiKeyRef: Type.String(),
-        // Per-tenant webhook secret ref (public.tenant_secrets). Inbound RevenueCat
+        // Per-tenant webhook secret ref (secret store). Inbound RevenueCat
         // webhooks are verified against THIS ref and nothing else: there is no
         // platform-wide PROVIDER_WEBHOOK_SECRET fallback for a real payment provider
-        // (that fallback WAS the multi-tenant RC webhook-forgery vector; it is now
-        // frozen out by tests/ci/src/provider-webhook-secret-fallback.test.ts, which
+        // (that fallback WAS a cross-tenant webhook-forgery vector; a CI gate now
         // permits `secrets.webhookSecret` only in makeProvider's mock/default arm).
         // Optional at the SCHEMA level only — leaving it unset does not disable
         // verification, it fails CLOSED: every delivery is 401 bad_signature with a
         // `sig_failed` row that can never be reprocessed. Mirrors stripe/paddle
         // webhookSecretRef.
         webhookSecretRef: Type.Optional(Type.String()),
-        // Environment integrity (money-path wave F1-4/D5). RevenueCat posts SANDBOX
+        // Environment integrity. RevenueCat posts SANDBOX
         // and PRODUCTION events to the SAME webhook with the same auth header, so a
         // sandbox purchase would otherwise fold into production entitlements. A
         // sandbox event is persisted as outcome 'rejected_environment' (200, never
         // folded) unless the tenant opts in here. Stripe/Paddle/PayPal separate
         // environments by signing secret / API base, so only RC carries this knob.
         acceptSandbox: Type.Boolean({ default: false }),
-        // (2026-10-01 §4.13 A18) Store-review purchases on a PRODUCTION tenant:
+        // (2026-10-01) Store-review purchases on a PRODUCTION tenant:
         // the reviewer accounts' RevenueCat `app_user_id`s (≤ 20). A SANDBOX event
         // whose subject (and, for a TRANSFER, every source user) is listed here
         // folds — recorded `environment: 'sandbox'` on the delivery, the
@@ -1242,9 +1245,9 @@ export const PaymentsConfigSchema = Type.Object({
     // Where a provider-hosted flow sends the payer back (Stripe billing-portal
     // return, PayPal approval return/cancel) — the TENANT's own app URL,
     // https-only. Absent ⇒ the worker's WEB_BASE_URL env (vxil's site), never a
-    // hardcoded host (audit 2026-07-10: the old fallback pointed at a dead apex).
+    // hardcoded host (2026-07-10: the old fallback pointed at a dead apex).
     returnUrl: Type.Optional(Type.String({ pattern: '^https://', maxLength: 512 })),
-    // NB (F8-54, 2026-09-11): the former `prices.catalogRef` leaf was DELETED —
+    // NB (2026-09-11): the former `prices.catalogRef` leaf was DELETED —
     // it named nothing (prices resolve from ledger.priceMap; no code path ever
     // read it). A persisted manifest that still carries `prices` folds:
     // validateFeatureConfig's Value.Clean strips the stray key.
@@ -1259,11 +1262,11 @@ export const PaymentsConfigSchema = Type.Object({
         // product_id → what the purchase GRANTS. ONE Type.Record leaf (the rag
         // `boosts` Record-of-Union precedent) with two rule shapes:
         //   { creditType, amount, period }  a credit grant (the original rule)
-        //   { tier, durationDays }          (2026-09-25 F35+) a TIME-BOXED
+        //   { tier, durationDays }          (2026-09-25) a TIME-BOXED
         //     ENTITLEMENT: the buyer gets `tier` (a tierMap key — cross-checked
         //     below) for `durationDays`, as a charge-linked manual-style row that
         //     STACKS behind the user's live same-tier manual rows that have an end
-        //     (earlier passes AND comp grants since 2026-09-25 F38 — never a row
+        //     (earlier passes AND comp grants since 2026-09-25 — never a row
         //     linked to the same charge, an open-ended grant or a provider
         //     subscription) and is ENDED by that charge's full refund / chargeback.
         //     No defaults in either shape, so an existing manifest is
@@ -1271,7 +1274,7 @@ export const PaymentsConfigSchema = Type.Object({
         productMap: Type.Record(Type.String(), Type.Union([
             Type.Object({
                 creditType: Type.String({ minLength: 1 }),
-                amount: Type.Integer({ minimum: 1 }), // #128: a grant only ADDS
+                amount: Type.Integer({ minimum: 1 }), // a grant only ADDS
                 period: Type.Union([Type.Literal('once'), Type.Literal('monthly'),
                     Type.Literal('annual')]),
             }),
@@ -1282,13 +1285,13 @@ export const PaymentsConfigSchema = Type.Object({
         ])),
         tierMap: Type.Record(Type.String(), Type.Object({
             entitlements: Type.Array(Type.String()),
-            quotas: Type.Record(Type.String(), Type.Integer({ minimum: 0 })), // #128: no negative quota
-            rank: Type.Optional(Type.Integer({ minimum: 0 })), // precedence for the multi-sub fold (#125)
+            quotas: Type.Record(Type.String(), Type.Integer({ minimum: 0 })), // no negative quota
+            rank: Type.Optional(Type.Integer({ minimum: 0 })), // precedence for the multi-sub fold
             grants: Type.Optional(Type.Array(Type.Object({
                 creditType: Type.String({ minLength: 1 }),
-                amount: Type.Integer({ minimum: 1 }), // #128
+                amount: Type.Integer({ minimum: 1 }), // a grant only ADDS
                 period: Type.String(),
-                // (2026-10-01 §4.13 W9) 'add' (the reader's default, today's
+                // (2026-10-01) 'add' (the reader's default, today's
                 // behaviour) ADDS `amount` each period; 'reset' makes the period's
                 // grant REPLACE what is left: the unspent available balance of
                 // `creditType` is written off as one `expire` ledger row and `amount`
@@ -1304,7 +1307,7 @@ export const PaymentsConfigSchema = Type.Object({
         // fold (refoldEntitlements WHERE tier IS NOT NULL) reflects the subscription.
         priceMap: Type.Optional(Type.Record(Type.String(), Type.String())),
         autoRefundOnJobFailure: Type.Boolean({ default: true }), // consume(jobId) reverses on DLQ/timeout
-        // Grace window (money-path wave F1-7): a `past_due` subscription stays
+        // Grace window: a `past_due` subscription stays
         // entitled for this many days AFTER its current_period_end (the dunning
         // window the provider is retrying inside). 0 = today's behaviour (a past_due
         // row is never entitled). ONE predicate in the fold — NOT a dunning ladder:
@@ -1312,8 +1315,7 @@ export const PaymentsConfigSchema = Type.Object({
         grace: Type.Optional(Type.Object({
             pastDueDays: Type.Integer({ default: 0, minimum: 0, maximum: 90 }),
         })),
-        // Opt-in period-end enforcement (money-path operations wave, decision D2
-        // option a). ABSENT (the default) = today's behaviour: a subscription whose
+        // Opt-in period-end enforcement. ABSENT (the default) = today's behaviour: a subscription whose
         // current_period_end passed with no provider event stays entitled forever
         // (the provider is the only clock). PRESENT = the nightly reconcile sweep
         // flips an `active`/`trialing` row whose current_period_end + slackHours
@@ -1348,28 +1350,28 @@ export const PaymentsConfigSchema = Type.Object({
         // (`config.ledger?.unmappedProduct ?? 'error'`), which is the one definition.
         unmappedProduct: Type.Optional(Type.Union([Type.Literal('error'), Type.Literal('ignore')])),
     })),
-    // NB (money-path wave F3-19): the former `webhooks.forwardToTenantUrl` leaf
+    // NB: the former `webhooks.forwardToTenantUrl` leaf
     // was DELETED — it had zero readers (never forwarded anything). Outbound
-    // delivery of payments state changes rides the audit_event → webhooks-out
-    // spine: subscribe to the `payments.` event prefix (payments.md §7b).
+    // delivery of payments state changes rides the audit stream → outbound
+    // webhooks: subscribe to the `payments.` event prefix (guide ch. 6, payments).
 });
-// functions feature (vxil-functions-design §4.c). Tenant-deployed backend edge
+// functions feature (guide ch. 8). Tenant-deployed backend edge
 // functions on the managed serverless runtime. The FUNCTION owns its identity (bundle via
 // scriptRef, scopes, secrets, egress, limits, runtime) + a SET of trigger
 // bindings; every other surface (e.g. cms.hooks) REFERENCES a function BY NAME and
 // never re-embeds deploy config. The per-function bag is ONE Type.Record leaf
 // (cms.hooks / payments.ledger precedent), so any number of deployed functions
-// never grows the flag cap. This is the §7.3 crossing — paid, tier-walled,
+// never grows the flag cap. Tenant code on the platform — paid, tier-walled,
 // opt-in (enabled defaults to false), egress-guarded.
 export const FunctionsConfigSchema = Type.Object({
     enabled: Type.Boolean({ default: false }),
-    // (F8-54) `runtime` ('isolate' | 'container') was DELETED: the container lane
-    // is design-only, nothing read the leaf, and accepting 'container' silently
+    // (2026-09-11) `runtime` ('isolate' | 'container') was DELETED: the container lane
+    // is not built, nothing read the leaf, and accepting 'container' silently
     // ran the isolate anyway. It comes back with the lane, not before.
     defaultLimits: Type.Object({
         // cpuMs is the ONLY per-dispatch limit the managed runtime accepts and the
         // only one anything reads (functions-v1 meter.ts + the dispatch cap).
-        // (F8-54) `timeoutMs` and `memoryMb` were DELETED: memory is fixed by the
+        // (2026-09-11) `timeoutMs` and `memoryMb` were DELETED: memory is fixed by the
         // runtime and not tenant-selectable, and no wall-clock abort was ever
         // applied — a declared 10s default that nothing enforced.
         cpuMs: Type.Integer({ default: 50, minimum: 5, maximum: 300_000 }),
@@ -1410,7 +1412,7 @@ export const FunctionsConfigSchema = Type.Object({
             source: Type.Optional(Type.String()), // webhook/queue: source/queue id
             collection: Type.Optional(Type.String()), // cmsHook: the CMS collection slug
             event: Type.Optional(Type.String()), // cmsHook: beforeCreate|beforeUpdate|beforeWrite · authHook: 'user.created'
-            // F33 (2026-09-25): the per-binding opt-in to re-delivery on
+            // (2026-09-25) the per-binding opt-in to re-delivery on
             // queue / webhook / cmsHook / authHook (the cross-field rule
             // rejects it on http / cron). Absent = the ACK-200 default. The
             // receiver answers a failed attempt as an enveloped 503 (ladder)
@@ -1434,7 +1436,7 @@ export const FunctionsConfigSchema = Type.Object({
         // the settings it was deployed and tested with, not today's. Absent =
         // the legacy settings (@vxil/types FUNCTIONS_RUNTIME_LEGACY). Unbounded
         // strings on purpose (the deploy writes them from the one constant).
-        // cpuMs (F2, 2026-10-01): the per-invoke CPU limit the script was
+        // cpuMs (2026-10-01): the per-invoke CPU limit the script was
         // uploaded with (limits.cpu_ms = min(declared limits.cpuMs, the tier's
         // cpuMsPerInvoke, FN_MAX_CPU_MS)) — server-set; the nightly plan pass
         // rewrites it after a tier change. Absent = the platform default.
@@ -1473,10 +1475,9 @@ export const FunctionsConfigSchema = Type.Object({
         //               egress guard as an outbound parameter. NOT an invocation
         //               budget: the INVOCATION is bounded by the platform's own
         //               FN_MAX_INVOKE_MS deadline (default >= 5 min), which a
-        //               bigger per-fetch budget widens with you (audit FN-3).
-        // (F8-54's standing "strip the twins" note is DISCHARGED here: `memoryMb`
-        // is deleted — memory is fixed by the managed runtime and is not a
-        // per-dispatch option; the WfP dispatch bag takes { cpuMs, subRequests }.
+        //               bigger per-fetch budget widens with you.
+        // (`memoryMb` is deleted — memory is fixed by the managed runtime and is
+        // not a per-dispatch option; a dispatch takes { cpuMs, subRequests }.
         // Value.Clean strips it from an old config, so such a config still loads
         // and `vxil plan --explain` marks the key DROPPED.)
         limits: Type.Optional(Type.Object({
@@ -1484,7 +1485,7 @@ export const FunctionsConfigSchema = Type.Object({
             timeoutMs: Type.Optional(Type.Integer()),
         })),
         enabled: Type.Optional(Type.Boolean()),
-        // Level-1 typed I/O (cli-sdk design §4.5): the declared input/output
+        // Level-1 typed I/O (guide ch. 8): the declared input/output
         // contract, persisted by the deploy body so ONLINE `vxil gen` emits the
         // same typed fn client as --offline. Opaque JSON-schema-ish payloads —
         // the CLI's lowerSig lowers them; the platform never interprets them.
@@ -1558,14 +1559,14 @@ export const CopilotConfigSchema = Type.Object({
             guestToolAllow: Type.Optional(Type.Array(Type.String({ maxLength: 64 }), { maxItems: 16, default: [] })),
         })),
     }), { default: {} }),
-    // (F8-54) the `escalation` bag ({enabled, handler, notifyTemplate}) was
+    // (2026-09-11) the `escalation` bag ({enabled, handler, notifyTemplate}) was
     // DELETED: the human hand-off it declared was never built — copilot-v1 read
     // none of the three leaves, so a tenant who turned it on got silence. The
     // shipped hand-off path is a tenant function on the conversation events.
     // ── limits: DELEGATE token/credit accounting to ai-v1 ─────────────────────
     limits: Type.Object({
         consumeCredits: Type.Boolean({ default: false }),
-        // (F8-54) `tokensPerUserPerDay` was DELETED here: token accounting is
+        // (2026-09-11) `tokensPerUserPerDay` was DELETED here: token accounting is
         // delegated to ai-v1 (this bag's own doctrine) and only `ai`'s
         // limits.tokensPerUserPerDay is enforced — the copilot twin read nothing.
     }, { default: {} }),
@@ -1599,11 +1600,11 @@ export const FEATURE_SCHEMAS = {
     copilot: CopilotConfigSchema,
 };
 export const CONFIG_FLAG_CAP = 15;
-/** Counts leaf flags in a TypeBox object schema (architecture §6).
- * Per features/auth.md §4: an OPTIONAL object (e.g. a provider credential
+/** Counts leaf flags in a TypeBox object schema.
+ * Per guide ch. 6, auth: an OPTIONAL object (e.g. a provider credential
  * block) counts as ONE flag — the tenant's decision is "configure it or
  * not", not each inner ref. */
-/** The auth lifecycle events an `authHook` binding may name (F4-30) — the
+/** The auth lifecycle events an `authHook` binding may name — the
  * closed union `packages/config` types as AuthHookEvent; the control-plane
  * reconciler maps each to its `auth.<event>` audit-event prefix. */
 export const AUTH_HOOK_EVENTS = ['user.created', 'session.created', 'session.revoked', 'signin.failure'];
@@ -1614,7 +1615,7 @@ export const AUTH_HOOK_EVENTS = ['user.created', 'session.created', 'session.rev
  * else is refused at config write (E-CMSHOOK, 2026-10-01): an unknown name used
  * to fall back to beforeWrite at delivery, so a typo like 'afterCreate' or
  * 'beforeDelete' silently subscribed the function to creates AND updates.
- * tests/ci/src/fn-binding-contracts.test.ts pins every copy to this list. */
+ * A CI gate pins every copy to this list. */
 export const CMS_HOOK_EVENTS = ['beforeCreate', 'beforeUpdate', 'beforeWrite'];
 /** The ONE refusal text for an unknown cmsHook binding event (the config
  * validator and the deploy route's early 422 both use it). */
@@ -1625,7 +1626,7 @@ export function cmsHookEventError(event) {
         return null;
     return `a 'cmsHook' binding's event must be one of ${CMS_HOOK_EVENTS.join(' | ')} (or omitted = beforeWrite), not ${JSON.stringify(event)}`;
 }
-/** F4-29 test-recipient entry grammar (shared by the validator and auth-v1's
+/** The OTP test-recipient entry grammar (shared by the validator and auth-v1's
  * matcher): an exact email, a `*@domain` glob, or a +E.164 phone number. */
 export const TEST_RECIPIENT_EMAIL_RE = /^[^\s@*]+@[^\s@]+\.[^\s@]+$/;
 export const TEST_RECIPIENT_GLOB_RE = /^\*@[^\s@*]+\.[^\s@*]+$/;
@@ -1678,7 +1679,7 @@ export function setKnownMcpTools(names) {
     knownMcpTools = new Set(names);
 }
 // ── mcp custom-tool / prompt caps + the pure public-https check ──────────────
-// (mcp.md §6.5) Caps are deliberately tighter than the 200-tool listing cap:
+// (guide ch. 10) Caps are deliberately tighter than the 200-tool listing cap:
 // each custom tool is a platform-signed egress target, so the bag stays small.
 export const MCP_MAX_CUSTOM_TOOLS = 32;
 export const MCP_MAX_PROMPTS = 32;
@@ -1734,7 +1735,7 @@ function publicHttpsUrlError(url) {
  *  stays ALLOWED (fn→fn composition). Source of truth for both the config-write
  *  validation below and the control-plane deploy clamp. */
 export const DENY_FUNCTION_SCOPES = new Set(['admin', '*', 'features:write', 'functions:write', 'secrets:write']);
-// ── declared API state — config-write validators (roadmap §4.11 P0-3) ────────
+// ── declared API state — config-write validators ────────────────────────────
 /** `{var}` names of a rate-limit key template (rate-limits-v1 core.ts
  *  templateVars parity). */
 export function rlTemplateVars(template) {
@@ -1819,6 +1820,13 @@ export function validateDeclaredAiTemplates(templates) {
     });
     return errs;
 }
+function badVariantPresetNames(raw) {
+    const variants = raw?.publicAssets?.variants;
+    if (!variants || typeof variants !== 'object' || Array.isArray(variants))
+        return [];
+    const re = new RegExp(VARIANT_PRESET_NAME_PATTERN);
+    return Object.keys(variants).filter((k) => !re.test(k));
+}
 export function validateFeatureConfig(feature, raw) {
     const schema = FEATURE_SCHEMAS[feature];
     if (!schema) {
@@ -1827,13 +1835,25 @@ export function validateFeatureConfig(feature, raw) {
     if (countLeaves(schema) > CONFIG_FLAG_CAP) {
         return { ok: false, errors: [`schema for '${feature}' exceeds the ${CONFIG_FLAG_CAP}-flag cap`] };
     }
+    // files.publicAssets.variants is a pattern-keyed record: Value.Clean below
+    // would silently DROP a preset whose name is not URL-safe, and the tenant
+    // would wonder why `/v/My Thumb` 404s. Refuse it by name instead.
+    if (feature === 'files') {
+        const bad = badVariantPresetNames(raw);
+        if (bad.length > 0) {
+            return {
+                ok: false,
+                errors: bad.map((n) => `/publicAssets/variants/${n}: a preset name is lower-case letters, numbers, '-' or '_' (at most 32 characters, starting with a letter or number)`),
+            };
+        }
+    }
     // Apply defaults to a clone, then STRIP any property the schema does not
-    // declare, then check. Value.Clean makes the validator TOTAL (audit #112):
+    // declare, then check. Value.Clean makes the validator TOTAL:
     // the schemas are open Type.Object()s, so without it Value.Check passes on —
     // and putConfig would persist — arbitrary unknown keys. Clean runs AFTER
     // Default so materialized nested defaults survive but stray top-level/nested
     // keys are dropped. This also removes the CLI dry-run idempotency drift
-    // (audit #118): plan/push diff the same cleaned manifest the server stores.
+    // too: plan/push diff the same cleaned manifest the server stores.
     const withDefaults = Value.Clean(schema, Value.Default(schema, Value.Clone(raw)));
     if (!Value.Check(schema, withDefaults)) {
         const errors = [...Value.Errors(schema, withDefaults)].map((e) => `${e.path || '/'}: ${e.message}`);
@@ -1865,7 +1885,7 @@ export function validateFeatureConfig(feature, raw) {
     }
     // Cross-field rule: a REAL payments provider needs its credential block; the
     // 'mock' provider (the deterministic default) stays zero-config so the whole
-    // ledger path is testable without real keys (features/payments.md §0/§6).
+    // ledger path is testable without real keys (guide ch. 6, payments).
     if (feature === 'payments') {
         const v = withDefaults;
         const needsBlock = {
@@ -1880,7 +1900,7 @@ export function validateFeatureConfig(feature, raw) {
         }
         // A reserved (vxil-COGS) credit_type must NEVER appear in a ledger grant map:
         // the webhook/subscription reducers would otherwise credit `fn_cpu_ms` to a
-        // user, running vxil-billed functions for free (audit F2). Rejected at write
+        // user, running vxil-billed functions for free. Rejected at write
         // time so the tenant gets a clear `vxil push` error, not a silent runtime skip.
         const ledgerErrs = [];
         const tierKeysForProducts = new Set(Object.keys(v.ledger?.tierMap ?? {}));
@@ -1888,7 +1908,7 @@ export function validateFeatureConfig(feature, raw) {
             if (rule.creditType && isReservedCreditType(rule.creditType)) {
                 ledgerErrs.push(`/ledger/productMap/${productId}/creditType: '${rule.creditType}' is a reserved vxil-COGS credit type and cannot be granted via config`);
             }
-            // (2026-09-25 F35+) an entitlement rule must name a declared tier — the
+            // (2026-09-25) an entitlement rule must name a declared tier — the
             // write-time mirror of the runtime's unknown-tier refusal (a purchase for
             // a tier nobody declared would land the delivery `error`).
             if (rule.tier !== undefined && !tierKeysForProducts.has(rule.tier)) {
@@ -1933,7 +1953,7 @@ export function validateFeatureConfig(feature, raw) {
                 ledgerErrs.push(`/ledger/productMap/${productId}/creditType: '${rule.creditType}' is reset each period by ${by} (mode 'reset' writes off purchased credits of that type) — sell packs on their own credit type and spend with credit_types`);
             }
         }
-        // Money-path wave F1-3 (D3): an UNMAPPED price silently revoked a paying
+        // An UNMAPPED price silently revoked a paying
         // customer (priceMap miss → tier NULL → refold excluded the row). The
         // reducer now stamps such an event outcome 'error' (reprocessable), and
         // this lint catches the config half at `vxil push` time: every priceMap
@@ -1981,7 +2001,7 @@ export function validateFeatureConfig(feature, raw) {
         if (rmErrors.length)
             return { ok: false, errors: rmErrors.slice(0, 10) };
     }
-    // Cross-field rules: mcp custom tools + prompts (mcp.md §6.5/§11). The URL
+    // Cross-field rules: mcp custom tools + prompts (guide ch. 10). The URL
     // check here is a PURE mirror of @vxil/runtime assertPublicHttpsUrl (this
     // package is typebox-only) — the authoritative runtime guard re-runs in
     // mcp-v1 at call time; this gate rejects obviously-internal targets BEFORE
@@ -2046,7 +2066,7 @@ export function validateFeatureConfig(feature, raw) {
         if (tplErrs.length)
             return { ok: false, errors: tplErrs.slice(0, 10) };
     }
-    // Cross-field rules: declared API state (roadmap §4.11 P0-3). Each list is
+    // Cross-field rules: declared API state. Each list is
     // converged by NAME/URL, so a duplicate key is ambiguous and refused at push;
     // the per-item rules mirror the feature route's own validation so a declared
     // entry can never be one the converge would 422 on.
@@ -2062,7 +2082,7 @@ export function validateFeatureConfig(feature, raw) {
         if (errs.length)
             return { ok: false, errors: errs.slice(0, 10) };
     }
-    // Cross-field rule: auth otp.testRecipients (F4-29) — every entry must be an
+    // Cross-field rule: auth otp.testRecipients — every entry must be an
     // email, an `*@domain` glob, or a +E.164 number; anything else would never
     // match and silently do nothing.
     if (feature === 'auth') {
@@ -2107,7 +2127,7 @@ export function validateFeatureConfig(feature, raw) {
                 if (b.overlap !== undefined && b.kind !== 'cron') {
                     errs.push(`/functions/${name}/bindings/${i}: 'overlap' applies to cron bindings only (not '${b.kind}')`);
                 }
-                // F33: retry is an opt-in for the platform-delivered event lanes only —
+                // retry is an opt-in for the platform-delivered event lanes only —
                 // an http invoke returns its real status to its caller, and a cron
                 // tick's retry would overlap the next tick.
                 if (b.retry !== undefined && !FN_RETRY_BINDING_KINDS.has(b.kind)) {
@@ -2121,7 +2141,7 @@ export function validateFeatureConfig(feature, raw) {
                 const cmsEventErr = b.kind === 'cmsHook' ? cmsHookEventError(b.event) : null;
                 if (cmsEventErr)
                     errs.push(`/functions/${name}/bindings/${i}: ${cmsEventErr}`);
-                // authHook: a CLOSED event union (F4-30) — reject typos at write time
+                // authHook: a CLOSED event union — reject typos at write time
                 // so a binding never silently subscribes to nothing.
                 if (b.kind === 'authHook' && b.event !== undefined && !AUTH_HOOK_EVENTS.includes(b.event)) {
                     errs.push(`/functions/${name}/bindings/${i}: an 'authHook' binding's event must be one of ${AUTH_HOOK_EVENTS.join(' | ')} (or omitted = user.created)`);