@vxil/sdk 0.12.0 → 0.13.1

package/dist/index.d.ts

@@ -475,7 +475,7 @@ export interface RateLimitOverride {
     created_at: string;
     updated_at?: string;
 }
-/** A payments provider webhook delivery in the event log (payments.md §7).
+/** A payments provider webhook delivery in the event log (guide ch. 6, payments).
  *  `payload` and `raw_body` are only populated on the detail read. */
 export interface PaymentsWebhookEvent {
     event_id: string;
@@ -508,7 +508,7 @@ export interface PaymentsWebhookEvent {
     raw_body?: string | null;
     provider_event_ts?: string | null;
 }
-/** The outcome of a provider re-sync / Restore Purchases (payments.md §7d). */
+/** The outcome of a provider re-sync / Restore Purchases (guide ch. 6, payments). */
 export interface PaymentsSyncOutcome {
     provider: string;
     synced: number;
@@ -523,7 +523,7 @@ export interface PaymentsSyncOutcome {
     }>;
     dry_run?: boolean;
 }
-/** A lifecycle simulation run (payments.md §7d; mock/dev tenants only). */
+/** A lifecycle simulation run (guide ch. 6, payments; mock/dev tenants only). */
 export interface PaymentsSimulationResult {
     scenario: string;
     run_id: string;
@@ -545,8 +545,8 @@ export interface PaymentsSimulationResult {
         pass: boolean;
     };
 }
-/** The ONE complete entitlement read (GET /v1/payments/entitlements; payments.md
- *  §3a). `until` is the winning subscription's current_period_end (+ the
+/** The ONE complete entitlement read (GET /v1/payments/entitlements; guide ch. 6,
+ *  payments). `until` is the winning subscription's current_period_end (+ the
  *  configured grace window when it is past_due); null on the free baseline. */
 export interface PaymentsEntitlementView {
     user_id: string;
@@ -581,7 +581,7 @@ export interface PaymentsEntitlementView {
  *  `completed` (Paddle paid → completed). Handle `succeeded` gated on
  *  `provider_status === 'completed'` plus `completed` to act once per charge. */
 export type PaymentsProviderChargeStatus = 'paid' | 'completed';
-/** A charge row as listed by GET /v1/payments/charges (payments.md §3). */
+/** A charge row as listed by GET /v1/payments/charges (guide ch. 6, payments). */
 export interface PaymentsCharge {
     /** the vxil charge id (`chg_…`) — what refunds and a charge-linked grant key on */
     charge_id: string;
@@ -630,8 +630,8 @@ export interface PaymentsRefund {
     source: 'api' | 'webhook';
     created_at: string | null;
 }
-/** A subscription row as listed by GET /v1/payments/subscriptions (payments.md
- *  §3) — provider subscriptions, manual grants and purchase passes alike.
+/** A subscription row as listed by GET /v1/payments/subscriptions (guide ch. 6,
+ *  payments) — provider subscriptions, manual grants and purchase passes alike.
  *  `current_period_start` (2026-09-25) is the row's own window start: for a
  *  purchase pass (`provider_sub_id: 'purchase:<charge_id>'`) the day its access
  *  begins, which is in the FUTURE for a pass queued behind a live one; for a
@@ -662,8 +662,8 @@ export interface FileObject {
     status: 'pending' | 'available' | 'deleted';
     created_at: string;
 }
-/** A live shared link as listed by GET /v1/files/{id}/shared-links (files.md
- *  §6). `downloads` is the burn-on-read counter; `max_downloads` null =
+/** A live shared link as listed by GET /v1/files/{id}/shared-links (guide ch. 6,
+ *  files). `downloads` is the burn-on-read counter; `max_downloads` null =
  *  unlimited (1 = a one-time link). A link that hit its cap, expired, or was
  *  revoked no longer lists. */
 export interface FileSharedLink {
@@ -682,7 +682,7 @@ export interface CreateSharedLinkOptions {
     expires_at?: string;
     max_downloads?: number | null;
 }
-/** One recognized OCR text block (files.md §1.1). bbox is [x, y, w, h] in the
+/** One recognized OCR text block (guide ch. 6, files). bbox is [x, y, w, h] in the
  *  provider's unit space; page is 1-based. confidence is 0..1 normalized per
  *  provider (Textract native 0..100 divided by 100; mock pins 0.95); absent
  *  when the provider supplied none. */
@@ -923,7 +923,7 @@ export interface AiGenerationRecord {
      *  generation) */
     result_state: 'stored' | 'purged' | 'not_recorded';
 }
-/** The `data` of `job.generation.queued` (jobs.md §11): the run was accepted. */
+/** The `data` of `job.generation.queued` (guide ch. 6, jobs): the run was accepted. */
 export interface JobGenerationQueuedEventPayload {
     run_id: string;
     job_name: string;
@@ -1510,7 +1510,7 @@ export interface RagSearchHit {
      *  vector-search (−1…1; null when retrieval used no query vector). */
     similarity?: number | null;
     /** the effective post-boost score results are RANKED by — present only when
-     *  metadata boosts applied (rag.md §2f). */
+     *  metadata boosts applied (guide ch. 6, rag). */
     boosted_score?: number;
     metadata?: Record<string, unknown>;
 }
@@ -1527,7 +1527,7 @@ export interface RagSearchResult {
     };
 }
 /** A replayed frame page from the rag-native resume endpoint (proxies the ai
- *  §2a replay buffer: every recorded frame with seq > since, plus done). */
+ *  feature's replay buffer: every recorded frame with seq > since, plus done). */
 export interface RagResumePage {
     generation_id: string;
     since: number;
@@ -1751,7 +1751,7 @@ export interface DmConfigState {
     version: number;
     configured: boolean;
 }
-/** The safe query subset the keyless cms public lane admits (roadmap §4.4): the
+/** The safe query subset the keyless cms public lane admits (guide ch. 4): the
  *  same bounded filter/sort/limit/cursor as the authored list, minus anything
  *  owner- or lifecycle-scoped (the lane FORCES status='published'). `filter` is a
  *  JSON object, serialized to the wire `filter=` param. */
@@ -1773,7 +1773,7 @@ export interface CmsPublicRow {
     published_at: string | null;
 }
 /** Build the anonymous, KEYLESS public-delivery URL for a collection's PUBLISHED
- *  items (roadmap §4.4) — `{base}/v1/cms/public/:tenantId/:collection[?…]`. This is
+ *  items (guide ch. 4, "Draft and publish") — `{base}/v1/cms/public/:tenantId/:collection[?…]`. This is
  *  the reader path a public blog/storefront/docs site hits with NO api key: the
  *  edge mints a restricted read-only inner token bound to the URL tenant, forces
  *  `status='published'`, and strips the collection's owner_field. PURE (no
@@ -1784,7 +1784,7 @@ export declare function cmsPublicUrl(tenantId: string, collection: string, query
     baseUrl?: string;
 }): string;
 /** Fetch a page of a collection's PUBLISHED items over the KEYLESS public lane
- *  (roadmap §4.4) — NO api key, no `Vxil` client, no auth of any kind. This is the
+ *  (guide ch. 4) — NO api key, no `Vxil` client, no auth of any kind. This is the
  *  anonymous reader path (a blog/storefront/docs front-end). Returns the same
  *  `{ items, next_cursor }` envelope the authed list does, but rows are stripped
  *  to the public surface (`CmsPublicRow`) — drafts and the owner_field are never
@@ -1952,12 +1952,12 @@ type DisabledFeatures<S extends VxilSchemaShape> = {
     [P in keyof FeatureMap]: FeatureMap[P] extends S['features'] ? never : P;
 }[keyof FeatureMap];
 /** The feature-narrowed client: feature namespaces the tenant hasn't enabled become
- *  a compile error (the design's §4.4 headline). `Vxil.connect<VxilSchema>()`
+ *  a compile error. `Vxil.connect<VxilSchema>()`
  *  returns it; plain `new Vxil<VxilSchema>()` stays un-narrowed for back-compat. */
 export type EnabledVxil<S extends VxilSchemaShape> = Omit<Vxil<S>, DisabledFeatures<S>> & {
     [P in DisabledFeatures<S>]: DisabledFeature<FeatureMap[P] & string>;
 };
-/** One config-declared per-record ACTION (cms.md §17): a button on a record row
+/** One config-declared per-record ACTION (guide ch. 4): a button on a record row
  *  that invokes the deployed tenant function `fn` ONCE with `{ collection,
  *  item_id, action, actor, item }`. Exactly one human-initiated step — no
  *  conditions, no chaining, no scheduling. ≤8 per collection. */
@@ -1969,7 +1969,7 @@ export interface CmsActionDef {
     /** the deployed function name (/^[a-z][a-z0-9-]{0,47}$/) */
     fn: string;
 }
-/** One live item referencing another through a relation field (cms.md §11.1). */
+/** One live item referencing another through a relation field (guide ch. 4). */
 export interface CmsBacklink {
     collection: string;
     field: string;
@@ -1986,7 +1986,7 @@ export interface CmsBacklinksPage {
     has_more: boolean;
     limit: number;
 }
-/** ONE page of the slot re-index (cms.md §19). Loop while `complete` is false,
+/** ONE page of the slot re-index (guide ch. 4). 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
@@ -1999,8 +1999,14 @@ export interface CmsReindexPage {
     skipped: number;
     next_cursor: string | null;
     complete: boolean;
-}
-/** The result of a bounded filtered delete (cms.md §20). `matched` counts the
+    /** Present when this page certified an index (the last page of a pass over
+     *  a collection whose equality / owner index was not armed): 'armed',
+     *  'pending' (rows changed during the pass — run another) or 'timeout' (the
+     *  check ran out of time — the index stays unarmed; filters stay correct
+     *  but unaccelerated). */
+    index_certify?: 'armed' | 'pending' | 'timeout';
+}
+/** The result of a bounded filtered delete (guide ch. 4). `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.
@@ -2020,33 +2026,33 @@ export interface CmsBulkDeleteResult {
     complete: boolean;
     next_cursor: string | null;
 }
-/** A write guard (cms.md §10): "after this write, at most `max` live items
+/** A write guard (guide ch. 4): "after this write, at most `max` live items
  *  match `filter`". Requires `lock` — an unlocked guard is racy by construction. */
 export interface CmsGuard {
     filter: Record<string, unknown>;
     max: number;
 }
-/** One guard of a `guards[]` multi-invariant write (cms.md §10). Same
+/** One guard of a `guards[]` multi-invariant write (guide ch. 4). Same
  *  { filter, max } as CmsGuard plus an optional custom 409 `message` surfaced on
  *  the FIRST violation. */
 export interface CmsGuardTerm extends CmsGuard {
     /** Custom guard_failed message (≤200 chars) for THIS invariant. */
     message?: string;
 }
-/** Concurrency options shared by the cms write methods (cms.md §9–10). */
+/** Concurrency options shared by the cms write methods (guide ch. 4). */
 export interface CmsWriteOpts {
     /** Optimistic CAS: sent as `If-Match: <version>`; mismatch → 409 version_conflict. */
     ifVersion?: number;
     /** Bounded field precondition checked against the locked row (≤4 terms;
      *  `{field: null}` = "absent or null" — the slot-claim shape). 409 precondition_failed. */
     if?: Record<string, unknown>;
-    /** Per-(tenant,collection,key) advisory lock — serializes same-key writers. */
+    /** A per-(project, collection, key) lock — serializes same-key writers. */
     lock?: string;
     /** Declarative capacity/overlap invariant; requires `lock`. 409 guard_failed.
      *  Mutually exclusive with `guards`. */
     guard?: CmsGuard;
     /** Multiple capacity/overlap invariants evaluated co-atomically under the ONE
-     *  `lock` (≤4; requires `lock`; cms.md §10). Mutually exclusive with `guard`.
+     *  `lock` (≤4; requires `lock`; guide ch. 4). Mutually exclusive with `guard`.
      *  The FIRST failing guard's optional `message` rides the 409 guard_failed. */
     guards?: CmsGuardTerm[];
 }
@@ -2062,7 +2068,7 @@ export interface CmsWindow {
     since?: string;
     until?: string;
 }
-/** cms-rel B2: the aggregate request body (cms.md §12.1). */
+/** the aggregate request body (guide ch. 4). */
 export interface CmsAggregateBody {
     /** 1–4 exprs; fn ∈ count|sum|min|max|avg (sum/avg need an n*-slot field). */
     aggregates: Array<{
@@ -2080,7 +2086,7 @@ export interface CmsAggregateBody {
     /** group rows returned; clamped to 500. */
     limit?: number;
 }
-/** cms-rel B3: the rank request body (cms.md §12.2). */
+/** the rank request body (guide ch. 4). */
 export interface CmsRankBody {
     /** REQUIRED: the ranked entity — a slot-bound own field (often a relation). */
     groupBy: string;
@@ -2097,7 +2103,7 @@ export interface CmsRankBody {
     window?: CmsWindow;
     limit?: number;
 }
-/** cms-rel B4: one transaction step (cms.md §13). `$where` = the bounded CAS
+/** one transaction step (guide ch. 4). `$where` = the bounded CAS
  *  precondition (the PATCH `if` grammar: ≤4 terms, scalar / null /
  *  {$eq $ne $gt $gte $lt $lte $in}). */
 export type CmsTxStep = {
@@ -2117,7 +2123,7 @@ export type CmsTxStep = {
     item_id: string;
     $where?: Record<string, unknown>;
 };
-/** One op of `vx.cms.batch` (cms.md §21) — the single route's own body keys,
+/** One op of `vx.cms.batch` (guide ch. 4) — the single route's own body keys,
  *  typed by op. `ref` is an opaque tag echoed on the matching result. */
 export type CmsBatchOp = {
     op: 'get';
@@ -2216,7 +2222,7 @@ export interface CmsBatchResponse<T extends readonly CmsBatchOp[]> {
     };
 }
 /** 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. */
+ *  of a stored relation id (guide ch. 4). `R` is the target collection's Row. */
 export interface CmsItemEnvelope<R> {
     item_id: string;
     collection: string;
@@ -2232,7 +2238,7 @@ export interface CmsFileRef {
     object_id: string;
     $ref: 'files';
 }
-/** Every shape an expanded member can take (cms.md §6.2, all four verified in
+/** Every shape an expanded member can take (guide ch. 4, 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
@@ -2276,7 +2282,7 @@ export interface CollectionClient<C extends VxilSchemaShape['cms'][string], S ex
         version: number;
         data: C['Row'];
     }>;
-    /** `expand` inlines the named relation/file fields (cms.md §6.2) — the names
+    /** `expand` inlines the named relation/file fields (guide ch. 4) — 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`. */
@@ -2311,12 +2317,12 @@ export interface CollectionClient<C extends VxilSchemaShape['cms'][string], S ex
         items: C['Row'][];
         next_cursor: string | null;
     }>;
-    /** `SELECT count(*)` under the same bounded filter grammar (cms.md §9.4).
+    /** `SELECT count(*)` under the same bounded filter grammar (guide ch. 4).
      *  Refused (422) on collections with beforeRead visibility hooks. */
     count(filter?: Partial<C['Filterable']>): Promise<number>;
     patch(itemId: string, data: C['Patch'], opts?: CmsWriteOpts): Promise<C['Row']>;
     /** Atomic in-database increment — ONE conditional UPDATE; never
-     *  read-modify-write (cms.md §9.3). Delta keys are the numeric Row fields. */
+     *  read-modify-write (guide ch. 4). Delta keys are the numeric Row fields. */
     inc(itemId: string, incs: Partial<Record<NumericKeys<C['Row']> & string, number>>, opts?: Pick<CmsWriteOpts, 'ifVersion' | 'if'>): Promise<C['Row']>;
     delete(itemId: string, opts?: Pick<CmsWriteOpts, 'ifVersion'>): Promise<{
         item_id: string;
@@ -2324,7 +2330,7 @@ export interface CollectionClient<C extends VxilSchemaShape['cms'][string], S ex
         cascaded: number;
         set_null: number;
     }>;
-    /** cms.md §20: bounded filtered delete over the generated `Filterable` — a
+    /** Bounded filtered delete over the generated `Filterable` — a
      *  filter is required, ≤100 rows per call, `dryRun` previews. Loop while
      *  `deleted > 0`. */
     deleteMany(q: {
@@ -2334,7 +2340,7 @@ export interface CollectionClient<C extends VxilSchemaShape['cms'][string], S ex
         dryRun?: boolean;
     }): Promise<CmsBulkDeleteResult>;
     publish(itemId: string): Promise<C['Row']>;
-    /** cms-rel B2: bounded group-by aggregate (spec §7 `groupBy()` surface).
+    /** Bounded group-by aggregate (guide ch. 4).
      *  groupBy/field names are typed over the Row's keys; slot-existence stays a
      *  runtime check — exactly like `query`. Joins stay expressed as dotted
      *  filter keys (no `.join()` builder — one grammar, not two). */
@@ -2351,7 +2357,7 @@ export interface CollectionClient<C extends VxilSchemaShape['cms'][string], S ex
         }>;
         scanned: number;
     }>;
-    /** cms-rel B3: window ranking over the aggregate. */
+    /** Window ranking over the aggregate (guide ch. 4). */
     rank(q: Omit<CmsRankBody, 'groupBy' | 'partitionBy' | 'metric'> & {
         groupBy: keyof C['Row'] & string;
         partitionBy?: keyof C['Row'] & string;
@@ -2407,12 +2413,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
      *  `Vxil.connect<VxilSchema>({ apiKey }).rag` won't type-check if `rag` is off.
      *  Runtime is identical to `new Vxil`; this only adds the compile-time gate. */
     static connect<S extends VxilSchemaShape = VxilSchemaShape>(opts: VxilOptions): EnabledVxil<S>;
-    /** Typed per-collection CMS handle (design §4.8). A thin wrapper over the
+    /** Typed per-collection CMS handle (guide ch. 5). A thin wrapper over the
      *  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], S>;
-    /** Typed function invoke (design §4.5). `vx.fn.<name>(payload)` POSTs to
+    /** Typed function invoke (guide ch. 8). `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
      *  `vx.fn.<name>` accessor shape without enumerating names at runtime.
@@ -2451,7 +2457,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          * (email/display_name/avatar_url/attributes) is scrubbed, while the id is
          * kept so cross-feature references stay intact. NOTE: a full account-delete
          * flow also calls the auth half — POST /v1/auth/users/:id/erase — to erase
-         * the credential/session identity (see features/tenant-users.md §3).
+         * the credential/session identity (see guide ch. 6, auth).
          */
         delete: (id: string, opts?: {
             erase?: boolean;
@@ -2488,7 +2494,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
     readonly notifications: {
         send: (input: {
             user_id: string;
-            /** The four shipped template ids (notifications.md §7). */
+            /** The four shipped template ids (guide ch. 6, notifications). */
             template: "magic-link" | "otp-code" | "welcome" | "transactional";
             data: Record<string, unknown>;
             /** Explicit wins; otherwise the recipient's stored `locale` attribute
@@ -2584,7 +2590,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             user_id?: string;
             status?: string;
             limit?: number;
-            /** A7: only deliveries that reached this engagement state */
+            /** only deliveries that reached this engagement state */
             engagement?: "delivered" | "opened" | "clicked";
         }) => Promise<Delivery[]>;
         suppressions: {
@@ -2637,7 +2643,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          *  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.)
+         *  muteable — see guide ch. 6, notifications.)
          *
          *  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
@@ -2681,7 +2687,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         };
         /** A single delivery by id (the list is `deliveries()`). */
         delivery: (deliveryId: string) => Promise<Delivery>;
-        /** Email broadcast campaigns (notifications.md §11b): audience-ref fan-out
+        /** Email broadcast campaigns (guide ch. 6, notifications): audience-ref fan-out
          *  with quiet-hours + frequency-cap policy. `schedule_cron` sets a recurring
          *  send (status `scheduled`); omit it for a `draft`. */
         campaigns: {
@@ -2748,12 +2754,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         /** The tenant's enabled-feature summary (GET /v1/features). Privilege-
          * independent: any valid key may read it — it leaks no secrets, only which
          * features the tenant has turned on. Mirrors what the MCP tool-list
-         * aggregation sees. (audit #113) */
+         * aggregation sees. */
         list: () => Promise<string[]>;
         /** The FULL enabled-feature summary: `features` + `api_versions` (released
          * API majors per feature) + the additive `key` block — the CALLING key's
          * identity and per-tool MCP permissions (allowed_tools/denied_tools
-         * patterns, api_keys 0057; mcp.md §6.7). `key` is absent for non-key
+         * patterns; guide ch. 10). `key` is absent for non-key
          * callers and for keys without explicit tool perms. `list()` stays the
          * stable flat-array shorthand. */
         summary: () => Promise<{
@@ -2859,7 +2865,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             }>;
             count: number;
         }>;
-        /** Enqueue a long-running EXTERNAL generation run (jobs.md §11): Vxil calls
+        /** Enqueue a long-running EXTERNAL generation run (guide ch. 6, jobs): Vxil calls
          * the provider (BYO key), tracks completion via poll/webhook, mirrors a typed
          * generation_status onto a tenant record, enforces a built-in timeout, and
          * (on failure) fires the payments credit-reversal.
@@ -2868,7 +2874,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          * of the same `idempotency_key` (`deduplicated: true`) carries the run's
          * status NOW (`processing`, `completed` or `failed` too).
          *
-         * `reserve_credits` (§11.8) takes a PROVISIONAL held credit debit at enqueue
+         * `reserve_credits` takes a PROVISIONAL held credit debit at enqueue
          * (linked to the run), committed on `completed` and reversed on
          * failed/timeout/DLQ. `amount` is positive-only and CLAMPED to the platform
          * `config.generation.maxReserveCredits` cap; in end-user mode `user_id` is
@@ -3425,9 +3431,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         createPolicy: (input: {
             name: string;
             key_template: string;
-            /** omitted ⇒ seeded from the tenant's rate-limits config `defaults` (F8-54) */
+            /** omitted ⇒ seeded from the tenant's rate-limits config `defaults` */
             limit?: number;
-            /** omitted ⇒ seeded from the tenant's rate-limits config `defaults` (F8-54) */
+            /** omitted ⇒ seeded from the tenant's rate-limits config `defaults` */
             window_seconds?: number;
             behavior?: "block" | "shape";
         }) => Promise<RateLimitPolicy>;
@@ -3501,7 +3507,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         }>;
         /** Per-identifier overrides layered over a policy: `pattern` matches the
          *  RENDERED key (exact, or a `*`-glob where the longest literal prefix
-         *  wins). Propagates to the check path within ≤30s (KV cacheTtl). */
+         *  wins). Propagates to the check path within ≤30s (cache TTL). */
         overrides: {
             list: (policyId: string) => Promise<RateLimitOverride[]>;
             create: (policyId: string, input: {
@@ -3533,7 +3539,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                  *  end-user principal (default-deny) in end-user mode; a no-op in
                  *  server-caller mode. Omit for shared/reference collections. */
                 owner_field?: string;
-                /** Public delivery (roadmap §4.4): when true, this collection's PUBLISHED
+                /** Public delivery (guide ch. 4): when true, this collection's PUBLISHED
                  *  items become KEYLESS-readable through the anonymous public lane —
                  *  `GET {base}/v1/cms/public/:tenantId/:collection` with NO api key. Drafts
                  *  and the owner_field are never exposed. Optional; defaults false. Use the
@@ -3551,15 +3557,15 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                     };
                     index_slot?: "s1" | "s2" | "s3" | "s4" | "n1" | "n2" | "t1" | "t2";
                     relation_to?: string;
-                    /** Value uniqueness across the collection's LIVE items (cms.md §9.3);
+                    /** Value uniqueness across the collection's LIVE items (guide ch. 4);
                      *  scalar-valued types only. Concurrent duplicates → 409 unique_violation. */
                     unique?: boolean;
                     /** relation fields only: what a delete of the referenced item does to
-                     *  this one — cascade / set_null (bounded fan-out, cms.md §11) or
-                     *  `restrict` (§11.1: the delete is refused with 409 `referenced`
+                     *  this one — cascade / set_null (bounded fan-out, guide ch. 4) or
+                     *  `restrict` (the delete is refused with 409 `referenced`
                      *  while a live reference exists). */
                     on_delete?: "cascade" | "set_null" | "restrict";
-                    /** FIELD-LEVEL read security (cms.md §18): the end-user ORG ROLE slugs
+                    /** FIELD-LEVEL read security (guide ch. 4): the end-user ORG ROLE slugs
                      *  allowed to READ this field. Omitted/`[]` = ungated. A non-empty list
                      *  is FAIL-SAFE — in verified end-user mode the field is OMITTED from
                      *  every read (get / list / query / `$expand` / the write-response echo)
@@ -3569,8 +3575,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                      *  session) still sees every field. Writes are unaffected. ≤16 entries,
                      *  each `^[a-z0-9][a-z0-9_-]{0,31}$` (the `orgs` role alphabet). */
                     read_roles?: string[];
+                    /** Equality index for an UNSLOTTED field (guide ch. 4 "Indexed
+                     *  equality"): `=` / `$eq` / `$in` filters on it are index-served
+                     *  instead of a bounded scan — results are identical either way. ≤4
+                     *  per collection; not with `index_slot` (a slot already indexes
+                     *  equality) and not on a computed field. */
+                    indexed?: boolean;
                 }>;
-                /** Per-record action buttons (cms.md §17): `[{ key, label, fn }]` —
+                /** Per-record action buttons (guide ch. 4): `[{ key, label, fn }]` —
                  *  exactly ONE human-initiated step each; `fn` names a deployed tenant
                  *  function invoked by `items.runAction`. ≤8 per collection. */
                 actions?: CmsActionDef[];
@@ -3588,7 +3600,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 owner_field?: string | null;
             }>>;
             addField: (collection: string, field: Record<string, unknown>) => Promise<void>;
-            /** Set (or clear, with `null`/`[]`) a field's READ-ROLE gate (cms.md §18) —
+            /** Set (or clear, with `null`/`[]`) a field's READ-ROLE gate (guide ch. 4) —
              *  the same-type in-place alter on the fields route. Re-sends the field's
              *  `type` (required by the alter path); every OTHER attribute the field
              *  carries is re-sent from `rest`, because the alter overwrites the whole
@@ -3596,17 +3608,29 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
              *  read unless the session's verified roles intersect `roles`; server-caller
              *  reads and ALL writes are unaffected. */
             setFieldReadRoles: (collection: string, field: string, type: "string" | "text" | "int" | "float" | "bool" | "datetime" | "json" | "relation" | "file", roles: string[] | null, rest?: Record<string, unknown>) => Promise<void>;
+            /** Turn a field's EQUALITY INDEX on or off (guide ch. 4 "Indexed equality")
+             *  — the same-type in-place alter on the fields route; `indexed` is
+             *  present-key, so no other attribute moves. Only for UNSLOTTED,
+             *  non-computed fields, ≤4 per collection (422 `eq_index_budget`).
+             *  `index_ready: false` + `reindex_required: true` on a collection over
+             *  2,000 live items: run `reindexAll` (until then filters stay on the
+             *  bounded scan — never wrong, only slower). */
+            setFieldIndexed: (collection: string, field: string, type: "string" | "text" | "int" | "float" | "bool" | "datetime" | "json" | "relation" | "file", indexed: boolean) => Promise<{
+                indexed: boolean;
+                index_ready: boolean;
+                reindex_required: boolean;
+            }>;
             /** Set (or clear, with `null`) the collection's end-user owner-scope flag
-             *  (design §5.1). Names an existing `string` field that holds the owner id. */
+             *  (guide ch. 4, "`ownerField`"). Names an existing `string` field that holds the owner id. */
             setOwnerField: (collection: string, ownerField: string | null) => Promise<void>;
-            /** Toggle the collection's PUBLIC-delivery flag (roadmap §4.4). When `true`,
+            /** Toggle the collection's PUBLIC-delivery flag (guide ch. 4). When `true`,
              *  its PUBLISHED items become KEYLESS-readable via the anonymous public lane
              *  (`GET {base}/v1/cms/public/:tenantId/:collection` — no api key); drafts and
              *  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,
+             *  (guide ch. 4). 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
@@ -3633,16 +3657,17 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 updated: number;
                 skipped: number;
                 pages: number;
+                index_certify?: CmsReindexPage["index_certify"];
             }>;
-            /** Replace the collection's per-record ACTION list (cms.md §17) — the
+            /** Replace the collection's per-record ACTION list (guide ch. 4) — the
              *  `{ actions }` fields-route meta-op; `[]` clears. Each action is ONE
              *  human-initiated step: the dashboard renders it as a button per record,
              *  and `items.runAction` invokes its deployed function. */
             setActions: (collection: string, actions: CmsActionDef[]) => Promise<void>;
         };
         items: {
-            /** `lock` serializes same-key writers (per-tenant advisory lock); `guard`
-             *  is the declarative capacity/overlap invariant (requires lock) — cms.md §10. */
+            /** `lock` serializes same-key writers (a per-key lock); `guard`
+             *  is the declarative capacity/overlap invariant (requires lock) — guide ch. 4. */
             create: (collection: string, input: {
                 data: Record<string, unknown>;
                 status?: "draft" | "published";
@@ -3655,7 +3680,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 version: number;
                 data: Record<string, unknown>;
             }>;
-            /** `expand` inlines relation/file fields into `data` (cms.md §6.2): the
+            /** `expand` inlines relation/file fields into `data` (guide ch. 4): 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?: {
@@ -3689,19 +3714,19 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 items: Array<Record<string, unknown>>;
                 next_cursor: string | null;
             }>;
-            /** Merge-patch data keys; null clears a key. Concurrency opts (cms.md §9):
+            /** Merge-patch data keys; null clears a key. Concurrency opts (guide ch. 4):
              *  `ifVersion` → If-Match CAS; `if` → bounded field precondition against
-             *  the locked row; `lock`/`guard` → the §10 serialization primitives. */
+             *  the locked row; `lock`/`guard` → the write-serialization primitives (guide ch. 4). */
             patch: (collection: string, itemId: string, data: Record<string, unknown>, opts?: CmsWriteOpts) => Promise<Record<string, unknown>>;
             /** Atomic in-database increment — PATCH `{ $inc: {field: delta} }`, ONE
              *  conditional UPDATE guarded by the field's validation min/max (the quota
              *  shape), the optional `if` precondition, and If-Match. 409
-             *  inc_out_of_bounds when the guard refuses (cms.md §9.3). */
+             *  inc_out_of_bounds when the guard refuses (guide ch. 4). */
             inc: (collection: string, itemId: string, incs: Record<string, number>, opts?: Pick<CmsWriteOpts, "ifVersion" | "if">) => Promise<Record<string, unknown>>;
-            /** `{ count }` under the same bounded filter grammar (cms.md §9.4). 422
+            /** `{ count }` under the same bounded filter grammar (guide ch. 4). 422
              *  count_unavailable_with_read_hooks on beforeRead-hooked collections. */
             count: (collection: string, filter?: Record<string, unknown>) => Promise<number>;
-            /** Returns the cascade tally (cms.md §11); `ifVersion` rides If-Match and
+            /** Returns the cascade tally (guide ch. 4); `ifVersion` rides If-Match and
              *  a conflict aborts BEFORE any cascade side-effect. */
             delete: (collection: string, itemId: string, opts?: Pick<CmsWriteOpts, "ifVersion">) => Promise<{
                 item_id: string;
@@ -3709,7 +3734,7 @@ 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`
+            /** 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,
@@ -3729,7 +3754,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 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
+            /** The BOUNDED reverse read — which live items
              *  reference this one, through which relation field. Owner-scoped in
              *  end-user mode like `get`. `count` is the page returned (≤ limit, max
              *  100), never a total; `has_more` says the cap was hit. A DELETE refused
@@ -3738,7 +3763,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             backlinks: (collection: string, itemId: string, opts?: {
                 limit?: number;
             }) => Promise<CmsBacklinksPage>;
-            /** P1-7 (cms.md §17): run ONE declared per-record action — invokes the
+            /** Run ONE declared per-record action — invokes the
              *  action's deployed function with `{ collection, item_id, action, actor,
              *  item }` and returns its result. 404 when the key is not declared;
              *  502 `action_failed` (with `upstream.code` = the function's error
@@ -3750,7 +3775,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 fn: string;
                 result: unknown;
             }>;
-            /** cms-rel B2 (cms.md §12): bounded group-by aggregate. fns count|sum|
+            /** Bounded group-by aggregate. fns count|sum|
              *  min|max|avg over index-slot-bound fields; groupBy ≤2 slot-bound
              *  fields; filter = the full query DSL incl. ONE-hop dotted join terms
              *  ({"channel.visibility":"public"}); scan capped at 50k rows → 422
@@ -3761,7 +3786,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 }>;
                 scanned: number;
             }>;
-            /** cms-rel B3 (cms.md §12): window ranking over the aggregate — rank ∈
+            /** Window ranking over the aggregate — rank ∈
              *  row_number|rank|percent_rank, computed over ≤500 aggregated groups
              *  (never raw rows), optional partitionBy. Same scan cap as aggregate. */
             rank: (collection: string, body: CmsRankBody) => Promise<{
@@ -3789,7 +3814,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 done: boolean;
             }>;
         };
-        /** cms-rel B4 (cms.md §13): atomic multi-collection transaction — 1–5
+        /** Atomic multi-collection transaction — 1–5
          *  steps over ≤3 collections, per-step `$where` CAS preconditions (the
          *  PATCH `if` grammar). All-or-nothing: any failed precondition/validation
          *  rolls the WHOLE transaction back (409 precondition_failed names the
@@ -3805,7 +3830,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             committed: boolean;
             tx_id: string;
         }>;
-        /** P1-1 (cms.md §21): several get / query / create / patch / delete ops in
+        /** Several get / query / create / patch / delete ops in
          *  ONE round trip — the function-chain shape ("read 3 rows → patch 2 →
          *  create 1" is one call, not six). ≤25 ops, each run through the SAME path
          *  its single route uses (scopes, owner-scoping, hooks, guards, `if`,
@@ -3819,7 +3844,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         batch: <T extends readonly CmsBatchOp[]>(ops: readonly [...T], opts?: {
             atomic?: boolean;
         }) => Promise<CmsBatchResponse<T>>;
-        /** cms-rel B5 (cms.md §12.4): declared read-models (config `readModels`
+        /** Declared read-models (config `readModels`
          *  bag) — list with last-run status, and "run now" materialization into
          *  the rollup collection. */
         readModels: {
@@ -3924,7 +3949,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         /** Read the resolved DM config (defaults merged with the stored partial). */
         getConfig: () => Promise<DmConfigState>;
         /** Write the DM master config — a partial merge (omitted leaves keep their
-         *  current value), version-bumped and republished to the gate's KV key. */
+         *  current value), version-bumped and republished to the gate's cache. */
         setConfig: (patch: {
             enabled?: boolean;
             maxParticipants?: number;
@@ -4057,7 +4082,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
     /** The MCP aggregation surface (the `mcp` feature). */
     readonly mcp: {
         /** Per-tenant secret for verifying the X-Vxil-Mcp-Signature header on custom
-         *  MCP tool calls (mcp.md §6.5) — the mirror of jobs.signingSecret(). */
+         *  MCP tool calls (guide ch. 10) — the mirror of jobs.signingSecret(). */
         signingSecret: () => Promise<string>;
     };
     /**
@@ -4154,7 +4179,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 ids?: string[];
                 before?: string;
             }) => Promise<FeedBadge>;
-            /** The badge: { unseen, unread, total } (KV-cached over the authority). */
+            /** The badge: { unseen, unread, total } (cached, recomputed on a miss). */
             unreadCount: (userId: string) => Promise<FeedBadge>;
         };
         /**
@@ -4269,7 +4294,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 ids?: string[];
                 before?: string;
             }) => Promise<FeedBadge>;
-            /** The badge: { unseen, unread, total } (KV-cached over the authority). */
+            /** The badge: { unseen, unread, total } (cached, recomputed on a miss). */
             unreadCount: (userId: string) => Promise<FeedBadge>;
         };
         /**
@@ -4520,7 +4545,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 pending?: boolean;
             }>>;
         };
-        /** Custom tenant roles (permission-sets; migration orgs/0019). A custom role
+        /** Custom tenant roles (permission-sets). A custom role
          *  is a named set of permissions assignable like any built-in; the four
          *  built-ins reproduce the fixed owner>admin>member>viewer lattice. */
         roles: {
@@ -4554,7 +4579,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             /** Delete a custom role (built-in roles cannot be deleted). */
             delete: (roleKey: string) => Promise<void>;
         };
-        /** Per-org/user resource ACL grants (migration orgs/0019): grant a permission
+        /** Per-org/user resource ACL grants: grant a permission
          *  on a specific resource string; `check(...,{ resource })` consults them. */
         acl: {
             grant: (orgId: string, input: {
@@ -4696,7 +4721,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             };
             available: Record<string, number | null>;
         }>;
-        /** OCR / text extraction (files.md §1.1, BYO-key add-on). Small/mock inputs
+        /** OCR / text extraction (guide ch. 6, files, BYO-key add-on). Small/mock inputs
          *  extract inline (status `available`); large inputs (or `async:true`) return
          *  202 with a `job_id` — poll `getText()`. */
         extractText: (objectId: string, opts?: {
@@ -4850,7 +4875,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
      * The AI substrate (the `ai` feature): store prompt TEMPLATES (config-as-code),
      * then generate (sync or streamed) and embed across providers. 'mock' is the
      * deterministic default; the real providers (openai/anthropic/gemini/azure/
-     * openrouter) route via BYO keys in tenant_secrets. `images` on the generate
+     * openrouter) route via BYO keys in your project secrets. `images` on the generate
      * inputs takes up to 8 vision refs: a public https:// URL, a
      * data:image/...;base64 URL, or file:<object_id> (a files-feature object) —
      * fetched images are capped at 4 MiB each; `documents` (pdf/text, ≤10 MiB
@@ -5062,7 +5087,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          *  outlives the ≤300s realtime token TTL); reconnect with `?since=<seq>`. */
         remintToken: (generationId: string) => Promise<AiStreamToken>;
         /** Resume a streamed generation after a dropped socket: every recorded frame
-         *  with seq > `since` plus `done` (the §2a replay buffer — plain JSON, not
+         *  with seq > `since` plus `done` (the replay buffer — plain JSON, not
          *  an SSE stream; the buffer lives 1 h). A settled JOB-lane generation is
          *  served from its stored answer instead (30 days). `status` says where the
          *  generation is; `expired: true` means it settled but its frames are gone
@@ -5159,7 +5184,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             user_id?: string;
             input?: Record<string, unknown>;
         }) => Promise<RagStreamHandle>;
-        /** Retrieval-only grounding preview (rag.md §1c): the exact chunks `answer`
+        /** Retrieval-only grounding preview (guide ch. 6, rag): the exact chunks `answer`
          *  would ground on, with rerank + metadata boosts applied — no generation,
          *  no token spend. `boosts`/`rerank`/`min_score` override the rag config.
          *  `min_score` floors the EFFECTIVE `score`, which is a RANK value (about
@@ -5287,7 +5312,7 @@ 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 (guide ch. 6, payments).
          *
          *  OVERLAPPING SUBSCRIPTIONS — what `until` means. The WINNER is the
          *  entitled subscription with the highest `tierMap[tier].rank` (default 0);
@@ -5431,7 +5456,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             status?: string;
         }) => Promise<PaymentsSubscription[]>;
         /**
-         * Create a hosted-checkout session (payments.md §3). Redirect the buyer to
+         * Create a hosted-checkout session (guide ch. 6, payments). Redirect the buyer to
          * the returned `url`; completion lands server-side via the provider webhook
          * (the matching session flips to completed, the charge/grant is folded).
          * Idempotency-Key REQUIRED — a retry replays the SAME session verbatim.
@@ -5455,7 +5480,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             url: string;
         }>;
         /**
-         * Refund a charge at-most-once (payments.md §6a). Omit `amount_cents` to
+         * Refund a charge at-most-once (guide ch. 6, payments). Omit `amount_cents` to
          * 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).
@@ -5652,7 +5677,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         }) => Promise<{
             refunds: PaymentsRefund[];
         }>;
-        /** Provider webhook event log (payments.md §7 "Event log & replay"):
+        /** Provider webhook event log (guide ch. 6, payments "Event log & replay"):
          *  operator visibility over every delivery — incl. persisted signature
          *  failures — plus an idempotent reprocess verb. Needs payments:read
          *  (reprocess: payments:write).

package/dist/index.js

@@ -3,7 +3,7 @@
 // (code/message/hint/fixUrl + request id) so callers — humans or agents —
 // can self-correct.
 /** The released API majors, as a CLOSED union — one per released major (docs/
- *  feature-versioning.md §3). `'v1'` is the only released major, so pinning
+ *  guide ch. 5). `'v1'` is the only released major, so pinning
  *  anything else (`apiVersion: 'v2'`) is a COMPILE error until a v2 GAs and
  *  widens this union. Every path the SDK builds is major-versioned; the default
  *  is the compile-time constant `'v1'` (never a floating `latest` alias). */
@@ -136,7 +136,7 @@ function resolveBase(explicit) {
     return (explicit ?? envBase ?? DEFAULT_BASE).replace(/\/$/, '');
 }
 /** Build the anonymous, KEYLESS public-delivery URL for a collection's PUBLISHED
- *  items (roadmap §4.4) — `{base}/v1/cms/public/:tenantId/:collection[?…]`. This is
+ *  items (guide ch. 4, "Draft and publish") — `{base}/v1/cms/public/:tenantId/:collection[?…]`. This is
  *  the reader path a public blog/storefront/docs site hits with NO api key: the
  *  edge mints a restricted read-only inner token bound to the URL tenant, forces
  *  `status='published'`, and strips the collection's owner_field. PURE (no
@@ -155,7 +155,7 @@ export function cmsPublicUrl(tenantId, collection, query, opts) {
     return `${base}${path}${s}`;
 }
 /** Fetch a page of a collection's PUBLISHED items over the KEYLESS public lane
- *  (roadmap §4.4) — NO api key, no `Vxil` client, no auth of any kind. This is the
+ *  (guide ch. 4) — NO api key, no `Vxil` client, no auth of any kind. This is the
  *  anonymous reader path (a blog/storefront/docs front-end). Returns the same
  *  `{ items, next_cursor }` envelope the authed list does, but rows are stripped
  *  to the public surface (`CmsPublicRow`) — drafts and the owner_field are never
@@ -254,7 +254,7 @@ export class Vxil {
     static connect(opts) {
         return new Vxil(opts);
     }
-    /** Typed per-collection CMS handle (design §4.8). A thin wrapper over the
+    /** Typed per-collection CMS handle (guide ch. 5). A thin wrapper over the
      *  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. */
@@ -291,7 +291,7 @@ export class Vxil {
             rank: (q) => this.cms.items.rank(c, q),
         };
     }
-    /** Typed function invoke (design §4.5). `vx.fn.<name>(payload)` POSTs to
+    /** Typed function invoke (guide ch. 8). `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
      *  `vx.fn.<name>` accessor shape without enumerating names at runtime.
@@ -359,7 +359,7 @@ export class Vxil {
         });
         // An empty body on a 2xx is a valid "no content" success (e.g. 204 from
         // DELETE/markRead) — never an error. Only parse when there are bytes; a
-        // void-returning caller ignores `data` anyway. (audit #115)
+        // void-returning caller ignores `data` anyway.
         let parsed = {};
         if (text.length > 0) {
             try {
@@ -395,7 +395,7 @@ export class Vxil {
          * (email/display_name/avatar_url/attributes) is scrubbed, while the id is
          * kept so cross-feature references stay intact. NOTE: a full account-delete
          * flow also calls the auth half — POST /v1/auth/users/:id/erase — to erase
-         * the credential/session identity (see features/tenant-users.md §3).
+         * the credential/session identity (see guide ch. 6, auth).
          */
         delete: async (id, opts) => {
             await this.call('DELETE', `/v1/users/${encodeURIComponent(id)}${opts?.erase ? '?erase=true' : ''}`);
@@ -497,7 +497,7 @@ export class Vxil {
          *  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.)
+         *  muteable — see guide ch. 6, notifications.)
          *
          *  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
@@ -524,7 +524,7 @@ export class Vxil {
         },
         /** A single delivery by id (the list is `deliveries()`). */
         delivery: async (deliveryId) => (await this.call('GET', `/v1/notifications/deliveries/${encodeURIComponent(deliveryId)}`)).data,
-        /** Email broadcast campaigns (notifications.md §11b): audience-ref fan-out
+        /** Email broadcast campaigns (guide ch. 6, notifications): audience-ref fan-out
          *  with quiet-hours + frequency-cap policy. `schedule_cron` sets a recurring
          *  send (status `scheduled`); omit it for a `draft`. */
         campaigns: {
@@ -557,12 +557,12 @@ export class Vxil {
         /** The tenant's enabled-feature summary (GET /v1/features). Privilege-
          * independent: any valid key may read it — it leaks no secrets, only which
          * features the tenant has turned on. Mirrors what the MCP tool-list
-         * aggregation sees. (audit #113) */
+         * aggregation sees. */
         list: async () => (await this.call('GET', '/v1/features')).data.features,
         /** The FULL enabled-feature summary: `features` + `api_versions` (released
          * API majors per feature) + the additive `key` block — the CALLING key's
          * identity and per-tool MCP permissions (allowed_tools/denied_tools
-         * patterns, api_keys 0057; mcp.md §6.7). `key` is absent for non-key
+         * patterns; guide ch. 10). `key` is absent for non-key
          * callers and for keys without explicit tool perms. `list()` stays the
          * stable flat-array shorthand. */
         summary: async () => (await this.call('GET', '/v1/features')).data,
@@ -610,7 +610,7 @@ export class Vxil {
             if (!res.ok) {
                 // Preserve the structured error envelope on failure — the export path
                 // is hand-rolled (no this.call), so without this a 403/429 would lose
-                // its code/hint/requestId. (audit #119)
+                // its code/hint/requestId.
                 let env = {};
                 try {
                     env = JSON.parse(text);
@@ -621,7 +621,7 @@ export class Vxil {
             }
             // Skip blank lines AND tolerate a single malformed NDJSON line rather
             // than aborting the whole batch (e.g. a truncated final line on a large
-            // page) — collect parse failures so the caller can decide. (audit #116)
+            // page) — collect parse failures so the caller can decide.
             const events = [];
             const parseErrors = [];
             text.split('\n').forEach((l, i) => {
@@ -657,7 +657,7 @@ export class Vxil {
          * batch). Each item = the enqueue input, incl. per-item idempotency_key
          * and deliver_after/delay_seconds. Results align with the input order. */
         enqueueBatch: async (items) => (await this.call('POST', '/v1/jobs/enqueue-batch', { jobs: items })).data,
-        /** Enqueue a long-running EXTERNAL generation run (jobs.md §11): Vxil calls
+        /** Enqueue a long-running EXTERNAL generation run (guide ch. 6, jobs): Vxil calls
          * the provider (BYO key), tracks completion via poll/webhook, mirrors a typed
          * generation_status onto a tenant record, enforces a built-in timeout, and
          * (on failure) fires the payments credit-reversal.
@@ -666,7 +666,7 @@ export class Vxil {
          * of the same `idempotency_key` (`deduplicated: true`) carries the run's
          * status NOW (`processing`, `completed` or `failed` too).
          *
-         * `reserve_credits` (§11.8) takes a PROVISIONAL held credit debit at enqueue
+         * `reserve_credits` takes a PROVISIONAL held credit debit at enqueue
          * (linked to the run), committed on `completed` and reversed on
          * failed/timeout/DLQ. `amount` is positive-only and CLAMPED to the platform
          * `config.generation.maxReserveCredits` cap; in end-user mode `user_id` is
@@ -1059,7 +1059,7 @@ export class Vxil {
         check: async (input) => (await this.call('POST', '/v1/rate-limits/check', input)).data,
         /** Per-identifier overrides layered over a policy: `pattern` matches the
          *  RENDERED key (exact, or a `*`-glob where the longest literal prefix
-         *  wins). Propagates to the check path within ≤30s (KV cacheTtl). */
+         *  wins). Propagates to the check path within ≤30s (cache TTL). */
         overrides: {
             list: async (policyId) => (await this.call('GET', `/v1/rate-limits/policies/${encodeURIComponent(policyId)}/overrides`)).data.overrides,
             create: async (policyId, input) => (await this.call('POST', `/v1/rate-limits/policies/${encodeURIComponent(policyId)}/overrides`, input)).data,
@@ -1078,7 +1078,7 @@ export class Vxil {
             addField: async (collection, field) => {
                 await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, field);
             },
-            /** Set (or clear, with `null`/`[]`) a field's READ-ROLE gate (cms.md §18) —
+            /** Set (or clear, with `null`/`[]`) a field's READ-ROLE gate (guide ch. 4) —
              *  the same-type in-place alter on the fields route. Re-sends the field's
              *  `type` (required by the alter path); every OTHER attribute the field
              *  carries is re-sent from `rest`, because the alter overwrites the whole
@@ -1088,12 +1088,35 @@ export class Vxil {
             setFieldReadRoles: async (collection, field, type, roles, rest = {}) => {
                 await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { ...rest, field, type, read_roles: roles ?? [] });
             },
+            /** Turn a field's EQUALITY INDEX on or off (guide ch. 4 "Indexed equality")
+             *  — the same-type in-place alter on the fields route; `indexed` is
+             *  present-key, so no other attribute moves. Only for UNSLOTTED,
+             *  non-computed fields, ≤4 per collection (422 `eq_index_budget`).
+             *  `index_ready: false` + `reindex_required: true` on a collection over
+             *  2,000 live items: run `reindexAll` (until then filters stay on the
+             *  bounded scan — never wrong, only slower). */
+            setFieldIndexed: async (collection, field, type, indexed) => {
+                try {
+                    const d = (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { field, type, indexed })).data ?? {};
+                    return { indexed: d.indexed ?? indexed, index_ready: d.index_ready ?? indexed, reindex_required: d.reindex_required === true };
+                }
+                catch (e) {
+                    // 409 already_exists = the field is already in that state (the
+                    // idempotent re-POST); read its readiness from the collection list.
+                    if (!(e instanceof VxilError) || e.status !== 409)
+                        throw e;
+                    const colls = (await this.call('GET', '/v1/cms/collections')).data.collections;
+                    const f = colls.find((c) => c.collection === collection)?.fields.find((x) => x.field === field);
+                    const ready = f?.index_ready === true;
+                    return { indexed: f?.indexed === true, index_ready: ready, reindex_required: f?.indexed === true && !ready };
+                }
+            },
             /** Set (or clear, with `null`) the collection's end-user owner-scope flag
-             *  (design §5.1). Names an existing `string` field that holds the owner id. */
+             *  (guide ch. 4, "`ownerField`"). Names an existing `string` field that holds the owner id. */
             setOwnerField: async (collection, ownerField) => {
                 await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { owner_field: ownerField });
             },
-            /** Toggle the collection's PUBLIC-delivery flag (roadmap §4.4). When `true`,
+            /** Toggle the collection's PUBLIC-delivery flag (guide ch. 4). When `true`,
              *  its PUBLISHED items become KEYLESS-readable via the anonymous public lane
              *  (`GET {base}/v1/cms/public/:tenantId/:collection` — no api key); drafts and
              *  the owner_field are never exposed. `false` closes the lane (and purges the
@@ -1102,7 +1125,7 @@ export class Vxil {
                 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,
+             *  (guide ch. 4). 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
@@ -1126,6 +1149,7 @@ export class Vxil {
                 let updated = 0;
                 let skipped = 0;
                 let pages = 0;
+                let indexCertify;
                 for (;;) {
                     let page = await this.cms.collections.reindex(collection, {
                         ...(opts?.field ? { field: opts.field } : {}),
@@ -1148,13 +1172,15 @@ export class Vxil {
                         opts?.onPage?.(page);
                     }
                     skipped += page.skipped ?? 0;
+                    if (page.index_certify)
+                        indexCertify = page.index_certify;
                     if (page.complete || !page.next_cursor)
                         break;
                     cursor = page.next_cursor;
                 }
-                return { scanned, updated, skipped, pages };
+                return { scanned, updated, skipped, pages, ...(indexCertify ? { index_certify: indexCertify } : {}) };
             },
-            /** Replace the collection's per-record ACTION list (cms.md §17) — the
+            /** Replace the collection's per-record ACTION list (guide ch. 4) — the
              *  `{ actions }` fields-route meta-op; `[]` clears. Each action is ONE
              *  human-initiated step: the dashboard renders it as a button per record,
              *  and `items.runAction` invokes its deployed function. */
@@ -1163,10 +1189,10 @@ export class Vxil {
             },
         },
         items: {
-            /** `lock` serializes same-key writers (per-tenant advisory lock); `guard`
-             *  is the declarative capacity/overlap invariant (requires lock) — cms.md §10. */
+            /** `lock` serializes same-key writers (a per-key lock); `guard`
+             *  is the declarative capacity/overlap invariant (requires lock) — guide ch. 4. */
             create: async (collection, input) => (await this.call('POST', `/v1/cms/items/${encodeURIComponent(collection)}`, input)).data,
-            /** `expand` inlines relation/file fields into `data` (cms.md §6.2): the
+            /** `expand` inlines relation/file fields into `data` (guide ch. 4): 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) => {
@@ -1198,9 +1224,9 @@ export class Vxil {
                 });
                 return (await this.call('GET', `/v1/cms/items/${encodeURIComponent(collection)}${s}`)).data;
             },
-            /** Merge-patch data keys; null clears a key. Concurrency opts (cms.md §9):
+            /** Merge-patch data keys; null clears a key. Concurrency opts (guide ch. 4):
              *  `ifVersion` → If-Match CAS; `if` → bounded field precondition against
-             *  the locked row; `lock`/`guard` → the §10 serialization primitives. */
+             *  the locked row; `lock`/`guard` → the write-serialization primitives (guide ch. 4). */
             patch: async (collection, itemId, data, opts) => (await this.call('PATCH', `/v1/cms/items/${encodeURIComponent(collection)}/${encodeURIComponent(itemId)}`, {
                 data,
                 ...(opts?.if ? { if: opts.if } : {}),
@@ -1211,18 +1237,18 @@ export class Vxil {
             /** Atomic in-database increment — PATCH `{ $inc: {field: delta} }`, ONE
              *  conditional UPDATE guarded by the field's validation min/max (the quota
              *  shape), the optional `if` precondition, and If-Match. 409
-             *  inc_out_of_bounds when the guard refuses (cms.md §9.3). */
+             *  inc_out_of_bounds when the guard refuses (guide ch. 4). */
             inc: async (collection, itemId, incs, opts) => (await this.call('PATCH', `/v1/cms/items/${encodeURIComponent(collection)}/${encodeURIComponent(itemId)}`, { $inc: incs, ...(opts?.if ? { if: opts.if } : {}) }, opts?.ifVersion !== undefined ? { 'if-match': String(opts.ifVersion) } : {})).data,
-            /** `{ count }` under the same bounded filter grammar (cms.md §9.4). 422
+            /** `{ count }` under the same bounded filter grammar (guide ch. 4). 422
              *  count_unavailable_with_read_hooks on beforeRead-hooked collections. */
             count: async (collection, filter) => {
                 const s = qs({ count: 'true', filter: filter ? JSON.stringify(filter) : undefined });
                 return (await this.call('GET', `/v1/cms/items/${encodeURIComponent(collection)}${s}`)).data.count;
             },
-            /** Returns the cascade tally (cms.md §11); `ifVersion` rides If-Match and
+            /** Returns the cascade tally (guide ch. 4); `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`
+            /** 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,
@@ -1242,7 +1268,7 @@ export class Vxil {
                 ...(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
+            /** The BOUNDED reverse read — which live items
              *  reference this one, through which relation field. Owner-scoped in
              *  end-user mode like `get`. `count` is the page returned (≤ limit, max
              *  100), never a total; `has_more` says the cap was hit. A DELETE refused
@@ -1252,19 +1278,19 @@ export class Vxil {
                 const qs = opts?.limit !== undefined ? `?limit=${encodeURIComponent(String(opts.limit))}` : '';
                 return (await this.call('GET', `/v1/cms/items/${encodeURIComponent(collection)}/${encodeURIComponent(itemId)}/backlinks${qs}`)).data;
             },
-            /** P1-7 (cms.md §17): run ONE declared per-record action — invokes the
+            /** Run ONE declared per-record action — invokes the
              *  action's deployed function with `{ collection, item_id, action, actor,
              *  item }` and returns its result. 404 when the key is not declared;
              *  502 `action_failed` (with `upstream.code` = the function's error
              *  class) when the function fails. Requires cms:write. */
             runAction: async (collection, itemId, key) => (await this.call('POST', `/v1/cms/items/${encodeURIComponent(collection)}/${encodeURIComponent(itemId)}/actions/${encodeURIComponent(key)}`)).data,
-            /** cms-rel B2 (cms.md §12): bounded group-by aggregate. fns count|sum|
+            /** Bounded group-by aggregate. fns count|sum|
              *  min|max|avg over index-slot-bound fields; groupBy ≤2 slot-bound
              *  fields; filter = the full query DSL incl. ONE-hop dotted join terms
              *  ({"channel.visibility":"public"}); scan capped at 50k rows → 422
              *  window_too_large (narrow the window or materialize a read-model). */
             aggregate: async (collection, body) => (await this.call('POST', `/v1/cms/items/${encodeURIComponent(collection)}/aggregate`, body)).data,
-            /** cms-rel B3 (cms.md §12): window ranking over the aggregate — rank ∈
+            /** Window ranking over the aggregate — rank ∈
              *  row_number|rank|percent_rank, computed over ≤500 aggregated groups
              *  (never raw rows), optional partitionBy. Same scan cap as aggregate. */
             rank: async (collection, body) => (await this.call('POST', `/v1/cms/items/${encodeURIComponent(collection)}/rank`, body)).data,
@@ -1278,13 +1304,13 @@ export class Vxil {
              *  merge, the event is the backstop. Emits one `cms.items.rekeyed`. */
             reKey: async (input) => (await this.call('POST', '/v1/cms/items/re-key', input)).data,
         },
-        /** cms-rel B4 (cms.md §13): atomic multi-collection transaction — 1–5
+        /** Atomic multi-collection transaction — 1–5
          *  steps over ≤3 collections, per-step `$where` CAS preconditions (the
          *  PATCH `if` grammar). All-or-nothing: any failed precondition/validation
          *  rolls the WHOLE transaction back (409 precondition_failed names the
          *  step). cms-internal only — no cross-feature effects inside the tx. */
         transaction: async (steps) => (await this.call('POST', '/v1/cms/transactions', { steps })).data,
-        /** P1-1 (cms.md §21): several get / query / create / patch / delete ops in
+        /** Several get / query / create / patch / delete ops in
          *  ONE round trip — the function-chain shape ("read 3 rows → patch 2 →
          *  create 1" is one call, not six). ≤25 ops, each run through the SAME path
          *  its single route uses (scopes, owner-scoping, hooks, guards, `if`,
@@ -1299,7 +1325,7 @@ export class Vxil {
             ops: ops.map((o) => ('expand' in o && o.expand !== undefined ? { ...o, expand: expandParam(o.expand) } : o)),
             ...(opts?.atomic !== undefined ? { atomic: opts.atomic } : {}),
         })).data,
-        /** cms-rel B5 (cms.md §12.4): declared read-models (config `readModels`
+        /** Declared read-models (config `readModels`
          *  bag) — list with last-run status, and "run now" materialization into
          *  the rollup collection. */
         readModels: {
@@ -1347,7 +1373,7 @@ export class Vxil {
         /** Read the resolved DM config (defaults merged with the stored partial). */
         getConfig: async () => (await this.call('GET', '/v1/dm/config')).data,
         /** Write the DM master config — a partial merge (omitted leaves keep their
-         *  current value), version-bumped and republished to the gate's KV key. */
+         *  current value), version-bumped and republished to the gate's cache. */
         setConfig: async (patch) => (await this.call('PUT', '/v1/dm/config', patch)).data,
         conversations: {
             /** Open (or, for a direct pair, return the existing) conversation. A
@@ -1410,7 +1436,7 @@ export class Vxil {
     /** The MCP aggregation surface (the `mcp` feature). */
     mcp = {
         /** Per-tenant secret for verifying the X-Vxil-Mcp-Signature header on custom
-         *  MCP tool calls (mcp.md §6.5) — the mirror of jobs.signingSecret(). */
+         *  MCP tool calls (guide ch. 10) — the mirror of jobs.signingSecret(). */
         signingSecret: async () => (await this.call('GET', '/v1/mcp/signing-secret')).data.signing_secret,
     };
     /**
@@ -1495,7 +1521,7 @@ export class Vxil {
             markAll: async (userId) => this.feedsMark(userId, 'read'),
             /** Archive/dismiss groups (hidden from inbox + dropped from the badge). */
             archive: async (userId, scope) => this.feedsMark(userId, 'archive', scope),
-            /** The badge: { unseen, unread, total } (KV-cached over the authority). */
+            /** The badge: { unseen, unread, total } (cached, recomputed on a miss). */
             unreadCount: async (userId) => (await this.call('GET', `/v1/feeds/notification/${encodeURIComponent(userId)}/count`)).data,
         },
         /**
@@ -1623,7 +1649,7 @@ export class Vxil {
             /** List an org's pending invitations. */
             list: async (orgId) => (await this.call('GET', `/v1/orgs/${encodeURIComponent(orgId)}/invitations`)).data.invitations,
         },
-        /** Custom tenant roles (permission-sets; migration orgs/0019). A custom role
+        /** Custom tenant roles (permission-sets). A custom role
          *  is a named set of permissions assignable like any built-in; the four
          *  built-ins reproduce the fixed owner>admin>member>viewer lattice. */
         roles: {
@@ -1636,7 +1662,7 @@ export class Vxil {
                 await this.call('DELETE', `/v1/orgs/roles/${encodeURIComponent(roleKey)}`);
             },
         },
-        /** Per-org/user resource ACL grants (migration orgs/0019): grant a permission
+        /** Per-org/user resource ACL grants: grant a permission
          *  on a specific resource string; `check(...,{ resource })` consults them. */
         acl: {
             grant: async (orgId, input) => (await this.call('POST', `/v1/orgs/${encodeURIComponent(orgId)}/acl`, input)).data,
@@ -1709,7 +1735,7 @@ export class Vxil {
         },
         /** Aggregate storage usage vs quotas (the FilesManager Storage panel). */
         usage: async () => (await this.call('GET', '/v1/files/usage')).data,
-        /** OCR / text extraction (files.md §1.1, BYO-key add-on). Small/mock inputs
+        /** OCR / text extraction (guide ch. 6, files, BYO-key add-on). Small/mock inputs
          *  extract inline (status `available`); large inputs (or `async:true`) return
          *  202 with a `job_id` — poll `getText()`. */
         extractText: async (objectId, opts) => (await this.call('POST', `/v1/files/${encodeURIComponent(objectId)}/extract-text`, opts ?? {})).data,
@@ -1792,7 +1818,7 @@ export class Vxil {
      * The AI substrate (the `ai` feature): store prompt TEMPLATES (config-as-code),
      * then generate (sync or streamed) and embed across providers. 'mock' is the
      * deterministic default; the real providers (openai/anthropic/gemini/azure/
-     * openrouter) route via BYO keys in tenant_secrets. `images` on the generate
+     * openrouter) route via BYO keys in your project secrets. `images` on the generate
      * inputs takes up to 8 vision refs: a public https:// URL, a
      * data:image/...;base64 URL, or file:<object_id> (a files-feature object) —
      * fetched images are capped at 4 MiB each; `documents` (pdf/text, ≤10 MiB
@@ -1852,7 +1878,7 @@ export class Vxil {
          *  outlives the ≤300s realtime token TTL); reconnect with `?since=<seq>`. */
         remintToken: async (generationId) => (await this.call('GET', `/v1/ai/generations/${encodeURIComponent(generationId)}/token`)).data,
         /** Resume a streamed generation after a dropped socket: every recorded frame
-         *  with seq > `since` plus `done` (the §2a replay buffer — plain JSON, not
+         *  with seq > `since` plus `done` (the replay buffer — plain JSON, not
          *  an SSE stream; the buffer lives 1 h). A settled JOB-lane generation is
          *  served from its stored answer instead (30 days). `status` says where the
          *  generation is; `expired: true` means it settled but its frames are gone
@@ -1903,7 +1929,7 @@ export class Vxil {
         /** Streamed grounded answer: citations + the channel handle up front, tokens
          *  over the realtime channel. */
         stream: async (input) => (await this.call('POST', '/v1/rag/answer', { ...input, stream: true })).data,
-        /** Retrieval-only grounding preview (rag.md §1c): the exact chunks `answer`
+        /** Retrieval-only grounding preview (guide ch. 6, rag): the exact chunks `answer`
          *  would ground on, with rerank + metadata boosts applied — no generation,
          *  no token spend. `boosts`/`rerank`/`min_score` override the rag config.
          *  `min_score` floors the EFFECTIVE `score`, which is a RANK value (about
@@ -2002,7 +2028,7 @@ 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 (guide ch. 6, payments).
          *
          *  OVERLAPPING SUBSCRIPTIONS — what `until` means. The WINNER is the
          *  entitled subscription with the highest `tierMap[tier].rank` (default 0);
@@ -2088,14 +2114,14 @@ export class Vxil {
             return (await this.call('GET', `/v1/payments/subscriptions${s}`)).data.subscriptions;
         },
         /**
-         * Create a hosted-checkout session (payments.md §3). Redirect the buyer to
+         * Create a hosted-checkout session (guide ch. 6, payments). Redirect the buyer to
          * the returned `url`; completion lands server-side via the provider webhook
          * (the matching session flips to completed, the charge/grant is folded).
          * Idempotency-Key REQUIRED — a retry replays the SAME session verbatim.
          */
         createCheckoutSession: async (input, opts) => (await this.call('POST', '/v1/payments/checkout-sessions', input, { 'idempotency-key': opts.idempotencyKey })).data,
         /**
-         * Refund a charge at-most-once (payments.md §6a). Omit `amount_cents` to
+         * Refund a charge at-most-once (guide ch. 6, payments). Omit `amount_cents` to
          * 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).
@@ -2215,7 +2241,7 @@ export class Vxil {
             });
             return (await this.call('GET', `/v1/payments/refunds${suffix}`)).data;
         },
-        /** Provider webhook event log (payments.md §7 "Event log & replay"):
+        /** Provider webhook event log (guide ch. 6, payments "Event log & replay"):
          *  operator visibility over every delivery — incl. persisted signature
          *  failures — plus an idempotent reprocess verb. Needs payments:read
          *  (reprocess: payments:write).
@@ -2250,5 +2276,5 @@ export class Vxil {
     };
 }
 // Failure reporting for tenant functions — the Sentry-envelope forwarder
-// (roadmap §4.11 P0-4e). Zero dependencies; see reporting.ts.
+// (guide ch. 8). Zero dependencies; see reporting.ts.
 export { withReporting, report, buildEnvelope, parseDsn, exceptionEvent, reportServerErrors, REPORT_TIMEOUT_MS, } from './reporting.js';

package/dist/qs.js

@@ -1,5 +1,5 @@
 // Query-string builder — the SDK's replacement for the WHATWG `URLSearchParams`
-// at every call site (F7-44, the React-Native-clean SDK).
+// at every call site (the React-Native-clean SDK).
 //
 // WHY (implementation note; `//` comments never reach the shipped .d.ts):
 // React Native supplies its own URLSearchParams polyfill, and up to RN 0.79

package/dist/reporting.js

@@ -1,6 +1,5 @@
 // withReporting — forward a tenant function's failure to the tenant's OWN
-// error reporter over the Sentry envelope HTTP format (roadmap §4.11 P0-4e,
-// techmaker evaluation P0-5's "SDK half", 2026-09-23).
+// error reporter over the Sentry envelope HTTP format.
 //
 // NOT a Sentry SDK and NOT a dependency on one: the function sandbox is
 // Web-standard fetch/crypto only, so this is the plain ingestion envelope

package/dist/retry.js

@@ -1,6 +1,6 @@
 // The request seam: retry + timeout + hooks around the ONE `fetch` every SDK
-// request goes through (parity P1 #9), and the `Retry-After` parser
-// `VxilError.retryAfter` shares (F7-44). DEFAULT OFF — with no `retry`,
+// request goes through, and the `Retry-After` parser
+// `VxilError.retryAfter` shares. DEFAULT OFF — with no `retry`,
 // `timeoutMs` or `hooks` option the transport is a single `fetch` + `text()`,
 // exactly what `call()` did before.
 //

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/sdk",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "private": false,
   "type": "module",
   "description": "Typed client for the Vxil REST API (notifications, auth, jobs, files, cms, comments, webhooks, realtime, orgs, rate-limits).",