@nitida/sdk 0.23.0 → 0.24.1

package/skills/nitida-sdk/SKILL.md

@@ -6,26 +6,18 @@ description: How to consume the nitida media platform (@nitida/sdk + @nitida/ass
 # Consuming the nitida media platform
 
 > **The product is called nitida.** It used to be called *aquienpz*, and that name survives on
-> purpose in three places that were NOT renamed: the GitHub repo (`aquienpz`), the CDN host
-> (`8ok.uk`), and three packages that still publish under `@aquienpz/*` (`tenant-config`,
-> `asset-uploader-web`, `asset-uploader-expo`). Everything else you install or import is
-> `@nitida/*`.
+> purpose in two places that were NOT renamed: the CDN host (`8ok.uk`), and three packages that
+> still publish under `@aquienpz/*` (`tenant-config`, `asset-uploader-web`, `asset-uploader-expo`).
+> Everything else you install or import is `@nitida/*`.
 
-> Durable source of truth: **the published docs at <https://nitida.gofuture.space>** — 187 pages, 166
-> of them generated from the types, so the API reference cannot rot. Agents can download it: the site
+> Durable source of truth: **the published docs at <https://nitida.gofuture.space>** — most of it
+> generated from the types, so the API reference cannot rot. Agents can download it: the site
 > serves `/agents/skill.md`, `/agents/index.json`, `llms.txt` / `llms-small.txt` / `llms-full.txt`,
-> and every page as raw `.md`. Source lives in `apps/nitida-docs`.
->
-> ⚠️ An earlier version of this line pointed at `docs/SDK_CONSUMER_GUIDE.md`. **That file does not
-> exist** (verified 2026-08-17) and did not when the line was written — a citation to nothing is
-> worse than a wrong one, because it sends the reader hunting instead of correcting them. The three
-> other docs this file cites (`ASSET_MANAGER_V2.md`, `CLIENT_OPERATIONS.md`, `TENANT_ONBOARDING.md`)
-> were checked and DO exist. This file is mirrored to `~/.claude/skills/nitida-sdk/SKILL.md` for skill
-> activation; update both when these learnings change.
+> and every page as raw `.md`.
 
-The platform stores assets in R2, is driven through the API **`https://api.nitida.gofuture.space`**
-and serves bytes through the CDN **`https://8ok.uk`**.
-Apps are **external consumers**: install the npm packages, never vendor neo's in-tree copies.
+The platform stores assets in object storage, is driven through the API
+**`https://api.nitida.gofuture.space`** and serves bytes through the CDN **`https://8ok.uk`**.
+Apps are **external consumers**: install the npm packages, never vendor an in-tree copy.
 
 ```bash
 bun add @nitida/sdk @nitida/asset-client
@@ -44,12 +36,11 @@ const nt = new NitidaClient({
 });
 ```
 
-:::note[The old Cloud Run address still works, and always will]
-Until 2026-08-17 the published endpoint was
-`https://aquienpz-asset-manager-nlchzy26qa-uc.a.run.app`. The branded name is an **additional**
-mapping onto the *same* Cloud Run service — same instance, no extra hop, byte-identical responses —
-and Cloud Run keeps a service's generated URL forever. Nothing breaks if you are still on it; point
-new work at `api.nitida.gofuture.space` and move the rest whenever it suits you.
+:::note[An older endpoint you were given still works, and always will]
+Until 2026-08-17 the published endpoint was a longer, generated hostname. The branded name is an
+**additional** mapping onto the *same* service — same instance, no extra hop, byte-identical
+responses — and the older address keeps working indefinitely. Nothing breaks if you are still on
+it; point new work at `api.nitida.gofuture.space` and move the rest whenever it suits you.
 :::
 
 ## 1. Configure once at module load
@@ -92,6 +83,119 @@ Output URL shape: `https://8ok.uk/t/format=webp,width=640/<sha16>.webp`.
 
 ⚠️ **Widths MUST be on the unsigned ladder** `TRANSFORM_WIDTHS` (`160,240,256,320,400,480,600,640,800,960,1080,1200,1280,1440,1600,1920,2560,3840`). Any other width → **HTTP 400** at the edge (DoS guard). The `TransformWidth` type makes an off-ladder width a compile error — import the type, don't hardcode magic numbers. (For a one-off custom width you'd need signed URLs; not used here.)
 
+## 2b. A responsive gallery — the widths, with their measured weight
+
+> Full page, with the reasoning: <https://nitida.gofuture.space/examples/responsive-gallery/>
+> Every claim below is re-checked against production by a scheduled job, so the
+> numbers cannot quietly rot.
+
+**Upload once, serve two ladders.** A phone and a 27-inch monitor need very
+different bytes from the same photo.
+
+```ts
+// ⚠️ `setCdnBase` is NOT re-exported by `@nitida/sdk` (but `setTenantId` is).
+import { setCdnBase, type TransformWidth } from "@nitida/asset-client";
+import { getTransformSrcSet, getTransformUrl } from "@nitida/sdk";
+
+await nt.upload(file, {
+  fileName: "villa-sunset.jpg",
+  presets: ["original", "thumb", "sm", "md", "lg", "xl"],
+});
+```
+
+**Measured** on a 2400×1600 master, WebP `quality=75`:
+
+| width | 400 | 600 | 800 | 960 | **1080** | 1600 | **1920** |
+|---|---|---|---|---|---|---|---|
+| **KB** | 21 | 32 | 56 | 74 | **86** | 123 | **175** |
+
+A phone served `1080` downloads **86 KB**; served `1920` it downloads **175 KB**
+— double the weight for pixels the screen cannot resolve. That is the whole
+speed/quality argument, as a number.
+
+| surface | ask for |
+|---|---|
+| Mobile · 2-col grid | `400`, `480` |
+| Mobile · full screen | `800`, `960`, `1080` |
+| Desktop · grid | `400`, `600`, `800` |
+| Desktop · lightbox | `1600`, `1920` |
+| Full-bleed retina hero | `2560` / `3840` — **only if the master reaches it** |
+
+```tsx
+// Sin `quality`: auto-quality sondea el MÁSTER ⇒ una sola compresión.
+<img
+  src={getTransformUrl(asset, { format: "webp", width: 800 })}
+  srcSet={getTransformSrcSet(asset, [400, 800, 1200, 1600], { format: "webp" })}
+  sizes="(max-width: 768px) 100vw, 40vw"
+/>
+```
+
+⚠️ **Fijate que NO lleva `quality`.** Un `quality` numérico activa el atajo que
+lee una variante ya comprimida — ver la advertencia de abajo. Si de verdad
+necesitás fijarlo (un presupuesto de bytes duro), es un opt-in consciente, no el
+default que se copia sin leer.
+
+**`sizes` is what makes the phone pick 800 and the desktop 1600 from the same
+tag.** Omit it and the browser assumes `100vw`, fetches the large candidate for
+everyone, and the ladder buys you nothing.
+
+- ⚠️ **Do not pass `quality`. Omit the key entirely.** Auto-quality probes the
+  master and compresses once; a numeric `quality` is precisely what switches on
+  the short-circuit that re-compresses an already-compressed variant — see the
+  measurements below. Pinning it is a deliberate opt-in for a hard byte budget,
+  never the default you copy. Format: **WebP** — the DSL accepts `avif`, this
+  platform does not use it.
+- Grid cells: `{ fit: "cover", gravity: "auto" }` — verified to return an exact
+  400×400. Lightbox: `fit: "inside"`, never crops.
+- ⚠️ **There is no upscale — the master is the ceiling.** Measured: a 2400 px
+  master asked for `width=2560` returns **2400 px**. Put widths in the `srcSet`
+  that your sources can sustain.
+- ⚠️ The **first** request of each width is generated cold, then cached at the
+  edge immutably. Warm them after upload if the first visitor matters.
+
+### ⚠️⚠️ On a LADDERED asset, an explicit `quality` compresses the image TWICE
+
+> Full measurements, with the method: <https://nitida.gofuture.space/guides/transform-benchmark/>
+
+`/t/` short-circuits to the smallest **stored variant** that covers the request
+— and that variant is already a WebP
+that went through one lossy pass. **The short-circuit only fires when the
+request carries an explicit numeric `quality`**, so the `quality: 75` above is
+exactly what turns it on.
+
+Measured at `width=800` on five photographs, same photo uploaded twice (full
+ladder vs `["original"]` only):
+
+| | source used | bytes | quality vs master |
+|---|---|---|---|
+| ladder + `quality=75` | `md` (1280 px WebP) | **7–9 % smaller** | **worse 5/5** — up to −3.01 dB PSNR, −0.0200 SSIM |
+| `["original"]` only | `original` | baseline | baseline |
+| ladder, **no `quality`** | `original` | −2.6 % … +4.7 % | better than the pinned arm 5/5 |
+
+Smaller **and** worse is generation loss, not a saving.
+
+- **Want the master's quality? Omit `quality`.** Auto-quality has to probe the
+  full-resolution master, so it cannot take the shortcut.
+- **Raising `quality` does not undo it.** Double-compressed at `quality: 80` is
+  still worse than single-pass at `quality: 60`, and 31 % heavier.
+- **Worst at 640 / 1280 / 1920** — the widths that match `sm`/`md`/`lg` exactly,
+  so there is no downscale in between to hide the first pass. At 640 and 1920
+  the laddered output is *heavier* too.
+- **`["original"]`-only assets are unaffected** — one pass, always.
+
+### What running this recipe caught
+
+Its first draft was written by reading the source, and executing it found two
+errors: `setCdnBase` imported from the wrong package (it failed on the first
+line), and `width=2560` silently returning 2400. **Neither is visible from
+reading the code** — which is why the verification script exists.
+
+A third arrived later, from the benchmark run: the `quality: 75`
+advice above was written without knowing that pinning a numeric `quality` is
+what enables the stored-variant shortcut. The recipe was recommending a second
+lossy pass on exactly the assets it tells you to upload. Reading the source is
+not measuring it.
+
 ## 3. Video URLs — `getAssetUrl(asset, "video")`  ← the #1 gotcha
 
 Videos are served from the **stored variant**, NOT a transform:
@@ -114,7 +218,7 @@ Output: `https://8ok.uk/<tenantId.toString(36)>/v/<sha16>-v.mp4`.
 
 **Audio IS supported (updated 2026-07-01 — verify against the SDK types, this used to say "not supported").** The platform recognizes `kind: "image" | "video" | "document" | "audio" | "other"` and ships an **`mp3`** variant preset (`VariantPreset` in `@nitida/asset-client`). Uploads are hash-deduped (byte-identical re-uploads return the existing sha — that's *byte* dedup, NOT semantic "find a similar track"). `nt.upload` also accepts an `audioTrack` on video-composition calls. Serve via the `mp3` preset / `original`. Confirm the current preset/kind list in `node_modules/@nitida/asset-client/dist/index.d.ts` before relying on a specific ext.
 
-> ✅ **FIXED 2026-08-17 (aquienpz #230/#231): you no longer have to pass `contentType` to avoid
+> ✅ **FIXED 2026-08-17 (#230/#231): you no longer have to pass `contentType` to avoid
 > `kind:"other"`.** This section used to insist on
 > `upload(bytes, { contentType: "audio/mpeg", fileName: "track.mp3" })` as a *defence*. Two
 > independent holes made that necessary and both are closed:
@@ -133,21 +237,17 @@ Output: `https://8ok.uk/<tenantId.toString(36)>/v/<sha16>-v.mp4`.
 > Passing `contentType` + `fileName` is still *good practice* — it is the cheapest possible signal
 > and it decides the stored extension. It is no longer load-bearing.
 >
-> ⚠️ **Against an `asset-manager` older than 2026-08-17 this bug is live**, so code that must run
+> ⚠️ **Against a server deploy older than 2026-08-17 this bug is live**, so code that must run
 > against an old deploy should keep declaring the MIME explicitly. Also note the owner's decision:
 > the **230 rows already misclassified** as `kind:"other"` are NOT being repaired — the fix is
 > forward-only.
 
 ## 3b. Keeping the ORIGINAL bytes (backup, not delivery) ← learned the hard way 2026-08-07
 
-If you are uploading to **archive** something (not just to serve it), three server behaviours decide whether you actually can get the bytes back. All three verified against `apps/asset-manager/src` in the `aquienpz` repo, after a 97-file backup ran "successfully" and produced **zero** recoverable originals.
+If you are uploading to **archive** something (not just to serve it), three server behaviours decide whether you actually can get the bytes back. All three verified against production, after a 97-file backup ran "successfully" and produced zero `original` variants. ⚠️ Those bytes were **not** actually unrecoverable — nobody checked `raw`, which cleanup keeps while the asset row exists (verified 2026-08-17 on a 2-month-old thumb-only asset). The lesson that survives is that *"N uploaded, 0 failed"* measures the upload, not the outcome.
 
-**1. `original` is written only if you ask for it.** In `features/assets/process.routes.ts`:
-
-```ts
-const effectivePresets: string[] = body.presets ?? ["original"];
-const wantsOriginal = effectivePresets.includes("original");
-```
+**1. `original` is written only if you ask for it.** The server's rule is that `presets` defaults to
+`["original"]`, and an `original` variant is written only when that list contains it:
 
 - Omit `presets` entirely → **original only**, no ladder (passthrough).
 - Pass `["thumb"]` → thumb only, **no original**. The bytes you PUT are not retrievable.
@@ -155,12 +255,11 @@ const wantsOriginal = effectivePresets.includes("original");
 
 ⚠️ The migration precedent in consumer repos (`migrate-*-images.ts`) uses `["thumb"]` because its goal is *delivery*. Copying it into a backup script silently produces a non-backup.
 
-**2. Building the `original` URL client-side is possible but easy to get wrong** (this section said "impossible" until 2026-08-15 — see the correction below). The server key is:
+**2. Building the `original` URL client-side is possible but easy to get wrong** (this section said "impossible" until 2026-08-15 — see the correction below). The stored key looks like
 
-```ts
-variantKey(tenantId, sha256, "original", ext)
-  → `${tenantPrefix(tenantId)}/v/${shortenSha(sha)}-o.${ext}`
-//    ext = body.rawKey.split(".").pop()   ← the UPLOADED file's extension
+```
+<tenant id in base36>/v/<sha16>-o.<ext>
+//                                 ↑ the UPLOADED file's extension, not one derived from the mime
 ```
 
 The client's `PRESET_EXT.original` is the literal `"bin"`, so `getAssetUrl({sha}, "original")` **without `mime`** emits `-o.bin` while a PNG is really stored at `-o.png` → 404, always.
@@ -176,8 +275,8 @@ The client's `PRESET_EXT.original` is the literal `"bin"`, so `getAssetUrl({sha}
 > the original was really stored under). `getAssetUrl` prefers the stored URL, falls back to
 > `oext`, and only then guesses from the mime.
 >
-> **Why guessing could never work.** The server keys the original off the **uploaded filename**
-> (`rawKey.split(".").pop()`), which the mime does not determine. Measured over the 2 001 stored
+> **Why guessing could never work.** The server keys the original off the **uploaded filename's
+> extension**, which the mime does not determine. Measured over the 2 001 stored
 > originals in production: all **420** `image/jpeg` originals are `.jpg` and none are `.jpeg`, so
 > the old mime table 404'd on every JPEG; and **234** originals are `application/octet-stream`
 > (`.mpga`, `.docx`, `.m4a`), where no mime table can ever produce the right key.
@@ -186,9 +285,8 @@ The client's `PRESET_EXT.original` is the literal `"bin"`, so `getAssetUrl({sha}
 > field on every response shape), and `getAssetUrl` was always correct for `video`/`poster`, whose
 > extensions are fixed.
 >
-> ⚠️ **Against an `asset-manager` older than 2026-08-17**, `variants` is `[]` and `oext` is absent
-> — the mime guess is all you have, so HEAD the URL before relying on it. Reference implementation
-> of the old dance: `apps/media-harness/scripts/seed-fixtures.ts` (`resolveOriginalUrl`).
+> ⚠️ **Against a server deploy older than 2026-08-17**, `variants` is `[]` and `oext` is absent
+> — the mime guess is all you have, so HEAD the URL before relying on it.
 
 **3. Re-uploading does NOT repair a missing preset.** Ingest dedupes by hash and returns `deduped: true` with the existing asset; no variants are regenerated. To add a preset to an existing asset use `regenerate`, which MERGES:
 
@@ -196,9 +294,35 @@ The client's `PRESET_EXT.original` is the literal `"bin"`, so `getAssetUrl({sha}
 await nt.assets.regenerate(assetId, { presets: ["original"] });
 ```
 
-⚠️ **There is a time window.** `admin.routes.ts` notes that once the cleanup job reaps `raw/`, regenerate reads from `variants/o.<ext>` — which is exactly what's missing. **If the first ingest didn't request `original`, the raw bytes may already be unrecoverable.** In the 2026-08-07 run, `regenerate({presets:["original"]})` returned without error and the `original` variant still did not appear — consistent with `raw/` already being gone. Get `original` right on the FIRST ingest.
+⚠️ **Elegir mal `presets` NO destruye nada — pero rompe una API y no la otra.** Verificado
+2026-08-17 contra producción, sobre un asset del **16-jun** con `presets:"q"` (sólo miniatura):
+**su `raw` sigue existiendo (HTTP 200), dos meses después.**
+
+La limpieza conserva el `raw` de **cualquier** sha referenciado por una fila de asset, incluidas las
+borradas en suave. **Mientras exista la fila, los bytes originales están.**
 
-**Verify, don't assume.** Round-trip every archived file: download the `original` URL from the API and compare its SHA-256 to the local file. "97 uploaded, 0 failed" was true and meaningless — all 97 were unrecoverable.
+⇒ lo que realmente pasa si pediste `["thumb"]` y necesitabas la escalera:
+
+| lo que llamás | qué obtenés |
+|---|---|
+| `getAssetUrl(asset, "md")` | **404** — esa variante nunca se generó |
+| `/t/…width=1280/<sha>.webp` | **200** — se genera al vuelo desde el raw |
+| `hasPreset(asset, "lg")` | `false`, correctamente |
+
+Una API te dice que no existe y la otra te la entrega. **Eso** es lo caro: no la pérdida, la
+incoherencia — más un cómputo en frío la primera vez que alguien pide cada tamaño.
+
+**Se arregla en cualquier momento** con `regenerate({presets:[...]})`, que lee del raw. No hay
+ventana que se cierre.
+
+> ⚠️ **CORREGIDO 2026-08-17. La versión anterior de este párrafo decía que «los bytes del raw pueden
+> ya ser irrecuperables» si la primera ingesta no pidió `original`.** Era falso, y venía de una
+> hipótesis escrita como diagnóstico: la corrida del 2026-08-07 observó que `regenerate` no producía
+> el `original` y concluyó *«consistent with `raw/` already being gone»*. Nadie comprobó el raw. Al
+> comprobarlo, está. Lo que sí sigue en pie de esa corrida es la disciplina de abajo.
+
+**Verify, don't assume.** Round-trip every archived file: download the `original` URL from the API
+and compare its SHA-256 to the local file. "97 uploaded, 0 failed" was true and meaningless.
 
 | Goal | presets | Where the URL comes from |
 |---|---|---|
@@ -219,7 +343,7 @@ before the `includes`. **`hasPreset(dto, preset)` remains the recommended existe
 the only field present on every response shape, including the slim list/resolver one that carries no
 `variants` at all.
 
-⚠️ **Against an `asset-manager` older than 2026-08-17 the contaminated strings are still being sent**
+⚠️ **Against a server deploy older than 2026-08-17 the contaminated strings are still being sent**
 (62 % of live rows had one). The client-side strip covers you; a hand-rolled
 `dto.presets.includes("o")` does not.
 
@@ -261,7 +385,7 @@ covers it: native if the engine is Apple's **OR** if there is no MSE to fall bac
 **When you use hls.js, stop it guessing** — the defaults are how a fast connection still opens at
 240p: `{ startLevel: -1, testBandwidth: true, abrEwmaDefaultEstimate: 1_000_000 }`.
 
-**The first request can answer `202`** while the Cloud Run Job builds the ladder (1–3 min for a
+**The first request can answer `202`** while the background job builds the ladder (1–3 min for a
 90 s source), then `302`s to the cached master. Keep the progressive MP4 as the fallback `<source>`
 so a player pointed at HLS too early still shows something.
 
@@ -289,15 +413,14 @@ step down to. **HLS = many files**: the same video cut into segments and encoded
 so the player switches mid-playback. That is the whole difference, and it is why only one of them
 can carry 4K.
 
-The ladder is not fixed at 1080p — the job probes the source and keeps every rung that fits
-(`LADDER.filter(r => r.height <= srcHeight)`, up to **2160p**). What it probes decides the ceiling:
+The ladder is not fixed at 1080p — the job probes the source and keeps every rung that fits, up to **2160p**. What it probes decides the ceiling:
 
 | Ladder built | Source | Ceiling |
 |---|---|---|
 | At ingest (automatic, unless `video.hls === false`) | the raw bytes you uploaded | **2160p from a 4K master** |
 | On demand later | the raw if present, else the `-v.mp4` | 1080p, second-generation |
 
-The progressive MP4 is capped unconditionally (`scale='min(1920,iw)'`), so `getAssetUrl(sha,"video")`
+The progressive MP4 is capped unconditionally at 1920 wide, so `getAssetUrl(sha,"video")`
 never exceeds 1080p whatever you uploaded. A rung that weighs *more* than its own source (measured:
 5090 vs 4866 kbps) is the signature of the fallback path, not of a broken ladder.
 
@@ -314,7 +437,7 @@ A robust app resolver tries, in order: an explicit `sha` on the row → a migrat
 
 ## 5. Migrating an app OFF a legacy CDN onto nitida
 
-Pattern proven on carniceria, novatibas, sueños (all off `cdn.espaciofuturo.io`):
+Pattern proven on three storefronts moved off the same legacy CDN:
 
 1. **Re-ingest is required, not a host rename.** Legacy hashes (64-hex sha256) ≠ nitida (16-hex sha). You must **fetch each legacy asset's bytes and re-upload** to the tenant (SDK server client + `amk_rt_*` key), producing a NEW sha. Emit an idempotent `old-URL → { sha, w, h, blur, kind }` map (`scripts/asset-migration-map.json`). Upload presets: images→`thumb`, videos→`poster`+`video`. Dedupe by sha; checkpoint (re-runnable).
 2. **Regenerate metadata** (`blur`/`w`/`h`/`aspectRatio`) from the uploaded asset (`assets.get`) — don't carry legacy values.
@@ -328,17 +451,15 @@ Pattern proven on carniceria, novatibas, sueños (all off `cdn.espaciofuturo.io`
 Google). *Tenants → New* creates the tenant rows, and the tenant's page **issues, shows and rotates**
 its runtime / admin / CI keys. A key's secret is displayed **once**, at issue time — store it then.
 
-That replaces `apps/asset-manager/scripts/bootstrap-project.ts` and the hand-written SQL that used to
-live here. The point is not convenience: **provisioning no longer requires the production database
-URL** (`PLATFORM_DATABASE_URL`) or `ASSET_AUTH_SECRET` on somebody's laptop. Reach for the script
-only if the console is down, and treat that as an incident, not a workflow.
+That replaces the older hand-run provisioning scripts and SQL that used to live here.
 
-- Endpoint = `https://api.nitida.gofuture.space` (the Cloud Run generated URL keeps working — see the
-  note at the top). Verify a fresh tenant: `GET /usage` with `Authorization: Bearer <amk_rt_*>` +
+- Endpoint = `https://api.nitida.gofuture.space` (an older endpoint you were given keeps working —
+  see the note at the top). Verify a fresh tenant: `GET /usage` with `Authorization: Bearer <amk_rt_*>` +
   `X-Tenant-Code: <code>` → `{ "tenant": { "id": N } }`.
 - The `@aquienpz/tenant-config` HTTP layer (still published under the old scope) **caches tenant
   lookups for 60s** — a fresh tenant resolves in services within a minute.
-- Asset-only consumers (a storefront with its own catalog DB) can skip the Qdrant/voice/scraper steps in `docs/TENANT_ONBOARDING.md` — only the two tenant rows + keys + `storefront_origins` are needed.
+- Asset-only consumers (a storefront with its own catalog DB) need only the tenant rows, its keys and
+  its allowed origins; see <https://nitida.gofuture.space/start/credentials/>.
 
 ## Quick reference
 
@@ -355,41 +476,51 @@ Variant preset short codes: `thumb=q, sm=s, md=m, lg=l, xl=x, original=o, poster
 
 ## 7. Browser-direct uploads — three things that only fail in a real browser
 
-Measured 2026-08-15 building `neo/apps/media-harness`, the bench for this SDK. Run it
-(`bun run scripts/verify-run.ts`) before debugging any of these by hand.
+Measured 2026-08-15 on the public bench at <https://media-harness.vercel.app> — no credentials
+needed. Reproduce there before debugging any of these by hand.
 
-1. **The PUT goes browser → R2, so R2 answers the CORS preflight.** An origin missing from the
-   BUCKET's policy cannot be fixed in your app, in this SDK, or in `tenant_config.storefront_origins`
-   — those govern the API, not the PUT. Symptom: `R2 PUT failed: network error` with compression,
-   hashing and presign all green. Fix in `aquienpz/scripts/setup-r2-cors.sh`, and ⚠️ `cors set`
-   **REPLACES** the whole policy — list it and diff before applying.
+1. **The PUT goes browser → object storage directly, so the STORAGE BUCKET answers the CORS
+   preflight** — not the API. An origin missing from the bucket's policy therefore cannot be fixed
+   in your app, in this SDK, or by the API's allowed-origins setting: those govern the API, not the
+   PUT. Symptom: the direct PUT fails with a bare network error while compression, hashing and
+   presign are all green. **This one is ours to fix — ask us to add your origin to the bucket
+   policy.**
 2. **A VIDEO answers `processAndWait` immediately, then transcodes.** `/assets/process` dispatches a
-   Cloud Run Job and answers `{ ok: true, kind: "video", assetId, status: "processing", dispatch }`;
+   background job and answers `{ ok: true, kind: "video", assetId, status: "processing", dispatch }`;
    the SDK then polls that id until `ready`. Budget for it — a transcode plus the HLS ladder runs
    1–2 min, so pass a `timeoutMs` of at least `300_000`. (Until 2026-08-16 the response carried **no
    `assetId`** and the call threw `"process returned no assetId"`, so no video ever registered
-   through the kit; the bytes still reached R2, which is what made it invisible.)
+   through the kit; the bytes still reached storage, which is what made it invisible.)
 3. **A video never gets an `original` variant.** `/assets/process` filters video presets through
    `{poster, video, aiproxy, probe}` before dispatch, so `"original"` is silently dropped even when
    you ask for it. If you need the source bytes back, archive them under a **non-video key** (e.g.
    `clip.mp4.bin`), which takes the passthrough branch and stores them verbatim.
 
+   ⚠️ **CORRECTED 2026-08-17 — you do NOT need to upload it twice.** The
+   `original` *variant* is dropped, but the raw upload is kept and
+   **`dto.rawUrl` serves the master**. Verified on a production video:
+   **9 197 163 B, `video/mp4`, 200**, range-capable — and *smaller* than the
+   deliverable `video` variant (15 875 972 B). Cleanup keeps `raw/` while an
+   asset row exists.
+
 | Symptom | Cause |
 |---|---|
 | **400** on an image URL | width not on `TRANSFORM_WIDTHS` ladder |
 | **410** on a video URL | used `/t/` (transform) for a stored video — use `getAssetUrl(...,'video')` |
 | **404** on a video URL | decimal tenant prefix (`/10/v/`) instead of base36 (`/a/v/`) — call `setTenantId` + `getAssetUrl`. Tenant 12 → `/c/v/` |
-| `process returned no assetId` | fixed 2026-08-16 — you are on an `asset-manager` older than that deploy, §7.2 |
+| `process returned no assetId` | fixed 2026-08-16 — you are on a server deploy older than that, §7.2 |
 | `waitReady timeout` on a video | a transcode + HLS ladder takes 1–2 min; the default `timeoutMs` is 5 min but a 4K source can beat it. Raise it, §7.2 |
-| `R2 PUT failed: network error` | your origin is not in the R2 BUCKET's CORS policy, §7.1 |
-| `nt.assets.variants()` returns `[]` | fixed 2026-08-17 (#225) — you are on an `asset-manager` older than that deploy. Existence from `dto.presets` + `hasPreset` works on every version |
+| the direct PUT fails with a bare network error | your origin is not in the storage bucket's CORS policy — ours to fix, §7.1 |
+| `nt.assets.variants()` returns `[]` | fixed 2026-08-17 (#225) — you are on a server deploy older than that. Existence from `dto.presets` + `hasPreset` works on every version |
 | `hasPreset` says a preset exists and its URL 404s | fixed 2026-08-17 (#228) — an old server sends multi-char tokens in `presets`; a current `@nitida/asset-client` strips them, a hand-rolled `includes` does not, §3b-bis |
 | `tenant_not_found` from a service | tenant rows missing, or the 60s tenant-config cache is stale |
 | `original` 404s | (a) never written — `presets` omitted `"original"` at ingest, or the asset is a VIDEO (always dropped, §7.3); (b) `getAssetUrl` called with a bare `{sha}` → the `-o.bin` sentinel; (c) called with `{sha, mime}` against an old server, so it guessed the extension. Pass the whole DTO from `nt.assets.get(id)` — see §3b |
 | "uploaded OK" but nothing to restore | `["thumb"]`-style presets store no original; verify by SHA-256 round-trip, not by upload count — see §3b |
-| audio stored as `kind:"other"` | fixed 2026-08-17 (#230/#231) — the ext→mime round-trip lost `.mpga`, and untyped bytes are now sniffed. Against an older `asset-manager`, upload with an explicit `contentType:"audio/mpeg"`. Rows misclassified **before** the fix stay that way by decision, §3 |
+| audio stored as `kind:"other"` | fixed 2026-08-17 (#230/#231) — the ext→mime round-trip lost `.mpga`, and untyped bytes are now sniffed. Against an older server deploy, upload with an explicit `contentType:"audio/mpeg"`. Rows misclassified **before** the fix stay that way by decision, §3 |
 
-> Source of truth for deeper detail: `docs/ASSET_MANAGER_V2.md`, `docs/CLIENT_OPERATIONS.md`, `docs/TENANT_ONBOARDING.md`, and `packages/asset-client/src/{transform.ts,index.ts}`.
+> Source of truth for deeper detail: the published docs — <https://nitida.gofuture.space/guides/advanced/>,
+> <https://nitida.gofuture.space/guides/troubleshooting/>, <https://nitida.gofuture.space/start/credentials/> —
+> and the API reference at <https://nitida.gofuture.space/api/>, generated from the shipped types.
 
 ## 8. The rest of the surface — the gaps this guide used to have
 
@@ -408,7 +539,7 @@ await nt.upload(file, { presets: ["original", "thumb", "md", "lg"] });
 | MIME | path | result |
 |---|---|---|
 | `image/*` | ladder | WebP variants + palette + dimensions |
-| `video/*` | Cloud Run Job | poster · mp4 · HLS · optional `aiproxy`/`probe` |
+| `video/*` | background job | poster · mp4 · HLS · optional `aiproxy`/`probe` |
 | `audio/*` | inline transcode | `mp3` variant (mono ~96 kbps) **+** untouched original |
 | anything else | **passthrough** | raw bytes under `original`, `ready` immediately |
 
@@ -443,8 +574,8 @@ MDN compat data: `canvas.toBlob(type="image/webp")` is **unsupported in
 Safari**, macOS included; every iOS browser is WebKit, so all inherit it.
 Measured iOS 27 / Chrome 151, 9.1 MP photo: `2.05 MB → 743.7 kB` as `jpeg`.
 
-**Delivery is WebP regardless** — the server re-encodes every variant with
-sharp. The fallback only costs upload bytes (measured: WebP is **41% smaller**
+**Delivery is WebP regardless** — the server re-encodes every variant. The
+fallback only costs upload bytes (measured: WebP is **41% smaller**
 than JPEG at the same quality) and leaves the archived `original` as JPEG.
 
 ### 8e. Palette — free, synchronous, on the DTO
@@ -484,6 +615,6 @@ pipelines get the process OOM-killed on low-end Android, not finished sooner.
 
 ### 8i. Failure isolation
 
-Only object storage is a hard dependency. Cloud Run down → video stays
+Only object storage is a hard dependency. Transcode service down → video stays
 `processing`, images fine. Webhooks down → **nothing**; they are fire-and-forget
 so an upload never fails because a consumer was unavailable.