From bc832277bd29548a5ac71bdfb7c347333daffd72 Mon Sep 17 00:00:00 2001
From: raz <konforti@gmail.com>
Date: Mon, 14 Sep 2026 17:39:12 +0300
Subject: [PATCH 1/3] Add the cloudinary-video skill
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Covers building video experiences on the Cloudinary Video Player —
adaptive streaming, chapters, captions, transcripts, hotspots and AI
analysis — plus migrating media in from Brightcove, Vimeo, YouTube and
Wistia.

The skill ships with the claim tests it was built against. They assert
the load-bearing factual claims (transformation behaviour, async output
shapes, player distribution, source-platform limits) against live
endpoints, so a claim going stale fails loudly rather than misleading an
agent. The default mode needs no credentials; --cloud additionally
provisions a cloud and needs media fixtures via MEDIA_DIR, which are too
large to vendor here.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 README.md                                     |   1 +
 skills/cloudinary-video/SKILL.md              | 697 ++++++++++++++++++
 .../references/build-patterns.md              | 198 +++++
 .../references/capabilities.md                | 258 +++++++
 .../references/field-guide.md                 | 122 +++
 skills/cloudinary-video/references/gotchas.md | 250 +++++++
 skills/cloudinary-video/references/player.md  | 306 ++++++++
 .../references/source-platforms.md            | 125 ++++
 skills/cloudinary-video/test/lib.sh           |  56 ++
 skills/cloudinary-video/test/skill-claims.sh  | 283 +++++++
 10 files changed, 2296 insertions(+)
 create mode 100644 skills/cloudinary-video/SKILL.md
 create mode 100644 skills/cloudinary-video/references/build-patterns.md
 create mode 100644 skills/cloudinary-video/references/capabilities.md
 create mode 100644 skills/cloudinary-video/references/field-guide.md
 create mode 100644 skills/cloudinary-video/references/gotchas.md
 create mode 100644 skills/cloudinary-video/references/player.md
 create mode 100644 skills/cloudinary-video/references/source-platforms.md
 create mode 100644 skills/cloudinary-video/test/lib.sh
 create mode 100755 skills/cloudinary-video/test/skill-claims.sh

diff --git a/README.md b/README.md
index c9fe919..125f378 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,7 @@ The agent skills in this package help your AI coding assistant write correct Clo
 | `cloudinary-transformations` | Turns natural language image and video transformation requirements into valid URL transformation strings that follow Cloudinary best practices. Use when building delivery URLs, applying transformations, optimizing media, or debugging transformation syntax errors. |
 | `cloudinary-react` | Provides opinionated React SDK patterns for configuration, common integration scenarios, and troubleshooting for frequent errors and TypeScript pitfalls. Use when developing React apps with Cloudinary. |
 | `cloudinary-next` | Provides opinionated Next.js SDK patterns for Server and Client Component boundaries, server-side uploads and deletes, and troubleshooting for frequent errors and TypeScript pitfalls. Use when developing Next.js apps with Cloudinary. |
+| `cloudinary-video` | Builds video experiences on the Cloudinary Video Player — adaptive streaming, chapters, captions, transcripts, hotspots, and AI analysis — and migrates media onto Cloudinary from Brightcove, Vimeo, YouTube, or Wistia. Use when building or improving a video site on Cloudinary. |
 
 ## Install
 
diff --git a/skills/cloudinary-video/SKILL.md b/skills/cloudinary-video/SKILL.md
new file mode 100644
index 0000000..4e0834a
--- /dev/null
+++ b/skills/cloudinary-video/SKILL.md
@@ -0,0 +1,697 @@
+---
+name: cloudinary-video
+description: Build websites with the Cloudinary Video Player — adaptive streaming, chapters, captions, transcripts, hotspots, AI analysis and metadata — on an existing Cloudinary cloud, or migrating the media on first. Use when building or improving a video experience on Cloudinary, moving video off Brightcove, Vimeo, YouTube or Wistia, or standing up a cloud for a demo.
+license: MIT
+metadata:
+  author: cloudinary
+  version: '2.1.0'
+---
+
+# Building video sites on Cloudinary
+
+Covers what the published `cloudinary-transformations` and `cloudinary-docs`
+skills do not: **the video player, the async AI features, provisioning, and
+getting existing media onto a cloud.** Those skills handle transformation URLs.
+Use them for that; use this for everything else.
+
+## How to use this
+
+You are helping someone reach a goal for their video experience, not applying a
+checklist. So:
+
+- **Ask when the answer changes the build.** The delivery branch, where the
+  media comes from, which cloud it lands on, whether an add-on exists — a wrong
+  guess here costs a whole run. One question beats an assumption. The questions
+  worth asking up front are in *Start here* below.
+- **Ask when you are unsure.** That is legitimate and always preferable to
+  quietly picking a default and presenting it as the decision. Say what you
+  would pick and why, then let them redirect.
+- **Recommend, don't enumerate — in conversation.** Where this skill gives
+  options, pick the one that fits and say so in a line. Spend their attention
+  on the thing you built, not on a tour of the choices behind it.
+- **But build generously.** The restraint is in what you *say*, never in what
+  you ship. Build the full experience — chapters, transcript, captions, AI
+  poster, preview loops, structured data, responsive delivery — not a minimum
+  viable one. Deleting a feature they do not want takes a minute; never seeing
+  it means they never knew to ask. Err toward the wow — but the wow is the
+  experience working, never the page advertising how it works. Ship their site,
+  not an exhibit about Cloudinary; see *Ship the site, not the demo
+  scaffolding* in [references/build-patterns.md](references/build-patterns.md).
+- **Say what is not there.** A missing add-on, an unreachable original, a
+  feature Cloudinary does not generate — name it plainly and move on. Silence
+  and approximation both cost more later.
+
+The work has two phases, and the first one is often skipped:
+
+- **Phase A — establish the assets.** Only needed if the media is not already
+  on a Cloudinary cloud.
+- **Phase B — build the site.** The substance: optimization strategy, player
+  capabilities, analysis and metadata.
+
+## Start here: get the intent, then the logistics
+
+Do not begin until you know what they are building. Each answer below changes
+the work substantially, so **ask for any you were not given** — one question
+costs a message, a wrong guess costs a run.
+
+**1. What are you building, and what should the video do there?**
+
+The one question the rest depends on. A product-page loop, a long-form library,
+a course, a news page and a landing hero want different delivery, different
+player features and different page shapes. Get this and most later choices
+follow; skip it and you will build a competent version of the wrong thing.
+
+**Do not interview them about features.** Do not ask whether they want
+captions, chapters, transcripts or hover previews — build them. Someone
+describing what they want in chat should get the magic without being asked to
+specify it, and should see everything Cloudinary can do for them before
+deciding what to keep.
+
+**2. Do you have an existing website or app — is this a migration or from
+scratch?**
+
+A migration gives you three things at once: the media, the conventions to match
+(layout, naming, structure), and human-authored metadata worth more than
+anything regenerated — see A2. From scratch, the builder supplies the sources;
+do not go looking.
+
+**3. Are the assets already on a Cloudinary cloud?**
+
+Yes → **skip phase A entirely.** Go to phase B. Confirm the cloud name, how you
+reach it (MCP or `CLOUDINARY_URL` — see the routing table in
+[references/capabilities.md](references/capabilities.md)), and which public IDs
+to build against. Do not re-upload assets that are already there.
+
+No → migration is needed, so:
+
+**4. Where are the resources?**
+
+| Source | What it means |
+| --- | --- |
+| **An existing website** | Try to fetch it for them; otherwise ask them to provide or map it. The site is also your source of guidelines and mapping — see below. |
+| **From scratch** | The builder provides the asset sources. Do not go looking; ask. |
+
+**A named real site is never a cue to reach for Cloudinary's `demo` cloud or
+any other stock/sample assets.** If the user names a real site or brand
+("build a page for gap.com"), you must actually open that site and pull its
+real images/video before writing any page code — do not silently substitute
+placeholder assets because fetching feels slower or the site has no obvious
+video element. Only fall back to demo/stock assets if, after actually trying,
+the real assets are genuinely unreachable (login-gated, blocked, no usable
+media) — and even then, say so explicitly and ask the user before
+substituting anything. Silently swapping in demo-cloud assets for a named
+brand is the single failure mode this rule exists to prevent.
+
+**5. Where does it land — an existing cloud, or a new claimable one?**
+
+| Destination | Consequences |
+| --- | --- |
+| Their **existing cloud** | No provisioning. No claim URL. Respect existing folders, naming and presets. Re-runs cost real quota and can overwrite live assets — be idempotent, and never loop the catalogue to probe. |
+| A **fresh claimable cloud** | Provision it (below). Expect no add-ons. Surface the claim URL at the end. Provision a new one per test run. |
+
+Local files into an existing cloud is a legitimate combination — source and
+destination are independent choices.
+
+**Detect what you can, ask what you cannot.** Duration, whether there is an
+audio track, resolution and which add-ons a cloud has are all measurable —
+`ffprobe` the source, probe one asset. Do not spend a question on something you
+can check, and do not guess at something you cannot.
+
+---
+
+# Phase A — establish the assets
+
+## A1. Get the originals
+
+**Find the video in the raw HTML, not in a browser's DOM.** `curl` the page
+and grep the source *first*:
+
+```sh
+curl -s -A "<a real desktop UA>" "<page url>" -o page.html
+grep -oE '[A-Za-z0-9_-]+\.(mp4|m3u8|webm|mov)' page.html | sort -u
+```
+
+**Do not conclude "this site has no video" from `document.querySelectorAll`.**
+An automated/headless browser's DOM is systematically *less complete* than
+what a real user sees, and it fails silently — you get a clean empty array,
+not an error:
+
+- On a React/Next.js site the `<video>` element is often created by
+  client-side hydration. The asset URL sits in the server-rendered JSON
+  payload (`__NEXT_DATA__`, RSC flight data, inline `<script>` state) while
+  the raw HTML contains **zero** `<video` tags. If hydration doesn't complete,
+  the element never exists to be queried.
+- Bot-detection layers (Akamai, Cloudflare, PerimeterX) serve automated
+  browsers a degraded page. `document.readyState === "complete"` still
+  reports complete — completeness of the *document* is not completeness of
+  the *content*.
+- A tell-tale sign you are looking at a hydrated-only element: its class is a
+  runtime-generated hash (`sitewide-ekvlu4`, `css-1a2b3c`) that appears
+  nowhere in the raw HTML.
+
+This is a real, observed failure: on gap.com the served HTML carried six
+`.mp4` URLs in its JSON payload and the driven browser reported **zero**
+video elements — after waiting for idle, after a shadow-DOM-piercing search,
+and at desktop viewport width. The grep above found all six instantly.
+
+Then, to catch what the source grep cannot (assets requested only at
+runtime):
+- Scroll the whole page and let it idle — some clips lazy-load.
+- List **every** network request, not just ones pre-filtered by extension —
+  a plain `<img src="...">` can return a `video/mp4` response.
+- Check more than one page type — homepage, campaign/collection, and product
+  detail each carry different media.
+
+Confirm any URL you find with `curl -sIL <url>` and read the `content-type`
+before trusting it. Only if all of that comes back empty may you say the site
+has no video — and then ask before falling back to placeholder assets (see
+the rule above on named real sites).
+
+**Never ingest what the website delivers.** A page serves a player embed backed
+by transcoded adaptive renditions. Ingest that and Cloudinary transcodes a
+transcode — quality is permanently capped below the original and every derived
+variant inherits the loss. Get the master from the source platform or the
+customer's own storage.
+
+This is the rule that decides whether a migration is worth anything. Full
+per-platform detail, verified, in
+[references/source-platforms.md](references/source-platforms.md):
+
+| Platform | Original retrievable? |
+| --- | --- |
+| Wistia | Yes — `medias#show` → `OriginalFile` asset |
+| Brightcove | Yes, but **not** via `/videos/{id}/sources` (those are renditions). Needs the Social Syndication master feed, and the master may have been deleted. |
+| Vimeo | Yes, but plan-gated and the field carrying the true original is undocumented — verify, do not guess |
+| YouTube | **No API path.** Google Takeout or the customer's masters |
+
+Graduated fallback when you cannot fetch: **fetch → ask them to provide → ask
+them to map.** All three are legitimate outcomes. Silently substituting a
+scraped rendition is not.
+
+Prefer download-then-upload over Cloudinary remote fetch: source URLs expire and
+are authenticated, and on an unclaimed cloud Cloudinary's own fetcher is blocked
+by the delivery IP allow-list anyway.
+
+`ffprobe` what you downloaded before uploading — resolution, bitrate, and
+whether an audio stream exists at all. That last one decides whether
+transcription and chaptering can work.
+
+## A2. Mine the existing site for guidelines and mapping
+
+When migrating from an existing website, the site is an **input to the build**,
+not just a media source. Three things to take from it:
+
+- **Structure and conventions** — layout, look, naming, how pages are
+  organized. You are improving their page, not replacing it with yours.
+- **Human-authored metadata** — captions, chapter lists, titles, descriptions,
+  tags. **Prefer these over regenerating.** A caption a human wrote and paid for
+  beats `auto_transcription` output. Source platforms often carry cue points and
+  custom fields that already hold the chapter→product bindings Cloudinary cannot
+  infer.
+- **The old→new mapping** — old asset/embed reference to new public ID. This is
+  what makes rewiring mechanical and verifiable rather than a hunt.
+
+Say what had no Cloudinary equivalent rather than approximating it.
+
+## A3. Provision a cloud (fresh-cloud destinations only)
+
+```sh
+npx @cloudinary/cloud --goal "<what you are building>" --model <your-model-id>
+```
+
+No signup, no credentials. Writes `CLOUDINARY_URL` to `./.env` and prints a
+**claim URL** a human can open later to keep the account.
+
+- `--ip <address>` — public IP allowed to view delivered media, repeatable, max
+  3. **Leave it off unless you know better**: the default locks delivery to the
+  calling address, which is almost always right. Getting this wrong is the main
+  way a migration appears to succeed while every asset 404s — uploads are never
+  IP-restricted, only CDN delivery.
+- `--json` — machine-readable, including `claim_url` and `expires_at`
+- `--no-env` — print credentials instead of writing `.env`
+
+**The cloud expires 24 hours after provisioning** unless claimed. Surface the
+claim URL at the end; it is what makes the work permanent. Never commit `.env`.
+
+**Provision a new cloud for every test run.** Reusing one skips exactly the work
+most likely to break, because it only breaks the first time: assets are already
+uploaded, async analysis already reports `complete` rather than `pending`, and
+derivations are warm so nothing returns 423. The clouds are free and expire on
+their own.
+
+If provisioning fails with `delivery_ips_not_public`, the connection is behind a
+VPN or secure gateway. That is the user's to resolve — see
+[references/gotchas.md](references/gotchas.md).
+
+## A4. Upload, and trigger analysis on the way in
+
+Ask for the AI features **on the upload call**. Re-running them afterwards costs
+a second operation against a quota.
+
+```
+upload video:                    # free
+  auto_transcription: true       # transcript + captions
+  auto_chaptering: true          # chapter VTT
+  auto_video_details: true       # title + description
+
+then, separately, and tolerate failure:
+  auto_transcription: { translate: ['es','fr'] }   # needs Google Translation
+  categorization: 'google_video_tagging'           # needs that add-on
+```
+
+`translate` is the add-on part, not transcription itself. Requesting
+`auto_transcription` **with** `translate` on a cloud without Google Translation
+fails the **whole** transcription — no transcript, no captions — where plain
+`auto_transcription` would have succeeded.
+
+`auto_video_details` is worth requesting here rather than leaving to the player.
+The player's `title: true` / `description: true` read the asset's context
+metadata and only trigger generation if no value is found — so an
+un-pre-generated title is a request happening for the first time mid-demo.
+
+```
+upload image:                    # free
+  (no analysis parameters)
+
+then, separately, and tolerate failure:
+  categorization: 'google_tagging'
+  auto_tagging: 0.65             # needs Google Auto Tagging
+```
+
+Know what image tagging returns before building on it: it describes **what is in
+the frame**. A hotel room yields `bed`, `bedding`, `ceiling`, `lamp` — accurate,
+and not what a guest filters by. Commercial attributes like "ocean view" are not
+visible to an image model. Use it for library search and coverage, not as a
+replacement for curated facets.
+
+### Upload rules that have bitten real runs
+
+1. **Upload with only the free features first.** Requesting a subscribed-only
+   add-on rejects the whole upload — the asset is never stored — which looks
+   like a broken upload rather than a missing entitlement.
+2. **Then try add-ons separately**, and treat failure as expected.
+3. **Add-ons cannot be enabled by an agent.** It is a console action, which on a
+   claimable cloud means claiming it first. No Admin API exists: `/addons`,
+   `/add_ons`, `/subscriptions`, `/entitlements` all 404.
+4. **An account-level upload preset can rewrite every asset on ingest** — adding
+   a watermark, downsizing — injected into signed uploads whether you ask or
+   not. Pass an explicit clean `upload_preset`. See
+   [references/gotchas.md](references/gotchas.md).
+5. **Overwriting a public ID can silently keep the old asset.** If a re-upload
+   reports new dimensions but delivery serves the old file, change the path.
+
+**Say which features are missing and why.** A run that silently drops translated
+subtitles has misled the user; one that says "translated subtitles need the
+Google Translation add-on, which needs the cloud claimed first" has not.
+
+## A5. Wait for the async features
+
+`auto_transcription`, `auto_chaptering` and title/description return
+`status: "pending"` and finish later — **or return `status: "failed"`**. Poll
+each until `complete`; never assume success.
+
+```sh
+curl -sf -o /dev/null https://res.cloudinary.com/<cloud>/raw/upload/<public_id>.transcript
+```
+
+They need **real speech**. Music-only or silent video produces no transcript, no
+chapters and no generated title. These features fail, they do not degrade.
+
+## A6. Warm the derivations
+
+The **first** request for an un-derived variant returns **HTTP 423** while
+Cloudinary builds it. `e_preview` can take minutes. An un-derived variant
+requested for the first time in front of an audience is a visible stall.
+
+```sh
+until [ "$(curl -s -o /dev/null -w '%{http_code}' "$URL")" = "200" ]; do sleep 5; done
+```
+
+Warm every URL the page will use, including hover previews and sprite sheets.
+
+**A 200 is not enough for video.** A derivative still being built can return
+200 with a *truncated* file, which the browser then caches — a 14-second source
+delivered as 2.6 seconds that refuses to play, with nothing in the status code
+to say so. Check the duration, not the status:
+
+```sh
+curl -s "$URL" -o /tmp/w.mp4
+ffprobe -v error -show_entries format=duration -of default=nk=1:nw=1 /tmp/w.mp4
+```
+
+**Re-warm whenever the delivery URLs change.** Each distinct transformation is
+its own derivative, so warming `sp_auto` does nothing for the progressive MP4s
+you switch to later, and responsive breakpoints mean warming a set of widths.
+Hard-reload afterwards to evict any truncated response already cached.
+
+For a real launch or a traffic spike, use **eager transformations at upload**
+instead of warming after the fact — see
+[references/field-guide.md](references/field-guide.md).
+
+---
+
+# Phase B — build the site
+
+**Read [references/field-guide.md](references/field-guide.md) alongside this.**
+It carries Cloudinary's own delivery best practices — the duration-based
+delivery cheat sheet, the optimizations customers most often miss, the
+`f_auto` transformation-usage spike to warn about, eager transformations,
+mobile-app delivery, and the pre-launch validation checklist. Phase B below is
+how to build; the field guide is what "built well" means.
+
+## B1. Resolve what this cloud can actually do
+
+Before writing page code, settle the capability set — one explicit flag map,
+with a fallback per feature. This is what keeps a page honest on a cloud without
+add-ons instead of rendering empty rails and dead caption buttons.
+
+**On a fresh cloud**, assume no add-ons: translated subtitles and machine tags
+will be absent every time, and that is correct rather than a regression.
+
+**On a customer cloud**, probe — attempt the operation on **one** asset and read
+the result. Never loop the catalogue: free tiers are small (Google Auto Tagging
+50/month, Video Tagging 5/month) and on a customer cloud quota is their money.
+
+The full matrix, the detection rules, and the **MCP vs `CLOUDINARY_URL` routing
+table** are in [references/capabilities.md](references/capabilities.md). The
+routing matters concretely: `ai_video_analysis` has no MCP tool and cannot be
+signed without an API secret, so on an MCP-only build the audio description
+track is unavailable. Everything else is reachable either way.
+
+## B2. Choose the optimization strategy
+
+An explicit decision, not a default — retrofitting the other one means rewiring
+the player.
+
+**This is a fork, not a comparison.** Video Player Studio encodes it as a
+segmented `Progressive | Adaptive` control — one source, one branch, and the
+two sets of controls are disjoint. Reproduce that shape in code: decide the
+branch first, then set only that branch's options.
+
+| Studio branch | what it offers |
+| --- | --- |
+| **Progressive** | Format (Auto / WebM-VP9 / MP4-H.265 / MP4-H.264), Enable breakpoints (→ Max DPR), Auto HDR, Aspect Ratio (→ Resize Mode) |
+| **Adaptive** | Format: **HLS or MPEG-DASH. Nothing else.** |
+
+Everything that shapes delivery — breakpoints, DPR, HDR, aspect ratio, resize
+mode — is absent from the Adaptive branch, because the streaming profile owns
+all of it. That is the same rule the server enforces with *resize is only
+supported for overlay*; the Studio simply never lets you reach the error.
+
+**The real question is: is this decoration, or is this content someone
+watches?** ABR only pays off when a viewer is watching long enough for the
+ladder to react to their network. Decoration never gets that far.
+
+**`ffprobe` answers it — read the source before choosing.** The signals are in
+the file:
+
+| Signal | Reading | Delivery |
+| --- | --- | --- |
+| **Loops** | decoration by definition — seen in passing, never watched through | **progressive**, always |
+| **No audio track** | background/ambient, and almost always short and autoplaying | **progressive** |
+| **Audio but no speech** (music-only) | montage or mood piece, not something followed | **progressive** |
+| **Portrait 9:16 or square** | social/short-form | **progressive** |
+| **Under ~20s** | over before a ladder could switch | **progressive** |
+| **Speech, over ~1–2 min, viewer-pressed play** | content — a talk, explainer, interview, course | **ABR** |
+
+Then:
+
+Each branch is one option. Nothing else:
+
+| Approach | Set |
+| --- | --- |
+| **Progressive** | `breakpoints: true` |
+| **ABR** | `sourceTypes: ['hls']` |
+
+That is the whole configuration. No `sourceTypes` on the progressive branch, no
+`breakpoints` on the adaptive one, and on neither a format, quality, width or
+`maxDpr` — the player's default is already `f_auto:video`, `breakpoints` brings
+DPR handling with it, and `sourceTypes:['hls']` emits `sp_auto` itself. Reach
+for `maxDpr` only to deliberately cap DPR below auto.
+
+Duration is the proxy, not the rule — a three-minute silent background loop is
+still progressive. Where signals disagree, **behaviour wins over length**.
+
+The same probe decides more than delivery: no audio track, or audio without
+speech, also means no transcript, no chapters and no generated title (A5). One
+`ffprobe` per source, read once.
+
+**Neither is free to get wrong, and the costs are asymmetric.** ABR on a short
+clip buys a manifest round-trip before the first frame — slower start on the
+content most sensitive to it — and a ladder to warm that never switches.
+Progressive on a long watch fixes one rendition at load, so a network that
+degrades at minute eight stalls with no recovery. That is worse, so a borderline
+video someone genuinely watches goes ABR; a borderline video that autoplays
+stays progressive whatever its length.
+
+`sp_auto` is the only mechanism that recovers from a network degrading
+*mid-playback* — but that needs a watch long enough for it to act. **Putting
+ABR on a short clip is a real and easy mistake**: on a 14-second film the
+ladder never meaningfully switches, and you have paid manifest round-trips,
+slower startup and a pile of renditions to warm for nothing. "It's the main
+player" is not a reason; length is.
+
+**Never use `e_preview` to shorten an already-short video.** It exists to cut a
+teaser from a *long* source. A 6-second preview of a 14-second film is barely
+shorter than the asset, costs extra derivations, and is worse than just
+looping the real file.
+
+**Do not hand-write `f_auto`/`q_auto` for player-delivered video, and do not
+force `sourceTypes:['mp4']`.** The player's default already is `f_auto:video`:
+
+```
+default                      → c_limit,w_640/f_auto:video/v1/<id>
+sourceTypes:['mp4']          → c_limit,w_640/<id>.mp4        ← format pinned
+```
+
+Setting `sourceTypes:['mp4']` **replaces** `f_auto:video` with a hard-coded
+extension, so every viewer gets MP4 and automatic format/codec selection is
+lost — verified against 4.1.0. Leave `sourceTypes` unset for progressive and
+just enable `breakpoints`; set it only to `['hls']`/`['dash']` for ABR. Written
+transformations like `c_limit,w_…/f_auto:video/q_auto` belong to the **native
+`<video>` fallback**, where no player is applying them for you.
+
+If the player cannot be used at all, deliver progressive from a native
+`<video>` with media-queried `<source>`s using
+`c_limit,w_…/f_auto:video/q_auto` — see
+[references/capabilities.md](references/capabilities.md).
+
+### Configure the player; do not hand-write its delivery transformation
+
+The player composes the delivery transformation from its options. Anything you
+write into `transformation:` that an option already covers lands in the *same*
+component and breaks the URL rather than adding to it.
+
+```js
+// WRONG — sourceTypes already produces sp_auto
+player.source(id, { transformation: { streaming_profile: 'auto' } });
+// RIGHT
+cloudinary.player(el, { sourceTypes: ['hls'] });   // → sp_auto/<id>.m3u8
+```
+
+Same for `f_auto`/`q_auto` (the default is already `f_auto:video`) and widths
+(that is `breakpoints`). Hand-written transformations are for assets no player
+manages — posters, hover loops, `e_preview` teasers, the native `<video>`
+fallback.
+
+`breakpoints` belongs to the progressive branch only; under ABR the ladder
+governs resolution. Set it there anyway and delivery 400s
+(`c_limit,w_…/sp_auto/…` — *resize is only supported for overlay*), whether you
+set it through player options or by hand.
+
+Both live on the **constructor**, so a page moving a viewer between a
+progressive and an ABR asset must **dispose and rebuild the player**. Calling
+`source()` on a player built for the other strategy carries the wrong option
+across.
+
+Most pages want both, on **different** sources: ABR for the tour, progressive
+for the loops. Full comparison table in
+[references/capabilities.md](references/capabilities.md).
+
+## B3. Load and configure the player
+
+Install from npm and use the **ES import** — the package ships an `exports`
+map with an `import` condition, bundles its own video.js, and loads the player
+core behind a dynamic `import()`, so a bundler code-splits it for you:
+
+```sh
+npm install cloudinary-video-player
+```
+
+```js
+import 'cloudinary-video-player/cld-video-player.min.css';
+import cloudinary from 'cloudinary-video-player';
+```
+
+For a single-file page with no build step, the UMD build off a CDN works the
+same way and puts `cloudinary` on `window`:
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/cloudinary-video-player/dist/cld-video-player.min.css">
+<script src="https://unpkg.com/cloudinary-video-player/dist/cld-video-player.min.js"></script>
+```
+
+**Construct with `cloudinary.player()`, not `cloudinary.videoPlayer()`.**
+`videoPlayer()` is the legacy synchronous constructor. `player()` is the
+current one: it returns a **Promise**, and it resolves *saved configuration*
+first — pass `publicId` and it picks up the settings saved onto that asset in
+Video Player Studio; pass `profile` for a stored profile instead.
+
+```js
+const player = await cloudinary.player('hero', {
+  cloudName, publicId: 'my/video',   // asset's saved settings apply
+  /* local options win over saved config */
+});
+```
+
+Precedence is **construction options > profile > asset-saved > defaults**, so
+repeating settings locally makes the saved config dead weight — save the
+presentation, pass only what is page-specific.
+
+Settings are normally saved through Video Player Studio in the console, but
+the **Video Config API** writes the same thing without console access — useful
+on a claimable cloud, and the way to make a build reproducible:
+
+```sh
+curl -X PUT https://api.cloudinary.com/v2/video/<cloud>/player/config/video/<asset_id> \
+  -u <key>:<secret> -H "Content-Type: application/json" \
+  -d '{"playerOptions":{…},"sourceOptions":{…}}'
+```
+
+Keyed by `asset_id`, not public ID, and PUT replaces the whole document.
+Passing `publicId` with no saved config is silent — you get HTTP 200 and an
+empty `{}`, and the page quietly falls back to its local options.
+
+Because construction is async, guard anything that seeks the player — a
+transcript line clicked before it resolves must queue, not throw. Details, the
+built-in profiles and how to verify what actually applied:
+[references/player.md](references/player.md).
+
+Constructor options vs `source()` options — the split is about **how many
+assets one player shows**. Constructor options configure the *player*;
+`source()` options describe the *asset currently in it*.
+
+**One player, one video:** set everything on the constructor and never call
+`source()` — pass `publicId` and you are done.
+
+**One player, several videos** — a playlist, a rail, a gallery where clicking a
+thumbnail changes the video — build the player **once** and call `source()` per
+asset. Constructor options persist across the swap; the per-asset metadata
+(`title`, `chapters`, `textTracks`) rides along with each `source()` call.
+Building a new player per video is the common mistake: it costs a fresh
+video.js instance each time and leaks the old ones unless you `dispose()`.
+
+The exception is the delivery strategy above: because it lives on the
+constructor, swapping between an ABR and a progressive asset is the one case
+that *does* need a dispose-and-rebuild rather than a `source()` call.
+
+Getting these the wrong way round silently does nothing:
+
+| Constructor | `source()` |
+| --- | --- |
+| `cloudName`, `sourceTypes`, `fluid`, `controls`, `showLogo`, `colors` | `chapters`, `title`, `description`, `textTracks`, `posterOptions`, `interactionAreas` |
+| `seekThumbnails`, `chaptersButton`, `aiHighlightsGraph` | |
+
+**`colors.text` must be a LIGHT colour.** Player chrome sits over dark video; a
+dark text token makes the controls invisible.
+
+Full option shapes: [references/player.md](references/player.md).
+
+## B4. Wire the experience
+
+The capabilities are only worth having if the page uses them. Patterns that
+worked, with the reasoning, in
+[references/build-patterns.md](references/build-patterns.md):
+
+- **For a long source: open on an `e_preview` loop and build the player lazily**
+  on first interaction — motion instead of a black frame, and no stream fetched
+  until wanted. **For a short clip, just loop the real video muted** and build
+  eagerly; there is no stream worth deferring and no teaser worth cutting.
+- **Guard against the async constructor** — `cloudinary.player()` returns a
+  Promise, so queue seeks that arrive before it resolves.
+- **Compose `source()` from the flags** by conditional spread. Skip absent
+  features; never stub them with a URL that 404s.
+- **Bind playback both directions** — rail and transcript seek the player;
+  `timeupdate` highlights the current segment. Render the rail before the player
+  exists, since clicking it is what builds the player.
+- **The transcript is JSON, not VTT** — hand it to the player for captions,
+  fetch and render it yourself for on-page search with click-to-seek.
+- **Emit JSON-LD** from the generated title, description and chapters.
+
+## B4a. Generated, supplied, or hand-authored — in that order
+
+Video Player Studio offers the same three-tier ladder on every piece of
+content, and it is a good default for deciding where metadata comes from:
+
+| panel | tier 1 — generate | tier 2 — supply | tier 3 — author |
+| --- | --- | --- | --- |
+| Chapters | Automatically generate chapters | Import a VTT file | Type `00:00` + name |
+| Transcript | Generate | Upload | — |
+| Poster | Suggested posters (AI frames) | Media Library / current frame | Upload |
+
+Two things follow. First, **every generated artefact has a supply path beside
+it** — so when a human-authored caption, chapter list or poster already exists
+(see A2), use it; the ladder exists precisely so generation is not the only
+route. Second, the tiers are per-asset, not per-site: generating chapters for
+a long talk and hand-authoring three for a short explainer is normal.
+
+## B5. Be straight about what Cloudinary does not generate
+
+- **Chapter→product bindings.** Auto-chaptering finds the segments; which
+  product a segment sells is your data. Check the source platform's cue points
+  and custom fields first — often it is already there.
+- **Hotspot positions.** `interactionAreas` takes coordinates you supply.
+  Cloudinary does not track objects and hand you positions. The AI Video
+  Analysis API returns a timestamped natural-language visual transcription and
+  explicitly **no** spatial coordinates or bounding boxes.
+- **Video background removal, virtual try-on, shade matching.** These do not
+  exist. Do not approximate them with something adjacent.
+
+## Close out
+
+- Which capabilities are on, which are off, **and why** — name the add-on and
+  what enabling it needs.
+- What was migrated, and anything that had no Cloudinary equivalent.
+- On a claimable cloud: **the claim URL**, and that it expires in 24 hours.
+
+## How much of this is verified
+
+Calibrate accordingly — the guidance is not uniformly tested:
+
+- **Cloudinary behaviour is machine-verified.** The delivery, transformation and
+  async-output claims are asserted against a live cloud by a test suite
+  (`sp_auto` rejecting a resize at every width, the transcript being JSON with
+  word-level timings, the chapters VTT path, the pinned player URLs). If
+  Cloudinary changes, those assertions fail rather than quietly misleading you.
+- **Source-platform APIs are documentation research, not tested calls.** The
+  routes in [references/source-platforms.md](references/source-platforms.md)
+  were read from each vendor's docs (September 2026) without an account to
+  exercise them. Treat the *shape* as reliable and confirm the specifics for the
+  account in front of you.
+- **One item is explicitly unresolved:** which Vimeo response field carries the
+  untranscoded original. Vimeo's own docs do not say. Verify before trusting a
+  field, or ask for the customer's master.
+- **Nothing here has been run end to end against a real existing-customer
+  migration.** The from-scratch path has a worked example behind it; the
+  existing-cloud path does not.
+
+Say which of these applies when you rely on one, rather than presenting all of
+it with equal confidence.
+
+## Reference
+
+- [references/field-guide.md](references/field-guide.md) — delivery best
+  practices: use-case discovery, the delivery cheat sheet, issues to avoid,
+  `f_auto` usage spikes, eager transformations, mobile apps, analytics,
+  accessibility, pre-launch validation
+- [references/capabilities.md](references/capabilities.md) — capability matrix,
+  detection, degradation, MCP vs `CLOUDINARY_URL` routing, ABR vs progressive
+- [references/build-patterns.md](references/build-patterns.md) — lazy player,
+  flag composition, playback binding, transcript handling, shipping the site
+  rather than the demo
+- [references/source-platforms.md](references/source-platforms.md) — getting
+  originals off Brightcove, Vimeo, YouTube, Wistia
+- [references/player.md](references/player.md) — full player option shapes
+- [references/gotchas.md](references/gotchas.md) — upload presets, poisoned
+  paths, quotas, async failure modes, truncated derivatives, video.js DOM
+  surgery, player API gaps, VPN and delivery-IP traps
diff --git a/skills/cloudinary-video/references/build-patterns.md b/skills/cloudinary-video/references/build-patterns.md
new file mode 100644
index 0000000..39431cc
--- /dev/null
+++ b/skills/cloudinary-video/references/build-patterns.md
@@ -0,0 +1,198 @@
+# Build patterns
+
+Wiring that turned out to matter, generalized from a working build. The player
+option *shapes* live in [player.md](player.md); this is how the pieces fit
+together into a page.
+
+## Build the player lazily, behind the opening frame
+
+The strongest single improvement to a **long-form** video page: do not open on a
+black frame, and do not fetch the real stream until someone wants it.
+
+Open with an `e_preview` loop — an AI-chosen summary of the video, muted and
+looping, playing as the poster — with a play affordance over it. The first
+interaction builds the player and starts playback.
+
+**This whole pattern assumes a long source.** For a short clip — a campaign
+film, a product video, anything under a minute or two — skip it entirely:
+there is no stream worth deferring, and `e_preview` would only produce
+something marginally shorter than the asset. Loop the real video muted and
+give it a sound/expand affordance instead. Building eagerly is fine there, and
+with `cloudinary.player()` resolving saved configuration it is one call.
+
+Note that `cloudinary.player()` is **async**, so even an eager build needs the
+queue below — a transcript cue or timecode chip can be clicked before the
+promise resolves.
+
+```js
+let player = null;
+const playerReady = [];
+
+/** Runs `fn` once the player exists, building it on the first call. */
+function withPlayer(fn) {
+  if (player) return fn(player);
+  playerReady.push(fn);
+  if (playerReady.length === 1) buildPlayer();
+}
+```
+
+Why a queue rather than building eagerly: other parts of the page (a room rail,
+a transcript cue) can be clicked before the player exists, and each of those is
+a reason to build it. The queue lets them all express "seek to 26s" without
+caring whether the player is there yet.
+
+Autoplay on the loop is only permitted while muted and can still be refused —
+`void loop.play().catch(() => {})`, and let the poster stand if it fails.
+
+## Let player options build the URL, not you
+
+Options carry **delivery** — profile, format, quality, width. `source()`
+carries **content** — which asset, its chapters, text tracks, poster,
+interaction areas. A delivery directive written into `source()` lands in the
+player's own transformation component instead of layering on top of it:
+
+```js
+// WRONG: sourceTypes:['hls'] already emits sp_auto. This yields
+// c_limit,sp_auto,w_640/… → 400 "streaming_profile must be the only directive"
+player.source(id, { transformation: { streaming_profile: 'auto' } });
+```
+
+## Compose `source()` from the feature flags
+
+Spread each capability in conditionally so an absent feature contributes
+nothing, rather than contributing an empty value the player then tries to load:
+
+```js
+player.source(publicId, {
+  ...(features.chapters ? { chapters: true } : {}),
+  ...(features.titleAndDescription ? { title: true, description: true } : {}),
+  ...(features.captions ? { textTracks: buildTextTracks(features) } : {}),
+  ...(features.hotspots ? { interactionAreas: buildAreas(map) } : {}),
+});
+```
+
+The distinction that bites: an omitted `textTracks` gives a player with no
+caption button; a `textTracks` containing an entry whose URL 404s gives a
+caption button that does nothing. Skip, do not stub.
+
+Note `posterOptions` and the `e_preview` opening frame are mutually exclusive —
+if the loop is the opening frame there is no poster to choose, so requesting an
+AI keyframe as well is wasted work.
+
+## Bind playback to the page, both directions
+
+Two-way binding is what makes chapters feel like part of the site rather than
+a player feature:
+
+- **Page → player.** A rail item or transcript cue calls
+  `player.currentTime(seconds); player.play()` (through `withPlayer`).
+- **Player → page.** A `timeupdate` handler finds the current segment and
+  highlights it. Track the last value and only act on change — `timeupdate`
+  fires several times a second and re-rendering on each is visible jank.
+
+```js
+player.on('timeupdate', () => {
+  const t = player.currentTime();
+  const match = chapters.find((c) => t >= c.start && t < c.end);
+  if (match?.sku !== lastSku) { lastSku = match?.sku; setActiveRoom(lastSku); }
+});
+```
+
+Render the rail **before** the player exists. Selecting a room is one of the
+things that builds the player, so a rail that waits for the player is a rail
+that can never trigger it.
+
+## The transcript: what the player does, and what it does not
+
+`<publicId>.transcript` is Cloudinary's own JSON — cues carrying `transcript`
+text and word-level timings — not a VTT file. **The player supports it
+natively**, so do not hand-roll what it already does:
+
+```js
+textTracks: {
+  captions: { label: 'English', default: true, maxWords: 3, wordHighlight: true },
+  options:  { theme: 'yellow-outlined', wordHighlightStyle: { color: 'royalblue' } },
+}
+```
+
+- Omitting `url` makes the player resolve the `.transcript` for that public ID.
+- Setting **`maxWords`** makes it look for `<publicId>.transcript` explicitly —
+  this is the documented trigger, not just a display cap.
+- **`wordHighlight: true`** uses the word-level timings to highlight each word
+  as it is spoken. This is the payoff for the transcript being JSON rather than
+  VTT, and it is a player feature — you do not build it.
+
+What the player has **no** native support for is a **searchable transcript
+panel** — a list of cues you can filter and click to seek. There is no
+`transcript`/`interactiveTranscript` option. If the page wants that, fetch the
+`.transcript` and render it yourself, using `words[].start_time` for
+click-to-seek accuracy, and drive the player with `player.currentTime(t)`.
+
+So the split is: **captions, word highlighting and translated subtitles are the
+player's job; an on-page searchable transcript is yours.**
+
+Translated transcripts live at `<publicId>.<lang>.transcript` and must be
+passed explicitly as `subtitles` entries.
+
+Always give it a failure path. The transcript can be pending, failed, or absent
+(no audio track), and a permanently "Loading transcript…" panel is worse than
+an honest "Transcript unavailable."
+
+## Audio description as a subtitles track
+
+The player has no native descriptions kind, so the visual transcription from
+`ai_video_analysis` — describing what is *on screen* rather than what is said —
+goes in as another `subtitles` entry, labelled so it is not mistaken for a
+translation. Requires an API secret; unavailable over MCP alone.
+
+## Structured data comes free once the metadata exists
+
+`auto_video_details` and `auto_chaptering` give you everything a
+`schema.org/VideoObject` wants — `name`, `description`, `duration`, and
+`hasPart` clips from the chapter boundaries. Emit it as JSON-LD. Only do this
+when the flag is on; fabricating a description for SEO is worse than omitting
+the block.
+
+## Let the player do visibility, not an IntersectionObserver
+
+For decorative loops — tiles, background clips, a feature panel — the reflex is
+an `IntersectionObserver` that plays on enter and pauses on exit. The player
+has this: `autoplay: 'on-scroll'`, alongside `muted`, `loop` and
+`controls: false`. Save that on each asset and the observer disappears, along
+with the lazy `src` assignment people bolt onto it.
+
+That also keeps every clip on the player's own optimizations (`f_auto:video`,
+breakpoints) rather than a hand-written URL on a bare `<video>` — a page mixing
+both ends up with the players optimized and the loops not.
+
+## Ship the site, not the demo scaffolding
+
+Build generously and present quietly. Those are not in tension: every
+capability the cloud supports should be *working* in the page, and none of them
+should be *announced* by it.
+
+When the deliverable is "a page for <brand>", it is that brand's site — not an
+exhibit about Cloudinary. Capability ledgers, delivery tables listing `sp_auto`
+and `f_auto`, transformation footnotes and "what this cloud can do" sections
+are scaffolding: they read as a vendor demo and would never survive on a real
+storefront. Build what the brand would actually ship — navigation, a hero,
+merchandising, working commerce affordances, a real footer — and let the media
+pipeline be invisible.
+
+Keep the honesty about missing capabilities, but put it in your *report to the
+user*, not on the page. The one exception is content that genuinely serves the
+visitor: a transcript is an accessibility feature and can stay, provided it is
+presented as a quiet disclosure rather than a showcase of transcription.
+
+Also watch for **copy that duplicates the footage**. Campaign films usually
+carry a burned-in end-card; if your headline repeats the line the video already
+says, the page reads as a mistake. Read the frames before writing the hero.
+
+## Framework note
+
+Build the `<video>` element imperatively and do **not** dispose the player on
+effect cleanup. Colors, adaptive streaming and interaction areas are lazy
+plugins that reach for the element after the effect returns; disposing pulls it
+out from under them (`Invalid target for null#one`). Route callbacks through
+refs so the effect can have an empty dependency list and build exactly one
+player for the page's lifetime.
diff --git a/skills/cloudinary-video/references/capabilities.md b/skills/cloudinary-video/references/capabilities.md
new file mode 100644
index 0000000..b33c58b
--- /dev/null
+++ b/skills/cloudinary-video/references/capabilities.md
@@ -0,0 +1,258 @@
+# Capabilities, detection, and degradation
+
+Every capability below is optional. A build that assumes all of them produces a
+page that breaks on the first cloud without an add-on; a build that assumes none
+produces a page indistinguishable from the one being replaced.
+
+So: **detect, then flag, then degrade.** The pattern that works is a single
+explicit map of what is on, resolved once at build time, with each feature
+carrying a fallback rather than a blank space.
+
+```js
+const features = {
+  adaptiveStreaming: true,
+  aiPoster: true,
+  previewLoopPoster: true,
+  hoverPreviews: true,
+  chapters: true,
+  seekThumbnails: true,
+  hotspots: true,
+  machineTags: false,         // needs Google Auto Tagging
+  responsivePlayer: true,
+  captions: true,
+  translatedSubtitles: false, // needs Google Translation
+  transcript: true,
+  titleAndDescription: true,
+};
+```
+
+Keeping it in one object rather than scattered `if`s is what makes the
+degradation auditable — you can read off what this page will and will not do,
+and say so honestly at the end of a run.
+
+## The matrix
+
+| Capability | Needs | Absent → degrade to |
+| --- | --- | --- |
+| Adaptive streaming (`sp_auto`) | nothing | progressive MP4 + `f_auto/q_auto` |
+| AI poster (`so_auto`) | nothing | first frame, or a chosen still |
+| `e_preview` loop opening frame (long sources only) | nothing (warm it) | AI poster, then plain poster |
+| Hover previews | chapter→SKU map | static image on hover |
+| Chapters + rail | `auto_chaptering` (or migrated cue points) | no rail; plain scrub bar |
+| Seek thumbnails (`fl_sprite`) | nothing | off — the player copes |
+| Hotspots → cart | **your** coordinates + SKU map | off; rail does the linking |
+| Machine tags / facets | Google Auto Tagging add-on | existing hand-authored tags |
+| Captions | `auto_transcription`, or migrated captions | no caption track |
+| Translated subtitles | Google Translation add-on | English captions only |
+| Audio description | `ai_video_analysis` (**needs API secret**) | omit the track |
+| Searchable transcript | `.transcript` JSON | off |
+| Title / description / JSON-LD | `auto_video_details` | hand-authored copy |
+
+Two rows deserve their own note, because they are the ones people assume
+Cloudinary supplies and it does not:
+
+- **Hotspot coordinates** are yours. `interactionAreas` takes coordinates you
+  pass. AI Video Analysis returns a timestamped natural-language visual
+  transcription and explicitly **no** spatial coordinates or bounding boxes.
+- **Chapter→product bindings** are yours. Auto-chaptering finds segment
+  boundaries; which SKU a segment is selling is business data. On a migration,
+  check the source platform first — cue points and custom fields often already
+  carry it.
+
+## Detecting, rather than assuming
+
+How you resolve the flags depends on the destination, and the two cases are
+opposites:
+
+**Fresh claimable cloud.** Assume no add-ons. Translated subtitles and machine
+tags will be absent every time; that is correct, not a regression. Hardcoding
+those two to `false` is the honest default.
+
+**Existing customer cloud.** Do not assume either way — add-ons may well be
+subscribed. Probe by attempting the operation on **one** asset and reading the
+result, then set the flag. Never probe by looping the catalogue: free tiers are
+small (Google Auto Tagging 50/month, Google Video Tagging 5/month) and on a
+customer cloud the quota is their money.
+
+There is no Admin API that lists entitlements — `/addons`, `/add_ons`,
+`/subscriptions`, `/entitlements` all 404. Attempting the operation is the only
+detection available.
+
+## Access routing: MCP vs `CLOUDINARY_URL`
+
+The Cloudinary MCP never exposes an API secret, so it can only do what it has a
+tool for. This is not a permissions problem you can escalate — unsigned
+requests to any other endpoint return
+`error while authenticating: api_secret not provided`.
+
+| Step | Over MCP | With `CLOUDINARY_URL` |
+| --- | --- | --- |
+| Upload, with free analysis on the call | yes | yes |
+| Poll asset for async status | yes | yes |
+| Asset update / tags / context | yes | yes |
+| Delivery URLs, warming derivations | yes (plain HTTP) | yes |
+| Add-on categorization / auto-tagging | yes | yes |
+| `ai_video_analysis` (visual transcription) | **no tool — unreachable** | yes |
+| Any v2 or beta route | **no** | yes |
+
+Consequence worth stating to the user rather than discovering late: on an
+MCP-only build the **audio description track is simply unavailable**, because
+`POST /v2/video/<cloud>/ai_video_analysis` cannot be signed. Everything else in
+the matrix is reachable either way.
+
+Before concluding a feature does not exist, check whether it is merely
+unreachable by the route in use. The two are indistinguishable from inside an
+MCP session.
+
+## Optimization strategy: `sp_auto` (ABR) vs `breakpoints` (progressive)
+
+Two mechanisms for the same goal — stop sending every viewer the same bytes —
+working in opposite ways. Pick one **per source**; the choice is not reversible
+without rewiring the player.
+
+| | `sp_auto` — adaptive bitrate | `breakpoints` — progressive |
+| --- | --- | --- |
+| `sourceTypes` | `['hls']` (or `['dash']`) | **leave unset** — the default. `['mp4']` pins the format and disables `f_auto:video` |
+| What it delivers | one manifest listing a rendition ladder | one file at one chosen width |
+| Who decides | the **player**, continuously, per segment | the **player**, once, at load |
+| Adapts to | bandwidth *and* changes mid-playback | viewport/DPR at startup only |
+| Recovers from a stall | yes — drops to a lower rung | no — it is one file |
+| Startup cost | manifest + first segments | one request |
+| Overhead | segmenting, manifest, more derivations to warm | none beyond the resize |
+
+### Duration decides this, not "main player vs decoration"
+
+**Check the asset's duration before choosing.** Cloudinary's own field guidance
+is duration-based, and it is the opposite of "ABR is the default for anything
+important":
+
+| Duration | Approach |
+| --- | --- |
+| **Up to 1–2 minutes** | **Progressive** — the player's default. `f_auto` + `q_auto`, plus responsive breakpoints. Product videos, campaign films, promos, social-style clips, anything inline or autoplaying. |
+| **More than 1–2 minutes**, especially viewer-selected and not autoplaying | **ABR** (`sp_auto` via `sourceTypes:['hls']`). Long-form, where a network can realistically degrade mid-watch. |
+
+`sp_auto` is the only mechanism that responds to bandwidth dropping *while
+someone is watching* — but that advantage needs a watch long enough for it to
+act. On a 14-second campaign film the ladder never meaningfully switches, and
+you have bought manifest round-trips, slower startup, and a pile of renditions
+to generate and warm in exchange for nothing. **Progressive is the default for
+short web video; reach for ABR when length justifies it.**
+
+`breakpoints` is right for short video generally — including silent decorative
+loops, hover previews and background clips, where a manifest is pure overhead.
+
+**Do not reach for `e_preview` to make a short clip shorter.** `e_preview`
+extracts a teaser from a *long* source. Generating a 6-second preview of a
+14-second video produces something barely shorter than the asset itself, costs
+extra derivations to warm, and is strictly worse than looping the real file.
+
+### The player already applies `f_auto:video` — do not restate it
+
+Measured against `cloudinary-video-player@4.1.0`, with the same asset:
+
+| Options | URL the player generates |
+| --- | --- |
+| none | `f_auto:video/v1/<id>` |
+| `breakpoints` | `c_limit,w_640/f_auto:video/v1/<id>` |
+| `sourceTypes:['mp4']` + `breakpoints` | `c_limit,w_640/<id>.mp4` |
+| `sourceTypes:['mp4']` + `breakpoints` + `transformation:{fetch_format:'auto',quality:'auto'}` | `c_limit,f_auto,q_auto,w_640/<id>.mp4` |
+
+The third row is the trap: asking for MP4 **removes** `f_auto:video`, pinning
+one format for every viewer. The fourth row is people noticing the loss and
+manually re-adding what the default gave them for free — while still pinned to
+the `.mp4` container.
+
+**The rule this table is an instance of:** express delivery through player
+options and let it build the URL. Anything written into `transformation:` that
+an option already covers gets merged into the player's own component. Save
+hand-written transformations for assets no player manages — posters, hover
+loops, `e_preview` teasers, the native `<video>` fallback.
+
+So for progressive: set `breakpoints`, leave `sourceTypes` alone, and write no
+format/quality transformation. The extensionless `f_auto:video` URL is
+content-negotiated per request — the same URL returned WebM to one request and
+MP4 to another in testing.
+
+### If the Cloudinary player cannot be used
+
+Deliver progressive with a native `<video>` and several `<source>` elements, so
+the browser picks by viewport — the same optimizations, without the player:
+
+```html
+<video controls autoplay muted playsinline preload="metadata">
+  <source media="(max-width: 640px)"
+    src=".../video/upload/c_limit,w_640/f_auto:video/q_auto/v1/<id>.mp4" type="video/mp4">
+  <source media="(max-width: 1280px)"
+    src=".../video/upload/c_limit,w_1280/f_auto:video/q_auto/v1/<id>.mp4" type="video/mp4">
+  <source
+    src=".../video/upload/c_limit,w_1920/f_auto:video/q_auto/v1/<id>.mp4" type="video/mp4">
+</video>
+```
+
+Note `f_auto:video` (not bare `f_auto`) for the format/codec pick, `q_auto` for
+quality, and `c_limit,w_…` to cap dimensions. For ABR without the player,
+generate the manifest with `sp_auto` and hand the `.m3u8` to a compatible
+third-party player.
+
+### `breakpoints` is progressive-only
+
+`breakpoints` exists to pick a delivery **width** for the container on the
+progressive path. ABR does not need one — the streaming profile defines the
+rendition ladder and the player moves between rungs as bandwidth changes. So
+the two are not alternatives to weigh against each other on one source:
+`breakpoints` has no meaning once `sourceTypes:['hls']` is set, exactly as
+`maxDpr` has none.
+
+Set it anyway and the player **prepends a resize** to the source URL. With
+`sp_auto` in the chain that produces:
+
+```
+c_limit,w_2560/sp_auto/….m3u8   →   HTTP 400
+```
+
+Cloudinary rejects a resize combined with a streaming profile ("sp_auto
+transformation is not allowed (resize is only supported for overlay)"), because
+the streaming profile *already defines* the rendition ladder — asking for one
+width contradicts the whole mechanism. Verified at every width tried, 640
+through 2560: always 400, and the video simply never loads.
+
+So `breakpoints` stays off under `sourceTypes:['hls']` — not as a workaround,
+but because there is no progressive path here to size. Using player options
+rather than hand-written URLs does not avoid it; the player composes the
+invalid URL for you.
+
+Don't hand-write the profile either: `sourceTypes:['hls']` already emits
+`sp_auto`, and adding `transformation:{streaming_profile:'auto'}` merges it
+into the resize's component, which hides the real cause behind a second error.
+
+Both are constructor options, so dispose and rebuild the player when a page
+moves a viewer between the two strategies.
+
+`maxDpr` is narrower than "MP4-only": Video Player Studio reveals Max DPR only
+*after* breakpoints is enabled, so it is a child of breakpoints rather than an
+independent option. With ABR neither exists — the ladder governs resolution.
+
+### The normal shape is both, on different sources
+
+A page usually wants ABR for the main tour and progressive for the loops:
+
+```js
+// main player, LONG source — adapts while watching
+sourceTypes: ['hls'],  breakpoints: false
+
+// preview loop cut from that long source — one small file, no manifest
+<video src=".../e_preview:duration_10.0/f_auto/q_auto/hero.mp4" muted loop>
+```
+
+That is the common configuration, not a compromise. What is *not* available is
+both mechanisms on the same source.
+
+If the main video is itself short, this shape does not apply: everything is
+progressive, and the "loop" is simply the real file
+(`c_limit,w_…/f_auto/q_auto/hero.mp4`) rather than an `e_preview` cut of it.
+
+### Naming collision worth flagging
+
+The player option `breakpoints` (a boolean, video) is unrelated to the image URL
+parameter `w_auto:breakpoints` (responsive image widths). Same word, different
+subsystems — do not let one's documentation answer a question about the other.
diff --git a/skills/cloudinary-video/references/field-guide.md b/skills/cloudinary-video/references/field-guide.md
new file mode 100644
index 0000000..3038466
--- /dev/null
+++ b/skills/cloudinary-video/references/field-guide.md
@@ -0,0 +1,122 @@
+# Field guide: delivery best practices
+
+Condensed from Cloudinary's internal CSM video onboarding checks & best
+practices guide. This is the guidance to apply when advising on, reviewing or
+building a customer's video implementation — it is about *delivering video
+well*, not about the player's API surface (see [player.md](player.md)).
+
+## Understand the use case before recommending anything
+
+Recommendations follow from the use case, so establish it first:
+
+- **What types of video?** In e-commerce, typically short product videos on
+  PDPs, plus campaign/content videos on homepages and landing pages.
+- **How long are they?** Under a minute, or longer? This drives the delivery
+  method more than anything else.
+- **Where are they delivered?** Web (desktop/mobile), native mobile apps, or
+  other channels. Native apps change the rules — see below.
+- **Do they need analytics?** Views, engagement, watch time.
+- **Do they release videos into traffic spikes?** Catalogue launches, major
+  campaigns — this is what makes eager transformations worth it.
+- **Do they need subtitles/captions?** Already authored, or generated and
+  translated?
+- **Any other accessibility or navigation needs?** Audio descriptions, chapters.
+
+## Delivery cheat sheet
+
+| Scenario | Approach | Notes |
+| --- | --- | --- |
+| Short, inline, autoplay, PDP, campaign or social-style web video | **Cloudinary Video Player, progressive** | Optimizes by default (the URL it builds carries `f_auto:video`) — write no format/quality transformation, and do not set `sourceTypes`. Enable responsive breakpoints for per-screen dimensions |
+| Short web video, player unavailable | **Native `<video>` with multiple `<source>`** | `c_limit,w_[width]` + `f_auto:video` + `q_auto` |
+| Longer-form / viewer-selected video | **ABR, preferably via the player** | Set `hls` (or `dash`) in `sourceTypes`; the player adds `sp_auto` for you |
+| ABR, player unavailable | **HLS via a compatible third-party player** | Generate the manifest with `sp_auto`; verify browser/device support |
+| Major launch, big catalogue drop, high-traffic event | **Eager transformations, on top of the chosen approach** | Pre-generate derivatives at upload; do not let first requests build them |
+| Native iOS/Android app | **Mobile-specific strategy** | App picks codec/format and dimensions; URL params or `Accept` header |
+| Analytics, captions, accessibility, chapters, branded UI needed | **Use the Cloudinary Video Player** | All of it works out of the box |
+
+## Typical issues to avoid
+
+- **Delivering the original**, untransformed. Default video quality only kicks
+  in when *some* transformation is present in the URL — a bare original URL
+  gets no optimization at all.
+- **No maximum dimensions.** Shipping 4K/8K where 1080p is indistinguishable
+  burns bandwidth and units for no visible gain. Cap with `c_limit,w_…` for
+  progressive, and cap the top rung for ABR too.
+- **Partial optimization** — applying some of `f_auto` / `q_auto` / resizing but
+  not the rest, and ending up with files larger than necessary.
+- **Assuming `f_auto` works in native mobile apps.** It is web delivery
+  behaviour.
+- **Preloading everything.** Preloading improves perceived start time but
+  consumes units for videos nobody watches. Prefer lazy loading, and make
+  autoplay/preload a deliberate decision rather than a default.
+
+## `f_auto` causes a transformation-usage spike — say so in advance
+
+Introducing `f_auto`, or adding format/codec combinations, forces new derived
+versions to be generated. Expect a visible **spike in transformation usage**,
+especially across a large existing library. It settles once the derivatives
+exist and get reused. Warn the customer *before* the rollout so the bill does
+not surprise them.
+
+## Account-level optimization settings
+
+- **Default automatic format** applies `f_auto`/`q_auto` to web-delivered video
+  without touching delivery URLs. Being rolled out to plans on the *video
+  seconds* metric; not available on video-bandwidth plans. Web only.
+- **Default video quality** lets Cloudinary pick quality and codec (`vc_auto`)
+  automatically. Available on all plans — but **only applies when another
+  transformation is present in the URL**.
+
+## Eager vs on-the-fly
+
+On-the-fly is the right default: derivatives build on first request, no
+preparation needed. Switch to **eager transformations at upload** when a launch
+or campaign will drive a traffic surge, when videos are long or high-resolution
+(2K/4K), or when transformations are complex enough to be slow to build. This
+is the production-grade version of "warm the derivations": generate them at
+upload rather than discovering the cost on the first viewer's request.
+
+## Mobile apps are a different problem
+
+The player requires a mobile SDK (iOS, Android, Flutter, React Native).
+
+**`f_auto` does not work the same way.** The app must tell Cloudinary what the
+device supports, either by naming it in the URL:
+
+- Android: `f_mp4,vc_av1` → `f_webm,vc_vp9` → `f_mp4,vc_h264` (fallback)
+- iOS: `f_mp4,vc_av1` → `f_mp4,vc_h265` → `f_mp4,vc_h264` (fallback)
+
+…or by sending an `Accept` header (e.g. `video/webm; codecs="vp9"`,
+`video/mp4; codecs="hvc1"`, `video/mp4; codecs="avc1"`). AV1 via `Accept` is
+not supported yet.
+
+**Responsive breakpoints are not supported in the mobile SDKs.** Request
+explicit widths per device instead (`c_limit,w_640` / `w_1280` / `w_1920`), and
+pick the smallest that suits the screen.
+
+## What the player gives you for free
+
+- **Analytics** — collected by default for anything delivered through the
+  player; visible in Console under Video → Analytics, and available via API.
+- **Accessibility** — WCAG 2.1 AA, keyboard navigation, captions/subtitles
+  (existing VTT/SRT or generated transcripts), audio descriptions via text
+  tracks or alternative audio tracks on ABR, and chapters (VTT, manual, or
+  AI-generated).
+- **Customization** — skins, colour schemes, fonts, titles/subtitles display.
+- **Video Player Studio** — a visual configurator that emits the player config,
+  rather than hand-writing it. Also handles transcripts and chapters.
+
+## Validate before launch
+
+Confirm, on representative videos and real devices:
+
+- Delivery URLs are **not** serving originals, and have size limits.
+- The intended optimization approach is actually enabled (check the URL that
+  ships, not the one you wrote).
+- Autoplay/preload behaviour is deliberate.
+- Playback works on target browsers, devices and networks.
+- Captions/subtitles and analytics work where required.
+- The expected initial transformation/delivery usage has been explained.
+
+Then review 2–4 weeks after launch: confirm delivery, check usage and
+transformation patterns, and look for optimization opportunities.
diff --git a/skills/cloudinary-video/references/gotchas.md b/skills/cloudinary-video/references/gotchas.md
new file mode 100644
index 0000000..5bc69c1
--- /dev/null
+++ b/skills/cloudinary-video/references/gotchas.md
@@ -0,0 +1,250 @@
+# Gotchas
+
+Each of these cost real debugging time on a real migration. They all look like
+code bugs and none of them are.
+
+## Upload presets can rewrite your assets on ingest
+
+An account can have an upload preset carrying an **incoming transformation**,
+which permanently rewrites every uploaded asset — resizing it, watermarking it,
+or both. The signing endpoint may inject that preset into signed uploads whether
+you asked for it or not.
+
+Symptom: uploads report success, but stored dimensions are smaller than the file
+you sent, and delivered images carry a watermark.
+
+What does **not** work:
+
+- `upload_preset: ""` — ignored, the preset is still applied
+- an explicit `transformation:` parameter — the upload *response* reports your
+  dimensions while the *stored* asset keeps the preset's
+- `invalidate: true` — this is not a cache problem
+
+What does work: pass an explicit clean preset by name (often `default` — check
+what exists on the account), or clear the offending preset's incoming
+transformation in Console → Settings → Upload → Upload presets.
+
+Note the watermark also **degrades Cloudinary's own AI**. Google Auto Tagging on
+a watermarked image returned 3 tags where the clean original returned 27.
+
+## A public ID path can become unusable
+
+On one account, uploads to a particular folder path kept storing the old
+788px watermarked asset no matter what — including after deleting the asset and
+uploading fresh. An identical upload to a *different* path stored correctly
+first time.
+
+If a path misbehaves twice, stop debugging it and change the path. Verify by
+fetching the delivery URL with a cache-busting query and checking the actual
+JPEG dimensions, not the upload response.
+
+## Add-on quotas are small and easy to burn
+
+Free-plan monthly limits worth knowing before you loop over an asset list:
+
+| Add-on | Limit |
+| --- | --- |
+| Google Auto Tagging | 50 |
+| Google Video Tagging | 5 |
+| Google Speech | 120 |
+| Image generation | 50 (a single request can consume 3) |
+| Image-to-video | 160 |
+
+Repeated re-uploads to fix something else will exhaust these. Get the upload
+parameters right before running the batch.
+
+## Async AI features fail rather than degrade
+
+`auto_chaptering`, `auto_transcription` and the generated title/description all
+return `status: "pending"` and complete later — **or return `status: "failed"`**.
+
+They need substantial real speech. On a 5-second silent clip:
+
+```json
+"auto_chaptering":    { "status": "failed", "data": "Failed to process request" },
+"auto_video_details": { "status": "failed", "data": "Failed to process request" }
+```
+
+Always poll for `complete`. Never assume.
+
+## HTTP 423 on first request
+
+An un-derived variant returns **423 Locked** while Cloudinary builds it
+asynchronously. `e_preview` on a 3-minute video took minutes. Poll until 200.
+
+For anything going into a launch or a traffic spike, the real fix is **eager
+transformations at upload** rather than warming by polling — see
+[field-guide.md](field-guide.md).
+
+### A 200 is not proof the derivative is complete
+
+Worse than a 423: a video derivative that is still building can return **200
+with a truncated file**, and the browser will cache that. Observed on a
+14.1-second source — the page reported `duration: 2.625`, buffering stopped at
+2.24s, and playback simply refused to start. Nothing in the HTTP status said
+anything was wrong.
+
+So verify the *content*, not the status code:
+
+```sh
+curl -s "$URL" -o /tmp/w.mp4
+ffprobe -v error -show_entries format=duration -of default=nk=1:nw=1 /tmp/w.mp4
+# compare against the known source duration; retry until it matches
+```
+
+And **re-warm whenever the delivery URLs change.** Warming `sp_auto` does
+nothing for the `c_limit,f_auto,q_auto,w_…` MP4s you switch to later; each
+distinct transformation is its own derivative. With responsive breakpoints the
+player may request several widths, so warm the whole set. After re-warming,
+hard-reload — the browser is still holding the truncated response.
+
+## Video.js rearranges your DOM, and two bugs follow
+
+The Cloudinary player is video.js underneath, which performs DOM surgery on
+init. Two failures come from this and both are silent:
+
+**The original `id` moves to a wrapper div.** After init,
+`document.getElementById('hero')` returns a `<div class="video-js">`, not the
+`<video>`. Attaching media listeners to it does nothing:
+
+```js
+document.getElementById('hero').addEventListener('timeupdate', …) // never fires
+player.on('timeupdate', …)                                        // correct
+```
+
+**An unclosed `<video>` tag swallows everything after it.** HTML parsing puts
+subsequent siblings *inside* the video element, where they never render:
+
+```html
+<video id="hero" class="cld-video-player" playsinline>   <!-- no </video> -->
+<button class="soundbtn">…</button>   <!-- becomes a child of <video> -->
+<div class="overlay">…</div>          <!-- gone: 0×0, never painted -->
+```
+
+The tell is an element measuring 0×0 whose `parentElement` is `VIDEO.vjs-tech`.
+Always close the tag.
+
+## The Cloudinary player proxies only some videojs methods
+
+`player.currentTime()` and `player.play()` are proxied through the Cloudinary
+wrapper. `player.muted()` and `player.controls()` are **not** — calling them
+throws `TypeError: player.muted is not a function`, which aborts the rest of
+your click handler and looks like "the button does nothing".
+
+Reach the underlying videojs player for those:
+
+```js
+var vjs = window.videojs && window.videojs.getPlayer('hero');
+if (vjs) { try { vjs.muted(false); vjs.controls(true); } catch (e) {} }
+```
+
+Setting `muted`/`volume` directly on the underlying `<video>` element also
+works and is the most robust option.
+
+## Artifacts cannot host a Cloudinary video demo
+
+The Claude Artifact viewer's CSP admits only the artifact's own files, Google
+Fonts and a few script CDNs. Every `res.cloudinary.com` image, video and
+`fetch()` is blocked, so the page publishes "successfully" and renders as an
+empty shell. Inlining media as data URIs would defeat the point (no adaptive
+delivery, no transformations). Serve these pages over HTTP instead.
+
+## Verifying what was actually stored
+
+The upload response can disagree with what is stored and delivered. To check
+real delivered dimensions:
+
+```sh
+curl -s "https://res.cloudinary.com/<cloud>/image/upload/<public_id>.jpg?bust=$RANDOM" \
+| python3 -c "
+import sys,struct
+d=sys.stdin.buffer.read(); i=2
+while i<len(d)-9:
+    if d[i]==0xFF and d[i+1] in (0xC0,0xC1,0xC2):
+        h,w=struct.unpack('>HH',d[i+5:i+9]); print(f'{w}x{h} {len(d)}B'); break
+    i+=1
+"
+```
+
+For video, `ffprobe` on a downloaded file is the honest check — including
+whether an audio stream exists at all, which decides whether transcription and
+chaptering can work.
+
+## The MCP has no API secret
+
+The Cloudinary MCP holds its credentials internally and never exposes the API
+secret, so an agent working through it can only do what the MCP has a tool for.
+Any other endpoint — a v2 route, a beta API — cannot be signed and returns:
+
+```
+{"error":{"message":"error while authenticating: api_secret not provided"}}
+```
+
+`POST /v2/video/<cloud>/ai_video_analysis` is the common case: no MCP tool, so
+the visual transcription cannot be produced this way at all.
+
+An agent that provisions its own cloud has no such limit. `npx
+@cloudinary/cloud` writes `CLOUDINARY_URL=cloudinary://<key>:<secret>@<cloud>`,
+and every endpoint is reachable with it.
+
+Before concluding a feature is unavailable, check whether it is merely
+unreachable — the two look identical from inside an MCP session.
+
+## Provisioning fails behind a VPN
+
+`npx @cloudinary/cloud` derives the media-delivery allow-list from the source
+IP, and refuses to provision from a private address:
+
+```
+delivery_ips_not_public — delivery_ips must contain at least one public IP address
+```
+
+A corporate VPN or secure gateway (Cloudflare WARP and similar) triggers this.
+The tool's own guidance says an agent should **report it and let the user
+decide** rather than changing network settings. Pausing the VPN for that one
+command is the fix.
+
+Related, and easy to misdiagnose: **read `delivery_ips` back from the response**
+rather than trusting what you sent. Behind a proxy your own address is silently
+dropped, and you end up with a cloud whose media nothing can view.
+
+### A VPN toggling *after* provisioning silently kills a working cloud
+
+Worse than the provisioning failure, because it fails late and quietly. The
+cloud is pinned to the IP it was provisioned from, so if the network changes —
+a VPN reconnecting, a gateway rotating its egress, moving to another network —
+every delivery URL starts returning **401**, on a cloud that worked minutes ago.
+
+The tell is *which* requests fail: uploads and Admin API calls keep succeeding,
+because only CDN delivery is IP-restricted. So an agent reports a successful
+migration while every image and video 401s.
+
+```sh
+# 401 on delivery but uploads fine? compare the current egress with the
+# address the cloud was provisioned from
+curl -s https://api.ipify.org
+```
+
+The 401 body says the OAuth token expired, which is misleading — it is an
+allow-list rejection, not an auth problem.
+
+For a demo, keep the VPN off for the **whole session**, not just the
+provisioning command.
+
+## The delivery IP restriction blocks Cloudinary's own fetches
+
+On an unclaimed cloud, `POST /upload` with `file=<a delivery URL on that same
+cloud>` fails with `401 Unauthorized`. Cloudinary's fetcher is not one of the
+allowed delivery IPs. Upload from a local file instead.
+
+Claiming the cloud lifts the restriction entirely.
+
+## Claimable clouds
+
+- Expire **24 hours** after provisioning unless claimed
+- Media delivery is restricted to the IPs in `delivery_ips`; **uploads and API
+  calls are not restricted**, so a wrong IP looks like a working migration with
+  broken media
+- The CLI's default (no `--ip`) locks delivery to the calling address, which is
+  usually correct — prefer it over guessing
+- Surface the `claim_url` to the user; it is what makes the cloud permanent
diff --git a/skills/cloudinary-video/references/player.md b/skills/cloudinary-video/references/player.md
new file mode 100644
index 0000000..8bdbe1b
--- /dev/null
+++ b/skills/cloudinary-video/references/player.md
@@ -0,0 +1,306 @@
+# Cloudinary Video Player option shapes
+
+Verified against `cloudinary-video-player@4.1.0`. Option names come from the
+player API reference, not from memory.
+
+## Use `cloudinary.player()`, not `cloudinary.videoPlayer()`
+
+The 4.1.0 UMD bundle attaches five things to `window.cloudinary`:
+`videoPlayer`, `videoPlayers`, `player`, `players`, `Cloudinary`. Two of those
+construct a player and they are **not** the same function:
+
+| | `cloudinary.videoPlayer()` | `cloudinary.player()` |
+| --- | --- | --- |
+| Status | legacy constructor | **current** — the bundle tags its own analytics `newPlayerMethod: true` |
+| Returns | the player, synchronously | a **Promise** resolving to the player |
+| Saved configuration | none — options only | fetches saved config before constructing |
+
+```js
+const player = await cloudinary.player('hero', {
+  cloudName: 'my-cloud',
+  publicId: 'my/public-id',   // also loads the source
+  // …local options win over anything fetched
+});
+```
+
+Because it is async, anything that touches the player (seeking from a
+transcript or a timecode chip) must tolerate being called before it resolves —
+queue the request and replay it on resolve.
+
+### Saved configuration: assets and profiles
+
+Video Player Studio saves settings **onto the video asset** by default. Passing
+`publicId` makes the player retrieve them automatically (requires player
+3.6.0+), so a page can inherit the styling and behaviour someone configured in
+the Studio without hard-coding it.
+
+`profile` loads a stored *profile* instead — either a built-in
+(`cld-default`, `cld-looping`, `cld-adaptive-stream`, `cld-live-streaming`) or
+one saved on the cloud, fetched from
+`/_applet_/video_service/video_player_profiles/<name>.json`.
+
+**Profiles are writable over HTTP — no console needed.** When the same
+presentation repeats across many assets, that is the signal to create one
+rather than repeat it in page code:
+
+```sh
+# create or update; also GET /player/profiles to list, DELETE to remove
+curl -X PUT https://api.cloudinary.com/v2/video/<cloud>/player/profiles/<name> \
+  -u <key>:<secret> -H "Content-Type: application/json" \
+  -d '{"playerOptions":{…},"sourceOptions":{…}}'
+```
+
+Basic auth with the API key and secret; both `playerOptions` and
+`sourceOptions` are required and take arbitrary player/source keys. Full
+reference: <https://cloudinary.com/documentation/video_player_profiles_reference>
+
+Precedence, and the trap: **specifying a `profile` overrides the asset's own
+saved settings.** If you want the per-video configuration to apply, do not pass
+a profile. Local options passed at construction beat both.
+
+Profiles deliberately exclude per-embed values — the video's `publicId` and
+`posterOptions` are never part of a profile, so keep passing those yourself.
+
+`cld-looping` is worth knowing: `{fluid, controls:false, muted:true,
+autoplay:true, loop:true}` — the standard hero/background-loop configuration.
+
+**Precedence is two different mechanisms, not one ranked list.** Getting this
+wrong leads to over-specifying the page defensively:
+
+- **A `profile` replaces the asset's video settings.** It is a substitution:
+  pass one and the per-asset saved configuration no longer supplies the base.
+  So a profile cannot be combined with per-video settings — if some setting
+  genuinely varies per asset, it cannot live behind a profile.
+- **Construction options are additive.** They layer *on top* of whichever base
+  applies and do **not** suppress it. Settings you do not pass keep coming from
+  the asset (or profile), so a page that sets three options still inherits
+  everything else that was saved.
+
+(Cloudinary's own statement; the public profiles API reference does not
+document precedence, so do not infer it from the endpoint docs.)
+
+Practically: save the presentation, pass only what is genuinely page-specific.
+Not because inline options would otherwise clobber the saved config — they
+won't — but because anything inline is a value nobody can change without a
+deploy.
+
+### What the Studio's own embed looks like
+
+Worth calibrating against, because it is the shape Cloudinary steers users to.
+The Studio's Share dialog offers two modes, and neither produces a wall of
+options:
+
+| mode | generated code |
+| --- | --- |
+| **Video settings** (asset-saved) | `cloudinary.player('player', { cloudName, publicId })` |
+| **Profile settings** | `cloudinary.player('player', { cloudName, publicId, profile: 'cld-default' })` |
+
+That is the whole call — `fluid` and the rest of the presentation all live in
+the asset's video settings, not in the page. The profile picker lists real
+reused ones (`pdp`, `abr-4k`, `translations`) beside the `cld-*` built-ins.
+
+**Configuration belongs on the asset or in a profile — not inline.** This is
+the practice, not a judgement call: presentation saved on the asset can be
+changed by anyone in Studio, while the same values in page code need a deploy.
+Repeat the same presentation across several assets and it should be a profile.
+
+Inline options are not *broken* — they layer on top rather than suppressing
+what was saved — but reach for them only for what genuinely cannot live on the
+asset, and expect that to be close to nothing. `cloudName` and the `publicId`
+are the call; everything else has a home.
+
+The Studio also has a raw-JS escape hatch — *Advanced settings editing* — and
+scopes it explicitly to "player options that are not currently exposed in the
+Studio UI", warning that default player options will be ignored. Treat
+hand-written config the same way: last resort, for what the supported surface
+does not cover.
+
+### Saving settings without the console — the Video Config API
+
+Video Player Studio saves settings through the console UI, but the same
+configuration is readable and writable over HTTP, keyed by **`asset_id`** (not
+public ID), with Basic auth:
+
+```sh
+# read
+curl https://api.cloudinary.com/v2/video/<cloud>/player/config/video/<asset_id> \
+  -u <key>:<secret>
+
+# write — PUT REPLACES the whole document; GET, merge, then PUT to patch
+curl -X PUT https://api.cloudinary.com/v2/video/<cloud>/player/config/video/<asset_id> \
+  -u <key>:<secret> -H "Content-Type: application/json" \
+  -d '{"playerOptions":{…},"sourceOptions":{…}}'
+```
+
+`playerOptions` takes constructor keys; `sourceOptions` takes `source()` keys
+(`sourceTypes`, `transformation`, `posterOptions`, `textTracks`). Get the
+`asset_id` from the Admin API — the resource endpoint returns it alongside the
+public ID.
+
+The player reads the same config at delivery time from
+`/_applet_/video_service/video_player_config/video/<type>/<base64(publicId)>.json`,
+which is handy for verifying what a page will actually receive. **An empty
+`{"playerOptions":{},"sourceOptions":{}}` and HTTP 200 means nothing is saved**
+— the fetch fails silently by design, so a page falls back to its local
+options and looks fine while inheriting nothing.
+
+### Confirming saved config actually applied
+
+Two checks that avoid false alarms:
+
+- The player's analytics beacon to `analytics-api-s.cloudinary.com/video_player_source`
+  spells it out: `newPlayerMethod=true`, `videoConfig=true`, and
+  `fetchedConfig=<comma-separated keys>` listing exactly which keys came from
+  the saved config.
+- **Do not test captions with `videoEl.textTracks`** — it reads empty because
+  video.js manages them as *remote* tracks. Use
+  `videojs.getPlayer(id).remoteTextTracks()`.
+
+## Constructor options
+
+These apply to either constructor.
+
+```js
+{
+  cloudName: 'my-cloud',
+  sourceTypes: ['hls'],        // ABR only. OMIT for progressive — setting
+                               // ['mp4'] disables the f_auto:video default
+  fluid: true,                 // fills its container
+  controls: true,
+  showLogo: false,
+  seekThumbnails: true,        // default true
+  chaptersButton: true,
+  aiHighlightsGraph: false,    // interest curve on the scrub bar
+  colors: {
+    accent: '#88c0d0',
+    base:   '#0b1015',
+    text:   '#eceff4',         // MUST be light — chrome sits over dark video
+  },
+}
+```
+
+`breakpoints` — a **boolean**, and a **progressive-only** option: it picks a
+delivery width for the container. It has no meaning under
+`sourceTypes: ['hls']`, where the streaming profile's ladder governs
+resolution, and setting it there yields a 400 — including when both are set
+purely as player options, since the player composes the rejected URL for you.
+Both are constructor options, so a player must be **disposed and rebuilt** to
+move between the two strategies. See the comparison in
+[capabilities.md](capabilities.md).
+
+Never pass `transformation:{streaming_profile:…}` to `source()`:
+`sourceTypes:['hls']` already emits `sp_auto`, and writing it yourself only
+collapses it into another directive's component.
+
+`maxDpr` — number or `true`. Only meaningful **with `breakpoints` on** (Studio
+reveals Max DPR only once breakpoints is enabled), so it is progressive-only by
+inheritance.
+
+**You do not need to set it.** Enabling `breakpoints` turns on DPR handling
+too: breakpoints chooses the *width* and the device's pixel density is matched
+automatically — `maxDpr: true` (auto), which is what Studio's "Auto" writes and
+what it defaults to. Setting it is redundant, in the same way writing `f_auto`
+for a player-delivered source is.
+
+Pass a **number** only to deliberately cap below auto — trading sharpness on
+dense screens for bytes (Studio offers 1.0, 1.5, 2.0). With a number, effective
+DPR is the minimum of `maxDpr`, the device's actual DPR, and 2.0. Only relevant
+on the MP4 path.
+
+## source()
+
+```js
+player.source('my/public-id', {
+  chapters: true,              // loads <publicId>-chapters.vtt
+  title: true,                 // AI-generated title in the title bar
+  description: true,
+
+  posterOptions: {
+    transformation: { start_offset: 'auto' },   // AI-selected keyframe
+  },
+
+  textTracks: {
+    captions: {
+      label: 'English', default: true,   // omit url → uses .transcript
+      maxWords: 3,                       // also TRIGGERS the .transcript lookup
+      wordHighlight: true,               // highlight each word as spoken
+    },
+    subtitles: [
+      { label: 'Español',  language: 'es', url: '…/my/public-id.es.transcript' },
+      { label: 'Français', language: 'fr', url: '…/my/public-id.fr.transcript' },
+    ],
+    options: { theme: 'player-colors', wordHighlightStyle: { color: 'royalblue' } },
+  },
+
+  interactionAreas: {
+    enable: true,
+    template: [
+      { left: 8, top: 62, width: 34, height: 30, id: 'SKU-1' },   // percentages
+    ],
+    onClick: (event) => addToCart(event?.item?.id),
+  },
+  interactionDisplay: { enable: true, template: 'pulsing' },      // or 'shadowed'
+});
+```
+
+### chapters
+
+- `true` — loads `<publicId>-chapters.vtt` (what `auto_chaptering` produces)
+- `{ url: '…' }` — an external VTT
+- `{ 1: 'Chapter 1', 6: 'Chapter 2' }` — manual, keys are seconds
+
+### textTracks
+
+Omitting `url` on `captions` makes the player resolve the `.transcript` file for
+that public ID. Setting `maxWords` also triggers that lookup — it is the
+documented trigger, not merely a display cap. Translated transcripts live at
+`<publicId>.<lang>.transcript` and must be given explicitly.
+
+`wordHighlight: true` uses the transcript's word-level timings to highlight
+words as they are spoken; pair it with `maxWords` so the caption box does not
+fill. Style it with `options.wordHighlightStyle`.
+
+There is **no** native searchable-transcript panel option — see
+[build-patterns.md](build-patterns.md).
+
+`options.theme`: `'default'`, `'videojs-default'`, `'yellow-outlined'`,
+`'player-colors'`, `'3d'`.
+
+### interactionAreas
+
+`template` is either a preset string — `'portrait'`, `'landscape'`, `'all'`,
+`'center'` — or an array of areas. Area coordinates are **percentages** of the
+video frame, not pixels.
+
+The `onClick` handler receives an event with `event.item.id` and an
+`event.zoom()` method.
+
+## React and other frameworks
+
+Build the `<video>` element imperatively and do **not** dispose the player on
+effect cleanup. The player finishes initialising asynchronously — colors,
+adaptive streaming and interaction areas are lazy-loaded plugins that reach for
+the element after the effect returns. Disposing pulls the element out from under
+those pending callbacks and they throw on a null node
+(`Invalid target for null#one`, `Cannot set properties of null`).
+
+Route callbacks through refs so the effect can have an empty dependency list and
+build exactly one player for the page's lifetime.
+
+## Transformation notes for video
+
+- **The player applies `f_auto:video` itself.** Write format/quality
+  transformations only when you are hand-rolling a native `<video>`; on a
+  player source they are redundant, and pairing them with
+  `sourceTypes:['mp4']` re-adds by hand what forcing MP4 just removed. See
+  [capabilities.md](capabilities.md).
+- Prefer `f_auto/q_auto` as **separate components** over `f_auto,q_auto`.
+  Both are accepted and, as of September 2026, deliver byte-identical results
+  for image and video alike — this is a convention for readability and for
+  matching Cloudinary's own docs, **not** a correctness rule. Do not tell a
+  user the combined form is broken; it is not.
+- `sp_auto` is the streaming profile. It cannot be combined with a resize.
+- `e_preview[:duration_<s>][:max_seg_<n>][:min_seg_dur_<s>]` — AI summary reel,
+  video only, default duration 5.0s.
+- `g_auto` works with `c_fill`, `c_lfill`, `c_fill_pad`, `c_crop`, `c_thumb`,
+  `c_auto`, `c_auto_pad`. It does **not** work for positioning overlays.
diff --git a/skills/cloudinary-video/references/source-platforms.md b/skills/cloudinary-video/references/source-platforms.md
new file mode 100644
index 0000000..665288c
--- /dev/null
+++ b/skills/cloudinary-video/references/source-platforms.md
@@ -0,0 +1,125 @@
+# Getting the original sources off a video platform
+
+The governing rule, before any per-platform detail:
+
+> **Never ingest what the website delivers.** A page serves a player embed —
+> an `<iframe>`, not a file — backed by transcoded adaptive renditions. Ingest
+> that and Cloudinary transcodes a transcode: quality is permanently capped
+> below the original, every derived variant inherits the loss, and no
+> transformation can recover it. The master exists only in the source
+> platform's catalogue or the customer's own storage.
+
+Scraping a `.m3u8` or a progressive rendition off the live page is the failure
+this whole file exists to prevent. It *looks* like a successful migration.
+
+## What each platform allows
+
+Verified September 2026. Endpoints change; treat the shape as durable and
+re-check the specifics for the account in front of you.
+
+| Platform | Original retrievable? | Route |
+| --- | --- | --- |
+| Wistia | Yes — cleanest | Data API `medias#show` → `assets[]` → `type: "OriginalFile"` |
+| Brightcove | Yes, **not** via the obvious endpoint | Social Syndication API MRSS feed, `fetch_digital_master: true` → `asset.digital_master.url` |
+| Vimeo | Yes, plan-gated | Video endpoint with the `video_files` scope; paid tier |
+| YouTube | **No** | No API path. Google Takeout, or the customer's masters |
+
+### Wistia
+
+`GET https://api.wistia.com/v1/medias/{hashed_id}.json` returns an `assets`
+array. The one you want is `type: "OriginalFile"` — Wistia documents it as the
+source media that was uploaded, never used for playback, and used only as the
+blueprint for the streaming encodes. Every other asset type
+(`Mp4VideoFile`, `HdMp4VideoFile`, `IPhoneVideoFile`, …) is a rendition.
+
+Append `?disposition=attachment` to download rather than stream.
+
+Originals are much larger than the streaming assets. Expect the bandwidth.
+
+### Brightcove — the trap
+
+The intuitive endpoint is wrong:
+
+```
+GET https://cms.api.brightcove.com/v1/accounts/{account}/videos/{id}/sources
+```
+
+That returns **transcoded renditions**, not the master. It succeeds, it looks
+right, and it is exactly the mistake the rule above warns about. (For DRM'd
+content the equivalent is `/clear_sources` — still renditions.)
+
+Masters come from a different API entirely. Create an MRSS syndication:
+
+```
+POST https://social.api.brightcove.com/v1/accounts/{account}/mrss/syndications
+     { "type": "universal", "fetch_digital_master": true }
+```
+
+then read `asset.digital_master.url` from the feed. Template changes take up to
+10 minutes to appear, and feeds over 100 items need the `offset` parameter.
+
+**The master may legitimately not exist.** Brightcove documents two cases: a
+custom ingest profile configured not to store masters, and customers who
+deleted masters to save storage cost. Neither is recoverable by retrying — fall
+back to asking the customer for their own copy, and if there is none, say so
+rather than quietly ingesting a rendition.
+
+### Vimeo
+
+Requires a paid plan (Standard/Pro/Business/Enterprise and up) and a token
+carrying the `public`, `private` and `video_files` scopes. Without the plan the
+fields are simply absent — not an error you can work around.
+
+Three fields can appear on the video response, and they are not equivalent:
+
+| Field | Expiry | What it is |
+| --- | --- | --- |
+| `play` | 24h | playback-optimized; for third-party players |
+| `files` | none | renditions with dimensions/size metadata |
+| `download` | 24h | attachment-headed download links |
+
+**Vimeo's own documentation does not state which field carries the untranscoded
+original.** Do not guess — guessing here produces precisely the silent quality
+loss this file is about. Inspect the actual candidates for the video in hand
+(compare resolution, bitrate and file size against what the customer says they
+uploaded, and `ffprobe` the result) before committing to a field, or ask the
+customer for their master.
+
+### YouTube — a hard stop
+
+The YouTube Data API **cannot download source files**. There is no scope, no
+endpoint, no parameter. An agent cannot resolve this by trying harder.
+
+The only owner path is **Google Takeout**, which returns the files exactly as
+uploaded with no transcoding — but builds an account-wide zip rather than
+per-video downloads. For a handful of videos that is awkward but workable; it
+is a human action either way.
+
+So for YouTube: ask for the customer's masters first, and offer Takeout as the
+fallback. Never substitute a scraped rendition.
+
+## Cross-cutting
+
+**URLs expire.** Vimeo `play`/`download` are 24h, Wistia and Brightcove CDN
+locations have their own TTLs, Brightcove feed templates lag ~10 minutes. Fetch
+and upload promptly; do not collect a list of URLs now to ingest tomorrow.
+
+**Prefer download-then-upload over Cloudinary remote fetch.** Two reasons that
+compound: these URLs are authenticated and/or expiring, and — per
+[gotchas.md](gotchas.md) — on an unclaimed claimable cloud Cloudinary's own
+fetcher is blocked by the delivery IP allow-list, so remote fetch fails there
+regardless. Downloading locally first works on every destination.
+
+**Verify what you got.** `ffprobe` the downloaded file before uploading:
+resolution, bitrate, and whether an audio stream exists at all. That last one
+decides whether transcription and chaptering can work — see the async failure
+modes in [gotchas.md](gotchas.md).
+
+## Sources
+
+- Wistia, Asset URLs — https://docs.wistia.com/docs/asset-urls
+- Brightcove, Download Video Masters — https://apis.support.brightcove.com/social-syndication/getting-started/download-video-masters.html
+- Brightcove, CMS API download links — https://apis.support.brightcove.com/cms/code-samples/cms-api-sample-download-links.html
+- Vimeo, About video file download links from the API — https://help.vimeo.com/hc/en-us/articles/12427806914577-About-video-file-download-links-from-the-API
+- Vimeo, Video File response reference — https://developer.vimeo.com/api/reference/response/video-file
+- Google Takeout / YouTube original files — https://techcrunch.com/?p=660785
diff --git a/skills/cloudinary-video/test/lib.sh b/skills/cloudinary-video/test/lib.sh
new file mode 100644
index 0000000..074df70
--- /dev/null
+++ b/skills/cloudinary-video/test/lib.sh
@@ -0,0 +1,56 @@
+# Shared assertion helpers. Sourced by the test scripts.
+
+PASS=0; FAIL=0
+
+_ok()   { PASS=$((PASS+1)); printf '  \033[32m✓\033[0m %s\n' "$1"; }
+_no()   { FAIL=$((FAIL+1)); printf '  \033[31m✗\033[0m %s\n' "$1"; [ -n "$2" ] && printf '      %s\n' "$2"; }
+
+section() { printf '\n\033[1m%s\033[0m\n' "$1"; }
+
+# status <label> <url> [expected]   — assert an HTTP status
+status() {
+  local label=$1 url=$2 want=${3:-200} got
+  got=$(curl -s -o /dev/null -w '%{http_code}' -L --max-time 60 "$url")
+  [ "$got" = "$want" ] && _ok "$label" || _no "$label" "want $want, got $got — $url"
+}
+
+# body_has <label> <url> <substring>   — assert response contains text
+body_has() {
+  local label=$1 url=$2 needle=$3
+  if curl -s -L --max-time 60 "$url" | grep -q -- "$needle"; then
+    _ok "$label"
+  else
+    _no "$label" "missing '$needle' — $url"
+  fi
+}
+
+# file_has <label> <path> <substring>
+file_has() {
+  local label=$1 path=$2 needle=$3
+  if [ -f "$path" ] && grep -q -- "$needle" "$path"; then
+    _ok "$label"
+  else
+    _no "$label" "missing '$needle' in $path"
+  fi
+}
+
+# json_field <label> <url> <python-expr on `d`> <expected>
+json_field() {
+  local label=$1 url=$2 expr=$3 want=$4 got
+  got=$(curl -s -L --max-time 60 "$url" | python3 -c "
+import sys,json
+try: d=json.load(sys.stdin)
+except Exception: print('<not json>'); raise SystemExit
+try: print($expr)
+except Exception as e: print(f'<{e}>')
+" 2>/dev/null)
+  [ "$got" = "$want" ] && _ok "$label" || _no "$label" "want $want, got $got"
+}
+
+# summary — print the tally and EXIT. Always exits, so it doubles as the
+# early-return for a script that has hit a blocking condition (no cloud, no
+# credentials) and cannot meaningfully continue.
+summary() {
+  printf '\n%s passed, %s failed\n' "$PASS" "$FAIL"
+  [ "$FAIL" -eq 0 ] && exit 0 || exit 1
+}
diff --git a/skills/cloudinary-video/test/skill-claims.sh b/skills/cloudinary-video/test/skill-claims.sh
new file mode 100755
index 0000000..1f135d9
--- /dev/null
+++ b/skills/cloudinary-video/test/skill-claims.sh
@@ -0,0 +1,283 @@
+#!/usr/bin/env bash
+# Assert the factual claims the cloudinary-video skill makes.
+#
+# A skill that is confidently wrong is worse than one that is silent, and these
+# claims are the load-bearing ones — an agent following them will not
+# second-guess them. Every check here maps to a specific line of guidance, and
+# a failure means the SKILL is stale, not that the code is broken.
+#
+# Two modes:
+#
+#   ./skills/cloudinary-video/test/skill-claims.sh
+#                                          # claims checkable without credentials
+#   ./skills/cloudinary-video/test/skill-claims.sh --cloud
+#                                          # also provision a fresh cloud and
+#                                          # assert the upload/add-on claims
+#
+# --cloud takes a few minutes and needs the VPN paused. It also uploads two
+# media fixtures that are not vendored here (they are large); set MEDIA_DIR to
+# a directory holding CR-OCS-001.jpg and hero-tour.mp4 — they live in docs/media
+# of CloudinaryLtd/cloudinary-video-skill, where this skill is developed.
+
+set -uo pipefail
+cd "$(dirname "$0")" || exit 1
+. lib.sh
+
+WITH_CLOUD=0
+[ "${1:-}" = "--cloud" ] && WITH_CLOUD=1
+
+# --cloud uploads real media. The fixtures are too large to vendor into a skills
+# repo, so point MEDIA_DIR at a checkout that has them.
+MEDIA_DIR=${MEDIA_DIR:-}
+if [ "$WITH_CLOUD" = "1" ]; then
+  for f in CR-OCS-001.jpg hero-tour.mp4; do
+    [ -f "$MEDIA_DIR/$f" ] || {
+      echo "--cloud needs $f. Set MEDIA_DIR to a directory containing the" >&2
+      echo "fixtures (docs/media in CloudinaryLtd/cloudinary-video-skill)." >&2
+      exit 1
+    }
+  done
+fi
+
+SKILL=..
+DEMO_CLOUD=dxuiuruim   # a claimed cloud with the full feature set present
+
+http() { curl -s -o /dev/null -w '%{http_code}' -L --max-time 60 "$1"; }
+
+# claim <label> <condition-result> <detail>
+# Used where the assertion is computed rather than a simple status check.
+claim() { [ "$2" = "yes" ] && _ok "$1" || _no "$1" "$3"; }
+
+# ── Claims about delivery and transformations ───────────────────────────────
+
+section "Transformation claims (SKILL.md B2, capabilities.md)"
+
+# "breakpoints/resize cannot be combined with sp_auto — Cloudinary rejects it"
+CODE=$(http "https://res.cloudinary.com/$DEMO_CLOUD/video/upload/c_limit,w_2560/sp_auto/costera/hero-tour.m3u8")
+[ "$CODE" != "200" ] \
+  && _ok "resize + sp_auto is rejected ($CODE)" \
+  || _no "resize + sp_auto was ACCEPTED" "SKILL says rejected; guidance is stale"
+
+# "Prefer f_auto/q_auto separate; the combined form is a convention, NOT a
+#  correctness rule." Assert the equivalence, so that if Cloudinary ever does
+#  start rejecting the combined form the guidance gets revisited.
+SEP=$(http "https://res.cloudinary.com/$DEMO_CLOUD/video/upload/f_auto/q_auto/costera/hero-tour.mp4")
+JOINT=$(http "https://res.cloudinary.com/$DEMO_CLOUD/video/upload/f_auto,q_auto/costera/hero-tour.mp4")
+claim "f_auto/q_auto (separate) delivers ($SEP)" \
+  "$([ "$SEP" = "200" ] && echo yes || echo no)" "expected 200, got $SEP"
+if [ "$JOINT" = "200" ]; then
+  # Same bytes? Then they are genuinely interchangeable and player.md is right
+  # to call it a convention rather than a rule.
+  L1=$(curl -s -o /dev/null -w '%{size_download}' -L --max-time 60 "https://res.cloudinary.com/$DEMO_CLOUD/video/upload/f_auto/q_auto/costera/hero-tour.mp4")
+  L2=$(curl -s -o /dev/null -w '%{size_download}' -L --max-time 60 "https://res.cloudinary.com/$DEMO_CLOUD/video/upload/f_auto,q_auto/costera/hero-tour.mp4")
+  [ "$L1" = "$L2" ] \
+    && _ok "f_auto,q_auto (combined) is equivalent — convention, not a rule" \
+    || _no "combined form delivers different bytes ($L1 vs $L2)" "player.md claims equivalence"
+else
+  _no "f_auto,q_auto combined now returns $JOINT" "player.md says both are accepted — guidance is stale"
+fi
+
+# "sp_auto returns a manifest with a rendition ladder"
+body_has "sp_auto manifest lists renditions" \
+  "https://res.cloudinary.com/$DEMO_CLOUD/video/upload/sp_auto/costera/hero-tour.m3u8" "RESOLUTION="
+
+# "breakpoints is mutually exclusive with sp_auto at EVERY width — the skill
+#  says verified 640..2560, so verify it rather than trusting one sample."
+BP_OK=yes
+for w in 640 1280 1920 2560; do
+  C=$(http "https://res.cloudinary.com/$DEMO_CLOUD/video/upload/c_limit,w_$w/sp_auto/costera/hero-tour.m3u8")
+  [ "$C" = "200" ] && BP_OK="w=$w accepted ($C)"
+done
+claim "resize+sp_auto rejected at every width (640-2560)" \
+  "$([ "$BP_OK" = "yes" ] && echo yes || echo no)" \
+  "$BP_OK — capabilities.md claims all widths are rejected"
+
+# "progressive accepts the same widths breakpoints would pick between"
+PROG_OK=yes
+for w in 640 1280 1920; do
+  C=$(http "https://res.cloudinary.com/$DEMO_CLOUD/video/upload/c_limit,w_$w/f_auto/q_auto/costera/hero-tour.mp4")
+  [ "$C" != "200" ] && PROG_OK="w=$w failed ($C)"
+done
+claim "progressive path accepts explicit widths" \
+  "$([ "$PROG_OK" = "yes" ] && echo yes || echo no)" "$PROG_OK"
+
+section "Async output shape claims (build-patterns.md)"
+
+# "<publicId>.transcript is Cloudinary JSON, not WebVTT"
+SHAPE=$(curl -s -L --max-time 60 "https://res.cloudinary.com/$DEMO_CLOUD/raw/upload/costera/hero-tour.transcript" \
+  | python3 -c "
+import sys,json
+raw=sys.stdin.read()
+if raw.lstrip().startswith('WEBVTT'): print('vtt'); raise SystemExit
+try: d=json.loads(raw)
+except Exception: print('neither'); raise SystemExit
+print('json-words' if (isinstance(d,list) and d and d[0].get('words')) else 'json-plain')
+" 2>/dev/null)
+claim "transcript is JSON with word-level timings" \
+  "$([ "$SHAPE" = "json-words" ] && echo yes || echo no)" \
+  "got '$SHAPE' — build-patterns.md relies on words[].start_time"
+
+# "auto_chaptering produces <publicId>-chapters.vtt, and it IS WebVTT"
+body_has "chapters file is WebVTT at <id>-chapters.vtt" \
+  "https://res.cloudinary.com/$DEMO_CLOUD/raw/upload/costera/hero-tour-chapters.vtt" "WEBVTT"
+
+# "translated transcripts live at <publicId>.<lang>.transcript"
+status "translated transcript path (.es.transcript)" \
+  "https://res.cloudinary.com/$DEMO_CLOUD/raw/upload/costera/hero-tour.es.transcript"
+
+section "Player transcript-support claims (build-patterns.md, player.md)"
+
+# The player consumes .transcript natively (maxWords triggers the lookup,
+# wordHighlight uses the word timings). What it does NOT have is a searchable
+# transcript panel. Both halves are documented, so both are asserted — the
+# second as a doc check, since absence of an option cannot be probed by curl.
+file_has "maxWords documented as the .transcript trigger" \
+  "$SKILL/references/player.md" "maxWords"
+file_has "wordHighlight documented" \
+  "$SKILL/references/player.md" "wordHighlight"
+file_has "no-native-searchable-panel recorded" \
+  "$SKILL/references/build-patterns.md" "no\*\* native support for is a \*\*searchable transcript"
+file_has "player-vs-yours split stated" \
+  "$SKILL/references/build-patterns.md" "an on-page searchable transcript is yours"
+
+section "Player distribution claims (SKILL.md B3)"
+
+# The script-tag URLs the skill tells people to use must actually resolve.
+status "player JS at the pinned version" \
+  "https://unpkg.com/cloudinary-video-player/dist/cld-video-player.min.js"
+status "player CSS at the pinned version" \
+  "https://unpkg.com/cloudinary-video-player/dist/cld-video-player.min.css"
+
+section "Source-platform claims (source-platforms.md)"
+
+# "The YouTube Data API cannot download source files." Asserting a negative
+# against a live API needs credentials, so this checks the weaker but still
+# useful thing: that the doc records it as a hard stop with a human fallback,
+# so an agent does not burn a run retrying.
+file_has "YouTube recorded as having no API path" \
+  "$SKILL/references/source-platforms.md" "No API path"
+file_has "Brightcove /sources trap is called out" \
+  "$SKILL/references/source-platforms.md" "returns \*\*transcoded renditions\*\*"
+file_has "Vimeo original field marked unverified" \
+  "$SKILL/references/source-platforms.md" "does not state which field"
+
+section "Internal consistency"
+
+for f in capabilities.md build-patterns.md source-platforms.md player.md gotchas.md; do
+  [ -f "$SKILL/references/$f" ] && _ok "reference exists: $f" || _no "missing reference: $f"
+done
+
+# Every references/ link in the skill must resolve.
+BROKEN=$(grep -oh 'references/[a-z-]*\.md' "$SKILL/SKILL.md" "$SKILL"/references/*.md \
+  | sort -u | while read -r r; do [ -f "$SKILL/$r" ] || echo "$r"; done)
+[ -z "$BROKEN" ] && _ok "all reference links resolve" || _no "broken links" "$BROKEN"
+
+# ── Claims that need a fresh cloud ──────────────────────────────────────────
+
+if [ "$WITH_CLOUD" -eq 0 ]; then
+  printf '\n\033[90mSkipping upload/add-on claims. Rerun with --cloud to assert those.\033[0m\n'
+  summary
+fi
+
+section "Provision a throwaway cloud"
+RESP=$(npx --yes @cloudinary/cloud --json --no-env \
+  --goal "assert the factual claims in the cloudinary-video skill" \
+  --model claude-opus-5 2>&1 | sed -n '/^{/,$p')
+
+if echo "$RESP" | grep -q delivery_ips_not_public; then
+  _no "provision" "behind a VPN — pause it and rerun"
+  summary
+fi
+
+eval "$(echo "$RESP" | python3 -c "
+import sys,json
+d=json.load(sys.stdin); e=d['product_environments'][0]
+print(f'CLOUD={e[\"cloud_name\"]}'); print(f'KEY={e[\"api_key\"]}'); print(f'SEC={e[\"api_secret\"]}')
+print(f'CLAIM=\"{d[\"claim_url\"]}\"')
+" 2>/dev/null)"
+[ -n "${CLOUD:-}" ] && _ok "provisioned $CLOUD" || { _no "provision" "$RESP"; summary; }
+
+API="https://api.cloudinary.com/v1_1/$CLOUD"
+
+section "Entitlement-API claims (SKILL.md A4, capabilities.md)"
+
+# "There is no Admin API for add-ons: /addons, /add_ons, /subscriptions and
+#  /entitlements all 404."
+for ep in addons add_ons subscriptions entitlements; do
+  C=$(curl -s -o /dev/null -w '%{http_code}' -u "$KEY:$SEC" "$API/$ep")
+  [ "$C" = "404" ] \
+    && _ok "/$ep returns 404, as documented" \
+    || _no "/$ep returned $C, not 404" "capabilities.md says no entitlement API exists"
+done
+
+section "Add-on failure-mode claims (SKILL.md A4)"
+
+# THE load-bearing claim: "requesting a subscribed-only add-on rejects the
+# WHOLE upload — the asset is never stored". If this ever degrades gracefully
+# instead, the upload-free-features-first rule becomes unnecessary.
+PROBE=$(curl -s "$API/image/upload" -u "$KEY:$SEC" \
+  -F "file=@$MEDIA_DIR/CR-OCS-001.jpg" -F "public_id=claims/addon_probe" \
+  -F "categorization=google_tagging")
+if echo "$PROBE" | grep -qi "subscription"; then
+  _ok "add-on request rejected with a subscription error"
+  STORED=$(curl -s -o /dev/null -w '%{http_code}' -u "$KEY:$SEC" \
+    "$API/resources/image/upload/claims%2Faddon_probe")
+  [ "$STORED" = "404" ] \
+    && _ok "and the asset was NOT stored (upload free features first)" \
+    || _no "the asset WAS stored ($STORED)" "SKILL says the whole upload is rejected"
+elif echo "$PROBE" | grep -q '"public_id"'; then
+  _ok "google_tagging is available on this fresh cloud (unexpected but fine)"
+else
+  _no "add-on probe gave neither" "$(echo "$PROBE" | head -c 200)"
+fi
+
+# "auto_transcription WITH translate fails the whole transcription on a cloud
+#  without Google Translation, where plain auto_transcription succeeds."
+section "Translate-is-the-add-on-part claim (SKILL.md A4)"
+T=$(curl -s "$API/video/upload" -u "$KEY:$SEC" \
+  -F "file=@$MEDIA_DIR/hero-tour.mp4" -F "public_id=claims/translate_probe" \
+  -F "auto_transcription[translate][]=es")
+if echo "$T" | grep -qi "subscription\|translation"; then
+  _ok "auto_transcription+translate rejected without the add-on"
+else
+  printf '  \033[33m◐\033[0m auto_transcription+translate did not error outright\n'
+  printf '      response: %s\n' "$(echo "$T" | head -c 160)"
+fi
+
+section "Free-feature claims (SKILL.md A4 table)"
+FREE=$(curl -s "$API/video/upload" -u "$KEY:$SEC" \
+  -F "file=@$MEDIA_DIR/hero-tour.mp4" -F "public_id=claims/free_probe" \
+  -F "auto_transcription=true" -F "auto_chaptering=true" -F "auto_video_details=true")
+if echo "$FREE" | grep -q '"public_id"'; then
+  _ok "auto_transcription + auto_chaptering + auto_video_details accepted on a fresh cloud"
+  # "They return status: pending and finish later" — assert pending, not done.
+  PEND=$(echo "$FREE" | python3 -c "
+import sys,json
+d=json.load(sys.stdin); i=d.get('info',{})
+sts={k:v.get('status') for k,v in i.items() if isinstance(v,dict) and 'status' in v}
+print(','.join(f'{k}={v}' for k,v in sorted(sts.items())) or 'none')
+" 2>/dev/null)
+  case $PEND in
+    *pending*) _ok "async features report pending: $PEND" ;;
+    none)      _no "no async status in the upload response" "SKILL says they return pending" ;;
+    *)         printf '  \033[33m◐\033[0m async statuses: %s\n' "$PEND" ;;
+  esac
+else
+  _no "free features were rejected" "$(echo "$FREE" | head -c 200)"
+fi
+
+section "Unclaimed-cloud remote-fetch claim (gotchas.md)"
+# "On an unclaimed cloud, POST /upload with file=<a delivery URL on that same
+#  cloud> fails 401 — Cloudinary's fetcher is not an allowed delivery IP."
+RF=$(curl -s "$API/image/upload" -u "$KEY:$SEC" \
+  -F "file=https://res.cloudinary.com/$CLOUD/image/upload/claims/addon_probe.jpg" \
+  -F "public_id=claims/remote_fetch_probe")
+if echo "$RF" | grep -qi "401\|unauthor\|not allowed"; then
+  _ok "remote fetch of own delivery URL fails on an unclaimed cloud"
+else
+  printf '  \033[33m◐\033[0m remote fetch did not fail as documented\n'
+  printf '      response: %s\n' "$(echo "$RF" | head -c 160)"
+fi
+
+printf '\n\033[1mThrowaway cloud\033[0m %s — expires in 24h, claim only if you want it:\n  %s\n' "$CLOUD" "$CLAIM"
+summary

From 11f695fedf588d9f948bef98e0a28d3d9ba6fb8a Mon Sep 17 00:00:00 2001
From: Ebenezer Don <ebenezer.don@cloudinary.com>
Date: Thu, 8 Oct 2026 11:41:13 +0100
Subject: [PATCH 2/3] Revise cloudinary-video for the platform category and
 split out migration

- Move the skill to skills/platform/cloudinary-video and list it under
  Platform in the README.
- Split out the platform-migration content (getting originals off other
  platforms, mining an existing site, source-platforms.md) for a separate
  asset-migration skill; keep two short tips for media from other platforms.
- Follow the repo conventions: version 1.0.0, a "Reference for... Use when..."
  description, When to Use, Quick Start rules, Additional Resources with
  tracked doc links, and Related Skills. Move upload and preparation detail
  to references/upload-and-prepare.md to keep SKILL.md under 500 lines.
- Correct claims that the docs, the player 4.1.0 source, or live requests
  contradict: first-request behaviour (streams with the wrong duration; 423
  only for async derivations), sourceTypes and breakpoints per source() call,
  maxDpr, autoplayMode, eager with f_auto, thresholds aligned with the field
  guidance, audio-only sources, lazy posters, seek thumbnails on loops, and
  warming with a browser User-Agent.
- Trim player.md to traps and link the API reference, drop internal
  references, and replace em dashes.
- Move the claim tests to tests/cloudinary-video, run them against the public
  demo cloud, and note the tests/ convention in CONTRIBUTING.md.
---
 CONTRIBUTING.md                               |   6 +
 README.md                                     |   2 +-
 skills/cloudinary-video/SKILL.md              | 697 ------------------
 .../references/field-guide.md                 | 122 ---
 skills/cloudinary-video/references/gotchas.md | 250 -------
 skills/cloudinary-video/references/player.md  | 306 --------
 .../references/source-platforms.md            | 125 ----
 skills/platform/cloudinary-video/SKILL.md     | 499 +++++++++++++
 .../references/build-patterns.md              |  82 ++-
 .../references/capabilities.md                | 149 ++--
 .../references/field-guide.md                 | 147 ++++
 .../cloudinary-video/references/gotchas.md    | 264 +++++++
 .../cloudinary-video/references/player.md     | 250 +++++++
 .../references/upload-and-prepare.md          | 158 ++++
 .../test => tests/cloudinary-video}/lib.sh    |  15 +-
 .../cloudinary-video}/skill-claims.sh         | 163 ++--
 16 files changed, 1547 insertions(+), 1688 deletions(-)
 delete mode 100644 skills/cloudinary-video/SKILL.md
 delete mode 100644 skills/cloudinary-video/references/field-guide.md
 delete mode 100644 skills/cloudinary-video/references/gotchas.md
 delete mode 100644 skills/cloudinary-video/references/player.md
 delete mode 100644 skills/cloudinary-video/references/source-platforms.md
 create mode 100644 skills/platform/cloudinary-video/SKILL.md
 rename skills/{ => platform}/cloudinary-video/references/build-patterns.md (70%)
 rename skills/{ => platform}/cloudinary-video/references/capabilities.md (56%)
 create mode 100644 skills/platform/cloudinary-video/references/field-guide.md
 create mode 100644 skills/platform/cloudinary-video/references/gotchas.md
 create mode 100644 skills/platform/cloudinary-video/references/player.md
 create mode 100644 skills/platform/cloudinary-video/references/upload-and-prepare.md
 rename {skills/cloudinary-video/test => tests/cloudinary-video}/lib.sh (75%)
 rename {skills/cloudinary-video/test => tests/cloudinary-video}/skill-claims.sh (63%)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9e2aa71..621260e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -92,6 +92,12 @@ attributable. Use the same `referrer` value throughout a skill, for example
 `trans-skill` or `react-skill`. CI fails the `links` job on any link missing
 either param.
 
+## Tests
+
+A skill's tests, if it has any, live in `tests/<skill-name>/` at the repo root,
+not inside the skill directory, so they don't ship to users who install the
+skill.
+
 ## Local check
 
 Before opening a PR, run the same checks CI runs:
diff --git a/README.md b/README.md
index 0f3583b..8ec9b73 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,7 @@ Skills are grouped by category below. The category is a folder in this repo only
 |---|---|
 | `cloudinary-docs` | Selects the most relevant markdown pages from the current documentation using the latest llms.txt. Use when answering Cloudinary questions or integrating Cloudinary into code. |
 | `cloudinary-transformations` | Turns natural language image and video transformation requirements into valid URL transformation strings that follow Cloudinary best practices. Use when building delivery URLs, applying transformations, optimizing media, or debugging transformation syntax errors. |
+| `cloudinary-video` | Reference for building video experiences with the Cloudinary Video Player. Use when adding or improving video on a page or site, choosing adaptive or progressive delivery, or generating captions, chapters, and titles for video. |
 
 ### Frameworks
 
@@ -19,7 +20,6 @@ Skills are grouped by category below. The category is a folder in this repo only
 |---|---|
 | `cloudinary-react` | Provides opinionated React SDK patterns for configuration, common integration scenarios, and troubleshooting for frequent errors and TypeScript pitfalls. Use when developing React apps with Cloudinary. |
 | `cloudinary-next` | Provides opinionated Next.js SDK patterns for Server and Client Component boundaries, server-side uploads and deletes, and troubleshooting for frequent errors and TypeScript pitfalls. Use when developing Next.js apps with Cloudinary. |
-| `cloudinary-video` | Builds video experiences on the Cloudinary Video Player — adaptive streaming, chapters, captions, transcripts, hotspots, and AI analysis — and migrates media onto Cloudinary from Brightcove, Vimeo, YouTube, or Wistia. Use when building or improving a video site on Cloudinary. |
 
 ## Install
 
diff --git a/skills/cloudinary-video/SKILL.md b/skills/cloudinary-video/SKILL.md
deleted file mode 100644
index 4e0834a..0000000
--- a/skills/cloudinary-video/SKILL.md
+++ /dev/null
@@ -1,697 +0,0 @@
----
-name: cloudinary-video
-description: Build websites with the Cloudinary Video Player — adaptive streaming, chapters, captions, transcripts, hotspots, AI analysis and metadata — on an existing Cloudinary cloud, or migrating the media on first. Use when building or improving a video experience on Cloudinary, moving video off Brightcove, Vimeo, YouTube or Wistia, or standing up a cloud for a demo.
-license: MIT
-metadata:
-  author: cloudinary
-  version: '2.1.0'
----
-
-# Building video sites on Cloudinary
-
-Covers what the published `cloudinary-transformations` and `cloudinary-docs`
-skills do not: **the video player, the async AI features, provisioning, and
-getting existing media onto a cloud.** Those skills handle transformation URLs.
-Use them for that; use this for everything else.
-
-## How to use this
-
-You are helping someone reach a goal for their video experience, not applying a
-checklist. So:
-
-- **Ask when the answer changes the build.** The delivery branch, where the
-  media comes from, which cloud it lands on, whether an add-on exists — a wrong
-  guess here costs a whole run. One question beats an assumption. The questions
-  worth asking up front are in *Start here* below.
-- **Ask when you are unsure.** That is legitimate and always preferable to
-  quietly picking a default and presenting it as the decision. Say what you
-  would pick and why, then let them redirect.
-- **Recommend, don't enumerate — in conversation.** Where this skill gives
-  options, pick the one that fits and say so in a line. Spend their attention
-  on the thing you built, not on a tour of the choices behind it.
-- **But build generously.** The restraint is in what you *say*, never in what
-  you ship. Build the full experience — chapters, transcript, captions, AI
-  poster, preview loops, structured data, responsive delivery — not a minimum
-  viable one. Deleting a feature they do not want takes a minute; never seeing
-  it means they never knew to ask. Err toward the wow — but the wow is the
-  experience working, never the page advertising how it works. Ship their site,
-  not an exhibit about Cloudinary; see *Ship the site, not the demo
-  scaffolding* in [references/build-patterns.md](references/build-patterns.md).
-- **Say what is not there.** A missing add-on, an unreachable original, a
-  feature Cloudinary does not generate — name it plainly and move on. Silence
-  and approximation both cost more later.
-
-The work has two phases, and the first one is often skipped:
-
-- **Phase A — establish the assets.** Only needed if the media is not already
-  on a Cloudinary cloud.
-- **Phase B — build the site.** The substance: optimization strategy, player
-  capabilities, analysis and metadata.
-
-## Start here: get the intent, then the logistics
-
-Do not begin until you know what they are building. Each answer below changes
-the work substantially, so **ask for any you were not given** — one question
-costs a message, a wrong guess costs a run.
-
-**1. What are you building, and what should the video do there?**
-
-The one question the rest depends on. A product-page loop, a long-form library,
-a course, a news page and a landing hero want different delivery, different
-player features and different page shapes. Get this and most later choices
-follow; skip it and you will build a competent version of the wrong thing.
-
-**Do not interview them about features.** Do not ask whether they want
-captions, chapters, transcripts or hover previews — build them. Someone
-describing what they want in chat should get the magic without being asked to
-specify it, and should see everything Cloudinary can do for them before
-deciding what to keep.
-
-**2. Do you have an existing website or app — is this a migration or from
-scratch?**
-
-A migration gives you three things at once: the media, the conventions to match
-(layout, naming, structure), and human-authored metadata worth more than
-anything regenerated — see A2. From scratch, the builder supplies the sources;
-do not go looking.
-
-**3. Are the assets already on a Cloudinary cloud?**
-
-Yes → **skip phase A entirely.** Go to phase B. Confirm the cloud name, how you
-reach it (MCP or `CLOUDINARY_URL` — see the routing table in
-[references/capabilities.md](references/capabilities.md)), and which public IDs
-to build against. Do not re-upload assets that are already there.
-
-No → migration is needed, so:
-
-**4. Where are the resources?**
-
-| Source | What it means |
-| --- | --- |
-| **An existing website** | Try to fetch it for them; otherwise ask them to provide or map it. The site is also your source of guidelines and mapping — see below. |
-| **From scratch** | The builder provides the asset sources. Do not go looking; ask. |
-
-**A named real site is never a cue to reach for Cloudinary's `demo` cloud or
-any other stock/sample assets.** If the user names a real site or brand
-("build a page for gap.com"), you must actually open that site and pull its
-real images/video before writing any page code — do not silently substitute
-placeholder assets because fetching feels slower or the site has no obvious
-video element. Only fall back to demo/stock assets if, after actually trying,
-the real assets are genuinely unreachable (login-gated, blocked, no usable
-media) — and even then, say so explicitly and ask the user before
-substituting anything. Silently swapping in demo-cloud assets for a named
-brand is the single failure mode this rule exists to prevent.
-
-**5. Where does it land — an existing cloud, or a new claimable one?**
-
-| Destination | Consequences |
-| --- | --- |
-| Their **existing cloud** | No provisioning. No claim URL. Respect existing folders, naming and presets. Re-runs cost real quota and can overwrite live assets — be idempotent, and never loop the catalogue to probe. |
-| A **fresh claimable cloud** | Provision it (below). Expect no add-ons. Surface the claim URL at the end. Provision a new one per test run. |
-
-Local files into an existing cloud is a legitimate combination — source and
-destination are independent choices.
-
-**Detect what you can, ask what you cannot.** Duration, whether there is an
-audio track, resolution and which add-ons a cloud has are all measurable —
-`ffprobe` the source, probe one asset. Do not spend a question on something you
-can check, and do not guess at something you cannot.
-
----
-
-# Phase A — establish the assets
-
-## A1. Get the originals
-
-**Find the video in the raw HTML, not in a browser's DOM.** `curl` the page
-and grep the source *first*:
-
-```sh
-curl -s -A "<a real desktop UA>" "<page url>" -o page.html
-grep -oE '[A-Za-z0-9_-]+\.(mp4|m3u8|webm|mov)' page.html | sort -u
-```
-
-**Do not conclude "this site has no video" from `document.querySelectorAll`.**
-An automated/headless browser's DOM is systematically *less complete* than
-what a real user sees, and it fails silently — you get a clean empty array,
-not an error:
-
-- On a React/Next.js site the `<video>` element is often created by
-  client-side hydration. The asset URL sits in the server-rendered JSON
-  payload (`__NEXT_DATA__`, RSC flight data, inline `<script>` state) while
-  the raw HTML contains **zero** `<video` tags. If hydration doesn't complete,
-  the element never exists to be queried.
-- Bot-detection layers (Akamai, Cloudflare, PerimeterX) serve automated
-  browsers a degraded page. `document.readyState === "complete"` still
-  reports complete — completeness of the *document* is not completeness of
-  the *content*.
-- A tell-tale sign you are looking at a hydrated-only element: its class is a
-  runtime-generated hash (`sitewide-ekvlu4`, `css-1a2b3c`) that appears
-  nowhere in the raw HTML.
-
-This is a real, observed failure: on gap.com the served HTML carried six
-`.mp4` URLs in its JSON payload and the driven browser reported **zero**
-video elements — after waiting for idle, after a shadow-DOM-piercing search,
-and at desktop viewport width. The grep above found all six instantly.
-
-Then, to catch what the source grep cannot (assets requested only at
-runtime):
-- Scroll the whole page and let it idle — some clips lazy-load.
-- List **every** network request, not just ones pre-filtered by extension —
-  a plain `<img src="...">` can return a `video/mp4` response.
-- Check more than one page type — homepage, campaign/collection, and product
-  detail each carry different media.
-
-Confirm any URL you find with `curl -sIL <url>` and read the `content-type`
-before trusting it. Only if all of that comes back empty may you say the site
-has no video — and then ask before falling back to placeholder assets (see
-the rule above on named real sites).
-
-**Never ingest what the website delivers.** A page serves a player embed backed
-by transcoded adaptive renditions. Ingest that and Cloudinary transcodes a
-transcode — quality is permanently capped below the original and every derived
-variant inherits the loss. Get the master from the source platform or the
-customer's own storage.
-
-This is the rule that decides whether a migration is worth anything. Full
-per-platform detail, verified, in
-[references/source-platforms.md](references/source-platforms.md):
-
-| Platform | Original retrievable? |
-| --- | --- |
-| Wistia | Yes — `medias#show` → `OriginalFile` asset |
-| Brightcove | Yes, but **not** via `/videos/{id}/sources` (those are renditions). Needs the Social Syndication master feed, and the master may have been deleted. |
-| Vimeo | Yes, but plan-gated and the field carrying the true original is undocumented — verify, do not guess |
-| YouTube | **No API path.** Google Takeout or the customer's masters |
-
-Graduated fallback when you cannot fetch: **fetch → ask them to provide → ask
-them to map.** All three are legitimate outcomes. Silently substituting a
-scraped rendition is not.
-
-Prefer download-then-upload over Cloudinary remote fetch: source URLs expire and
-are authenticated, and on an unclaimed cloud Cloudinary's own fetcher is blocked
-by the delivery IP allow-list anyway.
-
-`ffprobe` what you downloaded before uploading — resolution, bitrate, and
-whether an audio stream exists at all. That last one decides whether
-transcription and chaptering can work.
-
-## A2. Mine the existing site for guidelines and mapping
-
-When migrating from an existing website, the site is an **input to the build**,
-not just a media source. Three things to take from it:
-
-- **Structure and conventions** — layout, look, naming, how pages are
-  organized. You are improving their page, not replacing it with yours.
-- **Human-authored metadata** — captions, chapter lists, titles, descriptions,
-  tags. **Prefer these over regenerating.** A caption a human wrote and paid for
-  beats `auto_transcription` output. Source platforms often carry cue points and
-  custom fields that already hold the chapter→product bindings Cloudinary cannot
-  infer.
-- **The old→new mapping** — old asset/embed reference to new public ID. This is
-  what makes rewiring mechanical and verifiable rather than a hunt.
-
-Say what had no Cloudinary equivalent rather than approximating it.
-
-## A3. Provision a cloud (fresh-cloud destinations only)
-
-```sh
-npx @cloudinary/cloud --goal "<what you are building>" --model <your-model-id>
-```
-
-No signup, no credentials. Writes `CLOUDINARY_URL` to `./.env` and prints a
-**claim URL** a human can open later to keep the account.
-
-- `--ip <address>` — public IP allowed to view delivered media, repeatable, max
-  3. **Leave it off unless you know better**: the default locks delivery to the
-  calling address, which is almost always right. Getting this wrong is the main
-  way a migration appears to succeed while every asset 404s — uploads are never
-  IP-restricted, only CDN delivery.
-- `--json` — machine-readable, including `claim_url` and `expires_at`
-- `--no-env` — print credentials instead of writing `.env`
-
-**The cloud expires 24 hours after provisioning** unless claimed. Surface the
-claim URL at the end; it is what makes the work permanent. Never commit `.env`.
-
-**Provision a new cloud for every test run.** Reusing one skips exactly the work
-most likely to break, because it only breaks the first time: assets are already
-uploaded, async analysis already reports `complete` rather than `pending`, and
-derivations are warm so nothing returns 423. The clouds are free and expire on
-their own.
-
-If provisioning fails with `delivery_ips_not_public`, the connection is behind a
-VPN or secure gateway. That is the user's to resolve — see
-[references/gotchas.md](references/gotchas.md).
-
-## A4. Upload, and trigger analysis on the way in
-
-Ask for the AI features **on the upload call**. Re-running them afterwards costs
-a second operation against a quota.
-
-```
-upload video:                    # free
-  auto_transcription: true       # transcript + captions
-  auto_chaptering: true          # chapter VTT
-  auto_video_details: true       # title + description
-
-then, separately, and tolerate failure:
-  auto_transcription: { translate: ['es','fr'] }   # needs Google Translation
-  categorization: 'google_video_tagging'           # needs that add-on
-```
-
-`translate` is the add-on part, not transcription itself. Requesting
-`auto_transcription` **with** `translate` on a cloud without Google Translation
-fails the **whole** transcription — no transcript, no captions — where plain
-`auto_transcription` would have succeeded.
-
-`auto_video_details` is worth requesting here rather than leaving to the player.
-The player's `title: true` / `description: true` read the asset's context
-metadata and only trigger generation if no value is found — so an
-un-pre-generated title is a request happening for the first time mid-demo.
-
-```
-upload image:                    # free
-  (no analysis parameters)
-
-then, separately, and tolerate failure:
-  categorization: 'google_tagging'
-  auto_tagging: 0.65             # needs Google Auto Tagging
-```
-
-Know what image tagging returns before building on it: it describes **what is in
-the frame**. A hotel room yields `bed`, `bedding`, `ceiling`, `lamp` — accurate,
-and not what a guest filters by. Commercial attributes like "ocean view" are not
-visible to an image model. Use it for library search and coverage, not as a
-replacement for curated facets.
-
-### Upload rules that have bitten real runs
-
-1. **Upload with only the free features first.** Requesting a subscribed-only
-   add-on rejects the whole upload — the asset is never stored — which looks
-   like a broken upload rather than a missing entitlement.
-2. **Then try add-ons separately**, and treat failure as expected.
-3. **Add-ons cannot be enabled by an agent.** It is a console action, which on a
-   claimable cloud means claiming it first. No Admin API exists: `/addons`,
-   `/add_ons`, `/subscriptions`, `/entitlements` all 404.
-4. **An account-level upload preset can rewrite every asset on ingest** — adding
-   a watermark, downsizing — injected into signed uploads whether you ask or
-   not. Pass an explicit clean `upload_preset`. See
-   [references/gotchas.md](references/gotchas.md).
-5. **Overwriting a public ID can silently keep the old asset.** If a re-upload
-   reports new dimensions but delivery serves the old file, change the path.
-
-**Say which features are missing and why.** A run that silently drops translated
-subtitles has misled the user; one that says "translated subtitles need the
-Google Translation add-on, which needs the cloud claimed first" has not.
-
-## A5. Wait for the async features
-
-`auto_transcription`, `auto_chaptering` and title/description return
-`status: "pending"` and finish later — **or return `status: "failed"`**. Poll
-each until `complete`; never assume success.
-
-```sh
-curl -sf -o /dev/null https://res.cloudinary.com/<cloud>/raw/upload/<public_id>.transcript
-```
-
-They need **real speech**. Music-only or silent video produces no transcript, no
-chapters and no generated title. These features fail, they do not degrade.
-
-## A6. Warm the derivations
-
-The **first** request for an un-derived variant returns **HTTP 423** while
-Cloudinary builds it. `e_preview` can take minutes. An un-derived variant
-requested for the first time in front of an audience is a visible stall.
-
-```sh
-until [ "$(curl -s -o /dev/null -w '%{http_code}' "$URL")" = "200" ]; do sleep 5; done
-```
-
-Warm every URL the page will use, including hover previews and sprite sheets.
-
-**A 200 is not enough for video.** A derivative still being built can return
-200 with a *truncated* file, which the browser then caches — a 14-second source
-delivered as 2.6 seconds that refuses to play, with nothing in the status code
-to say so. Check the duration, not the status:
-
-```sh
-curl -s "$URL" -o /tmp/w.mp4
-ffprobe -v error -show_entries format=duration -of default=nk=1:nw=1 /tmp/w.mp4
-```
-
-**Re-warm whenever the delivery URLs change.** Each distinct transformation is
-its own derivative, so warming `sp_auto` does nothing for the progressive MP4s
-you switch to later, and responsive breakpoints mean warming a set of widths.
-Hard-reload afterwards to evict any truncated response already cached.
-
-For a real launch or a traffic spike, use **eager transformations at upload**
-instead of warming after the fact — see
-[references/field-guide.md](references/field-guide.md).
-
----
-
-# Phase B — build the site
-
-**Read [references/field-guide.md](references/field-guide.md) alongside this.**
-It carries Cloudinary's own delivery best practices — the duration-based
-delivery cheat sheet, the optimizations customers most often miss, the
-`f_auto` transformation-usage spike to warn about, eager transformations,
-mobile-app delivery, and the pre-launch validation checklist. Phase B below is
-how to build; the field guide is what "built well" means.
-
-## B1. Resolve what this cloud can actually do
-
-Before writing page code, settle the capability set — one explicit flag map,
-with a fallback per feature. This is what keeps a page honest on a cloud without
-add-ons instead of rendering empty rails and dead caption buttons.
-
-**On a fresh cloud**, assume no add-ons: translated subtitles and machine tags
-will be absent every time, and that is correct rather than a regression.
-
-**On a customer cloud**, probe — attempt the operation on **one** asset and read
-the result. Never loop the catalogue: free tiers are small (Google Auto Tagging
-50/month, Video Tagging 5/month) and on a customer cloud quota is their money.
-
-The full matrix, the detection rules, and the **MCP vs `CLOUDINARY_URL` routing
-table** are in [references/capabilities.md](references/capabilities.md). The
-routing matters concretely: `ai_video_analysis` has no MCP tool and cannot be
-signed without an API secret, so on an MCP-only build the audio description
-track is unavailable. Everything else is reachable either way.
-
-## B2. Choose the optimization strategy
-
-An explicit decision, not a default — retrofitting the other one means rewiring
-the player.
-
-**This is a fork, not a comparison.** Video Player Studio encodes it as a
-segmented `Progressive | Adaptive` control — one source, one branch, and the
-two sets of controls are disjoint. Reproduce that shape in code: decide the
-branch first, then set only that branch's options.
-
-| Studio branch | what it offers |
-| --- | --- |
-| **Progressive** | Format (Auto / WebM-VP9 / MP4-H.265 / MP4-H.264), Enable breakpoints (→ Max DPR), Auto HDR, Aspect Ratio (→ Resize Mode) |
-| **Adaptive** | Format: **HLS or MPEG-DASH. Nothing else.** |
-
-Everything that shapes delivery — breakpoints, DPR, HDR, aspect ratio, resize
-mode — is absent from the Adaptive branch, because the streaming profile owns
-all of it. That is the same rule the server enforces with *resize is only
-supported for overlay*; the Studio simply never lets you reach the error.
-
-**The real question is: is this decoration, or is this content someone
-watches?** ABR only pays off when a viewer is watching long enough for the
-ladder to react to their network. Decoration never gets that far.
-
-**`ffprobe` answers it — read the source before choosing.** The signals are in
-the file:
-
-| Signal | Reading | Delivery |
-| --- | --- | --- |
-| **Loops** | decoration by definition — seen in passing, never watched through | **progressive**, always |
-| **No audio track** | background/ambient, and almost always short and autoplaying | **progressive** |
-| **Audio but no speech** (music-only) | montage or mood piece, not something followed | **progressive** |
-| **Portrait 9:16 or square** | social/short-form | **progressive** |
-| **Under ~20s** | over before a ladder could switch | **progressive** |
-| **Speech, over ~1–2 min, viewer-pressed play** | content — a talk, explainer, interview, course | **ABR** |
-
-Then:
-
-Each branch is one option. Nothing else:
-
-| Approach | Set |
-| --- | --- |
-| **Progressive** | `breakpoints: true` |
-| **ABR** | `sourceTypes: ['hls']` |
-
-That is the whole configuration. No `sourceTypes` on the progressive branch, no
-`breakpoints` on the adaptive one, and on neither a format, quality, width or
-`maxDpr` — the player's default is already `f_auto:video`, `breakpoints` brings
-DPR handling with it, and `sourceTypes:['hls']` emits `sp_auto` itself. Reach
-for `maxDpr` only to deliberately cap DPR below auto.
-
-Duration is the proxy, not the rule — a three-minute silent background loop is
-still progressive. Where signals disagree, **behaviour wins over length**.
-
-The same probe decides more than delivery: no audio track, or audio without
-speech, also means no transcript, no chapters and no generated title (A5). One
-`ffprobe` per source, read once.
-
-**Neither is free to get wrong, and the costs are asymmetric.** ABR on a short
-clip buys a manifest round-trip before the first frame — slower start on the
-content most sensitive to it — and a ladder to warm that never switches.
-Progressive on a long watch fixes one rendition at load, so a network that
-degrades at minute eight stalls with no recovery. That is worse, so a borderline
-video someone genuinely watches goes ABR; a borderline video that autoplays
-stays progressive whatever its length.
-
-`sp_auto` is the only mechanism that recovers from a network degrading
-*mid-playback* — but that needs a watch long enough for it to act. **Putting
-ABR on a short clip is a real and easy mistake**: on a 14-second film the
-ladder never meaningfully switches, and you have paid manifest round-trips,
-slower startup and a pile of renditions to warm for nothing. "It's the main
-player" is not a reason; length is.
-
-**Never use `e_preview` to shorten an already-short video.** It exists to cut a
-teaser from a *long* source. A 6-second preview of a 14-second film is barely
-shorter than the asset, costs extra derivations, and is worse than just
-looping the real file.
-
-**Do not hand-write `f_auto`/`q_auto` for player-delivered video, and do not
-force `sourceTypes:['mp4']`.** The player's default already is `f_auto:video`:
-
-```
-default                      → c_limit,w_640/f_auto:video/v1/<id>
-sourceTypes:['mp4']          → c_limit,w_640/<id>.mp4        ← format pinned
-```
-
-Setting `sourceTypes:['mp4']` **replaces** `f_auto:video` with a hard-coded
-extension, so every viewer gets MP4 and automatic format/codec selection is
-lost — verified against 4.1.0. Leave `sourceTypes` unset for progressive and
-just enable `breakpoints`; set it only to `['hls']`/`['dash']` for ABR. Written
-transformations like `c_limit,w_…/f_auto:video/q_auto` belong to the **native
-`<video>` fallback**, where no player is applying them for you.
-
-If the player cannot be used at all, deliver progressive from a native
-`<video>` with media-queried `<source>`s using
-`c_limit,w_…/f_auto:video/q_auto` — see
-[references/capabilities.md](references/capabilities.md).
-
-### Configure the player; do not hand-write its delivery transformation
-
-The player composes the delivery transformation from its options. Anything you
-write into `transformation:` that an option already covers lands in the *same*
-component and breaks the URL rather than adding to it.
-
-```js
-// WRONG — sourceTypes already produces sp_auto
-player.source(id, { transformation: { streaming_profile: 'auto' } });
-// RIGHT
-cloudinary.player(el, { sourceTypes: ['hls'] });   // → sp_auto/<id>.m3u8
-```
-
-Same for `f_auto`/`q_auto` (the default is already `f_auto:video`) and widths
-(that is `breakpoints`). Hand-written transformations are for assets no player
-manages — posters, hover loops, `e_preview` teasers, the native `<video>`
-fallback.
-
-`breakpoints` belongs to the progressive branch only; under ABR the ladder
-governs resolution. Set it there anyway and delivery 400s
-(`c_limit,w_…/sp_auto/…` — *resize is only supported for overlay*), whether you
-set it through player options or by hand.
-
-Both live on the **constructor**, so a page moving a viewer between a
-progressive and an ABR asset must **dispose and rebuild the player**. Calling
-`source()` on a player built for the other strategy carries the wrong option
-across.
-
-Most pages want both, on **different** sources: ABR for the tour, progressive
-for the loops. Full comparison table in
-[references/capabilities.md](references/capabilities.md).
-
-## B3. Load and configure the player
-
-Install from npm and use the **ES import** — the package ships an `exports`
-map with an `import` condition, bundles its own video.js, and loads the player
-core behind a dynamic `import()`, so a bundler code-splits it for you:
-
-```sh
-npm install cloudinary-video-player
-```
-
-```js
-import 'cloudinary-video-player/cld-video-player.min.css';
-import cloudinary from 'cloudinary-video-player';
-```
-
-For a single-file page with no build step, the UMD build off a CDN works the
-same way and puts `cloudinary` on `window`:
-
-```html
-<link rel="stylesheet" href="https://unpkg.com/cloudinary-video-player/dist/cld-video-player.min.css">
-<script src="https://unpkg.com/cloudinary-video-player/dist/cld-video-player.min.js"></script>
-```
-
-**Construct with `cloudinary.player()`, not `cloudinary.videoPlayer()`.**
-`videoPlayer()` is the legacy synchronous constructor. `player()` is the
-current one: it returns a **Promise**, and it resolves *saved configuration*
-first — pass `publicId` and it picks up the settings saved onto that asset in
-Video Player Studio; pass `profile` for a stored profile instead.
-
-```js
-const player = await cloudinary.player('hero', {
-  cloudName, publicId: 'my/video',   // asset's saved settings apply
-  /* local options win over saved config */
-});
-```
-
-Precedence is **construction options > profile > asset-saved > defaults**, so
-repeating settings locally makes the saved config dead weight — save the
-presentation, pass only what is page-specific.
-
-Settings are normally saved through Video Player Studio in the console, but
-the **Video Config API** writes the same thing without console access — useful
-on a claimable cloud, and the way to make a build reproducible:
-
-```sh
-curl -X PUT https://api.cloudinary.com/v2/video/<cloud>/player/config/video/<asset_id> \
-  -u <key>:<secret> -H "Content-Type: application/json" \
-  -d '{"playerOptions":{…},"sourceOptions":{…}}'
-```
-
-Keyed by `asset_id`, not public ID, and PUT replaces the whole document.
-Passing `publicId` with no saved config is silent — you get HTTP 200 and an
-empty `{}`, and the page quietly falls back to its local options.
-
-Because construction is async, guard anything that seeks the player — a
-transcript line clicked before it resolves must queue, not throw. Details, the
-built-in profiles and how to verify what actually applied:
-[references/player.md](references/player.md).
-
-Constructor options vs `source()` options — the split is about **how many
-assets one player shows**. Constructor options configure the *player*;
-`source()` options describe the *asset currently in it*.
-
-**One player, one video:** set everything on the constructor and never call
-`source()` — pass `publicId` and you are done.
-
-**One player, several videos** — a playlist, a rail, a gallery where clicking a
-thumbnail changes the video — build the player **once** and call `source()` per
-asset. Constructor options persist across the swap; the per-asset metadata
-(`title`, `chapters`, `textTracks`) rides along with each `source()` call.
-Building a new player per video is the common mistake: it costs a fresh
-video.js instance each time and leaks the old ones unless you `dispose()`.
-
-The exception is the delivery strategy above: because it lives on the
-constructor, swapping between an ABR and a progressive asset is the one case
-that *does* need a dispose-and-rebuild rather than a `source()` call.
-
-Getting these the wrong way round silently does nothing:
-
-| Constructor | `source()` |
-| --- | --- |
-| `cloudName`, `sourceTypes`, `fluid`, `controls`, `showLogo`, `colors` | `chapters`, `title`, `description`, `textTracks`, `posterOptions`, `interactionAreas` |
-| `seekThumbnails`, `chaptersButton`, `aiHighlightsGraph` | |
-
-**`colors.text` must be a LIGHT colour.** Player chrome sits over dark video; a
-dark text token makes the controls invisible.
-
-Full option shapes: [references/player.md](references/player.md).
-
-## B4. Wire the experience
-
-The capabilities are only worth having if the page uses them. Patterns that
-worked, with the reasoning, in
-[references/build-patterns.md](references/build-patterns.md):
-
-- **For a long source: open on an `e_preview` loop and build the player lazily**
-  on first interaction — motion instead of a black frame, and no stream fetched
-  until wanted. **For a short clip, just loop the real video muted** and build
-  eagerly; there is no stream worth deferring and no teaser worth cutting.
-- **Guard against the async constructor** — `cloudinary.player()` returns a
-  Promise, so queue seeks that arrive before it resolves.
-- **Compose `source()` from the flags** by conditional spread. Skip absent
-  features; never stub them with a URL that 404s.
-- **Bind playback both directions** — rail and transcript seek the player;
-  `timeupdate` highlights the current segment. Render the rail before the player
-  exists, since clicking it is what builds the player.
-- **The transcript is JSON, not VTT** — hand it to the player for captions,
-  fetch and render it yourself for on-page search with click-to-seek.
-- **Emit JSON-LD** from the generated title, description and chapters.
-
-## B4a. Generated, supplied, or hand-authored — in that order
-
-Video Player Studio offers the same three-tier ladder on every piece of
-content, and it is a good default for deciding where metadata comes from:
-
-| panel | tier 1 — generate | tier 2 — supply | tier 3 — author |
-| --- | --- | --- | --- |
-| Chapters | Automatically generate chapters | Import a VTT file | Type `00:00` + name |
-| Transcript | Generate | Upload | — |
-| Poster | Suggested posters (AI frames) | Media Library / current frame | Upload |
-
-Two things follow. First, **every generated artefact has a supply path beside
-it** — so when a human-authored caption, chapter list or poster already exists
-(see A2), use it; the ladder exists precisely so generation is not the only
-route. Second, the tiers are per-asset, not per-site: generating chapters for
-a long talk and hand-authoring three for a short explainer is normal.
-
-## B5. Be straight about what Cloudinary does not generate
-
-- **Chapter→product bindings.** Auto-chaptering finds the segments; which
-  product a segment sells is your data. Check the source platform's cue points
-  and custom fields first — often it is already there.
-- **Hotspot positions.** `interactionAreas` takes coordinates you supply.
-  Cloudinary does not track objects and hand you positions. The AI Video
-  Analysis API returns a timestamped natural-language visual transcription and
-  explicitly **no** spatial coordinates or bounding boxes.
-- **Video background removal, virtual try-on, shade matching.** These do not
-  exist. Do not approximate them with something adjacent.
-
-## Close out
-
-- Which capabilities are on, which are off, **and why** — name the add-on and
-  what enabling it needs.
-- What was migrated, and anything that had no Cloudinary equivalent.
-- On a claimable cloud: **the claim URL**, and that it expires in 24 hours.
-
-## How much of this is verified
-
-Calibrate accordingly — the guidance is not uniformly tested:
-
-- **Cloudinary behaviour is machine-verified.** The delivery, transformation and
-  async-output claims are asserted against a live cloud by a test suite
-  (`sp_auto` rejecting a resize at every width, the transcript being JSON with
-  word-level timings, the chapters VTT path, the pinned player URLs). If
-  Cloudinary changes, those assertions fail rather than quietly misleading you.
-- **Source-platform APIs are documentation research, not tested calls.** The
-  routes in [references/source-platforms.md](references/source-platforms.md)
-  were read from each vendor's docs (September 2026) without an account to
-  exercise them. Treat the *shape* as reliable and confirm the specifics for the
-  account in front of you.
-- **One item is explicitly unresolved:** which Vimeo response field carries the
-  untranscoded original. Vimeo's own docs do not say. Verify before trusting a
-  field, or ask for the customer's master.
-- **Nothing here has been run end to end against a real existing-customer
-  migration.** The from-scratch path has a worked example behind it; the
-  existing-cloud path does not.
-
-Say which of these applies when you rely on one, rather than presenting all of
-it with equal confidence.
-
-## Reference
-
-- [references/field-guide.md](references/field-guide.md) — delivery best
-  practices: use-case discovery, the delivery cheat sheet, issues to avoid,
-  `f_auto` usage spikes, eager transformations, mobile apps, analytics,
-  accessibility, pre-launch validation
-- [references/capabilities.md](references/capabilities.md) — capability matrix,
-  detection, degradation, MCP vs `CLOUDINARY_URL` routing, ABR vs progressive
-- [references/build-patterns.md](references/build-patterns.md) — lazy player,
-  flag composition, playback binding, transcript handling, shipping the site
-  rather than the demo
-- [references/source-platforms.md](references/source-platforms.md) — getting
-  originals off Brightcove, Vimeo, YouTube, Wistia
-- [references/player.md](references/player.md) — full player option shapes
-- [references/gotchas.md](references/gotchas.md) — upload presets, poisoned
-  paths, quotas, async failure modes, truncated derivatives, video.js DOM
-  surgery, player API gaps, VPN and delivery-IP traps
diff --git a/skills/cloudinary-video/references/field-guide.md b/skills/cloudinary-video/references/field-guide.md
deleted file mode 100644
index 3038466..0000000
--- a/skills/cloudinary-video/references/field-guide.md
+++ /dev/null
@@ -1,122 +0,0 @@
-# Field guide: delivery best practices
-
-Condensed from Cloudinary's internal CSM video onboarding checks & best
-practices guide. This is the guidance to apply when advising on, reviewing or
-building a customer's video implementation — it is about *delivering video
-well*, not about the player's API surface (see [player.md](player.md)).
-
-## Understand the use case before recommending anything
-
-Recommendations follow from the use case, so establish it first:
-
-- **What types of video?** In e-commerce, typically short product videos on
-  PDPs, plus campaign/content videos on homepages and landing pages.
-- **How long are they?** Under a minute, or longer? This drives the delivery
-  method more than anything else.
-- **Where are they delivered?** Web (desktop/mobile), native mobile apps, or
-  other channels. Native apps change the rules — see below.
-- **Do they need analytics?** Views, engagement, watch time.
-- **Do they release videos into traffic spikes?** Catalogue launches, major
-  campaigns — this is what makes eager transformations worth it.
-- **Do they need subtitles/captions?** Already authored, or generated and
-  translated?
-- **Any other accessibility or navigation needs?** Audio descriptions, chapters.
-
-## Delivery cheat sheet
-
-| Scenario | Approach | Notes |
-| --- | --- | --- |
-| Short, inline, autoplay, PDP, campaign or social-style web video | **Cloudinary Video Player, progressive** | Optimizes by default (the URL it builds carries `f_auto:video`) — write no format/quality transformation, and do not set `sourceTypes`. Enable responsive breakpoints for per-screen dimensions |
-| Short web video, player unavailable | **Native `<video>` with multiple `<source>`** | `c_limit,w_[width]` + `f_auto:video` + `q_auto` |
-| Longer-form / viewer-selected video | **ABR, preferably via the player** | Set `hls` (or `dash`) in `sourceTypes`; the player adds `sp_auto` for you |
-| ABR, player unavailable | **HLS via a compatible third-party player** | Generate the manifest with `sp_auto`; verify browser/device support |
-| Major launch, big catalogue drop, high-traffic event | **Eager transformations, on top of the chosen approach** | Pre-generate derivatives at upload; do not let first requests build them |
-| Native iOS/Android app | **Mobile-specific strategy** | App picks codec/format and dimensions; URL params or `Accept` header |
-| Analytics, captions, accessibility, chapters, branded UI needed | **Use the Cloudinary Video Player** | All of it works out of the box |
-
-## Typical issues to avoid
-
-- **Delivering the original**, untransformed. Default video quality only kicks
-  in when *some* transformation is present in the URL — a bare original URL
-  gets no optimization at all.
-- **No maximum dimensions.** Shipping 4K/8K where 1080p is indistinguishable
-  burns bandwidth and units for no visible gain. Cap with `c_limit,w_…` for
-  progressive, and cap the top rung for ABR too.
-- **Partial optimization** — applying some of `f_auto` / `q_auto` / resizing but
-  not the rest, and ending up with files larger than necessary.
-- **Assuming `f_auto` works in native mobile apps.** It is web delivery
-  behaviour.
-- **Preloading everything.** Preloading improves perceived start time but
-  consumes units for videos nobody watches. Prefer lazy loading, and make
-  autoplay/preload a deliberate decision rather than a default.
-
-## `f_auto` causes a transformation-usage spike — say so in advance
-
-Introducing `f_auto`, or adding format/codec combinations, forces new derived
-versions to be generated. Expect a visible **spike in transformation usage**,
-especially across a large existing library. It settles once the derivatives
-exist and get reused. Warn the customer *before* the rollout so the bill does
-not surprise them.
-
-## Account-level optimization settings
-
-- **Default automatic format** applies `f_auto`/`q_auto` to web-delivered video
-  without touching delivery URLs. Being rolled out to plans on the *video
-  seconds* metric; not available on video-bandwidth plans. Web only.
-- **Default video quality** lets Cloudinary pick quality and codec (`vc_auto`)
-  automatically. Available on all plans — but **only applies when another
-  transformation is present in the URL**.
-
-## Eager vs on-the-fly
-
-On-the-fly is the right default: derivatives build on first request, no
-preparation needed. Switch to **eager transformations at upload** when a launch
-or campaign will drive a traffic surge, when videos are long or high-resolution
-(2K/4K), or when transformations are complex enough to be slow to build. This
-is the production-grade version of "warm the derivations": generate them at
-upload rather than discovering the cost on the first viewer's request.
-
-## Mobile apps are a different problem
-
-The player requires a mobile SDK (iOS, Android, Flutter, React Native).
-
-**`f_auto` does not work the same way.** The app must tell Cloudinary what the
-device supports, either by naming it in the URL:
-
-- Android: `f_mp4,vc_av1` → `f_webm,vc_vp9` → `f_mp4,vc_h264` (fallback)
-- iOS: `f_mp4,vc_av1` → `f_mp4,vc_h265` → `f_mp4,vc_h264` (fallback)
-
-…or by sending an `Accept` header (e.g. `video/webm; codecs="vp9"`,
-`video/mp4; codecs="hvc1"`, `video/mp4; codecs="avc1"`). AV1 via `Accept` is
-not supported yet.
-
-**Responsive breakpoints are not supported in the mobile SDKs.** Request
-explicit widths per device instead (`c_limit,w_640` / `w_1280` / `w_1920`), and
-pick the smallest that suits the screen.
-
-## What the player gives you for free
-
-- **Analytics** — collected by default for anything delivered through the
-  player; visible in Console under Video → Analytics, and available via API.
-- **Accessibility** — WCAG 2.1 AA, keyboard navigation, captions/subtitles
-  (existing VTT/SRT or generated transcripts), audio descriptions via text
-  tracks or alternative audio tracks on ABR, and chapters (VTT, manual, or
-  AI-generated).
-- **Customization** — skins, colour schemes, fonts, titles/subtitles display.
-- **Video Player Studio** — a visual configurator that emits the player config,
-  rather than hand-writing it. Also handles transcripts and chapters.
-
-## Validate before launch
-
-Confirm, on representative videos and real devices:
-
-- Delivery URLs are **not** serving originals, and have size limits.
-- The intended optimization approach is actually enabled (check the URL that
-  ships, not the one you wrote).
-- Autoplay/preload behaviour is deliberate.
-- Playback works on target browsers, devices and networks.
-- Captions/subtitles and analytics work where required.
-- The expected initial transformation/delivery usage has been explained.
-
-Then review 2–4 weeks after launch: confirm delivery, check usage and
-transformation patterns, and look for optimization opportunities.
diff --git a/skills/cloudinary-video/references/gotchas.md b/skills/cloudinary-video/references/gotchas.md
deleted file mode 100644
index 5bc69c1..0000000
--- a/skills/cloudinary-video/references/gotchas.md
+++ /dev/null
@@ -1,250 +0,0 @@
-# Gotchas
-
-Each of these cost real debugging time on a real migration. They all look like
-code bugs and none of them are.
-
-## Upload presets can rewrite your assets on ingest
-
-An account can have an upload preset carrying an **incoming transformation**,
-which permanently rewrites every uploaded asset — resizing it, watermarking it,
-or both. The signing endpoint may inject that preset into signed uploads whether
-you asked for it or not.
-
-Symptom: uploads report success, but stored dimensions are smaller than the file
-you sent, and delivered images carry a watermark.
-
-What does **not** work:
-
-- `upload_preset: ""` — ignored, the preset is still applied
-- an explicit `transformation:` parameter — the upload *response* reports your
-  dimensions while the *stored* asset keeps the preset's
-- `invalidate: true` — this is not a cache problem
-
-What does work: pass an explicit clean preset by name (often `default` — check
-what exists on the account), or clear the offending preset's incoming
-transformation in Console → Settings → Upload → Upload presets.
-
-Note the watermark also **degrades Cloudinary's own AI**. Google Auto Tagging on
-a watermarked image returned 3 tags where the clean original returned 27.
-
-## A public ID path can become unusable
-
-On one account, uploads to a particular folder path kept storing the old
-788px watermarked asset no matter what — including after deleting the asset and
-uploading fresh. An identical upload to a *different* path stored correctly
-first time.
-
-If a path misbehaves twice, stop debugging it and change the path. Verify by
-fetching the delivery URL with a cache-busting query and checking the actual
-JPEG dimensions, not the upload response.
-
-## Add-on quotas are small and easy to burn
-
-Free-plan monthly limits worth knowing before you loop over an asset list:
-
-| Add-on | Limit |
-| --- | --- |
-| Google Auto Tagging | 50 |
-| Google Video Tagging | 5 |
-| Google Speech | 120 |
-| Image generation | 50 (a single request can consume 3) |
-| Image-to-video | 160 |
-
-Repeated re-uploads to fix something else will exhaust these. Get the upload
-parameters right before running the batch.
-
-## Async AI features fail rather than degrade
-
-`auto_chaptering`, `auto_transcription` and the generated title/description all
-return `status: "pending"` and complete later — **or return `status: "failed"`**.
-
-They need substantial real speech. On a 5-second silent clip:
-
-```json
-"auto_chaptering":    { "status": "failed", "data": "Failed to process request" },
-"auto_video_details": { "status": "failed", "data": "Failed to process request" }
-```
-
-Always poll for `complete`. Never assume.
-
-## HTTP 423 on first request
-
-An un-derived variant returns **423 Locked** while Cloudinary builds it
-asynchronously. `e_preview` on a 3-minute video took minutes. Poll until 200.
-
-For anything going into a launch or a traffic spike, the real fix is **eager
-transformations at upload** rather than warming by polling — see
-[field-guide.md](field-guide.md).
-
-### A 200 is not proof the derivative is complete
-
-Worse than a 423: a video derivative that is still building can return **200
-with a truncated file**, and the browser will cache that. Observed on a
-14.1-second source — the page reported `duration: 2.625`, buffering stopped at
-2.24s, and playback simply refused to start. Nothing in the HTTP status said
-anything was wrong.
-
-So verify the *content*, not the status code:
-
-```sh
-curl -s "$URL" -o /tmp/w.mp4
-ffprobe -v error -show_entries format=duration -of default=nk=1:nw=1 /tmp/w.mp4
-# compare against the known source duration; retry until it matches
-```
-
-And **re-warm whenever the delivery URLs change.** Warming `sp_auto` does
-nothing for the `c_limit,f_auto,q_auto,w_…` MP4s you switch to later; each
-distinct transformation is its own derivative. With responsive breakpoints the
-player may request several widths, so warm the whole set. After re-warming,
-hard-reload — the browser is still holding the truncated response.
-
-## Video.js rearranges your DOM, and two bugs follow
-
-The Cloudinary player is video.js underneath, which performs DOM surgery on
-init. Two failures come from this and both are silent:
-
-**The original `id` moves to a wrapper div.** After init,
-`document.getElementById('hero')` returns a `<div class="video-js">`, not the
-`<video>`. Attaching media listeners to it does nothing:
-
-```js
-document.getElementById('hero').addEventListener('timeupdate', …) // never fires
-player.on('timeupdate', …)                                        // correct
-```
-
-**An unclosed `<video>` tag swallows everything after it.** HTML parsing puts
-subsequent siblings *inside* the video element, where they never render:
-
-```html
-<video id="hero" class="cld-video-player" playsinline>   <!-- no </video> -->
-<button class="soundbtn">…</button>   <!-- becomes a child of <video> -->
-<div class="overlay">…</div>          <!-- gone: 0×0, never painted -->
-```
-
-The tell is an element measuring 0×0 whose `parentElement` is `VIDEO.vjs-tech`.
-Always close the tag.
-
-## The Cloudinary player proxies only some videojs methods
-
-`player.currentTime()` and `player.play()` are proxied through the Cloudinary
-wrapper. `player.muted()` and `player.controls()` are **not** — calling them
-throws `TypeError: player.muted is not a function`, which aborts the rest of
-your click handler and looks like "the button does nothing".
-
-Reach the underlying videojs player for those:
-
-```js
-var vjs = window.videojs && window.videojs.getPlayer('hero');
-if (vjs) { try { vjs.muted(false); vjs.controls(true); } catch (e) {} }
-```
-
-Setting `muted`/`volume` directly on the underlying `<video>` element also
-works and is the most robust option.
-
-## Artifacts cannot host a Cloudinary video demo
-
-The Claude Artifact viewer's CSP admits only the artifact's own files, Google
-Fonts and a few script CDNs. Every `res.cloudinary.com` image, video and
-`fetch()` is blocked, so the page publishes "successfully" and renders as an
-empty shell. Inlining media as data URIs would defeat the point (no adaptive
-delivery, no transformations). Serve these pages over HTTP instead.
-
-## Verifying what was actually stored
-
-The upload response can disagree with what is stored and delivered. To check
-real delivered dimensions:
-
-```sh
-curl -s "https://res.cloudinary.com/<cloud>/image/upload/<public_id>.jpg?bust=$RANDOM" \
-| python3 -c "
-import sys,struct
-d=sys.stdin.buffer.read(); i=2
-while i<len(d)-9:
-    if d[i]==0xFF and d[i+1] in (0xC0,0xC1,0xC2):
-        h,w=struct.unpack('>HH',d[i+5:i+9]); print(f'{w}x{h} {len(d)}B'); break
-    i+=1
-"
-```
-
-For video, `ffprobe` on a downloaded file is the honest check — including
-whether an audio stream exists at all, which decides whether transcription and
-chaptering can work.
-
-## The MCP has no API secret
-
-The Cloudinary MCP holds its credentials internally and never exposes the API
-secret, so an agent working through it can only do what the MCP has a tool for.
-Any other endpoint — a v2 route, a beta API — cannot be signed and returns:
-
-```
-{"error":{"message":"error while authenticating: api_secret not provided"}}
-```
-
-`POST /v2/video/<cloud>/ai_video_analysis` is the common case: no MCP tool, so
-the visual transcription cannot be produced this way at all.
-
-An agent that provisions its own cloud has no such limit. `npx
-@cloudinary/cloud` writes `CLOUDINARY_URL=cloudinary://<key>:<secret>@<cloud>`,
-and every endpoint is reachable with it.
-
-Before concluding a feature is unavailable, check whether it is merely
-unreachable — the two look identical from inside an MCP session.
-
-## Provisioning fails behind a VPN
-
-`npx @cloudinary/cloud` derives the media-delivery allow-list from the source
-IP, and refuses to provision from a private address:
-
-```
-delivery_ips_not_public — delivery_ips must contain at least one public IP address
-```
-
-A corporate VPN or secure gateway (Cloudflare WARP and similar) triggers this.
-The tool's own guidance says an agent should **report it and let the user
-decide** rather than changing network settings. Pausing the VPN for that one
-command is the fix.
-
-Related, and easy to misdiagnose: **read `delivery_ips` back from the response**
-rather than trusting what you sent. Behind a proxy your own address is silently
-dropped, and you end up with a cloud whose media nothing can view.
-
-### A VPN toggling *after* provisioning silently kills a working cloud
-
-Worse than the provisioning failure, because it fails late and quietly. The
-cloud is pinned to the IP it was provisioned from, so if the network changes —
-a VPN reconnecting, a gateway rotating its egress, moving to another network —
-every delivery URL starts returning **401**, on a cloud that worked minutes ago.
-
-The tell is *which* requests fail: uploads and Admin API calls keep succeeding,
-because only CDN delivery is IP-restricted. So an agent reports a successful
-migration while every image and video 401s.
-
-```sh
-# 401 on delivery but uploads fine? compare the current egress with the
-# address the cloud was provisioned from
-curl -s https://api.ipify.org
-```
-
-The 401 body says the OAuth token expired, which is misleading — it is an
-allow-list rejection, not an auth problem.
-
-For a demo, keep the VPN off for the **whole session**, not just the
-provisioning command.
-
-## The delivery IP restriction blocks Cloudinary's own fetches
-
-On an unclaimed cloud, `POST /upload` with `file=<a delivery URL on that same
-cloud>` fails with `401 Unauthorized`. Cloudinary's fetcher is not one of the
-allowed delivery IPs. Upload from a local file instead.
-
-Claiming the cloud lifts the restriction entirely.
-
-## Claimable clouds
-
-- Expire **24 hours** after provisioning unless claimed
-- Media delivery is restricted to the IPs in `delivery_ips`; **uploads and API
-  calls are not restricted**, so a wrong IP looks like a working migration with
-  broken media
-- The CLI's default (no `--ip`) locks delivery to the calling address, which is
-  usually correct — prefer it over guessing
-- Surface the `claim_url` to the user; it is what makes the cloud permanent
diff --git a/skills/cloudinary-video/references/player.md b/skills/cloudinary-video/references/player.md
deleted file mode 100644
index 8bdbe1b..0000000
--- a/skills/cloudinary-video/references/player.md
+++ /dev/null
@@ -1,306 +0,0 @@
-# Cloudinary Video Player option shapes
-
-Verified against `cloudinary-video-player@4.1.0`. Option names come from the
-player API reference, not from memory.
-
-## Use `cloudinary.player()`, not `cloudinary.videoPlayer()`
-
-The 4.1.0 UMD bundle attaches five things to `window.cloudinary`:
-`videoPlayer`, `videoPlayers`, `player`, `players`, `Cloudinary`. Two of those
-construct a player and they are **not** the same function:
-
-| | `cloudinary.videoPlayer()` | `cloudinary.player()` |
-| --- | --- | --- |
-| Status | legacy constructor | **current** — the bundle tags its own analytics `newPlayerMethod: true` |
-| Returns | the player, synchronously | a **Promise** resolving to the player |
-| Saved configuration | none — options only | fetches saved config before constructing |
-
-```js
-const player = await cloudinary.player('hero', {
-  cloudName: 'my-cloud',
-  publicId: 'my/public-id',   // also loads the source
-  // …local options win over anything fetched
-});
-```
-
-Because it is async, anything that touches the player (seeking from a
-transcript or a timecode chip) must tolerate being called before it resolves —
-queue the request and replay it on resolve.
-
-### Saved configuration: assets and profiles
-
-Video Player Studio saves settings **onto the video asset** by default. Passing
-`publicId` makes the player retrieve them automatically (requires player
-3.6.0+), so a page can inherit the styling and behaviour someone configured in
-the Studio without hard-coding it.
-
-`profile` loads a stored *profile* instead — either a built-in
-(`cld-default`, `cld-looping`, `cld-adaptive-stream`, `cld-live-streaming`) or
-one saved on the cloud, fetched from
-`/_applet_/video_service/video_player_profiles/<name>.json`.
-
-**Profiles are writable over HTTP — no console needed.** When the same
-presentation repeats across many assets, that is the signal to create one
-rather than repeat it in page code:
-
-```sh
-# create or update; also GET /player/profiles to list, DELETE to remove
-curl -X PUT https://api.cloudinary.com/v2/video/<cloud>/player/profiles/<name> \
-  -u <key>:<secret> -H "Content-Type: application/json" \
-  -d '{"playerOptions":{…},"sourceOptions":{…}}'
-```
-
-Basic auth with the API key and secret; both `playerOptions` and
-`sourceOptions` are required and take arbitrary player/source keys. Full
-reference: <https://cloudinary.com/documentation/video_player_profiles_reference>
-
-Precedence, and the trap: **specifying a `profile` overrides the asset's own
-saved settings.** If you want the per-video configuration to apply, do not pass
-a profile. Local options passed at construction beat both.
-
-Profiles deliberately exclude per-embed values — the video's `publicId` and
-`posterOptions` are never part of a profile, so keep passing those yourself.
-
-`cld-looping` is worth knowing: `{fluid, controls:false, muted:true,
-autoplay:true, loop:true}` — the standard hero/background-loop configuration.
-
-**Precedence is two different mechanisms, not one ranked list.** Getting this
-wrong leads to over-specifying the page defensively:
-
-- **A `profile` replaces the asset's video settings.** It is a substitution:
-  pass one and the per-asset saved configuration no longer supplies the base.
-  So a profile cannot be combined with per-video settings — if some setting
-  genuinely varies per asset, it cannot live behind a profile.
-- **Construction options are additive.** They layer *on top* of whichever base
-  applies and do **not** suppress it. Settings you do not pass keep coming from
-  the asset (or profile), so a page that sets three options still inherits
-  everything else that was saved.
-
-(Cloudinary's own statement; the public profiles API reference does not
-document precedence, so do not infer it from the endpoint docs.)
-
-Practically: save the presentation, pass only what is genuinely page-specific.
-Not because inline options would otherwise clobber the saved config — they
-won't — but because anything inline is a value nobody can change without a
-deploy.
-
-### What the Studio's own embed looks like
-
-Worth calibrating against, because it is the shape Cloudinary steers users to.
-The Studio's Share dialog offers two modes, and neither produces a wall of
-options:
-
-| mode | generated code |
-| --- | --- |
-| **Video settings** (asset-saved) | `cloudinary.player('player', { cloudName, publicId })` |
-| **Profile settings** | `cloudinary.player('player', { cloudName, publicId, profile: 'cld-default' })` |
-
-That is the whole call — `fluid` and the rest of the presentation all live in
-the asset's video settings, not in the page. The profile picker lists real
-reused ones (`pdp`, `abr-4k`, `translations`) beside the `cld-*` built-ins.
-
-**Configuration belongs on the asset or in a profile — not inline.** This is
-the practice, not a judgement call: presentation saved on the asset can be
-changed by anyone in Studio, while the same values in page code need a deploy.
-Repeat the same presentation across several assets and it should be a profile.
-
-Inline options are not *broken* — they layer on top rather than suppressing
-what was saved — but reach for them only for what genuinely cannot live on the
-asset, and expect that to be close to nothing. `cloudName` and the `publicId`
-are the call; everything else has a home.
-
-The Studio also has a raw-JS escape hatch — *Advanced settings editing* — and
-scopes it explicitly to "player options that are not currently exposed in the
-Studio UI", warning that default player options will be ignored. Treat
-hand-written config the same way: last resort, for what the supported surface
-does not cover.
-
-### Saving settings without the console — the Video Config API
-
-Video Player Studio saves settings through the console UI, but the same
-configuration is readable and writable over HTTP, keyed by **`asset_id`** (not
-public ID), with Basic auth:
-
-```sh
-# read
-curl https://api.cloudinary.com/v2/video/<cloud>/player/config/video/<asset_id> \
-  -u <key>:<secret>
-
-# write — PUT REPLACES the whole document; GET, merge, then PUT to patch
-curl -X PUT https://api.cloudinary.com/v2/video/<cloud>/player/config/video/<asset_id> \
-  -u <key>:<secret> -H "Content-Type: application/json" \
-  -d '{"playerOptions":{…},"sourceOptions":{…}}'
-```
-
-`playerOptions` takes constructor keys; `sourceOptions` takes `source()` keys
-(`sourceTypes`, `transformation`, `posterOptions`, `textTracks`). Get the
-`asset_id` from the Admin API — the resource endpoint returns it alongside the
-public ID.
-
-The player reads the same config at delivery time from
-`/_applet_/video_service/video_player_config/video/<type>/<base64(publicId)>.json`,
-which is handy for verifying what a page will actually receive. **An empty
-`{"playerOptions":{},"sourceOptions":{}}` and HTTP 200 means nothing is saved**
-— the fetch fails silently by design, so a page falls back to its local
-options and looks fine while inheriting nothing.
-
-### Confirming saved config actually applied
-
-Two checks that avoid false alarms:
-
-- The player's analytics beacon to `analytics-api-s.cloudinary.com/video_player_source`
-  spells it out: `newPlayerMethod=true`, `videoConfig=true`, and
-  `fetchedConfig=<comma-separated keys>` listing exactly which keys came from
-  the saved config.
-- **Do not test captions with `videoEl.textTracks`** — it reads empty because
-  video.js manages them as *remote* tracks. Use
-  `videojs.getPlayer(id).remoteTextTracks()`.
-
-## Constructor options
-
-These apply to either constructor.
-
-```js
-{
-  cloudName: 'my-cloud',
-  sourceTypes: ['hls'],        // ABR only. OMIT for progressive — setting
-                               // ['mp4'] disables the f_auto:video default
-  fluid: true,                 // fills its container
-  controls: true,
-  showLogo: false,
-  seekThumbnails: true,        // default true
-  chaptersButton: true,
-  aiHighlightsGraph: false,    // interest curve on the scrub bar
-  colors: {
-    accent: '#88c0d0',
-    base:   '#0b1015',
-    text:   '#eceff4',         // MUST be light — chrome sits over dark video
-  },
-}
-```
-
-`breakpoints` — a **boolean**, and a **progressive-only** option: it picks a
-delivery width for the container. It has no meaning under
-`sourceTypes: ['hls']`, where the streaming profile's ladder governs
-resolution, and setting it there yields a 400 — including when both are set
-purely as player options, since the player composes the rejected URL for you.
-Both are constructor options, so a player must be **disposed and rebuilt** to
-move between the two strategies. See the comparison in
-[capabilities.md](capabilities.md).
-
-Never pass `transformation:{streaming_profile:…}` to `source()`:
-`sourceTypes:['hls']` already emits `sp_auto`, and writing it yourself only
-collapses it into another directive's component.
-
-`maxDpr` — number or `true`. Only meaningful **with `breakpoints` on** (Studio
-reveals Max DPR only once breakpoints is enabled), so it is progressive-only by
-inheritance.
-
-**You do not need to set it.** Enabling `breakpoints` turns on DPR handling
-too: breakpoints chooses the *width* and the device's pixel density is matched
-automatically — `maxDpr: true` (auto), which is what Studio's "Auto" writes and
-what it defaults to. Setting it is redundant, in the same way writing `f_auto`
-for a player-delivered source is.
-
-Pass a **number** only to deliberately cap below auto — trading sharpness on
-dense screens for bytes (Studio offers 1.0, 1.5, 2.0). With a number, effective
-DPR is the minimum of `maxDpr`, the device's actual DPR, and 2.0. Only relevant
-on the MP4 path.
-
-## source()
-
-```js
-player.source('my/public-id', {
-  chapters: true,              // loads <publicId>-chapters.vtt
-  title: true,                 // AI-generated title in the title bar
-  description: true,
-
-  posterOptions: {
-    transformation: { start_offset: 'auto' },   // AI-selected keyframe
-  },
-
-  textTracks: {
-    captions: {
-      label: 'English', default: true,   // omit url → uses .transcript
-      maxWords: 3,                       // also TRIGGERS the .transcript lookup
-      wordHighlight: true,               // highlight each word as spoken
-    },
-    subtitles: [
-      { label: 'Español',  language: 'es', url: '…/my/public-id.es.transcript' },
-      { label: 'Français', language: 'fr', url: '…/my/public-id.fr.transcript' },
-    ],
-    options: { theme: 'player-colors', wordHighlightStyle: { color: 'royalblue' } },
-  },
-
-  interactionAreas: {
-    enable: true,
-    template: [
-      { left: 8, top: 62, width: 34, height: 30, id: 'SKU-1' },   // percentages
-    ],
-    onClick: (event) => addToCart(event?.item?.id),
-  },
-  interactionDisplay: { enable: true, template: 'pulsing' },      // or 'shadowed'
-});
-```
-
-### chapters
-
-- `true` — loads `<publicId>-chapters.vtt` (what `auto_chaptering` produces)
-- `{ url: '…' }` — an external VTT
-- `{ 1: 'Chapter 1', 6: 'Chapter 2' }` — manual, keys are seconds
-
-### textTracks
-
-Omitting `url` on `captions` makes the player resolve the `.transcript` file for
-that public ID. Setting `maxWords` also triggers that lookup — it is the
-documented trigger, not merely a display cap. Translated transcripts live at
-`<publicId>.<lang>.transcript` and must be given explicitly.
-
-`wordHighlight: true` uses the transcript's word-level timings to highlight
-words as they are spoken; pair it with `maxWords` so the caption box does not
-fill. Style it with `options.wordHighlightStyle`.
-
-There is **no** native searchable-transcript panel option — see
-[build-patterns.md](build-patterns.md).
-
-`options.theme`: `'default'`, `'videojs-default'`, `'yellow-outlined'`,
-`'player-colors'`, `'3d'`.
-
-### interactionAreas
-
-`template` is either a preset string — `'portrait'`, `'landscape'`, `'all'`,
-`'center'` — or an array of areas. Area coordinates are **percentages** of the
-video frame, not pixels.
-
-The `onClick` handler receives an event with `event.item.id` and an
-`event.zoom()` method.
-
-## React and other frameworks
-
-Build the `<video>` element imperatively and do **not** dispose the player on
-effect cleanup. The player finishes initialising asynchronously — colors,
-adaptive streaming and interaction areas are lazy-loaded plugins that reach for
-the element after the effect returns. Disposing pulls the element out from under
-those pending callbacks and they throw on a null node
-(`Invalid target for null#one`, `Cannot set properties of null`).
-
-Route callbacks through refs so the effect can have an empty dependency list and
-build exactly one player for the page's lifetime.
-
-## Transformation notes for video
-
-- **The player applies `f_auto:video` itself.** Write format/quality
-  transformations only when you are hand-rolling a native `<video>`; on a
-  player source they are redundant, and pairing them with
-  `sourceTypes:['mp4']` re-adds by hand what forcing MP4 just removed. See
-  [capabilities.md](capabilities.md).
-- Prefer `f_auto/q_auto` as **separate components** over `f_auto,q_auto`.
-  Both are accepted and, as of September 2026, deliver byte-identical results
-  for image and video alike — this is a convention for readability and for
-  matching Cloudinary's own docs, **not** a correctness rule. Do not tell a
-  user the combined form is broken; it is not.
-- `sp_auto` is the streaming profile. It cannot be combined with a resize.
-- `e_preview[:duration_<s>][:max_seg_<n>][:min_seg_dur_<s>]` — AI summary reel,
-  video only, default duration 5.0s.
-- `g_auto` works with `c_fill`, `c_lfill`, `c_fill_pad`, `c_crop`, `c_thumb`,
-  `c_auto`, `c_auto_pad`. It does **not** work for positioning overlays.
diff --git a/skills/cloudinary-video/references/source-platforms.md b/skills/cloudinary-video/references/source-platforms.md
deleted file mode 100644
index 665288c..0000000
--- a/skills/cloudinary-video/references/source-platforms.md
+++ /dev/null
@@ -1,125 +0,0 @@
-# Getting the original sources off a video platform
-
-The governing rule, before any per-platform detail:
-
-> **Never ingest what the website delivers.** A page serves a player embed —
-> an `<iframe>`, not a file — backed by transcoded adaptive renditions. Ingest
-> that and Cloudinary transcodes a transcode: quality is permanently capped
-> below the original, every derived variant inherits the loss, and no
-> transformation can recover it. The master exists only in the source
-> platform's catalogue or the customer's own storage.
-
-Scraping a `.m3u8` or a progressive rendition off the live page is the failure
-this whole file exists to prevent. It *looks* like a successful migration.
-
-## What each platform allows
-
-Verified September 2026. Endpoints change; treat the shape as durable and
-re-check the specifics for the account in front of you.
-
-| Platform | Original retrievable? | Route |
-| --- | --- | --- |
-| Wistia | Yes — cleanest | Data API `medias#show` → `assets[]` → `type: "OriginalFile"` |
-| Brightcove | Yes, **not** via the obvious endpoint | Social Syndication API MRSS feed, `fetch_digital_master: true` → `asset.digital_master.url` |
-| Vimeo | Yes, plan-gated | Video endpoint with the `video_files` scope; paid tier |
-| YouTube | **No** | No API path. Google Takeout, or the customer's masters |
-
-### Wistia
-
-`GET https://api.wistia.com/v1/medias/{hashed_id}.json` returns an `assets`
-array. The one you want is `type: "OriginalFile"` — Wistia documents it as the
-source media that was uploaded, never used for playback, and used only as the
-blueprint for the streaming encodes. Every other asset type
-(`Mp4VideoFile`, `HdMp4VideoFile`, `IPhoneVideoFile`, …) is a rendition.
-
-Append `?disposition=attachment` to download rather than stream.
-
-Originals are much larger than the streaming assets. Expect the bandwidth.
-
-### Brightcove — the trap
-
-The intuitive endpoint is wrong:
-
-```
-GET https://cms.api.brightcove.com/v1/accounts/{account}/videos/{id}/sources
-```
-
-That returns **transcoded renditions**, not the master. It succeeds, it looks
-right, and it is exactly the mistake the rule above warns about. (For DRM'd
-content the equivalent is `/clear_sources` — still renditions.)
-
-Masters come from a different API entirely. Create an MRSS syndication:
-
-```
-POST https://social.api.brightcove.com/v1/accounts/{account}/mrss/syndications
-     { "type": "universal", "fetch_digital_master": true }
-```
-
-then read `asset.digital_master.url` from the feed. Template changes take up to
-10 minutes to appear, and feeds over 100 items need the `offset` parameter.
-
-**The master may legitimately not exist.** Brightcove documents two cases: a
-custom ingest profile configured not to store masters, and customers who
-deleted masters to save storage cost. Neither is recoverable by retrying — fall
-back to asking the customer for their own copy, and if there is none, say so
-rather than quietly ingesting a rendition.
-
-### Vimeo
-
-Requires a paid plan (Standard/Pro/Business/Enterprise and up) and a token
-carrying the `public`, `private` and `video_files` scopes. Without the plan the
-fields are simply absent — not an error you can work around.
-
-Three fields can appear on the video response, and they are not equivalent:
-
-| Field | Expiry | What it is |
-| --- | --- | --- |
-| `play` | 24h | playback-optimized; for third-party players |
-| `files` | none | renditions with dimensions/size metadata |
-| `download` | 24h | attachment-headed download links |
-
-**Vimeo's own documentation does not state which field carries the untranscoded
-original.** Do not guess — guessing here produces precisely the silent quality
-loss this file is about. Inspect the actual candidates for the video in hand
-(compare resolution, bitrate and file size against what the customer says they
-uploaded, and `ffprobe` the result) before committing to a field, or ask the
-customer for their master.
-
-### YouTube — a hard stop
-
-The YouTube Data API **cannot download source files**. There is no scope, no
-endpoint, no parameter. An agent cannot resolve this by trying harder.
-
-The only owner path is **Google Takeout**, which returns the files exactly as
-uploaded with no transcoding — but builds an account-wide zip rather than
-per-video downloads. For a handful of videos that is awkward but workable; it
-is a human action either way.
-
-So for YouTube: ask for the customer's masters first, and offer Takeout as the
-fallback. Never substitute a scraped rendition.
-
-## Cross-cutting
-
-**URLs expire.** Vimeo `play`/`download` are 24h, Wistia and Brightcove CDN
-locations have their own TTLs, Brightcove feed templates lag ~10 minutes. Fetch
-and upload promptly; do not collect a list of URLs now to ingest tomorrow.
-
-**Prefer download-then-upload over Cloudinary remote fetch.** Two reasons that
-compound: these URLs are authenticated and/or expiring, and — per
-[gotchas.md](gotchas.md) — on an unclaimed claimable cloud Cloudinary's own
-fetcher is blocked by the delivery IP allow-list, so remote fetch fails there
-regardless. Downloading locally first works on every destination.
-
-**Verify what you got.** `ffprobe` the downloaded file before uploading:
-resolution, bitrate, and whether an audio stream exists at all. That last one
-decides whether transcription and chaptering can work — see the async failure
-modes in [gotchas.md](gotchas.md).
-
-## Sources
-
-- Wistia, Asset URLs — https://docs.wistia.com/docs/asset-urls
-- Brightcove, Download Video Masters — https://apis.support.brightcove.com/social-syndication/getting-started/download-video-masters.html
-- Brightcove, CMS API download links — https://apis.support.brightcove.com/cms/code-samples/cms-api-sample-download-links.html
-- Vimeo, About video file download links from the API — https://help.vimeo.com/hc/en-us/articles/12427806914577-About-video-file-download-links-from-the-API
-- Vimeo, Video File response reference — https://developer.vimeo.com/api/reference/response/video-file
-- Google Takeout / YouTube original files — https://techcrunch.com/?p=660785
diff --git a/skills/platform/cloudinary-video/SKILL.md b/skills/platform/cloudinary-video/SKILL.md
new file mode 100644
index 0000000..5cb4a3a
--- /dev/null
+++ b/skills/platform/cloudinary-video/SKILL.md
@@ -0,0 +1,499 @@
+---
+name: cloudinary-video
+description: "Reference for building video experiences with the Cloudinary Video Player. Use when adding or improving video on a page or site, choosing adaptive or progressive delivery, or generating captions, chapters, and titles for video."
+license: MIT
+metadata:
+  author: cloudinary
+  version: '1.0.0'
+---
+
+# Cloudinary Video
+
+Covers what the `cloudinary-transformations` and `cloudinary-docs` skills do
+not: **the video player, the async AI features, and provisioning.** Use
+cloudinary-transformations for transformation URLs and cloudinary-docs for
+anything outside this skill's scope.
+
+## When to Use
+
+- Adding video to a page or site, or improving how existing video is delivered
+- Choosing between adaptive streaming (HLS or DASH) and progressive delivery
+- Configuring the Cloudinary Video Player, its saved settings, or its profiles
+- Generating transcripts, captions, chapters, titles, or descriptions for video
+- Reviewing a video implementation against Cloudinary best practices
+- Uploading video so a page can use it, including on a fresh claimable cloud
+
+## Quick Start
+
+### Default Best Practices: Apply These to Every Video Build
+
+Unless the user has a specific reason not to, every video build you produce
+should:
+
+1. **Deliver video through the Cloudinary Video Player.** Fall back to a native
+   `<video>` only when the player genuinely cannot be used, and say why.
+2. **Pick one delivery branch per source, from the file itself.** Loops, short
+   clips, and silent or music-only clips are progressive (`breakpoints: true`).
+   Speech that a viewer presses play to watch, over about a minute, is
+   adaptive (`sourceTypes: ['hls']`). See [B2](#b2-choose-the-optimization-strategy).
+3. **Never hand-write delivery transformations for a player source.** No
+   `f_auto`, `q_auto`, `sp_auto`, or widths in `transformation:`, and no
+   `sourceTypes: ['mp4']`. The player already applies `f_auto:video`.
+4. **Construct with `cloudinary.player()`, not `cloudinary.videoPlayer()`**, and
+   queue seeks until its Promise resolves. See [B3](#b3-load-and-configure-the-player).
+5. **Request `auto_transcription`, `auto_chaptering`, and `auto_video_details`
+   on the upload call** (REST or a preset: the MCP and SDKs may not pass
+   `auto_video_details`), and request add-on features in a separate call.
+6. **Pre-generate derived videos when the first viewer matters**: eager
+   transformations at upload (the explicit method for existing assets), or
+   warmed URLs on a test cloud. Otherwise the first request streams with the
+   wrong duration and no seeking.
+7. **Name anything missing**, such as an absent add-on, and what enabling it
+   takes, rather than silently dropping the feature.
+
+## How to Use This
+
+You are helping someone reach a goal for their video experience, not applying a
+checklist. So:
+
+- **Ask when an answer changes the build, or when you are unsure.** The
+  delivery branch, which cloud the media lands on, whether an add-on exists, a
+  source that turns out to be audio only: one question beats a wrong guess that
+  costs a whole run. Say what you would pick and why, then let them redirect.
+  Ask about facts, never about features (see *Start here*).
+- **Recommend, don't enumerate, in conversation.** Where this skill gives
+  options, pick the one that fits and say so in a line.
+- **But build generously.** The restraint is in what you *say*, never in what
+  you ship. Build the full experience (chapters, transcript, captions, AI
+  poster, preview loops, structured data, responsive delivery): deleting a
+  feature takes a minute, while never seeing it means they never knew to ask.
+  Ship their site, not an exhibit about Cloudinary; see *Ship the site, not the
+  demo scaffolding* in [references/build-patterns.md](references/build-patterns.md).
+- **Say what is not there.** A missing add-on, a feature Cloudinary does not
+  generate: name it plainly and move on.
+
+The work has two phases: **Phase A** gets the assets onto Cloudinary (skip it
+if they are already there), and **Phase B** builds the site.
+
+## Start here: get the intent, then the logistics
+
+Do not begin until you know what they are building. Each answer below changes
+the work substantially, so **ask for any you were not given**: one question
+costs a message, a wrong guess costs a run.
+
+**1. What are you building, and what should the video do there?**
+
+The one question the rest depends on. A product-page loop, a long-form library,
+a course, a news page and a landing hero want different delivery, different
+player features and different page shapes. Get this and most later choices
+follow; skip it and you will build a competent version of the wrong thing.
+
+**Do not interview them about features.** Do not ask whether they want
+captions, chapters, transcripts or hover previews. Build them. Someone
+describing what they want in chat should get the magic without being asked to
+specify it, and should see everything Cloudinary can do for them before
+deciding what to keep.
+
+**2. Are the assets already on a Cloudinary cloud?**
+
+Yes → **skip phase A entirely.** Go to phase B. Confirm the cloud name, how you
+reach it (MCP or `CLOUDINARY_URL`; see the routing table in
+[references/capabilities.md](references/capabilities.md)), and which public IDs
+to build against. Do not re-upload assets that are already there.
+
+No → ask where the source files are: local files, their own storage, or
+another platform (see *If the media is on another platform* below). Never
+substitute Cloudinary's `demo` cloud or other stock assets without asking.
+
+**3. Where does it land: an existing cloud, or a new claimable one?**
+
+| Destination | Consequences |
+| --- | --- |
+| Their **existing cloud** | No provisioning. No claim URL. Respect existing folders, naming and presets. Re-runs cost real quota and can overwrite live assets, so be idempotent, and never loop the catalogue to probe. |
+| A **fresh claimable cloud** | Provision it (below). Expect no add-ons. Surface the claim URL at the end. Provision a new one per test run. |
+
+Local files into an existing cloud is a legitimate combination: source and
+destination are independent choices.
+
+**Detect what you can, ask what you cannot.** Duration, whether there is a
+video track and an audio track, resolution and which add-ons a cloud has are
+all measurable:
+`ffprobe` the source, probe one asset. Do not spend a question on something you
+can check, and do not guess at something you cannot.
+
+### If the media is on another platform
+
+Moving a library off another video platform is out of scope for this skill.
+Two rules still apply when the files come from one:
+
+- **Upload the master, never what the website delivers.** A page serves
+  transcoded renditions. Upload one and Cloudinary transcodes a transcode, so
+  quality is permanently capped and every derived variant inherits the loss.
+- **Prefer human-authored captions, chapters, and titles over regenerating
+  them.** If the old platform has them, upload them alongside the video.
+
+---
+
+# Phase A: get the assets onto Cloudinary
+
+## A1. Provision a cloud (fresh-cloud destinations only)
+
+Run `npx @cloudinary/cloud --goal "<what you are building>" --model <your-model-id>`.
+It needs no signup, writes `CLOUDINARY_URL` to `./.env`, and prints a **claim
+URL**. The cloud expires 24 hours after provisioning unless claimed, so surface
+the claim URL at the end. Leave `--ip` off when the user views media from
+the machine you run on; if you run remotely (CI, a cloud agent), pass the
+user's public IP. Provision a new cloud for every test run.
+
+## A2. Upload, and request the AI features on the way in
+
+Upload video with the free features on the same call: `auto_transcription`,
+`auto_chaptering`, and `auto_video_details`. Request add-on features
+(`translate`, `google_video_tagging`, `google_tagging`, `auto_tagging`) in a
+separate call and treat failure as expected. Asking for an add-on the cloud
+lacks fails the whole upload, or the whole transcription.
+
+## A3. Wait for the async features
+
+Transcripts, chapters, and generated titles return `pending` and finish later,
+or fail. Poll each until `complete`. They need real speech: silent or
+music-only video produces none of them.
+
+## A4. Generate derived videos before anyone watches
+
+The first request for a transformed video is the slow one. Ordinary
+transformations return 200 but stream while they are generated, so the player
+shows the wrong duration and cannot seek; async ones (`e_preview`, DASH, 2K/4K
+`sp_auto`, very long videos) return 423 until built. For launches and long
+videos, use eager transformations at upload (with explicit formats, since
+`f_auto` does nothing in eager). On a demo or test cloud, warm every URL the
+page uses and confirm it is complete by its headers, not its status.
+
+Read [references/upload-and-prepare.md](references/upload-and-prepare.md) for
+the commands, the upload rules that have bitten real runs, and how to verify
+each step.
+
+---
+
+# Phase B: build the site
+
+**Read [references/field-guide.md](references/field-guide.md) alongside this.**
+It carries Cloudinary's own delivery best practices: the duration-based
+delivery cheat sheet, the optimizations customers most often miss, the
+`f_auto` transformation-usage spike to warn about, eager transformations,
+mobile-app delivery, and the pre-launch validation checklist. Phase B below is
+how to build; the field guide is what "built well" means.
+
+## B1. Resolve what this cloud can actually do
+
+Before writing page code, settle the capability set: one explicit flag map,
+with a fallback per feature. This is what keeps a page honest on a cloud without
+add-ons instead of rendering empty rails and dead caption buttons.
+
+**On a fresh cloud**, assume no add-ons: translated subtitles and machine tags
+will be absent every time, and that is correct rather than a regression.
+
+**On a customer cloud**, probe: attempt the operation on **one** asset and read
+the result. Never loop the catalogue: free tiers are small (Google Auto Tagging
+50/month, Video Tagging 5/month) and on a customer cloud quota is their money.
+
+The full matrix, the detection rules, and the **MCP vs `CLOUDINARY_URL` routing
+table** are in [references/capabilities.md](references/capabilities.md). The
+routing matters concretely: `ai_video_analysis` has no MCP tool and cannot be
+signed without an API secret, so on an MCP-only build the audio description
+track is unavailable, and generated titles need a preset that sets
+`auto_video_details`. Everything else is reachable either way.
+
+## B2. Choose the optimization strategy
+
+An explicit decision, not a default. Retrofitting the other one means rewiring
+the player.
+
+**This is a fork, not a comparison.** Video Player Studio encodes it as a
+segmented `Progressive | Adaptive` control: one source, one branch, and the
+two sets of controls are disjoint. Reproduce that shape in code: decide the
+branch first, then set only that branch's options.
+
+| Studio branch | what it offers |
+| --- | --- |
+| **Progressive** | Format (Auto / WebM-VP9 / MP4-H.265 / MP4-H.264), Enable breakpoints (→ Max DPR), Auto HDR, Aspect Ratio (→ Resize Mode) |
+| **Adaptive** | Format: **HLS or MPEG-DASH. Nothing else.** |
+
+The Adaptive branch has no sizing controls because the streaming profile owns
+them, the same rule the server enforces with *resize is only supported for
+overlay*. **The real question is: is this decoration, or is this content
+someone watches?** ABR only pays off when a viewer watches long enough for the
+ladder to react to their network.
+
+**`ffprobe` answers it, so read the source before choosing.** The signals are in
+the file:
+
+| Signal | Reading | Delivery |
+| --- | --- | --- |
+| **Loops** | decoration by definition, seen in passing, never watched through | **progressive**, always |
+| **No audio track** | background/ambient, and almost always short and autoplaying | **progressive** |
+| **Audio but no speech** (music-only) | montage or mood piece, not something followed | **progressive** |
+| **Portrait 9:16 or square** | social/short-form | **progressive** |
+| **Under ~30s** | over before a ladder could switch; never ABR | **progressive** |
+| **Speech, over ~1 min, viewer-pressed play** | content: a talk, explainer, interview, course | **ABR** |
+| **No video track** (audio only) | `sp_auto`, posters and seek thumbnails return 400 | **progressive**, no `breakpoints`; see gotchas.md |
+
+Each branch is one option. Nothing else:
+
+| Approach | Set |
+| --- | --- |
+| **Progressive** | `breakpoints: true` |
+| **ABR** | `sourceTypes: ['hls']` |
+
+That is the whole configuration. No `sourceTypes` on the progressive branch, no
+`breakpoints` on the adaptive one, and on neither a format, quality, width or
+`maxDpr`. The player's default is already `f_auto:video`, `breakpoints` brings
+DPR handling with it, and `sourceTypes:['hls']` emits `sp_auto` itself. Reach
+for `maxDpr` only to deliberately cap DPR below the default 2.0.
+
+Duration is the proxy, not the rule: a three-minute silent loop is still
+progressive, because **behaviour wins over length**, except that under 30
+seconds is always progressive. `ffprobe` shows whether there is audio (and so
+whether transcripts, chapters, and titles can work, A3), not whether it is
+speech; if you can't tell, ask.
+
+**Neither is free to get wrong, and the costs are asymmetric.** ABR on a short
+clip is a real and easy mistake: the ladder never switches, so you pay a
+manifest round-trip and slower startup for nothing. Progressive on a long watch
+fixes one rendition at load, so a network that degrades at minute eight stalls
+with no recovery. That is worse, so a borderline video someone genuinely
+watches goes ABR; a borderline video that autoplays stays progressive. "It's the
+main player" is not a reason. Do not use `e_preview` to shorten an
+already-short video either; loop the real file.
+
+**Do not hand-write `f_auto`/`q_auto` for player-delivered video, and do not
+force `sourceTypes:['mp4']`.** The player's default is already `f_auto:video`,
+and `['mp4']` replaces it with a pinned extension. Hand-written
+`c_limit,w_…/f_auto:video/q_auto` belongs to the native `<video>` fallback only.
+The measured URLs are in [references/capabilities.md](references/capabilities.md).
+
+If the player cannot be used at all, use a native `<video>` with
+media-queried `<source>`s (see the same reference).
+
+### Configure the player; do not hand-write its delivery transformation
+
+The player composes the delivery transformation from its options. Anything you
+write into `transformation:` that an option already covers lands in the *same*
+component: redundant at best, and a 400 for `streaming_profile`.
+
+```js
+// WRONG: the profile shares a component with another directive:
+// e_vignette:50,sp_auto → 400 "streaming_profile must be the only directive"
+player.source(id, { sourceTypes: ['hls'],
+  transformation: { streaming_profile: 'auto', effect: 'vignette:50' } });
+// RIGHT: sourceTypes adds sp_auto itself
+cloudinary.player(el, { sourceTypes: ['hls'] });   // → sp_auto/<id>.m3u8
+```
+
+`sp_auto` also accepts only a [limited set of other transformations](https://cloudinary.com/documentation/adaptive_bitrate_streaming.md?install_source=skillspack&referrer=video-skill#combining_transformations_with_automatic_streaming_profile_selection),
+even in a separate component.
+
+Hand-written transformations are for media no player delivers: posters, hover
+previews, `e_preview` teasers, and the native `<video>` fallback. `breakpoints`
+belongs to the progressive branch only. Set it under ABR and delivery returns
+400 (*resize is only supported for overlay*).
+
+`breakpoints` and `sourceTypes` work on the constructor and on each
+`source()` call, and constructor values are inherited by every `source()`
+call. So a page moving a viewer between a progressive and an ABR asset sets
+both explicitly per call, for example
+`player.source(id, { sourceTypes: ['hls'], breakpoints: false })`. Leaving the
+inherited value in place carries the wrong option across.
+
+Most pages want both, on **different** sources: ABR for the tour, progressive
+for the loops. Full comparison table in
+[references/capabilities.md](references/capabilities.md).
+
+## B3. Load and configure the player
+
+Install from npm and use the **ES import**. The package ships an `exports`
+map with an `import` condition, bundles its own video.js, and loads the player
+core behind a dynamic `import()`, so a bundler code-splits it for you:
+
+```sh
+npm install cloudinary-video-player
+```
+
+```js
+import 'cloudinary-video-player/player.min.css';
+import cloudinary from 'cloudinary-video-player';
+```
+
+For a single-file page with no build step, the UMD build off a CDN works the
+same way and puts `cloudinary` on `window`:
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/cloudinary-video-player@4.1.0/dist/player.min.css">
+<script src="https://unpkg.com/cloudinary-video-player@4.1.0/dist/player.min.js"></script>
+```
+
+**Construct with `cloudinary.player()`, not `cloudinary.videoPlayer()`.**
+`videoPlayer()` is the older synchronous constructor. `player()` is the
+current one: it returns a **Promise**, and it resolves *saved configuration*
+first. Pass `publicId` and it picks up the settings saved onto that asset in
+Video Player Studio; pass `profile` for a stored profile instead.
+
+```js
+const player = await cloudinary.player('hero', {
+  cloudName, publicId: 'my/video',   // asset's saved settings apply
+  /* local options win over saved config */
+});
+```
+
+Precedence is **construction options > profile > asset-saved > defaults**, so
+repeating settings locally makes the saved config dead weight. Save the
+presentation, pass only what is page-specific.
+
+Settings are normally saved through Video Player Studio, but the **Video
+Config API** writes the same thing without console access, which is useful on
+a claimable cloud and makes a build reproducible. It is keyed by `asset_id`, not
+public ID, and PUT replaces the whole document. Passing `publicId` with no
+saved config is silent: HTTP 200 and an empty
+`{"playerOptions":{},"sourceOptions":{}}`. The calls are in
+[references/player.md](references/player.md).
+
+Because construction is async, guard anything that seeks the player: a
+transcript line clicked before it resolves must queue, not throw. The built-in
+profiles and how to verify what applied are in the same reference.
+
+Constructor options vs `source()` options: the split is about **how many
+assets one player shows**. Constructor options configure the *player*;
+`source()` options describe the *asset currently in it*.
+
+**One player, one video:** set everything on the constructor and never call
+`source()`. Pass `publicId` and you are done.
+
+**One player, several videos** (a playlist, a rail, a gallery where clicking a
+thumbnail changes the video): build the player **once** and call `source()` per
+asset. Constructor options persist across the swap; the per-asset metadata
+(`title`, `chapters`, `textTracks`) rides along with each `source()` call.
+Building a new player per video is the common mistake: it costs a fresh
+video.js instance each time and leaks the old ones unless you `dispose()`.
+
+The one thing to watch when swapping is the delivery strategy above: set
+`sourceTypes` and `breakpoints` explicitly on each `source()` call.
+
+Player-only options go on the constructor and are ignored by `source()`.
+Per-video options work on `source()`, and on the constructor they become
+defaults every `source()` call inherits:
+
+| Constructor only | `source()` (or constructor, as a default) |
+| --- | --- |
+| `cloudName`, `fluid`, `controls`, `showLogo`, `colors` | `sourceTypes`, `breakpoints`, `maxDpr`, `transformation` |
+| `seekThumbnails`, `chaptersButton`, `aiHighlightsGraph` | `chapters`, `title`, `description`, `textTracks`, `posterOptions`, `interactionAreas` |
+
+**`colors.text` must be a LIGHT colour.** Player chrome sits over dark video; a
+dark text token makes the controls invisible.
+
+Every option is in the
+[Video Player API reference](https://cloudinary.com/documentation/video_player_api_reference.md?install_source=skillspack&referrer=video-skill);
+the traps are in [references/player.md](references/player.md).
+
+## B4. Wire the experience
+
+The capabilities are only worth having if the page uses them. Patterns that
+worked, with the reasoning, in
+[references/build-patterns.md](references/build-patterns.md):
+
+- **For a long source: open on an `e_preview` loop and build the player lazily**
+  on first interaction: motion instead of a black frame, and no stream fetched
+  until wanted. **For a short clip, just loop the real video muted** and build
+  eagerly; there is no stream worth deferring and no teaser worth cutting.
+- **Guard against the async constructor**: `cloudinary.player()` returns a
+  Promise, so queue seeks that arrive before it resolves.
+- **Compose `source()` from the flags** by conditional spread. Skip absent
+  features; never stub them with a URL that 404s. Check the content too: a
+  chapters VTT can return 200 with nothing but the `WEBVTT` header.
+- **Bind playback both directions**: rail and transcript seek the player;
+  `timeupdate` highlights the current segment. Render the rail before the player
+  exists, since clicking it is what builds the player.
+- **The transcript is JSON, not VTT**: hand it to the player for captions,
+  fetch and render it yourself for on-page search with click-to-seek.
+- **Emit JSON-LD** from the generated title, description and chapters.
+
+## B4a. Generated, supplied, or hand-authored, in that order
+
+Video Player Studio offers the same three-tier ladder on every piece of
+content, and it is a good default for deciding where metadata comes from:
+
+| panel | tier 1: generate | tier 2: supply | tier 3: author |
+| --- | --- | --- | --- |
+| Chapters | Automatically generate chapters | Import a VTT file | Type `00:00` + name |
+| Transcript | Generate | Upload | n/a |
+| Poster | Suggested posters (AI frames) | Media Library / current frame | Upload |
+
+Two things follow. First, **every generated artefact has a supply path beside
+it**, so when a human-authored caption, chapter list or poster already exists
+(for example, carried over from the platform the video came from), use it; the
+ladder exists precisely so generation is not the only route. Second, the tiers
+are per-asset, not per-site: generating chapters for a long talk and
+hand-authoring three for a short explainer is normal.
+
+## B5. Be straight about what Cloudinary does not generate
+
+- **Chapter→product bindings.** Auto-chaptering finds the segments; which
+  product a segment sells is your data. Check the source platform's cue points
+  and custom fields first; often it is already there.
+- **Hotspot positions.** `interactionAreas` takes coordinates you supply.
+  Cloudinary does not track objects and hand you positions. The AI Video
+  Analysis API (Beta) returns timestamped natural-language segments with no
+  spatial coordinates or bounding boxes.
+- **Video background removal, virtual try-on, shade matching.** These do not
+  exist. Do not approximate them with something adjacent.
+
+## Close out
+
+- Which capabilities are on, which are off, **and why**: name the add-on and
+  what enabling it needs.
+- What was uploaded, and anything that had no Cloudinary equivalent.
+- On a claimable cloud: **the claim URL**, and that it expires in 24 hours.
+
+## How much of this is verified
+
+Calibrate accordingly. The guidance is not uniformly tested:
+
+- **Key Cloudinary behaviour is machine-verified.** A subset of the delivery,
+  transformation and async-output claims is asserted against live Cloudinary by
+  a test suite kept in the cloudinary-devs/skills repo (`sp_auto` rejecting a resize at every
+  width, the transcript being JSON with word-level timings, the pinned player
+  CDN URLs). If Cloudinary changes, those assertions fail rather than quietly
+  misleading you.
+- **Nothing here has been run end to end against an existing customer cloud.**
+  The from-scratch path has a worked example behind it; that one does not.
+
+Say which applies when you rely on one; don't present it all as equally sure.
+
+## Additional Resources
+
+### Skill References (Progressive Disclosure)
+- [references/upload-and-prepare.md](references/upload-and-prepare.md) - Use when the media is not yet on Cloudinary: provisioning, upload parameters, async features, and warming
+- [references/field-guide.md](references/field-guide.md) - Use when advising on or reviewing a video implementation: the delivery cheat sheet, common mistakes, `f_auto` usage spikes, eager transformations, mobile apps, and pre-launch checks
+- [references/capabilities.md](references/capabilities.md) - Use when deciding which features a cloud supports, whether to use MCP or `CLOUDINARY_URL`, or ABR versus progressive
+- [references/build-patterns.md](references/build-patterns.md) - Use when wiring the page: lazy player, feature flags, chapter and transcript binding, structured data
+- [references/player.md](references/player.md) - Use when constructing or configuring the player: `player()` versus `videoPlayer()`, saved configuration, profiles, and option traps
+- [references/gotchas.md](references/gotchas.md) - Use when something fails unexpectedly: upload presets, quotas, async failures, still-generating derivatives, video.js DOM changes, and delivery-IP traps
+
+### Core Cloudinary Documentation
+- [Cloudinary Video Player](https://cloudinary.com/documentation/cloudinary_video_player.md?install_source=skillspack&referrer=video-skill)
+- [Video Player API Reference](https://cloudinary.com/documentation/video_player_api_reference.md?install_source=skillspack&referrer=video-skill) - All constructor and `source()` options
+- [Video Player Customization](https://cloudinary.com/documentation/video_player_customization.md?install_source=skillspack&referrer=video-skill) - Chapters, captions, transcripts, breakpoints
+- [Adaptive Streaming in the Video Player](https://cloudinary.com/documentation/video_player_hls_dash.md?install_source=skillspack&referrer=video-skill)
+- [Video Player Studio](https://cloudinary.com/documentation/video_player_studio.md?install_source=skillspack&referrer=video-skill)
+- [Video Player Profiles](https://cloudinary.com/documentation/video_player_profiles_reference.md?install_source=skillspack&referrer=video-skill)
+- [Interactive Video](https://cloudinary.com/documentation/video_player_interactive_videos.md?install_source=skillspack&referrer=video-skill) - Interaction areas
+- [Video Optimization](https://cloudinary.com/documentation/video_optimization.md?install_source=skillspack&referrer=video-skill)
+- [Adaptive Bitrate Streaming](https://cloudinary.com/documentation/adaptive_bitrate_streaming.md?install_source=skillspack&referrer=video-skill)
+- [Eager and Incoming Transformations](https://cloudinary.com/documentation/eager_and_incoming_transformations.md?install_source=skillspack&referrer=video-skill)
+- [Video Transcription](https://cloudinary.com/documentation/video_transcription.md?install_source=skillspack&referrer=video-skill)
+- [AI Video Analysis](https://cloudinary.com/documentation/ai_video_analysis.md?install_source=skillspack&referrer=video-skill)
+
+## Related Skills
+
+- **cloudinary-transformations**: Building and debugging transformation URLs, including video transformations
+- **cloudinary-docs**: Looking up anything this skill does not cover
+- **cloudinary-react** and **cloudinary-next**: Framework patterns when the page is a React or Next.js app
diff --git a/skills/cloudinary-video/references/build-patterns.md b/skills/platform/cloudinary-video/references/build-patterns.md
similarity index 70%
rename from skills/cloudinary-video/references/build-patterns.md
rename to skills/platform/cloudinary-video/references/build-patterns.md
index 39431cc..ec58879 100644
--- a/skills/cloudinary-video/references/build-patterns.md
+++ b/skills/platform/cloudinary-video/references/build-patterns.md
@@ -1,27 +1,32 @@
 # Build patterns
 
-Wiring that turned out to matter, generalized from a working build. The player
-option *shapes* live in [player.md](player.md); this is how the pieces fit
-together into a page.
+Wiring that turned out to matter, generalized from a working build. Player
+configuration and option traps live in [player.md](player.md); this is how the
+pieces fit together into a page.
 
 ## Build the player lazily, behind the opening frame
 
 The strongest single improvement to a **long-form** video page: do not open on a
 black frame, and do not fetch the real stream until someone wants it.
 
-Open with an `e_preview` loop — an AI-chosen summary of the video, muted and
-looping, playing as the poster — with a play affordance over it. The first
+`cloudinary.player()` has a built-in `lazy` option that defers the full player
+behind a static poster. Use it when a still poster is enough; the pattern below
+is for when you want a moving opening frame instead. Pre-generate the
+`e_preview` eagerly: its first request returns 423 until analysis finishes.
+
+Open with an `e_preview` loop (an AI-chosen summary of the video, muted and
+looping, playing as the poster) with a play affordance over it. The first
 interaction builds the player and starts playback.
 
-**This whole pattern assumes a long source.** For a short clip — a campaign
-film, a product video, anything under a minute or two — skip it entirely:
+**This whole pattern assumes a long source.** For a short clip (a campaign
+film, a product video, anything under about a minute), skip it entirely:
 there is no stream worth deferring, and `e_preview` would only produce
 something marginally shorter than the asset. Loop the real video muted and
 give it a sound/expand affordance instead. Building eagerly is fine there, and
 with `cloudinary.player()` resolving saved configuration it is one call.
 
 Note that `cloudinary.player()` is **async**, so even an eager build needs the
-queue below — a transcript cue or timecode chip can be clicked before the
+queue below: a transcript cue or timecode chip can be clicked before the
 promise resolves.
 
 ```js
@@ -36,25 +41,27 @@ function withPlayer(fn) {
 }
 ```
 
-Why a queue rather than building eagerly: other parts of the page (a room rail,
+Why a queue rather than building eagerly: other parts of the page (a chapter rail,
 a transcript cue) can be clicked before the player exists, and each of those is
 a reason to build it. The queue lets them all express "seek to 26s" without
 caring whether the player is there yet.
 
-Autoplay on the loop is only permitted while muted and can still be refused —
+Autoplay on the loop is only permitted while muted and can still be refused:
 `void loop.play().catch(() => {})`, and let the poster stand if it fails.
 
 ## Let player options build the URL, not you
 
-Options carry **delivery** — profile, format, quality, width. `source()`
-carries **content** — which asset, its chapters, text tracks, poster,
-interaction areas. A delivery directive written into `source()` lands in the
+Delivery options (`sourceTypes`, `breakpoints`) shape the URL; the player
+composes it. A delivery directive written into `transformation:` lands in the
 player's own transformation component instead of layering on top of it:
 
 ```js
-// WRONG: sourceTypes:['hls'] already emits sp_auto. This yields
-// c_limit,sp_auto,w_640/… → 400 "streaming_profile must be the only directive"
-player.source(id, { transformation: { streaming_profile: 'auto' } });
+// WRONG: the hand-written profile shares a component with another directive:
+// e_vignette:50,sp_auto → 400 "streaming_profile must be the only directive"
+player.source(id, { sourceTypes: ['hls'],
+  transformation: { streaming_profile: 'auto', effect: 'vignette:50' } });
+// RIGHT: let sourceTypes add sp_auto
+player.source(id, { sourceTypes: ['hls'] });
 ```
 
 ## Compose `source()` from the feature flags
@@ -75,7 +82,7 @@ The distinction that bites: an omitted `textTracks` gives a player with no
 caption button; a `textTracks` containing an entry whose URL 404s gives a
 caption button that does nothing. Skip, do not stub.
 
-Note `posterOptions` and the `e_preview` opening frame are mutually exclusive —
+Note `posterOptions` and the `e_preview` opening frame are mutually exclusive:
 if the loop is the opening frame there is no poster to choose, so requesting an
 AI keyframe as well is wasted work.
 
@@ -87,25 +94,25 @@ a player feature:
 - **Page → player.** A rail item or transcript cue calls
   `player.currentTime(seconds); player.play()` (through `withPlayer`).
 - **Player → page.** A `timeupdate` handler finds the current segment and
-  highlights it. Track the last value and only act on change — `timeupdate`
+  highlights it. Track the last value and only act on change: `timeupdate`
   fires several times a second and re-rendering on each is visible jank.
 
 ```js
 player.on('timeupdate', () => {
   const t = player.currentTime();
   const match = chapters.find((c) => t >= c.start && t < c.end);
-  if (match?.sku !== lastSku) { lastSku = match?.sku; setActiveRoom(lastSku); }
+  if (match?.id !== lastId) { lastId = match?.id; setActiveSegment(lastId); }
 });
 ```
 
-Render the rail **before** the player exists. Selecting a room is one of the
+Render the rail **before** the player exists. Selecting a rail item is one of the
 things that builds the player, so a rail that waits for the player is a rail
 that can never trigger it.
 
 ## The transcript: what the player does, and what it does not
 
-`<publicId>.transcript` is Cloudinary's own JSON — cues carrying `transcript`
-text and word-level timings — not a VTT file. **The player supports it
+`<publicId>.transcript` is Cloudinary's own JSON (cues carrying `transcript`
+text and word-level timings), not a VTT file. **The player supports it
 natively**, so do not hand-roll what it already does:
 
 ```js
@@ -116,17 +123,19 @@ textTracks: {
 ```
 
 - Omitting `url` makes the player resolve the `.transcript` for that public ID.
-- Setting **`maxWords`** makes it look for `<publicId>.transcript` explicitly —
+- Setting **`maxWords`** makes it look for `<publicId>.transcript` explicitly;
   this is the documented trigger, not just a display cap.
 - **`wordHighlight: true`** uses the word-level timings to highlight each word
   as it is spoken. This is the payoff for the transcript being JSON rather than
-  VTT, and it is a player feature — you do not build it.
+  VTT, and it is a player feature: you do not build it.
 
 What the player has **no** native support for is a **searchable transcript
-panel** — a list of cues you can filter and click to seek. There is no
+panel**: a list of cues you can filter and click to seek. There is no
 `transcript`/`interactiveTranscript` option. If the page wants that, fetch the
-`.transcript` and render it yourself, using `words[].start_time` for
-click-to-seek accuracy, and drive the player with `player.currentTime(t)`.
+`.transcript` and render it yourself, and drive the player with
+`player.currentTime(t)`. Each cue is `{ transcript, confidence, words }` with no
+cue-level time, so seek to a cue's `words[0].start_time` (or a word's own
+`start_time` for word-level accuracy).
 
 So the split is: **captions, word highlighting and translated subtitles are the
 player's job; an on-page searchable transcript is yours.**
@@ -141,28 +150,29 @@ an honest "Transcript unavailable."
 ## Audio description as a subtitles track
 
 The player has no native descriptions kind, so the visual transcription from
-`ai_video_analysis` — describing what is *on screen* rather than what is said —
+`ai_video_analysis` (describing what is *on screen* rather than what is said)
 goes in as another `subtitles` entry, labelled so it is not mistaken for a
 translation. Requires an API secret; unavailable over MCP alone.
 
 ## Structured data comes free once the metadata exists
 
 `auto_video_details` and `auto_chaptering` give you everything a
-`schema.org/VideoObject` wants — `name`, `description`, `duration`, and
+`schema.org/VideoObject` wants: `name`, `description`, `duration`, and
 `hasPart` clips from the chapter boundaries. Emit it as JSON-LD. Only do this
 when the flag is on; fabricating a description for SEO is worse than omitting
 the block.
 
 ## Let the player do visibility, not an IntersectionObserver
 
-For decorative loops — tiles, background clips, a feature panel — the reflex is
+For decorative loops (tiles, background clips, a feature panel), the reflex is
 an `IntersectionObserver` that plays on enter and pauses on exit. The player
-has this: `autoplay: 'on-scroll'`, alongside `muted`, `loop` and
-`controls: false`. Save that on each asset and the observer disappears, along
+has this: `autoplayMode: 'on-scroll'`, alongside `muted`, `loop` and
+`controls: false`. (Not `autoplay: 'on-scroll'`: that value is treated as plain
+`autoplay: true`, so the clip always autoplays.) Save that on each asset and the observer disappears, along
 with the lazy `src` assignment people bolt onto it.
 
 That also keeps every clip on the player's own optimizations (`f_auto:video`,
-breakpoints) rather than a hand-written URL on a bare `<video>` — a page mixing
+breakpoints) rather than a hand-written URL on a bare `<video>`; a page mixing
 both ends up with the players optimized and the loops not.
 
 ## Ship the site, not the demo scaffolding
@@ -171,12 +181,12 @@ Build generously and present quietly. Those are not in tension: every
 capability the cloud supports should be *working* in the page, and none of them
 should be *announced* by it.
 
-When the deliverable is "a page for <brand>", it is that brand's site — not an
+When the deliverable is "a page for <brand>", it is that brand's site, not an
 exhibit about Cloudinary. Capability ledgers, delivery tables listing `sp_auto`
 and `f_auto`, transformation footnotes and "what this cloud can do" sections
 are scaffolding: they read as a vendor demo and would never survive on a real
-storefront. Build what the brand would actually ship — navigation, a hero,
-merchandising, working commerce affordances, a real footer — and let the media
+storefront. Build what the brand would actually ship (navigation, a hero,
+merchandising, working commerce affordances, a real footer) and let the media
 pipeline be invisible.
 
 Keep the honesty about missing capabilities, but put it in your *report to the
diff --git a/skills/cloudinary-video/references/capabilities.md b/skills/platform/cloudinary-video/references/capabilities.md
similarity index 56%
rename from skills/cloudinary-video/references/capabilities.md
rename to skills/platform/cloudinary-video/references/capabilities.md
index b33c58b..2e09640 100644
--- a/skills/cloudinary-video/references/capabilities.md
+++ b/skills/platform/cloudinary-video/references/capabilities.md
@@ -17,7 +17,7 @@ const features = {
   chapters: true,
   seekThumbnails: true,
   hotspots: true,
-  machineTags: false,         // needs Google Auto Tagging
+  machineTags: false,         // needs Google Automatic Video Tagging
   responsivePlayer: true,
   captions: true,
   translatedSubtitles: false, // needs Google Translation
@@ -27,21 +27,21 @@ const features = {
 ```
 
 Keeping it in one object rather than scattered `if`s is what makes the
-degradation auditable — you can read off what this page will and will not do,
+degradation auditable: you can read off what this page will and will not do,
 and say so honestly at the end of a run.
 
 ## The matrix
 
 | Capability | Needs | Absent → degrade to |
 | --- | --- | --- |
-| Adaptive streaming (`sp_auto`) | nothing | progressive MP4 + `f_auto/q_auto` |
-| AI poster (`so_auto`) | nothing | first frame, or a chosen still |
-| `e_preview` loop opening frame (long sources only) | nothing (warm it) | AI poster, then plain poster |
+| Adaptive streaming (`sp_auto`) | a video track (audio-only sources return 400) | progressive (`breakpoints: true`) |
+| Auto poster (`so_auto`) | nothing | first frame, or a chosen still |
+| `e_preview` loop opening frame (long sources only) | nothing (warm it) | auto poster, then plain poster |
 | Hover previews | chapter→SKU map | static image on hover |
 | Chapters + rail | `auto_chaptering` (or migrated cue points) | no rail; plain scrub bar |
-| Seek thumbnails (`fl_sprite`) | nothing | off — the player copes |
+| Seek thumbnails (`fl_sprite`) | nothing | off; the player copes |
 | Hotspots → cart | **your** coordinates + SKU map | off; rail does the linking |
-| Machine tags / facets | Google Auto Tagging add-on | existing hand-authored tags |
+| Machine tags / facets | Google Automatic Video Tagging add-on (Google Auto Tagging for images) | existing hand-authored tags |
 | Captions | `auto_transcription`, or migrated captions | no caption track |
 | Translated subtitles | Google Translation add-on | English captions only |
 | Audio description | `ai_video_analysis` (**needs API secret**) | omit the track |
@@ -52,11 +52,12 @@ Two rows deserve their own note, because they are the ones people assume
 Cloudinary supplies and it does not:
 
 - **Hotspot coordinates** are yours. `interactionAreas` takes coordinates you
-  pass. AI Video Analysis returns a timestamped natural-language visual
-  transcription and explicitly **no** spatial coordinates or bounding boxes.
+  pass. AI Video Analysis (Beta) returns timestamped natural-language segments
+  (`transcript`, `start_time`, `end_time`) with no spatial coordinates or
+  bounding boxes.
 - **Chapter→product bindings** are yours. Auto-chaptering finds segment
   boundaries; which SKU a segment is selling is business data. On a migration,
-  check the source platform first — cue points and custom fields often already
+  check the source platform first: cue points and custom fields often already
   carry it.
 
 ## Detecting, rather than assuming
@@ -68,37 +69,39 @@ opposites:
 tags will be absent every time; that is correct, not a regression. Hardcoding
 those two to `false` is the honest default.
 
-**Existing customer cloud.** Do not assume either way — add-ons may well be
+**Existing customer cloud.** Do not assume either way: add-ons may well be
 subscribed. Probe by attempting the operation on **one** asset and reading the
 result, then set the flag. Never probe by looping the catalogue: free tiers are
-small (Google Auto Tagging 50/month, Google Video Tagging 5/month) and on a
-customer cloud the quota is their money.
+small monthly quotas, and on a customer cloud the quota is their money.
 
-There is no Admin API that lists entitlements — `/addons`, `/add_ons`,
+There is no Admin API that lists entitlements: `/addons`, `/add_ons`,
 `/subscriptions`, `/entitlements` all 404. Attempting the operation is the only
 detection available.
 
 ## Access routing: MCP vs `CLOUDINARY_URL`
 
-The Cloudinary MCP never exposes an API secret, so it can only do what it has a
-tool for. This is not a permissions problem you can escalate — unsigned
-requests to any other endpoint return
+Working through the Cloudinary MCP servers, the agent never holds the API
+secret, so it can only do what the MCP has a tool for. This is not a
+permissions problem you can escalate: unsigned requests to any other endpoint
+return
 `error while authenticating: api_secret not provided`.
 
 | Step | Over MCP | With `CLOUDINARY_URL` |
 | --- | --- | --- |
-| Upload, with free analysis on the call | yes | yes |
+| Upload with `auto_transcription` / `auto_chaptering` | yes | yes |
+| Upload with `auto_video_details` | **no parameter** (use an upload preset that sets it) | yes |
 | Poll asset for async status | yes | yes |
 | Asset update / tags / context | yes | yes |
 | Delivery URLs, warming derivations | yes (plain HTTP) | yes |
 | Add-on categorization / auto-tagging | yes | yes |
-| `ai_video_analysis` (visual transcription) | **no tool — unreachable** | yes |
+| `ai_video_analysis` (visual transcription) | **no tool, so unreachable** | yes |
 | Any v2 or beta route | **no** | yes |
 
 Consequence worth stating to the user rather than discovering late: on an
 MCP-only build the **audio description track is simply unavailable**, because
-`POST /v2/video/<cloud>/ai_video_analysis` cannot be signed. Everything else in
-the matrix is reachable either way.
+`POST /v2/video/<cloud>/ai_video_analysis` cannot be signed, and generated
+titles and descriptions need an upload preset that sets `auto_video_details`.
+Everything else in the matrix is reachable either way.
 
 Before concluding a feature does not exist, check whether it is merely
 unreachable by the route in use. The two are indistinguishable from inside an
@@ -106,47 +109,48 @@ MCP session.
 
 ## Optimization strategy: `sp_auto` (ABR) vs `breakpoints` (progressive)
 
-Two mechanisms for the same goal — stop sending every viewer the same bytes —
-working in opposite ways. Pick one **per source**; the choice is not reversible
-without rewiring the player.
+Two mechanisms for the same goal (stop sending every viewer the same bytes),
+working in opposite ways. Pick one **per source**.
 
-| | `sp_auto` — adaptive bitrate | `breakpoints` — progressive |
+| | `sp_auto` (adaptive bitrate) | `breakpoints` (progressive) |
 | --- | --- | --- |
-| `sourceTypes` | `['hls']` (or `['dash']`) | **leave unset** — the default. `['mp4']` pins the format and disables `f_auto:video` |
+| `sourceTypes` | `['hls']` (or `['dash']`) | **leave unset** (the default). `['mp4']` pins the format and disables `f_auto:video` |
 | What it delivers | one manifest listing a rendition ladder | one file at one chosen width |
 | Who decides | the **player**, continuously, per segment | the **player**, once, at load |
 | Adapts to | bandwidth *and* changes mid-playback | viewport/DPR at startup only |
-| Recovers from a stall | yes — drops to a lower rung | no — it is one file |
+| Recovers from a stall | yes, drops to a lower rung | no, it is one file |
 | Startup cost | manifest + first segments | one request |
 | Overhead | segmenting, manifest, more derivations to warm | none beyond the resize |
 
-### Duration decides this, not "main player vs decoration"
+### Behaviour decides; duration is the proxy
 
 **Check the asset's duration before choosing.** Cloudinary's own field guidance
 is duration-based, and it is the opposite of "ABR is the default for anything
-important":
+important". Behaviour still wins where the two disagree (a long silent loop is
+progressive), except that under 30 seconds is always progressive:
 
 | Duration | Approach |
 | --- | --- |
-| **Up to 1–2 minutes** | **Progressive** — the player's default. `f_auto` + `q_auto`, plus responsive breakpoints. Product videos, campaign films, promos, social-style clips, anything inline or autoplaying. |
-| **More than 1–2 minutes**, especially viewer-selected and not autoplaying | **ABR** (`sp_auto` via `sourceTypes:['hls']`). Long-form, where a network can realistically degrade mid-watch. |
+| **Under about 1 minute** (and never ABR under 30 seconds) | **Progressive**, the player's default: the player's own `f_auto:video`, plus `breakpoints: true`. Product videos, campaign films, promos, social-style clips, anything inline or autoplaying. |
+| **About 1 minute or more**, especially viewer-selected and not autoplaying | **ABR** (`sp_auto` via `sourceTypes:['hls']`). Long-form, where a network can realistically degrade mid-watch. |
 
 `sp_auto` is the only mechanism that responds to bandwidth dropping *while
-someone is watching* — but that advantage needs a watch long enough for it to
+someone is watching*, but that advantage needs a watch long enough for it to
 act. On a 14-second campaign film the ladder never meaningfully switches, and
 you have bought manifest round-trips, slower startup, and a pile of renditions
 to generate and warm in exchange for nothing. **Progressive is the default for
 short web video; reach for ABR when length justifies it.**
 
-`breakpoints` is right for short video generally — including silent decorative
-loops, hover previews and background clips, where a manifest is pure overhead.
+`breakpoints` is right for short player-delivered video generally, including
+silent decorative loops and background clips, where a manifest is pure
+overhead.
 
 **Do not reach for `e_preview` to make a short clip shorter.** `e_preview`
 extracts a teaser from a *long* source. Generating a 6-second preview of a
 14-second video produces something barely shorter than the asset itself, costs
 extra derivations to warm, and is strictly worse than looping the real file.
 
-### The player already applies `f_auto:video` — do not restate it
+### The player already applies `f_auto:video`, so do not restate it
 
 Measured against `cloudinary-video-player@4.1.0`, with the same asset:
 
@@ -159,45 +163,48 @@ Measured against `cloudinary-video-player@4.1.0`, with the same asset:
 
 The third row is the trap: asking for MP4 **removes** `f_auto:video`, pinning
 one format for every viewer. The fourth row is people noticing the loss and
-manually re-adding what the default gave them for free — while still pinned to
-the `.mp4` container.
+manually re-adding what the default gave them for free. `f_auto` still picks
+the format despite the `.mp4` extension, so it works, but it is redundant noise
+the player already handles.
 
 **The rule this table is an instance of:** express delivery through player
 options and let it build the URL. Anything written into `transformation:` that
 an option already covers gets merged into the player's own component. Save
-hand-written transformations for assets no player manages — posters, hover
-loops, `e_preview` teasers, the native `<video>` fallback.
+hand-written transformations for media no player delivers: posters, hover
+previews, `e_preview` teasers, the native `<video>` fallback.
 
 So for progressive: set `breakpoints`, leave `sourceTypes` alone, and write no
 format/quality transformation. The extensionless `f_auto:video` URL is
-content-negotiated per request — the same URL returned WebM to one request and
-MP4 to another in testing.
+content-negotiated per request, so different browsers can receive WebM or MP4
+from the same URL.
 
 ### If the Cloudinary player cannot be used
 
 Deliver progressive with a native `<video>` and several `<source>` elements, so
-the browser picks by viewport — the same optimizations, without the player:
+the browser picks by viewport. That gives the same optimizations without the player:
 
 ```html
 <video controls autoplay muted playsinline preload="metadata">
   <source media="(max-width: 640px)"
-    src=".../video/upload/c_limit,w_640/f_auto:video/q_auto/v1/<id>.mp4" type="video/mp4">
+    src=".../video/upload/c_limit,w_640/f_auto/q_auto/v1/<id>.mp4">
   <source media="(max-width: 1280px)"
-    src=".../video/upload/c_limit,w_1280/f_auto:video/q_auto/v1/<id>.mp4" type="video/mp4">
+    src=".../video/upload/c_limit,w_1280/f_auto/q_auto/v1/<id>.mp4">
   <source
-    src=".../video/upload/c_limit,w_1920/f_auto:video/q_auto/v1/<id>.mp4" type="video/mp4">
+    src=".../video/upload/c_limit,w_1920/f_auto/q_auto/v1/<id>.mp4">
 </video>
 ```
 
-Note `f_auto:video` (not bare `f_auto`) for the format/codec pick, `q_auto` for
-quality, and `c_limit,w_…` to cap dimensions. For ABR without the player,
-generate the manifest with `sp_auto` and hand the `.m3u8` to a compatible
-third-party player.
+Use `f_auto` for the format/codec pick (`f_auto:video` is only needed when the
+URL has no file extension), `q_auto` for quality, and `c_limit,w_…` to cap
+dimensions. Leave out `type="video/mp4"`: `f_auto` may return WebM, and a
+wrong type hint can make a browser skip the source. For ABR without the
+player, generate the manifest with `sp_auto` and hand the `.m3u8` to a
+compatible third-party player.
 
 ### `breakpoints` is progressive-only
 
 `breakpoints` exists to pick a delivery **width** for the container on the
-progressive path. ABR does not need one — the streaming profile defines the
+progressive path. ABR does not need one: the streaming profile defines the
 rendition ladder and the player moves between rungs as bandwidth changes. So
 the two are not alternatives to weigh against each other on one source:
 `breakpoints` has no meaning once `sourceTypes:['hls']` is set, exactly as
@@ -212,47 +219,55 @@ c_limit,w_2560/sp_auto/….m3u8   →   HTTP 400
 
 Cloudinary rejects a resize combined with a streaming profile ("sp_auto
 transformation is not allowed (resize is only supported for overlay)"), because
-the streaming profile *already defines* the rendition ladder — asking for one
+the streaming profile *already defines* the rendition ladder, and asking for one
 width contradicts the whole mechanism. Verified at every width tried, 640
 through 2560: always 400, and the video simply never loads.
 
-So `breakpoints` stays off under `sourceTypes:['hls']` — not as a workaround,
+So `breakpoints` stays off under `sourceTypes:['hls']`, not as a workaround
 but because there is no progressive path here to size. Using player options
 rather than hand-written URLs does not avoid it; the player composes the
 invalid URL for you.
 
-Don't hand-write the profile either: `sourceTypes:['hls']` already emits
-`sp_auto`, and adding `transformation:{streaming_profile:'auto'}` merges it
-into the resize's component, which hides the real cause behind a second error.
+Don't hand-write the profile for `sp_auto` either: `sourceTypes:['hls']` adds
+it for you. Set `transformation:{streaming_profile:…}` only to pick a named
+profile, and never alongside `breakpoints` or another directive in the same
+component, because a streaming profile must be alone in its component
+("streaming_profile must be the only directive in the transformation
+component").
 
-Both are constructor options, so dispose and rebuild the player when a page
-moves a viewer between the two strategies.
+Both can be set per source: `source()` options override the constructor's, and
+constructor values are inherited by every `source()` call. So when a page moves
+a viewer between strategies, pass both explicitly on each call, for example
+`player.source(id, { sourceTypes: ['hls'], breakpoints: false })` for ABR.
 
-`maxDpr` is narrower than "MP4-only": Video Player Studio reveals Max DPR only
-*after* breakpoints is enabled, so it is a child of breakpoints rather than an
-independent option. With ABR neither exists — the ladder governs resolution.
+`maxDpr` (a number, default 2.0) is a child of breakpoints: Video Player Studio
+reveals Max DPR only *after* breakpoints is enabled. With ABR neither exists;
+the ladder governs resolution.
 
 ### The normal shape is both, on different sources
 
 A page usually wants ABR for the main tour and progressive for the loops:
 
 ```js
-// main player, LONG source — adapts while watching
-sourceTypes: ['hls'],  breakpoints: false
+// main player, LONG source: adapts while watching
+cloudinary.player(el, { publicId: 'tour', sourceTypes: ['hls'], breakpoints: false });
+```
 
-// preview loop cut from that long source — one small file, no manifest
-<video src=".../e_preview:duration_10.0/f_auto/q_auto/hero.mp4" muted loop>
+```html
+<!-- preview loop cut from that long source: one small file, no manifest -->
+<video src=".../e_preview:duration_10.0/f_auto/q_auto/tour.mp4" muted loop playsinline></video>
 ```
 
 That is the common configuration, not a compromise. What is *not* available is
 both mechanisms on the same source.
 
 If the main video is itself short, this shape does not apply: everything is
-progressive, and the "loop" is simply the real file
-(`c_limit,w_…/f_auto/q_auto/hero.mp4`) rather than an `e_preview` cut of it.
+progressive, and the loop is the real file played through the player (the
+`cld-looping` profile, `breakpoints: true`, `seekThumbnails: false`) rather
+than an `e_preview` cut of it.
 
 ### Naming collision worth flagging
 
 The player option `breakpoints` (a boolean, video) is unrelated to the image URL
 parameter `w_auto:breakpoints` (responsive image widths). Same word, different
-subsystems — do not let one's documentation answer a question about the other.
+subsystems: do not let one's documentation answer a question about the other.
diff --git a/skills/platform/cloudinary-video/references/field-guide.md b/skills/platform/cloudinary-video/references/field-guide.md
new file mode 100644
index 0000000..4d5f70a
--- /dev/null
+++ b/skills/platform/cloudinary-video/references/field-guide.md
@@ -0,0 +1,147 @@
+# Field guide: delivery best practices
+
+This is the guidance to apply when advising on, reviewing or building a
+customer's video implementation. It is about *delivering video well*, not
+about the player's API surface (see [player.md](player.md)).
+
+## Understand the use case before recommending anything
+
+Recommendations follow from the use case, so establish it first:
+
+- **What types of video?** In e-commerce, typically short product videos on
+  PDPs, plus campaign/content videos on homepages and landing pages.
+- **How long are they?** Under a minute, or longer? This drives the delivery
+  method more than anything else.
+- **Where are they delivered?** Web (desktop/mobile), native mobile apps, or
+  other channels. Native apps change the rules; see below.
+- **Do they need analytics?** Views, engagement, watch time.
+- **Do they release videos into traffic spikes?** Catalogue launches, major
+  campaigns. This is what makes eager transformations worth it.
+- **Do they need subtitles/captions?** Already authored, or generated and
+  translated?
+- **Any other accessibility or navigation needs?** Audio descriptions, chapters.
+- **Is anything done to the video before upload?** Cropping, logo overlays, or
+  burned-in subtitles done in an editor can usually be replaced with
+  transformations, upload presets, or player text tracks.
+
+## Delivery cheat sheet
+
+| Scenario | Approach | Notes |
+| --- | --- | --- |
+| Short (under about a minute), inline, autoplay, PDP, campaign or social-style web video | **Cloudinary Video Player, progressive** | Optimizes by default (the URL it builds carries `f_auto:video`; quality comes from Default video quality). Write no format/quality transformation, and do not set `sourceTypes`. Enable responsive breakpoints for per-screen dimensions |
+| Short web video, player unavailable | **Native `<video>` with multiple `<source>`** | `c_limit,w_[width]` + `f_auto:video` + `q_auto` |
+| Longer-form / viewer-selected video (about a minute or more; never under 30 seconds) | **ABR, preferably via the player** | Set `hls` in `sourceTypes` (HLS has the broadest support, and plays natively on Apple devices; `dash` also works); the player adds `sp_auto` for you |
+| ABR, player unavailable | **HLS via a compatible third-party player** | Generate the manifest with `sp_auto`; verify browser/device support |
+| Major launch, big catalogue drop, high-traffic event | **Eager transformations, on top of the chosen approach** | Pre-generate derivatives at upload; do not let first requests build them |
+| Native iOS/Android app | **Mobile-specific strategy** | App picks codec/format and dimensions; URL params or `Accept` header |
+| Analytics, captions, accessibility, chapters, branded UI needed | **Use the Cloudinary Video Player** | All of it works out of the box. Other HTML5 players can report the same analytics with the `cloudinary-video-analytics` library |
+
+## Typical issues to avoid
+
+- **Delivering the original**, untransformed. Default video quality only kicks
+  in when *some* transformation is present in the URL; a bare original URL
+  gets no optimization at all.
+- **No maximum dimensions.** Shipping 4K/8K where 1080p is indistinguishable
+  burns bandwidth and units for no visible gain. Cap with `c_limit,w_…` for
+  progressive. `sp_auto` already caps at 1080p by default; set
+  `sp_auto:maxres_<n>p` only to change that.
+- **Partial optimization**: applying some of `f_auto` / `q_auto` / resizing but
+  not the rest, and ending up with files larger than necessary.
+- **Assuming `f_auto` picks a codec in native mobile apps on its own.** It only
+  works there if the app sends an `Accept` header listing the formats the
+  device supports. See *Mobile apps are a different problem* below.
+- **Preloading everything.** Preloading improves perceived start time but
+  consumes units for videos nobody watches. The player's `preload` defaults to
+  `auto`, so make it a deliberate decision: `preload: 'none'` or `lazy` for
+  players below the fold or behind a click.
+
+## `f_auto` causes a transformation-usage spike, so say so in advance
+
+Introducing `f_auto`, or adding format/codec combinations, forces new derived
+versions to be generated. Expect a visible **spike in transformation usage**,
+especially across a large existing library. It settles once the derivatives
+exist and get reused. Warn the customer *before* the rollout so the bill does
+not surprise them.
+
+## Account-level optimization settings
+
+- **Default automatic format** adds `f_auto` to every delivered video without
+  touching delivery URLs. Because that counts as a transformation, Default video
+  quality also applies. It is available only on plans that use the *video
+  seconds* metric. It is not compatible with strict transformations, and while
+  it is on, eager transformations generated without a format aren't
+  delivered. `fl_original` bypasses it.
+- **Default video quality** lets Cloudinary pick quality and codec (`vc_auto`)
+  automatically. Available on all plans, but **only applies when another
+  transformation is present in the URL**.
+
+## Eager vs on-the-fly
+
+On-the-fly is the default: derivatives build on first request, with no
+preparation and no cost for versions nobody requests. The catch is the first
+viewer. An ordinary video transformation streams while it is generated, so the
+player shows the wrong duration and cannot seek, and async derivations
+(`e_preview`, DASH, 2K/4K `sp_auto`, videos over 30 minutes progressive or
+60 minutes ABR) return 423 until built.
+
+Switch to **eager transformations at upload** (or the explicit method
+afterwards) when a launch or campaign will drive a traffic surge, when videos
+are long or high-resolution (2K/4K), when transformations are slow to build, or
+whenever the first viewer's playback matters. Two rules:
+
+- **`f_auto` in an eager transformation generates nothing.** There is no
+  browser at upload time, so name each format you need instead, with its
+  codec (for example `f_webm,vc_vp9` and `f_mp4,vc_h264`).
+- If you can't pre-generate, add `fl_no_stream` to the delivery URL so
+  Cloudinary waits for the finished file before responding.
+
+## Mobile apps are a different problem
+
+A webview is the web: web rules apply. Native apps use a mobile SDK player (iOS,
+Android, Flutter, React Native) or the app's own player. The SDK players send
+analytics by default and can play `sp_auto` HLS (on by default in Flutter, off
+by default on Android and iOS).
+
+**`f_auto` does not work the same way.** The app must tell Cloudinary what the
+device supports. Detect support at runtime rather than hardcoding it, then
+either name it in the URL:
+
+- Android: `f_webm,vc_vp9`, or `f_mp4,vc_av1` where supported, with
+  `f_mp4,vc_h264` as the fallback
+- iOS: `f_mp4,vc_h265`, or `f_mp4,vc_av1` where supported, with
+  `f_mp4,vc_h264` as the fallback
+
+…or send an `Accept` header (e.g. `video/webm; codecs="vp9"`,
+`video/mp4; codecs="hvc1"`, `video/mp4; codecs="avc1"`). For AV1, use the URL
+form.
+
+**Responsive breakpoints are not supported in the mobile SDKs.** Request
+explicit widths per device instead (`c_limit,w_640` / `w_1280` / `w_1920`), and
+pick the smallest that suits the screen.
+
+## What the player gives you for free
+
+- **Analytics**: collected by default for anything delivered through the
+  player; visible in Console under Video → Analytics, and available via API.
+- **Accessibility**: WCAG 2.1 AA, keyboard navigation, captions/subtitles
+  (existing VTT/SRT or generated transcripts), audio descriptions via text
+  tracks or alternative audio tracks on ABR, and chapters (VTT, manual, or
+  AI-generated).
+- **Customization**: skins, colour schemes, fonts, titles/subtitles display.
+- **Video Player Studio**: a visual configurator that emits the player config,
+  rather than hand-writing it. Also handles transcripts and chapters.
+
+## Validate before launch
+
+Confirm, on representative videos and real devices:
+
+- Delivery URLs are **not** serving originals, and have size limits.
+- The intended optimization approach is actually enabled (check the URL that
+  ships, not the one you wrote).
+- Autoplay/preload behaviour is deliberate.
+- Playback works on target browsers, devices and networks.
+- Captions/subtitles and analytics work where required.
+- The expected initial transformation/delivery usage has been explained.
+
+Then review 2–4 weeks after launch: confirm delivery, check usage and
+transformation patterns, and look for optimization opportunities.
diff --git a/skills/platform/cloudinary-video/references/gotchas.md b/skills/platform/cloudinary-video/references/gotchas.md
new file mode 100644
index 0000000..7153402
--- /dev/null
+++ b/skills/platform/cloudinary-video/references/gotchas.md
@@ -0,0 +1,264 @@
+# Gotchas
+
+Each of these cost real debugging time on a real build. They all look like
+code bugs and none of them are.
+
+## Upload presets can rewrite your assets on ingest
+
+An account can set a **default upload preset** (Console > Settings > Upload)
+that applies to every API upload that doesn't name a preset. If that preset
+carries an **incoming transformation**, it permanently rewrites every uploaded
+asset: resizing it, watermarking it, or both.
+
+Symptom: uploads report success, but stored dimensions are smaller than the file
+you sent, and delivered images carry a watermark.
+
+What does **not** work:
+
+- `upload_preset: ""`: ignored, the preset is still applied
+- an explicit `transformation:` parameter: the upload *response* reports your
+  dimensions while the *stored* asset keeps the preset's
+- `invalidate: true`: this is not a cache problem
+
+What does work: pass an explicit clean preset by name (check what exists on
+the account), change the default upload preset, or clear the offending preset's
+incoming transformation in Console > Settings > Upload.
+
+Note the watermark also **degrades Cloudinary's own AI**. Google Auto Tagging on
+a watermarked image returned 3 tags where the clean original returned 27.
+
+## Re-uploading to the same public ID can keep serving the old file
+
+After you overwrite, rename, or delete an asset, delivered versions can stay
+cached on the CDN for up to 30 days. On one account, a path kept serving the old
+788px watermarked asset after a fresh upload.
+
+Deliver the versioned URL from the upload response (`/v<version>/`), or upload
+with `invalidate: true`. Unsigned uploads never overwrite an existing public ID.
+Verify by fetching the versioned `secure_url` and checking the actual
+dimensions, not the upload response.
+
+## Add-on quotas are small and easy to burn
+
+Free add-on tiers are small monthly quotas, and Image to Video gives a one-time
+trial allocation (16 credits on a Free plan, 32 on a paid plan). Check the
+add-on's page in the Console before looping over an asset list.
+
+Repeated re-uploads to fix something else will exhaust these. Get the upload
+parameters right before running the batch.
+
+## Async AI features can fail or come back empty
+
+`auto_chaptering`, `auto_transcription` and the generated title/description all
+return `status: "pending"` and complete later, **or return `status: "failed"`**.
+
+They need an audio track with speech. With no audio track the request fails;
+with audio but no speech the result is empty. On a 5-second silent clip:
+
+```json
+"auto_chaptering":    { "status": "failed", "data": "Failed to process request" },
+"auto_video_details": { "status": "failed", "data": "Failed to process request" }
+```
+
+Always poll for `complete` and check the output. Never assume.
+
+## HTTP 423 on first request, for async derivations
+
+Async derivations return **423** on the first request until they are built:
+`e_preview`, `g_auto` crops, DASH, `sp_auto` at 2K/4K (`maxres_1440p` or
+`maxres_2160p`), and videos longer than 30 minutes (progressive) or 60 minutes
+(ABR). A default `sp_auto` HLS manifest returns 200. `e_preview` on a 3-minute video took
+minutes. Poll until 200.
+
+For anything going into a launch or a traffic spike, the real fix is **eager
+transformations at upload** rather than warming by polling; see
+[field-guide.md](field-guide.md).
+
+### A 200 is not proof the derivative is complete
+
+The first request for an ordinary video transformation returns **200** and
+streams the video while Cloudinary is still generating it. The player shows the
+wrong duration and cannot seek. Observed on a 14.1-second source: the page
+reported `duration: 2.625`, buffering stopped at 2.24s, and playback refused to
+start. Nothing in the HTTP status said anything was wrong.
+
+Check the headers, not the status code. A still-generating response has no
+`content-length` and `accept-ranges: none`; a finished one has both
+`content-length` and `accept-ranges: bytes`:
+
+```sh
+curl -sI "$URL" | grep -i 'content-length\|accept-ranges'
+```
+
+If you can't generate a video in advance, add `fl_no_stream` to the delivery
+URL: Cloudinary then waits until the video is fully generated before
+responding.
+
+And **re-warm whenever the delivery URLs change.** Warming `sp_auto` does
+nothing for the progressive MP4s you switch to later; each distinct
+transformation is its own derivative. With responsive breakpoints the player
+may request several widths, and with `f_auto` each delivered format is its own
+derivative, so a `curl` may warm a different format than the browser gets.
+
+## Audio-only sources break the video-shaped defaults
+
+An asset with no video track (a podcast, a narration track uploaded as video)
+plays fine through the player as progressive `f_auto:video`, but several
+defaults request things that need frames, and each returns 400:
+
+- `sp_auto`: "sp_auto is not supported with audio only"
+- the auto poster (`so_auto`, `<publicId>.jpg`): "No video stream to convert to image"
+- seek thumbnails (`fl_sprite`), on by default
+
+So for audio only: progressive, no `breakpoints` (every width is an identical
+file), `seekThumbnails: false`, and an explicit poster, for example a waveform
+image (`…/video/upload/fl_waveform,w_1280,h_720/<publicId>.png`). The video.js
+option `audioPosterMode: true` keeps that poster visible during playback.
+`ffprobe -show_streams` tells you which case you have; check it before choosing.
+
+## Video.js rearranges your DOM, and two bugs follow
+
+The Cloudinary player is video.js underneath, which performs DOM surgery on
+init. Two failures come from this and both are silent:
+
+**The original `id` moves to a wrapper div.** After init,
+`document.getElementById('hero')` returns a `<div class="video-js">`, not the
+`<video>`. Attaching media listeners to it does nothing:
+
+```js
+document.getElementById('hero').addEventListener('timeupdate', …) // never fires
+player.on('timeupdate', …)                                        // correct
+```
+
+**An unclosed `<video>` tag swallows everything after it.** HTML parsing puts
+subsequent siblings *inside* the video element, where they never render:
+
+```html
+<video id="hero" class="cld-video-player" playsinline>   <!-- no </video> -->
+<button class="soundbtn">…</button>   <!-- becomes a child of <video> -->
+<div class="overlay">…</div>          <!-- gone: 0×0, never painted -->
+```
+
+The tell is an element measuring 0×0 whose `parentElement` is `VIDEO.vjs-tech`.
+Always close the tag.
+
+## The Cloudinary player proxies only some videojs methods
+
+`player.currentTime()`, `player.play()`, `player.mute()`, `player.unmute()` and
+`player.isMuted()` are Cloudinary player methods. `player.muted()` and
+`player.controls()` are **not**: calling them throws
+`TypeError: player.muted is not a function`, which aborts the rest of your
+click handler and looks like "the button does nothing".
+
+Use `player.mute()` / `player.unmute()`, and reach the underlying videojs player
+for anything else:
+
+```js
+var vjs = window.videojs && window.videojs.getPlayer('hero');
+if (vjs) { try { vjs.controls(true); } catch (e) {} }
+```
+
+Setting `muted`/`volume` directly on the underlying `<video>` element also
+works and is the most robust option.
+
+## Verifying what was actually stored
+
+The upload response can disagree with what is stored and delivered. To check
+real delivered dimensions, fetch the versioned `secure_url` from the upload
+response:
+
+```sh
+curl -s "https://res.cloudinary.com/<cloud>/image/upload/v<version>/<public_id>.jpg" \
+| python3 -c "
+import sys,struct
+d=sys.stdin.buffer.read(); i=2
+while i<len(d)-9:
+    if d[i]==0xFF and d[i+1] in (0xC0,0xC1,0xC2):
+        h,w=struct.unpack('>HH',d[i+5:i+9]); print(f'{w}x{h} {len(d)}B'); break
+    i+=1
+"
+```
+
+For video, `ffprobe` on a downloaded file is the honest check, including
+whether an audio stream exists at all, which decides whether transcription and
+chaptering can work.
+
+## The MCP has no API secret
+
+The agent never holds the API secret when it works through the Cloudinary MCP
+servers, so it can only do what the MCP has a tool for.
+Any other endpoint (a v2 route, a beta API) cannot be signed and returns:
+
+```
+{"error":{"message":"error while authenticating: api_secret not provided"}}
+```
+
+`POST /v2/video/<cloud>/ai_video_analysis` is the common case: no MCP tool, so
+the visual transcription cannot be produced this way at all.
+
+An agent that provisions its own cloud has no such limit. `npx
+@cloudinary/cloud` writes `CLOUDINARY_URL=cloudinary://<key>:<secret>@<cloud>`,
+and every endpoint is reachable with it.
+
+Before concluding a feature is unavailable, check whether it is merely
+unreachable: the two look identical from inside an MCP session.
+
+## Provisioning fails behind a VPN
+
+`npx @cloudinary/cloud` derives the media-delivery allow-list from the source
+IP, and refuses to provision from a private address:
+
+```
+Error: delivery_ips must contain at least one public IP address [delivery_ips_not_public]
+```
+
+A corporate VPN or secure gateway (Cloudflare WARP and similar) triggers this.
+The tool's own guidance says an agent should **report it and let the user
+decide** rather than changing network settings. Pausing the VPN for that one
+command is the fix.
+
+Related, and easy to misdiagnose: **read `delivery_ips` back from the response
+and heed the CLI's mismatch warning.** Behind a VPN or NAT, the API call and
+media delivery can leave from different addresses, and you end up with a cloud
+whose media nothing on this machine can view.
+
+### A VPN toggling *after* provisioning silently kills a working cloud
+
+Worse than the provisioning failure, because it fails late and quietly. The
+cloud is pinned to the IP it was provisioned from, so if the network changes
+(a VPN reconnecting, a gateway rotating its egress, moving to another network),
+every delivery URL starts returning **401**, on a cloud that worked minutes ago.
+
+The tell is *which* requests fail: uploads and Admin API calls keep succeeding,
+because only CDN delivery is IP-restricted. So an agent reports a successful
+upload while every image and video 401s.
+
+```sh
+# 401 on delivery but uploads fine? compare the current egress with the
+# address the cloud was provisioned from
+curl -s https://api.ipify.org
+```
+
+The 401 body says the OAuth token expired, which is misleading: it is an
+allow-list rejection, not an auth problem.
+
+For a demo, keep the VPN off for the **whole session**, not just the
+provisioning command.
+
+## The delivery IP restriction blocks Cloudinary's own fetches
+
+On an unclaimed cloud, `POST /upload` with `file=<a delivery URL on that same
+cloud>` fails with `401 Unauthorized`. Cloudinary's fetcher is not one of the
+allowed delivery IPs. Upload from a local file instead.
+
+Claiming the cloud lifts the restriction entirely.
+
+## Claimable clouds
+
+- Expire **24 hours** after provisioning unless claimed
+- Media delivery is restricted to the IPs in `delivery_ips`; **uploads and API
+  calls are not restricted**, so a wrong IP looks like a working upload with
+  broken media
+- The CLI's default (no `--ip`) locks delivery to the calling address, which is
+  usually correct, so prefer it over guessing
+- Surface the `claim_url` to the user; it is what makes the cloud permanent
diff --git a/skills/platform/cloudinary-video/references/player.md b/skills/platform/cloudinary-video/references/player.md
new file mode 100644
index 0000000..13e434d
--- /dev/null
+++ b/skills/platform/cloudinary-video/references/player.md
@@ -0,0 +1,250 @@
+# Cloudinary Video Player configuration
+
+Verified against `cloudinary-video-player@4.1.0`. Option names come from the
+player API reference, not from memory.
+
+## Use `cloudinary.player()`, not `cloudinary.videoPlayer()`
+
+The 4.1.0 UMD bundle attaches five things to `window.cloudinary`:
+`videoPlayer`, `videoPlayers`, `player`, `players`, `Cloudinary`. Two of those
+construct a player and they are **not** the same function:
+
+| | `cloudinary.videoPlayer()` | `cloudinary.player()` |
+| --- | --- | --- |
+| Status | older constructor | **current**; the bundle tags its own analytics `newPlayerMethod: true` |
+| Returns | the player, synchronously in the UMD full bundle (a buffering proxy via ES import) | a **Promise** resolving to the player |
+| Saved configuration | none, options only | fetches saved config before constructing |
+
+```js
+const player = await cloudinary.player('hero', {
+  cloudName: 'my-cloud',
+  publicId: 'my/public-id',   // also loads the source
+  // …local options win over anything fetched
+});
+```
+
+Because it is async, anything that touches the player (seeking from a
+transcript or a timecode chip) must tolerate being called before it resolves:
+queue the request and replay it on resolve.
+
+### Saved configuration: assets and profiles
+
+Video Player Studio saves settings **onto the video asset** by default. Passing
+`publicId` makes the player retrieve them automatically (requires player
+3.6.0+), so a page can inherit the styling and behaviour someone configured in
+the Studio without hard-coding it.
+
+`profile` loads a stored *profile* instead: either a built-in
+(`cld-default`, `cld-looping`, `cld-adaptive-stream`, `cld-live-streaming`) or
+one saved on the cloud, fetched from
+`/_applet_/video_service/video_player_profiles/<name>.json`.
+
+**Profiles are writable over HTTP, with no console needed.** When the same
+presentation repeats across many assets, that is the signal to create one
+rather than repeat it in page code:
+
+```sh
+# create or update; also GET /player/profiles to list, DELETE to remove
+curl -X PUT https://api.cloudinary.com/v2/video/<cloud>/player/profiles/<name> \
+  -u <key>:<secret> -H "Content-Type: application/json" \
+  -d '{"playerOptions":{…},"sourceOptions":{…}}'
+```
+
+Basic auth with the API key and secret; both `playerOptions` and
+`sourceOptions` are required and take arbitrary player/source keys. Full
+reference: [Video Player profiles](https://cloudinary.com/documentation/video_player_profiles_reference.md?install_source=skillspack&referrer=video-skill)
+
+Precedence, and the trap: **specifying a `profile` overrides the asset's own
+saved settings.** If you want the per-video configuration to apply, do not pass
+a profile. Local options passed at construction beat both.
+
+Profiles deliberately exclude per-embed values: the video's `publicId` and
+`posterOptions` are never part of a profile, so keep passing those yourself.
+
+`cld-looping` is worth knowing: `{fluid, controls:false, muted:true,
+autoplay:true, loop:true}`, the standard hero/background-loop configuration.
+
+**Precedence:** the docs rank it as instance code, then profile, then
+asset-saved settings, then defaults (see
+[Configuration precedence](https://cloudinary.com/documentation/video_player_how_to_embed.md?install_source=skillspack&referrer=video-skill#configuration_precedence)).
+In practice that is two different mechanisms, and getting this wrong leads to
+over-specifying the page defensively:
+
+- **A `profile` replaces the asset's video settings.** It is a substitution:
+  pass one and the per-asset saved configuration no longer supplies the base.
+  So a profile cannot be combined with per-video settings: if some setting
+  genuinely varies per asset, it cannot live behind a profile.
+- **Construction options are additive.** They layer *on top* of whichever base
+  applies and do **not** suppress it. Settings you do not pass keep coming from
+  the asset (or profile), so a page that sets three options still inherits
+  everything else that was saved. The merge is shallow: a local `colors` or
+  `textTracks` object replaces the saved one wholesale.
+
+Practically: save the presentation, pass only what is genuinely page-specific.
+Not because inline options would otherwise clobber the saved config (they
+won't), but because anything inline is a value nobody can change without a
+deploy.
+
+### What the Studio's own embed looks like
+
+Worth calibrating against, because it is the shape Cloudinary steers users to.
+The Studio's Share dialog offers two modes, and neither produces a wall of
+options:
+
+| mode | generated code |
+| --- | --- |
+| **Video settings** (asset-saved) | `cloudinary.player('player', { cloudName, publicId })` |
+| **Profile settings** | `cloudinary.player('player', { cloudName, publicId, profile: 'cld-default' })` |
+
+That is the whole call: `fluid` and the rest of the presentation all live in
+the asset's video settings, not in the page. The profile picker lists the
+cloud's own saved profiles beside the `cld-*` built-ins.
+
+**Configuration belongs on the asset or in a profile, not inline.** This is
+the practice, not a judgement call: presentation saved on the asset can be
+changed by anyone in Studio, while the same values in page code need a deploy.
+Repeat the same presentation across several assets and it should be a profile.
+
+Inline options are not *broken* (they layer on top rather than suppressing
+what was saved), but reach for them only for what genuinely cannot live on the
+asset, and expect that to be close to nothing. The exception is a build with no
+console access and no API secret: nothing can be saved, so inline options are
+the only route. `cloudName` and the `publicId`
+are the call; everything else has a home.
+
+The Studio also has a raw-JS escape hatch, *Advanced config editing*, for
+options not exposed in the Studio UI. Treat hand-written config the same way:
+last resort, for what the supported surface does not cover.
+
+### Saving settings without the console: the Video Config API
+
+Video Player Studio saves settings through the console UI, but the same
+configuration is readable and writable over HTTP, keyed by **`asset_id`** (not
+public ID), with Basic auth:
+
+```sh
+# read
+curl https://api.cloudinary.com/v2/video/<cloud>/player/config/video/<asset_id> \
+  -u <key>:<secret>
+
+# write: PUT REPLACES the whole document; GET, merge, then PUT to patch
+curl -X PUT https://api.cloudinary.com/v2/video/<cloud>/player/config/video/<asset_id> \
+  -u <key>:<secret> -H "Content-Type: application/json" \
+  -d '{"playerOptions":{…},"sourceOptions":{…}}'
+```
+
+`playerOptions` takes constructor keys; `sourceOptions` takes `source()` keys
+(`sourceTypes`, `transformation`, `posterOptions`, `textTracks`). Get the
+`asset_id` from the Admin API: the resource endpoint returns it alongside the
+public ID.
+
+The player reads the same config at delivery time from
+`/_applet_/video_service/video_player_config/video/<type>/<base64(publicId)>.json`
+(observed, undocumented, may change), which is handy for verifying what a page
+will actually receive. **An empty
+`{"playerOptions":{},"sourceOptions":{}}` and HTTP 200 means nothing is saved**:
+the fetch fails silently by design, so a page falls back to its local
+options and looks fine while inheriting nothing.
+
+### Confirming saved config actually applied
+
+Two checks that avoid false alarms:
+
+- The player's analytics beacon to `analytics-api-s.cloudinary.com/video_player_source`
+  (observed, undocumented, may change) spells it out: `newPlayerMethod=true`, `videoConfig=true`, and
+  `fetchedConfig=<comma-separated keys>` listing the `playerOptions` keys that
+  came from the saved config (`sourceOptions` keys are not listed).
+- **Do not test captions with `videoEl.textTracks`**: it reads empty because
+  video.js manages them as *remote* tracks. Use
+  `videojs.getPlayer(id).remoteTextTracks()`.
+
+## Constructor and `source()` options
+
+For every option and its shape, see the
+[Video Player API reference](https://cloudinary.com/documentation/video_player_api_reference.md?install_source=skillspack&referrer=video-skill).
+Options that describe the video (`sourceTypes`, `breakpoints`, `maxDpr`,
+`transformation`, `chapters`, `textTracks`, `posterOptions`, and so on) work on
+`source()` and also on the constructor, where they become defaults every
+`source()` call inherits. Player-only options (`fluid`, `colors`, `controls`,
+`showLogo`, `seekThumbnails`, `chaptersButton`, `aiHighlightsGraph`) belong on
+the constructor. The traps that cost real builds:
+
+- **`sourceTypes`: omit it for progressive delivery.** Setting `['mp4']`
+  replaces the `f_auto:video` default with a pinned extension. Set it only to
+  `['hls']` or `['dash']` for adaptive streaming.
+- **`breakpoints` is progressive-only.** Under `sourceTypes: ['hls']` the
+  streaming profile's ladder governs resolution, and setting `breakpoints` too
+  yields a 400, even when both are set as player options. Constructor values
+  are inherited, so a player built with `breakpoints: true` needs
+  `breakpoints: false` on any ABR `source()` call. See the comparison in
+  [capabilities.md](capabilities.md).
+- **Don't add `streaming_profile` for `sp_auto`.** `sourceTypes: ['hls']` adds
+  it for you. Pass `transformation: { streaming_profile: … }` only to pick a
+  named profile, and keep it alone in its component: combined with a resize or
+  an effect, delivery returns 400.
+- **You do not need to set `maxDpr`.** It is a number from 1.0 to 2.0, default
+  2.0, and enabling `breakpoints` already accounts for the device pixel ratio.
+  Pass a lower number only to deliberately cap DPR. Never pass `true`: it is
+  coerced to 1 and caps DPR at 1x.
+- **`colors.text` must be a light colour.** Player chrome sits over dark video,
+  so a dark text token makes the controls invisible.
+- **`chapters: true` loads `<publicId>-chapters.vtt`**, which is what
+  `auto_chaptering` produces.
+- **Omitting `url` on `textTracks.captions` makes the player use the
+  `.transcript` file** for that public ID. Setting `maxWords` also triggers that
+  lookup. The player fetches it from its own service endpoint, not from
+  `…/raw/upload/<publicId>.transcript`, so a page that also renders the
+  transcript downloads it twice. Translated transcripts live at
+  `<publicId>.<lang>.transcript` and must be passed explicitly. Pair
+  `wordHighlight: true` with `maxWords` so the caption box does not fill;
+  neither works on translated transcripts. `textTracks.options.theme` takes
+  `default`, `videojs-default`, `yellow-outlined`, `player-colors`, or `3d`.
+- **There is no native searchable-transcript panel.** See
+  [build-patterns.md](build-patterns.md).
+- **`interactionAreas` coordinates are percentages** of the video frame, not
+  pixels. Cloudinary does not supply them (see SKILL.md B5).
+- **`preload` defaults to `auto`**, so every non-autoplaying player starts
+  downloading video at load. For players below the fold or behind a click, set
+  `preload: 'none'` or use `lazy` (`cloudinary.player()` only), which shows a
+  lightweight poster until the viewer clicks or scrolls to it. The lazy
+  placeholder ignores `posterOptions` and defaults to the untransformed middle
+  frame (`<publicId>.jpg`, full resolution), so pass an explicit sized `poster`
+  URL such as `…/video/upload/so_auto/c_limit,w_1280/f_auto/q_auto/<publicId>.jpg`.
+- **`seekThumbnails` defaults to `true`, even with `controls: false`.** A
+  decorative loop (including the `cld-looping` profile) still fetches an
+  `fl_sprite` thumbnail track it never shows. Set `seekThumbnails: false` on
+  loops.
+
+## React and other frameworks
+
+Build the `<video>` element imperatively, and route callbacks through refs so
+the effect can have an empty dependency list and build exactly one player for
+the component's lifetime.
+
+Be careful with `dispose()` in effect cleanup. The player finishes initialising
+asynchronously: colors, adaptive streaming and interaction areas are
+lazy-loaded plugins that reach for the element after the effect returns.
+Disposing before they finish (for example, in the extra cleanup React
+StrictMode runs in development) pulls the element out from under them, and
+they throw on a null node (`Invalid target for null#one`,
+`Cannot set properties of null`). Dispose when the component unmounts for good,
+such as on a route change, so players don't leak; the cloudinary-react skill
+shows that cleanup.
+
+## Transformation notes for video
+
+- **The player applies `f_auto:video` itself.** Write format/quality
+  transformations only when you are hand-rolling a native `<video>`; on a
+  player source they are redundant, and pairing them with
+  `sourceTypes:['mp4']` re-adds by hand what forcing MP4 just removed. See
+  [capabilities.md](capabilities.md).
+- Prefer `f_auto/q_auto` as **separate components** over `f_auto,q_auto`.
+  Both are accepted and, as of September 2026, deliver byte-identical results
+  for image and video alike. This is a convention for readability and for
+  matching Cloudinary's own docs, **not** a correctness rule. Do not tell a
+  user the combined form is broken; it is not.
+- `sp_auto` is the streaming profile. It cannot be combined with a resize.
+- `e_preview[:duration_<s>][:max_seg_<n>][:min_seg_dur_<s>]`: AI summary reel,
+  video only, default duration 5.0s.
+- For video, `g_auto` works only with `c_fill` and `c_fill_pad`, once per
+  transformation, and not for positioning overlays.
diff --git a/skills/platform/cloudinary-video/references/upload-and-prepare.md b/skills/platform/cloudinary-video/references/upload-and-prepare.md
new file mode 100644
index 0000000..a4a49f2
--- /dev/null
+++ b/skills/platform/cloudinary-video/references/upload-and-prepare.md
@@ -0,0 +1,158 @@
+# Getting assets onto Cloudinary and ready to play
+
+Use this when the media is not yet on a Cloudinary cloud: provisioning a fresh
+cloud, uploading with the AI features requested on the way in, waiting for the
+async outputs, and warming derived videos before anyone watches.
+
+## Provision a cloud (fresh-cloud destinations only)
+
+```sh
+npx @cloudinary/cloud --goal "<what you are building>" --model <your-model-id>
+```
+
+No signup, no credentials. Writes `CLOUDINARY_URL` to `./.env` and prints a
+**claim URL** a human can open later to keep the account.
+
+- `--ip <address>`: public IP allowed to view delivered media, repeatable, max
+  3. **Leave it off when the user views media from the machine you run on**:
+  the default locks delivery to the calling address. If you run remotely (CI, a
+  cloud agent, a remote dev box), pass the user's public IP instead, because
+  delivery is locked to wherever the media will be *viewed*. Getting this wrong is the main
+  way an upload appears to succeed while every asset returns 401: uploads are
+  never IP-restricted, only CDN delivery.
+- `--json`: machine-readable, including `claim_url` and `expires_at`
+- `--no-env`: print credentials instead of writing `.env`
+
+**The cloud expires 24 hours after provisioning** unless claimed. Surface the
+claim URL at the end; it is what makes the work permanent. Never commit `.env`.
+
+**Provision a new cloud for every test run.** Reusing one skips exactly the work
+most likely to break, because it only breaks the first time: assets are already
+uploaded, async analysis already reports `complete` rather than `pending`, and
+derivations are warm so nothing returns 423. The clouds are free and expire on
+their own. Run each one in a fresh directory (or pass `--force`): the CLI exits
+without provisioning if `.env` already has a `CLOUDINARY_URL`. Provisioning is
+rate-limited per IP.
+
+If provisioning fails with `delivery_ips_not_public`, the connection is behind a
+VPN or secure gateway. That is the user's to resolve; see
+[gotchas.md](gotchas.md).
+
+## Upload, and trigger analysis on the way in
+
+Ask for the AI features **on the upload call**. Re-running them afterwards costs
+a second operation against a quota.
+
+```
+upload video:                    # no add-on needed
+  auto_transcription: true       # transcript + captions
+  auto_chaptering: true          # chapter VTT
+  auto_video_details: true       # title, description, tags (counts 1 tx/second)
+
+then, separately, and tolerate failure:
+  auto_transcription: { translate: ['es','fr'] }   # needs Google Translation
+  categorization: 'google_video_tagging'           # needs that add-on
+```
+
+`translate` is the add-on part, not transcription itself. Requesting
+`auto_transcription` **with** `translate` on a cloud without Google Translation
+fails the **whole** transcription (no transcript, no captions), where plain
+`auto_transcription` would have succeeded.
+
+`auto_video_details` is worth requesting here rather than leaving to the player.
+The player's `title: true` / `description: true` read the asset's context
+metadata and only trigger generation if no value is found, so an
+un-pre-generated title is a request happening for the first time mid-demo.
+
+```
+upload image:                    # no add-on needed
+  (no analysis parameters)
+
+then, separately, and tolerate failure:
+  categorization: 'google_tagging'
+  auto_tagging: 0.65             # needs Google Auto Tagging
+```
+
+Know what image tagging returns before building on it: it describes **what is in
+the frame**. A hotel room yields `bed`, `bedding`, `ceiling`, `lamp`: accurate,
+and not what a guest filters by. Commercial attributes like "ocean view" are not
+visible to an image model. Use it for library search and coverage, not as a
+replacement for curated facets.
+
+### Upload rules that have bitten real runs
+
+1. **Upload with only the free features first.** Requesting a subscribed-only
+   add-on rejects the whole upload (the asset is never stored), which looks
+   like a broken upload rather than a missing entitlement.
+2. **Then try add-ons separately**, and treat failure as expected.
+3. **Add-ons cannot be enabled by an agent.** It is a console action, which on a
+   claimable cloud means claiming it first. No Admin API exists: `/addons`,
+   `/add_ons`, `/subscriptions`, `/entitlements` all 404.
+4. **A default upload preset can rewrite every asset on ingest**, adding a
+   watermark or downsizing, whenever an upload doesn't name a preset. Pass an
+   explicit clean `upload_preset`. See [gotchas.md](gotchas.md).
+5. **Re-uploading to the same public ID can keep serving the old file** from
+   the CDN cache. Deliver the versioned URL from the upload response, or upload
+   with `invalidate: true`.
+
+**Say which features are missing and why.** A run that silently drops translated
+subtitles has misled the user; one that says "translated subtitles need the
+Google Translation add-on, which needs the cloud claimed first" has not.
+
+## Wait for the async features
+
+`auto_transcription`, `auto_chaptering` and title/description return
+`status: "pending"` and finish later, **or return `status: "failed"`**. Poll
+each until `complete`, or pass a `notification_url` to be told when processing
+finishes; never assume success.
+
+```sh
+curl -sf -o /dev/null https://res.cloudinary.com/<cloud>/raw/upload/<public_id>.transcript
+```
+
+They need **an audio track with speech**. With no audio track the request
+fails; with music only or silence the result is empty. Either way there is no
+usable transcript, chapters, or generated title, so check the status and the
+output.
+
+## Generate the derived videos before anyone watches
+
+The first request for a transformed video is the slow one, in one of two ways:
+
+- **Async derivations return HTTP 423** until they are built: `e_preview`,
+  `g_auto` crops, DASH, `sp_auto` at 2K/4K, and videos longer than 30 minutes
+  (progressive) or 60 minutes (ABR). `e_preview` can take minutes.
+- **Everything else returns 200 and streams while it is generated**, so the
+  player shows the wrong duration and cannot seek. A 14-second source played
+  as 2.6 seconds and refused to start, with nothing in the status code to say
+  so.
+
+For production, generate them in advance with **eager transformations at
+upload** (or the explicit method afterwards); see
+[field-guide.md](field-guide.md). Eager with `f_auto` generates nothing, so
+name each format you need, with both the format and the codec (for example
+`f_webm,vc_vp9` and `f_mp4,vc_h264`). If you can't pre-generate, add `fl_no_stream` to the
+delivery URL so Cloudinary waits for the finished file.
+
+For a demo or test cloud, warm each URL instead, then confirm it is complete by
+its headers, not its status. A finished video has `content-length` and
+`accept-ranges: bytes`:
+
+```sh
+UA='Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0 Safari/537.36'
+until curl -sI -A "$UA" "$URL" | grep -qi '^accept-ranges: bytes'; do sleep 5; done
+```
+
+`f_auto` picks the format from the request's `User-Agent` and `Accept`
+headers, so a bare `curl` warms the MP4 while Chrome is served WebM. Send a
+browser's `User-Agent`, and repeat with a Safari one if Safari matters.
+
+Warm the **exact** URLs the player requests, including hover previews and
+sprite sheets. Read them from the browser's network panel rather than building
+them by hand: the player's choices differ in ways that matter, such as a
+`/v1/` segment on some constructions and not others, and a breakpoint width
+(640, 848, 1280, 1920, 2560, or 3840) picked from the container size.
+**Re-warm whenever the delivery URLs change.** Each distinct transformation is
+its own derivative, so warming `sp_auto` does nothing for the progressive MP4s
+you switch to later, responsive breakpoints mean warming a set of widths, and
+with `f_auto` each delivered format is a separate derivative.
diff --git a/skills/cloudinary-video/test/lib.sh b/tests/cloudinary-video/lib.sh
similarity index 75%
rename from skills/cloudinary-video/test/lib.sh
rename to tests/cloudinary-video/lib.sh
index 074df70..644a459 100644
--- a/skills/cloudinary-video/test/lib.sh
+++ b/tests/cloudinary-video/lib.sh
@@ -1,26 +1,27 @@
 # Shared assertion helpers. Sourced by the test scripts.
 
-PASS=0; FAIL=0
+PASS=0; FAIL=0; SKIP=0
 
 _ok()   { PASS=$((PASS+1)); printf '  \033[32m✓\033[0m %s\n' "$1"; }
 _no()   { FAIL=$((FAIL+1)); printf '  \033[31m✗\033[0m %s\n' "$1"; [ -n "$2" ] && printf '      %s\n' "$2"; }
+_skip() { SKIP=$((SKIP+1)); printf '  \033[33m-\033[0m %s (skipped)\n' "$1"; [ -n "${2:-}" ] && printf '      %s\n' "$2"; }
 
 section() { printf '\n\033[1m%s\033[0m\n' "$1"; }
 
-# status <label> <url> [expected]   — assert an HTTP status
+# status <label> <url> [expected]   : assert an HTTP status
 status() {
   local label=$1 url=$2 want=${3:-200} got
   got=$(curl -s -o /dev/null -w '%{http_code}' -L --max-time 60 "$url")
-  [ "$got" = "$want" ] && _ok "$label" || _no "$label" "want $want, got $got — $url"
+  [ "$got" = "$want" ] && _ok "$label" || _no "$label" "want $want, got $got: $url"
 }
 
-# body_has <label> <url> <substring>   — assert response contains text
+# body_has <label> <url> <substring>   : assert response contains text
 body_has() {
   local label=$1 url=$2 needle=$3
   if curl -s -L --max-time 60 "$url" | grep -q -- "$needle"; then
     _ok "$label"
   else
-    _no "$label" "missing '$needle' — $url"
+    _no "$label" "missing '$needle': $url"
   fi
 }
 
@@ -47,10 +48,10 @@ except Exception as e: print(f'<{e}>')
   [ "$got" = "$want" ] && _ok "$label" || _no "$label" "want $want, got $got"
 }
 
-# summary — print the tally and EXIT. Always exits, so it doubles as the
+# summary: print the tally and EXIT. Always exits, so it doubles as the
 # early-return for a script that has hit a blocking condition (no cloud, no
 # credentials) and cannot meaningfully continue.
 summary() {
-  printf '\n%s passed, %s failed\n' "$PASS" "$FAIL"
+  printf '\n%s passed, %s failed, %s skipped\n' "$PASS" "$FAIL" "$SKIP"
   [ "$FAIL" -eq 0 ] && exit 0 || exit 1
 }
diff --git a/skills/cloudinary-video/test/skill-claims.sh b/tests/cloudinary-video/skill-claims.sh
similarity index 63%
rename from skills/cloudinary-video/test/skill-claims.sh
rename to tests/cloudinary-video/skill-claims.sh
index 1f135d9..33292d3 100755
--- a/skills/cloudinary-video/test/skill-claims.sh
+++ b/tests/cloudinary-video/skill-claims.sh
@@ -2,22 +2,25 @@
 # Assert the factual claims the cloudinary-video skill makes.
 #
 # A skill that is confidently wrong is worse than one that is silent, and these
-# claims are the load-bearing ones — an agent following them will not
+# claims are the load-bearing ones: an agent following them will not
 # second-guess them. Every check here maps to a specific line of guidance, and
 # a failure means the SKILL is stale, not that the code is broken.
 #
 # Two modes:
 #
-#   ./skills/cloudinary-video/test/skill-claims.sh
+#   ./tests/cloudinary-video/skill-claims.sh
 #                                          # claims checkable without credentials
-#   ./skills/cloudinary-video/test/skill-claims.sh --cloud
+#   ./tests/cloudinary-video/skill-claims.sh --cloud
 #                                          # also provision a fresh cloud and
 #                                          # assert the upload/add-on claims
 #
-# --cloud takes a few minutes and needs the VPN paused. It also uploads two
-# media fixtures that are not vendored here (they are large); set MEDIA_DIR to
-# a directory holding CR-OCS-001.jpg and hero-tour.mp4 — they live in docs/media
-# of CloudinaryLtd/cloudinary-video-skill, where this skill is developed.
+# The default mode runs against Cloudinary's public `demo` cloud. Two checks
+# (chapters VTT and translated transcript paths) need a cloud that holds those
+# files; set FEATURE_CLOUD and FEATURE_ID to one, or they are skipped.
+#
+# --cloud takes a few minutes and needs any VPN paused. It uploads two media
+# files that are not vendored here: set TEST_IMAGE to any JPEG and TEST_VIDEO
+# to an MP4 of at least 15 seconds with clear speech.
 
 set -uo pipefail
 cd "$(dirname "$0")" || exit 1
@@ -26,21 +29,23 @@ cd "$(dirname "$0")" || exit 1
 WITH_CLOUD=0
 [ "${1:-}" = "--cloud" ] && WITH_CLOUD=1
 
-# --cloud uploads real media. The fixtures are too large to vendor into a skills
-# repo, so point MEDIA_DIR at a checkout that has them.
-MEDIA_DIR=${MEDIA_DIR:-}
+# --cloud uploads real media, which is too large to vendor into a skills repo.
+TEST_IMAGE=${TEST_IMAGE:-}
+TEST_VIDEO=${TEST_VIDEO:-}
 if [ "$WITH_CLOUD" = "1" ]; then
-  for f in CR-OCS-001.jpg hero-tour.mp4; do
-    [ -f "$MEDIA_DIR/$f" ] || {
-      echo "--cloud needs $f. Set MEDIA_DIR to a directory containing the" >&2
-      echo "fixtures (docs/media in CloudinaryLtd/cloudinary-video-skill)." >&2
-      exit 1
-    }
-  done
+  [ -f "$TEST_IMAGE" ] && [ -f "$TEST_VIDEO" ] || {
+    echo "--cloud needs TEST_IMAGE (any JPEG) and TEST_VIDEO (an MP4 of at" >&2
+    echo "least 15 seconds with clear speech) set to existing files." >&2
+    exit 1
+  }
 fi
 
-SKILL=..
-DEMO_CLOUD=dxuiuruim   # a claimed cloud with the full feature set present
+SKILL=../../skills/platform/cloudinary-video
+PUB=https://res.cloudinary.com/demo   # Cloudinary's public demo cloud
+VID=dog                               # a short public video on it
+TRANSCRIPT=docs/nanotech              # a public audio-only asset with a .transcript
+FEATURE_CLOUD=${FEATURE_CLOUD:-}      # optional: a cloud with chapters and an
+FEATURE_ID=${FEATURE_ID:-}            # .es.transcript for FEATURE_ID
 
 http() { curl -s -o /dev/null -w '%{http_code}' -L --max-time 60 "$1"; }
 
@@ -52,59 +57,69 @@ claim() { [ "$2" = "yes" ] && _ok "$1" || _no "$1" "$3"; }
 
 section "Transformation claims (SKILL.md B2, capabilities.md)"
 
-# "breakpoints/resize cannot be combined with sp_auto — Cloudinary rejects it"
-CODE=$(http "https://res.cloudinary.com/$DEMO_CLOUD/video/upload/c_limit,w_2560/sp_auto/costera/hero-tour.m3u8")
-[ "$CODE" != "200" ] \
-  && _ok "resize + sp_auto is rejected ($CODE)" \
-  || _no "resize + sp_auto was ACCEPTED" "SKILL says rejected; guidance is stale"
+# "breakpoints/resize cannot be combined with sp_auto: Cloudinary rejects it"
+ERR=$(curl -s -D - -o /dev/null --max-time 60 "$PUB/video/upload/c_limit,w_2560/sp_auto/$VID.m3u8" | tr -d '\r')
+if echo "$ERR" | grep -q '^HTTP/[0-9.]* 400' && echo "$ERR" | grep -qi 'resize is only supported for overlay'; then
+  _ok "resize + sp_auto is rejected (400, resize is only supported for overlay)"
+else
+  _no "resize + sp_auto was not rejected as documented" "$(echo "$ERR" | grep -i '^HTTP\|x-cld-error')"
+fi
 
 # "Prefer f_auto/q_auto separate; the combined form is a convention, NOT a
 #  correctness rule." Assert the equivalence, so that if Cloudinary ever does
 #  start rejecting the combined form the guidance gets revisited.
-SEP=$(http "https://res.cloudinary.com/$DEMO_CLOUD/video/upload/f_auto/q_auto/costera/hero-tour.mp4")
-JOINT=$(http "https://res.cloudinary.com/$DEMO_CLOUD/video/upload/f_auto,q_auto/costera/hero-tour.mp4")
+SEP=$(http "$PUB/video/upload/f_auto/q_auto/$VID.mp4")
+JOINT=$(http "$PUB/video/upload/f_auto,q_auto/$VID.mp4")
 claim "f_auto/q_auto (separate) delivers ($SEP)" \
   "$([ "$SEP" = "200" ] && echo yes || echo no)" "expected 200, got $SEP"
 if [ "$JOINT" = "200" ]; then
   # Same bytes? Then they are genuinely interchangeable and player.md is right
   # to call it a convention rather than a rule.
-  L1=$(curl -s -o /dev/null -w '%{size_download}' -L --max-time 60 "https://res.cloudinary.com/$DEMO_CLOUD/video/upload/f_auto/q_auto/costera/hero-tour.mp4")
-  L2=$(curl -s -o /dev/null -w '%{size_download}' -L --max-time 60 "https://res.cloudinary.com/$DEMO_CLOUD/video/upload/f_auto,q_auto/costera/hero-tour.mp4")
+  L1=$(curl -s -o /dev/null -w '%{size_download}' -L --max-time 60 "$PUB/video/upload/f_auto/q_auto/$VID.mp4")
+  L2=$(curl -s -o /dev/null -w '%{size_download}' -L --max-time 60 "$PUB/video/upload/f_auto,q_auto/$VID.mp4")
   [ "$L1" = "$L2" ] \
-    && _ok "f_auto,q_auto (combined) is equivalent — convention, not a rule" \
+    && _ok "f_auto,q_auto (combined) is equivalent: convention, not a rule" \
     || _no "combined form delivers different bytes ($L1 vs $L2)" "player.md claims equivalence"
 else
-  _no "f_auto,q_auto combined now returns $JOINT" "player.md says both are accepted — guidance is stale"
+  _no "f_auto,q_auto combined now returns $JOINT" "player.md says both are accepted, so guidance is stale"
 fi
 
 # "sp_auto returns a manifest with a rendition ladder"
 body_has "sp_auto manifest lists renditions" \
-  "https://res.cloudinary.com/$DEMO_CLOUD/video/upload/sp_auto/costera/hero-tour.m3u8" "RESOLUTION="
+  "$PUB/video/upload/sp_auto/$VID.m3u8" "RESOLUTION="
 
-# "breakpoints is mutually exclusive with sp_auto at EVERY width — the skill
+# "breakpoints is mutually exclusive with sp_auto at EVERY width; the skill
 #  says verified 640..2560, so verify it rather than trusting one sample."
 BP_OK=yes
 for w in 640 1280 1920 2560; do
-  C=$(http "https://res.cloudinary.com/$DEMO_CLOUD/video/upload/c_limit,w_$w/sp_auto/costera/hero-tour.m3u8")
-  [ "$C" = "200" ] && BP_OK="w=$w accepted ($C)"
+  C=$(http "$PUB/video/upload/c_limit,w_$w/sp_auto/$VID.m3u8")
+  [ "$C" != "400" ] && BP_OK="w=$w returned $C, not 400"
 done
 claim "resize+sp_auto rejected at every width (640-2560)" \
   "$([ "$BP_OK" = "yes" ] && echo yes || echo no)" \
-  "$BP_OK — capabilities.md claims all widths are rejected"
+  "$BP_OK, but capabilities.md claims all widths are rejected"
 
 # "progressive accepts the same widths breakpoints would pick between"
 PROG_OK=yes
 for w in 640 1280 1920; do
-  C=$(http "https://res.cloudinary.com/$DEMO_CLOUD/video/upload/c_limit,w_$w/f_auto/q_auto/costera/hero-tour.mp4")
+  C=$(http "$PUB/video/upload/c_limit,w_$w/f_auto/q_auto/$VID.mp4")
   [ "$C" != "200" ] && PROG_OK="w=$w failed ($C)"
 done
 claim "progressive path accepts explicit widths" \
   "$([ "$PROG_OK" = "yes" ] && echo yes || echo no)" "$PROG_OK"
 
+# "Audio-only sources: sp_auto returns 400" (gotchas.md)
+AUD=$(curl -s -D - -o /dev/null --max-time 60 "$PUB/video/upload/sp_auto/$TRANSCRIPT.m3u8" | tr -d '\r')
+if echo "$AUD" | grep -q '^HTTP/[0-9.]* 400' && echo "$AUD" | grep -qi 'audio only'; then
+  _ok "sp_auto on an audio-only source is rejected (400, audio only)"
+else
+  _no "sp_auto on an audio-only source was not rejected as documented" "$(echo "$AUD" | grep -i '^HTTP\|x-cld-error')"
+fi
+
 section "Async output shape claims (build-patterns.md)"
 
 # "<publicId>.transcript is Cloudinary JSON, not WebVTT"
-SHAPE=$(curl -s -L --max-time 60 "https://res.cloudinary.com/$DEMO_CLOUD/raw/upload/costera/hero-tour.transcript" \
+SHAPE=$(curl -s -L --max-time 60 "$PUB/raw/upload/$TRANSCRIPT.transcript" \
   | python3 -c "
 import sys,json
 raw=sys.stdin.read()
@@ -115,21 +130,25 @@ print('json-words' if (isinstance(d,list) and d and d[0].get('words')) else 'jso
 " 2>/dev/null)
 claim "transcript is JSON with word-level timings" \
   "$([ "$SHAPE" = "json-words" ] && echo yes || echo no)" \
-  "got '$SHAPE' — build-patterns.md relies on words[].start_time"
-
-# "auto_chaptering produces <publicId>-chapters.vtt, and it IS WebVTT"
-body_has "chapters file is WebVTT at <id>-chapters.vtt" \
-  "https://res.cloudinary.com/$DEMO_CLOUD/raw/upload/costera/hero-tour-chapters.vtt" "WEBVTT"
-
-# "translated transcripts live at <publicId>.<lang>.transcript"
-status "translated transcript path (.es.transcript)" \
-  "https://res.cloudinary.com/$DEMO_CLOUD/raw/upload/costera/hero-tour.es.transcript"
+  "got '$SHAPE', but build-patterns.md relies on words[].start_time"
+
+# "auto_chaptering produces <publicId>-chapters.vtt, and it IS WebVTT" and
+# "translated transcripts live at <publicId>.<lang>.transcript". No public
+# asset carries these, so they need FEATURE_CLOUD and FEATURE_ID.
+if [ -n "$FEATURE_CLOUD" ] && [ -n "$FEATURE_ID" ]; then
+  body_has "chapters file is WebVTT at <id>-chapters.vtt" \
+    "https://res.cloudinary.com/$FEATURE_CLOUD/raw/upload/$FEATURE_ID-chapters.vtt" "WEBVTT"
+  status "translated transcript path (.es.transcript)" \
+    "https://res.cloudinary.com/$FEATURE_CLOUD/raw/upload/$FEATURE_ID.es.transcript"
+else
+  _skip "chapters VTT and translated transcript paths" "set FEATURE_CLOUD and FEATURE_ID to check them"
+fi
 
 section "Player transcript-support claims (build-patterns.md, player.md)"
 
 # The player consumes .transcript natively (maxWords triggers the lookup,
 # wordHighlight uses the word timings). What it does NOT have is a searchable
-# transcript panel. Both halves are documented, so both are asserted — the
+# transcript panel. Both halves are documented, so both are asserted; the
 # second as a doc check, since absence of an option cannot be probed by curl.
 file_has "maxWords documented as the .transcript trigger" \
   "$SKILL/references/player.md" "maxWords"
@@ -144,26 +163,13 @@ section "Player distribution claims (SKILL.md B3)"
 
 # The script-tag URLs the skill tells people to use must actually resolve.
 status "player JS at the pinned version" \
-  "https://unpkg.com/cloudinary-video-player/dist/cld-video-player.min.js"
+  "https://unpkg.com/cloudinary-video-player@4.1.0/dist/player.min.js"
 status "player CSS at the pinned version" \
-  "https://unpkg.com/cloudinary-video-player/dist/cld-video-player.min.css"
-
-section "Source-platform claims (source-platforms.md)"
-
-# "The YouTube Data API cannot download source files." Asserting a negative
-# against a live API needs credentials, so this checks the weaker but still
-# useful thing: that the doc records it as a hard stop with a human fallback,
-# so an agent does not burn a run retrying.
-file_has "YouTube recorded as having no API path" \
-  "$SKILL/references/source-platforms.md" "No API path"
-file_has "Brightcove /sources trap is called out" \
-  "$SKILL/references/source-platforms.md" "returns \*\*transcoded renditions\*\*"
-file_has "Vimeo original field marked unverified" \
-  "$SKILL/references/source-platforms.md" "does not state which field"
+  "https://unpkg.com/cloudinary-video-player@4.1.0/dist/player.min.css"
 
 section "Internal consistency"
 
-for f in capabilities.md build-patterns.md source-platforms.md player.md gotchas.md; do
+for f in capabilities.md build-patterns.md field-guide.md player.md gotchas.md upload-and-prepare.md; do
   [ -f "$SKILL/references/$f" ] && _ok "reference exists: $f" || _no "missing reference: $f"
 done
 
@@ -182,10 +188,10 @@ fi
 section "Provision a throwaway cloud"
 RESP=$(npx --yes @cloudinary/cloud --json --no-env \
   --goal "assert the factual claims in the cloudinary-video skill" \
-  --model claude-opus-5 2>&1 | sed -n '/^{/,$p')
+  ${MODEL:+--model "$MODEL"} 2>&1 | sed -n '/^{/,$p')
 
 if echo "$RESP" | grep -q delivery_ips_not_public; then
-  _no "provision" "behind a VPN — pause it and rerun"
+  _no "provision" "behind a VPN: pause it and rerun"
   summary
 fi
 
@@ -199,7 +205,7 @@ print(f'CLAIM=\"{d[\"claim_url\"]}\"')
 
 API="https://api.cloudinary.com/v1_1/$CLOUD"
 
-section "Entitlement-API claims (SKILL.md A4, capabilities.md)"
+section "Entitlement-API claims (upload-and-prepare.md, capabilities.md)"
 
 # "There is no Admin API for add-ons: /addons, /add_ons, /subscriptions and
 #  /entitlements all 404."
@@ -210,13 +216,13 @@ for ep in addons add_ons subscriptions entitlements; do
     || _no "/$ep returned $C, not 404" "capabilities.md says no entitlement API exists"
 done
 
-section "Add-on failure-mode claims (SKILL.md A4)"
+section "Add-on failure-mode claims (upload-and-prepare.md)"
 
 # THE load-bearing claim: "requesting a subscribed-only add-on rejects the
-# WHOLE upload — the asset is never stored". If this ever degrades gracefully
+# WHOLE upload (the asset is never stored)". If this ever degrades gracefully
 # instead, the upload-free-features-first rule becomes unnecessary.
 PROBE=$(curl -s "$API/image/upload" -u "$KEY:$SEC" \
-  -F "file=@$MEDIA_DIR/CR-OCS-001.jpg" -F "public_id=claims/addon_probe" \
+  -F "file=@$TEST_IMAGE" -F "public_id=claims/addon_probe" \
   -F "categorization=google_tagging")
 if echo "$PROBE" | grep -qi "subscription"; then
   _ok "add-on request rejected with a subscription error"
@@ -233,9 +239,9 @@ fi
 
 # "auto_transcription WITH translate fails the whole transcription on a cloud
 #  without Google Translation, where plain auto_transcription succeeds."
-section "Translate-is-the-add-on-part claim (SKILL.md A4)"
+section "Translate-is-the-add-on-part claim (upload-and-prepare.md)"
 T=$(curl -s "$API/video/upload" -u "$KEY:$SEC" \
-  -F "file=@$MEDIA_DIR/hero-tour.mp4" -F "public_id=claims/translate_probe" \
+  -F "file=@$TEST_VIDEO" -F "public_id=claims/translate_probe" \
   -F "auto_transcription[translate][]=es")
 if echo "$T" | grep -qi "subscription\|translation"; then
   _ok "auto_transcription+translate rejected without the add-on"
@@ -244,13 +250,13 @@ else
   printf '      response: %s\n' "$(echo "$T" | head -c 160)"
 fi
 
-section "Free-feature claims (SKILL.md A4 table)"
+section "Free-feature claims (SKILL.md A2)"
 FREE=$(curl -s "$API/video/upload" -u "$KEY:$SEC" \
-  -F "file=@$MEDIA_DIR/hero-tour.mp4" -F "public_id=claims/free_probe" \
+  -F "file=@$TEST_VIDEO" -F "public_id=claims/free_probe" \
   -F "auto_transcription=true" -F "auto_chaptering=true" -F "auto_video_details=true")
 if echo "$FREE" | grep -q '"public_id"'; then
   _ok "auto_transcription + auto_chaptering + auto_video_details accepted on a fresh cloud"
-  # "They return status: pending and finish later" — assert pending, not done.
+  # "They return status: pending and finish later": assert pending, not done.
   PEND=$(echo "$FREE" | python3 -c "
 import sys,json
 d=json.load(sys.stdin); i=d.get('info',{})
@@ -268,9 +274,12 @@ fi
 
 section "Unclaimed-cloud remote-fetch claim (gotchas.md)"
 # "On an unclaimed cloud, POST /upload with file=<a delivery URL on that same
-#  cloud> fails 401 — Cloudinary's fetcher is not an allowed delivery IP."
+#  cloud> fails 401: Cloudinary's fetcher is not an allowed delivery IP."
+# Upload a plain image first so the fetch targets an asset that exists.
+curl -s -o /dev/null "$API/image/upload" -u "$KEY:$SEC" \
+  -F "file=@$TEST_IMAGE" -F "public_id=claims/plain"
 RF=$(curl -s "$API/image/upload" -u "$KEY:$SEC" \
-  -F "file=https://res.cloudinary.com/$CLOUD/image/upload/claims/addon_probe.jpg" \
+  -F "file=https://res.cloudinary.com/$CLOUD/image/upload/claims/plain.jpg" \
   -F "public_id=claims/remote_fetch_probe")
 if echo "$RF" | grep -qi "401\|unauthor\|not allowed"; then
   _ok "remote fetch of own delivery URL fails on an unclaimed cloud"
@@ -279,5 +288,5 @@ else
   printf '      response: %s\n' "$(echo "$RF" | head -c 160)"
 fi
 
-printf '\n\033[1mThrowaway cloud\033[0m %s — expires in 24h, claim only if you want it:\n  %s\n' "$CLOUD" "$CLAIM"
+printf '\n\033[1mThrowaway cloud\033[0m %s expires in 24h; claim only if you want it:\n  %s\n' "$CLOUD" "$CLAIM"
 summary

From 5eb6bf5fa6f821b915202ee0aa31aa583a59bcfd Mon Sep 17 00:00:00 2001
From: Ebenezer Don <ebenezer.don@cloudinary.com>
Date: Thu, 8 Oct 2026 12:22:16 +0100
Subject: [PATCH 3/3] Correct cloudinary-video claims found in a second
 fact-check

- Switching one player between progressive and ABR: the breakpoint resize
  stays in the player's transformation, so breakpoints: false alone still
  returns 400. Recommend separate players, and give the reset that works
  (player.transformation({}) plus breakpoints: false), verified in a browser.
- Player facts from the 4.1.0 source: preload defaults to metadata, lazy
  resolves to a placeholder until loadPlayer(), controls() is a wrapper
  method, which bundles construct synchronously, and colors.text must contrast
  with colors.base.
- Captions and tracks: translations need only a language, audio description
  goes in a descriptions track, and Studio transcripts can be uploaded only
  for translations.
- Delivery: use f_auto:video in the native fallback (matching
  cloudinary-transformations), the combined f_auto,q_auto can encode
  differently, e_preview fails on very short sources, eager isn't supported
  with Optimize by default, and auto_video_details isn't supported by the
  SDKs or the MCP.
- Remove undocumented internal endpoints, the unverified quota numbers, the
  "how much is verified" section, and demo-specific wording; reconcile the
  React guidance with cloudinary-react; make Phase headings H2.
- Make the warming loop stop on real errors and report a timeout, and test
  that both f_auto forms are accepted rather than byte-identical.
---
 skills/platform/cloudinary-video/SKILL.md     | 118 +++++++++---------
 .../references/build-patterns.md              |  37 +++---
 .../references/capabilities.md                |  45 +++----
 .../references/field-guide.md                 |  13 +-
 .../cloudinary-video/references/gotchas.md    |  32 ++---
 .../cloudinary-video/references/player.md     |  82 ++++++------
 .../references/upload-and-prepare.md          |  17 ++-
 tests/cloudinary-video/skill-claims.sh        |  18 +--
 8 files changed, 180 insertions(+), 182 deletions(-)

diff --git a/skills/platform/cloudinary-video/SKILL.md b/skills/platform/cloudinary-video/SKILL.md
index 5cb4a3a..53f5c45 100644
--- a/skills/platform/cloudinary-video/SKILL.md
+++ b/skills/platform/cloudinary-video/SKILL.md
@@ -40,10 +40,14 @@ should:
    `f_auto`, `q_auto`, `sp_auto`, or widths in `transformation:`, and no
    `sourceTypes: ['mp4']`. The player already applies `f_auto:video`.
 4. **Construct with `cloudinary.player()`, not `cloudinary.videoPlayer()`**, and
-   queue seeks until its Promise resolves. See [B3](#b3-load-and-configure-the-player).
+   queue seeks until its Promise resolves. In React or Next.js, take the
+   mounting pattern from the cloudinary-react or cloudinary-next skill, but
+   keep `cloudinary.player()` and the dispose guidance in references/player.md.
+   See [B3](#b3-load-and-configure-the-player).
 5. **Request `auto_transcription`, `auto_chaptering`, and `auto_video_details`
-   on the upload call** (REST or a preset: the MCP and SDKs may not pass
-   `auto_video_details`), and request add-on features in a separate call.
+   on the upload call**, and request add-on features in a separate call.
+   `auto_video_details` isn't supported by the SDKs or the MCP, so send it
+   through the REST API or an upload preset.
 6. **Pre-generate derived videos when the first viewer matters**: eager
    transformations at upload (the explicit method for existing assets), or
    warmed URLs on a test cloud. Otherwise the first request streams with the
@@ -134,9 +138,9 @@ Two rules still apply when the files come from one:
 
 ---
 
-# Phase A: get the assets onto Cloudinary
+## Phase A: get the assets onto Cloudinary
 
-## A1. Provision a cloud (fresh-cloud destinations only)
+### A1. Provision a cloud (fresh-cloud destinations only)
 
 Run `npx @cloudinary/cloud --goal "<what you are building>" --model <your-model-id>`.
 It needs no signup, writes `CLOUDINARY_URL` to `./.env`, and prints a **claim
@@ -145,7 +149,7 @@ the claim URL at the end. Leave `--ip` off when the user views media from
 the machine you run on; if you run remotely (CI, a cloud agent), pass the
 user's public IP. Provision a new cloud for every test run.
 
-## A2. Upload, and request the AI features on the way in
+### A2. Upload, and request the AI features on the way in
 
 Upload video with the free features on the same call: `auto_transcription`,
 `auto_chaptering`, and `auto_video_details`. Request add-on features
@@ -153,13 +157,14 @@ Upload video with the free features on the same call: `auto_transcription`,
 separate call and treat failure as expected. Asking for an add-on the cloud
 lacks fails the whole upload, or the whole transcription.
 
-## A3. Wait for the async features
+### A3. Wait for the async features
 
 Transcripts, chapters, and generated titles return `pending` and finish later,
-or fail. Poll each until `complete`. They need real speech: silent or
-music-only video produces none of them.
+or fail. Poll each until `complete`. They need an audio track with speech:
+silent or music-only video gives empty results (a transcript may hold a short,
+low-confidence spurious phrase).
 
-## A4. Generate derived videos before anyone watches
+### A4. Generate derived videos before anyone watches
 
 The first request for a transformed video is the slow one. Ordinary
 transformations return 200 but stream while they are generated, so the player
@@ -175,7 +180,7 @@ each step.
 
 ---
 
-# Phase B: build the site
+## Phase B: build the site
 
 **Read [references/field-guide.md](references/field-guide.md) alongside this.**
 It carries Cloudinary's own delivery best practices: the duration-based
@@ -184,7 +189,7 @@ delivery cheat sheet, the optimizations customers most often miss, the
 mobile-app delivery, and the pre-launch validation checklist. Phase B below is
 how to build; the field guide is what "built well" means.
 
-## B1. Resolve what this cloud can actually do
+### B1. Resolve what this cloud can actually do
 
 Before writing page code, settle the capability set: one explicit flag map,
 with a fallback per feature. This is what keeps a page honest on a cloud without
@@ -194,17 +199,19 @@ add-ons instead of rendering empty rails and dead caption buttons.
 will be absent every time, and that is correct rather than a regression.
 
 **On a customer cloud**, probe: attempt the operation on **one** asset and read
-the result. Never loop the catalogue: free tiers are small (Google Auto Tagging
-50/month, Video Tagging 5/month) and on a customer cloud quota is their money.
+the result. Never loop the catalogue: free add-on tiers are small, and on a
+customer cloud quota is their money. Before generating AI features across a
+library, say what it costs (`auto_video_details`, for example, counts one
+transformation per second of video).
 
 The full matrix, the detection rules, and the **MCP vs `CLOUDINARY_URL` routing
 table** are in [references/capabilities.md](references/capabilities.md). The
-routing matters concretely: `ai_video_analysis` has no MCP tool and cannot be
-signed without an API secret, so on an MCP-only build the audio description
+routing matters concretely: `ai_video_analysis` has no MCP tool and requires
+the API secret, so on an MCP-only build the audio description
 track is unavailable, and generated titles need a preset that sets
 `auto_video_details`. Everything else is reachable either way.
 
-## B2. Choose the optimization strategy
+### B2. Choose the optimization strategy
 
 An explicit decision, not a default. Retrofitting the other one means rewiring
 the player.
@@ -234,7 +241,7 @@ the file:
 | **No audio track** | background/ambient, and almost always short and autoplaying | **progressive** |
 | **Audio but no speech** (music-only) | montage or mood piece, not something followed | **progressive** |
 | **Portrait 9:16 or square** | social/short-form | **progressive** |
-| **Under ~30s** | over before a ladder could switch; never ABR | **progressive** |
+| **Under ~1 min** (never ABR under 30s) | over before a ladder could switch | **progressive** |
 | **Speech, over ~1 min, viewer-pressed play** | content: a talk, explainer, interview, course | **ABR** |
 | **No video track** (audio only) | `sp_auto`, posters and seek thumbnails return 400 | **progressive**, no `breakpoints`; see gotchas.md |
 
@@ -275,7 +282,7 @@ The measured URLs are in [references/capabilities.md](references/capabilities.md
 If the player cannot be used at all, use a native `<video>` with
 media-queried `<source>`s (see the same reference).
 
-### Configure the player; do not hand-write its delivery transformation
+#### Configure the player; do not hand-write its delivery transformation
 
 The player composes the delivery transformation from its options. Anything you
 write into `transformation:` that an option already covers lands in the *same*
@@ -287,7 +294,7 @@ component: redundant at best, and a 400 for `streaming_profile`.
 player.source(id, { sourceTypes: ['hls'],
   transformation: { streaming_profile: 'auto', effect: 'vignette:50' } });
 // RIGHT: sourceTypes adds sp_auto itself
-cloudinary.player(el, { sourceTypes: ['hls'] });   // → sp_auto/<id>.m3u8
+cloudinary.player(el, { cloudName, publicId, sourceTypes: ['hls'] }); // → sp_auto/<id>.m3u8
 ```
 
 `sp_auto` also accepts only a [limited set of other transformations](https://cloudinary.com/documentation/adaptive_bitrate_streaming.md?install_source=skillspack&referrer=video-skill#combining_transformations_with_automatic_streaming_profile_selection),
@@ -298,18 +305,22 @@ previews, `e_preview` teasers, and the native `<video>` fallback. `breakpoints`
 belongs to the progressive branch only. Set it under ABR and delivery returns
 400 (*resize is only supported for overlay*).
 
-`breakpoints` and `sourceTypes` work on the constructor and on each
-`source()` call, and constructor values are inherited by every `source()`
-call. So a page moving a viewer between a progressive and an ABR asset sets
-both explicitly per call, for example
-`player.source(id, { sourceTypes: ['hls'], breakpoints: false })`. Leaving the
-inherited value in place carries the wrong option across.
+**Use a separate player per strategy.** To switch one player instead, dispose
+it and build a new one on a fresh `<video>` element (`dispose()` removes the
+element), or reset it as below. Once
+a player has delivered a progressive source with `breakpoints`, it keeps that
+resize in its own transformation and adds it to later sources, so a following
+ABR source requests `c_limit,w_…/sp_auto` and fails with 400, even with
+`breakpoints: false` on the call. If one player must switch, call
+`player.transformation({})` and pass `{ sourceTypes: ['hls'], breakpoints: false }`
+before an ABR source, and `{ sourceTypes: ['auto'], breakpoints: true }`
+before a progressive one.
 
 Most pages want both, on **different** sources: ABR for the tour, progressive
 for the loops. Full comparison table in
 [references/capabilities.md](references/capabilities.md).
 
-## B3. Load and configure the player
+### B3. Load and configure the player
 
 Install from npm and use the **ES import**. The package ships an `exports`
 map with an `import` condition, bundles its own video.js, and loads the player
@@ -333,10 +344,11 @@ same way and puts `cloudinary` on `window`:
 ```
 
 **Construct with `cloudinary.player()`, not `cloudinary.videoPlayer()`.**
-`videoPlayer()` is the older synchronous constructor. `player()` is the
+`videoPlayer()` is the older constructor. `player()` is the
 current one: it returns a **Promise**, and it resolves *saved configuration*
 first. Pass `publicId` and it picks up the settings saved onto that asset in
-Video Player Studio; pass `profile` for a stored profile instead.
+Video Player Studio; pass `profile` for a stored profile instead. The skill
+was tested against player 4.1.0; pin the release you test against.
 
 ```js
 const player = await cloudinary.player('hero', {
@@ -375,8 +387,8 @@ asset. Constructor options persist across the swap; the per-asset metadata
 Building a new player per video is the common mistake: it costs a fresh
 video.js instance each time and leaks the old ones unless you `dispose()`.
 
-The one thing to watch when swapping is the delivery strategy above: set
-`sourceTypes` and `breakpoints` explicitly on each `source()` call.
+The one exception is switching between a progressive and an ABR source: see
+*Configure the player* in B2.
 
 Player-only options go on the constructor and are ignored by `source()`.
 Per-video options work on `source()`, and on the constructor they become
@@ -387,14 +399,15 @@ defaults every `source()` call inherits:
 | `cloudName`, `fluid`, `controls`, `showLogo`, `colors` | `sourceTypes`, `breakpoints`, `maxDpr`, `transformation` |
 | `seekThumbnails`, `chaptersButton`, `aiHighlightsGraph` | `chapters`, `title`, `description`, `textTracks`, `posterOptions`, `interactionAreas` |
 
-**`colors.text` must be a LIGHT colour.** Player chrome sits over dark video; a
-dark text token makes the controls invisible.
+**`colors.text` must contrast with `colors.base`.** The default skin is a dark
+base with light text; a dark text token on a dark base makes the controls
+invisible.
 
 Every option is in the
 [Video Player API reference](https://cloudinary.com/documentation/video_player_api_reference.md?install_source=skillspack&referrer=video-skill);
 the traps are in [references/player.md](references/player.md).
 
-## B4. Wire the experience
+### B4. Wire the experience
 
 The capabilities are only worth having if the page uses them. Patterns that
 worked, with the reasoning, in
@@ -416,7 +429,7 @@ worked, with the reasoning, in
   fetch and render it yourself for on-page search with click-to-seek.
 - **Emit JSON-LD** from the generated title, description and chapters.
 
-## B4a. Generated, supplied, or hand-authored, in that order
+### B4a. Generated, supplied, or hand-authored, in that order
 
 Video Player Studio offers the same three-tier ladder on every piece of
 content, and it is a good default for deciding where metadata comes from:
@@ -424,17 +437,17 @@ content, and it is a good default for deciding where metadata comes from:
 | panel | tier 1: generate | tier 2: supply | tier 3: author |
 | --- | --- | --- | --- |
 | Chapters | Automatically generate chapters | Import a VTT file | Type `00:00` + name |
-| Transcript | Generate | Upload | n/a |
+| Transcript | Generate | Upload (translations only) | n/a |
 | Poster | Suggested posters (AI frames) | Media Library / current frame | Upload |
 
-Two things follow. First, **every generated artefact has a supply path beside
-it**, so when a human-authored caption, chapter list or poster already exists
-(for example, carried over from the platform the video came from), use it; the
-ladder exists precisely so generation is not the only route. Second, the tiers
-are per-asset, not per-site: generating chapters for a long talk and
+Two things follow. First, **most generated artefacts have a supply path beside
+them** (in Studio the source-language transcript has none, but the player takes
+existing captions as a VTT `url`), so when a human-authored caption, chapter
+list or poster already exists (for example, from the video's old platform), use
+it. Second, the tiers are per-asset: generating chapters for a long talk and
 hand-authoring three for a short explainer is normal.
 
-## B5. Be straight about what Cloudinary does not generate
+### B5. Be straight about what Cloudinary does not generate
 
 - **Chapter→product bindings.** Auto-chaptering finds the segments; which
   product a segment sells is your data. Check the source platform's cue points
@@ -443,8 +456,9 @@ hand-authoring three for a short explainer is normal.
   Cloudinary does not track objects and hand you positions. The AI Video
   Analysis API (Beta) returns timestamped natural-language segments with no
   spatial coordinates or bounding boxes.
-- **Video background removal, virtual try-on, shade matching.** These do not
-  exist. Do not approximate them with something adjacent.
+- **AI background removal, virtual try-on, or shade matching on video.** Not
+  available for video (only chroma-key transparency on a video overlay, with
+  `e_make_transparent`). Do not approximate them with something adjacent.
 
 ## Close out
 
@@ -453,21 +467,6 @@ hand-authoring three for a short explainer is normal.
 - What was uploaded, and anything that had no Cloudinary equivalent.
 - On a claimable cloud: **the claim URL**, and that it expires in 24 hours.
 
-## How much of this is verified
-
-Calibrate accordingly. The guidance is not uniformly tested:
-
-- **Key Cloudinary behaviour is machine-verified.** A subset of the delivery,
-  transformation and async-output claims is asserted against live Cloudinary by
-  a test suite kept in the cloudinary-devs/skills repo (`sp_auto` rejecting a resize at every
-  width, the transcript being JSON with word-level timings, the pinned player
-  CDN URLs). If Cloudinary changes, those assertions fail rather than quietly
-  misleading you.
-- **Nothing here has been run end to end against an existing customer cloud.**
-  The from-scratch path has a worked example behind it; that one does not.
-
-Say which applies when you rely on one; don't present it all as equally sure.
-
 ## Additional Resources
 
 ### Skill References (Progressive Disclosure)
@@ -488,6 +487,7 @@ Say which applies when you rely on one; don't present it all as equally sure.
 - [Interactive Video](https://cloudinary.com/documentation/video_player_interactive_videos.md?install_source=skillspack&referrer=video-skill) - Interaction areas
 - [Video Optimization](https://cloudinary.com/documentation/video_optimization.md?install_source=skillspack&referrer=video-skill)
 - [Adaptive Bitrate Streaming](https://cloudinary.com/documentation/adaptive_bitrate_streaming.md?install_source=skillspack&referrer=video-skill)
+- [Video Best Practices](https://cloudinary.com/documentation/video_best_practices.md?install_source=skillspack&referrer=video-skill)
 - [Eager and Incoming Transformations](https://cloudinary.com/documentation/eager_and_incoming_transformations.md?install_source=skillspack&referrer=video-skill)
 - [Video Transcription](https://cloudinary.com/documentation/video_transcription.md?install_source=skillspack&referrer=video-skill)
 - [AI Video Analysis](https://cloudinary.com/documentation/ai_video_analysis.md?install_source=skillspack&referrer=video-skill)
diff --git a/skills/platform/cloudinary-video/references/build-patterns.md b/skills/platform/cloudinary-video/references/build-patterns.md
index ec58879..0ca9ce0 100644
--- a/skills/platform/cloudinary-video/references/build-patterns.md
+++ b/skills/platform/cloudinary-video/references/build-patterns.md
@@ -98,6 +98,7 @@ a player feature:
   fires several times a second and re-rendering on each is visible jank.
 
 ```js
+let lastId;
 player.on('timeupdate', () => {
   const t = player.currentTime();
   const match = chapters.find((c) => t >= c.start && t < c.end);
@@ -140,19 +141,20 @@ cue-level time, so seek to a cue's `words[0].start_time` (or a word's own
 So the split is: **captions, word highlighting and translated subtitles are the
 player's job; an on-page searchable transcript is yours.**
 
-Translated transcripts live at `<publicId>.<lang>.transcript` and must be
-passed explicitly as `subtitles` entries.
+Translated transcripts live at `<publicId>.<lang>.transcript`. Add each as a
+`subtitles` entry with its `language`; the player fetches it without a `url`.
 
 Always give it a failure path. The transcript can be pending, failed, or absent
 (no audio track), and a permanently "Loading transcript…" panel is worse than
 an honest "Transcript unavailable."
 
-## Audio description as a subtitles track
+## Audio description as a descriptions track
 
-The player has no native descriptions kind, so the visual transcription from
-`ai_video_analysis` (describing what is *on screen* rather than what is said)
-goes in as another `subtitles` entry, labelled so it is not mistaken for a
-translation. Requires an API secret; unavailable over MCP alone.
+The visual transcription from `ai_video_analysis` describes what is *on
+screen* rather than what is said. Write it to a VTT file and add it as a
+`descriptions` text track (`textTracks: { descriptions: [{ label, url }] }`),
+which the player lists in its audio-descriptions menu and screen readers can
+read. Generating it requires the API secret; it is unavailable over MCP alone.
 
 ## Structured data comes free once the metadata exists
 
@@ -166,10 +168,14 @@ the block.
 
 For decorative loops (tiles, background clips, a feature panel), the reflex is
 an `IntersectionObserver` that plays on enter and pauses on exit. The player
-has this: `autoplayMode: 'on-scroll'`, alongside `muted`, `loop` and
-`controls: false`. (Not `autoplay: 'on-scroll'`: that value is treated as plain
-`autoplay: true`, so the clip always autoplays.) Save that on each asset and the observer disappears, along
-with the lazy `src` assignment people bolt onto it.
+has this: `autoplayMode: 'on-scroll'`, alongside `muted`, `loop`,
+`controls: false`, and `seekThumbnails: false`. (Not `autoplay: 'on-scroll'`:
+that value is treated as plain `autoplay: true`, so the clip always autoplays.)
+Save those settings on each asset and the observer disappears, along with the
+lazy `src` assignment people bolt onto it. For a loop that should play as soon
+as the page loads, such as a hero, use `profile: 'cld-looping'` and pass
+`seekThumbnails: false` locally (the profile doesn't set it, and a profile
+replaces the asset's saved settings).
 
 That also keeps every clip on the player's own optimizations (`f_auto:video`,
 breakpoints) rather than a hand-written URL on a bare `<video>`; a page mixing
@@ -197,12 +203,3 @@ presented as a quiet disclosure rather than a showcase of transcription.
 Also watch for **copy that duplicates the footage**. Campaign films usually
 carry a burned-in end-card; if your headline repeats the line the video already
 says, the page reads as a mistake. Read the frames before writing the hero.
-
-## Framework note
-
-Build the `<video>` element imperatively and do **not** dispose the player on
-effect cleanup. Colors, adaptive streaming and interaction areas are lazy
-plugins that reach for the element after the effect returns; disposing pulls it
-out from under them (`Invalid target for null#one`). Route callbacks through
-refs so the effect can have an empty dependency list and build exactly one
-player for the page's lifetime.
diff --git a/skills/platform/cloudinary-video/references/capabilities.md b/skills/platform/cloudinary-video/references/capabilities.md
index 2e09640..2eba233 100644
--- a/skills/platform/cloudinary-video/references/capabilities.md
+++ b/skills/platform/cloudinary-video/references/capabilities.md
@@ -34,13 +34,13 @@ and say so honestly at the end of a run.
 
 | Capability | Needs | Absent → degrade to |
 | --- | --- | --- |
-| Adaptive streaming (`sp_auto`) | a video track (audio-only sources return 400) | progressive (`breakpoints: true`) |
+| Adaptive streaming (`sp_auto`) | a video track (audio-only sources return 400) | progressive (`breakpoints: true`; none for audio only) |
 | Auto poster (`so_auto`) | nothing | first frame, or a chosen still |
 | `e_preview` loop opening frame (long sources only) | nothing (warm it) | auto poster, then plain poster |
-| Hover previews | chapter→SKU map | static image on hover |
+| Hover previews | chapter→item map | static image on hover |
 | Chapters + rail | `auto_chaptering` (or migrated cue points) | no rail; plain scrub bar |
 | Seek thumbnails (`fl_sprite`) | nothing | off; the player copes |
-| Hotspots → cart | **your** coordinates + SKU map | off; rail does the linking |
+| Hotspots → links | **your** coordinates + item map | off; rail does the linking |
 | Machine tags / facets | Google Automatic Video Tagging add-on (Google Auto Tagging for images) | existing hand-authored tags |
 | Captions | `auto_transcription`, or migrated captions | no caption track |
 | Translated subtitles | Google Translation add-on | English captions only |
@@ -56,7 +56,7 @@ Cloudinary supplies and it does not:
   (`transcript`, `start_time`, `end_time`) with no spatial coordinates or
   bounding boxes.
 - **Chapter→product bindings** are yours. Auto-chaptering finds segment
-  boundaries; which SKU a segment is selling is business data. On a migration,
+  boundaries; which product a segment is about is business data. On a migration,
   check the source platform first: cue points and custom fields often already
   carry it.
 
@@ -74,9 +74,8 @@ subscribed. Probe by attempting the operation on **one** asset and reading the
 result, then set the flag. Never probe by looping the catalogue: free tiers are
 small monthly quotas, and on a customer cloud the quota is their money.
 
-There is no Admin API that lists entitlements: `/addons`, `/add_ons`,
-`/subscriptions`, `/entitlements` all 404. Attempting the operation is the only
-detection available.
+There is no documented API that lists a cloud's add-ons. Attempting the
+operation is the only detection available.
 
 ## Access routing: MCP vs `CLOUDINARY_URL`
 
@@ -89,7 +88,7 @@ return
 | Step | Over MCP | With `CLOUDINARY_URL` |
 | --- | --- | --- |
 | Upload with `auto_transcription` / `auto_chaptering` | yes | yes |
-| Upload with `auto_video_details` | **no parameter** (use an upload preset that sets it) | yes |
+| Upload with `auto_video_details` | **no parameter** (use an upload preset that sets it) | yes, via the REST upload endpoint or a preset (not the SDKs) |
 | Poll asset for async status | yes | yes |
 | Asset update / tags / context | yes | yes |
 | Delivery URLs, warming derivations | yes (plain HTTP) | yes |
@@ -99,7 +98,7 @@ return
 
 Consequence worth stating to the user rather than discovering late: on an
 MCP-only build the **audio description track is simply unavailable**, because
-`POST /v2/video/<cloud>/ai_video_analysis` cannot be signed, and generated
+`POST /v2/video/<cloud>/ai_video_analysis` needs the API secret, and generated
 titles and descriptions need an upload preset that sets `auto_video_details`.
 Everything else in the matrix is reachable either way.
 
@@ -186,17 +185,18 @@ the browser picks by viewport. That gives the same optimizations without the pla
 ```html
 <video controls autoplay muted playsinline preload="metadata">
   <source media="(max-width: 640px)"
-    src=".../video/upload/c_limit,w_640/f_auto/q_auto/v1/<id>.mp4">
+    src=".../video/upload/c_limit,w_640/f_auto:video/q_auto/v1/<id>">
   <source media="(max-width: 1280px)"
-    src=".../video/upload/c_limit,w_1280/f_auto/q_auto/v1/<id>.mp4">
+    src=".../video/upload/c_limit,w_1280/f_auto:video/q_auto/v1/<id>">
   <source
-    src=".../video/upload/c_limit,w_1920/f_auto/q_auto/v1/<id>.mp4">
+    src=".../video/upload/c_limit,w_1920/f_auto:video/q_auto/v1/<id>">
 </video>
 ```
 
-Use `f_auto` for the format/codec pick (`f_auto:video` is only needed when the
-URL has no file extension), `q_auto` for quality, and `c_limit,w_…` to cap
-dimensions. Leave out `type="video/mp4"`: `f_auto` may return WebM, and a
+Use `f_auto:video` for the format/codec pick (it delivers video with or
+without a file extension, matching the cloudinary-transformations skill),
+`q_auto` for quality, and `c_limit,w_…` to cap dimensions. Leave out
+`type="video/mp4"`: `f_auto:video` may return WebM, and a
 wrong type hint can make a browser skip the source. For ABR without the
 player, generate the manifest with `sp_auto` and hand the `.m3u8` to a
 compatible third-party player.
@@ -235,10 +235,13 @@ component, because a streaming profile must be alone in its component
 ("streaming_profile must be the only directive in the transformation
 component").
 
-Both can be set per source: `source()` options override the constructor's, and
-constructor values are inherited by every `source()` call. So when a page moves
-a viewer between strategies, pass both explicitly on each call, for example
-`player.source(id, { sourceTypes: ['hls'], breakpoints: false })` for ABR.
+Keep the two strategies on separate players. Once a player has delivered a
+progressive source with `breakpoints`, it keeps that resize in its own
+transformation and adds it to later sources, so a following ABR source still
+returns 400, even with `breakpoints: false` on the `source()` call. To switch
+one player anyway, call `player.transformation({})` and pass
+`{ sourceTypes: ['hls'], breakpoints: false }` before an ABR source (verified
+on player 4.1.0).
 
 `maxDpr` (a number, default 2.0) is a child of breakpoints: Video Player Studio
 reveals Max DPR only *after* breakpoints is enabled. With ABR neither exists;
@@ -250,12 +253,12 @@ A page usually wants ABR for the main tour and progressive for the loops:
 
 ```js
 // main player, LONG source: adapts while watching
-cloudinary.player(el, { publicId: 'tour', sourceTypes: ['hls'], breakpoints: false });
+cloudinary.player(el, { cloudName, publicId: 'tour', sourceTypes: ['hls'] });
 ```
 
 ```html
 <!-- preview loop cut from that long source: one small file, no manifest -->
-<video src=".../e_preview:duration_10.0/f_auto/q_auto/tour.mp4" muted loop playsinline></video>
+<video src=".../e_preview:duration_10.0/f_auto:video/q_auto/tour" autoplay muted loop playsinline></video>
 ```
 
 That is the common configuration, not a compromise. What is *not* available is
diff --git a/skills/platform/cloudinary-video/references/field-guide.md b/skills/platform/cloudinary-video/references/field-guide.md
index 4d5f70a..a9be5c9 100644
--- a/skills/platform/cloudinary-video/references/field-guide.md
+++ b/skills/platform/cloudinary-video/references/field-guide.md
@@ -51,8 +51,8 @@ Recommendations follow from the use case, so establish it first:
   works there if the app sends an `Accept` header listing the formats the
   device supports. See *Mobile apps are a different problem* below.
 - **Preloading everything.** Preloading improves perceived start time but
-  consumes units for videos nobody watches. The player's `preload` defaults to
-  `auto`, so make it a deliberate decision: `preload: 'none'` or `lazy` for
+  consumes units for videos nobody watches. The player preloads metadata by
+  default, so make it a deliberate decision: `preload: 'none'` or `lazy` for
   players below the fold or behind a click.
 
 ## `f_auto` causes a transformation-usage spike, so say so in advance
@@ -68,9 +68,8 @@ not surprise them.
 - **Default automatic format** adds `f_auto` to every delivered video without
   touching delivery URLs. Because that counts as a transformation, Default video
   quality also applies. It is available only on plans that use the *video
-  seconds* metric. It is not compatible with strict transformations, and while
-  it is on, eager transformations generated without a format aren't
-  delivered. `fl_original` bypasses it.
+  seconds* metric. It is not compatible with strict transformations or with
+  eager transformations. `fl_original` bypasses it.
 - **Default video quality** lets Cloudinary pick quality and codec (`vc_auto`)
   automatically. Available on all plans, but **only applies when another
   transformation is present in the URL**.
@@ -87,13 +86,15 @@ player shows the wrong duration and cannot seek, and async derivations
 Switch to **eager transformations at upload** (or the explicit method
 afterwards) when a launch or campaign will drive a traffic surge, when videos
 are long or high-resolution (2K/4K), when transformations are slow to build, or
-whenever the first viewer's playback matters. Two rules:
+whenever the first viewer's playback matters. Three rules:
 
 - **`f_auto` in an eager transformation generates nothing.** There is no
   browser at upload time, so name each format you need instead, with its
   codec (for example `f_webm,vc_vp9` and `f_mp4,vc_h264`).
 - If you can't pre-generate, add `fl_no_stream` to the delivery URL so
   Cloudinary waits for the finished file before responding.
+- **Check Optimize by default first.** If it is on, eager derivatives aren't
+  the ones delivered, so pre-generating them does nothing for viewers.
 
 ## Mobile apps are a different problem
 
diff --git a/skills/platform/cloudinary-video/references/gotchas.md b/skills/platform/cloudinary-video/references/gotchas.md
index 7153402..306aa2a 100644
--- a/skills/platform/cloudinary-video/references/gotchas.md
+++ b/skills/platform/cloudinary-video/references/gotchas.md
@@ -24,14 +24,14 @@ What does work: pass an explicit clean preset by name (check what exists on
 the account), change the default upload preset, or clear the offending preset's
 incoming transformation in Console > Settings > Upload.
 
-Note the watermark also **degrades Cloudinary's own AI**. Google Auto Tagging on
-a watermarked image returned 3 tags where the clean original returned 27.
+Note the watermark also **degrades Cloudinary's own AI**: auto-tagging a
+watermarked image returns far fewer tags than the clean original.
 
 ## Re-uploading to the same public ID can keep serving the old file
 
 After you overwrite, rename, or delete an asset, delivered versions can stay
-cached on the CDN for up to 30 days. On one account, a path kept serving the old
-788px watermarked asset after a fresh upload.
+cached on the CDN for up to 30 days, so a fresh upload can keep delivering the
+old file.
 
 Deliver the versioned URL from the upload response (`/v<version>/`), or upload
 with `invalidate: true`. Unsigned uploads never overwrite an existing public ID.
@@ -40,9 +40,8 @@ dimensions, not the upload response.
 
 ## Add-on quotas are small and easy to burn
 
-Free add-on tiers are small monthly quotas, and Image to Video gives a one-time
-trial allocation (16 credits on a Free plan, 32 on a paid plan). Check the
-add-on's page in the Console before looping over an asset list.
+Free add-on tiers are small monthly quotas. Check the add-on's page in the
+Console before looping over an asset list.
 
 Repeated re-uploads to fix something else will exhaust these. Get the upload
 parameters right before running the batch.
@@ -68,7 +67,8 @@ Async derivations return **423** on the first request until they are built:
 `e_preview`, `g_auto` crops, DASH, `sp_auto` at 2K/4K (`maxres_1440p` or
 `maxres_2160p`), and videos longer than 30 minutes (progressive) or 60 minutes
 (ABR). A default `sp_auto` HLS manifest returns 200. `e_preview` on a 3-minute video took
-minutes. Poll until 200.
+minutes, and on a very short source (a 13-second clip) it returned 500 instead.
+Poll until 200.
 
 For anything going into a launch or a traffic spike, the real fix is **eager
 transformations at upload** rather than warming by polling; see
@@ -144,18 +144,18 @@ Always close the tag.
 
 ## The Cloudinary player proxies only some videojs methods
 
-`player.currentTime()`, `player.play()`, `player.mute()`, `player.unmute()` and
-`player.isMuted()` are Cloudinary player methods. `player.muted()` and
-`player.controls()` are **not**: calling them throws
+`player.currentTime()`, `player.play()`, `player.controls()`, `player.mute()`,
+`player.unmute()` and `player.isMuted()` are Cloudinary player methods.
+`player.muted()` is **not**: calling it throws
 `TypeError: player.muted is not a function`, which aborts the rest of your
 click handler and looks like "the button does nothing".
 
-Use `player.mute()` / `player.unmute()`, and reach the underlying videojs player
-for anything else:
+Use `player.mute()` / `player.unmute()`, and reach the underlying video.js
+instance, `player.videojs`, for anything else the Cloudinary player doesn't
+expose:
 
 ```js
-var vjs = window.videojs && window.videojs.getPlayer('hero');
-if (vjs) { try { vjs.controls(true); } catch (e) {} }
+player.videojs.playbackRate(1.5);
 ```
 
 Setting `muted`/`volume` directly on the underlying `<video>` element also
@@ -187,7 +187,7 @@ chaptering can work.
 
 The agent never holds the API secret when it works through the Cloudinary MCP
 servers, so it can only do what the MCP has a tool for.
-Any other endpoint (a v2 route, a beta API) cannot be signed and returns:
+Any other endpoint that needs the secret (a v2 route, a beta API) returns:
 
 ```
 {"error":{"message":"error while authenticating: api_secret not provided"}}
diff --git a/skills/platform/cloudinary-video/references/player.md b/skills/platform/cloudinary-video/references/player.md
index 13e434d..bc80050 100644
--- a/skills/platform/cloudinary-video/references/player.md
+++ b/skills/platform/cloudinary-video/references/player.md
@@ -11,8 +11,8 @@ construct a player and they are **not** the same function:
 
 | | `cloudinary.videoPlayer()` | `cloudinary.player()` |
 | --- | --- | --- |
-| Status | older constructor | **current**; the bundle tags its own analytics `newPlayerMethod: true` |
-| Returns | the player, synchronously in the UMD full bundle (a buffering proxy via ES import) | a **Promise** resolving to the player |
+| Status | older constructor | **current** |
+| Returns | a player synchronously from the full bundle (`player-full.min.js`, `cld-video-player.min.js`, or the `/full` import); a buffering proxy from `player.min.js` and the default ES import | a **Promise** resolving to the player |
 | Saved configuration | none, options only | fetches saved config before constructing |
 
 ```js
@@ -36,8 +36,7 @@ the Studio without hard-coding it.
 
 `profile` loads a stored *profile* instead: either a built-in
 (`cld-default`, `cld-looping`, `cld-adaptive-stream`, `cld-live-streaming`) or
-one saved on the cloud, fetched from
-`/_applet_/video_service/video_player_profiles/<name>.json`.
+one saved on the cloud.
 
 **Profiles are writable over HTTP, with no console needed.** When the same
 presentation repeats across many assets, that is the signal to create one
@@ -50,8 +49,8 @@ curl -X PUT https://api.cloudinary.com/v2/video/<cloud>/player/profiles/<name> \
   -d '{"playerOptions":{…},"sourceOptions":{…}}'
 ```
 
-Basic auth with the API key and secret; both `playerOptions` and
-`sourceOptions` are required and take arbitrary player/source keys. Full
+Basic auth with the API key and secret; the body takes `playerOptions` and
+`sourceOptions`, holding player and source keys. Full
 reference: [Video Player profiles](https://cloudinary.com/documentation/video_player_profiles_reference.md?install_source=skillspack&referrer=video-skill)
 
 Precedence, and the trap: **specifying a `profile` overrides the asset's own
@@ -138,25 +137,16 @@ curl -X PUT https://api.cloudinary.com/v2/video/<cloud>/player/config/video/<ass
 `asset_id` from the Admin API: the resource endpoint returns it alongside the
 public ID.
 
-The player reads the same config at delivery time from
-`/_applet_/video_service/video_player_config/video/<type>/<base64(publicId)>.json`
-(observed, undocumented, may change), which is handy for verifying what a page
-will actually receive. **An empty
-`{"playerOptions":{},"sourceOptions":{}}` and HTTP 200 means nothing is saved**:
-the fetch fails silently by design, so a page falls back to its local
-options and looks fine while inheriting nothing.
+Read the config back with a GET to check what a page will receive. **An empty
+`{"playerOptions":{},"sourceOptions":{}}` with HTTP 200 means nothing is
+saved**: the player's own fetch fails silently in the same way, so a page falls
+back to its local options and looks fine while inheriting nothing.
 
-### Confirming saved config actually applied
+### Checking captions
 
-Two checks that avoid false alarms:
-
-- The player's analytics beacon to `analytics-api-s.cloudinary.com/video_player_source`
-  (observed, undocumented, may change) spells it out: `newPlayerMethod=true`, `videoConfig=true`, and
-  `fetchedConfig=<comma-separated keys>` listing the `playerOptions` keys that
-  came from the saved config (`sourceOptions` keys are not listed).
-- **Do not test captions with `videoEl.textTracks`**: it reads empty because
-  video.js manages them as *remote* tracks. Use
-  `videojs.getPlayer(id).remoteTextTracks()`.
+**Do not test captions with `videoEl.textTracks`**: it reads empty because
+video.js manages them as *remote* tracks. Use
+`videojs.getPlayer(id).remoteTextTracks()`.
 
 ## Constructor and `source()` options
 
@@ -174,10 +164,10 @@ the constructor. The traps that cost real builds:
   `['hls']` or `['dash']` for adaptive streaming.
 - **`breakpoints` is progressive-only.** Under `sourceTypes: ['hls']` the
   streaming profile's ladder governs resolution, and setting `breakpoints` too
-  yields a 400, even when both are set as player options. Constructor values
-  are inherited, so a player built with `breakpoints: true` needs
-  `breakpoints: false` on any ABR `source()` call. See the comparison in
-  [capabilities.md](capabilities.md).
+  yields a 400, even when both are set as player options. Once a player has
+  delivered a progressive source with `breakpoints`, an ABR `source()` call
+  needs `player.transformation({})` first as well as `breakpoints: false`.
+  Better, use a separate player per strategy (SKILL.md B2).
 - **Don't add `streaming_profile` for `sp_auto`.** `sourceTypes: ['hls']` adds
   it for you. Pass `transformation: { streaming_profile: … }` only to pick a
   named profile, and keep it alone in its component: combined with a resize or
@@ -186,16 +176,18 @@ the constructor. The traps that cost real builds:
   2.0, and enabling `breakpoints` already accounts for the device pixel ratio.
   Pass a lower number only to deliberately cap DPR. Never pass `true`: it is
   coerced to 1 and caps DPR at 1x.
-- **`colors.text` must be a light colour.** Player chrome sits over dark video,
-  so a dark text token makes the controls invisible.
+- **`colors.text` must contrast with `colors.base`.** The default skin is a
+  dark base with light text; a dark text token on a dark base makes the
+  controls invisible.
 - **`chapters: true` loads `<publicId>-chapters.vtt`**, which is what
   `auto_chaptering` produces.
 - **Omitting `url` on `textTracks.captions` makes the player use the
   `.transcript` file** for that public ID. Setting `maxWords` also triggers that
   lookup. The player fetches it from its own service endpoint, not from
   `…/raw/upload/<publicId>.transcript`, so a page that also renders the
-  transcript downloads it twice. Translated transcripts live at
-  `<publicId>.<lang>.transcript` and must be passed explicitly. Pair
+  transcript downloads it twice. For a translation, add a `subtitles` entry
+  with its `language` (for example `'es'`) and no `url`; the player fetches the
+  translated transcript itself. Pair
   `wordHighlight: true` with `maxWords` so the caption box does not fill;
   neither works on translated transcripts. `textTracks.options.theme` takes
   `default`, `videojs-default`, `yellow-outlined`, `player-colors`, or `3d`.
@@ -203,10 +195,15 @@ the constructor. The traps that cost real builds:
   [build-patterns.md](build-patterns.md).
 - **`interactionAreas` coordinates are percentages** of the video frame, not
   pixels. Cloudinary does not supply them (see SKILL.md B5).
-- **`preload` defaults to `auto`**, so every non-autoplaying player starts
-  downloading video at load. For players below the fold or behind a click, set
-  `preload: 'none'` or use `lazy` (`cloudinary.player()` only), which shows a
-  lightweight poster until the viewer clicks or scrolls to it. The lazy
+- **`preload` defaults to `metadata` in player 4.1.0** (the API reference
+  still says `auto`), so every non-autoplaying player fetches video metadata at
+  load. For players below the fold or behind a click, set `preload: 'none'` or
+  use `lazy` (`cloudinary.player()` only), which shows a lightweight poster:
+  `lazy: true` loads the player on click, `lazy: { loadOnScroll: true }` when
+  it scrolls into view. With `lazy`, `await cloudinary.player()` resolves to a
+  placeholder, not the player: its `source()` does nothing, and
+  `await placeholder.loadPlayer()` builds the player, starts playback, and
+  resolves to the player. Use that for seeking or reading state. The lazy
   placeholder ignores `posterOptions` and defaults to the untransformed middle
   frame (`<publicId>.jpg`, full resolution), so pass an explicit sized `poster`
   URL such as `…/video/upload/so_auto/c_limit,w_1280/f_auto/q_auto/<publicId>.jpg`.
@@ -238,13 +235,14 @@ shows that cleanup.
   player source they are redundant, and pairing them with
   `sourceTypes:['mp4']` re-adds by hand what forcing MP4 just removed. See
   [capabilities.md](capabilities.md).
-- Prefer `f_auto/q_auto` as **separate components** over `f_auto,q_auto`.
-  Both are accepted and, as of September 2026, deliver byte-identical results
-  for image and video alike. This is a convention for readability and for
-  matching Cloudinary's own docs, **not** a correctness rule. Do not tell a
-  user the combined form is broken; it is not.
-- `sp_auto` is the streaming profile. It cannot be combined with a resize.
+- Write `f_auto/q_auto` as **separate components**. The combined
+  `f_auto,q_auto` is accepted too, but for video it can produce a different
+  encode.
 - `e_preview[:duration_<s>][:max_seg_<n>][:min_seg_dur_<s>]`: AI summary reel,
-  video only, default duration 5.0s.
+  video only, default duration 5.0s. It needs a source long enough to
+  summarise; on a 13-second clip it returned a 500.
 - For video, `g_auto` works only with `c_fill` and `c_fill_pad`, once per
   transformation, and not for positioning overlays.
+
+For everything else about transformation syntax, use the
+cloudinary-transformations skill.
diff --git a/skills/platform/cloudinary-video/references/upload-and-prepare.md b/skills/platform/cloudinary-video/references/upload-and-prepare.md
index a4a49f2..b02bfd2 100644
--- a/skills/platform/cloudinary-video/references/upload-and-prepare.md
+++ b/skills/platform/cloudinary-video/references/upload-and-prepare.md
@@ -62,7 +62,7 @@ fails the **whole** transcription (no transcript, no captions), where plain
 `auto_video_details` is worth requesting here rather than leaving to the player.
 The player's `title: true` / `description: true` read the asset's context
 metadata and only trigger generation if no value is found, so an
-un-pre-generated title is a request happening for the first time mid-demo.
+un-pre-generated title is generated for the first time in front of a viewer.
 
 ```
 upload image:                    # no add-on needed
@@ -86,8 +86,8 @@ replacement for curated facets.
    like a broken upload rather than a missing entitlement.
 2. **Then try add-ons separately**, and treat failure as expected.
 3. **Add-ons cannot be enabled by an agent.** It is a console action, which on a
-   claimable cloud means claiming it first. No Admin API exists: `/addons`,
-   `/add_ons`, `/subscriptions`, `/entitlements` all 404.
+   claimable cloud means claiming it first. There is no documented API for
+   checking or enabling add-ons.
 4. **A default upload preset can rewrite every asset on ingest**, adding a
    watermark or downsizing, whenever an upload doesn't name a preset. Pass an
    explicit clean `upload_preset`. See [gotchas.md](gotchas.md).
@@ -140,7 +140,16 @@ its headers, not its status. A finished video has `content-length` and
 
 ```sh
 UA='Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0 Safari/537.36'
-until curl -sI -A "$UA" "$URL" | grep -qi '^accept-ranges: bytes'; do sleep 5; done
+for i in $(seq 1 60); do      # give up after about 5 minutes
+  H=$(curl -sI -A "$UA" "$URL")
+  if echo "$H" | grep -q '^HTTP/[0-9.]* 200'; then
+    echo "$H" | grep -qi '^accept-ranges: bytes' && break   # fully generated
+  elif ! echo "$H" | grep -q '^HTTP/[0-9.]* 423'; then
+    echo "$H" | grep -i '^HTTP\|x-cld-error'; break       # a real error
+  fi
+  sleep 5
+done
+[ "$i" = 60 ] && echo "gave up: $URL is still generating"
 ```
 
 `f_auto` picks the format from the request's `User-Agent` and `Accept`
diff --git a/tests/cloudinary-video/skill-claims.sh b/tests/cloudinary-video/skill-claims.sh
index 33292d3..9efcb5a 100755
--- a/tests/cloudinary-video/skill-claims.sh
+++ b/tests/cloudinary-video/skill-claims.sh
@@ -65,24 +65,14 @@ else
   _no "resize + sp_auto was not rejected as documented" "$(echo "$ERR" | grep -i '^HTTP\|x-cld-error')"
 fi
 
-# "Prefer f_auto/q_auto separate; the combined form is a convention, NOT a
-#  correctness rule." Assert the equivalence, so that if Cloudinary ever does
-#  start rejecting the combined form the guidance gets revisited.
+# "Write f_auto/q_auto as separate components; the combined form is accepted
+#  too" (player.md). Assert both deliver; the bytes can differ for video.
 SEP=$(http "$PUB/video/upload/f_auto/q_auto/$VID.mp4")
 JOINT=$(http "$PUB/video/upload/f_auto,q_auto/$VID.mp4")
 claim "f_auto/q_auto (separate) delivers ($SEP)" \
   "$([ "$SEP" = "200" ] && echo yes || echo no)" "expected 200, got $SEP"
-if [ "$JOINT" = "200" ]; then
-  # Same bytes? Then they are genuinely interchangeable and player.md is right
-  # to call it a convention rather than a rule.
-  L1=$(curl -s -o /dev/null -w '%{size_download}' -L --max-time 60 "$PUB/video/upload/f_auto/q_auto/$VID.mp4")
-  L2=$(curl -s -o /dev/null -w '%{size_download}' -L --max-time 60 "$PUB/video/upload/f_auto,q_auto/$VID.mp4")
-  [ "$L1" = "$L2" ] \
-    && _ok "f_auto,q_auto (combined) is equivalent: convention, not a rule" \
-    || _no "combined form delivers different bytes ($L1 vs $L2)" "player.md claims equivalence"
-else
-  _no "f_auto,q_auto combined now returns $JOINT" "player.md says both are accepted, so guidance is stale"
-fi
+claim "f_auto,q_auto (combined) is accepted ($JOINT)" \
+  "$([ "$JOINT" = "200" ] && echo yes || echo no)" "player.md says both forms are accepted; got $JOINT"
 
 # "sp_auto returns a manifest with a rendition ladder"
 body_has "sp_auto manifest lists renditions" \