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 04d8bed..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
 
diff --git a/skills/platform/cloudinary-video/SKILL.md b/skills/platform/cloudinary-video/SKILL.md
new file mode 100644
index 0000000..53f5c45
--- /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. 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**, 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
+   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 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
+
+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 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 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
+
+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 ~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 |
+
+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, { 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),
+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*).
+
+**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
+
+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 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. The skill
+was tested against player 4.1.0; pin the release you test against.
+
+```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 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
+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 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
+
+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 (translations only) | n/a |
+| Poster | Suggested posters (AI frames) | Media Library / current frame | Upload |
+
+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
+
+- **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.
+- **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
+
+- 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.
+
+## 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)
+- [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)
+
+## 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/platform/cloudinary-video/references/build-patterns.md b/skills/platform/cloudinary-video/references/build-patterns.md
new file mode 100644
index 0000000..0ca9ce0
--- /dev/null
+++ b/skills/platform/cloudinary-video/references/build-patterns.md
@@ -0,0 +1,205 @@
+# Build patterns
+
+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.
+
+`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 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
+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 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:
+`void loop.play().catch(() => {})`, and let the poster stand if it fails.
+
+## Let player options build the URL, not you
+
+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: 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
+
+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
+let lastId;
+player.on('timeupdate', () => {
+  const t = player.currentTime();
+  const match = chapters.find((c) => t >= c.start && t < c.end);
+  if (match?.id !== lastId) { lastId = match?.id; setActiveSegment(lastId); }
+});
+```
+
+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
+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, 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.**
+
+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 descriptions track
+
+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
+
+`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: `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
+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.
diff --git a/skills/platform/cloudinary-video/references/capabilities.md b/skills/platform/cloudinary-video/references/capabilities.md
new file mode 100644
index 0000000..2eba233
--- /dev/null
+++ b/skills/platform/cloudinary-video/references/capabilities.md
@@ -0,0 +1,276 @@
+# 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 Automatic Video 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`) | 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→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 → 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 |
+| 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 (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 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.
+
+## 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 monthly quotas, and on a customer cloud the quota is their money.
+
+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`
+
+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 `auto_transcription` / `auto_chaptering` | yes | 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 |
+| Add-on categorization / auto-tagging | yes | 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` 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.
+
+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**.
+
+| | `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 |
+
+### 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". Behaviour still wins where the two disagree (a long silent loop is
+progressive), except that under 30 seconds is always progressive:
+
+| Duration | Approach |
+| --- | --- |
+| **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
+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 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`, so 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. `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 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, 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. 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>">
+  <source media="(max-width: 1280px)"
+    src=".../video/upload/c_limit,w_1280/f_auto:video/q_auto/v1/<id>">
+  <source
+    src=".../video/upload/c_limit,w_1920/f_auto:video/q_auto/v1/<id>">
+</video>
+```
+
+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.
+
+### `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, 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
+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 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").
+
+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;
+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
+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:video/q_auto/tour" autoplay 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 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.
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..a9be5c9
--- /dev/null
+++ b/skills/platform/cloudinary-video/references/field-guide.md
@@ -0,0 +1,148 @@
+# 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 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
+
+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 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**.
+
+## 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. 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
+
+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..306aa2a
--- /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**: 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, 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.
+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. 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, 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
+[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.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 video.js
+instance, `player.videojs`, for anything else the Cloudinary player doesn't
+expose:
+
+```js
+player.videojs.playbackRate(1.5);
+```
+
+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 that needs the secret (a v2 route, a beta API) 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..bc80050
--- /dev/null
+++ b/skills/platform/cloudinary-video/references/player.md
@@ -0,0 +1,248 @@
+# 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** |
+| 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
+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.
+
+**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; 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
+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.
+
+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.
+
+### Checking captions
+
+**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. 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
+  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 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. 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`.
+- **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 `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`.
+- **`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).
+- 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. 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
new file mode 100644
index 0000000..b02bfd2
--- /dev/null
+++ b/skills/platform/cloudinary-video/references/upload-and-prepare.md
@@ -0,0 +1,167 @@
+# 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 generated for the first time in front of a viewer.
+
+```
+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. 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).
+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'
+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`
+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/tests/cloudinary-video/lib.sh b/tests/cloudinary-video/lib.sh
new file mode 100644
index 0000000..644a459
--- /dev/null
+++ b/tests/cloudinary-video/lib.sh
@@ -0,0 +1,57 @@
+# Shared assertion helpers. Sourced by the test scripts.
+
+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() {
+  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, %s skipped\n' "$PASS" "$FAIL" "$SKIP"
+  [ "$FAIL" -eq 0 ] && exit 0 || exit 1
+}
diff --git a/tests/cloudinary-video/skill-claims.sh b/tests/cloudinary-video/skill-claims.sh
new file mode 100755
index 0000000..9efcb5a
--- /dev/null
+++ b/tests/cloudinary-video/skill-claims.sh
@@ -0,0 +1,282 @@
+#!/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:
+#
+#   ./tests/cloudinary-video/skill-claims.sh
+#                                          # claims checkable without credentials
+#   ./tests/cloudinary-video/skill-claims.sh --cloud
+#                                          # also provision a fresh cloud and
+#                                          # assert the upload/add-on claims
+#
+# 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
+. lib.sh
+
+WITH_CLOUD=0
+[ "${1:-}" = "--cloud" ] && WITH_CLOUD=1
+
+# --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
+  [ -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=../../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"; }
+
+# 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"
+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
+
+# "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"
+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" \
+  "$PUB/video/upload/sp_auto/$VID.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 "$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, 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 "$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 "$PUB/raw/upload/$TRANSCRIPT.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', 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
+# 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@4.1.0/dist/player.min.js"
+status "player CSS at the pinned version" \
+  "https://unpkg.com/cloudinary-video-player@4.1.0/dist/player.min.css"
+
+section "Internal consistency"
+
+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
+
+# 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:+--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"
+  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 (upload-and-prepare.md, 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 (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
+# instead, the upload-free-features-first rule becomes unnecessary.
+PROBE=$(curl -s "$API/image/upload" -u "$KEY:$SEC" \
+  -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"
+  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 (upload-and-prepare.md)"
+T=$(curl -s "$API/video/upload" -u "$KEY:$SEC" \
+  -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"
+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 A2)"
+FREE=$(curl -s "$API/video/upload" -u "$KEY:$SEC" \
+  -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.
+  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."
+# 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/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"
+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