@vxil/sdk 0.4.0 → 0.5.0

package/README.md

@@ -88,6 +88,10 @@ try {
 
 ## Changelog
 
+### 0.4.1 — 2026-09-13
+
+- Documentation only: JSDoc no longer cites internal repository paths; points at the public guide instead. No runtime change.
+
 ### 0.4.0 — 2026-09-11
 
 - React-Native-clean: every query string is built without `URLSearchParams` (React Native's polyfill throws on `.set` before 0.81); wire bytes unchanged.

package/dist/index.d.ts

@@ -84,11 +84,11 @@ export interface VxilOptions {
      *  a mobile/SPA holds a public/thin-client key + the signed-in user's session
      *  token and calls the edge directly, safely scoped to that user. Absent ⇒
      *  **no header** ⇒ server-caller mode, exactly as today (backward compatible).
-     *  See docs/end-user-principals-design.md §4.1, §10. For a per-call override on
+     *  See https://vxil.com/docs/guide/09-security-and-multitenancy. For a per-call override on
      *  an otherwise server-mode client, use `vx.asEndUser(token)`. */
     endUserToken?: string;
     /** Global API major every request pins (default `'v1'`). Path-major, per
-     *  docs/feature-versioning.md — a breaking change ships as a new major on a
+     *  the versioning section of https://vxil.com/docs/guide/12-going-to-production — a breaking change ships as a new major on a
      *  new path, never in place. */
     apiVersion?: ApiVersion;
     /** Per-feature API-major overrides (`{ cms: 'v2' }`); each takes precedence
@@ -208,6 +208,41 @@ export interface FeatureConfig {
     version: number;
     manifest: Record<string, unknown>;
 }
+/** One rule in the advisory architecture brief. `title`, `fact`, `replaces` and
+ *  `docs` are platform copy rendered by the server from a gate-checked rule
+ *  catalog — they are never model prose. `why` explains why the rule applies to
+ *  the app you described. */
+export interface VxilBriefItem {
+    /** stable rule id, e.g. 'anonymous-session-for-guests'. */
+    rule_id: string;
+    title: string;
+    /** the platform rule itself, numbers inline. */
+    fact: string;
+    /** why it applies to this app. */
+    why: string;
+    /** the older habit this rule supersedes, when there is one. */
+    replaces?: string;
+    /** site path to the chapter section, e.g. '/docs/guide/16-…#…'. */
+    docs: string;
+}
+/** One section of the brief: the eight subject sections plus 'old-patterns',
+ *  a derived view of every cited rule that supersedes an older habit. */
+export interface VxilBriefSection {
+    /** 'identity' | 'data' | 'money' | 'background' | 'notifications' |
+     *  'rate-limits' | 'environments' | 'limits' | 'old-patterns' */
+    key: string;
+    title: string;
+    items: VxilBriefItem[];
+}
+/** The ADVISORY architecture brief attached to a plan: the platform rules the
+ *  plan's shape implies. `source` is 'ai' when a model chose the rules and
+ *  'deterministic' when they were derived from the feature set alone. */
+export interface VxilPlanBrief {
+    source: 'ai' | 'deterministic';
+    sections: VxilBriefSection[];
+    /** decisions the description does not settle (empty on the deterministic path). */
+    open_questions: string[];
+}
 /** An advisory plan from the planner (POST /v1/plan) — a proposal, not applied. */
 export interface VxilPlan {
     app: {
@@ -254,6 +289,8 @@ export interface VxilPlan {
     rationale: string;
     /** which brain produced the plan. */
     source: 'ai' | 'deterministic';
+    /** the advisory architecture brief. Absent when you pass `{ brief: false }`. */
+    brief?: VxilPlanBrief;
 }
 /** Current-month usage projection (GET /v1/usage) — the same meter the
  *  platform bills and enforces request quotas from. */
@@ -281,6 +318,15 @@ export interface UsageCurrent {
         metric: string;
         quantity: number;
     }>;
+    /** month-to-date split of `requests.used` by the SURFACE that served it —
+     *  the edge's resolved upstream (a bounded set), with /v1/fn/* reported as
+     *  'fn-invoke' and /v1/functions/* as its management surface,
+     *  'control-plane'. Busiest first. Observational only: never a billing
+     *  basis, and [] wherever request metering is not switched on. */
+    routes: Array<{
+        route_class: string;
+        requests: number;
+    }>;
 }
 export interface DeadLetter {
     delivery_id: string;
@@ -567,6 +613,12 @@ export interface SearchSyncSource {
 export interface AiUsage {
     input_tokens: number;
     output_tokens: number;
+    /** PROMPT-CACHE accounting, present only when the provider reports it
+     *  (anthropic, when the request asked for a cache breakpoint). A cache read
+     *  is already excluded from `input_tokens`, so metering and the daily budget
+     *  need no adjustment — these are for your own visibility. */
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
 }
 /** One tool invocation the model asked for (tool-use passthrough — vxil relays,
  *  YOU execute). Echo `id` back as `tool_call_id` on the `role:'tool'` turn. */
@@ -1074,6 +1126,12 @@ export interface VxilSchemaShape {
         Patch: unknown;
         Sortable: string;
         Filterable: Record<string, unknown>;
+        /** `vxil gen` emits this per collection: every `$expand`-able field (relation
+         *  + file) → its target collection slug (`'files'` for a file field, `null`
+         *  for a relation with no declared target). OPTIONAL on the shape so a client
+         *  generated BEFORE typed expand still satisfies the constraint — the expand
+         *  names then stay `string` and an expanded member resolves to an opaque bag. */
+        Relations?: Record<string, string | null>;
     }>;
     functions: Record<string, {
         Input: unknown;
@@ -1144,6 +1202,33 @@ export interface CmsBacklinksPage {
     has_more: boolean;
     limit: number;
 }
+/** ONE page of the slot re-index (cms.md §19). Loop while `complete` is false,
+ *  feeding `next_cursor` back in. `skipped` counts rows a concurrent write moved
+ *  under the page — the re-index never overwrites them (their own writer
+ *  re-projected them), but a `$inc` or a cascade `set_null` only re-projects its
+ *  OWN field's slot, so re-run the page while `skipped > 0`. */
+export interface CmsReindexPage {
+    collection: string;
+    field: string | null;
+    scanned: number;
+    updated: number;
+    skipped: number;
+    next_cursor: string | null;
+    complete: boolean;
+}
+/** The result of a bounded filtered delete (cms.md §20). `matched` counts the
+ *  rows this page selected (≤ `limit`); `deleted` counts the ones actually
+ *  removed (a row that vanished between the match and the delete is skipped).
+ *  Loop while `deleted > 0` — the filter re-evaluates against live rows. */
+export interface CmsBulkDeleteResult {
+    collection: string;
+    matched: number;
+    deleted: number;
+    cascaded: number;
+    set_null: number;
+    dry_run: boolean;
+    next_cursor: string | null;
+}
 /** A write guard (cms.md §10): "after this write, at most `max` live items
  *  match `filter`". Requires `lock` — an unlocked guard is racy by construction. */
 export interface CmsGuard {
@@ -1241,8 +1326,56 @@ export type CmsTxStep = {
     item_id: string;
     $where?: Record<string, unknown>;
 };
-/** A per-collection typed handle returned by `vx.from(collection)`. */
-export interface CollectionClient<C extends VxilSchemaShape['cms'][string]> {
+/** One CMS item as the API returns it — the envelope `$expand` inlines in place
+ *  of a stored relation id (cms.md §6.2). `R` is the target collection's Row. */
+export interface CmsItemEnvelope<R> {
+    item_id: string;
+    collection: string;
+    status: string;
+    version: number;
+    data: R;
+    created_at: string;
+    updated_at: string;
+    published_at: string | null;
+}
+/** What an expanded FILE field resolves to — a stub, never a cms row. */
+export interface CmsFileRef {
+    object_id: string;
+    $ref: 'files';
+}
+/** Every shape an expanded member can take (cms.md §6.2, all four verified in
+ *  cms-v1 core.ts): the full envelope; a `{ object_id, $ref: 'files' }` stub for
+ *  a file field; the BARE id when the expansion hit a cycle or the depth budget;
+ *  `null` when the target is soft-deleted, not visible to this caller, or owned
+ *  by another end-user. A
+ *  relation field may hold an ARRAY of ids, in which case the expansion is an
+ *  array of those same shapes — `vxil gen` types a relation as `string` and does
+ *  not carry arity, so the union includes the array form rather than inventing
+ *  a precision the model does not have. */
+export type CmsExpanded<R> = CmsItemEnvelope<R> | CmsFileRef | string | null | Array<CmsItemEnvelope<R> | CmsFileRef | string | null>;
+/** The expand-able field names of a collection: the keys of the generated
+ *  `Relations` map, or plain `string` for a client generated before it existed. */
+type ExpandableOf<C> = C extends {
+    Relations: infer R;
+} ? (R extends Record<string, unknown> ? keyof R & string : string) : string;
+/** Resolve one expanded member's row type: the target collection's `Row` when
+ *  `Relations` names a cms collection in THIS schema, else an opaque bag (a file
+ *  stub, an untargeted relation, or an older generated client). */
+type TargetRow<C, S extends VxilSchemaShape, K extends string> = C extends {
+    Relations: infer R;
+} ? (K extends keyof R ? (R[K] extends keyof S['cms'] ? S['cms'][R[K]]['Row'] : Record<string, unknown>) : Record<string, unknown>) : Record<string, unknown>;
+/** The Row with the expanded members re-typed. Non-expanded fields are untouched,
+ *  so a query WITHOUT `expand` keeps exactly today's type. */
+export type ExpandedRow<C extends {
+    Row: unknown;
+}, S extends VxilSchemaShape, E extends readonly string[]> = Omit<C['Row'], E[number]> & {
+    [K in E[number]]: CmsExpanded<TargetRow<C, S, K>>;
+};
+/** A per-collection typed handle returned by `vx.from(collection)`. `S` (the
+ *  whole generated schema) is DEFAULTED so `CollectionClient<X>` — the only
+ *  spelling that existed before typed expand — still compiles; it is what lets
+ *  an expanded relation resolve to the TARGET collection's Row. */
+export interface CollectionClient<C extends VxilSchemaShape['cms'][string], S extends VxilSchemaShape = VxilSchemaShape> {
     create(data: C['Insert'], opts?: {
         status?: 'draft' | 'published';
         lock?: string;
@@ -1254,7 +1387,26 @@ export interface CollectionClient<C extends VxilSchemaShape['cms'][string]> {
         version: number;
         data: C['Row'];
     }>;
+    /** `expand` inlines the named relation/file fields (cms.md §6.2) — the names
+     *  come from the generated `Relations`, so a typo is a compile error. Bounds
+     *  (worker-clamped regardless of config): depth 1 (ceiling 2), ≤5 fields
+     *  (ceiling 25). Omit it and the result type is exactly today's `Row`. */
+    get<E extends readonly ExpandableOf<C>[]>(itemId: string, opts: {
+        expand: E;
+    }): Promise<ExpandedRow<C, S, E>>;
     get(itemId: string): Promise<C['Row']>;
+    query<E extends readonly ExpandableOf<C>[]>(q: {
+        filter?: Partial<C['Filterable']>;
+        sort?: C['Sortable'] | `-${C['Sortable'] & string}`;
+        limit?: number;
+        cursor?: string;
+        /** relation/file fields to inline — see `get`. Cannot be combined with
+         *  `count` (a separate method here; the raw API 422s when both are sent). */
+        expand: E;
+    }): Promise<{
+        items: ExpandedRow<C, S, E>[];
+        next_cursor: string | null;
+    }>;
     query(q?: {
         /** Keys AND values come from the generated `Filterable`: each field's value
          *  is its operator union (`VxilFilterRange*` on slotted fields, equality/
@@ -1283,6 +1435,15 @@ export interface CollectionClient<C extends VxilSchemaShape['cms'][string]> {
         cascaded: number;
         set_null: number;
     }>;
+    /** cms.md §20: bounded filtered delete over the generated `Filterable` — a
+     *  filter is required, ≤100 rows per call, `dryRun` previews. Loop while
+     *  `deleted > 0`. */
+    deleteMany(q: {
+        filter: Partial<C['Filterable']>;
+        limit?: number;
+        cursor?: string;
+        dryRun?: boolean;
+    }): Promise<CmsBulkDeleteResult>;
     publish(itemId: string): Promise<C['Row']>;
     /** cms-rel B2: bounded group-by aggregate (spec §7 `groupBy()` surface).
      *  groupBy/field names are typed over the Row's keys; slot-existence stays a
@@ -1345,7 +1506,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
      *  client, mirroring how the edge threads the verified principal. The base
      *  URL, api key, fetch impl, version pins and the retry/timeout/hooks options
      *  are inherited unchanged; only the end-user token is (re)set. Pass a falsy token to get back a server-mode
-     *  client (drops the header). See docs/end-user-principals-design.md §4.1. */
+     *  client (drops the header). See https://vxil.com/docs/guide/09-security-and-multitenancy. */
     asEndUser(endUserToken: string | undefined): Vxil<S>;
     /** Build the versioned request path — the ONE place a wire path is finalized.
      *  Every request (call(), audit.export, the fn proxy) routes through here, so
@@ -1361,7 +1522,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
      *  generic `cms.items.*` methods — the wire calls are identical; the generated
      *  `VxilSchema` supplies the field types. `vx.cms.items.*` stays as the
      *  always-available un-generic fallback. */
-    from<C extends keyof S['cms'] & string>(collection: C): CollectionClient<S['cms'][C]>;
+    from<C extends keyof S['cms'] & string>(collection: C): CollectionClient<S['cms'][C], S>;
     /** Typed function invoke (design §4.5). `vx.fn.<name>(payload)` POSTs to
      *  /v1/fn/<name>; the generated `VxilSchema` types Input/Output (Level-0
      *  opaque until a function declares a signature). A Proxy gives the
@@ -1415,7 +1576,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
     readonly notifications: {
         send: (input: {
             user_id: string;
-            template: "magic-link" | "welcome" | "transactional";
+            /** The four shipped template ids (notifications.md §7). */
+            template: "magic-link" | "otp-code" | "welcome" | "transactional";
             data: Record<string, unknown>;
             /** Explicit wins; otherwise the recipient's stored `locale` attribute
              *  (set it via `users.upsert({ attributes: { locale } })`), then
@@ -1434,7 +1596,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          *  + enqueued, or neither) and `results` is index-aligned with `items`. */
         sendBatch: (items: Array<{
             user_id: string;
-            template: "magic-link" | "welcome" | "transactional";
+            template: "magic-link" | "otp-code" | "welcome" | "transactional";
             data: Record<string, unknown>;
             locale?: string;
             channel?: "email" | "inbox" | "both";
@@ -1521,6 +1683,80 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             }>>;
             add: (email: string) => Promise<void>;
             remove: (email: string) => Promise<void>;
+            /** Bounce/complaint AGGREGATE over a 1–90 day window (default 30; an
+             *  out-of-range or non-numeric `days` clamps rather than erroring).
+             *  `counts` always carries all four reasons with explicit zeros; `rate` is
+             *  `counts.total / sent` to 4 dp, or null when nothing was sent. `sent`
+             *  counts deliveries the provider ACCEPTED, not inbox-delivered mail —
+             *  this is a suppressions-per-accepted-send ratio, not an RFC bounce rate.
+             *  Operator surface: a verified end-user token gets 403. */
+            stats: (q?: {
+                days?: number;
+            }) => Promise<{
+                window_days: number;
+                since: string;
+                counts: {
+                    hard_bounce: number;
+                    spam_complaint: number;
+                    soft_bounce: number;
+                    manual: number;
+                    total: number;
+                };
+                sent: number;
+                rate: number | null;
+            }>;
+        };
+        /** Per-end-user MUTES — the opt-out table every send channel checks before
+         *  it delivers. Absence of a row means "not muted". A row with no
+         *  `template_id` is the ALL-TEMPLATES row.
+         *
+         *  MUTE WINS. Enforcement is `(template_id = <template> OR template_id IS
+         *  NULL) AND muted`, so the all-templates row SHADOWS a per-template
+         *  `muted: false` — to re-enable one template after a master mute, clear the
+         *  all-templates row (`{ muted: false }`, no `template_id`) and mute the
+         *  others individually. `get` returns a computed `effective` per row, which
+         *  is the answer enforcement gives; render THAT, not the stored `muted`.
+         *
+         *  AUTH MAIL IS NEVER MUTEABLE. `magic-link` and `otp-code` carry sign-in
+         *  links and codes: `set` rejects them with a 422 and the all-templates row
+         *  does not cover them, so an "unsubscribe from everything" click can never
+         *  lock a user out of its own account. Muteable ids: `welcome`,
+         *  `transactional`. (Password-reset mail rides `transactional`, which stays
+         *  muteable — see the notifications feature doc §6c.)
+         *
+         *  SCOPES: with an end-user token both calls are confined to the verified
+         *  principal and take `notifications:read` (a browser key that can mute its
+         *  own mail must not also be able to send mail). With a server key
+         *  `user_id` is required and `set` takes `notifications:send`. */
+        preferences: {
+            get: (q: {
+                user_id?: string;
+            }) => Promise<{
+                preferences: Array<{
+                    user_id: string;
+                    template_id: string | null;
+                    muted: boolean;
+                    /** what enforcement actually does with this row: the stored `muted`
+                     *  OR the all-templates row's mute (which shadows it). */
+                    effective: boolean;
+                    updated_at: string;
+                }>;
+                count: number;
+            }>;
+            /** Idempotent upsert. OMIT `template_id` for the all-templates row; pass
+             *  a MUTEABLE id to mute just that template. Auth mail (`magic-link`,
+             *  `otp-code`) is a 422 — it always sends. There is no delete —
+             *  `muted: false` is the un-mute. */
+            set: (input: {
+                user_id?: string;
+                template_id?: "welcome" | "transactional";
+                muted: boolean;
+            }) => Promise<{
+                user_id: string;
+                template_id: string | null;
+                muted: boolean;
+                updated_at: string;
+            }>;
         };
         /** Deliveries the retry budget could not save (the dashboard "Resend" surface). */
         deadLetters: {
@@ -1618,11 +1854,15 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
     };
     /** The planner (config-architect): describe an app in plain English and get an
      *  ADVISORY vxil plan — which features to enable, a materialized `config_draft`,
-     *  and which truly-unique logic needs a tenant function. Deterministic + pure;
-     *  it PROPOSES a plan, it never applies anything (review it, then push the
-     *  config). Needs `features:read`. (POST /v1/plan; docs/planner-feature-design.md) */
+     *  which truly-unique logic needs a tenant function, and an architecture brief
+     *  (identity, data, money path, background work, limits, and the older patterns
+     *  vxil replaces). It PROPOSES a plan, it never applies anything (review it,
+     *  then push the config). Pass `{ brief: false }` to skip the brief.
+     *  Needs `features:read`. (POST /v1/plan; https://vxil.com/docs/guide/10-agents-and-mcp) */
     readonly planner: {
-        create: (description: string, name?: string) => Promise<VxilPlan>;
+        create: (description: string, name?: string, opts?: {
+            brief?: boolean;
+        }) => Promise<VxilPlan>;
     };
     readonly audit: {
         list: (q?: {
@@ -1832,7 +2072,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             delete: (ruleId: string) => Promise<void>;
         };
     };
-    /** vxil-auth. SCOPES (docs/features/auth.md §7.6): every flow here that
+    /** vxil-auth. SCOPES (vxil.com/docs/guide/09-security-and-multitenancy): every flow here that
      *  obtains, renews, verifies or ends the caller's OWN session (signUp/signIn,
      *  magicLink, otp, anonymous, stepUp, oauth, sessions.refresh/revoke/verify,
      *  password reset) accepts the narrow `auth:signin` — the ONLY auth scope a
@@ -1859,11 +2099,27 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             session: AuthSession;
             verified: boolean;
         }>;
+        /** Magic-link sign-in: vxil mails a single-use link to the address and the
+         *  click returns here with `?token=`. The request is always a 202 —
+         *  identical for a known and an unknown address (anti-enumeration). A
+         *  second request for the SAME address inside the per-identifier cooldown
+         *  (auth config `magicLink.resendCooldownSec`, default 60s, 0 disables) is
+         *  `429 magic_link_rate_limited` with a `Retry-After` header. */
         magicLink: {
+            /** `test_link` is present ONLY when the address matches auth config
+             *  `otp.testRecipients` (store-review / CI accounts): no mail is sent and
+             *  the full sign-in link comes back instead. `captcha_token` is required
+             *  when the tenant configured `security.captchaSecretRef`; `locale`
+             *  chooses the mail's language. */
             request: (input: {
                 email: string;
                 redirect_url: string;
-            }) => Promise<void>;
+                locale?: string;
+                captcha_token?: string;
+            }) => Promise<{
+                sent: true;
+                test_link?: string;
+            }>;
             verify: (token: string) => Promise<{
                 user_id: string;
                 session: AuthSession;
@@ -2174,7 +2430,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             create: (input: {
                 collection: string;
                 singular?: string;
-                /** End-user owner-scoping (docs/end-user-principals-design.md §5.1):
+                /** End-user owner-scoping (https://vxil.com/docs/guide/09-security-and-multitenancy):
                  *  names an existing `string` field that holds the owner id. When set,
                  *  the cms worker auto-scopes owned reads/writes to the VERIFIED
                  *  end-user principal (default-deny) in end-user mode; a no-op in
@@ -2252,6 +2508,35 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
              *  the owner_field are never exposed. `false` closes the lane (and purges the
              *  edge cache). Read the public side with `cmsPublicUrl` / `listCmsPublic`. */
             setPublic: (collection: string, isPublic: boolean) => Promise<void>;
+            /** Re-project the collection's index slots after an `index_slot` move
+             *  (cms.md §19). Slots are projected on WRITE only, so until this runs,
+             *  stored rows keep their OLD projection: the new slot is NULL and the
+             *  VACATED slot still holds the old field's values — range/sort on the
+             *  moved field returns the WRONG rows, not merely missing ones. ONE page
+             *  per call (≤2000 rows, default 500), resumable via `next_cursor`,
+             *  idempotent (a second full pass reports `updated: 0`), and never a
+             *  version bump / CDC event (slots are derived columns). Server-key only.
+             *  `field` narrows the write to that field's slot plus any unowned slot. */
+            reindex: (collection: string, opts?: {
+                field?: string;
+                cursor?: string;
+                limit?: number;
+            }) => Promise<CmsReindexPage>;
+            /** Drive `reindex` to completion, page by page. Returns the totals.
+             *  A page that reports `skipped > 0` lost rows to a concurrent writer, so
+             *  it is re-run ONCE before the loop advances (the write is idempotent and
+             *  the retry is bounded — a permanently hot collection never spins). The
+             *  residual `skipped` is returned, not swallowed. */
+            reindexAll: (collection: string, opts?: {
+                field?: string;
+                limit?: number;
+                onPage?: (p: CmsReindexPage) => void;
+            }) => Promise<{
+                scanned: number;
+                updated: number;
+                skipped: number;
+                pages: number;
+            }>;
             /** Replace the collection's per-record ACTION list (cms.md §17) — the
              *  `{ actions }` fields-route meta-op; `[]` clears. Each action is ONE
              *  human-initiated step: the dashboard renders it as a button per record,
@@ -2273,7 +2558,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 version: number;
                 data: Record<string, unknown>;
             }>;
-            get: (collection: string, itemId: string) => Promise<Record<string, unknown>>;
+            /** `expand` inlines relation/file fields into `data` (cms.md §6.2): the
+             *  full item envelope, a `{ object_id, $ref: 'files' }` stub for a file,
+             *  the bare id on a cycle/depth cut, `null` for an invisible target. */
+            get: (collection: string, itemId: string, opts?: {
+                expand?: readonly string[] | string;
+            }) => Promise<Record<string, unknown>>;
             /**
              * The bounded query DSL. filter ops: $eq $ne $gt $gte $lt $lte $in
              * $contains $startsWith (LIKE-escaped; substring-searchable on s*-slotted
@@ -2289,6 +2579,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 sort?: string;
                 limit?: number;
                 cursor?: string;
+                /** relation/file fields to inline (`$expand`) — see `get`. The server
+                 *  refuses `$expand` together with `count=true` (422 invalid_query), so
+                 *  use `count()` for the aggregate. */
+                expand?: readonly string[] | string;
             }) => Promise<{
                 items: Array<Record<string, unknown>>;
                 next_cursor: string | null;
@@ -2313,6 +2607,22 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 cascaded: number;
                 set_null: number;
             }>;
+            /** N-22 (cms.md §20): BOUNDED FILTERED delete — soft-delete up to `limit`
+             *  items (1–100, default 25) matching `filter`, newest id first. A filter
+             *  is REQUIRED (an unselected sweep is refused 422). Each matched row runs
+             *  the SAME single-item delete path (restrict refusal, cascade budget,
+             *  unique-claim freeing, CDC), so this is N deletes in one round trip, not
+             *  a set-delete. `dryRun` reports `matched` and mutates nothing. Loop
+             *  while `deleted > 0`. A refusal mid-sweep (409 referenced / 422
+             *  cascade_too_large) stops the call — rows already deleted STAY deleted,
+             *  and the error message names how many. Soft-deleted rows are hard-purged
+             *  by the platform 30 days later (there is no per-tenant retention knob). */
+            deleteMany: (collection: string, q: {
+                filter: Record<string, unknown>;
+                limit?: number;
+                cursor?: string;
+                dryRun?: boolean;
+            }) => Promise<CmsBulkDeleteResult>;
             publish: (collection: string, itemId: string) => Promise<Record<string, unknown>>;
             /** P1-12 (cms.md §11.1): the BOUNDED reverse read — which live items
              *  reference this one, through which relation field. Owner-scoped in
@@ -2474,7 +2784,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
      * only the envelope: membership, read-cursors, mute, and a directed block
      * list; the messages themselves are `comments` rows on the
      * `dm:<conversation_id>` topic. Gated by its own `dm` config, independent of
-     * comments. See docs/features/dm.md.
+     * comments. See vxil.com/docs/guide/06-feature-catalog.
      */
     readonly dm: {
         /** Read the resolved DM config (defaults merged with the stored partial). */
@@ -3362,6 +3672,27 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
              *  over the template's stored schema. */
             response_schema?: Record<string, unknown>;
             images?: string[];
+            /** DOCUMENT inputs (pdf / plain text), up to 8 refs, each a public https
+             *  URL, a `data:application/pdf;base64,…` (or `text/plain`) URL, or
+             *  `file:<object_id>`. Every ref is fetched + inlined server-side, so the
+             *  provider only ever sees base64. Needs a provider with the `documents`
+             *  capability (anthropic) — others answer 501 with a fixHint. */
+            documents?: string[];
+            /** PROMPT-CACHE breakpoints (anthropic; ignored elsewhere). `system`
+             *  caches the system prompt (tool definitions render before it and cache
+             *  with it); `messages` asks the provider to cache the transcript prefix;
+             *  `ttl` picks the 5-minute default or the 1-hour window. A cache READ
+             *  simply lowers the billed `input_tokens` — reported back as
+             *  `usage.cache_read_input_tokens` / `usage.cache_creation_input_tokens`
+             *  when the provider sends them. The minimum cacheable prefix is
+             *  model-dependent (512-4096 tokens); a shorter prompt silently does not
+             *  cache. The response cache key ignores this field (it changes billing,
+             *  not output). */
+            cache?: {
+                system?: boolean;
+                messages?: boolean;
+                ttl?: "5m" | "1h";
+            };
             user_id?: string;
         }) => Promise<AiGeneration>;
         /** Streamed generation: returns the channel + connect token immediately; open
@@ -3418,6 +3749,27 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
              *  usage frame). */
             response_schema?: Record<string, unknown>;
             images?: string[];
+            /** DOCUMENT inputs (pdf / plain text), up to 8 refs, each a public https
+             *  URL, a `data:application/pdf;base64,…` (or `text/plain`) URL, or
+             *  `file:<object_id>`. Every ref is fetched + inlined server-side, so the
+             *  provider only ever sees base64. Needs a provider with the `documents`
+             *  capability (anthropic) — others answer 501 with a fixHint. */
+            documents?: string[];
+            /** PROMPT-CACHE breakpoints (anthropic; ignored elsewhere). `system`
+             *  caches the system prompt (tool definitions render before it and cache
+             *  with it); `messages` asks the provider to cache the transcript prefix;
+             *  `ttl` picks the 5-minute default or the 1-hour window. A cache READ
+             *  simply lowers the billed `input_tokens` — reported back as
+             *  `usage.cache_read_input_tokens` / `usage.cache_creation_input_tokens`
+             *  when the provider sends them. The minimum cacheable prefix is
+             *  model-dependent (512-4096 tokens); a shorter prompt silently does not
+             *  cache. The response cache key ignores this field (it changes billing,
+             *  not output). */
+            cache?: {
+                system?: boolean;
+                messages?: boolean;
+                ttl?: "5m" | "1h";
+            };
             user_id?: string;
         }) => Promise<AiJobHandle>;
         /** Re-mint a fresh connect token for a LIVE stream (a generation that
@@ -3648,7 +4000,23 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          *  `quota` inlines one quota, `creditType` inlines the same owner-bound
          *  balance `getBalance` returns — ONE call for a thin client's paywall.
          *  A non-2xx answer means UNKNOWN: render the last cached answer, never
-         *  free (payments.md §3a). */
+         *  free (payments.md §3a).
+         *
+         *  OVERLAPPING SUBSCRIPTIONS — what `until` means. The WINNER is the
+         *  entitled subscription with the highest `tierMap[tier].rank` (default 0);
+         *  within a rank, the one with the latest period end (an open-ended manual
+         *  grant counts as unbounded), ties broken by subscription id, so the answer
+         *  is stable on every read. `entitlements` are the UNION and `quotas` the
+         *  MAX across ALL entitled rows, so a cancelled add-on never strips an
+         *  entitlement another live row still grants. `until` is the WINNER's OWN
+         *  boundary — not `max()` across rows, and not "when all access ends": it
+         *  answers *when does the CURRENT tier stop being good*. It is `null` for an
+         *  open-ended manual grant and on the `free` baseline. Across ranks a higher
+         *  tier wins even when a lower one runs longer, so `until` can report the
+         *  higher tier's earlier end; access does not dip (a lapsed winner re-folds
+         *  on read and the lower tier takes over), but a client that CACHES `until`
+         *  will show an early expiry — re-read instead of trusting a cached value
+         *  past it. */
         getEntitlements: (userId: string, opts?: {
             quota?: string;
             creditType?: string;
@@ -3800,6 +4168,21 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          * refund the full un-refunded remainder. Idempotency-Key REQUIRED — a retry
          * replays the recorded refund (never a second provider refund); a refund can
          * NEVER exceed the charge (422 refund_exceeds_charge).
+         *
+         * PADDLE: a PARTIAL refund is issued as a per-line-item adjustment on the
+         * Paddle transaction and typically settles ASYNCHRONOUSLY — it comes back
+         * `pending` until your Paddle account approves the adjustment, and the
+         * approving webhook flips it to `succeeded`. A rejected adjustment flips it
+         * to `failed`, releases the reserved amount back onto the charge and emits
+         * `payments.refund.failed`. While a refund is `pending`, the credits the
+         * charge bought are NOT yet reversed. Stripe and the mock settle inline.
+         *
+         * If the provider has nothing left to refund on the charge — e.g. a refund
+         * was already issued in the provider's own dashboard, which vxil's running
+         * total cannot see — the call returns 422 `refund_not_allocatable` with the
+         * precise reason, and nothing is sent to the provider. It is deterministic:
+         * retrying the same refund fails the same way. A provider call that actually
+         * fails is still 502 `provider_error`.
          */
         createRefund: (input: {
             charge_id: string;
@@ -3896,7 +4279,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             tier?: string;
         }) => Promise<PaymentsSimulationResult>;
         /** The last report-only reconciliation sweep result for this project
-         *  (`run: null` before the first daily tick). */
+         *  (`run: null` before the first daily tick). Finding kinds:
+         *  `balance_drift`, `entitlement_lag`, `null_tier`, `refund_pending`,
+         *  `stranded_webhook`, `terminal_entitled`, `webhook_secret_missing`.
+         *  SERVER-SIDE KEYS ONLY — a thin-client (`end_user_required`) key gets
+         *  403 `server_only`; the sweep is a tenant-wide operator surface. */
         reconcile: () => Promise<{
             run: {
                 run_id: string;
@@ -3935,7 +4322,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         /** Provider webhook event log (payments.md §7 "Event log & replay"):
          *  operator visibility over every delivery — incl. persisted signature
          *  failures — plus an idempotent reprocess verb. Needs payments:read
-         *  (reprocess: payments:write). */
+         *  (reprocess: payments:write).
+         *  SERVER-SIDE KEYS ONLY — a thin-client (`end_user_required`) key gets
+         *  403 `server_only` on list, detail and reprocess: the event log is a
+         *  tenant-wide operator surface and the detail carries the provider
+         *  payload (other customers' emails, provider ids and amounts). */
         webhookEvents: {
             /** List deliveries newest-first (keyset-paginated; pass `cursor` from a
              *  prior page's next_cursor). List rows omit payload/raw_body. */

package/dist/index.js

@@ -48,6 +48,16 @@ export class VxilError extends Error {
     }
 }
 const DEFAULT_BASE = 'https://api.vxil.com';
+/** Normalize the `expand` option to the `$expand` query value: a comma-joined
+ *  list (the server's spelling), or `undefined` when nothing is expanded so the
+ *  emitted URL is BYTE-IDENTICAL to a call without it. `qs()` percent-encodes
+ *  the `$` in the key, which `url.searchParams.get('$expand')` decodes. */
+function expandParam(e) {
+    if (e === undefined)
+        return undefined;
+    const list = (typeof e === 'string' ? [e] : e).filter((x) => typeof x === 'string' && x.length > 0);
+    return list.length ? list.join(',') : undefined;
+}
 /** Resolve the API base. Precedence: explicit `baseUrl` option > the
  *  `VXIL_BASE_URL` env var (Node/server only — guarded via `globalThis`, so it's
  *  inert in browsers & Workers) > the production default. This lets an internal /
@@ -150,7 +160,7 @@ export class Vxil {
      *  client, mirroring how the edge threads the verified principal. The base
      *  URL, api key, fetch impl, version pins and the retry/timeout/hooks options
      *  are inherited unchanged; only the end-user token is (re)set. Pass a falsy token to get back a server-mode
-     *  client (drops the header). See docs/end-user-principals-design.md §4.1. */
+     *  client (drops the header). See https://vxil.com/docs/guide/09-security-and-multitenancy. */
     asEndUser(endUserToken) {
         return new Vxil({
             apiKey: this.key,
@@ -195,13 +205,21 @@ export class Vxil {
                 ...(opts?.guard ? { guard: opts.guard } : {}),
                 ...(opts?.guards ? { guards: opts.guards } : {}),
             }),
-            get: (itemId) => this.cms.items.get(c, itemId).then(unwrap),
-            query: (q) => this.cms.items.query(c, q)
-                .then((r) => ({ items: r.items.map(unwrap), next_cursor: r.next_cursor })),
+            // `expand` rides through as `$expand` on the wire; the envelope's `.data`
+            // already CARRIES the expanded members (cms-v1 replaces the stored id
+            // inside `data`), so the unwrap is unchanged and the overloads above are
+            // purely a type-level narrowing.
+            // (the two `as` casts pick the OVERLOADED member type: one runtime
+            // implementation serves both the plain and the `expand` overload, which
+            // differ only in the result TYPE — the wire call is the same.)
+            get: ((itemId, opts) => this.cms.items.get(c, itemId, opts).then(unwrap)),
+            query: ((q) => this.cms.items.query(c, q)
+                .then((r) => ({ items: r.items.map(unwrap), next_cursor: r.next_cursor }))),
             count: (filter) => this.cms.items.count(c, filter),
             patch: (itemId, data, opts) => this.cms.items.patch(c, itemId, data, opts).then(unwrap),
             inc: (itemId, incs, opts) => this.cms.items.inc(c, itemId, incs, opts).then(unwrap),
             delete: (itemId, opts) => this.cms.items.delete(c, itemId, opts),
+            deleteMany: (q) => this.cms.items.deleteMany(c, q),
             publish: (itemId) => this.cms.items.publish(c, itemId).then(unwrap),
             aggregate: (q) => this.cms.items.aggregate(c, q),
             rank: (q) => this.cms.items.rank(c, q),
@@ -344,6 +362,50 @@ export class Vxil {
             remove: async (email) => {
                 await this.call('DELETE', `/v1/notifications/suppressions/${encodeURIComponent(email)}`);
             },
+            /** Bounce/complaint AGGREGATE over a 1–90 day window (default 30; an
+             *  out-of-range or non-numeric `days` clamps rather than erroring).
+             *  `counts` always carries all four reasons with explicit zeros; `rate` is
+             *  `counts.total / sent` to 4 dp, or null when nothing was sent. `sent`
+             *  counts deliveries the provider ACCEPTED, not inbox-delivered mail —
+             *  this is a suppressions-per-accepted-send ratio, not an RFC bounce rate.
+             *  Operator surface: a verified end-user token gets 403. */
+            stats: async (q) => {
+                const s = qs({ days: q?.days || undefined });
+                return (await this.call('GET', `/v1/notifications/suppressions/stats${s}`)).data;
+            },
+        },
+        /** Per-end-user MUTES — the opt-out table every send channel checks before
+         *  it delivers. Absence of a row means "not muted". A row with no
+         *  `template_id` is the ALL-TEMPLATES row.
+         *
+         *  MUTE WINS. Enforcement is `(template_id = <template> OR template_id IS
+         *  NULL) AND muted`, so the all-templates row SHADOWS a per-template
+         *  `muted: false` — to re-enable one template after a master mute, clear the
+         *  all-templates row (`{ muted: false }`, no `template_id`) and mute the
+         *  others individually. `get` returns a computed `effective` per row, which
+         *  is the answer enforcement gives; render THAT, not the stored `muted`.
+         *
+         *  AUTH MAIL IS NEVER MUTEABLE. `magic-link` and `otp-code` carry sign-in
+         *  links and codes: `set` rejects them with a 422 and the all-templates row
+         *  does not cover them, so an "unsubscribe from everything" click can never
+         *  lock a user out of its own account. Muteable ids: `welcome`,
+         *  `transactional`. (Password-reset mail rides `transactional`, which stays
+         *  muteable — see the notifications feature doc §6c.)
+         *
+         *  SCOPES: with an end-user token both calls are confined to the verified
+         *  principal and take `notifications:read` (a browser key that can mute its
+         *  own mail must not also be able to send mail). With a server key
+         *  `user_id` is required and `set` takes `notifications:send`. */
+        preferences: {
+            get: async (q) => {
+                const s = qs({ user_id: q.user_id || undefined });
+                return (await this.call('GET', `/v1/notifications/preferences${s}`)).data;
+            },
+            /** Idempotent upsert. OMIT `template_id` for the all-templates row; pass
+             *  a MUTEABLE id to mute just that template. Auth mail (`magic-link`,
+             *  `otp-code`) is a 422 — it always sends. There is no delete —
+             *  `muted: false` is the un-mute. */
+            set: async (input) => (await this.call('PUT', '/v1/notifications/preferences', input)).data,
         },
         /** Deliveries the retry budget could not save (the dashboard "Resend" surface). */
         deadLetters: {
@@ -400,13 +462,18 @@ export class Vxil {
     };
     /** The planner (config-architect): describe an app in plain English and get an
      *  ADVISORY vxil plan — which features to enable, a materialized `config_draft`,
-     *  and which truly-unique logic needs a tenant function. Deterministic + pure;
-     *  it PROPOSES a plan, it never applies anything (review it, then push the
-     *  config). Needs `features:read`. (POST /v1/plan; docs/planner-feature-design.md) */
+     *  which truly-unique logic needs a tenant function, and an architecture brief
+     *  (identity, data, money path, background work, limits, and the older patterns
+     *  vxil replaces). It PROPOSES a plan, it never applies anything (review it,
+     *  then push the config). Pass `{ brief: false }` to skip the brief.
+     *  Needs `features:read`. (POST /v1/plan; https://vxil.com/docs/guide/10-agents-and-mcp) */
     planner = {
-        create: async (description, name) => (await this.call('POST', '/v1/plan', {
+        create: async (description, name, opts) => (await this.call('POST', '/v1/plan', {
             description,
             ...(name ? { name } : {}),
+            // sent ONLY when opting out, so every shipped call site's request body
+            // stays byte-identical
+            ...(opts?.brief === false ? { brief: false } : {}),
         })).data,
     };
     audit = {
@@ -544,7 +611,7 @@ export class Vxil {
             },
         },
     };
-    /** vxil-auth. SCOPES (docs/features/auth.md §7.6): every flow here that
+    /** vxil-auth. SCOPES (vxil.com/docs/guide/09-security-and-multitenancy): every flow here that
      *  obtains, renews, verifies or ends the caller's OWN session (signUp/signIn,
      *  magicLink, otp, anonymous, stepUp, oauth, sessions.refresh/revoke/verify,
      *  password reset) accepts the narrow `auth:signin` — the ONLY auth scope a
@@ -557,10 +624,19 @@ export class Vxil {
     auth = {
         signUp: async (input) => (await this.call('POST', '/v1/auth/sign-up', input)).data,
         signIn: async (input) => (await this.call('POST', '/v1/auth/sign-in', input)).data,
+        /** Magic-link sign-in: vxil mails a single-use link to the address and the
+         *  click returns here with `?token=`. The request is always a 202 —
+         *  identical for a known and an unknown address (anti-enumeration). A
+         *  second request for the SAME address inside the per-identifier cooldown
+         *  (auth config `magicLink.resendCooldownSec`, default 60s, 0 disables) is
+         *  `429 magic_link_rate_limited` with a `Retry-After` header. */
         magicLink: {
-            request: async (input) => {
-                await this.call('POST', '/v1/auth/magic-link/request', input);
-            },
+            /** `test_link` is present ONLY when the address matches auth config
+             *  `otp.testRecipients` (store-review / CI accounts): no mail is sent and
+             *  the full sign-in link comes back instead. `captcha_token` is required
+             *  when the tenant configured `security.captchaSecretRef`; `locale`
+             *  chooses the mail's language. */
+            request: async (input) => (await this.call('POST', '/v1/auth/magic-link/request', input)).data,
             verify: async (token) => (await this.call('POST', '/v1/auth/magic-link/verify', { token })).data,
         },
         /** Email OTP sign-in: a 6-digit single-use code (distinct from magic-link).
@@ -748,6 +824,59 @@ export class Vxil {
             setPublic: async (collection, isPublic) => {
                 await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { public: isPublic });
             },
+            /** Re-project the collection's index slots after an `index_slot` move
+             *  (cms.md §19). Slots are projected on WRITE only, so until this runs,
+             *  stored rows keep their OLD projection: the new slot is NULL and the
+             *  VACATED slot still holds the old field's values — range/sort on the
+             *  moved field returns the WRONG rows, not merely missing ones. ONE page
+             *  per call (≤2000 rows, default 500), resumable via `next_cursor`,
+             *  idempotent (a second full pass reports `updated: 0`), and never a
+             *  version bump / CDC event (slots are derived columns). Server-key only.
+             *  `field` narrows the write to that field's slot plus any unowned slot. */
+            reindex: async (collection, opts) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/reindex`, {
+                ...(opts?.field ? { field: opts.field } : {}),
+                ...(opts?.cursor ? { cursor: opts.cursor } : {}),
+                ...(opts?.limit ? { limit: opts.limit } : {}),
+            })).data,
+            /** Drive `reindex` to completion, page by page. Returns the totals.
+             *  A page that reports `skipped > 0` lost rows to a concurrent writer, so
+             *  it is re-run ONCE before the loop advances (the write is idempotent and
+             *  the retry is bounded — a permanently hot collection never spins). The
+             *  residual `skipped` is returned, not swallowed. */
+            reindexAll: async (collection, opts) => {
+                let cursor;
+                let scanned = 0;
+                let updated = 0;
+                let skipped = 0;
+                let pages = 0;
+                for (;;) {
+                    let page = await this.cms.collections.reindex(collection, {
+                        ...(opts?.field ? { field: opts.field } : {}),
+                        ...(opts?.limit ? { limit: opts.limit } : {}),
+                        ...(cursor ? { cursor } : {}),
+                    });
+                    scanned += page.scanned;
+                    updated += page.updated;
+                    pages += 1;
+                    opts?.onPage?.(page);
+                    if ((page.skipped ?? 0) > 0) {
+                        page = await this.cms.collections.reindex(collection, {
+                            ...(opts?.field ? { field: opts.field } : {}),
+                            ...(opts?.limit ? { limit: opts.limit } : {}),
+                            ...(cursor ? { cursor } : {}),
+                        });
+                        scanned += page.scanned;
+                        updated += page.updated;
+                        pages += 1;
+                        opts?.onPage?.(page);
+                    }
+                    skipped += page.skipped ?? 0;
+                    if (page.complete || !page.next_cursor)
+                        break;
+                    cursor = page.next_cursor;
+                }
+                return { scanned, updated, skipped, pages };
+            },
             /** Replace the collection's per-record ACTION list (cms.md §17) — the
              *  `{ actions }` fields-route meta-op; `[]` clears. Each action is ONE
              *  human-initiated step: the dashboard renders it as a button per record,
@@ -760,7 +889,13 @@ export class Vxil {
             /** `lock` serializes same-key writers (per-tenant advisory lock); `guard`
              *  is the declarative capacity/overlap invariant (requires lock) — cms.md §10. */
             create: async (collection, input) => (await this.call('POST', `/v1/cms/items/${encodeURIComponent(collection)}`, input)).data,
-            get: async (collection, itemId) => (await this.call('GET', `/v1/cms/items/${encodeURIComponent(collection)}/${encodeURIComponent(itemId)}`)).data,
+            /** `expand` inlines relation/file fields into `data` (cms.md §6.2): the
+             *  full item envelope, a `{ object_id, $ref: 'files' }` stub for a file,
+             *  the bare id on a cycle/depth cut, `null` for an invisible target. */
+            get: async (collection, itemId, opts) => {
+                const s = qs({ $expand: expandParam(opts?.expand) });
+                return (await this.call('GET', `/v1/cms/items/${encodeURIComponent(collection)}/${encodeURIComponent(itemId)}${s}`)).data;
+            },
             /**
              * The bounded query DSL. filter ops: $eq $ne $gt $gte $lt $lte $in
              * $contains $startsWith (LIKE-escaped; substring-searchable on s*-slotted
@@ -777,6 +912,7 @@ export class Vxil {
                     sort: q?.sort || undefined,
                     limit: q?.limit || undefined,
                     cursor: q?.cursor || undefined,
+                    $expand: expandParam(q?.expand),
                 });
                 return (await this.call('GET', `/v1/cms/items/${encodeURIComponent(collection)}${s}`)).data;
             },
@@ -804,6 +940,22 @@ export class Vxil {
             /** Returns the cascade tally (cms.md §11); `ifVersion` rides If-Match and
              *  a conflict aborts BEFORE any cascade side-effect. */
             delete: async (collection, itemId, opts) => (await this.call('DELETE', `/v1/cms/items/${encodeURIComponent(collection)}/${encodeURIComponent(itemId)}`, undefined, opts?.ifVersion !== undefined ? { 'if-match': String(opts.ifVersion) } : {})).data,
+            /** N-22 (cms.md §20): BOUNDED FILTERED delete — soft-delete up to `limit`
+             *  items (1–100, default 25) matching `filter`, newest id first. A filter
+             *  is REQUIRED (an unselected sweep is refused 422). Each matched row runs
+             *  the SAME single-item delete path (restrict refusal, cascade budget,
+             *  unique-claim freeing, CDC), so this is N deletes in one round trip, not
+             *  a set-delete. `dryRun` reports `matched` and mutates nothing. Loop
+             *  while `deleted > 0`. A refusal mid-sweep (409 referenced / 422
+             *  cascade_too_large) stops the call — rows already deleted STAY deleted,
+             *  and the error message names how many. Soft-deleted rows are hard-purged
+             *  by the platform 30 days later (there is no per-tenant retention knob). */
+            deleteMany: async (collection, q) => (await this.call('POST', `/v1/cms/items/${encodeURIComponent(collection)}/delete`, {
+                filter: q.filter,
+                ...(q.limit !== undefined ? { limit: q.limit } : {}),
+                ...(q.cursor ? { cursor: q.cursor } : {}),
+                ...(q.dryRun !== undefined ? { dry_run: q.dryRun } : {}),
+            })).data,
             publish: async (collection, itemId) => (await this.call('POST', `/v1/cms/items/${encodeURIComponent(collection)}/${encodeURIComponent(itemId)}/publish`)).data,
             /** P1-12 (cms.md §11.1): the BOUNDED reverse read — which live items
              *  reference this one, through which relation field. Owner-scoped in
@@ -880,7 +1032,7 @@ export class Vxil {
      * only the envelope: membership, read-cursors, mute, and a directed block
      * list; the messages themselves are `comments` rows on the
      * `dm:<conversation_id>` topic. Gated by its own `dm` config, independent of
-     * comments. See docs/features/dm.md.
+     * comments. See vxil.com/docs/guide/06-feature-catalog.
      */
     dm = {
         /** Read the resolved DM config (defaults merged with the stored partial). */
@@ -1455,7 +1607,23 @@ export class Vxil {
          *  `quota` inlines one quota, `creditType` inlines the same owner-bound
          *  balance `getBalance` returns — ONE call for a thin client's paywall.
          *  A non-2xx answer means UNKNOWN: render the last cached answer, never
-         *  free (payments.md §3a). */
+         *  free (payments.md §3a).
+         *
+         *  OVERLAPPING SUBSCRIPTIONS — what `until` means. The WINNER is the
+         *  entitled subscription with the highest `tierMap[tier].rank` (default 0);
+         *  within a rank, the one with the latest period end (an open-ended manual
+         *  grant counts as unbounded), ties broken by subscription id, so the answer
+         *  is stable on every read. `entitlements` are the UNION and `quotas` the
+         *  MAX across ALL entitled rows, so a cancelled add-on never strips an
+         *  entitlement another live row still grants. `until` is the WINNER's OWN
+         *  boundary — not `max()` across rows, and not "when all access ends": it
+         *  answers *when does the CURRENT tier stop being good*. It is `null` for an
+         *  open-ended manual grant and on the `free` baseline. Across ranks a higher
+         *  tier wins even when a lower one runs longer, so `until` can report the
+         *  higher tier's earlier end; access does not dip (a lapsed winner re-folds
+         *  on read and the lower tier takes over), but a client that CACHES `until`
+         *  will show an early expiry — re-read instead of trusting a cached value
+         *  past it. */
         getEntitlements: async (userId, opts) => {
             const s = qs({
                 user_id: userId,
@@ -1527,6 +1695,21 @@ export class Vxil {
          * refund the full un-refunded remainder. Idempotency-Key REQUIRED — a retry
          * replays the recorded refund (never a second provider refund); a refund can
          * NEVER exceed the charge (422 refund_exceeds_charge).
+         *
+         * PADDLE: a PARTIAL refund is issued as a per-line-item adjustment on the
+         * Paddle transaction and typically settles ASYNCHRONOUSLY — it comes back
+         * `pending` until your Paddle account approves the adjustment, and the
+         * approving webhook flips it to `succeeded`. A rejected adjustment flips it
+         * to `failed`, releases the reserved amount back onto the charge and emits
+         * `payments.refund.failed`. While a refund is `pending`, the credits the
+         * charge bought are NOT yet reversed. Stripe and the mock settle inline.
+         *
+         * If the provider has nothing left to refund on the charge — e.g. a refund
+         * was already issued in the provider's own dashboard, which vxil's running
+         * total cannot see — the call returns 422 `refund_not_allocatable` with the
+         * precise reason, and nothing is sent to the provider. It is deterministic:
+         * retrying the same refund fails the same way. A provider call that actually
+         * fails is still 502 `provider_error`.
          */
         createRefund: async (input, opts) => (await this.call('POST', '/v1/payments/refunds', input, { 'idempotency-key': opts.idempotencyKey })).data,
         /** Where the user MANAGES their subscription, resolved by FUNDING SOURCE
@@ -1569,7 +1752,11 @@ export class Vxil {
          *  webhook path and judge it with the conformance oracle. */
         simulate: async (input) => (await this.call('POST', '/v1/payments/simulate', input)).data,
         /** The last report-only reconciliation sweep result for this project
-         *  (`run: null` before the first daily tick). */
+         *  (`run: null` before the first daily tick). Finding kinds:
+         *  `balance_drift`, `entitlement_lag`, `null_tier`, `refund_pending`,
+         *  `stranded_webhook`, `terminal_entitled`, `webhook_secret_missing`.
+         *  SERVER-SIDE KEYS ONLY — a thin-client (`end_user_required`) key gets
+         *  403 `server_only`; the sweep is a tenant-wide operator surface. */
         reconcile: async () => (await this.call('GET', '/v1/payments/reconcile')).data,
         /** List charges newest-first (the refund enabler — discover the charge_id).
          *  Filters: user_id, status, limit (clamped 1..100, default 50). */
@@ -1584,7 +1771,11 @@ export class Vxil {
         /** Provider webhook event log (payments.md §7 "Event log & replay"):
          *  operator visibility over every delivery — incl. persisted signature
          *  failures — plus an idempotent reprocess verb. Needs payments:read
-         *  (reprocess: payments:write). */
+         *  (reprocess: payments:write).
+         *  SERVER-SIDE KEYS ONLY — a thin-client (`end_user_required`) key gets
+         *  403 `server_only` on list, detail and reprocess: the event log is a
+         *  tenant-wide operator surface and the detail carries the provider
+         *  payload (other customers' emails, provider ids and amounts). */
         webhookEvents: {
             /** List deliveries newest-first (keyset-paginated; pass `cursor` from a
              *  prior page's next_cursor). List rows omit payload/raw_body. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": false,
   "type": "module",
   "description": "Typed client for the Vxil REST API (notifications, auth, jobs, files, cms, comments, webhooks, realtime, orgs, rate-limits).",
@@ -10,8 +10,7 @@
     "backend",
     "baas",
     "sdk",
-    "typed-client",
-    "cloudflare-workers"
+    "typed-client"
   ],
   "engines": {
     "node": ">=18"