@vxil/feature-configs 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -1,18 +1,23 @@
 import { type Static, type TSchema } from '@sinclair/typebox';
 export * from './hooks.js';
 export * from './readmodels.js';
+export declare const RESERVED_CREDIT_TYPES: ReadonlySet<string>;
+/** True when a credit_type is a vxil-COGS reserved type (grant/consume/config
+ *  of which is restricted to internal platform machinery). */
+export declare function isReservedCreditType(creditType: string): boolean;
 export declare const NotificationsConfigSchema: import("@sinclair/typebox").TObject<{
     enabled: import("@sinclair/typebox").TBoolean;
     fromEmail: import("@sinclair/typebox").TString;
     fromName: import("@sinclair/typebox").TString;
     replyTo: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     resendApiKeyRef: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    webhookSecretRef: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     provider: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"resend">, import("@sinclair/typebox").TLiteral<"mock">]>;
     defaultLocale: import("@sinclair/typebox").TString;
-    retry: import("@sinclair/typebox").TObject<{
+    retry: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         maxAttempts: import("@sinclair/typebox").TInteger;
         backoff: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"exponential">, import("@sinclair/typebox").TLiteral<"linear">]>;
-    }>;
+    }>>;
     suppression: import("@sinclair/typebox").TObject<{
         softBounceThreshold: import("@sinclair/typebox").TInteger;
     }>;
@@ -25,8 +30,31 @@ export declare const NotificationsConfigSchema: import("@sinclair/typebox").TObj
     }>;
     /** in-app inbox channel (send with channel: 'inbox' | 'both') */
     inboxEnabled: import("@sinclair/typebox").TBoolean;
+    /** §11b.5 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
+     * worker-local extension, so campaigns 403'd via the real config path). */
+    broadcast: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        enabled: import("@sinclair/typebox").TBoolean;
+        /** tenant-default per-recipient quiet window (defer-not-drop); a
+         * per-campaign quiet_hours wins over it. Mirrors the campaigns-row shape
+         * (workers/notifications-v1 CampaignBody.quiet_hours). start/end are
+         * pattern-pinned to what the worker's parseHhMm actually parses — a
+         * looser string ('10pm') would validate but FAIL OPEN at runtime
+         * (quiet window silently ignored). */
+        defaultQuietHours: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+            tz: import("@sinclair/typebox").TString;
+            start: import("@sinclair/typebox").TString;
+            end: import("@sinclair/typebox").TString;
+        }>>;
+        /** default rolling per-user-per-day campaign-send cap across campaigns */
+        freqCapPerUserPerDay: import("@sinclair/typebox").TInteger;
+    }>>;
 }>;
 export type NotificationsConfig = Static<typeof NotificationsConfigSchema>;
+/** The §11b.5 broadcast bag as persisted (present ⇒ leaf defaults applied). */
+export type BroadcastConfig = NonNullable<NotificationsConfig['broadcast']>;
 export declare const JobsConfigSchema: import("@sinclair/typebox").TObject<{
     enabled: import("@sinclair/typebox").TBoolean;
     retry: import("@sinclair/typebox").TObject<{
@@ -585,3 +613,19 @@ export declare const MCP_MAX_PROMPTS = 32;
  *  validation below and the control-plane deploy clamp. */
 export declare const DENY_FUNCTION_SCOPES: Set<string>;
 export declare function validateFeatureConfig(feature: string, raw: unknown): ConfigValidation;
+export declare const FEATURE_KEYS: readonly ["notifications", "jobs", "auth", "rate-limits", "files", "webhooks", "comments", "cms", "mcp", "realtime", "presence", "orgs", "activity-feed", "vector-search", "ai", "rag", "payments", "functions", "copilot"];
+export type FeatureKey = (typeof FEATURE_KEYS)[number];
+/** The hand-authored "when to use" intent a machine schema cannot convey.
+ *  REQUIRED for every feature (Record key-closure): a feature added to
+ *  FEATURE_KEYS without a hint is a compile error naming the missing key. */
+export interface PlannerHint {
+    /** One or two sentences: when an app needs this feature. */
+    whenToUse: string;
+    /** Soft priors — words/needs that suggest the feature (NOT a matcher). */
+    signals: string[];
+    /** When NOT to pick it (disambiguation vs neighbors). */
+    notFor: string;
+    /** Features that must be enabled alongside (runtime substrate deps). */
+    dependsOn: FeatureKey[];
+}
+export declare const FEATURE_HINTS: Record<FeatureKey, PlannerHint>;

package/dist/index.js

@@ -18,6 +18,21 @@ export * from './readmodels.js';
 if (!FormatRegistry.Has('email')) {
     FormatRegistry.Set('email', (v) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v));
 }
+// ── RESERVED (vxil-COGS) CREDIT TYPES — single source of truth (audit F2) ─────
+// `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
+// tenant that self-grants `fn_cpu_ms` (directly, or by routing a product/tier
+// through the webhook/subscription grant reducers) runs vxil-billed function CPU
+// for free. Defined HERE (the typebox-only shared package both the control-plane
+// 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']);
+/** True when a credit_type is a vxil-COGS reserved type (grant/consume/config
+ *  of which is restricted to internal platform machinery). */
+export function isReservedCreditType(creditType) {
+    return RESERVED_CREDIT_TYPES.has(creditType);
+}
 export const NotificationsConfigSchema = Type.Object({
     enabled: Type.Boolean({ default: true }),
     fromEmail: Type.String({ format: 'email' }),
@@ -27,19 +42,32 @@ 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).
+    // 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).
+    webhookSecretRef: Type.Optional(Type.String()),
     // 'mock' exists for staging/e2e (deterministic provider); 'resend' is MVP.
     provider: Type.Union([Type.Literal('resend'), Type.Literal('mock')], {
         default: 'resend',
     }),
     defaultLocale: Type.String({ default: 'en-US' }),
     // nested objects carry `default: {}` so Value.Default can materialize them
-    // and then recurse into the leaf defaults
-    retry: Type.Object({
+    // 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).
+    // 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
+    // via retryOf()'s fallback).
+    retry: Type.Optional(Type.Object({
         maxAttempts: Type.Integer({ default: 5, minimum: 1, maximum: 20 }),
         backoff: Type.Union([Type.Literal('exponential'), Type.Literal('linear')], {
             default: 'exponential',
         }),
-    }, { default: {} }),
+    }, { default: {} })),
     suppression: Type.Object({ softBounceThreshold: Type.Integer({ default: 3 }) }, { default: {} }),
     rateLimit: Type.Object({
         perDay: Type.Integer({ default: 100000 }),
@@ -48,6 +76,27 @@ export const NotificationsConfigSchema = Type.Object({
     templates: Type.Object({ allowOverride: Type.Boolean({ default: false }) }, { 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
+     * 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
+     * worker-local extension, so campaigns 403'd via the real config path). */
+    broadcast: Type.Optional(Type.Object({
+        enabled: Type.Boolean({ default: false }),
+        /** tenant-default per-recipient quiet window (defer-not-drop); a
+         * per-campaign quiet_hours wins over it. Mirrors the campaigns-row shape
+         * (workers/notifications-v1 CampaignBody.quiet_hours). start/end are
+         * pattern-pinned to what the worker's parseHhMm actually parses — a
+         * looser string ('10pm') would validate but FAIL OPEN at runtime
+         * (quiet window silently ignored). */
+        defaultQuietHours: Type.Optional(Type.Object({
+            tz: Type.String({ minLength: 1, maxLength: 64 }),
+            start: Type.String({ maxLength: 5, pattern: '^\\d{1,2}:\\d{2}$' }),
+            end: Type.String({ maxLength: 5, pattern: '^\\d{1,2}:\\d{2}$' }),
+        })),
+        /** default rolling per-user-per-day campaign-send cap across campaigns */
+        freqCapPerUserPerDay: Type.Integer({ default: 5, minimum: 0 }),
+    })),
 });
 export const JobsConfigSchema = Type.Object({
     enabled: Type.Boolean({ default: true }),
@@ -208,7 +257,7 @@ 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 —
-        // R2 is cheap but Neon-resident metadata + abuse aren't (pricing re-audit
+        // 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
         // (Free/Dev 10 GB · Team 50 GB · Business 256 GB) are a follow-up needing the
         // tenant tier threaded to files-v1 (docs/pricing-model-analysis.md §6).
@@ -338,7 +387,7 @@ export const CmsConfigSchema = Type.Object({
         enabled: Type.Optional(Type.Boolean()),
     }))),
     // Realtime CDC bridge (cms-rel E): cms writes auto-publish a change event to
-    // a realtime channel — config-only rewiring of postgres_changes-style subs.
+    // a realtime channel — config-only rewiring of database-change-event-style subs.
     // Fire-and-forget via waitUntil; at-most-once (guaranteed delivery stays
     // webhooks-out / functions cms-hook). ONE Type.Record leaf.
     cdc: Type.Optional(Type.Record(Type.String({ maxLength: 64 }), Type.Object({
@@ -473,10 +522,10 @@ 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 pgvector until Lakebase is GA'd for the tier (#147).
+    // 'auto' resolves to the default managed vector backend for the tier (#147).
     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 public.tenant_secrets via apiKeyRef (envelope-encrypted).
+    // BYO key from tenant secrets via apiKeyRef (encrypted at rest).
     embed: Type.Object({
         provider: Type.Union([
             Type.Literal('byov'),
@@ -709,7 +758,7 @@ export const PaymentsConfigSchema = Type.Object({
     webhooks: Type.Object({ forwardToTenantUrl: Type.Optional(Type.String({ format: 'uri' })) }, { default: {} }),
 });
 // functions feature (vxil-functions-design §4.c). Tenant-deployed backend edge
-// functions on Workers-for-Platforms. The FUNCTION owns its identity (bundle via
+// 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
@@ -1020,6 +1069,25 @@ export function validateFeatureConfig(feature, raw) {
                 errors: [`/${String(key)}: required when provider is '${v.provider}' (omit it for provider 'mock')`],
             };
         }
+        // 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
+        // time so the tenant gets a clear `vxil push` error, not a silent runtime skip.
+        const ledgerErrs = [];
+        for (const [productId, rule] of Object.entries(v.ledger?.productMap ?? {})) {
+            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`);
+            }
+        }
+        for (const [tier, rule] of Object.entries(v.ledger?.tierMap ?? {})) {
+            (rule.grants ?? []).forEach((g, i) => {
+                if (g.creditType && isReservedCreditType(g.creditType)) {
+                    ledgerErrs.push(`/ledger/tierMap/${tier}/grants/${i}/creditType: '${g.creditType}' is a reserved vxil-COGS credit type and cannot be granted via config`);
+                }
+            });
+        }
+        if (ledgerErrs.length)
+            return { ok: false, errors: ledgerErrs.slice(0, 10) };
     }
     // Cross-field rule: CMS lifecycle hooks. Each hook's expression is parsed and
     // AST-validated against the closed sandbox allow-list HERE, at config-write
@@ -1189,3 +1257,133 @@ export function validateFeatureConfig(feature, raw) {
     }
     return { ok: true, errors: [], value: withDefaults };
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// PLANNER GROUNDING (roadmap §4.6.E; docs/ai-planner-design.md §2).
+// FEATURE_KEYS is the literal feature list the planner catalog is projected
+// from; the planner-catalog CI gate asserts set-equality with
+// Object.keys(FEATURE_SCHEMAS), so adding a feature without extending this
+// list (and FEATURE_HINTS below — a tsc error via the Record key-closure)
+// turns the gate red. Coverage is derived-and-gated; intent (whenToUse) is
+// human-authored but gated-for-presence.
+// ─────────────────────────────────────────────────────────────────────────────
+export const FEATURE_KEYS = [
+    'notifications', 'jobs', 'auth', 'rate-limits', 'files', 'webhooks',
+    'comments', 'cms', 'mcp', 'realtime', 'presence', 'orgs', 'activity-feed',
+    'vector-search', 'ai', 'rag', 'payments', 'functions', 'copilot',
+];
+export const FEATURE_HINTS = {
+    notifications: {
+        whenToUse: 'Sending email (transactional or broadcast) or in-app inbox messages to end-users: welcomes, receipts, reminders, alerts, digests.',
+        signals: ['email', 'notify', 'alert', 'reminder', 'welcome', 'receipt', 'digest', 'inbox'],
+        notFor: 'Live in-page updates (realtime) or activity timelines (activity-feed).',
+        dependsOn: [],
+    },
+    jobs: {
+        whenToUse: 'Background work: scheduled/cron tasks, delayed sends, retries, queues, long-running or periodic processing, durable multi-step waits.',
+        signals: ['schedule', 'cron', 'daily', 'background', 'queue', 'later', 'recurring', 'batch'],
+        notFor: 'Simple request-response logic that completes inline.',
+        dependsOn: [],
+    },
+    auth: {
+        whenToUse: 'End-users sign in/up to the app: passwords, magic links, OTP, social login, sessions. Almost every app with per-user data wants it.',
+        signals: ['sign in', 'login', 'account', 'register', 'user', 'password', 'profile', 'member', 'seller', 'buyer'],
+        notFor: 'Pure-public read-only content with no user state.',
+        dependsOn: [],
+    },
+    'rate-limits': {
+        whenToUse: 'Throttling abuse-prone or costly operations: public forms, expensive endpoints, per-user quotas.',
+        signals: ['rate limit', 'throttle', 'abuse', 'quota', 'spam'],
+        notFor: 'General correctness — the platform already meters requests globally.',
+        dependsOn: [],
+    },
+    files: {
+        whenToUse: 'End-users upload or download files/images/documents: avatars, attachments, photos, PDFs, media libraries.',
+        signals: ['upload', 'image', 'photo', 'file', 'attachment', 'document', 'avatar', 'media'],
+        notFor: 'Structured records (cms) or text content authored in-app.',
+        dependsOn: [],
+    },
+    webhooks: {
+        whenToUse: 'Receiving events FROM external services (Stripe/GitHub/etc. callbacks) or fanning tenant events out TO external URLs.',
+        signals: ['webhook', 'callback', 'external event', 'integration', 'sync with'],
+        notFor: 'In-app eventing between vxil features (the audit bus covers that).',
+        dependsOn: ['jobs'],
+    },
+    comments: {
+        whenToUse: 'Threaded discussion, reviews, replies, or reactions attached to any topic/record; also direct messages between users.',
+        signals: ['comment', 'review', 'discussion', 'reply', 'thread', 'DM', 'message'],
+        notFor: 'A social following timeline (activity-feed) or live chat transport (realtime).',
+        dependsOn: [],
+    },
+    cms: {
+        whenToUse: 'The data spine: typed record collections with fields, relations, owner-scoping, draft/publish, and optional keyless public reads. Most apps are, underneath, cms collections.',
+        signals: ['store', 'list', 'catalog', 'posts', 'products', 'records', 'items', 'content', 'blog', 'tasks', 'listings'],
+        notFor: 'End-user identity (auth) or file bytes (files).',
+        dependsOn: [],
+    },
+    mcp: {
+        whenToUse: 'Exposing the tenant backend as typed tools an AI agent drives (Claude/Cursor etc.).',
+        signals: ['agent', 'MCP', 'AI tools', 'tool-calling'],
+        notFor: 'In-app AI text generation (ai) or chat over documents (rag).',
+        dependsOn: [],
+    },
+    realtime: {
+        whenToUse: 'Live in-page updates over channels: chat rooms, live boards, collaborative views, instant refresh when data changes.',
+        signals: ['live', 'realtime', 'chat', 'instantly', 'websocket', 'multiplayer'],
+        notFor: 'Email/inbox notifications (notifications) or historical timelines (activity-feed).',
+        dependsOn: [],
+    },
+    presence: {
+        whenToUse: 'Showing who is online/typing/active on a channel right now.',
+        signals: ['online', 'who is here', 'typing', 'active users', 'presence'],
+        notFor: 'Message delivery itself (realtime carries the messages).',
+        dependsOn: ['realtime'],
+    },
+    orgs: {
+        whenToUse: 'End-users grouped into teams/workspaces with roles and per-resource permissions (multi-member accounts, RBAC).',
+        signals: ['team', 'workspace', 'organization', 'role', 'invite member', 'permission'],
+        notFor: 'Simple per-user ownership (cms ownerField covers that without orgs).',
+        dependsOn: ['auth'],
+    },
+    'activity-feed': {
+        whenToUse: 'Social timelines: follow/unfollow, personal feeds, notification feeds of who-did-what.',
+        signals: ['feed', 'timeline', 'follow', 'social', 'activity', 'news feed'],
+        notFor: 'Live transport (realtime) or email (notifications).',
+        dependsOn: [],
+    },
+    'vector-search': {
+        whenToUse: 'Semantic/similarity search over content: find-similar, meaning-based search boxes.',
+        signals: ['search', 'semantic', 'similar', 'find by meaning'],
+        notFor: 'Exact filters/sorts over records (the cms query DSL covers those).',
+        dependsOn: [],
+    },
+    ai: {
+        whenToUse: 'Calling LLMs from the app: generate/summarize/classify text, prompt templates, streaming completions (BYO provider key).',
+        signals: ['generate', 'summarize', 'AI', 'GPT', 'classify', 'rewrite', 'draft'],
+        notFor: 'Answers grounded in the tenant’s own documents (rag) or an embedded agent (copilot).',
+        dependsOn: [],
+    },
+    rag: {
+        whenToUse: 'Question-answering grounded in the tenant’s own content with citations: “ask your docs/notes/knowledge base”.',
+        signals: ['ask questions', 'chatbot over', 'knowledge base', 'Q&A', 'answers from documents'],
+        notFor: 'Free-form generation with no grounding (ai).',
+        dependsOn: ['vector-search', 'ai', 'files'],
+    },
+    payments: {
+        whenToUse: 'A payments integration: the tenant connects their OWN Stripe/Paddle/PayPal/RevenueCat account for checkout sessions, subscriptions, entitlements, and usage credits. Funds never touch vxil.',
+        signals: ['pay', 'subscription', 'checkout', 'billing', 'sale', 'order', 'price', 'monetize', 'credits'],
+        notFor: 'Anything implying vxil processes money — it is an integration with the tenant’s own provider.',
+        dependsOn: [],
+    },
+    functions: {
+        whenToUse: 'ONLY for truly-unique server logic no feature or cms rule can express: bespoke sagas, custom integrations over the egress guard, computed endpoints. Prefer features/cms first; functions are the escape hatch.',
+        signals: ['custom logic', 'custom backend', 'integration with', 'workflow', 'saga'],
+        notFor: 'Anything a shipped feature or a cms lifecycle hook already covers.',
+        dependsOn: [],
+    },
+    copilot: {
+        whenToUse: 'An embeddable in-app AI assistant that retrieves tenant content and proposes/confirms actions against the tenant’s own API.',
+        signals: ['assistant', 'copilot', 'in-app AI helper', 'agent widget'],
+        notFor: 'Plain text generation (ai) or doc Q&A without actions (rag).',
+        dependsOn: ['ai', 'vector-search', 'rag', 'mcp'],
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/feature-configs",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "TypeBox config schemas for every vxil feature — the typed manifests vxil.config.ts is built on. INTERNAL workspace package: bundled into the published `vxil` package (via @vxil/config), not published separately.",
   "license": "MIT",
   "homepage": "https://vxil.com",

package/src/index.test.ts

@@ -4,7 +4,10 @@ import {
   CopilotConfigSchema,
   FEATURE_SCHEMAS,
   NotificationsConfigSchema,
+  PaymentsConfigSchema,
+  RESERVED_CREDIT_TYPES,
   countLeaves,
+  isReservedCreditType,
   setKnownMcpTools,
   validateFeatureConfig,
 } from './index.js';
@@ -14,8 +17,11 @@ import {
 import { TOOLS } from '../../../workers/mcp-v1/src/tools.js';
 
 describe('15-flag cap analyzer (architecture §6)', () => {
-  it('notifications schema has 14 leaves — under the cap', () => {
-    expect(countLeaves(NotificationsConfigSchema)).toBe(14);
+  it('notifications schema has 15 leaves — at the cap (retry + broadcast are Optional bags, M21)', () => {
+    // enabled, fromEmail, fromName, replyTo, resendApiKeyRef, webhookSecretRef,
+    // provider, defaultLocale, retry(bag=1), suppression.softBounceThreshold,
+    // rateLimit(2), templates.allowOverride, inboxEnabled, broadcast(bag=1) = 15.
+    expect(countLeaves(NotificationsConfigSchema)).toBe(15);
     expect(countLeaves(NotificationsConfigSchema)).toBeLessThanOrEqual(CONFIG_FLAG_CAP);
   });
 
@@ -129,6 +135,74 @@ describe('validateFeatureConfig', () => {
     expect(r.ok).toBe(false);
   });
 
+  it('broadcast SURVIVES Value.Clean and persists via the real config path (M21/#4 regression)', () => {
+    // The HIGH this guards: `broadcast` used to live only in a worker-local
+    // schema, so this exact pipeline (Default → Clean → Check) silently
+    // DROPPED it and createCampaign 403'd on every real-config tenant.
+    const r = validateFeatureConfig('notifications', {
+      ...minimal,
+      broadcast: { enabled: true },
+    });
+    expect(r.ok).toBe(true);
+    const v = r.value as {
+      broadcast?: { enabled: boolean; freqCapPerUserPerDay: number };
+    };
+    expect(v.broadcast).toBeDefined();
+    expect(v.broadcast!.enabled).toBe(true);
+    // leaf default materialized inside the present bag
+    expect(v.broadcast!.freqCapPerUserPerDay).toBe(5);
+  });
+
+  it('broadcast.defaultQuietHours round-trips; absent broadcast stays absent (defaults-off deny)', () => {
+    const withQh = validateFeatureConfig('notifications', {
+      ...minimal,
+      broadcast: {
+        enabled: true,
+        defaultQuietHours: { tz: 'UTC', start: '22:00', end: '08:00' },
+      },
+    });
+    expect(withQh.ok).toBe(true);
+    const v = withQh.value as {
+      broadcast?: { defaultQuietHours?: { tz: string; start: string; end: string } };
+    };
+    expect(v.broadcast!.defaultQuietHours).toEqual({ tz: 'UTC', start: '22:00', end: '08:00' });
+
+    const absent = validateFeatureConfig('notifications', minimal);
+    expect(absent.ok).toBe(true);
+    expect((absent.value as { broadcast?: unknown }).broadcast).toBeUndefined();
+    // while retry (Optional bag WITH default:{}) still materializes — the
+    // shape-preserving half of the M21 leaf-budget fund
+    expect(((absent.value as { retry?: { maxAttempts: number } }).retry ?? {}).maxAttempts).toBe(5);
+  });
+
+  it('rejects a quiet-hours window parseHhMm cannot parse (would fail OPEN at run time)', () => {
+    const bad = validateFeatureConfig('notifications', {
+      ...minimal,
+      broadcast: {
+        enabled: true,
+        defaultQuietHours: { tz: 'UTC', start: '10pm', end: '08:00' },
+      },
+    });
+    expect(bad.ok).toBe(false);
+    expect(bad.errors.join(' ')).toContain('start');
+  });
+
+  it('rejects a malformed broadcast bag (unknown sub-keys stripped; bad types fail)', () => {
+    const badType = validateFeatureConfig('notifications', {
+      ...minimal,
+      broadcast: { enabled: 'yes' },
+    });
+    expect(badType.ok).toBe(false);
+
+    const sneaky = validateFeatureConfig('notifications', {
+      ...minimal,
+      broadcast: { enabled: true, maxAudiencePerRun: 100000 },
+    });
+    expect(sneaky.ok).toBe(true); // unknown key CLEANED, not persisted
+    expect(Object.keys((sneaky.value as { broadcast: object }).broadcast))
+      .not.toContain('maxAudiencePerRun');
+  });
+
   it('rejects an unknown feature', () => {
     const r = validateFeatureConfig('telepathy', { enabled: true });
     expect(r.ok).toBe(false);
@@ -737,3 +811,60 @@ describe('cms-rel config: readModels + cdc (cms-relational-depth §3/§4)', () =
     expect(validateFeatureConfig('cms', { cdc: bag }).ok).toBe(false);
   });
 });
+
+// ── payments: reserved (vxil-COGS) credit type cannot be mapped in ledger (F2) ─
+// A tenant that maps a product/tier grant to `fn_cpu_ms` and then triggers a
+// webhook/subscription would credit the vxil-COGS meter type through the grant
+// reducers → free vxil-billed functions. Rejected at config-write time so the
+// tenant gets a clear `vxil push` error instead of a silent runtime skip.
+describe('payments: reserved credit_type rejected in ledger grant maps (F2)', () => {
+  it('RESERVED_CREDIT_TYPES / isReservedCreditType are the shared SSOT', () => {
+    expect(RESERVED_CREDIT_TYPES.has('fn_cpu_ms')).toBe(true);
+    expect(isReservedCreditType('fn_cpu_ms')).toBe(true);
+    expect(isReservedCreditType('tokens')).toBe(false);
+  });
+
+  it('rejects fn_cpu_ms in productMap.creditType', () => {
+    const v = validateFeatureConfig('payments', {
+      ledger: {
+        productMap: { prod_free_cpu: { creditType: 'fn_cpu_ms', amount: 1000, period: 'once' } },
+        tierMap: {},
+      },
+    });
+    expect(v.ok).toBe(false);
+    expect(v.errors.some((e) => e.includes('/ledger/productMap/prod_free_cpu/creditType') && e.includes('reserved'))).toBe(true);
+  });
+
+  it('rejects fn_cpu_ms in a tierMap grant', () => {
+    const v = validateFeatureConfig('payments', {
+      ledger: {
+        productMap: {},
+        tierMap: {
+          pro: {
+            entitlements: [], quotas: {},
+            grants: [{ creditType: 'tokens', amount: 5, period: 'monthly' },
+                     { creditType: 'fn_cpu_ms', amount: 999_999, period: 'monthly' }],
+          },
+        },
+      },
+    });
+    expect(v.ok).toBe(false);
+    expect(v.errors.some((e) => e.includes('/ledger/tierMap/pro/grants/1/creditType') && e.includes('reserved'))).toBe(true);
+  });
+
+  it('accepts an ORDINARY credit_type through the same maps (no false-positive)', () => {
+    const v = validateFeatureConfig('payments', {
+      ledger: {
+        productMap: { pack_100: { creditType: 'tokens', amount: 100, period: 'once' } },
+        tierMap: { pro: { entitlements: ['pro'], quotas: {}, grants: [{ creditType: 'tokens', amount: 5, period: 'monthly' }] } },
+      },
+    });
+    expect(v.ok, v.errors.join()).toBe(true);
+  });
+
+  it('the reserved-type refinement is a VALIDATION rule, not a leaf — cap unaffected', () => {
+    // The refinement adds cross-field checks, never a schema property, so the
+    // payments leaf count is unchanged and comfortably under the cap.
+    expect(countLeaves(PaymentsConfigSchema)).toBeLessThanOrEqual(CONFIG_FLAG_CAP);
+  });
+});

package/src/index.ts

@@ -21,6 +21,23 @@ if (!FormatRegistry.Has('email')) {
   FormatRegistry.Set('email', (v) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v));
 }
 
+// ── RESERVED (vxil-COGS) CREDIT TYPES — single source of truth (audit F2) ─────
+// `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
+// tenant that self-grants `fn_cpu_ms` (directly, or by routing a product/tier
+// through the webhook/subscription grant reducers) runs vxil-billed function CPU
+// for free. Defined HERE (the typebox-only shared package both the control-plane
+// 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: ReadonlySet<string> = new Set<string>(['fn_cpu_ms']);
+
+/** True when a credit_type is a vxil-COGS reserved type (grant/consume/config
+ *  of which is restricted to internal platform machinery). */
+export function isReservedCreditType(creditType: string): boolean {
+  return RESERVED_CREDIT_TYPES.has(creditType);
+}
+
 export const NotificationsConfigSchema = Type.Object({
   enabled: Type.Boolean({ default: true }),
   fromEmail: Type.String({ format: 'email' }),
@@ -30,14 +47,27 @@ 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).
+  // 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).
+  webhookSecretRef: Type.Optional(Type.String()),
   // 'mock' exists for staging/e2e (deterministic provider); 'resend' is MVP.
   provider: Type.Union([Type.Literal('resend'), Type.Literal('mock')], {
     default: 'resend',
   }),
   defaultLocale: Type.String({ default: 'en-US' }),
   // nested objects carry `default: {}` so Value.Default can materialize them
-  // and then recurse into the leaf defaults
-  retry: Type.Object(
+  // 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).
+  // 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
+  // via retryOf()'s fallback).
+  retry: Type.Optional(Type.Object(
     {
       maxAttempts: Type.Integer({ default: 5, minimum: 1, maximum: 20 }),
       backoff: Type.Union([Type.Literal('exponential'), Type.Literal('linear')], {
@@ -45,7 +75,7 @@ export const NotificationsConfigSchema = Type.Object({
       }),
     },
     { default: {} },
-  ),
+  )),
   suppression: Type.Object(
     { softBounceThreshold: Type.Integer({ default: 3 }) },
     { default: {} },
@@ -63,13 +93,37 @@ export const NotificationsConfigSchema = Type.Object({
   ),
   /** 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
+   * 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
+   * worker-local extension, so campaigns 403'd via the real config path). */
+  broadcast: Type.Optional(Type.Object({
+    enabled: Type.Boolean({ default: false }),
+    /** tenant-default per-recipient quiet window (defer-not-drop); a
+     * per-campaign quiet_hours wins over it. Mirrors the campaigns-row shape
+     * (workers/notifications-v1 CampaignBody.quiet_hours). start/end are
+     * pattern-pinned to what the worker's parseHhMm actually parses — a
+     * looser string ('10pm') would validate but FAIL OPEN at runtime
+     * (quiet window silently ignored). */
+    defaultQuietHours: Type.Optional(Type.Object({
+      tz: Type.String({ minLength: 1, maxLength: 64 }),
+      start: Type.String({ maxLength: 5, pattern: '^\\d{1,2}:\\d{2}$' }),
+      end: Type.String({ maxLength: 5, pattern: '^\\d{1,2}:\\d{2}$' }),
+    })),
+    /** default rolling per-user-per-day campaign-send cap across campaigns */
+    freqCapPerUserPerDay: Type.Integer({ default: 5, minimum: 0 }),
+  })),
 });
-// Leaves: enabled, fromEmail, fromName, replyTo, resendApiKeyRef, provider,
-// defaultLocale, retry.maxAttempts, retry.backoff,
+// Leaves: enabled, fromEmail, fromName, replyTo, resendApiKeyRef,
+// webhookSecretRef, provider, defaultLocale, retry (Optional bag = 1),
 // suppression.softBounceThreshold, rateLimit.perDay, rateLimit.perTenantSec,
-// templates.allowOverride, inboxEnabled → 14. Cap = 15.
+// templates.allowOverride, inboxEnabled, broadcast (Optional bag = 1) → 15.
+// Cap = 15 — AT the cap; the next flag must collapse something.
 
 export type NotificationsConfig = Static<typeof NotificationsConfigSchema>;
+/** The §11b.5 broadcast bag as persisted (present ⇒ leaf defaults applied). */
+export type BroadcastConfig = NonNullable<NotificationsConfig['broadcast']>;
 
 export const JobsConfigSchema = Type.Object({
   enabled: Type.Boolean({ default: true }),
@@ -288,7 +342,7 @@ export const FilesConfigSchema = Type.Object({
   quotas: Type.Object(
     {
       // maximum caps are a defense-in-depth ceiling on tenant-editable storage —
-      // R2 is cheap but Neon-resident metadata + abuse aren't (pricing re-audit
+      // 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
       // (Free/Dev 10 GB · Team 50 GB · Business 256 GB) are a follow-up needing the
       // tenant tier threaded to files-v1 (docs/pricing-model-analysis.md §6).
@@ -458,7 +512,7 @@ export const CmsConfigSchema = Type.Object({
     }),
   )),
   // Realtime CDC bridge (cms-rel E): cms writes auto-publish a change event to
-  // a realtime channel — config-only rewiring of postgres_changes-style subs.
+  // a realtime channel — config-only rewiring of database-change-event-style subs.
   // Fire-and-forget via waitUntil; at-most-once (guaranteed delivery stays
   // webhooks-out / functions cms-hook). ONE Type.Record leaf.
   cdc: Type.Optional(Type.Record(
@@ -681,13 +735,13 @@ export type ActivityFeedConfig = Static<typeof ActivityFeedConfigSchema>;
 // 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 pgvector until Lakebase is GA'd for the tier (#147).
+  // 'auto' resolves to the default managed vector backend for the tier (#147).
   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 public.tenant_secrets via apiKeyRef (envelope-encrypted).
+  // BYO key from tenant secrets via apiKeyRef (encrypted at rest).
   embed: Type.Object(
     {
       provider: Type.Union(
@@ -1005,7 +1059,7 @@ export const PaymentsConfigSchema = Type.Object({
 export type PaymentsConfig = Static<typeof PaymentsConfigSchema>;
 
 // functions feature (vxil-functions-design §4.c). Tenant-deployed backend edge
-// functions on Workers-for-Platforms. The FUNCTION owns its identity (bundle via
+// 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
@@ -1381,8 +1435,14 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
   // 'mock' provider (the deterministic default) stays zero-config so the whole
   // ledger path is testable without real keys (features/payments.md §0/§6).
   if (feature === 'payments') {
-    const v = withDefaults as { provider?: string; stripe?: unknown; paddle?: unknown; revenuecat?: unknown };
-    const needsBlock: Record<string, keyof typeof v> = {
+    const v = withDefaults as {
+      provider?: string; stripe?: unknown; paddle?: unknown; revenuecat?: unknown;
+      ledger?: {
+        productMap?: Record<string, { creditType?: string }>;
+        tierMap?: Record<string, { grants?: Array<{ creditType?: string }> }>;
+      };
+    };
+    const needsBlock: Record<string, 'stripe' | 'paddle' | 'revenuecat'> = {
       stripe: 'stripe', paddle: 'paddle', revenuecat: 'revenuecat',
     };
     const key = v.provider ? needsBlock[v.provider] : undefined;
@@ -1392,6 +1452,28 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
         errors: [`/${String(key)}: required when provider is '${v.provider}' (omit it for provider 'mock')`],
       };
     }
+    // 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
+    // time so the tenant gets a clear `vxil push` error, not a silent runtime skip.
+    const ledgerErrs: string[] = [];
+    for (const [productId, rule] of Object.entries(v.ledger?.productMap ?? {})) {
+      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`,
+        );
+      }
+    }
+    for (const [tier, rule] of Object.entries(v.ledger?.tierMap ?? {})) {
+      (rule.grants ?? []).forEach((g, i) => {
+        if (g.creditType && isReservedCreditType(g.creditType)) {
+          ledgerErrs.push(
+            `/ledger/tierMap/${tier}/grants/${i}/creditType: '${g.creditType}' is a reserved vxil-COGS credit type and cannot be granted via config`,
+          );
+        }
+      });
+    }
+    if (ledgerErrs.length) return { ok: false, errors: ledgerErrs.slice(0, 10) };
   }
   // Cross-field rule: CMS lifecycle hooks. Each hook's expression is parsed and
   // AST-validated against the closed sandbox allow-list HERE, at config-write
@@ -1570,3 +1652,150 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
   }
   return { ok: true, errors: [], value: withDefaults };
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PLANNER GROUNDING (roadmap §4.6.E; docs/ai-planner-design.md §2).
+// FEATURE_KEYS is the literal feature list the planner catalog is projected
+// from; the planner-catalog CI gate asserts set-equality with
+// Object.keys(FEATURE_SCHEMAS), so adding a feature without extending this
+// list (and FEATURE_HINTS below — a tsc error via the Record key-closure)
+// turns the gate red. Coverage is derived-and-gated; intent (whenToUse) is
+// human-authored but gated-for-presence.
+// ─────────────────────────────────────────────────────────────────────────────
+export const FEATURE_KEYS = [
+  'notifications', 'jobs', 'auth', 'rate-limits', 'files', 'webhooks',
+  'comments', 'cms', 'mcp', 'realtime', 'presence', 'orgs', 'activity-feed',
+  'vector-search', 'ai', 'rag', 'payments', 'functions', 'copilot',
+] as const;
+export type FeatureKey = (typeof FEATURE_KEYS)[number];
+
+/** The hand-authored "when to use" intent a machine schema cannot convey.
+ *  REQUIRED for every feature (Record key-closure): a feature added to
+ *  FEATURE_KEYS without a hint is a compile error naming the missing key. */
+export interface PlannerHint {
+  /** One or two sentences: when an app needs this feature. */
+  whenToUse: string;
+  /** Soft priors — words/needs that suggest the feature (NOT a matcher). */
+  signals: string[];
+  /** When NOT to pick it (disambiguation vs neighbors). */
+  notFor: string;
+  /** Features that must be enabled alongside (runtime substrate deps). */
+  dependsOn: FeatureKey[];
+}
+
+export const FEATURE_HINTS: Record<FeatureKey, PlannerHint> = {
+  notifications: {
+    whenToUse: 'Sending email (transactional or broadcast) or in-app inbox messages to end-users: welcomes, receipts, reminders, alerts, digests.',
+    signals: ['email', 'notify', 'alert', 'reminder', 'welcome', 'receipt', 'digest', 'inbox'],
+    notFor: 'Live in-page updates (realtime) or activity timelines (activity-feed).',
+    dependsOn: [],
+  },
+  jobs: {
+    whenToUse: 'Background work: scheduled/cron tasks, delayed sends, retries, queues, long-running or periodic processing, durable multi-step waits.',
+    signals: ['schedule', 'cron', 'daily', 'background', 'queue', 'later', 'recurring', 'batch'],
+    notFor: 'Simple request-response logic that completes inline.',
+    dependsOn: [],
+  },
+  auth: {
+    whenToUse: 'End-users sign in/up to the app: passwords, magic links, OTP, social login, sessions. Almost every app with per-user data wants it.',
+    signals: ['sign in', 'login', 'account', 'register', 'user', 'password', 'profile', 'member', 'seller', 'buyer'],
+    notFor: 'Pure-public read-only content with no user state.',
+    dependsOn: [],
+  },
+  'rate-limits': {
+    whenToUse: 'Throttling abuse-prone or costly operations: public forms, expensive endpoints, per-user quotas.',
+    signals: ['rate limit', 'throttle', 'abuse', 'quota', 'spam'],
+    notFor: 'General correctness — the platform already meters requests globally.',
+    dependsOn: [],
+  },
+  files: {
+    whenToUse: 'End-users upload or download files/images/documents: avatars, attachments, photos, PDFs, media libraries.',
+    signals: ['upload', 'image', 'photo', 'file', 'attachment', 'document', 'avatar', 'media'],
+    notFor: 'Structured records (cms) or text content authored in-app.',
+    dependsOn: [],
+  },
+  webhooks: {
+    whenToUse: 'Receiving events FROM external services (Stripe/GitHub/etc. callbacks) or fanning tenant events out TO external URLs.',
+    signals: ['webhook', 'callback', 'external event', 'integration', 'sync with'],
+    notFor: 'In-app eventing between vxil features (the audit bus covers that).',
+    dependsOn: ['jobs'],
+  },
+  comments: {
+    whenToUse: 'Threaded discussion, reviews, replies, or reactions attached to any topic/record; also direct messages between users.',
+    signals: ['comment', 'review', 'discussion', 'reply', 'thread', 'DM', 'message'],
+    notFor: 'A social following timeline (activity-feed) or live chat transport (realtime).',
+    dependsOn: [],
+  },
+  cms: {
+    whenToUse: 'The data spine: typed record collections with fields, relations, owner-scoping, draft/publish, and optional keyless public reads. Most apps are, underneath, cms collections.',
+    signals: ['store', 'list', 'catalog', 'posts', 'products', 'records', 'items', 'content', 'blog', 'tasks', 'listings'],
+    notFor: 'End-user identity (auth) or file bytes (files).',
+    dependsOn: [],
+  },
+  mcp: {
+    whenToUse: 'Exposing the tenant backend as typed tools an AI agent drives (Claude/Cursor etc.).',
+    signals: ['agent', 'MCP', 'AI tools', 'tool-calling'],
+    notFor: 'In-app AI text generation (ai) or chat over documents (rag).',
+    dependsOn: [],
+  },
+  realtime: {
+    whenToUse: 'Live in-page updates over channels: chat rooms, live boards, collaborative views, instant refresh when data changes.',
+    signals: ['live', 'realtime', 'chat', 'instantly', 'websocket', 'multiplayer'],
+    notFor: 'Email/inbox notifications (notifications) or historical timelines (activity-feed).',
+    dependsOn: [],
+  },
+  presence: {
+    whenToUse: 'Showing who is online/typing/active on a channel right now.',
+    signals: ['online', 'who is here', 'typing', 'active users', 'presence'],
+    notFor: 'Message delivery itself (realtime carries the messages).',
+    dependsOn: ['realtime'],
+  },
+  orgs: {
+    whenToUse: 'End-users grouped into teams/workspaces with roles and per-resource permissions (multi-member accounts, RBAC).',
+    signals: ['team', 'workspace', 'organization', 'role', 'invite member', 'permission'],
+    notFor: 'Simple per-user ownership (cms ownerField covers that without orgs).',
+    dependsOn: ['auth'],
+  },
+  'activity-feed': {
+    whenToUse: 'Social timelines: follow/unfollow, personal feeds, notification feeds of who-did-what.',
+    signals: ['feed', 'timeline', 'follow', 'social', 'activity', 'news feed'],
+    notFor: 'Live transport (realtime) or email (notifications).',
+    dependsOn: [],
+  },
+  'vector-search': {
+    whenToUse: 'Semantic/similarity search over content: find-similar, meaning-based search boxes.',
+    signals: ['search', 'semantic', 'similar', 'find by meaning'],
+    notFor: 'Exact filters/sorts over records (the cms query DSL covers those).',
+    dependsOn: [],
+  },
+  ai: {
+    whenToUse: 'Calling LLMs from the app: generate/summarize/classify text, prompt templates, streaming completions (BYO provider key).',
+    signals: ['generate', 'summarize', 'AI', 'GPT', 'classify', 'rewrite', 'draft'],
+    notFor: 'Answers grounded in the tenant’s own documents (rag) or an embedded agent (copilot).',
+    dependsOn: [],
+  },
+  rag: {
+    whenToUse: 'Question-answering grounded in the tenant’s own content with citations: “ask your docs/notes/knowledge base”.',
+    signals: ['ask questions', 'chatbot over', 'knowledge base', 'Q&A', 'answers from documents'],
+    notFor: 'Free-form generation with no grounding (ai).',
+    dependsOn: ['vector-search', 'ai', 'files'],
+  },
+  payments: {
+    whenToUse: 'A payments integration: the tenant connects their OWN Stripe/Paddle/PayPal/RevenueCat account for checkout sessions, subscriptions, entitlements, and usage credits. Funds never touch vxil.',
+    signals: ['pay', 'subscription', 'checkout', 'billing', 'sale', 'order', 'price', 'monetize', 'credits'],
+    notFor: 'Anything implying vxil processes money — it is an integration with the tenant’s own provider.',
+    dependsOn: [],
+  },
+  functions: {
+    whenToUse: 'ONLY for truly-unique server logic no feature or cms rule can express: bespoke sagas, custom integrations over the egress guard, computed endpoints. Prefer features/cms first; functions are the escape hatch.',
+    signals: ['custom logic', 'custom backend', 'integration with', 'workflow', 'saga'],
+    notFor: 'Anything a shipped feature or a cms lifecycle hook already covers.',
+    dependsOn: [],
+  },
+  copilot: {
+    whenToUse: 'An embeddable in-app AI assistant that retrieves tenant content and proposes/confirms actions against the tenant’s own API.',
+    signals: ['assistant', 'copilot', 'in-app AI helper', 'agent widget'],
+    notFor: 'Plain text generation (ai) or doc Q&A without actions (rag).',
+    dependsOn: ['ai', 'vector-search', 'rag', 'mcp'],
+  },
+};