@vxil/sdk 0.13.0 → 0.14.0

package/dist/index.d.ts

@@ -382,6 +382,55 @@ export interface JobRun {
      *  the fire); `started_at − scheduled_for` is how late it started. null for a
      *  run you enqueued (and for runs fired before 2026-10-01). */
     scheduled_for?: string | null;
+    /** the single-run read only: what the run completed with — the `result` of
+     *  its signed callback's `completed` body, or the value a generation run
+     *  settled with (the fields its status mirror received; an over-64 KiB value
+     *  reads `{ truncated: true, bytes, max_bytes }`). null when nothing reported
+     *  one — a handler's own 2xx response body is never stored. */
+    result?: unknown;
+    /** the single-run read only: the latest progress report of the run — a
+     *  `processing` ping on its signed callback (plain run) or its provider's
+     *  webhook (generation run). null until one arrives. */
+    progress?: JobRunProgress | null;
+}
+/** A run's latest progress report (`JobRun.progress`): only these keys pass. */
+export interface JobRunProgress {
+    /** 0..100 */
+    progress?: number;
+    /** ≤ 64 chars */
+    stage?: string;
+    /** ≤ 200 chars */
+    message?: string;
+    /** when the report was stored (ISO) */
+    at: string;
+}
+/** The body an external worker POSTs to a run's signed `callback_url`
+ *  (`postRunCallback`). `completed` ends the run `succeeded` with `result`
+ *  stored (≤ 64 KiB of JSON); `failed` dead-letters it with `error`;
+ *  `processing` only records progress (repeatable). On a run suspended in
+ *  `jobs.wait(…)`, completed / failed WAKE the handler instead, with
+ *  `payload.wakeup = { via: 'callback', status, result?, error? }`. */
+export type RunCallbackBody = {
+    status: 'completed';
+    result?: unknown;
+} | {
+    status: 'failed';
+    error?: string;
+} | {
+    status: 'processing';
+    progress?: number;
+    stage?: string;
+    message?: string;
+};
+/** What a run callback answers: the run's state after it (`deduplicated: true`
+ *  when the URL was already used or the run was already terminal — nothing
+ *  changed). */
+export interface RunCallbackAnswer {
+    run_id: string;
+    state: JobRun['state'];
+    deduplicated?: boolean;
+    woken?: boolean;
+    event?: string;
 }
 /** The run states no later write can move — what `waitForRun` and an
  *  async+wait invoke resolve `done: true` on. */
@@ -475,7 +524,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 +557,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 +572,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 +594,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 +630,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 +679,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
@@ -661,9 +710,27 @@ export interface FileObject {
     size_bytes: number;
     status: 'pending' | 'available' | 'deleted';
     created_at: string;
+    /** The object's public URL when it is published to the public asset host
+     *  (`files.publish`), else null. */
+    public_url?: string | null;
+}
+/** A published object (guide ch. 6, files, "Public asset delivery"): a stable,
+ *  content-addressed URL on vxil's public asset host, served with
+ *  `Cache-Control: public, max-age=31536000, immutable`. `variants` maps each
+ *  declared image preset (`publicAssets.variants`) to its URL — images only. */
+export interface PublishedFile {
+    object_id: string;
+    url: string;
+    sha256: string;
+    content_type: string;
+    size_bytes: number;
+    published_at: string | null;
+    variants: Record<string, 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 =
+/** Why one id of a bulk publish was not published. */
+export type PublishErrorCode = 'not_found' | 'upload_incomplete' | 'content_type_not_publishable' | 'object_too_large' | 'quota_exceeded' | 'batch_budget_exceeded' | 'asset_taken_down' | 'publish_failed';
+/** 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 +749,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 +990,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;
@@ -971,10 +1038,13 @@ export interface JobRunEventPayload {
     level?: 'error';
     state?: 'broken';
     /** `job.dead_lettered` only, and only when something other than the
-     *  executor killed the run: `reaped` (the stuck-run reaper) or
-     *  `queue_backstop` (the queue's own retries ran out). Absent when the run
+     *  executor killed the run: `reaped` (the stuck-run reaper),
+     *  `queue_backstop` (the queue's own retries ran out), `callback_failed`
+     *  (the run's signed callback reported `status: 'failed'`) or
+     *  `callback_timeout` (the handler handed the run off with a 202 and no
+     *  callback completed it within its lifetime). Absent when the run
      *  exhausted its attempts normally. */
-    reason?: 'reaped' | 'queue_backstop';
+    reason?: 'reaped' | 'queue_backstop' | 'callback_failed' | 'callback_timeout';
 }
 /** The provider-reported environment of the money (`production` | `sandbox`). */
 export type PaymentsEventEnvironment = 'production' | 'sandbox';
@@ -1366,6 +1436,13 @@ export interface JobDelivery<P = unknown> {
     payload: P;
     /** a schedule-fired run only: the slot it was due for (ISO, UTC) */
     scheduled_for?: string;
+    /** a run enqueued with `callback` only: its CURRENT single-use signed
+     *  callback URL. Hand it to the worker that finishes the job (no API key
+     *  needed) and answer 202 — the run waits until that worker POSTs
+     *  `{ status: 'completed', result }` / `{ status: 'failed', error }` /
+     *  `{ status: 'processing', progress, stage, message }` to it (see
+     *  `postRunCallback`). */
+    callback_url?: string;
 }
 /** The `?since=` replay read (GET /v1/ai/generations/{id}/stream). */
 export interface AiResumePage {
@@ -1510,7 +1587,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 +1604,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 +1828,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 +1850,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 +1861,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
@@ -1798,6 +1875,16 @@ export declare function listCmsPublic(tenantId: string, collection: string, quer
     items: CmsPublicRow[];
     next_cursor: string | null;
 }>;
+/** POST a run's single-use signed `callback_url` (guide ch. 6, "Hand a run to
+ *  an external worker") — KEYLESS: no API key, no `Vxil` client; the URL is the
+ *  credential, so call this from the worker that finishes the job (a render
+ *  farm, a GPU box, another queue's task). Idempotent: a repeat of a used URL
+ *  answers `deduplicated: true`. A non-2xx throws `VxilError` (401 a forged or
+ *  altered URL, 410 `callback_expired`, 413 `result_too_large`, 404 a run that
+ *  did not opt in). */
+export declare function postRunCallback(callbackUrl: string, body: RunCallbackBody, opts?: {
+    fetch?: typeof fetch;
+}): Promise<RunCallbackAnswer>;
 /** The structural shape a `vxil gen`-generated `VxilSchema` satisfies. The base
  *  `Vxil` class is generic over it (`new Vxil<VxilSchema>(...)`), exactly the
  *  `createClient<Database>()` move — types are layered on; the runtime is
@@ -1952,12 +2039,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 +2056,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 +2073,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
@@ -2006,7 +2093,7 @@ export interface CmsReindexPage {
      *  but unaccelerated). */
     index_certify?: 'armed' | 'pending' | 'timeout';
 }
-/** The result of a bounded filtered delete (cms.md §20). `matched` counts the
+/** 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.
@@ -2026,33 +2113,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[];
 }
@@ -2068,7 +2155,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<{
@@ -2086,7 +2173,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;
@@ -2103,7 +2190,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 = {
@@ -2123,7 +2210,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';
@@ -2222,7 +2309,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;
@@ -2238,7 +2325,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
@@ -2282,7 +2369,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`. */
@@ -2317,12 +2404,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;
@@ -2330,7 +2417,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: {
@@ -2340,7 +2427,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). */
@@ -2357,7 +2444,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;
@@ -2413,12 +2500,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.
@@ -2457,7 +2544,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;
@@ -2494,7 +2581,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
@@ -2590,7 +2677,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: {
@@ -2643,7 +2730,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
@@ -2687,7 +2774,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: {
@@ -2754,12 +2841,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<{
@@ -2831,7 +2918,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
     readonly jobs: {
         /** Enqueue a one-off job; Vxil POSTs a signed callback to target_url with
          * retries. deliver_after (ISO) / delay_seconds (≤ 30 d, at most one of the
-         * two) defer the first delivery; > 12 h returns state 'delayed'. */
+         * two) defer the first delivery; > 12 h returns state 'delayed'.
+         *
+         * `callback: true` (or `{ ttl_seconds }`, 60 s..31 d; default 24 h) opts
+         * the run in to a KEYLESS signed `callback_url` (in the answer and on every
+         * delivery): an external worker POSTs it to complete / fail the run, report
+         * progress, or wake a `wait`. A handler that answers 202 HANDS the run off
+         * — it waits for that callback (dead-lettered as `CallbackTimeout` when the
+         * lifetime passes). See `postRunCallback`. */
         enqueue: (input: {
             job_name: string;
             target_url: string;
@@ -2840,11 +2934,15 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             max_attempts?: number;
             deliver_after?: string;
             delay_seconds?: number;
+            callback?: boolean | {
+                ttl_seconds?: number;
+            };
         }) => Promise<{
             run_id: string;
             state: string;
             deduplicated?: boolean;
             deliver_after?: string;
+            callback_url?: string;
         }>;
         /** Atomic multi-enqueue (≤100 items; any invalid item rejects the whole
          * batch). Each item = the enqueue input, incl. per-item idempotency_key
@@ -2865,7 +2963,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.
@@ -2874,7 +2972,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
@@ -2916,11 +3014,15 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 /** dotted path of the value a completed run settles with (mirrored as `result`) */
                 result_path?: string;
             };
+            /** `progress_fields`: the progress keys (`progress` / `stage` /
+             *  `message`) a webhook-mode `processing` callback also writes onto the
+             *  mirrored record — realtime clients of that record see them live */
             status_mirror?: {
                 feature: string;
                 collection: string;
                 record_id: string;
                 column?: string;
+                progress_fields?: Array<"progress" | "stage" | "message">;
             };
             timeout?: {
                 after_ms: number;
@@ -2988,12 +3090,21 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         }>;
         /**
          * Suspend the RUNNING run until an event (call from the executing
-         * handler, then return 200 — the suspension wins).
+         * handler, then return 200 — the suspension wins). `state: 'resumed'` =
+         * the event already fired (continue; `wakeup` is its payload). A run
+         * enqueued with `callback` also gets its `callback_url`: an external worker
+         * POSTing it wakes this wait with no API key.
          */
         wait: (runId: string, input: {
             event: string;
             timeout_seconds?: number;
-        }) => Promise<void>;
+        }) => Promise<{
+            run_id: string;
+            state: "waiting" | "resumed";
+            event: string;
+            wakeup?: unknown;
+            callback_url?: string;
+        }>;
         /** Wake every run waiting on the event. */
         emitEvent: (event: string, payload?: Record<string, unknown>) => Promise<number>;
         /** Secret for verifying X-Vxil-Jobs-Signature on your callback endpoints. */
@@ -3431,9 +3542,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>;
@@ -3507,7 +3618,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: {
@@ -3539,7 +3650,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
@@ -3557,15 +3668,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)
@@ -3575,14 +3686,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 (cms.md §3 "Indexed
+                    /** 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[];
@@ -3600,7 +3711,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
@@ -3608,7 +3719,7 @@ 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 (cms.md §3 "Indexed equality")
+            /** 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`).
@@ -3621,16 +3732,16 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 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
@@ -3659,15 +3770,15 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 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";
@@ -3680,7 +3791,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?: {
@@ -3714,19 +3825,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;
@@ -3734,7 +3845,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,
@@ -3754,7 +3865,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
@@ -3763,7 +3874,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
@@ -3775,7 +3886,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
@@ -3786,7 +3897,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<{
@@ -3814,7 +3925,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
@@ -3830,7 +3941,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`,
@@ -3844,7 +3955,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: {
@@ -3949,7 +4060,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;
@@ -4082,7 +4193,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>;
     };
     /**
@@ -4179,7 +4290,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>;
         };
         /**
@@ -4294,7 +4405,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>;
         };
         /**
@@ -4545,7 +4656,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: {
@@ -4579,7 +4690,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: {
@@ -4708,7 +4819,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         }>;
         /** Soft delete; bytes are hard-deleted 30 days later. */
         delete: (objectId: string) => Promise<void>;
-        /** Aggregate storage usage vs quotas (the FilesManager Storage panel). */
+        /** Aggregate storage usage vs quotas (the FilesManager Storage panel).
+         *  `public_assets` = published copies vs the plan's published-bytes ceiling
+         *  (identical bytes count once). */
         usage: () => Promise<{
             usage: {
                 object_count: number;
@@ -4720,8 +4833,47 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 maxTotalBytes?: number;
             };
             available: Record<string, number | null>;
+            public_assets?: {
+                enabled: boolean;
+                published_objects: number;
+                published_bytes: number;
+                max_published_bytes: number;
+                bytes_remaining: number;
+            };
+        }>;
+        /** SERVER-ONLY (403 server_only in end-user mode). Publish an available
+         *  object to vxil's public asset host: a stable, content-addressed URL
+         *  (`https://cdn.vxil.app/<tenant>/<sha256>.<ext>`) served from a global
+         *  edge cache with `Cache-Control: public, max-age=31536000, immutable`,
+         *  playable video/audio and CORS from `publicAssets.corsOrigins`. Needs
+         *  `files.publicAssets.enabled`. Publishable: png/jpeg/webp/avif/gif,
+         *  mp4/webm, mp3/m4a/ogg, woff2/woff, json — never HTML or SVG (422
+         *  `content_type_not_publishable`). Counts against the plan's
+         *  published-bytes ceiling (422 `quota_exceeded`). Idempotent: an already
+         *  published object answers its existing URL. Emits
+         *  `files.object.published`. */
+        publish: (objectId: string) => Promise<PublishedFile>;
+        /** SERVER-ONLY. Publish up to 100 objects (about 2 GiB of bytes) in one
+         *  call; a bad id lands in `errors[]` without failing the rest (ids past
+         *  the byte budget as `batch_budget_exceeded` — send them again),
+         *  `published[]` keeps your order. */
+        publishMany: (objectIds: string[]) => Promise<{
+            published: PublishedFile[];
+            errors: Array<{
+                object_id: string;
+                code: PublishErrorCode;
+                message: string;
+            }>;
         }>;
-        /** OCR / text extraction (files.md §1.1, BYO-key add-on). Small/mock inputs
+        /** SERVER-ONLY. Take an object off the public asset host. Its public copy
+         *  is deleted once no other object of yours has the same bytes, and the
+         *  edge cache stops serving it within about a minute and a half (a
+         *  browser that already downloaded it keeps its copy). Deleting the object
+         *  unpublishes it too. 404 when it is not published; 503
+         *  `unpublish_failed` when the public copy could not be removed right
+         *  then (it stays published — retry). Emits `files.object.unpublished`. */
+        unpublish: (objectId: string) => Promise<void>;
+        /** 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?: {
@@ -4875,7 +5027,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
@@ -5087,7 +5239,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
@@ -5184,7 +5336,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
@@ -5312,7 +5464,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);
@@ -5456,7 +5608,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.
@@ -5480,7 +5632,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).
@@ -5677,7 +5829,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).