@nitida/sdk 0.24.1 → 0.25.0

package/README.md

@@ -7,7 +7,7 @@ bindings** — admin-managed names that resolve to assets at runtime.
 
 ## One client, every environment
 
-The whole SDK ships as **one `AquienpzClient` class** behind environment-
+The whole SDK ships as **one `NitidaClient` class** behind environment-
 specific subpath entries. Each subpath bundles the same client PLUS the
 helpers safe for that runtime — same pattern as **Vercel Blob** (`@vercel/blob`
 vs `@vercel/blob/client`), **Better Auth**, **Uploadthing**, and the **Vercel AI
@@ -17,11 +17,11 @@ eliminates type drift between server and client surfaces.
 
 | Where you run | Import | What it bundles |
 |---|---|---|
-| Node 20+, Bun, Cloud Run, Lambda, Edge, agents, cron | **`@nitida/sdk/server`** | `AquienpzClient` + URL builders + `signTransformUrl`. **No browser-only code.** Hard guarantee against shipping `Blob`-workflow helpers to the wrong runtime. |
-| Browser (Next.js client, Vite, CRA, web workers) | **`@nitida/sdk/web`** | `AquienpzClient` + everything in `/server` + `createWebUploader` (multipart, parallel parts, IndexedDB resume) + `compressImage` (HEIC→WebP, compressorjs). |
+| Node 20+, Bun, Cloud Run, Lambda, Edge, agents, cron | **`@nitida/sdk/server`** | `NitidaClient` + URL builders + `signTransformUrl`. **No browser-only code.** Hard guarantee against shipping `Blob`-workflow helpers to the wrong runtime. |
+| Browser (Next.js client, Vite, CRA, web workers) | **`@nitida/sdk/web`** | `NitidaClient` + everything in `/server` + `createWebUploader` (multipart, parallel parts, IndexedDB resume) + `compressImage` (HEIC→WebP, compressorjs). |
 | React Native / Expo apps | `@nitida/sdk/native` | `compressImage` for RN (libjpeg-turbo via `react-native-compressor`). Pair with `/expo`. |
 | Expo background uploads | `@nitida/sdk/expo` | `createExpoUploader` — native `URLSession` (iOS) / `WorkManager` (Android) sessions that survive app backgrounding. |
-| Next.js / React (hooks) | `@nitida/sdk/react` | `AquienpzProvider` + `useSlot` / `useSlots` / `useAsset`. |
+| Next.js / React (hooks) | `@nitida/sdk/react` | `NitidaProvider` + `useSlot` / `useSlots` / `useAsset`. |
 | Backwards-compat (root) | `@nitida/sdk` | Same shape as today; equivalent to `/web` for the public symbols. **Prefer the explicit subpath in new code.** |
 
 Uploaders + compressors are **optional** peer deps (`@aquienpz/asset-uploader-{web,expo}`,
@@ -57,7 +57,7 @@ loud — same pattern as `@vercel/blob/client`, `better-auth/client`, AI SDK's
 `/edge` subpath.
 
 `@nitida/sdk/web` v0.17+ enforces this physically: the constructor type
-is `Omit<AquienpzClientOptions, "apiKey" | "signingKey">`. Passing `apiKey`
+is `Omit<NitidaClientOptions, "apiKey" | "signingKey">`. Passing `apiKey`
 won't compile, period.
 
 ## BFF-proxy mode (browser → your route → aquienpz)
@@ -71,11 +71,11 @@ token and forwards to aquienpz. Same pattern Vercel Blob uses for
 
 ```tsx
 "use client";
-import { AquienpzClient } from "@nitida/sdk/web";
+import { NitidaClient } from "@nitida/sdk/web";
 
-const aq = new AquienpzClient({
+const aq = new NitidaClient({
   endpoint:   "/api/am",              // OK: relative → same-origin BFF
-  tenantCode: "realtyone-cr",
+  tenantCode: "acme-co",
   tenantId:   1,
   // apiKey: ... ERROR: TS error: not assignable to WebClientOptions
 });
@@ -96,7 +96,7 @@ import { NextRequest } from "next/server";
 
 const UPSTREAM = process.env.AQUIENPZ_URL!;        // server-only
 const API_KEY = process.env.AQUIENPZ_API_KEY!;     // server-only
-const TENANT  = process.env.AQUIENPZ_TENANT_CODE!; // e.g. "realtyone-cr"
+const TENANT  = process.env.AQUIENPZ_TENANT_CODE!; // e.g. "acme-co"
 
 async function proxy(req: NextRequest, { params }: { params: { path: string[] } }) {
   const search = new URL(req.url).search;
@@ -119,12 +119,12 @@ export { proxy as GET, proxy as POST, proxy as PUT, proxy as PATCH, proxy as DEL
 ### Bun / Elysia backend
 
 ```ts
-import { AquienpzClient } from "@nitida/sdk/server";
+import { NitidaClient } from "@nitida/sdk/server";
 
-const aq = new AquienpzClient({
+const aq = new NitidaClient({
   endpoint:   process.env.AQUIENPZ_URL!,
   apiKey:     process.env.AQUIENPZ_API_KEY!,   // OK: required by ServerClientOptions
-  tenantCode: "realtyone-cr",
+  tenantCode: "acme-co",
   tenantId:   1,
 });
 ```
@@ -132,7 +132,7 @@ const aq = new AquienpzClient({
 ### Expo
 
 ```ts
-import { AquienpzClient } from "@nitida/sdk/web"; // same browser-safe type
+import { NitidaClient } from "@nitida/sdk/web"; // same browser-safe type
 // Construct against your /api/am proxy; no apiKey in the app bundle.
 ```
 
@@ -150,34 +150,37 @@ bun add @nitida/sdk @nitida/asset-client
 npm install @nitida/sdk @nitida/asset-client
 ```
 
-Optional, only if you need large uploads:
+Optional, only if you compress on the client before uploading:
 
 ```bash
-# Web / Vite / Next.js client uploads
-bun add @aquienpz/asset-uploader-web
-
-# Expo / React Native background uploads
-bun add @aquienpz/asset-uploader-expo
+bun add @nitida/asset-compressor-web      # browser: HEIC→WebP, resize
+bun add @nitida/asset-compressor-native   # Expo / React Native
 ```
 
 Peer deps: `@nitida/asset-client` (URL builders + types) and `react` (only if
-you use the `/react` subpath).
+you use the `/react` subpath). Both compressors are optional and lazy — the
+SDK never imports them unless you call a compress path.
+
+> ⚠️ The multipart uploader packages (`@aquienpz/asset-uploader-web` /
+> `-expo`) are **not published on npm**. `aq.upload()` covers files in a
+> single PUT and is what every consumer uses today; see *Large uploads* below
+> for where the ceiling actually is.
 
 ## Quick start
 
 ```ts
-import { AquienpzClient } from "@nitida/sdk";
+import { NitidaClient } from "@nitida/sdk";
 
-const aq = new AquienpzClient({
+const aq = new NitidaClient({
   endpoint: "https://api.nitida.gofuture.space",
-  apiKey:   process.env.ASSET_MANAGER_RUNTIME_KEY!, // amk_rt_* Better Auth API key
+  apiKey:   process.env.AQUIENPZ_API_KEY!,          // amk_rt_* runtime API key
   tenantCode: "your-tenant",
   tenantId:   42,                  // numeric tenant id (used in CDN URL prefix)
   cdnBase:    "https://8ok.uk",    // optional, defaults to https://8ok.uk
 });
 
 // Slots — the recommended way to reference brand assets in code.
-// Source never hardcodes a CDN URL; admin rebinds from asset-lab-web.
+// Source never hardcodes a CDN URL; an admin rebinds it from the console.
 const hero = await aq.slots.resolve("storefront.home.hero");
 //   → { slot: { asset, preset, … }, preset: "lg", url: "https://8ok.uk/2a/v/<sha>-l.webp" }
 
@@ -240,8 +243,8 @@ await aq.upload(file, {
 });
 ```
 
-**Defaults** (matched to the realtyone-cr production webapp:
-`LISTING_STANDARD_*` constants):
+**Defaults** (tuned against a production photo-upload workload —
+phone cameras, listing covers):
 
 | Option | Default |
 |---|---|
@@ -263,9 +266,8 @@ await aq.upload(file, {
 - Expo / React Native: the `/expo` subpath uses native
   `expo-image-manipulator` instead (already wired in the uploader). The
   `compress` option on `aq.upload` is web-only.
-- The server-side `assets.client_original_bytes` column is populated
-  from the original pre-compression size, surfacing the savings story
-  in admin dashboards.
+- The original pre-compression size is recorded server-side, so the
+  savings show up in the admin usage dashboards.
 
 Direct access to the compressor (without going through `aq.upload`):
 
@@ -279,23 +281,25 @@ const results = await compressImages([fileA, fileB, fileC]);
 
 ## Large uploads (web)
 
-The core `aq.upload()` handles files under 50 MB in a single PUT. For
-bigger files use the `/web` subpath — it delegates to
-`@aquienpz/asset-uploader-web`'s multipart `UploadTask` (chunks, parallel
-parts, retries with backoff, IndexedDB-persisted progress, Web Worker
-SHA-256).
+`aq.upload()` is a single PUT: atomic, BFF-friendly, and the path this SDK
+supports. It is what you should call.
 
-```ts
-import { createWebUploader } from "@nitida/sdk/web";
+**Multipart is deliberately NOT exposed from `@nitida/sdk/web`.** A static
+import of the uploader package broke every consumer of the subpath (the
+bundler resolves before the optional-peer check runs), and the `UploadTask`
+API needs a raw `authToken` that BFF-proxy mode does not hand out — so there
+is no `createWebUploader` export. Earlier drafts of this README described
+one; it never shipped.
 
-const task = createWebUploader(aq, { file });
-task.on("progress", ({ ratio }) => setProgress(ratio));
-task.on("ready",    ({ assetId }) => bindSlot(assetId));
-const { assetId, deduped } = await task.start();
-```
+Where that leaves you:
 
-Peer dep: `@aquienpz/asset-uploader-web` (lazy — apps that only need
-small uploads skip it).
+| file size | what to call |
+|---|---|
+| any size the browser can hold in memory | `aq.upload(file)` |
+| bigger, or you need resume across reloads | not covered by this SDK yet — talk to us |
+
+Client-side compression is the lever that keeps most media under the
+single-PUT ceiling; see *Client-side compression* below.
 
 ## Large uploads (Expo / React Native)
 
@@ -307,13 +311,13 @@ WorkManager. Same JS API as the web flavor.
 import { useEffect, useState } from "react";
 import { Image } from "react-native";
 import * as ImagePicker from "expo-image-picker";
-import { AquienpzClient } from "@nitida/sdk";
+import { NitidaClient } from "@nitida/sdk";
 import {
   createExpoUploader,
   listResumableSessions,
 } from "@nitida/sdk/expo";
 
-const aq = new AquienpzClient({
+const aq = new NitidaClient({
   endpoint:   process.env.EXPO_PUBLIC_AQUIENPZ_URL!,
   apiKey:     process.env.EXPO_PUBLIC_AQUIENPZ_API_KEY!, // amk_rt_*
   tenantCode: "your-tenant",
@@ -359,9 +363,10 @@ export function UploadHeroScreen() {
 }
 ```
 
-Peer dep: `@aquienpz/asset-uploader-expo`. Ships a config plugin for the Expo
-prebuild step (background mode + native module registration); add it to
-`app.json` under `plugins` before running `expo prebuild`.
+⚠️ The Expo background-upload path depends on `@aquienpz/asset-uploader-expo`,
+which is **not on npm**. `aq.upload()` works on Expo today without it; the
+background/resumable variant is not something an external consumer can install
+yet.
 
 ## Next.js App Router (Server Components)
 
@@ -370,9 +375,9 @@ no provider, no hook. The slot URLs ship as plain `<img>` markup.
 
 ```tsx
 // app/page.tsx — Server Component
-import { AquienpzClient } from "@nitida/sdk";
+import { NitidaClient } from "@nitida/sdk";
 
-const aq = new AquienpzClient({
+const aq = new NitidaClient({
   endpoint:   process.env.AQUIENPZ_URL!,
   apiKey:     process.env.AQUIENPZ_API_KEY!, // amk_rt_* — server-only
   tenantCode: "your-tenant",
@@ -412,11 +417,11 @@ each hook subscribes to the in-process cache.
 ```tsx
 // app/providers.tsx — Client Component
 "use client";
-import { AquienpzClient } from "@nitida/sdk";
-import { AquienpzProvider } from "@nitida/sdk/react";
+import { NitidaClient } from "@nitida/sdk";
+import { NitidaProvider } from "@nitida/sdk/react";
 
 // In production, get apiKey from a /session route instead of bundling it.
-const client = new AquienpzClient({
+const client = new NitidaClient({
   endpoint:   process.env.NEXT_PUBLIC_AQUIENPZ_URL!,
   apiKey:     process.env.NEXT_PUBLIC_AQUIENPZ_API_KEY!,
   tenantCode: "your-tenant",
@@ -424,7 +429,7 @@ const client = new AquienpzClient({
 });
 
 export function Providers({ children }: { children: React.ReactNode }) {
-  return <AquienpzProvider client={client}>{children}</AquienpzProvider>;
+  return <NitidaProvider client={client}>{children}</NitidaProvider>;
 }
 ```
 
@@ -451,7 +456,7 @@ deploys to brand decisions. With slots:
 
 | Without slots | With slots |
 |---|---|
-| Edit URL in code | Drag-drop a new asset in asset-lab-web |
+| Edit URL in code | Drag-drop a new asset in the admin console |
 | Commit + PR + deploy | Cache refreshes (60s default) |
 | 5-30 minute roundtrip | Instant |
 
@@ -501,8 +506,8 @@ slot defaults to and emit responsive `srcSet` for browser-side resizing.
 
 Omitting `presets` is always equivalent to `["original"]` — the platform
 never auto-generates the responsive ladder. This keeps logo / SVG /
-one-shot uploads cheap and avoids surprise R2 writes (the ladder is 4×
-the source bytes). Apps that want responsive sizes pass them explicitly:
+one-shot uploads cheap and avoids surprise storage writes (the ladder
+is 4× the source bytes). Apps that want responsive sizes pass them explicitly:
 
 ```ts
 await aq.upload(file, {
@@ -516,8 +521,8 @@ Or add missing variants later without re-uploading:
 await aq.assets.regenerate(assetId, { presets: ["thumb", "sm", "md", "lg"] });
 ```
 
-Variants are WebP `quality: 75–80`. Total R2 cost when generating the
-full responsive ladder ≈ 4× source bytes.
+Variants are WebP `quality: 75–80`. Total stored bytes when generating
+the full responsive ladder ≈ 4× source bytes.
 
 **Variants never upscale.** The pipeline clamps each preset's target to
 `min(presetMaxSide, sourceMaxSide)`. A 1080×720 photo asked for `xl`
@@ -628,26 +633,26 @@ You can call it many times; it's idempotent per preset.
 
 ### Source-byte lifecycle (why regenerate always works)
 
-Two distinct R2 prefixes; most people only care about one:
+Your bytes exist in two places with **very different lifetimes**:
 
-| R2 path | Role | Lifetime |
+| Bytes | Role | Lifetime |
 |---|---|---|
-| `raw/<sha>.<ext>` | Landing zone for the presigned PUT. `/process` reads it once to verify the SHA. Never CDN-served. | Deleted ~24h after upload by the cleanup job |
-| `variants/<sha>-<preset>.<ext>` | The CDN-served files. `<sha>-o.<ext>` is the permanent home of `original`. | **Permanent** — only deleted by explicit DELETE on the asset or variant |
+| The upload you PUT to the presigned URL | Read once to verify the SHA. Never CDN-served. | **Deleted ~24h after upload** |
+| The stored variants | The CDN-served files. The `original` variant is the permanent home of your source bytes. | **Permanent** — only deleted by an explicit DELETE on the asset or variant |
+
+⚠️ **That 24h is why you should ask for `original`.** Once the grace window
+closes, the highest-fidelity bytes still on the platform are whatever variants
+you asked for.
 
 `regenerate()` walks a fidelity-ordered fallback chain until it finds
 usable bytes — it **never fails on a still-present asset**:
 
 ```
-1. variants/<sha>-o.<ext>     ← permanent original (best)
-2. raw/<sha>.<ext>            ← exact upload bytes, only during the 24h grace
-3. variants/<sha>-x.webp      ← xl
-4. variants/<sha>-l.webp      ← lg
-5. variants/<sha>-m.webp      ← md
-6. variants/<sha>-s.webp      ← sm
-7. variants/<sha>-q.webp      ← thumb (last resort — smart-cropped square,
-                                  so aspect ratio of derived variants
-                                  will inherit the thumb's crop)
+1. original   ← permanent, your exact source (best)
+2. raw        ← the upload bytes, only during the 24h grace
+3. xl → lg → md → sm
+4. thumb      ← last resort: it is a smart-cropped square, so anything
+                derived from it inherits the thumb's crop
 ```
 
 The no-upscale clamp guarantees we never invent pixels: asking for
@@ -677,9 +682,9 @@ For everything else — exact CSS pixel widths, art-directed crops, devicePixelR
 ladders, square thumbs from rectangular sources — call `aq.transform()`:
 
 ```tsx
-import { AquienpzClient } from "@nitida/sdk";
+import { NitidaClient } from "@nitida/sdk";
 
-const aq = new AquienpzClient({ /* ... */ });
+const aq = new NitidaClient({ /* ... */ });
 const asset = await aq.assets.byHash(sha256);
 
 // Single URL
@@ -727,18 +732,15 @@ source-size bracket with virtually identical SSIM. The policy is re-evaluated as
 libavif improves, so `auto` may resolve differently in the future — that is the
 point of asking for `auto` instead of naming a format.
 
-`gravity=face` runs the source image through a ~1 MB Ultra-Light face
-detector (ultraface-RFB-320 via ONNX Runtime) and crops to the
-highest-confidence face with sensible padding (50 % of face dimensions
-on each side, clamped to source bounds, keeping the requested aspect
-ratio). When no face is detected, it falls back to sharp's `attention`
-strategy and returns the response with `X-Transform-Face: fallback` so
-you can detect the cache state. Cost: ~10 ms inference per image
-(warm); ~150 ms cold-start on the first request after a new Cloud Run
-instance boots.
+`gravity=face` detects the highest-confidence face and crops to it with
+sensible padding (50 % of face dimensions on each side, clamped to source
+bounds, keeping the requested aspect ratio). When no face is detected it
+falls back to saliency-based cropping and returns the response with
+`X-Transform-Face: fallback`, so you can tell the two apart. Cost to you:
+~10 ms warm; ~150 ms on the first request after a cold start.
 
 `quality=auto` adapts the per-format quality to source complexity
-(luminance stddev via sharp `.stats()`):
+(the luminance standard deviation of the source):
 
 | Bucket (stddev) | WebP | AVIF | JPEG |
 |---|---:|---:|---:|
@@ -754,7 +756,7 @@ number that does not move.
 
 ### Canonicalization & caching
 
-URLs with the same params in different order share the same R2 cache entry:
+URLs with the same params in different order share the same cache entry:
 
 ```ts
 aq.transform(asset, { width: 480, fit: "contain" })
@@ -766,21 +768,21 @@ aq.transform(asset, { fit: "contain", width: 480 })
 
 The server canonicalizes incoming DSL the same way the SDK does (sort keys
 alphabetically, lowercase string values, drop `undefined`) and hashes the
-canonical string into the R2 cache key — so even non-SDK URLs (e.g. typed
+canonical string into the cache key — so even non-SDK URLs (e.g. typed
 by a developer in a browser bar) collapse onto the same cache entry as long
 as they specify the same params.
 
 ### Signed URLs + strict mode (Phase 3)
 
-Every tenant has an HMAC-SHA256 signing key (`signing_key` column in
-`public.tenants`, 32 random bytes generated on tenant creation).
+Every tenant has an HMAC-SHA256 signing key — 32 random bytes, generated
+on tenant creation.
 Optionally enable `strict_transforms = true` to reject unsigned URLs
 with a 401 — useful when transform URLs leak from a private surface
 (internal admin, b2b portal) and you don't want third parties
 generating arbitrary crops.
 
 ```ts
-const aq = new AquienpzClient({
+const aq = new NitidaClient({
   endpoint:   process.env.AQUIENPZ_URL!,
   apiKey:     process.env.AQUIENPZ_API_KEY!,
   tenantCode: "your-tenant",
@@ -812,16 +814,16 @@ different order accept the same signature.
 ```bash
 # Rotate the signing key — invalidates every URL signed with the old one.
 curl -X POST -H "Authorization: Bearer amk_ad_..." \
-  https://aquienpz-asset-manager.../admin/projects/your-tenant/rotate-signing-key
+  https://api.nitida.gofuture.space/admin/projects/your-tenant/rotate-signing-key
 # → { ok: true, tenantId, code, signingKey: "<64-hex>" }
 
 # Flip strict mode on/off.
 curl -X PATCH -H "Authorization: Bearer amk_ad_..." -H "Content-Type: application/json" \
   -d '{"enabled":true}' \
-  https://aquienpz-asset-manager.../admin/projects/your-tenant/strict-transforms
+  https://api.nitida.gofuture.space/admin/projects/your-tenant/strict-transforms
 ```
 
-**Rotation cost**: cached transform variants on R2 are NOT re-keyed by
+**Rotation cost**: cached transform variants are NOT re-keyed by
 the signature, so they keep serving the same bytes. Only the URLs your
 consumers hold need re-signing. Coordinate the rotation with anyone who
 pre-signs at build time (e.g. SSG / next-build).
@@ -851,13 +853,13 @@ per deployment. What the caller sees:
   and fine detail.
 
 Either way the contract is the same, and the first request is the only one
-that pays. In both cases the route caches the PNG in R2 under the standard
+that pays. In both cases the route caches the PNG under the standard
 `<sha>-t<dslHash>.png` key, so subsequent identical requests are 302
 redirects to the CDN — no inference, no per-image cost. **Always
 forces `format=png`** because the entire point is preserving alpha.
 
 The output is the same dimensions as the source. Chain with `width`
-to resize the cutout in a single request (cached as one R2 entry per
+to resize the cutout in a single request (cached as one entry per
 canonical DSL).
 
 The matting model is server-side and may be swapped for a better one
@@ -872,8 +874,8 @@ Primary use case: building OG cards (1200×630) from portrait listing
 photos, or 1:1 social tiles from 16:9 originals.
 
 ```ts
-// 1200×630 OG card from a portrait listing cover — gutters generated
-// by Flux-Fill Pro, source pasted centered.
+// 1200×630 OG card from a portrait listing cover — the gutters are
+// generated, the source is pasted centered.
 const ogUrl = aq.transform(asset, {
   effect: "genfill",
   width: 1200,
@@ -894,7 +896,7 @@ const tileUrl = aq.transform(asset, {
 outpaint.
 
 **Output defaults to WebP** at q=85 (~150KB for a 1200×630 OG card —
-12× lighter than raw Flux-Fill PNG output). Honors `format=` for
+12× lighter than the raw generated PNG). Honors `format=` for
 explicit overrides:
 
 | Format | Bytes (typical 1200×630) | Use case |
@@ -908,19 +910,18 @@ explicit overrides:
 differs heavily from the source (1:1 from horizontal photo → tiled
 artifacts because the model has to invent rooftops and floors).
 Reserve `genfill` for SMALL aspect deltas (OG card 1200×630 from
-landscape source ✓). For bigger crops, prefer `gravity=auto` smart-crop
-which is deterministic and free (no Replicate cost, no AI invention).
+landscape source ✓). For bigger crops, prefer `gravity=auto` smart-crop,
+which is deterministic and free — no generation, no invention.
 
-Powered by Replicate's `black-forest-labs/flux-fill-pro`. ~$0.05 per
-first request per (sha, dsl, format) tuple; subsequent identical
-requests are 302 redirects to the R2 cache — zero Replicate cost.
-
-Server-side credentials for the generative provider are part of the
-deployment; nothing to provision on your side.
+**What it costs you: ~$0.05 for the first request** per (sha, dsl, format)
+tuple. Subsequent identical requests are 302 redirects to the cached PNG —
+zero generative cost, forever. The model is server-side and may be swapped
+for a better one without any change on your side; the DSL, the output and
+the cache semantics are the contract.
 
 **Short-circuit**: when the source already matches the target aspect
 exactly (resized to fill the canvas with zero padding), the server
-returns the resized PNG without calling Replicate — you don't pay
+returns the resized PNG without generating anything — you don't pay
 $0.05 for an effective no-op.
 
 ### Video transforms (`aq.transformVideo`)
@@ -943,8 +944,8 @@ const portraitUrl = aq.transformVideo(asset, {
 const webmUrl = aq.transformVideo(asset, { format: "webm", width: 1280 });
 ```
 
-**First request is async**. Cache miss → Cloud Run Job runs ffmpeg
-(typically 5-30 s for short clips) → output written to R2. The route
+**First request is async**. Cache miss → a background transcode runs
+(typically 5-30 s for short clips) → the output is stored. The route
 returns **202 Accepted** with `Retry-After: 10` and a `Location`
 header pointing at the eventual CDN URL. The response body has
 `{ status, message, retryAfterSec, outputUrl }`. Subsequent requests
@@ -954,17 +955,16 @@ Consumer pattern with Video.js v10 / `<video>`:
 
 ```tsx
 const src = aq.transformVideo(asset, { width: 1080, height: 1920 });
-// Pass directly to <video src={src} />. While the Job runs the
+// Pass directly to <video src={src} />. While the transcode runs the
 // browser sees 202 → retry; once cached, the 302 → CDN. Most players
 // retry transparently; if yours doesn't, poll `src` every 5 s until
 // `Response.redirected` is true or the body content-type starts with
 // "video/".
 ```
 
-Implementation: extends the EXISTING `asset-processing` Cloud Run Job
-with a `transform-video` op. Reuses the same Cloud Tasks dispatch
-pattern as `process-video` and `compose-slideshow`. Idempotent —
-re-dispatching the same DSL noops if R2 already has the output.
+**Idempotent** — requesting the same DSL again while the first job is
+still running does not start a second one, and does nothing at all once
+the output is cached. Fire and retry freely.
 
 ### Adaptive HLS streaming (`aq.streamingUrl`)
 
@@ -984,9 +984,9 @@ const teaser = aq.streamingUrl(asset, { start: 0, duration: 30 });
 ```
 
 First request to a new HLS URL returns **202 Accepted** with
-`Retry-After: 20` while a Cloud Run Job builds the multi-rung ladder
+`Retry-After: 20` while a background job builds the multi-rung ladder
 (typically 1-3 min for a 90 s source). Subsequent requests get
-**302** to the cached `master.m3u8`. The R2 layout:
+**302** to the cached `master.m3u8`. The CDN layout:
 
 ```
 <tid>/v/<sha>-hls<dslHash>/master.m3u8        ← entry point
@@ -1007,7 +1007,7 @@ either loaded or timed out.
 ### Billing model
 
 Transforms are billed as **storage**, not as "transformations" the way
-Cloudinary does — one R2 PUT per unique canonical DSL, then served from
+Cloudinary does — one stored object per unique canonical DSL, then served from
 the CDN cache forever (until manually invalidated). The cache key is
 deterministic, so identical DSLs across deploys/tenants don't re-encode;
 mounting an existing CDN URL costs zero compute.
@@ -1050,7 +1050,7 @@ The wire format is intentionally tight: `{d, v, m, dv, lv, dm, lm}`
 light-muted). 7 hex strings per asset — much smaller than a full
 base64 LQIP, but composes into nicer ambient UX.
 
-When sharp can't decode the image (SVG sources, exotic formats,
+When the image can't be decoded (SVG sources, exotic formats,
 deliberately corrupted bytes), palette + blur silently come back
 `null`. The rest of the pipeline still succeeds.
 
@@ -1092,9 +1092,8 @@ them — and the same URL never invalidates.
 
 ## Auth
 
-Auth is a Better Auth API key (`amk_rt_*`) emitted by
-`aquienpz/bootstrap-project.ts` per tenant. The key's metadata holds the tenant
-id, so `X-Tenant-Code` is log-only.
+Auth is a bearer API key (`amk_rt_*`), issued per tenant when the tenant is
+created. The key itself carries the tenant id, so `X-Tenant-Code` is log-only.
 
 API key tiers:
 
@@ -1130,7 +1129,7 @@ own tenant (no cross-tenant data ever leaks):
 ```ts
 const usage = await aq.usage.snapshot();
 // {
-//   tenant: { id: 4, code: "realtyone-cr" },
+//   tenant: { id: 4, code: "acme-co" },
 //   storage: { totalBytes: 4_810_000_000, assetCount: 15_760 },
 //   today: { reads: 3201, writes: 18, processes: 6, videoMinutes: 4.5, ... },
 //   last30Days: { reads: 86_400, writes: 412, videoMinutes: 312.75, ... }
@@ -1140,11 +1139,10 @@ const chart = await aq.usage.timeseries(30); // for a 30-day line chart
 const byKey = await aq.usage.keys();         // who's using the most quota
 ```
 
-Backed by the daily rollup of `assets.api_key_usage` →
-`assets.tenant_usage_daily`. The "today" window queries the raw
-`api_key_usage` table since the rollup runs once per day at ~00:30 UTC —
-except `videoMinutes`, which is accumulated live and so is real-time on
-every window.
+`last30Days` is served from a rollup that runs **once per day at
+~00:30 UTC**; the `today` window is computed live off the raw counters, so
+it is current. The exception is `videoMinutes`, which is accumulated live
+and is therefore real-time on **every** window.
 
 **`videoMinutes` counts minutes actually TRANSCODED, not videos stored.**
 It is *source minutes × encode passes*, so a 7-rung HLS ladder over a
@@ -1155,9 +1153,10 @@ or a cache hit runs no encoder and books nothing, so `0` means zero.
 
 > ⚠️ **Removed 2026-08-17:** `bytesIn` (on the usage windows and daily
 > points) and `bytesTotal` (on the per-key rows). They were fed by
-> `api_key_usage.bytes`, which is structurally zero — measured at 440,820
-> rows, none above 0 — and could not be instrumented, because uploads go to
-> R2 through presigned URLs and never traverse the API. A field that always
+> a counter that is structurally zero — measured across 440,820 usage
+> rows, none above 0 — and could not be instrumented, because uploads go
+> to object storage through presigned URLs and **never traverse the API**.
+> A field that always
 > reads `0` is worse than an absent one. The byte figure that is true,
 > `storage.totalBytes`, is unchanged.