diff --git a/cli.js b/cli.js
index 23597f1..707cfbf 100755
--- a/cli.js
+++ b/cli.js
@@ -3,7 +3,7 @@
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
-import { spawnSync } from 'child_process';
+import { spawnSync, spawn } from 'child_process';
 import inquirer from 'inquirer';
 import chalk from 'chalk';
 import fs from 'fs-extra';
@@ -208,12 +208,14 @@ async function main() {
         name: 'aiTools',
         message:
           'Which AI coding assistant(s) are you using? (Select all that apply)\n' +
-          chalk.gray('   We’ll add local instruction files so your assistant knows Cloudinary patterns.\n'),
+          chalk.gray('   We\'ll install Cloudinary skills in the right location for each tool.\n'),
         choices: [
           { name: 'Cursor', value: 'cursor' },
-          { name: 'GitHub Copilot', value: 'copilot' },
           { name: 'Claude Code', value: 'claude' },
-          { name: 'Other / Generic AI tools', value: 'generic' },
+          { name: 'GitHub Copilot', value: 'copilot' },
+          { name: 'OpenAI Codex', value: 'codex' },
+          { name: 'Gemini CLI', value: 'gemini' },
+          { name: 'Other', value: 'generic' },
         ],
         default: ['cursor'],
       },
@@ -316,35 +318,68 @@ async function main() {
     copyTemplate(file);
   });
 
-  // Create AI rules based on user's tool selection
-  const aiRulesTemplatePath = join(TEMPLATES_DIR, '.cursorrules.template');
-  if (existsSync(aiRulesTemplatePath) && aiTools && aiTools.length > 0) {
-    const aiRulesContent = replaceTemplate(
-      readFileSync(aiRulesTemplatePath, 'utf-8'),
-      templateVars
-    );
+  // Install Cloudinary skills into the directories each selected tool actually reads:
+  // .cursor/skills/  = Cursor
+  // .claude/skills/  = Claude Code
+  // .agents/skills/  = Copilot, Codex, Gemini, Generic (and any unrecognised tool)
+  console.log(chalk.blue('\n🤖 Installing Cloudinary AI skills...\n'));
+
+  const skillTargetDirs = new Set();
+  if (aiTools && aiTools.includes('cursor')) skillTargetDirs.add(join(projectPath, '.cursor', 'skills'));
+  if (aiTools && aiTools.includes('claude')) skillTargetDirs.add(join(projectPath, '.claude', 'skills'));
+  if (!aiTools || aiTools.some(t => !['cursor', 'claude'].includes(t))) {
+    skillTargetDirs.add(join(projectPath, '.agents', 'skills'));
+  }
 
-    // Generate files based on selected tools
-    if (aiTools.includes('cursor')) {
-      writeFileSync(join(projectPath, '.cursorrules'), aiRulesContent);
-    }
+  const skills = ['cloudinary-docs', 'cloudinary-react', 'cloudinary-transformations'];
+  // Download each skill once then copy to any additional targets
+  const [primaryDir, ...additionalDirs] = skillTargetDirs;
+  mkdirSync(primaryDir, { recursive: true });
 
-    if (aiTools.includes('copilot')) {
-      const githubDir = join(projectPath, '.github');
-      mkdirSync(githubDir, { recursive: true });
-      writeFileSync(join(githubDir, 'copilot-instructions.md'), aiRulesContent);
-    }
+  // Print all skill names upfront so the user sees activity immediately
+  for (const skill of skills) {
+    console.log(chalk.gray(`   Fetching ${skill}...`));
+  }
 
-    if (aiTools.includes('claude')) {
-      writeFileSync(join(projectPath, 'CLAUDE.md'), aiRulesContent);
+  // Download all 3 skills in parallel
+  const results = await Promise.all(
+    skills.map(skill => new Promise(resolve => {
+      const proc = spawn(
+        'npx',
+        ['--yes', 'degit', `cloudinary-devs/skills/skills/${skill}`, join(primaryDir, skill)],
+        { stdio: 'pipe', shell: false }
+      );
+      proc.on('close', code => resolve({ skill, ok: code === 0 }));
+    }))
+  );
+
+  const BUNDLED_SKILLS_DIR = join(__dirname, 'skills');
+
+  let skillsInstalled = 0;
+  for (const { skill, ok } of results) {
+    if (ok) {
+      console.log(chalk.gray(`   ✓ ${skill}`));
+      skillsInstalled++;
+    } else {
+      const bundled = join(BUNDLED_SKILLS_DIR, skill);
+      if (existsSync(bundled)) {
+        fs.copySync(bundled, join(primaryDir, skill));
+        console.log(chalk.gray(`   ✓ ${skill} (installed from local cache)`));
+        skillsInstalled++;
+      } else {
+        console.warn(chalk.yellow(`   ⚠ Could not install ${skill}`));
+      }
     }
+  }
 
-    if (aiTools.includes('generic')) {
-      writeFileSync(join(projectPath, 'AI_INSTRUCTIONS.md'), aiRulesContent);
-      writeFileSync(join(projectPath, 'PROMPT.md'), aiRulesContent);
+  if (skillsInstalled > 0) {
+    for (const target of additionalDirs) {
+      fs.copySync(primaryDir, target);
     }
+  }
 
-    // Generate MCP configuration: Cursor uses .cursor/mcp.json, Claude Code uses .mcp.json in project root
+  // Generate MCP configuration: Cursor uses .cursor/mcp.json, Claude Code uses .mcp.json in project root
+  if (aiTools && aiTools.length > 0) {
     const mcpTemplatePath = join(TEMPLATES_DIR, '.cursor/mcp.json.template');
     if (existsSync(mcpTemplatePath)) {
       const mcpContent = replaceTemplate(
@@ -370,26 +405,16 @@ async function main() {
 
   console.log(chalk.green('✅ Project created successfully!\n'));
 
-  if (aiTools && aiTools.length > 0) {
-    // Count actual files created
-    let fileCount = 0;
-    if (aiTools.includes('cursor')) fileCount += 2; // .cursorrules + mcp.json
-    if (aiTools.includes('copilot')) fileCount += 1;
-    if (aiTools.includes('claude')) fileCount += 2; // CLAUDE.md + .mcp.json
-    if (aiTools.includes('generic')) fileCount += 2; // AI_INSTRUCTIONS.md + PROMPT.md
-    
-    const filesText = fileCount === 1 ? 'file' : 'files';
-    console.log(chalk.cyan(`📋 AI assistant configuration ${filesText} created:`));
-    if (aiTools.includes('cursor')) console.log(chalk.gray('   • Cursor: .cursorrules'));
-    if (aiTools.includes('copilot')) console.log(chalk.gray('   • GitHub Copilot: .github/copilot-instructions.md'));
-    if (aiTools.includes('claude')) console.log(chalk.gray('   • Claude: CLAUDE.md'));
-    if (aiTools.includes('generic')) console.log(chalk.gray('   • Generic: AI_INSTRUCTIONS.md, PROMPT.md'));
-    if (aiTools.includes('cursor')) console.log(chalk.gray('   • MCP (Cursor): .cursor/mcp.json'));
-    if (aiTools.includes('claude')) console.log(chalk.gray('   • MCP (Claude Code): .mcp.json'));
-    console.log(chalk.gray(`\n   ${fileCount === 1 ? 'This file teaches' : 'These files teach'} your AI assistant about Cloudinary patterns and best practices.`));
-    console.log(chalk.gray(`\n   💡 How to use ${fileCount === 1 ? 'this file' : 'these files'}:`));
-    console.log(chalk.gray('   • Simply open your project in your AI assistant - the configuration is already loaded'));
-    console.log(chalk.gray('   • Ask your AI to help build Cloudinary features, and it will follow these patterns'));
+  if (skillsInstalled > 0) {
+    console.log(chalk.cyan(`\n📋 AI skills installed → .agents/skills/ (works with Cursor, Claude Code, Copilot, and more):`));
+    console.log(chalk.gray('   • cloudinary-docs — looks up live Cloudinary documentation'));
+    console.log(chalk.gray('   • cloudinary-react — uses React SDK patterns and best practices'));
+    console.log(chalk.gray('   • cloudinary-transformations — creates and debugs Cloudinary transformation URLs from natural language instructions'));
+    if (aiTools && aiTools.includes('cursor')) console.log(chalk.gray('   • MCP (Cursor): .cursor/mcp.json'));
+    if (aiTools && aiTools.includes('claude')) console.log(chalk.gray('   • MCP (Claude Code): .mcp.json'));
+    console.log(chalk.gray('\n   💡 How to use:'));
+    console.log(chalk.gray('   • Open your project in your AI assistant — skills are picked up automatically'));
+    console.log(chalk.gray('   • Ask your AI assistant to help build Cloudinary features and it will use these skills'));
     console.log(chalk.gray('   • Example prompts: "Add image upload", "Create a transformation gallery"\n'));
   }
 
diff --git a/skills/cloudinary-docs/SKILL.md b/skills/cloudinary-docs/SKILL.md
new file mode 100644
index 0000000..a9690f2
--- /dev/null
+++ b/skills/cloudinary-docs/SKILL.md
@@ -0,0 +1,53 @@
+---
+name: cloudinary-docs
+description: Local version -- Looks up implementation details in the latest Cloudinary docs via llms.txt. Use when building code or answering questions relating to image or video uploads, optimization, or transformations, and for Cloudinary SDKs, APIs, webhooks, or integrations.
+license: MIT
+metadata:
+  author: cloudinary
+  version: '1.0.1'
+---
+
+# Cloudinary Documentation
+
+Helps developers integrate Cloudinary into their applications by providing documentation and code examples retrieved directly from the optimized markdown files in the Cloudinary documentation.
+
+## When to Use
+
+- When a user asks questions or requests code implementation relating to image or video upload, management, optimization, or transformations (resizing, applying effects, visual improvements, adding overlays, generative AI, etc.)
+- User asks about Cloudinary SDKs, upload APIs, or integration guides
+- General Cloudinary documentation lookup (account settings, webhooks, DAM features)
+- Looking up specific Cloudinary API endpoints or SDK methods
+- Use this skill in conjunction with more specialized Cloudinary skills when relevant.
+
+## Instructions
+
+When answering image and video upload, management, optimization, or transformation questions or when implementing Cloudinary code:
+
+1. **First, get the documentation index** using llms.txt with the llms.txt URL - https://cloudinary.com/documentation/llms.txt
+2. **Analyze the llms.txt content** to understand what documentation pages are available
+3. **Reflect on the user's question** and identify which specific documentation URLs would be most relevant
+4. **Navigate** to the specific relevant documentation URLs from the llms.txt index (you can make multiple calls)
+5. **Use the fetched documentation** to provide a comprehensive, accurate answer or code implementation.  When relevant, use in conjunction with more specialized Cloudinary skills like cloudinary-transformations. The best practices defined in the specialized skills should guide which doc instructions to use.
+
+Example workflows:
+
+**Example 1: Upload question**
+- User asks: "How do I upload images to Cloudinary?"
+- You retrieve the llms.txt index: https://cloudinary.com/documentation/llms.txt
+- You analyze the llms.txt content to understand what documentation pages are available
+- You identify relevant pages like "image_upload.md" or "upload_api.md"
+- You retrieve those specific pages from the llms.txt index
+- You provide an answer with code examples and citations
+
+**Example 2: Transformation question**
+- User asks: "How do I resize and crop images?"
+- You retrieve the llms.txt index
+- You identify relevant pages like "image_transformations.md" or "transformation_reference.md"
+- You fetch the specific documentation
+- You provide transformation syntax and examples
+
+**Example 3: SDK question**
+- User asks: "What's the Node.js SDK for Cloudinary?"
+- You retrieve the llms.txt index
+- You identify SDK-related pages
+- You provide installation instructions and usage examples
\ No newline at end of file
diff --git a/skills/cloudinary-react/SKILL.md b/skills/cloudinary-react/SKILL.md
new file mode 100644
index 0000000..0a34687
--- /dev/null
+++ b/skills/cloudinary-react/SKILL.md
@@ -0,0 +1,486 @@
+---
+name: cloudinary-react
+description: Local version -- Provides opinionated React SDK patterns for configuration, common integration scenarios, and troubleshooting for frequent errors and TypeScript pitfalls. Use when writing code or answering questions related to the Cloudinary React SDK.
+license: MIT
+metadata:
+  author: cloudinary
+  version: '1.0.1'
+---
+
+# Cloudinary React Skill
+
+## When to Use
+
+- When a user is building or debugging Cloudinary in a **React** app (Vite, Create React App, Parcel, etc.).
+- When implementing or fixing: Upload Widget, AdvancedImage/AdvancedVideo, transformations, overlays, image galleries, video player, or signed/unsigned uploads.
+- When the user sees errors like "createUploadWidget is not a function", wrong imports from `@cloudinary/url-gen`, upload preset issues, or video player DOM errors.
+
+
+## Quick Start
+
+**Most common operations:**
+1. **Setup**: Create config file with `cld` instance (see Project setup section)
+2. **Display image**: `const img = cld.image('id').resize(fill().width(800)); <AdvancedImage cldImg={img} />`
+3. **Upload Widget**: Script in index.html + poll for `createUploadWidget` in useEffect
+4. **Image overlay**: Use `source(text(...))` or `source(image(...))` - see Import reference table for exact paths
+5. **Signed uploads**: See [references/signed-uploads.md](references/signed-uploads.md)
+6. **Troubleshooting**: See [references/troubleshooting.md](references/troubleshooting.md)
+
+**For TypeScript**: See [references/typescript-patterns.md](references/typescript-patterns.md)
+**For Video Player**: See [references/video-player.md](references/video-player.md)
+
+
+
+## Instructions
+
+When helping with Cloudinary in React, follow the patterns and rules below. Use the **exact** import paths and code patterns specified; do not guess subpaths or invent APIs.
+
+---
+
+# Cloudinary React SDK Patterns & Common Errors
+
+**Scope**: These rules apply to **React (web)** with the browser Upload Widget. The **default** is **Vite** (create-cloudinary-react uses Vite). They also work with **other bundlers** (Create React App, Next.js, Parcel, etc.): only **how you read env vars** changes; see **"Other bundlers (non-Vite)"** below. Rules-only users: see **"Project setup (rules-only / without CLI)"** for the reusable Cloudinary instance, env, Upload Widget (unsigned/signed), and video player. For **React Native** uploads (including signed upload), see: https://cloudinary.com/documentation/react_native_image_and_video_upload#signed_upload — same "never expose secret, generate signature on backend" principle, but React Native uses the `upload()` method and backend SDKs differently.
+
+## Official Documentation
+
+**For complete API references and all configuration options**, consult the Cloudinary documentation via **llms.txt**: https://cloudinary.com/documentation/llms.txt
+
+This skill provides React patterns and common errors. For detailed API options (e.g., all Upload Widget config properties, Video Player API methods), use the documentation markdown files available through llms.txt.
+
+### Key References
+- **Transformation Rules**: https://cloudinary.com/documentation/cloudinary_transformation_rules.md
+- **Transformation Reference**: https://cloudinary.com/documentation/transformation_reference.md
+- **React Image Transformations & Plugins**: https://cloudinary.com/documentation/react_image_transformations.md#plugins
+- **React Video Transformations**: https://cloudinary.com/documentation/react_video_transformations.md
+- **Upload Widget Reference** (complete config options): https://cloudinary.com/documentation/upload_widget_reference.md
+- **Upload Widget (signed uploads)**: https://cloudinary.com/documentation/upload_widget.md#signed_uploads
+- **Cloudinary Video Player** (standalone player): https://cloudinary.com/documentation/cloudinary_video_player.md
+- **Video Player API Reference** (complete API methods): https://cloudinary.com/documentation/video_player_api_reference.md
+- **Video Player React Tutorial**: https://cloudinary.com/documentation/video_player_react_tutorial.md
+- **Upload assets in Next.js (backend signature)**: https://cloudinary.com/documentation/upload_assets_in_nextjs_tutorial.md
+- **Cloudinary Node.js SDK (server-side signing)** — use **v2**: `import { v2 as cloudinary } from 'cloudinary'`; do not use v1 (e.g. 1.47.0). https://cloudinary.com/documentation/node_integration.md
+- **React Native image and video upload (signed)**: https://cloudinary.com/documentation/react_native_image_and_video_upload.md#signed_upload
+- Always consult the official transformation rules when creating transformations
+- Use only officially supported parameters from the transformation reference
+
+**Golden rule for @cloudinary/url-gen:** When generating overlay or transformation code, use **only** the "Import reference" table and "Canonical overlay block" in these rules. Copy those import paths and usage patterns exactly; do not guess or derive paths (e.g. `text` and `image` are from `qualifiers/source`, not `actions/overlay`; `Position` is from `qualifiers/position`, not `positioning/Position`).
+
+---
+
+# 📋 PATTERNS (How to Do It Right)
+
+## Project setup (rules-only / without CLI)
+
+If the user is **not** using the create-cloudinary-react CLI and only has these rules, generate the following so they get correct config, env, and widget setup.
+
+**1. Environment (.env)**  
+Create a `.env` file in the project root with **Vite prefix** (required for client access):
+- `VITE_CLOUDINARY_CLOUD_NAME_=my_cloud` (required — use your actual cloud name, **never** the literal string `your_cloud_name` which causes 401)
+- `VITE_CLOUDINARY_UPLOAD_PRESET=my_preset` (optional; required for unsigned upload widget — use your actual preset name)
+- **Restart the dev server** after adding or changing `.env`. Use `import.meta.env.VITE_*` in code, not `process.env`.
+- **If env var still empty in browser after restart**: Vite may cache the old value. Clear `node_modules/.vite/`, restart dev server, and do a hard refresh (Cmd+Shift+R / Ctrl+Shift+F5). If still empty, see "Vite env not reaching client" in Common Errors.
+
+**2. Reusable Cloudinary instance (config)**  
+Create a config file (e.g. `src/cloudinary/config.ts`) so the rest of the app can use a single `cld` instance:
+```ts
+import { Cloudinary } from '@cloudinary/url-gen';
+
+const cloudName = import.meta.env.VITE_CLOUDINARY_CLOUD_NAME;
+if (!cloudName) {
+  throw new Error('VITE_CLOUDINARY_CLOUD_NAME is not set. Add it to .env with the VITE_ prefix.');
+}
+
+export const cld = new Cloudinary({ cloud: { cloudName } });
+export const uploadPreset = import.meta.env.VITE_CLOUDINARY_UPLOAD_PRESET || '';
+```
+- Use **this** pattern for the reusable instance. Everywhere else: `import { cld } from './cloudinary/config'` (or the path the user chose) and call `cld.image(publicId)` / `cld.video(publicId)`.
+
+**3. Upload Widget (unsigned, from scratch)**  
+
+**Strict pattern (always follow this exactly):**
+1. **Script in `index.html`** (required): Add `<script src="https://upload-widget.cloudinary.com/global/all.js" async></script>` to `index.html`. Do **not** rely only on dynamic script injection from React — it's fragile.
+2. **Poll in useEffect** (required): In `useEffect`, poll with `setInterval` (e.g. every 100ms) until `typeof window.cloudinary?.createUploadWidget === 'function'`. Only then create the widget. A single check (even in `onload`) is **not** reliable because `window.cloudinary` can exist before `createUploadWidget` is attached.
+3. **Add a timeout**: Set a timeout (e.g. 10 seconds) to stop polling and show an error if the script never loads. Clear both interval and timeout in cleanup.
+4. **Create widget once**: When `createUploadWidget` is available, create the widget and store it in a **ref**. Clear the interval and timeout. Pass options: `{ cloudName, uploadPreset, sources: ['local', 'camera', 'url'], multiple: false }`.
+5. **Open on click**: Attach a click listener to a button that calls `widgetRef.current?.open()`. Remove the listener in useEffect cleanup.
+
+❌ **Do NOT**: Check only `window.cloudinary` (not enough); do a single check in `onload` (unreliable); skip the script in `index.html`; poll forever without a timeout.
+- **Signed uploads**: Do not use only `uploadPreset`; use the pattern under "Secure (Signed) Uploads" (uploadSignature as function, fetch api_key, server includes upload_preset in signature).
+
+**4. Video player**  
+- Use imperative video element only (create with document.createElement, append to container ref, pass to videoPlayer). See "Cloudinary Video Player (The Player)" for the full pattern.
+
+**5. Summary for rules-only users**  
+- **Env**: Use your bundler's client env prefix and access (Vite: `VITE_` + `import.meta.env.VITE_*`; see "Other bundlers" if not Vite).
+- **Reusable instance**: One config file that creates and exports `cld` (and optionally `uploadPreset`) from `@cloudinary/url-gen`; use it everywhere.
+- **Upload widget**: Script in index.html (required); in useEffect, **poll** until `createUploadWidget` is a function, then create widget once and store in ref; unsigned = cloudName + uploadPreset; signed = use uploadSignature function and backend.
+- **Video player**: Imperative video element (createElement, append to container ref, pass to videoPlayer); dispose + removeChild in cleanup; fall back to AdvancedVideo if init fails.
+
+**If the user is not using Vite:** Use their bundler's client env prefix and access in the config file and everywhere you read env. Examples: Create React App → `REACT_APP_CLOUDINARY_CLOUD_NAME`, `process.env.REACT_APP_CLOUDINARY_CLOUD_NAME`; Next.js (client) → `NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME`, `process.env.NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME`. The rest (cld instance, widget options, video player) is the same.
+
+## Environment Variables
+- **Default: Vite** — Vite requires `VITE_` prefix; use `import.meta.env.VITE_CLOUDINARY_CLOUD_NAME` (not `process.env`). Restart dev server after changing `.env`.
+- ✅ CORRECT (Vite): `VITE_CLOUDINARY_CLOUD_NAME=mycloud` in `.env`; `import.meta.env.VITE_CLOUDINARY_CLOUD_NAME`
+- ❌ **WRONG**: `VITE_CLOUDINARY_CLOUD_NAME=your_cloud_name` — **Never** use the literal placeholder `your_cloud_name`; it causes 401 errors. Use your actual cloud name from the Cloudinary dashboard.
+- ⚠️ **Vite env not reaching client**: If `import.meta.env.VITE_CLOUDINARY_CLOUD_NAME` is still `undefined` in the browser after restarting:
+  1. Clear Vite cache: `rm -rf node_modules/.vite/` (or delete `node_modules/.vite` folder)
+  2. Restart dev server: `npm run dev`
+  3. Hard refresh browser: Cmd+Shift+R (Mac) or Ctrl+Shift+F5 (Windows/Linux)
+  4. If still empty, use a **static config** workaround (create a `cloudinaryConfig.ts` with a hardcoded cloud name for dev, then switch back to env later) and see Common Errors → "VITE_ prefix required or env var is undefined"
+
+## Other bundlers (non-Vite)
+- **Only the env access changes.** All other patterns (reusable `cld`, Upload Widget, Video Player, overlays, signed uploads) are bundler-agnostic.
+- **Create React App**: Prefix `REACT_APP_`; access `process.env.REACT_APP_CLOUDINARY_CLOUD_NAME`, `process.env.REACT_APP_CLOUDINARY_UPLOAD_PRESET`. Restart dev server after `.env` changes.
+- **Next.js (client)**: Prefix `NEXT_PUBLIC_` for client; access `process.env.NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME`, etc. Server-side can use `process.env.CLOUDINARY_*` without `NEXT_PUBLIC_`.
+- **Parcel / other**: Check the bundler's docs for "exposing environment variables to the client" (often a prefix or allowlist). Use that prefix and the documented access (e.g. `process.env.*`).
+- **Config file**: In `src/cloudinary/config.ts` (or equivalent), read cloud name and upload preset using the **user's bundler** env API (e.g. for CRA: `process.env.REACT_APP_CLOUDINARY_CLOUD_NAME`). Same `new Cloudinary({ cloud: { cloudName } })` and exports; only the env read line changes.
+
+## Upload Presets
+- **Unsigned** = client-only uploads (no backend). **Signed** = backend required, more secure. See **"Signed vs unsigned uploads"** below for when to use which.
+- ✅ Create unsigned upload preset (for simple client uploads): https://console.cloudinary.com/app/settings/upload/presets
+- ✅ Set preset in `.env`: `VITE_CLOUDINARY_UPLOAD_PRESET=your-preset-name`
+- ✅ Use in code: `import { uploadPreset } from './cloudinary/config'`
+- ⚠️ If upload preset is missing, the Upload Widget will show an error message
+- ⚠️ Upload presets must be set to "Unsigned" mode for client-side usage (no API key/secret needed)
+- **When unsigned upload fails**: First check that the user configured their upload preset:
+  1. Is `VITE_CLOUDINARY_UPLOAD_PRESET` set in `.env`? (must match preset name exactly)
+  2. Does the preset exist in the dashboard under Settings → Upload → Upload presets?
+  3. Is the preset set to **Unsigned** (not Signed)?
+  4. Was the dev server restarted after adding/updating `.env`?
+
+## Installing Cloudinary packages
+- ✅ **Install the latest**: When adding Cloudinary packages, use `npm install <package>` **with no version** so npm installs the latest compatible version (e.g. `npm install cloudinary-video-player`). In package.json use a **caret range** (e.g. `"cloudinary-video-player": "^1.0.0"`) so future installs get the latest compatible. Do not pin to an exact version unless you have verified it exists on npm.
+- ✅ **Package names only**: Use **only** these names: `@cloudinary/react`, `@cloudinary/url-gen`, `cloudinary-video-player` (standalone player), `cloudinary` (Node server-side only). Do not invent names (e.g. no `@cloudinary/video-player`).
+- ❌ **WRONG**: `npm install cloudinary-video-player@1.2.3` or `"cloudinary-video-player": "1.2.3"` (exact pin) — versions may not exist and break installs.
+- ✅ **Correct**: `npm install cloudinary-video-player` (no version) or in package.json: `"cloudinary-video-player": "^1.0.0"` (caret = latest compatible).
+
+## Import Patterns
+- ✅ Import Cloudinary instance: `import { cld } from './cloudinary/config'`
+- ✅ Import components: `import { AdvancedImage, AdvancedVideo } from '@cloudinary/react'`
+- ✅ Import plugins: `import { responsive, lazyload, placeholder } from '@cloudinary/react'`
+- ✅ **For transformations and overlays**, use **only** the exact paths in "Import reference: @cloudinary/url-gen" and the "Canonical overlay block" below. Do **not** guess subpaths (e.g. `text` and `image` are from `qualifiers/source`, not `actions/overlay`).
+
+## Import reference: @cloudinary/url-gen (use these exact paths only)
+
+**Rule:** Do not invent or guess import paths for `@cloudinary/url-gen`. Use **only** the paths in the table and canonical block below. Copy the import statements exactly; do not derive paths (e.g. `@cloudinary/url-gen/overlay` exports only `source` — `text` and `image` are from **`qualifiers/source`**; `Position` is from **`qualifiers/position`**, not `positioning/Position`). Wrong paths cause "module not found" or "does not exist".
+
+| Purpose | Exact import |
+|--------|----------------|
+| Cloudinary instance (config) | `import { Cloudinary } from '@cloudinary/url-gen';` |
+| Resize (fill) | `import { fill } from '@cloudinary/url-gen/actions/resize';` |
+| Resize (scale, for overlays) | `import { scale } from '@cloudinary/url-gen/actions/resize';` |
+| Delivery format/quality | `import { format, quality } from '@cloudinary/url-gen/actions/delivery';` |
+| Format qualifier (auto) | `import { auto } from '@cloudinary/url-gen/qualifiers/format';` |
+| Quality qualifier (auto) | `import { auto as autoQuality } from '@cloudinary/url-gen/qualifiers/quality';` |
+| Effects (e.g. blur) | `import { blur } from '@cloudinary/url-gen/actions/effect';` |
+| Overlay source | `import { source } from '@cloudinary/url-gen/actions/overlay';` |
+| Overlay text / image (source types) | `import { text, image } from '@cloudinary/url-gen/qualifiers/source';` |
+| Overlay image transformation | `import { Transformation } from '@cloudinary/url-gen/transformation/Transformation';` |
+| Position (overlay) | `import { Position } from '@cloudinary/url-gen/qualifiers/position';` |
+| Gravity/compass | `import { compass } from '@cloudinary/url-gen/qualifiers/gravity';` |
+| Text style (overlay) | `import { TextStyle } from '@cloudinary/url-gen/qualifiers/textStyle';` |
+| Types | `import type { CloudinaryImage, CloudinaryVideo } from '@cloudinary/url-gen';` |
+
+**Canonical overlay block (copy these imports and patterns exactly):**
+```ts
+// Overlay imports — text/image from qualifiers/source, NOT actions/overlay
+import { source } from '@cloudinary/url-gen/actions/overlay';
+import { text, image } from '@cloudinary/url-gen/qualifiers/source';
+import { Position } from '@cloudinary/url-gen/qualifiers/position';
+import { TextStyle } from '@cloudinary/url-gen/qualifiers/textStyle';
+import { compass } from '@cloudinary/url-gen/qualifiers/gravity';
+import { Transformation } from '@cloudinary/url-gen/transformation/Transformation';
+import { scale } from '@cloudinary/url-gen/actions/resize';
+
+// Text overlay (compass with underscores: 'south_east', 'center')
+cld.image('id').overlay(
+  source(text('Hello', new TextStyle('Arial', 60).fontWeight('bold')).textColor('white'))
+    .position(new Position().gravity(compass('center')))
+);
+
+// Image overlay (logo/image with resize)
+cld.image('id').overlay(
+  source(image('logo').transformation(new Transformation().resize(scale().width(100))))
+    .position(new Position().gravity(compass('south_east')).offsetX(20).offsetY(20))
+);
+```
+
+- **Components** (AdvancedImage, AdvancedVideo, plugins) come from **`@cloudinary/react`**, not from `@cloudinary/url-gen`.
+- **Transformation actions and qualifiers** (resize, delivery, effect, overlay, etc.) come from **`@cloudinary/url-gen/actions/*`** and **`@cloudinary/url-gen/qualifiers/*`** with the exact subpaths above.
+- If an import fails, verify the package version (`@cloudinary/url-gen` in package.json) and the [Cloudinary URL-Gen SDK docs](https://cloudinary.com/documentation/sdks/js/url-gen/index.html) or [Transformation Builder reference](https://cloudinary.com/documentation/sdks/js/transformation_builder_reference).
+
+## Creating Image & Video Instances
+- ✅ Create image instance: `const img = cld.image(publicId)`
+- ✅ Create video instance: `const video = cld.video(publicId)` (same pattern as images)
+- ✅ Public ID format: Use forward slashes for folders (e.g., `'folder/subfolder/image'`)
+- ✅ Public IDs are case-sensitive and should not include file extensions
+- ✅ **Sample assets**: Cloudinary may provide sample assets under `samples/`. **Assume they might not exist** (users can delete them); always handle load errors and provide fallbacks (see Image gallery). When they exist, use them for examples and demos instead of requiring uploads first.
+- ✅ **Sample public IDs that may be available** (use for galleries, demos; handle onError if missing):
+  - Images: `samples/cloudinary-icon`, `samples/two-ladies`, `samples/food/spices`, `samples/landscapes/beach-boat`, `samples/bike`, `samples/landscapes/girl-urban-view`, `samples/animals/reindeer`, `samples/food/pot-mussels`
+  - Video: `samples/elephants`
+- ✅ **Default / most reliable**: Start with `samples/cloudinary-icon` for a single image; use the list above for galleries or variety. Prefer uploaded assets when the user has them.
+- ✅ Examples:
+  ```tsx
+  const displayImage = cld.image('samples/cloudinary-icon');
+  const displayVideo = cld.video('samples/elephants');
+  // Gallery: e.g. ['samples/bike', 'samples/landscapes/beach-boat', 'samples/food/spices', ...]
+  ```
+
+## Transformation Patterns
+
+### Image Transformations
+- ✅ Chain transformations on image instance:
+  ```tsx
+  const img = cld.image('id')
+    .resize(fill().width(800).height(600))
+    .effect(blur(800))
+    .delivery(format(auto()))
+    .delivery(quality(autoQuality()));
+  ```
+- ✅ Pass to component: `<AdvancedImage cldImg={img} />`
+
+### Video Transformations
+- ✅ Chain transformations on video instance (same pattern as images):
+  ```tsx
+  const video = cld.video('id')
+    .resize(fill().width(800).height(600))
+    .delivery(format(auto()));
+  ```
+- ✅ Pass to component: `<AdvancedVideo cldVid={video} />`
+- ✅ Video transformations work the same way as image transformations
+
+### Transformation Best Practices
+- ✅ Format and quality must use separate `.delivery()` calls
+- ✅ Always end with auto format/quality: `.delivery(format(auto())).delivery(quality(autoQuality()))` unless user specifies a particular format or quality
+- ✅ Use `gravity(auto())` unless user specifies a focal point
+- ✅ Same transformation syntax works for both images and videos
+
+## Plugin Patterns
+- ✅ **When the user asks for lazy loading or responsive images**: Use the **Cloudinary plugins** from `@cloudinary/react` — `responsive()`, `lazyload()`, `placeholder()` — with `AdvancedImage`. Do not use only native `loading="lazy"` or CSS-only responsive; the Cloudinary plugins handle breakpoints, lazy loading, and placeholders for Cloudinary URLs.
+- ✅ Import plugins from `@cloudinary/react`
+- ✅ Pass plugins as array: `plugins={[responsive(), lazyload(), placeholder()]}`
+- ✅ Recommended plugin order:
+  1. `responsive()` - First (handles breakpoints)
+  2. `placeholder()` - Second (shows placeholder while loading)
+  3. `lazyload()` - Third (delays loading until in viewport)
+  4. `accessibility()` - Last (if needed)
+- ✅ Always add `width` and `height` attributes to prevent layout shift
+- ✅ Example:
+  ```tsx
+  <AdvancedImage
+    cldImg={img}
+    plugins={[responsive(), placeholder({ mode: 'blur' }), lazyload()]}
+    width={800}
+    height={600}
+  />
+  ```
+
+## Responsive Images Pattern
+- ✅ **Responsive images**: Use the Cloudinary `responsive()` plugin with `fill()` resize (not only CSS). **Lazy loading**: Use the Cloudinary `lazyload()` plugin with `AdvancedImage` (not only `loading="lazy"`).
+- ✅ Use `responsive()` plugin with `fill()` resize
+- ✅ Combine with `placeholder()` and `lazyload()` plugins
+- ✅ Example:
+  ```tsx
+  const img = cld.image('id').resize(fill().width(800));
+  <AdvancedImage 
+    cldImg={img} 
+    plugins={[responsive(), placeholder({ mode: 'blur' }), lazyload()]} 
+    width={800}
+    height={600}
+  />
+  ```
+
+## Image gallery with lazy loading and responsive
+- ✅ **When the user asks for an image gallery with lazy loading and responsive**: Use Cloudinary **plugins** with `AdvancedImage`: `responsive()`, `lazyload()`, `placeholder()` (see Plugin Patterns). Use `fill()` resize with the responsive plugin. Add `width` and `height` to prevent layout shift.
+- ✅ **Sample assets in galleries**: Use the sample public IDs from "Creating Image & Video Instances" (e.g. `samples/bike`, `samples/landscapes/beach-boat`, `samples/food/spices`, `samples/two-ladies`, `samples/landscapes/girl-urban-view`, `samples/animals/reindeer`, `samples/food/pot-mussels`, `samples/cloudinary-icon`). **Assume any sample might not exist** — users can delete them. Start with one reliable sample (e.g. `samples/cloudinary-icon`) or a short list; add **onError** handling and remove/hide failed images. Prefer **uploaded** assets when available (e.g. from UploadWidget) over samples.
+- ✅ **Handle load errors**: Use `onError` on `AdvancedImage` to hide or remove failed images (e.g. set state to filter out the publicId, or hide the parent). Provide user feedback (e.g. "Some images could not be loaded. Try uploading your own!") and upload functionality so users can add their own images.
+- ✅ **Fallback**: Default gallery list can be a subset of the sample list (e.g. `['samples/cloudinary-icon', 'samples/bike', 'samples/landscapes/beach-boat']`); when user uploads, append `result.public_id`. If an image fails to load, remove it from the list or hide it so the UI doesn't show broken images.
+
+## Image Overlays (text or logos)
+- ✅ **When the user asks for image overlays with text or logos**: Use `@cloudinary/url-gen` overlay APIs. Copy imports and patterns from the **"Import reference"** table and **"Canonical overlay block"** in these rules. Do not import `text` or `image` from `actions/overlay` — they are from **`qualifiers/source`**; only `source` is from `actions/overlay`.
+- ✅ **Import** `source` from `actions/overlay`; **`text` and `image` from `qualifiers/source`**. Also: `Position` from `qualifiers/position`, `TextStyle` from `qualifiers/textStyle`, `compass` from `qualifiers/gravity`, `Transformation` from `transformation/Transformation`, `scale` from `actions/resize`.
+- ✅ **compass()** takes **string** values, with **underscores**: `compass('center')`, `compass('south_east')`, `compass('north_west')`. ❌ WRONG: `compass(southEast)` or `'southEast'` (no camelCase).
+- ✅ **Overlay image**: Use `new Transformation()` **inside** `.transformation()`: `image('logo').transformation(new Transformation().resize(scale().width(100)))`. ❌ WRONG: `image('logo').transformation().resize(...)` (`.transformation()` does not return a chainable object).
+- ✅ **Text overlay**: `fontWeight` goes on **TextStyle**: `new TextStyle('Arial', 60).fontWeight('bold')`. `textColor` goes on the **text source** (chained after `text(...)`): `text('Hello', new TextStyle('Arial', 60)).textColor('white')`.
+- ✅ **Position** is chained **after** `source(...)`, not inside: `source(image('logo').transformation(...)).position(new Position().gravity(compass('south_east')).offsetX(20).offsetY(20))`.
+- ✅ **Image overlay pattern**: `baseImage.overlay(source(image('id').transformation(new Transformation().resize(scale().width(100)))).position(new Position().gravity(compass('south_east')).offsetX(20).offsetY(20)))`. (Import `scale` from `@cloudinary/url-gen/actions/resize` if needed.)
+- ✅ **Text overlay pattern**: `baseImage.overlay(source(text('Your Text', new TextStyle('Arial', 60).fontWeight('bold')).textColor('white')).position(new Position().gravity(compass('center'))))`.
+- ✅ Docs: React Image Transformations and transformation reference for overlay syntax.
+
+## Upload Widget Pattern
+- ✅ Use component: `import { UploadWidget } from './cloudinary/UploadWidget'`
+
+**Strict initialization pattern (always follow this exactly):**
+1. ✅ **Script in `index.html`** (required):
+  ```html
+  <script src="https://upload-widget.cloudinary.com/global/all.js" async></script>
+  ```
+2. ✅ **Poll in useEffect until `createUploadWidget` is available** (required): Use `setInterval` (e.g. every 100ms) to check `typeof window.cloudinary?.createUploadWidget === 'function'`. Only create the widget when this returns `true`. Clear the interval once ready.
+3. ✅ **Add a timeout** (e.g. 10 seconds) to stop polling and show an error state if the script never loads. Clear both interval and timeout in cleanup and when ready.
+4. ✅ **Create widget once**, store in a ref. Cleanup: clear interval, clear timeout, remove click listener.
+
+❌ **Do NOT**: Check only `window.cloudinary` (the function may not be attached yet); do a single check in `onload` (unreliable timing); skip `index.html` and rely only on dynamic injection; poll forever without a timeout.
+
+- ✅ Create unsigned upload preset in dashboard at `settings/upload/presets`
+- ✅ Add to `.env`: `VITE_CLOUDINARY_UPLOAD_PRESET=your_preset_name`
+- ✅ Handle callbacks:
+  ```tsx
+  <UploadWidget
+    onUploadSuccess={(result) => {
+      console.log('Public ID:', result.public_id);
+    }}
+    onUploadError={(error) => {
+      console.error('Upload failed:', error);
+    }}
+  />
+  ```
+- ✅ Upload result contains: `public_id`, `secure_url`, `width`, `height`, etc.
+
+**For complete Upload Widget configuration options** (all properties for `createUploadWidget`), see the official reference: https://cloudinary.com/documentation/upload_widget_reference.md
+
+## Signed vs unsigned uploads (when to use which)
+
+**Unsigned uploads** (simpler, no backend required):
+- Use when: Quick prototypes, low-risk apps, or when anyone with the preset name may upload.
+- Preset: Create an **Unsigned** upload preset in Cloudinary dashboard (Settings → Upload → Upload presets). Put preset name in `.env` as `VITE_CLOUDINARY_UPLOAD_PRESET`.
+- Client: Widget needs only `cloudName` and `uploadPreset`. No API key or secret; no backend.
+- Trade-off: Anyone who knows the preset name can upload. Use only when that is acceptable.
+
+**Signed uploads** (more secure, backend required):
+- Use when: Production apps, authenticated users, or when you need to control who can upload.
+- Preset: Create a **Signed** upload preset in the dashboard. The backend generates a signature using your API secret; the client never sees the secret.
+- Client: Widget gets `api_key` (from your backend), `uploadPreset`, and an `uploadSignature` **function** that calls your backend for each upload. API secret stays on server only.
+- Trade-off: Requires a backend (Node/Express, Next.js API route, etc.) to sign requests. More secure; signature validates each upload.
+
+**Rule of thumb**: **Default to unsigned uploads** unless the user explicitly asks for "secure" or "signed" uploads. Do not default to signed — it requires a running backend and will fail out of the box. Use **signed** only when the user explicitly requests secure/signed uploads or needs to restrict who can upload.
+
+## Secure (Signed) Uploads
+
+**When to use:** Production apps, authenticated users, or when you need to control who can upload (more secure than unsigned).
+
+**Golden rules:** 
+1. Never expose or commit the API secret (server-only)
+2. Use `server/.env` in `.gitignore` for API key/secret
+3. API key can be sent to client; API secret must stay server-only
+
+**Quick implementation:**
+- Use `uploadSignature` as function (not `signatureEndpoint`)
+- Fetch `api_key` from server before creating widget
+- Include `uploadPreset` in widget config
+- Server includes `upload_preset` in signed params
+- Use Cloudinary Node.js SDK v2 on server
+
+For complete implementation patterns, client/server code examples, and troubleshooting, see [references/signed-uploads.md](references/signed-uploads.md)
+
+## Video Patterns
+
+- ✅ **Display a video** → Use **AdvancedVideo** (`@cloudinary/react`). It just displays a video (with optional transformations). Not a full player.
+- ✅ **A video player** → Use **Cloudinary Video Player** (`cloudinary-video-player`). That is the actual player (styled UI, controls, playlists, etc.).
+
+### ⚠️ IMPORTANT: Two Different Approaches
+
+**1. AdvancedVideo** (`@cloudinary/react`) — For **displaying** a video
+- React component similar to `AdvancedImage`; just displays a video with Cloudinary transformations
+- Not a full "player" — it's video display (native HTML5 video with optional controls)
+- Use when: user wants to show/display a video. Works with `cld.video()` like images with `cld.image()`
+
+**2. Cloudinary Video Player** (`cloudinary-video-player`) — The **player**
+- Full-featured video player (styled UI, controls, playlists). Use when the user asks for a "video player."
+- **Use imperative video element only** (create with document.createElement, append to container ref); do not pass a React-managed `<video ref>`. See "Cloudinary Video Player (The Player)" below.
+
+### AdvancedVideo (React SDK - For Displaying a Video)
+- ✅ **Purpose**: Display a video with Cloudinary transformations (resize, effects, etc.). It is **not** a full player — it is for showing a video. For a player, use Cloudinary Video Player.
+- ✅ **Package**: `@cloudinary/react` (same as AdvancedImage)
+- ✅ **Import**: `import { AdvancedVideo } from '@cloudinary/react'`
+- ✅ **NO CSS IMPORT NEEDED**: AdvancedVideo uses native HTML5 video - no CSS import required
+- ❌ **WRONG**: `import '@cloudinary/react/dist/cld-video-player.css'` (this path doesn't exist)
+- ✅ **Create video instance**: `const video = cld.video(publicId)` (like `cld.image()`)
+- ✅ **Apply transformations**: Chain transformations like images:
+  ```tsx
+  const video = cld.video('video-id')
+    .resize(fill().width(800).height(600))
+    .delivery(format(auto()));
+  ```
+- ✅ **Use component**:
+  ```tsx
+  <AdvancedVideo
+    cldVid={video}
+    controls
+    autoplay
+    muted
+  />
+  ```
+- ✅ **Documentation**: https://cloudinary.com/documentation/react_video_transformations.md
+
+### Cloudinary Video Player (The Player)
+Use when the user asks for a **video player** (styled UI, controls, playlists). For just **displaying** a video, use AdvancedVideo instead.
+
+**Critical rule: Imperative element only**
+- ❌ Do NOT pass React-managed `<video ref>` (causes removeChild errors)
+- ✅ Use `document.createElement('video')`, append to container ref, pass to `videoPlayer(el, ...)`
+
+**Quick setup:**
+- Package: `npm install cloudinary-video-player`
+- Import: `import { videoPlayer } from 'cloudinary-video-player'` and CSS
+- Source: `player.source({ publicId })` (object, not string)
+- Cleanup: `player.dispose()` then `if (el.parentNode) el.parentNode.removeChild(el)`
+- Always include `posterOptions: { transformation: { startOffset: '0' }, posterColor: '#0f0f0f' }`
+
+For complete implementation pattern, cleanup, error handling, and troubleshooting, see [references/video-player.md](references/video-player.md)
+
+### When to Use Which?
+- ✅ **Use AdvancedVideo** when: User wants to **display** or **show** a video (no full player). It just displays a video with transformations.
+- ✅ **Use Cloudinary Video Player** when: User asks for a **video player** — the actual player with styled UI, controls, and optional features (playlists, ads, etc.).
+
+## TypeScript Patterns
+
+**Essential TypeScript usage:**
+- Type imports: `import type { CloudinaryImage, CloudinaryVideo } from '@cloudinary/url-gen'`
+- Upload results: Define `CloudinaryUploadResult` interface
+- Environment variables: Create `vite-env.d.ts` with `ImportMetaEnv` interface
+- Avoid `any`: Use proper interfaces or `unknown` with type guards
+- Type refs: `useRef<HTMLVideoElement>(null)`, `useRef<unknown>(null)` for widgets
+
+For complete TypeScript patterns, type guards, ref typing, and error solutions, see [references/typescript-patterns.md](references/typescript-patterns.md)
+
+## Best Practices
+- ✅ Always use `fill()` resize with automatic gravity for responsive images
+- ✅ Always end transformations with `.delivery(format(auto())).delivery(quality(autoQuality()))` unless the user specifies a format or quality
+- ✅ Use `placeholder()` and `lazyload()` plugins together
+- ✅ Always add `width` and `height` attributes to `AdvancedImage`
+- ✅ Store `public_id` from upload success, not full URL
+- ✅ Video player: use imperative element only; dispose in useLayoutEffect cleanup and remove element with `if (el.parentNode) el.parentNode.removeChild(el)`; always include `posterOptions` with `transformation: { startOffset: '0' }` and `posterColor: '#0f0f0f'` for reliable poster display
+- ✅ Use TypeScript for better autocomplete and error catching
+- ✅ Prefer `unknown` over `any` when types aren't available
+- ✅ Use type guards for runtime type checking
+- ✅ Define interfaces for Cloudinary API responses
+- ✅ Create `vite-env.d.ts` for environment variable typing
+- ✅ Use proper HTML element types for refs
+
+---
+
+# ⚠️ COMMON ERRORS & SOLUTIONS
+
+For detailed error solutions and troubleshooting, see [references/troubleshooting.md](references/troubleshooting.md)
+
+## Quick Error Reference
+
+### Environment Variable Errors
+- **Env vars**: Wrong prefix, missing VITE_, not restarted → Use correct bundler prefix, restart, clear cache
+- **Imports**: Wrong package/path → Use exact paths from Import reference table
+- **Upload Widget**: "createUploadWidget is not a function" → Poll with setInterval, don't check only `window.cloudinary`
+- **Transformations**: Not working → Chain properly, use v2 syntax, separate format/quality
+- **Video Player**: removeChild errors → Use imperative element (createElement), not React ref
+- **TypeScript**: Type errors → See [references/typescript-patterns.md](references/typescript-patterns.md)
+- **Signed uploads**: Invalid signature → See [references/signed-uploads.md](references/signed-uploads.md)
+
+## Most Common Issues
+
+1. **Environment variables undefined**: Clear `node_modules/.vite/`, restart dev server, hard refresh browser
+2. **"createUploadWidget is not a function"**: Poll with `setInterval` until `typeof window.cloudinary?.createUploadWidget === 'function'`
+3. **Wrong imports**: Use ONLY paths from Import reference table - don't guess subpaths
+4. **Upload fails**: Check preset exists, is Unsigned (for unsigned), dev server restarted
+5. **Video player errors**: Use imperative element only, include posterOptions
+6. **Overlay issues**: Import `text`/`image` from `qualifiers/source`, not `actions/overlay`
+
+For complete troubleshooting with detailed solutions, see [references/troubleshooting.md](references/troubleshooting.md)
diff --git a/skills/cloudinary-react/references/signed-uploads.md b/skills/cloudinary-react/references/signed-uploads.md
new file mode 100644
index 0000000..0a6b7de
--- /dev/null
+++ b/skills/cloudinary-react/references/signed-uploads.md
@@ -0,0 +1,130 @@
+# Secure (Signed) Uploads
+
+Complete guide for implementing signed uploads with Cloudinary.
+
+## Golden Rules
+
+1. **Never expose or commit the API secret** - server-only
+2. **Never commit API key or secret** - use `server/.env` in `.gitignore`
+3. **API key** is not secret (can be sent to client); **API secret** must stay server-only
+
+## Where to Put API Key and Secret
+
+**Do NOT** put in root `.env` used by Vite.
+
+✅ Create `server/.env`:
+```
+CLOUDINARY_CLOUD_NAME=your_cloud
+CLOUDINARY_API_KEY=your_key
+CLOUDINARY_API_SECRET=your_secret
+```
+
+✅ Add `server/.env` to `.gitignore`
+✅ Load only in server: `dotenv.config({ path: 'server/.env' })`
+✅ Read only in server code: `process.env.CLOUDINARY_API_SECRET`
+✅ Use Cloudinary Node.js SDK v2: `import { v2 as cloudinary } from 'cloudinary'`
+
+## Client Pattern (Working Implementation)
+
+Use `uploadSignature` as a function (not `signatureEndpoint`):
+
+```tsx
+// 1. Fetch api_key from server first
+const response = await fetch('/api/sign-image');
+const data = await response.json();
+
+// 2. Configure widget
+const widgetConfig = {
+  cloudName: 'your_cloud',
+  api_key: data.api_key, // from server
+  uploadPreset: 'ml_default', // or your signed preset
+  uploadSignature: function(callback, params_to_sign) {
+    const paramsWithPreset = { 
+      ...params_to_sign, 
+      upload_preset: 'ml_default' 
+    };
+    
+    fetch('/api/sign-image', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ params_to_sign: paramsWithPreset }),
+    })
+      .then(r => r.json())
+      .then(data => data.signature ? callback(data.signature) : callback(''))
+      .catch(() => callback(''));
+  }
+};
+
+// 3. Create widget with config
+window.cloudinary.createUploadWidget(widgetConfig, callback);
+```
+
+## Server Pattern (Node/Express with SDK v2)
+
+```ts
+import { v2 as cloudinary } from 'cloudinary';
+
+app.post('/api/sign-image', (req, res) => {
+  const params = req.body.params_to_sign || {};
+  const paramsToSign = { 
+    ...params, 
+    upload_preset: params.upload_preset || 'ml_default' 
+  };
+  
+  const signature = cloudinary.utils.api_sign_request(
+    paramsToSign, 
+    process.env.CLOUDINARY_API_SECRET
+  );
+  
+  res.json({ 
+    signature, 
+    timestamp: paramsToSign.timestamp, 
+    api_key: process.env.CLOUDINARY_API_KEY,
+    cloud_name: process.env.CLOUDINARY_CLOUD_NAME 
+  });
+});
+```
+
+## Rules for Secure Uploads
+
+✅ Use signed upload preset (dashboard → Upload presets → Signed)
+✅ Default preset: `ml_default` (if not deleted by user)
+✅ Generate signature on server only using SDK v2
+✅ Keep `server/.env` in `.gitignore`
+✅ Use `uploadSignature` as function
+✅ Include `uploadPreset` in widget config
+✅ Server must include `upload_preset` in signed params
+
+## What NOT to Do
+
+❌ Never put API secret in `VITE_` or `NEXT_PUBLIC_` variable
+❌ Never commit API key or secret
+❌ Do not generate signature in client-side JavaScript
+❌ Do not use unsigned preset for secure uploads
+❌ Do not omit `uploadPreset` from widget config
+❌ Do not use Cloudinary Node SDK v1 - use v2
+❌ Do not rely on `signatureEndpoint` - use `uploadSignature` function
+
+## Debugging Signed Uploads
+
+### "Invalid Signature"
+- Check: Using `uploadSignature` function? `api_key` fetched from server? `uploadPreset` in widget config? Server includes `upload_preset` in signature?
+
+### "Missing required parameter - api_key"
+- Fetch `api_key` from server before creating widget
+- API key is NOT secret - safe to use in client
+
+### Preset doesn't exist
+- Use `ml_default` if available (default signed preset)
+- Or create signed preset in dashboard
+
+## Next.js Specifics
+
+- Root `.env.local`: Server-only vars (no `NEXT_PUBLIC_`)
+- Client vars need `NEXT_PUBLIC_` prefix
+- API secret goes in server-only section (no prefix)
+
+## Documentation
+
+- [Upload Widget - Signed Uploads](https://cloudinary.com/documentation/upload_widget.md#signed_uploads)
+- [Upload assets in Next.js](https://cloudinary.com/documentation/upload_assets_in_nextjs_tutorial.md)
diff --git a/skills/cloudinary-react/references/troubleshooting.md b/skills/cloudinary-react/references/troubleshooting.md
new file mode 100644
index 0000000..fcb99e7
--- /dev/null
+++ b/skills/cloudinary-react/references/troubleshooting.md
@@ -0,0 +1,131 @@
+# Common Errors & Solutions
+
+This reference contains detailed solutions for common Cloudinary React errors.
+
+## Environment Variable Errors
+
+### "Where do I create the Cloudinary instance?" / "Config with Vite prefix"
+- ❌ Problem: No config file or wrong env prefix
+- ✅ Create `src/cloudinary/config.ts` with: `import { Cloudinary } from '@cloudinary/url-gen'`, read `import.meta.env.VITE_CLOUDINARY_CLOUD_NAME`, create and export `cld` instance
+
+### "Cloud name is required"
+- ❌ Problem: `VITE_CLOUDINARY_CLOUD_NAME` not set
+- ✅ Solution: Check `.env` exists, has `VITE_` prefix, restart dev server
+
+### "VITE_ prefix required" or env var is undefined
+- ❌ Problem: Wrong prefix or Vite cached old value
+- ✅ Vite: Use `VITE_` prefix and `import.meta.env.VITE_*`
+- ✅ Other bundlers: CRA uses `REACT_APP_`, Next.js client uses `NEXT_PUBLIC_`
+- ✅ If still undefined: Clear `node_modules/.vite/`, restart, hard refresh (Cmd+Shift+R)
+
+### Using literal placeholder "your_cloud_name" causes 401
+- ❌ Problem: Used placeholder string instead of actual cloud name
+- ✅ Solution: Replace with your actual cloud name from dashboard
+
+## Import Errors
+
+### "Cannot find module" or wrong import
+- ❌ Problem: Wrong package or subpath
+- ✅ Use ONLY exact paths from Import reference table
+- ✅ Components/plugins: `@cloudinary/react`
+- ✅ Transformations: `@cloudinary/url-gen` with exact subpaths (e.g. `actions/resize`, `qualifiers/source`)
+
+## Transformation Errors
+
+### "Transformation not working" or image looks wrong
+- ✅ Check: transformation is chained, correct imports, valid public_id, v2 syntax
+- ✅ Format/quality must be separate: `.delivery(format(auto())).delivery(quality(autoQuality()))`
+
+### Wrong transformation syntax
+- ❌ WRONG: `<AdvancedImage src="image.jpg" width={800} />`
+- ✅ CORRECT: `const img = cld.image('id').resize(fill().width(800)); <AdvancedImage cldImg={img} />`
+
+## Plugin Errors
+
+### "Responsive images not working" or "Placeholder issues"
+- ✅ Must use `responsive()` with `fill()` resize
+- ✅ Include both `placeholder()` and `lazyload()` plugins
+- ✅ Always add `width` and `height` attributes
+
+### Plugins not working
+- ❌ WRONG: `<AdvancedImage cldImg={img} lazyLoad placeholder />`
+- ✅ CORRECT: `<AdvancedImage cldImg={img} plugins={[lazyload(), placeholder()]} />`
+
+## Upload Widget Errors
+
+### Upload fails (unsigned) — check upload preset first
+- ✅ Debug checklist: 1) Preset configured in `.env`? 2) Exists in dashboard? 3) Is Unsigned? 4) Dev server restarted?
+
+### "Upload preset not found"
+- ✅ Create unsigned preset in dashboard, copy exact name to `.env`, restart
+
+### Widget not opening
+- ✅ Script in `index.html`
+- ✅ Poll with `setInterval` until `typeof window.cloudinary?.createUploadWidget === 'function'`
+
+### "createUploadWidget is not a function"
+- ❌ Problem: Race condition - script loads async
+- ✅ Always poll in useEffect: `setInterval` checking `typeof window.cloudinary?.createUploadWidget === 'function'`
+- ❌ Do NOT: Check only `window.cloudinary`; single check in `onload`
+
+### User needs secure/signed uploads
+- ✅ See [signed-uploads.md](signed-uploads.md) for complete implementation
+
+### "Invalid Signature" or "Missing required parameter - api_key"
+- ✅ Use `uploadSignature` as function (not `signatureEndpoint`)
+- ✅ Fetch `api_key` from server first
+- ✅ Include `uploadPreset` in widget config
+- ✅ Server must include `upload_preset` in signed params
+- ✅ Use Cloudinary Node.js SDK v2
+
+## Video Errors
+
+### "AdvancedVideo not working"
+- ✅ Verify: using `AdvancedVideo` from `@cloudinary/react`, video instance created, NO CSS import needed
+- ❌ WRONG: `import '@cloudinary/react/dist/cld-video-player.css'` (doesn't exist)
+
+### "Video player not working"
+- ✅ Use imperative element: `document.createElement('video')`, append to container ref
+- ✅ See [video-player.md](video-player.md) for complete pattern
+
+### Confusion between AdvancedVideo and Video Player
+- **AdvancedVideo**: For displaying a video (not a full player)
+- **Cloudinary Video Player**: The player (styled UI, controls, playlists)
+
+### Video player: poster image missing or broken
+- ✅ Always include `posterOptions: { transformation: { startOffset: '0' }, posterColor: '#0f0f0f' }`
+
+## Overlay Errors
+
+### "Cannot read properties of undefined" or overlay not showing
+- ✅ Import `source` from `actions/overlay`
+- ✅ Use string values for compass: `compass('south_east')` (underscores)
+- ✅ Use `new Transformation()` inside `.transformation()`
+- ✅ `fontWeight` on TextStyle, `textColor` on text source
+
+### Wrong import path for `text` or `image`
+- ❌ Wrong: Importing from `actions/overlay`
+- ✅ Correct: `text` and `image` from `qualifiers/source`
+
+## TypeScript Errors
+
+See [typescript-patterns.md](typescript-patterns.md) for complete TypeScript patterns and solutions.
+
+### Common TypeScript issues:
+- Missing types: Import from `@cloudinary/url-gen`
+- Using `any`: Define proper interfaces or use `unknown`
+- Missing window.cloudinary type: Add global declaration
+- Missing env var types: Create `vite-env.d.ts`
+- Incorrect ref typing: Use proper HTML element types
+
+## Quick Debug Checklist
+
+When something isn't working:
+- [ ] Environment variables use correct bundler prefix (VITE_, REACT_APP_, NEXT_PUBLIC_)
+- [ ] Dev server restarted after .env changes
+- [ ] Env var undefined? Clear `node_modules/.vite/`, restart, hard refresh
+- [ ] Imports use exact paths from Import reference table
+- [ ] Upload Widget: script in index.html, poll for createUploadWidget
+- [ ] Video Player: imperative element only, include posterOptions
+- [ ] Upload fails? Check preset exists and is Unsigned (for unsigned uploads)
+- [ ] Signed uploads? See signed-uploads.md for complete pattern
diff --git a/skills/cloudinary-react/references/typescript-patterns.md b/skills/cloudinary-react/references/typescript-patterns.md
new file mode 100644
index 0000000..482e5d7
--- /dev/null
+++ b/skills/cloudinary-react/references/typescript-patterns.md
@@ -0,0 +1,133 @@
+# TypeScript Patterns
+
+Complete TypeScript patterns for Cloudinary React integration.
+
+## Type Imports
+
+```tsx
+import type { CloudinaryImage, CloudinaryVideo } from '@cloudinary/url-gen';
+
+const img: CloudinaryImage = cld.image('id');
+const video: CloudinaryVideo = cld.video('id');
+```
+
+## Upload Result Types
+
+```tsx
+interface CloudinaryUploadResult {
+  public_id: string;
+  secure_url: string;
+  url: string;
+  width: number;
+  height: number;
+  format: string;
+  resource_type: string;
+  bytes: number;
+  created_at: string;
+}
+
+// Type callbacks
+onUploadSuccess?: (result: CloudinaryUploadResult) => void;
+```
+
+❌ WRONG: `onUploadSuccess?: (result: any) => void`
+✅ CORRECT: Use proper interface
+
+## Environment Variable Typing
+
+Create `vite-env.d.ts`:
+
+```tsx
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_CLOUDINARY_CLOUD_NAME: string;
+  readonly VITE_CLOUDINARY_UPLOAD_PRESET?: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}
+```
+
+## Type Guards
+
+```tsx
+function isUploadWidgetReady(): boolean {
+  return typeof window !== 'undefined' && 
+         typeof window.cloudinary?.createUploadWidget === 'function';
+}
+
+// Always poll in useEffect with timeout
+const interval = setInterval(() => {
+  if (isUploadWidgetReady()) {
+    clearInterval(interval);
+    clearTimeout(timeout);
+    window.cloudinary.createUploadWidget(...);
+  }
+}, 100);
+```
+
+## Ref Typing
+
+```tsx
+// Video element
+const videoRef = useRef<HTMLVideoElement>(null);
+
+// Button
+const buttonRef = useRef<HTMLButtonElement>(null);
+
+// Widget (use unknown if types not available)
+const widgetRef = useRef<unknown>(null);
+```
+
+## Type Narrowing
+
+```tsx
+const preset = uploadPreset || undefined; // Type: string | undefined
+
+if (uploadPreset) {
+  // TypeScript knows uploadPreset is string here
+  console.log(preset.length);
+}
+```
+
+## Avoid `any` Type
+
+❌ WRONG: `const result: any = ...`
+✅ CORRECT: Use proper interface or `unknown` with type guards
+
+```tsx
+function handleResult(result: unknown) {
+  if (result && typeof result === 'object' && 'public_id' in result) {
+    const uploadResult = result as CloudinaryUploadResult;
+    // Use uploadResult
+  }
+}
+```
+
+## Window Type Declaration
+
+```tsx
+declare global {
+  interface Window {
+    cloudinary?: {
+      createUploadWidget: (config: any, callback: any) => any;
+    };
+  }
+}
+```
+
+## Common TypeScript Errors
+
+### "Property 'cloudinary' does not exist on type 'Window'"
+✅ Add global type declaration above
+
+### "Property 'VITE_CLOUDINARY_CLOUD_NAME' does not exist"
+✅ Create `vite-env.d.ts` with ImportMetaEnv interface
+
+### "Type 'null' is not assignable to type 'RefObject'"
+✅ Use proper HTML element type: `useRef<HTMLVideoElement>(null)`
+
+### "Parameter implicitly has 'any' type"
+✅ Define proper interface for callbacks and results
diff --git a/skills/cloudinary-react/references/video-player.md b/skills/cloudinary-react/references/video-player.md
new file mode 100644
index 0000000..94e89a2
--- /dev/null
+++ b/skills/cloudinary-react/references/video-player.md
@@ -0,0 +1,165 @@
+# Cloudinary Video Player
+
+Complete implementation guide for Cloudinary Video Player in React.
+
+## When to Use
+
+- ✅ Use **Cloudinary Video Player** when user asks for a "video player" (styled UI, controls, playlists)
+- ✅ Use **AdvancedVideo** when just displaying a video (no full player needed)
+
+## Critical Rule: Imperative Element Only
+
+**Do NOT** pass a React-managed `<video ref={...} />` to the player. The library mutates the DOM and React will throw removeChild errors.
+
+✅ Create element with `document.createElement('video')`
+✅ Append to container ref
+✅ Pass that element to `videoPlayer(el, ...)`
+
+## Installation
+
+```bash
+npm install cloudinary-video-player
+```
+
+## Imports
+
+```tsx
+import { videoPlayer } from 'cloudinary-video-player';
+import 'cloudinary-video-player/cld-video-player.min.css';
+```
+
+Note: No `dist/` in CSS path - package exposes `lib/` paths via exports
+
+## Complete Implementation Pattern
+
+```tsx
+import { useRef, useLayoutEffect } from 'react';
+import { videoPlayer } from 'cloudinary-video-player';
+import 'cloudinary-video-player/cld-video-player.min.css';
+
+function VideoPlayerComponent({ cloudName, publicId }) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const playerRef = useRef<ReturnType<typeof videoPlayer> | null>(null);
+  
+  useLayoutEffect(() => {
+    // Check container is in DOM
+    if (!cloudName || !containerRef.current?.isConnected) return;
+    
+    // Create imperative video element
+    const el = document.createElement('video');
+    el.className = 'cld-video-player cld-fluid';
+    containerRef.current.appendChild(el);
+    
+    try {
+      const player = videoPlayer(el, {
+        cloudName,
+        secure: true,
+        controls: true,
+        fluid: true,
+        posterOptions: {
+          transformation: { startOffset: '0' },  // Use first frame
+          posterColor: '#0f0f0f',                // Fallback color
+        },
+      });
+      
+      // Source takes an object, not a string
+      player.source({ publicId });
+      playerRef.current = player;
+    } catch (err) {
+      console.error('Video player init failed:', err);
+      // Fallback to AdvancedVideo if init fails
+    }
+    
+    // Cleanup
+    return () => {
+      if (playerRef.current) {
+        try { 
+          playerRef.current.dispose(); 
+        } catch (e) { 
+          console.warn('Player disposal error:', e); 
+        }
+        playerRef.current = null;
+      }
+      // Only remove if still has parent
+      if (el.parentNode) {
+        el.parentNode.removeChild(el);
+      }
+    };
+  }, [cloudName, publicId]);
+  
+  return <div ref={containerRef} />;
+}
+```
+
+## Key Points
+
+### Poster Options
+Always include `posterOptions` for reliable poster display:
+
+```tsx
+posterOptions: {
+  transformation: { startOffset: '0' },  // First frame (reliable)
+  posterColor: '#0f0f0f',                // Dark fallback if poster fails
+}
+```
+
+Override via props if needed (e.g. `startOffset: '5'` for 5 seconds in)
+
+### player.source()
+Takes an **object**, not a string:
+
+```tsx
+✅ player.source({ publicId: 'samples/elephants' })
+❌ player.source('samples/elephants')  // WRONG
+```
+
+### Cleanup Pattern
+1. Call `player.dispose()` (wrap in try-catch)
+2. Set ref to null
+3. Remove element only if `el.parentNode` exists (avoids NotFoundError)
+
+### If Init Fails
+- CSP restrictions or browser extensions may block player
+- **Do NOT** relax CSP or ask user to disable extensions
+- ✅ Fall back to **AdvancedVideo** with same publicId
+
+## Common Errors
+
+### "Invalid target for null#on" or React removeChild error
+❌ Problem: Passed React-managed `<video ref>` to player
+✅ Solution: Use imperative element (createElement, append to container)
+
+### "source is not a function"
+❌ Problem: Wrong import or calling source incorrectly
+✅ Solution: `import { videoPlayer }` (named), call `player.source({ publicId })`
+
+### Poster image missing or broken
+❌ Problem: No posterOptions configured
+✅ Solution: Always include `posterOptions` with `startOffset: '0'` and `posterColor`
+
+### Failed HEAD requests or CORS console noise
+- Analytics/telemetry from player - doesn't necessarily mean playback fails
+- Do not add preflight GET
+- If video doesn't play, check imperative pattern and fall back to AdvancedVideo
+
+### Memory leak
+❌ Problem: Not disposing player in cleanup
+✅ Solution: Always dispose in cleanup (see pattern above)
+
+## AdvancedVideo vs Video Player
+
+| Feature | AdvancedVideo | Video Player |
+|---------|---------------|--------------|
+| Purpose | Display video | Full player |
+| Package | `@cloudinary/react` | `cloudinary-video-player` |
+| CSS | Not needed | Required |
+| Setup | Declarative | Imperative |
+| Controls | Native HTML5 | Styled custom |
+| Playlists | No | Yes |
+| Use when | Show video | Need player UI |
+
+## Documentation
+
+- [Cloudinary Video Player](https://cloudinary.com/documentation/cloudinary_video_player.md)
+- [Video Player API Reference](https://cloudinary.com/documentation/video_player_api_reference.md)
+- [Video Player React Tutorial](https://cloudinary.com/documentation/video_player_react_tutorial.md)
diff --git a/skills/cloudinary-transformations/SKILL.md b/skills/cloudinary-transformations/SKILL.md
new file mode 100644
index 0000000..026ba3c
--- /dev/null
+++ b/skills/cloudinary-transformations/SKILL.md
@@ -0,0 +1,545 @@
+---
+name: cloudinary-transformations
+description: Local version -- Create and debug Cloudinary transformation URLs from natural language instructions. Use when building Cloudinary delivery URLs, applying image/video transformations, optimizing media, or debugging transformation syntax errors.
+license: MIT
+metadata:
+  author: cloudinary
+  version: '1.0.1'
+---
+
+# Cloudinary Transformation Rules
+
+## When to Use
+
+- Building Cloudinary delivery/transformation URLs
+- Converting natural language requests to transformation syntax
+- Debugging transformation URLs that aren't working
+- Optimizing images or videos with Cloudinary
+- Applying effects, overlays, resizing, or cropping
+
+## Quick Start
+
+### Default Best Practice: Always Optimize
+
+**Add `f_auto/q_auto` to the end of nearly every transformation URL** (as final components):
+- Automatically delivers optimal format
+- Optimizes quality for best balance of visual quality and file size
+- Reduces bandwidth and improves performance
+
+**Example:** `c_fill,g_auto,w_400,h_300/f_auto/q_auto`
+
+**Exceptions - Don't add optimization when:**
+- Account has "Optimize By Default" enabled (already applied automatically)
+- Special quality requirements (use `q_auto:best`, `q_auto:low`, or manual `q_N` instead)
+- Specific format required (replace `f_auto` with `f_png`, `f_jpg`, etc.)
+- Delivering exact original with no modifications
+
+**Examples of common transformations (with optimization):**
+1. Resize: `c_scale,w_400/f_auto/q_auto`
+2. Smart crop: `c_fill,g_auto,h_300,w_400/f_auto/q_auto`
+3. Background removal: `e_background_removal/f_png/q_auto`
+4. Text overlay: `co_yellow,l_text:Arial_40:Hello%20World/fl_layer_apply,g_south/f_auto/q_auto`
+5. Image overlay: `l_logo/c_scale,w_100/fl_layer_apply,g_north_west,x_10,y_10/f_auto/q_auto`
+
+**Important:** All transformation strings shown throughout this skill are illustrative examples to demonstrate syntax and concepts. When generating transformations, choose specific values (dimensions, colors, positions, etc.) based on the user's actual requirements and use case, not the example values shown.
+
+**For debugging:** See [references/debugging.md](references/debugging.md) for detailed troubleshooting steps.
+
+
+## Gathering Requirements
+
+Before generating a transformation URL, if not already specified, clarify these details based on the user's request:
+
+### For Resize/Crop Requests
+**Required:**
+- At least one dimension (width OR height)
+- Crop behavior if both dimensions specified (fill, pad, scale, limit, etc.)
+
+**Clarify:**
+- Focal point/gravity (especially for cropping): Face detection? Center? Smart auto-detection?
+- Maintain aspect ratio? (if only one dimension, this is automatic)
+
+**Example questions:**
+- "What dimensions do you need? (width and/or height)"
+- "Should this fill the space (may crop) or fit within it (no cropping)?"
+- "Any important focal point? (faces, center, specific area)"
+
+### For AI Transformation Requests
+**Background removal:**
+- Output format needs (PNG for transparency vs JPG with solid background)
+- What to do with transparent area (keep transparent, add color, or gen_fill)
+
+**Generative fill:**
+- Target dimensions or aspect ratio
+- How much extension needed
+
+**Generative replace:**
+- What object to replace (from)
+- What to replace it with (to)
+- Preserve original shape? (for clothing/objects)
+
+**Generative remove:**
+- What object(s) to remove
+- Remove all instances or just one?
+
+**Generative background replace:**
+- Describe desired background (or use auto-generation)
+- Need reproducibility? (consider seed parameter)
+
+### For Video Transformation Requests
+**Trimming:**
+- Start and end time, or duration
+- Seconds or percentage of video
+
+**Codec/format:**
+- Output format needs (MP4, WebM, etc.)
+- Quality requirements (use `vc_auto` if unsure)
+
+**Audio:**
+- Keep or remove audio track
+- If for autoplay, suggest removing audio (`ac_none`)
+
+### Always Recommend
+Unless user specifies otherwise:
+- **Add `f_auto/q_auto` at the end** of transformation URLs (see Quick Start section for exceptions)
+- Use `g_auto` for smart cropping when filling dimensions
+- Consider cost for AI transformations (inform user of transformation credits)
+
+## Quick Reference
+
+### URL Structure
+
+```
+https://res.cloudinary.com/<cloud_name>/<asset_type>/<delivery_type>/<transformations>/<version>/<public_id>.<ext>
+```
+
+**Key Rules:**
+- Commas (`,`) separate parameters **within** a component
+- Slashes (`/`) separate components **between** transformations
+- Each component acts on the output of the previous one
+
+### Parameter Types
+
+**Action parameters**: Perform transformations (one action per component: each action transformation should be separated by a slash)
+**Qualifier parameters**: Modify action behavior (in the same component as the action, using commas as separators)
+
+Check the [Transformation Reference](https://cloudinary.com/documentation/transformation_reference.md) to determine if a parameter is an action or qualifier.
+
+## Core Transformations
+
+### Resize & Crop
+
+**Dimension value formats:**
+- **Whole numbers** (e.g., `w_400`, `h_300`) = pixels
+- **Decimal values** (e.g., `w_0.5`, `h_1.0`) = percentage of original dimensions (0.5 = 50%, 1.0 = 100%)
+
+**Choosing the right crop mode:**
+
+Use **`c_scale`** when:
+- Resizing while maintaining original aspect ratio
+- Specify only ONE dimension (width OR height)
+- No cropping needed
+- The user intentionally wants to stretch or squash an image by changing the aspect ratio
+
+Use **`c_fill`** when:
+- Must fit exact dimensions (e.g., thumbnail grid, fixed layout)
+- Okay to crop parts of image
+- Combine with `g_auto` for smart cropping, or `g_face` for portraits
+
+Use **`c_fit`** when:
+- Image must fit within dimensions without cropping
+- Okay to have empty space
+- Maintaining full image content is critical
+
+Use **`c_pad`** when:
+- Must fit exact dimensions without cropping
+- Need to fill empty space with background color/blur/AI-generated pixels
+- Use with `b_<color>` or `b_auto` (blurred background) or `b_gen_fill`
+
+Use **`c_limit`** when:
+- Set maximum dimensions but don't upscale small images
+- Preserving original quality of small images matters
+
+Use **`c_thumb`** when:
+- Creating thumbnails (typically avatars)
+- Use with `g_face` for face-centered crops
+
+Use **`c_auto`** when:
+- Cloudinary should intelligently crop to interesting content
+- Combine with `g_auto` for best results
+- Good for dynamic content where focal point varies
+
+**Examples:**
+```
+c_scale,w_400                      # Resize width to 400px, maintain aspect ratio
+c_scale,w_0.5                      # Resize to 50% of original width
+c_fill,g_auto,h_300,w_400          # Fill 400x300px dimensions, smart crop
+c_fit,h_300,w_400                  # Fit within dimensions, no crop
+c_pad,b_white,h_300,w_400          # Pad to exact size with white background
+c_pad,w_1.0                        # Pad to original width (100%)
+c_limit,w_1000                     # Limit max width, no upscale
+c_thumb,g_face,h_150,w_150         # Face-centered square thumbnail
+c_auto,g_auto,w_800                # Auto crop to interesting area
+```
+
+**Important**: Always specify a crop mode explicitly. Avoid using both dimensions with `c_scale` (will distort if aspect ratios don't match) - prefer one dimension to maintain aspect ratio.
+
+### Gravity (Focal Point)
+
+Gravity determines which part of the image to focus on when cropping:
+
+- **`g_auto`** - Smart detection (recommended for varied content; detects faces, objects, contrast)
+- **`g_face`** - Face detection (portraits, avatars)
+- **`g_center`** - Center position (centered subjects, logos)
+- **`g_north`, `g_south_east`, etc.** - Compass positions (fixed locations, overlay positioning)
+- **`x_N,y_N`** - Custom offsets (integers = pixels, floats = percentage: 0.8 = 80%)
+
+**Examples:**
+```
+c_fill,g_auto,w_400,h_300                      # Smart crop
+c_thumb,g_face,w_200,h_200                     # Face-centered
+l_logo/fl_layer_apply,g_south_east,x_10,y_10  # Logo bottom-right
+```
+
+**Important**: 
+- `g_auto` only works with `c_fill`, `c_lfill`, `c_crop`, `c_thumb`, `c_auto`
+- When using x, y, h, w together, use all integers OR all floats (don't mix)
+
+### Format & Quality
+
+**Recommended defaults:**
+- **`f_auto/q_auto`** - Use for most production images (WebP to supported browsers, optimized file size)
+
+**Specific formats** (when requirements dictate):
+- **`f_png`** - Transparency needed (e.g., after background removal)
+- **`f_jpg`** - Force JPEG (remove transparency)
+- **`q_N`** - Manual quality 1-100 (e.g., `q_60` for thumbnails, `q_90` for hero images)
+- **`dpr_auto`** - Retina displays (Chromium-only, requires Client Hints - see limitations below)
+
+**Examples:**
+```
+f_auto/q_auto           # Recommended default
+f_png/q_auto            # PNG with transparency
+q_80                    # Manual 80% quality
+```
+
+**Best Practice**: Use `/` to separate format and quality as distinct components.
+
+#### Responsive Images (`dpr_auto`, `w_auto`)
+
+**`dpr_auto`** - Automatically adapts to device pixel ratio (Retina displays)
+- **Chromium-only** (Chrome, Edge, Opera, Samsung Internet)
+- Requires Client Hints configuration
+- Falls back to `dpr_1.0` on other browsers
+- Does NOT work inside named transformations
+
+**Alternative for universal support:** Use explicit `dpr_2.0` or `<img srcset>` with 1x/2x variants
+
+For Client Hints configuration, browser compatibility, responsive breakpoints, and framework integration, see [references/responsive-images.md](references/responsive-images.md)
+
+### Effects
+
+**Common effects:**
+- **`e_grayscale`** - Black and white (artistic, accessibility)
+- **`e_sepia`** - Vintage/nostalgic feel
+- **`e_blur:N`** - Blur (privacy, placeholders; N typically 300-2000)
+- **`e_sharpen`** - Enhance clarity (useful after resizing)
+- **`e_cartoonify`** - Illustrated style
+- **`co_rgb:RRGGBB,e_colorize:N`** - Color tint (N = intensity 0-100, for brand theming)
+- **`e_background_removal`** - See AI Transformations section
+
+**Examples:**
+```
+e_blur:800                       # Blur effect
+e_sharpen                        # Enhance clarity
+co_rgb:0044ff,e_colorize:40      # Blue tint at 40%
+```
+
+**Note**: Color (`co_`) is a qualifier - use in same component as `e_colorize`.
+
+### Overlays & Underlays
+
+**Use for:**
+- **`l_<public_id>`** - Image overlays (logos, watermarks, badges)
+- **`u_<public_id>`** - Image underlays (custom backgrounds behind transparent subjects)
+- **`l_text:font_size:text`** - Text overlays (labels, social cards, dynamic text)
+
+**Pattern:**
+1. Declare: `l_<public_id>` or `u_<public_id>` or `l_text:Arial_40:Hello%20World`
+2. Transform (optional): e.g.  `/c_scale,w_100/` or `/o_50/` (opacity)
+3. Apply: `/fl_layer_apply,g_<position>,x_<offset>,y_<offset>`
+
+**Critical: Using `fl_relative` for overlay dimensions:**
+- **Without `fl_relative`**: Dimensions are relative to the **overlay's original size**
+  - Example: `w_1.0` = 100% of the overlay image's width (not useful for small images)
+- **With `fl_relative`**: Dimensions are relative to the **base image's size**
+  - Example: `w_1.0` = 100% of the base image's width (covers entire width)
+  - **Always use `fl_relative`** when sizing overlays as a percentage of the base image
+
+**Examples:**
+```
+l_logo/c_scale,w_100/fl_layer_apply,g_north_west,x_10,y_10                # Logo at 100px
+l_logo/c_scale,fl_relative,w_0.25/fl_layer_apply,g_north_west,x_10,y_10  # Logo at 25% of image width
+l_docs:one_black_pixel/c_scale,fl_relative,h_1.0,w_1.0/o_50/fl_layer_apply # Full-image semi-transparent overlay
+co_yellow,l_text:Arial_40:Hello%20World/fl_layer_apply,g_south            # Text overlay
+u_background/e_background_removal                                          # Custom background
+```
+
+**Important**: 
+- Color (`co_`) is a qualifier — use in the **same component** as text overlay declaration
+- **Always use `fl_relative`** when you want overlay dimensions as a percentage of the base image
+
+### Borders & Rounding
+
+- **`r_N`** - Rounded corners (N = radius in pixels; for modern UI, cards)
+- **`r_max`** - Perfect circle (use with square dimensions; avatars, icons)
+- **`bo_NNpx_solid_color`** - Border (frame images, separate from background)
+
+**Examples:**
+```
+r_20                           # 20px rounded corners
+r_max                          # Perfect circle
+bo_5px_solid_black             # 5px black border
+r_20,bo_5px_solid_rgb:0066ff   # Rounded with border (same component)
+```
+
+**Important**: For borders that follow rounded corners, use border as qualifier in same component.
+
+### Background Color
+
+- **`b_color,c_pad`** - Fill empty space with solid color (product images, letterboxing)
+- **`b_auto,c_pad`** - Blurred original as background (elegant alternative to solid)
+- **`b_gen_fill,c_pad`** - AI-extended background (change aspect ratio without cropping; see AI Transformations for cost)
+
+**Examples:**
+```
+b_lightblue,c_pad,w_1.0         # Light blue background
+b_auto,c_pad,ar_16:9            # Blurred background, 16:9
+b_gen_fill,c_pad,ar_1:1         # AI-extended to square
+```
+
+**Critical**: Background (`b_`) is a qualifier - use **with** pad crop in same component: `b_color,c_pad,w_X`, NOT `/b_color/`.
+
+### Rotation & Flips
+
+- **`a_90`, `a_180`, `a_270`** - Rotate in 90° increments (correct orientation)
+- **`a_N`** - Rotate by degrees (e.g., `a_-2` to straighten crooked photos)
+- **`a_hflip`** - Horizontal flip (mirror selfies, directional images)
+- **`a_vflip`** - Vertical flip (reflections)
+- **`a_auto_right`/`a_auto_left`** - Auto-rotate based on EXIF orientation
+
+**Examples:**
+```
+a_90                    # Rotate 90° clockwise
+a_-2                    # Straighten slight tilt
+a_hflip                 # Mirror horizontally
+a_auto_right            # Auto-fix from EXIF
+```
+
+## Named Transformations
+
+Named transformations (`t_<name>`) save transformation chains for reuse. Suggest for:
+- Transformations used across multiple assets
+- Complex transformation chains
+- Expensive operations (to enable baseline transformations and reduce costs)
+
+**Baseline transformations** (`bl_<name>`) cache expensive named transformations so they don't need to be regenerated. Use `bl_` instead of `t_` for AI transformations (background removal, generative AI) that will have variations applied. This can reduce costs from 75-230 tx per variation down to 1 tx each after the initial baseline is generated.
+
+**Example:** `bl_bg_removed/c_scale,w_500` - Uses cached background removal result, only pays for resize (1 tx instead of 75 tx)
+
+**Important:** `f_auto`, `dpr_auto`, and `w_auto` don't work inside named transformations - use them directly in URLs: `t_avatar/f_auto/q_auto`
+
+For complete details, limitations, and baseline transformation examples, see [references/named-transformations.md](references/named-transformations.md)
+
+## Generative AI Transformations
+
+**Proactively suggest these AI transformations when appropriate:**
+
+**Note:** Numbers in parentheses (e.g., 75 tx) indicate additional transformation credits consumed per use. Standard transformations = 1 tx.
+
+- **`e_background_removal`** (75 tx) - Remove backgrounds (e-commerce, profiles; combine with `f_png` or `b_color,c_pad`)
+- **`b_gen_fill`** (50 tx) - Extend backgrounds (change aspect ratio without cropping; use with `c_pad`)
+- **`e_gen_background_replace:prompt_<text>`** (230 tx) - AI-generated backgrounds (custom environments, seasonal variations; high cost)
+- **`e_gen_replace:from_<obj>;to_<new>`** (120 tx) - Swap objects (product variations, colors; use `;preserve_geometry_true` for clothing)
+- **`e_gen_remove:prompt_<text>`** (50 tx) - Remove objects (clean up distractions)
+- **`e_auto_enhance`** (100 tx) - Improve quality (fix poor lighting/exposure)
+- **`e_upscale`** (10-100 tx) - Enlarge without quality loss (low-res to high-res)
+
+**Important:** AI transformations cost significantly more (50-230 tx vs 1 tx). Inform users of costs and consider baseline transformations (e.g., `bl_bg_removed/c_scale,w_500`) to avoid re-processing expensive operations - see [references/named-transformations.md](references/named-transformations.md#baseline-transformations) and [references/transformation-costs.md](references/transformation-costs.md) for details.
+
+For complete details, syntax, and powerful combinations, see [references/ai-transformations.md](references/ai-transformations.md)
+
+## Video-Specific Transformations
+
+**Critical:** Use `f_auto:video` (not just `f_auto`) to ensure video output - plain `f_auto` may return an image thumbnail.
+
+- **`vc_auto`** - Automatic codec (recommended; optimal for browser/device)
+- **`so_N/eo_M`** - Trim (start/end in seconds; create clips, remove intro/outro)
+- **`ac_none`** - Remove audio (essential for autoplay; reduces file size)
+- **`fps_N`** - Set frame rate (lower = smaller file; standardize rates)
+- **Video resizing** - Same crop modes as images (`c_fill`, `c_scale`, `c_pad`)
+
+**Common patterns:**
+```
+vc_auto/ac_none/f_auto:video/q_auto                      # Autoplay-ready
+so_0/du_10/vc_auto/f_auto:video/q_auto                   # First 10 seconds
+c_scale,w_720/vc_auto/f_auto:video/q_auto                # Resize to 720p width
+c_fill,g_auto,h_720,w_1280/vc_auto/f_auto:video/q_auto  # 720p HD, smart crop
+```
+
+For complete details including codecs, trimming strategies, and video concatenation, see [references/video-transformations.md](references/video-transformations.md)
+
+## Variables & Conditionals
+
+**Variables** reuse values and create templates:
+```
+$size_300/c_fill,h_$size,w_$size        # Reuse value
+$iw/w_$iw_div_2                         # Half original width (arithmetic)
+```
+
+**Conditionals** adapt transformations dynamically:
+```
+if_w_gt_1000/c_scale,w_1000/if_end                          # Responsive sizing
+if_ar_gt_1.0/c_fill,w_800,h_450/if_else/c_fill,w_450,h_800/if_end  # Orientation handling
+```
+
+**Key rules:**
+- Variable names: alphanumeric, start with letter, no underscores
+- Conditionals: Must close with `if_end`
+- Arithmetic: `add`, `sub`, `mul`, `div` (left-to-right evaluation)
+
+For complete syntax, arithmetic operations, nested conditionals, and real-world patterns, see [references/advanced-features.md](references/advanced-features.md)
+
+## Self-Validation Checklist
+
+**Before returning a transformation URL, verify:**
+
+1. ✅ **URL structure is complete** (cloud_name, asset_type `/image/` or `/video/` or `/raw/`, delivery_type, public_id)
+2. ✅ **Each component has only one action parameter** (e.g., one crop mode per component)
+3. ✅ **Crop mode is explicit** (don't rely on defaults; avoid both dimensions with `c_scale`)
+4. ✅ **Overlays end with `fl_layer_apply`** in separate component
+5. ✅ **Text strings are URL-encoded** (spaces = `%20`, special chars encoded)
+6. ✅ **Variable names follow rules** (alphanumeric, start with letter, no underscores)
+7. ✅ **`g_auto` compatibility** (only works with `c_fill`, `c_lfill`, `c_crop`, `c_thumb`, `c_auto`)
+8. ✅ **Background as qualifier** (use with pad crop: `b_color,c_pad,w_X`, not `/b_color/`)
+9. ✅ **Format/quality at end** (prefer `f_auto/q_auto` as final components)
+
+**Quick syntax check:**
+- Commas separate parameters within a component: `c_fill,g_auto,w_400`
+- Slashes separate components: `c_fill,w_400/f_auto/q_auto`
+- Actions vs qualifiers: Only one action per component, qualifiers modify that action
+
+See [references/debugging.md](references/debugging.md) for detailed examples of each check.
+
+## Debugging Checklist
+
+When a transformation isn't working:
+
+1. **Verify URL structure**: Check that all required URL parts are present:
+   - Cloud name: `/<cloud_name>/`
+   - Asset type: `/image/` or `/video/` or `/raw/`
+   - Delivery type: `/upload/` or `/fetch/` etc.
+   - Public ID at the end
+2. **Check the X-Cld-Error header**: Cloudinary reports errors in the `X-Cld-Error` HTTP response header
+3. **Check parameter names** against [Transformation Reference](https://cloudinary.com/documentation/transformation_reference.md)
+4. **Check crop mode**: Specify crop mode explicitly; avoid both dimensions with `c_scale` (causes distortion if aspect ratios don't match)
+5. **Verify gravity compatibility**: `g_auto` doesn't work with `c_scale`, `c_fit`, `c_limit`, `c_pad`
+6. **Check action vs qualifier**: Only one action per component, qualifiers in same component
+7. **Verify overlay pattern**: Must end with `fl_layer_apply` component
+8. **Check variable names**: No underscores, must start with letter
+9. **Verify URL encoding**: Text overlays need URL-encoded strings (spaces = `%20`)
+10. **Check auto parameters in named transformations**: `f_auto`, `dpr_auto`, and `w_auto` don't work inside named transformations - use them directly in URLs
+11. **Verify Client Hints for `dpr_auto`/`w_auto`**: These only work on Chromium browsers with Client Hints enabled; fallback to `dpr_1.0` otherwise (see [references/responsive-images.md](references/responsive-images.md) for configuration)
+12. **Video returns image instead of video**: Use `f_auto:video` (not just `f_auto`) for video transformations - plain `f_auto` may return an image thumbnail
+
+### Checking X-Cld-Error Header
+
+The `X-Cld-Error` header contains error details when a transformation fails. To check it:
+
+**Using browser DevTools:**
+1. Open Developer Tools (Network tab)
+2. Request the transformation URL
+3. Look for `X-Cld-Error` in Response Headers
+
+**Using code (fetch the URL):**
+```javascript
+fetch('https://res.cloudinary.com/demo/image/upload/w_abc/sample.jpg')
+  .then(response => {
+    const error = response.headers.get('x-cld-error');
+    if (error) {
+      console.log('Cloudinary Error:', error);
+    }
+  });
+```
+
+**Common X-Cld-Error messages:**
+- `Invalid width - abc` - Width parameter expects a number
+- `Invalid transformation syntax` - Malformed transformation string
+- `Resource not found` - Asset doesn't exist or public ID is incorrect
+- `Transformation limit exceeded` - Account transformation quota reached
+
+**Online tool:** Use the [X-Cld-Error Inspector](https://cloudinary.com/documentation/advanced_url_delivery_options#x_cld_error_inspector_tool) to check any Cloudinary URL
+
+For more details, see [Error Handling](https://cloudinary.com/documentation/advanced_url_delivery_options#error_handling)
+
+## Transformation Costs
+
+**Important:** Warn users about high-cost transformations before generating URLs. AI effects cost significantly more than standard transformations (50-230 tx vs 1 tx).
+
+For complete cost details and cost reduction strategies, see [references/transformation-costs.md](references/transformation-costs.md)
+
+## Additional Resources
+
+### Skill References (Progressive Disclosure)
+- [references/debugging.md](references/debugging.md) - Use when transformations return errors or unexpected results
+- [references/ai-transformations.md](references/ai-transformations.md) - Use when you need AI transformation prompt syntax, cost details, or complex AI combinations
+- [references/video-transformations.md](references/video-transformations.md) - Use when working with video codecs, trimming strategies, or concatenation
+- [references/advanced-features.md](references/advanced-features.md) - Use when building complex logic with variables, conditionals, or arithmetic
+- [references/responsive-images.md](references/responsive-images.md) - Use when implementing responsive images, configuring Client Hints, or using dpr_auto/w_auto
+- [references/transformation-costs.md](references/transformation-costs.md) - Use when optimizing for cost or explaining cost implications to users
+- [references/named-transformations.md](references/named-transformations.md) - Use when creating reusable transformations or reducing costs for repeated operations
+- [references/examples.md](references/examples.md) - Use when you need real-world examples beyond the Quick Start (social cards, e-commerce, responsive images)
+
+### Core Cloudinary Documentation
+- [Transformation Reference](https://cloudinary.com/documentation/transformation_reference.md) - All parameters
+
+### Image Transformations
+- [Image Transformations Overview](https://cloudinary.com/documentation/image_transformations.md)
+- [Resizing and Cropping](https://cloudinary.com/documentation/resizing_and_cropping.md)
+- [Placing Layers on Images](https://cloudinary.com/documentation/layers.md)
+- [Effects and Enhancements](https://cloudinary.com/documentation/effects_and_artistic_enhancements.md)
+- [Background Removal](https://cloudinary.com/documentation/background_removal.md)
+- [Generative AI Transformations](https://cloudinary.com/documentation/generative_ai_transformations.md)
+- [Face-Detection Based Transformations](https://cloudinary.com/documentation/face_detection_based_transformations.md)
+- [Custom Focus Areas](https://cloudinary.com/documentation/custom_focus_areas.md)
+- [Transformation Refiners](https://cloudinary.com/documentation/transformation_refiners.md)
+- [Animated Images](https://cloudinary.com/documentation/animated_images.md)
+- [Transformations on 3D Models](https://cloudinary.com/documentation/transformations_on_3d_models.md)
+- [Conditional Transformations](https://cloudinary.com/documentation/conditional_transformations.md)
+- [User-Defined Variables and Arithmetic](https://cloudinary.com/documentation/user_defined_variables.md)
+- [Custom Functions](https://cloudinary.com/documentation/custom_functions.md)
+
+### Video Transformations
+- [Video Transformations Overview](https://cloudinary.com/documentation/video_manipulation_and_delivery.md)
+- [Resizing and Cropping](https://cloudinary.com/documentation/video_resizing_and_cropping.md)
+- [Trimming and Concatenating](https://cloudinary.com/documentation/video_trimming_and_concatenating.md)
+- [Placing Layers on Videos](https://cloudinary.com/documentation/video_layers.md)
+- [Effects and Enhancements](https://cloudinary.com/documentation/video_effects_and_enhancements.md)
+- [Audio Transformations](https://cloudinary.com/documentation/audio_transformations.md)
+- [Converting Videos to Animated Images](https://cloudinary.com/documentation/videos_to_animated_images.md)
+- [Conditional Transformations](https://cloudinary.com/documentation/video_conditional_expressions.md)
+- [User-Defined Variables and Arithmetic](https://cloudinary.com/documentation/video_user_defined_variables.md)
+
+## Common Mistakes & Best Practices
+
+**Avoid:**
+- ❌ `w_400,h_300` → ✅ `c_scale,w_400` (both dimensions with c_scale distorts image; prefer one dimension)
+- ❌ `c_scale,g_auto,w_400` → ✅ `c_fill,g_auto,w_400` (g_auto doesn't work with c_scale)
+- ❌ `l_logo/fl_layer_apply,g_north_west` → ✅ `l_logo/c_scale,w_100/fl_layer_apply,g_north_west`
+- ❌ `b_lightblue/e_trim` → ✅ `b_lightblue,c_pad,w_1.0/e_trim` (background as qualifier)
+
+**Always:**
+- Prefer `f_auto/q_auto` in separate components over `f_auto,q_auto`
+- Use `g_auto` for smart cropping unless specific focal point needed
+- Specify crop mode with width/height; prefer one dimension with `c_scale`
+- Never guess parameter names - verify against documentation
diff --git a/skills/cloudinary-transformations/references/advanced-features.md b/skills/cloudinary-transformations/references/advanced-features.md
new file mode 100644
index 0000000..ca5c713
--- /dev/null
+++ b/skills/cloudinary-transformations/references/advanced-features.md
@@ -0,0 +1,727 @@
+# Advanced Features: Variables, Conditionals & Arithmetic
+
+This reference covers advanced Cloudinary transformation capabilities for building dynamic, template-based, and conditional transformations.
+
+## Variables
+
+Variables allow you to reuse values across a transformation chain and create template transformations that adapt to asset properties.
+
+### Basic Variable Syntax
+
+**Declaration and usage:**
+```
+$varName_value/...use_$varName...
+```
+
+**Rules:**
+- Variable names: alphanumeric only, must start with letter
+- **NO underscores in variable names** (❌ `$my_width` ✅ `$mywidth`)
+- Values can be numeric or string (strings use `!` delimiters)
+- Declare before use (left to right in URL)
+
+### Numeric Variables
+
+**Simple value reuse:**
+```
+$size_300/c_fill,h_$size,w_$size
+```
+Creates a 300x300 square. Change `$size_300` once to update both dimensions.
+
+**Multiple variables:**
+```
+$width_800,$height_600/c_fill,h_$height,w_$width/f_auto/q_auto
+```
+Template for any dimensions.
+
+**Padding/offset consistency:**
+```
+$pad_50/l_logo/c_scale,w_100/fl_layer_apply,g_north_west,x_$pad,y_$pad/f_auto/q_auto
+```
+Logo positioned with consistent 50px padding from edges.
+
+### String Variables
+
+**Syntax:** Use `!` delimiters for string values
+```
+$color_!blue!/b_$color,c_pad,w_1.0/f_auto/q_auto
+$text_!Hello World!/l_text:Arial_40:$text/fl_layer_apply/f_auto/q_auto
+```
+
+**Important:** Spaces in string variables are preserved, no URL encoding needed in declaration.
+
+**Text interpolation:** Use `$(varName)` syntax in text overlays
+```
+$date_25/co_white,l_text:Arial_60:Day%20$(date)/fl_layer_apply,g_center/f_auto/q_auto
+```
+
+### Asset Property Variables
+
+Access original asset properties using predefined variables:
+
+**Dimension variables:**
+- `$iw` - Initial width (original width in pixels)
+- `$ih` - Initial height (original height in pixels)
+- `$ar` - Aspect ratio (width/height, e.g., 1.5 for 3:2 ratio)
+- `$cp` - Current page/layer number (for PDFs, multi-page TIFFs)
+- `$tags` - Asset tags (use in conditionals)
+
+**Examples:**
+```
+$iw/w_$iw_div_2/f_auto/q_auto                    # Half original width
+$iw,$ih/c_scale,w_$iw,h_$ih_div_2/f_auto/q_auto  # Half original height
+$ar/c_fill,ar_$ar,w_800/f_auto/q_auto            # Maintain original aspect ratio
+```
+
+**Use cases:**
+- Relative sizing: resize based on original dimensions
+- Maintain proportions: preserve original aspect ratio while resizing
+- Responsive templates: one URL adapts to any asset size
+
+### Metadata and Context Variables
+
+**Structured metadata:**
+```
+$title_!md:title!/co_white,l_text:Arial_50:$(title)/fl_layer_apply,g_north/f_auto/q_auto
+```
+Overlays text from asset's metadata field `title`.
+
+**Context variables:**
+```
+$category_!ctx:category!/if_ctx:!category!_eq_!featured!/e_saturation:50/if_end/f_auto/q_auto
+```
+Conditional transformation based on context variable.
+
+**Common metadata fields:**
+- `md:title`, `md:description`, `md:price`, `md:stock`, `md:date`
+- Must be set on asset via [structured metadata](https://cloudinary.com/documentation/structured_metadata.md)
+
+### Variable Scope and Order
+
+**Variables are scoped left-to-right:**
+```
+✅ $size_300/c_fill,h_$size,w_$size              # Declared before use
+❌ c_fill,h_$size,w_$size/$size_300              # Used before declaration
+```
+
+**Variables persist across components:**
+```
+$brand_!0066ff!/bo_3px_solid_rgb:$brand,c_fill,h_400,w_600/co_rgb:$brand,l_text:Arial_40:Brand/fl_layer_apply/f_auto/q_auto
+```
+Brand color used in multiple components.
+
+## Arithmetic Operations
+
+Perform calculations on dimensions using asset properties or variables.
+
+### Basic Operators
+
+- `add` - Addition: `w_add_100` (width + 100px)
+- `sub` - Subtraction: `h_sub_50` (height - 50px)
+- `mul` - Multiplication: `w_mul_2` (width × 2)
+- `div` - Division: `w_div_2` (width ÷ 2)
+
+**Examples:**
+```
+c_scale,w_iw_div_2/f_auto/q_auto                     # Half original width
+c_crop,h_ih_sub_100,w_iw/f_auto/q_auto               # Crop 100px from height
+c_scale,w_mul_1.5/f_auto/q_auto                      # 150% of original width
+```
+
+### Chaining Operations
+
+**Multiple operations in sequence:**
+```
+c_scale,w_iw_div_2_mul_3/f_auto/q_auto               # (width ÷ 2) × 3
+c_scale,w_iw_sub_100_div_2/f_auto/q_auto             # (width - 100) ÷ 2
+```
+
+**Order of operations:** Left to right, no precedence
+
+### Practical Arithmetic Examples
+
+**Create responsive padding:**
+```
+$pad_iw_mul_0.05/l_logo/fl_layer_apply,g_north_west,x_$pad,y_$pad/f_auto/q_auto
+```
+Logo padding is 5% of original width.
+
+**Maintain aspect ratio with constraints:**
+```
+c_scale,w_800,h_800_div_ar/f_auto/q_auto
+```
+Width fixed at 800px, height calculated from aspect ratio.
+
+**Add borders relative to size:**
+```
+$border_iw_div_100/bo_$(border)px_solid_black/f_auto/q_auto
+```
+Border thickness is 1% of image width.
+
+### Using Arithmetic with Variables
+
+```
+$base_200/c_fill,h_$base,w_$base_mul_2/f_auto/q_auto
+```
+Creates 200×400 rectangle (height = $base, width = $base × 2).
+
+```
+$margin_iw_mul_0.1/l_badge/fl_layer_apply,g_north_east,x_$margin,y_$margin/f_auto/q_auto
+```
+Badge positioned with 10% margin relative to image width.
+
+## Conditionals
+
+Build responsive, adaptive transformations that change based on asset properties, tags, metadata, or context.
+
+### Basic Conditional Syntax
+
+```
+if_<condition>/...transformations.../if_end
+if_<condition>/...true_branch.../if_else/...false_branch.../if_end
+```
+
+**Critical:** Every `if_` must close with `if_end`
+
+### Comparison Operators
+
+- `eq` - Equal to
+- `ne` - Not equal to
+- `lt` - Less than
+- `lte` - Less than or equal
+- `gt` - Greater than
+- `gte` - Greater than or equal
+
+**Examples:**
+```
+if_w_gt_1000/c_scale,w_1000/if_end                   # Downsize large images
+if_ar_eq_1.0/r_max/if_end                            # Circle if square
+if_fc_gte_1/c_thumb,g_face,w_200/if_end              # Face-centered if face detected
+```
+
+### Logical Operators
+
+**AND** - Both conditions must be true:
+```
+if_w_gt_800_and_h_gt_600/c_fill,h_600,w_800/if_end
+```
+
+**OR** - Either condition must be true:
+```
+if_w_gt_2000_or_h_gt_2000/c_limit,w_2000/if_end
+```
+
+**Precedence:** AND has higher precedence than OR
+```
+if_A_and_B_or_C     # Evaluates as: (A AND B) OR C
+```
+
+### Dimension-Based Conditionals
+
+**Width and height:**
+```
+if_w_gt_1000/c_scale,w_1000/if_end                           # Limit max width
+if_h_lt_500/c_fit,h_500,w_800/if_end                         # Ensure min height
+if_w_gte_1920_and_h_gte_1080/q_90/if_else/q_auto/if_end     # Higher quality for large images
+```
+
+**Aspect ratio:**
+```
+if_ar_gt_1.0/c_fill,h_400,w_800/if_else/c_fill,h_800,w_400/if_end
+```
+Different crops for landscape (ar > 1.0) vs portrait (ar ≤ 1.0).
+
+```
+if_ar_gt_1.5/c_crop,ar_16:9/if_else/c_pad,ar_16:9,b_auto/if_end
+```
+Crop wide images to 16:9, pad narrower images.
+
+### Tag-Based Conditionals
+
+**Check for tag presence:**
+```
+if_!sale!_in_tags/l_sale_badge/fl_layer_apply,g_north_east/if_end/f_auto/q_auto
+```
+
+**Check for tag absence:**
+```
+if_!premium!_nin_tags/l_watermark/fl_layer_apply,g_center/if_end/f_auto/q_auto
+```
+
+**Multiple tags (AND logic):**
+```
+if_!sale:featured!_in_tags/e_saturation:50/if_end/f_auto/q_auto
+```
+Both "sale" AND "featured" tags must be present (colon = AND).
+
+**Important:** Tag values must be wrapped in `!` delimiters.
+
+### Face Count Conditionals
+
+**Face detection:**
+```
+if_fc_gt_0/c_thumb,g_face,h_200,w_200/if_else/c_fill,g_auto,h_200,w_200/if_end/f_auto/q_auto
+```
+Uses face detection if faces found, otherwise smart crop.
+
+```
+if_fc_eq_1/c_thumb,g_face,h_300,w_300/if_else/c_fill,g_faces,h_300,w_400/if_end/f_auto/q_auto
+```
+Single face: square crop. Multiple faces: wider crop to include all.
+
+### Metadata-Based Conditionals
+
+**Numeric metadata:**
+```
+if_md:!price!_gt_100/l_premium_badge/fl_layer_apply,g_north_west/if_end/f_auto/q_auto
+```
+
+**String metadata:**
+```
+if_md:!category!_eq_!electronics!/e_sharpen:100/if_end/f_auto/q_auto
+```
+
+**Combined conditions:**
+```
+if_md:!stock!_gt_0_and_md:!featured!_eq_!true!/l_featured_badge/fl_layer_apply/if_end/f_auto/q_auto
+```
+Badge only if in stock AND featured.
+
+### Context-Based Conditionals
+
+**Context variables** (set at request time):
+```
+if_ctx:!theme!_eq_!dark!/e_brightness:20/if_end/f_auto/q_auto
+```
+
+**Use cases:**
+- A/B testing: different transformations per variant
+- Personalization: adapt to user preferences
+- Multi-tenant: brand-specific overlays
+
+### Nested Conditionals
+
+**Pattern:** Conditionals can be nested for complex logic
+```
+if_w_gt_1000/if_ar_gt_1.5/c_crop,ar_16:9/if_else/c_scale,w_1000/if_end/if_end/f_auto/q_auto
+```
+If wide (>1000px), check aspect ratio and handle accordingly.
+
+**Best practice:** Keep nesting shallow (2-3 levels max) for maintainability.
+
+### Complex Conditional Examples
+
+**Art direction with fallback:**
+```
+if_ar_gt_2.0/c_crop,ar_16:9/if_else/if_ar_lt_0.5/c_pad,ar_9:16,b_auto/if_else/c_scale,w_800/if_end/if_end/f_auto/q_auto
+```
+- Very wide (ar > 2.0): Crop to 16:9
+- Very tall (ar < 0.5): Pad to 9:16 with blur
+- Normal: Scale to 800px width
+
+**Quality optimization by size:**
+```
+if_w_gt_2000_or_h_gt_2000/q_90/if_else/if_w_lt_500/q_70/if_else/q_auto/if_end/if_end/f_auto
+```
+- Large (>2000px): q_90
+- Small (<500px): q_70
+- Normal: q_auto
+
+**Face-aware with density check:**
+```
+if_fc_eq_0/c_fill,g_auto,h_400,w_600/if_else/if_fc_lt_3/c_thumb,g_face,h_400,w_600/if_else/c_fill,g_faces,h_400,w_800/if_end/if_end/f_auto/q_auto
+```
+- No faces: Smart crop
+- 1-2 faces: Face-centered crop
+- 3+ faces: Wider crop to include all faces
+
+## Arithmetic Expressions
+
+Perform calculations on dimensions, positions, and other numeric parameters.
+
+### Available Operators
+
+- `add` - Addition
+- `sub` - Subtraction  
+- `mul` - Multiplication
+- `div` - Division
+- `pow` - Power/exponent
+
+### Basic Arithmetic
+
+**Division:**
+```
+c_scale,w_div_2/f_auto/q_auto                        # Half width
+w_iw_div_2                                           # Half of initial width
+```
+
+**Multiplication:**
+```
+c_scale,w_mul_1.5/f_auto/q_auto                      # 150% width
+w_iw_mul_2                                           # Double initial width
+```
+
+**Addition:**
+```
+c_crop,h_add_100,w_800/f_auto/q_auto                 # Add 100px to height
+w_iw_add_200                                         # Initial width + 200px
+```
+
+**Subtraction:**
+```
+c_crop,h_sub_50,w_800/f_auto/q_auto                  # Subtract 50px from height
+h_ih_sub_100                                         # Initial height - 100px
+```
+
+### Chained Arithmetic
+
+**Multiple operations (left-to-right evaluation):**
+```
+w_iw_div_2_mul_3                                     # (initial_width ÷ 2) × 3
+h_ih_sub_100_div_2                                   # (initial_height - 100) ÷ 2
+w_iw_mul_0.8_add_50                                  # (initial_width × 0.8) + 50
+```
+
+**Order matters:**
+```
+w_100_add_50_mul_2   # (100 + 50) × 2 = 300
+w_100_mul_2_add_50   # (100 × 2) + 50 = 250
+```
+
+### Aspect Ratio Calculations
+
+**Calculate height from width:**
+```
+c_scale,w_800,h_800_div_ar/f_auto/q_auto
+```
+Height = 800 ÷ aspect_ratio (maintains proportions).
+
+**Calculate width from height:**
+```
+c_scale,h_600,w_600_mul_ar/f_auto/q_auto
+```
+Width = 600 × aspect_ratio (maintains proportions).
+
+**Adjust aspect ratio:**
+```
+c_crop,ar_ar_mul_1.5/f_auto/q_auto
+```
+Makes image 50% wider while maintaining height.
+
+### Using Arithmetic with Variables
+
+**Combine variables and arithmetic:**
+```
+$base_200/c_fill,h_$base,w_$base_mul_2/f_auto/q_auto
+```
+Creates 200×400 rectangle (width = base × 2).
+
+**Complex calculations:**
+```
+$margin_iw_mul_0.05,$size_iw_mul_0.25/l_logo/c_scale,w_$size/fl_layer_apply,g_north_east,x_$margin,y_$margin/f_auto/q_auto
+```
+Logo size is 25% of image width, margin is 5% of image width.
+
+**Responsive overlay positioning:**
+```
+$offset_iw_sub_200_div_2/l_badge/fl_layer_apply,g_north,x_$offset/f_auto/q_auto
+```
+Centers 200px badge horizontally: offset = (width - 200) ÷ 2.
+
+## Real-World Advanced Patterns
+
+### Template Transformation with Multiple Variables
+
+```
+$w_800,$h_600,$brand_!0066ff!,$opacity_70/c_fill,h_$h,w_$w/bo_5px_solid_rgb:$brand,co_rgb:$brand,l_text:Arial_50_bold:$(brand)/fl_layer_apply,g_south,o_$opacity,y_30/f_auto/q_auto
+```
+Complete template: dimensions, brand color for border and text, custom opacity.
+
+### Responsive Watermark Sizing
+
+```
+$wmsize_iw_mul_0.15/l_watermark/c_scale,fl_relative,w_$wmsize/fl_layer_apply,g_south_east,x_20,y_20/f_auto/q_auto
+```
+Watermark scales to 15% of image width (responsive to any size).
+
+### Conditional Quality Based on Size
+
+```
+if_w_gt_2000_or_h_gt_2000/q_90/if_else/if_w_lt_400_or_h_lt_400/q_70/if_else/q_auto/if_end/if_end/f_auto
+```
+- Very large images: High quality (90)
+- Very small images: Lower quality (70)
+- Normal images: Automatic
+
+### Dynamic Cropping Based on Orientation
+
+```
+$targetw_800,$targeth_600/if_ar_gt_ar_calc_$targetw_div_$targeth/c_fill,h_$targeth,w_$targetw/if_else/c_fit,h_$targeth,w_$targetw/if_end/f_auto/q_auto
+```
+Fill if aspect ratio matches target, otherwise fit.
+
+### Smart Thumbnail Generation
+
+```
+$size_300/if_fc_gt_0/c_thumb,g_face,h_$size,w_$size/r_max/if_else/c_fill,g_auto,h_$size,w_$size/r_20/if_end/f_auto/q_auto
+```
+- Face detected: Circular face thumbnail
+- No face: Rounded square with smart crop
+
+### Responsive Text Overlay
+
+```
+$fontsize_iw_div_10/co_white,l_text:Arial_$(fontsize)_bold:SALE/b_red,fl_layer_apply,g_north/f_auto/q_auto
+```
+Font size scales to 10% of image width.
+
+**Note:** Font size must be an integer. Use variables carefully with arithmetic to ensure valid values.
+
+### Conditional Overlay Based on Tags
+
+```
+if_!watermark!_nin_tags/if_end/if_!premium!_in_tags/l_premium_badge/fl_layer_apply,g_north_east/if_end/f_auto/q_auto
+```
+- Skip everything if "watermark" tag present
+- Add premium badge if "premium" tag present
+
+### Aspect Ratio Preservation with Max Size
+
+```
+$maxdim_1200/if_w_gt_h/c_scale,w_$maxdim/if_else/c_scale,h_$maxdim/if_end/f_auto/q_auto
+```
+Scales longest dimension to 1200px while preserving aspect ratio.
+
+### E-commerce Product Variations
+
+```
+$size_800/if_md:!category!_eq_!apparel!/c_pad,ar_3:4,b_white,h_$size,w_$size_mul_0.75/if_else/c_pad,ar_1:1,b_white,h_$size,w_$size/if_end/f_auto/q_auto
+```
+- Apparel products: 3:4 ratio (portrait)
+- Other products: 1:1 ratio (square)
+
+### Seasonal Overlay Based on Context
+
+```
+$season_!ctx:season!/if_ctx:!season!_eq_!winter!/l_snowflake/fl_layer_apply,g_north_west/if_else/if_ctx:!season!_eq_!summer!/l_sun/fl_layer_apply,g_north_west/if_end/if_end/f_auto/q_auto
+```
+Different seasonal icons based on context.
+
+## Best Practices
+
+### Variable Naming
+
+**Good names:**
+- ✅ `$width`, `$size`, `$margin`, `$brand`, `$opacity`
+- ✅ Start with letter, descriptive, lowercase
+
+**Bad names:**
+- ❌ `$my_width` (underscores not allowed)
+- ❌ `$1size` (must start with letter)
+- ❌ `$w` (too cryptic, prefer `$width`)
+
+### When to Use Variables
+
+**Use variables when:**
+- Same value used multiple times (DRY principle)
+- Building reusable templates
+- Calculating relative values (percentages, ratios)
+- Simplifying complex transformation chains
+
+**Don't use variables when:**
+- Value only used once (unnecessary complexity)
+- Simple static transformations
+
+### When to Use Conditionals
+
+**Use conditionals when:**
+- Different transformations needed for different asset types
+- Responsive behavior based on dimensions
+- Tag-based variations (sale items, featured content)
+- Metadata-driven transformations (pricing tiers, categories)
+- Protecting against edge cases (very small/large images)
+
+**Don't use conditionals when:**
+- Simple static transformation works for all cases
+- Can handle variation with single flexible transformation (e.g., `c_fit` vs complex conditional)
+
+### Performance Considerations
+
+**Conditionals are evaluated at delivery time:**
+- No extra cost for conditional logic itself
+- Only the executed branch counts toward transformation credits
+- Good for reducing unnecessary transformations
+
+**Variables add minimal overhead:**
+- Negligible performance impact
+- Improve maintainability of complex URLs
+- Consider named transformations for frequently used variable combinations
+
+## Debugging Advanced Features
+
+### Variable Issues
+
+**Variable not working:**
+1. Check variable name has no underscores
+2. Verify variable declared before use
+3. Check syntax: `$name_value` for declaration, `$name` for reference
+4. For strings: Ensure `!` delimiters used
+
+**Text interpolation not working:**
+1. Use `$(varName)` syntax in text overlays, not just `$varName`
+2. Ensure URL encoding for rest of text: `Day%20$(date)`
+
+### Conditional Issues
+
+**Conditional not applying:**
+1. Verify condition syntax matches operators exactly
+2. Check for missing `if_end`
+3. Verify tag/metadata delimiters (`!` for strings)
+4. Test condition values (are they actually true?)
+
+**Nested conditionals not working:**
+1. Count `if_` and `if_end` pairs (must match)
+2. Check `if_else` placement (between branches, not after `if_end`)
+3. Simplify: Test each condition separately first
+
+### Arithmetic Issues
+
+**Calculation not working:**
+1. Check operator spelling: `div` not `divide`
+2. Verify asset property names: `iw`, `ih`, `ar` (not `width`, `height`)
+3. Check order of operations (left-to-right)
+4. Ensure result is valid for parameter (e.g., dimensions must be positive integers)
+
+**Division by zero:**
+```
+❌ w_10_div_0                    # Invalid
+✅ w_iw_div_2                    # Safe (iw is always > 0)
+```
+
+## Advanced Examples Library
+
+### Responsive Image Grid
+
+```
+$cols_3,$gutter_20,$container_1200/c_fill,g_auto,w_$container_sub_$gutter_mul_$cols_add_1_div_$cols/if_ar_gt_1.0/ar_16:9/if_else/ar_1:1/if_end/f_auto/q_auto
+```
+Calculates grid item width: (container - (gutter × (cols + 1))) ÷ cols
+
+### Progressive Enhancement
+
+```
+if_w_gt_1920/c_scale,w_1920/q_90/if_else/if_w_gt_1200/c_scale,w_1200/q_85/if_else/c_scale,w_800/q_auto/if_end/if_end/f_auto
+```
+Tiered quality based on size.
+
+### Smart Product Thumbnails
+
+```
+$size_400/if_fc_gt_0/c_crop,g_face,h_$size,w_$size/if_else/if_ar_gt_1.2/c_fill,g_auto,h_$size,w_$size_mul_1.3/if_else/if_ar_lt_0.8/c_fill,g_auto,h_$size_mul_1.3,w_$size/if_else/c_fill,g_auto,h_$size,w_$size/if_end/if_end/if_end/f_auto/q_auto
+```
+- Face: Face-centered square
+- Landscape: Slightly wider
+- Portrait: Slightly taller
+- Square: Standard square
+
+### Dynamic Watermark Placement
+
+```
+$wmw_iw_mul_0.3,$wmh_ih_mul_0.1,$xpos_iw_sub_$wmw_sub_30,$ypos_ih_sub_$wmh_sub_30/l_watermark/c_scale,h_$wmh,w_$wmw/fl_layer_apply,x_$xpos,y_$ypos/f_auto/q_auto
+```
+Watermark sized to 30% width × 10% height, positioned 30px from bottom-right.
+
+### Conditional Padding Strategy
+
+```
+if_ar_gt_1.5/c_pad,ar_16:9,b_auto/if_else/if_ar_lt_0.67/c_pad,ar_9:16,b_auto/if_else/c_fit,w_800/if_end/if_end/f_auto/q_auto
+```
+- Wide images: Pad to 16:9 with blur
+- Tall images: Pad to 9:16 with blur  
+- Normal: Fit to 800px
+
+## Limitations and Gotchas
+
+### Variable Limitations
+
+1. **No recursive references**: Can't use a variable in its own definition
+   ```
+   ❌ $size_$size_mul_2    # Invalid
+   ```
+
+2. **No string arithmetic**: Can't perform math on string variables
+   ```
+   ❌ $text_!Hello!/$newtext_$text_add_!World!    # Invalid
+   ```
+
+3. **Integer results**: Some parameters require integers (font size, dimensions)
+   ```
+   ⚠️  $fontsize_iw_div_7.5    # May produce decimals, font size needs integer
+   ```
+
+### Conditional Limitations
+
+1. **No else-if**: Use nested conditionals instead
+   ```
+   ❌ if_A/X/else_if_B/Y/else/Z/if_end    # Not supported
+   ✅ if_A/X/if_else/if_B/Y/if_else/Z/if_end/if_end    # Use nested
+   ```
+
+2. **Evaluation order**: AND has higher precedence than OR
+   ```
+   if_A_or_B_and_C    # Evaluates as: A OR (B AND C)
+   ```
+
+3. **Max nesting depth**: Keep practical (2-3 levels for readability)
+
+### Arithmetic Limitations
+
+1. **Left-to-right only**: No operator precedence
+   ```
+   w_100_add_50_mul_2   # (100 + 50) × 2, not 100 + (50 × 2)
+   ```
+
+2. **Division truncates**: Results are integers
+   ```
+   w_100_div_3          # Result: 33 (not 33.333...)
+   ```
+
+3. **No parentheses**: Can't group operations
+   ```
+   ❌ w_(100_add_50)_mul_2    # Not supported
+   ✅ w_100_add_50_mul_2       # Left-to-right: (100 + 50) × 2
+   ```
+
+## When to Use Advanced Features
+
+### Use Variables When:
+- Building transformation templates for consistency
+- Same value appears multiple times
+- Calculating relative dimensions (responsive sizing)
+- Simplifying complex overlay positioning
+
+### Use Conditionals When:
+- Asset properties vary widely (dimensions, aspect ratios)
+- Tag-based variations needed (sales, featured items)
+- Metadata-driven transformations (categories, pricing)
+- Responsive transformations for different screen sizes
+- Protecting against edge cases
+
+### Use Arithmetic When:
+- Resizing relative to original dimensions
+- Calculating proportional overlays/padding
+- Maintaining aspect ratios with constraints
+- Creating responsive designs
+
+### Consider Named Transformations Instead When:
+- Transformation is static and reused frequently
+- No dynamic values needed
+- Simpler maintenance than complex variable/conditional chains
+
+For named transformation details, see [named-transformations.md](named-transformations.md)
+
+## Additional Resources
+
+- [Conditional Transformations](https://cloudinary.com/documentation/conditional_transformations.md) - Complete conditional syntax
+- [User-Defined Variables and Arithmetic](https://cloudinary.com/documentation/user_defined_variables.md) - Full variable reference
+- [Structured Metadata](https://cloudinary.com/documentation/structured_metadata.md) - Using metadata in conditionals
+- [Context Variables](https://cloudinary.com/documentation/user_defined_variables.md#context_variables) - Request-time variables
diff --git a/skills/cloudinary-transformations/references/ai-transformations.md b/skills/cloudinary-transformations/references/ai-transformations.md
new file mode 100644
index 0000000..07f6f8d
--- /dev/null
+++ b/skills/cloudinary-transformations/references/ai-transformations.md
@@ -0,0 +1,133 @@
+# Generative AI Transformations
+
+Cloudinary's AI transformations solve common business challenges. **Proactively suggest these when appropriate:**
+
+## Background Removal (`e_background_removal`)
+**Cost:** 75 tx | **Use when:** Product images, portraits, preparing for overlays
+**Value:** Professional product photos without manual editing
+
+```
+e_background_removal/f_png
+```
+
+## Generative Fill (`b_gen_fill`)
+**Cost:** 50 tx | **Use when:** Changing aspect ratios without cropping, extending images
+**Value:** Adapt one image to multiple formats without reshooting
+
+```
+c_pad,ar_16:9,b_gen_fill,w_1200/f_auto/q_auto
+```
+
+## Auto Enhance (`e_auto_enhance`)
+**Cost:** 100 tx | **Use when:** Improving UGC quality, correcting lighting/exposure
+**Value:** Professional-looking images without manual photo editing
+
+```
+e_auto_enhance/f_auto/q_auto
+```
+
+## Upscale (`e_upscale`)
+**Cost:** 10-100 tx | **Use when:** Enlarging images without quality loss
+**Value:** Use existing images at larger sizes for print or displays
+
+```
+e_upscale/c_scale,w_2000/f_auto/q_auto
+```
+
+## Generative Background Replace (`e_gen_background_replace`)
+**Cost:** 230 tx | **Use when:** Replacing backgrounds with AI-generated environments
+**Value:** Create contextual product imagery without photoshoots
+
+```
+e_gen_background_replace:prompt_modern office space/f_auto/q_auto
+e_gen_background_replace:prompt_<text>;seed_<num>      # Use seed for reproducibility
+```
+
+**Key notes:**
+- Auto-detects/preserves foreground on non-transparent images
+- For transparent images, fills transparent area
+- Not supported for animated/fetched images
+
+## Generative Replace (`e_gen_replace`)
+**Cost:** 120 tx | **Use when:** Swapping objects, A/B testing product variations
+**Value:** Create product variations instantly without reshoots
+
+```
+e_gen_replace:from_shirt;to_cable knit sweater;preserve-geometry_true
+e_gen_replace:from_<object>;to_<replacement>;multiple_true     # Replace all instances
+```
+
+**Key notes:**
+- Use `preserve-geometry_true` to maintain shape (ideal for clothing)
+- Don't use for faces, hands, or text
+- Only works on non-transparent images
+
+## Generative Restore (`e_gen_restore`)
+**Cost:** 100 tx | **Use when:** Restoring old photos, fixing compression artifacts
+**Value:** Revitalize low-quality or historical content at scale
+
+```
+e_gen_restore/f_auto/q_auto
+```
+
+**Key notes:** Removes artifacts, reduces noise, sharpens, recovers detail
+
+## Generative Remove (`e_gen_remove`)
+**Cost:** 50 tx | **Use when:** Removing unwanted objects, cleaning product photos
+**Value:** Clean up images at scale without manual editing
+
+```
+e_gen_remove:prompt_the stick/f_auto/q_auto
+e_gen_remove:prompt_goose;multiple_true                 # Remove all instances
+e_gen_remove:prompt_(text;person)                       # Remove multiple types
+```
+
+**Key notes:** Parentheses syntax removes multiple different objects simultaneously
+
+## When to Suggest AI Transformations
+
+**Proactively recommend:**
+- "Remove background" → `e_background_removal`
+- "Replace background" → `e_gen_background_replace:prompt_<text>`
+- "Change aspect ratio without cropping" → `b_gen_fill` with `c_pad`
+- "Swap object/change color" → `e_gen_replace:from_<obj>;to_<new>`
+- "Fix old photo/restore" → `e_gen_restore`
+- "Remove object" → `e_gen_remove:prompt_<text>`
+- "Improve quality" → `e_auto_enhance`
+- "Make bigger" → `e_upscale`
+
+## Powerful AI Combinations
+
+```
+e_background_removal/e_gen_background_replace:prompt_modern office/f_auto/q_auto
+e_gen_remove:prompt_price tag/e_background_removal/b_white,c_pad,w_1.0/e_auto_enhance/f_auto/q_auto
+e_gen_restore/e_upscale/c_scale,w_2000/f_auto/q_auto
+e_background_removal/b_gen_fill,c_pad,ar_16:9,w_1200/e_auto_enhance/f_auto/q_auto
+```
+
+## Cost Optimization with Baseline Transformations
+
+Since AI transformations are expensive (50-230 tx), use **baseline transformations** to cache results and avoid re-processing:
+
+**Example: Background removal with multiple variations**
+```
+# Without baseline - regenerates background removal each time (75 tx each)
+e_background_removal/c_scale,w_500/f_auto/q_auto           # 75 tx
+e_background_removal/c_fill,h_300,w_400/f_auto/q_auto     # 75 tx
+e_background_removal/e_grayscale/f_auto/q_auto            # 75 tx
+# Total: 225 tx
+
+# With baseline - processes background removal once (75 tx + 1 tx per variation)
+# Named transformation "bg_removed" contains: e_background_removal/f_jxl/q_100
+bl_bg_removed/c_scale,w_500/f_auto/q_auto                 # 1 tx
+bl_bg_removed/c_fill,h_300,w_400/f_auto/q_auto           # 1 tx
+bl_bg_removed/e_grayscale/f_auto/q_auto                  # 1 tx
+# Total: 78 tx (75 tx for baseline + 3 tx for variations)
+```
+
+**When to suggest baseline transformations:**
+- User needs multiple variations of an AI-transformed image
+- Expensive AI operations will be reused (background removal, generative AI, upscale)
+- Building a product catalog with consistent AI processing
+
+For complete syntax, rules, and implementation details, see [named-transformations.md](named-transformations.md#baseline-transformations)
diff --git a/skills/cloudinary-transformations/references/debugging.md b/skills/cloudinary-transformations/references/debugging.md
new file mode 100644
index 0000000..2b04bbc
--- /dev/null
+++ b/skills/cloudinary-transformations/references/debugging.md
@@ -0,0 +1,528 @@
+# Debugging Cloudinary Transformations
+
+Common issues and their solutions when transformations don't work as expected.
+
+## Syntax Errors
+
+### Issue: Both Dimensions Without Explicit Crop Mode
+⚠️ **Works but risky:**
+```
+w_400,h_300
+```
+
+✅ **Better:**
+```
+c_scale,w_400                  # Specify one dimension, maintain aspect ratio
+```
+or
+```
+c_fill,h_300,w_400            # Both dimensions needed, smart crop
+```
+
+**Why:** While `c_scale` is the default crop mode, specifying both dimensions with `c_scale` (explicit or default) will distort the image if the aspect ratio doesn't match the original. Best practice: specify the crop mode explicitly and prefer one dimension with `c_scale` to maintain aspect ratio.
+
+### Issue: Invalid Parameter Names
+❌ **Wrong:**
+```
+crop_scale,width_400
+```
+
+✅ **Correct:**
+```
+c_scale,w_400
+```
+
+**Why:** Cloudinary uses abbreviated parameter names. Always check the [Transformation Reference](https://cloudinary.com/documentation/transformation_reference).
+
+## Gravity Issues
+
+### Issue: g_auto Not Working
+❌ **Wrong:**
+```
+c_scale,g_auto,w_400
+```
+
+✅ **Correct:**
+```
+c_fill,g_auto,w_400
+```
+
+**Why:** `g_auto` only works with: `c_fill`, `c_lfill`, `c_fill_pad`, `c_crop`, `c_thumb`, `c_auto`, `c_auto_pad`
+
+**Does NOT work with:** `c_scale`, `c_fit`, `c_limit`, `c_mfit`, `c_pad`, `c_lpad`, `c_mpad`
+
+### Issue: g_auto on Overlays
+❌ **Wrong:**
+```
+l_logo/c_scale,w_100/fl_layer_apply,g_auto
+```
+
+✅ **Correct:**
+```
+l_logo/c_scale,w_100/fl_layer_apply,g_north_west,x_10,y_10
+```
+
+**Why:** `g_auto` doesn't work for positioning overlays. Use compass directions or `g_center`.
+
+## Overlay Issues
+
+### Issue: Overlay Not Appearing
+❌ **Wrong:**
+```
+l_logo/c_scale,w_100
+```
+
+✅ **Correct:**
+```
+l_logo/c_scale,w_100/fl_layer_apply,g_north_west
+```
+
+**Why:** Every overlay must end with a `fl_layer_apply` component.
+
+### Issue: Overlay Positioning in Wrong Component
+❌ **Wrong:**
+```
+l_logo,g_north_west/c_scale,w_100/fl_layer_apply
+```
+
+✅ **Correct:**
+```
+l_logo/c_scale,w_100/fl_layer_apply,g_north_west
+```
+
+**Why:** Positioning parameters (`g_`, `x_`, `y_`) go in the `fl_layer_apply` component, not the layer declaration.
+
+### Issue: Multiple Overlays Missing fl_layer_apply
+❌ **Wrong:**
+```
+l_logo/c_scale,w_100/l_badge/c_scale,w_60/fl_layer_apply,g_north_west
+```
+
+✅ **Correct:**
+```
+l_logo/c_scale,w_100/fl_layer_apply,g_north_west,x_10,y_10/l_badge/c_scale,w_60/fl_layer_apply,g_north_east,x_10,y_10
+```
+
+**Why:** Each overlay needs its own `fl_layer_apply` component.
+
+## Background Color Issues
+
+### Issue: Background Not Applied in Chained Transformations
+❌ **Wrong:**
+```
+e_background_removal/b_lightblue/e_trim
+```
+
+✅ **Correct:**
+```
+e_background_removal/b_lightblue,c_pad,w_1.0/e_trim
+```
+
+**Why:** When chaining transformations, use background as a qualifier with a pad crop that doesn't change dimensions.
+
+### Issue: Background on Non-Transparent Image
+❌ **Wrong:**
+```
+c_fill,h_400,w_600/b_blue
+```
+
+✅ **Correct:**
+```
+c_pad,b_blue,h_400,w_600
+```
+
+**Why:** Background color only shows on transparent areas or with pad crop mode.
+
+## Border and Rounding Issues
+
+### Issue: Border Not Following Rounded Corners
+❌ **Wrong:**
+```
+r_20/bo_5px_solid_blue
+```
+
+✅ **Correct:**
+```
+bo_5px_solid_blue,r_20
+```
+
+**Why:** Border is a qualifier in this case and should be in the same component as radius to follow the rounded corners.
+
+### Issue: Border on Transparent Images
+❌ **Wrong:**
+```
+bo_5px_solid_blue
+```
+
+✅ **Correct:**
+```
+co_rgb:0066ff,e_outline:outer:15:200
+```
+
+**Why:** For images with transparency, use `e_outline` effect instead of `bo_` border.
+
+## Variable Issues
+
+### Issue: Variable Name with Underscore
+❌ **Wrong:**
+```
+$my_width_300/c_scale,w_$my_width
+```
+
+✅ **Correct:**
+```
+$mywidth_300/c_scale,w_$mywidth
+```
+
+**Why:** Variable names cannot contain underscores. Use alphanumeric characters only, must start with a letter.
+
+### Issue: String Variable Without Delimiters
+❌ **Wrong:**
+```
+$color_blue/b_$color
+```
+
+✅ **Correct:**
+```
+$color_!blue!/b_$color
+```
+
+**Why:** String values must be wrapped in `!` delimiters when assigning to variables.
+
+### Issue: Variable Reference in Text
+❌ **Wrong:**
+```
+$date_25/l_text:Arial_40:Day%20$date/fl_layer_apply
+```
+
+✅ **Correct:**
+```
+$date_25/l_text:Arial_40:Day%20$(date)/fl_layer_apply
+```
+
+**Why:** In text overlays, wrap variable names in `$()` for proper interpolation.
+
+## Conditional Issues
+
+### Issue: Missing if_end
+❌ **Wrong:**
+```
+if_w_gt_300/c_scale,w_300
+```
+
+✅ **Correct:**
+```
+if_w_gt_300/c_scale,w_300/if_end
+```
+
+**Why:** Every conditional must close with `if_end`.
+
+### Issue: Tag Condition Without Delimiters
+❌ **Wrong:**
+```
+if_sale_in_tags/l_badge/fl_layer_apply/if_end
+```
+
+✅ **Correct:**
+```
+if_!sale!_in_tags/l_badge/fl_layer_apply/if_end
+```
+
+**Why:** Tag values must be wrapped in `!` delimiters.
+
+### Issue: Multiple Tags Without Colon
+❌ **Wrong:**
+```
+if_!sale!_!featured!_in_tags
+```
+
+✅ **Correct:**
+```
+if_!sale:featured!_in_tags
+```
+
+**Why:** Multiple tags are separated by colons within the `!` delimiters (colon means AND).
+
+## Text Overlay Issues
+
+### Issue: Spaces Not Encoded
+❌ **Wrong:**
+```
+l_text:Arial_40:Hello World/fl_layer_apply
+```
+
+✅ **Correct:**
+```
+l_text:Arial_40:Hello%20World/fl_layer_apply
+```
+
+**Why:** Text must be URL-encoded. Spaces become `%20`.
+
+### Issue: Color Not Applied to Text
+❌ **Wrong:**
+```
+l_text:Arial_40:Hello/co_yellow/fl_layer_apply
+```
+
+✅ **Correct:**
+```
+co_yellow,l_text:Arial_40:Hello/fl_layer_apply
+```
+
+**Why:** Color (`co_`) is a qualifier and must be in the same component as the text overlay.
+
+### Issue: Background Not Applied to Text
+❌ **Wrong:**
+```
+l_text:Arial_40:Hello/b_black/fl_layer_apply
+```
+
+✅ **Correct:**
+```
+b_black,l_text:Arial_40:Hello/fl_layer_apply
+```
+
+**Why:** Background (`b_`) is a qualifier and must be in the same component as the text overlay.
+
+## Action vs Qualifier Issues
+
+### Issue: Multiple Actions in One Component
+❌ **Wrong:**
+```
+c_scale,e_sepia,w_400
+```
+
+✅ **Correct:**
+```
+c_scale,w_400/e_sepia
+```
+
+**Why:** Only one action parameter per component. Separate actions with `/`.
+
+### Issue: Qualifier in Wrong Component
+❌ **Wrong:**
+```
+e_colorize:40/co_rgb:0044ff
+```
+
+✅ **Correct:**
+```
+co_rgb:0044ff,e_colorize:40
+```
+
+**Why:** Qualifiers must be in the same component as the action they modify.
+
+## Aspect Ratio Issues
+
+### Issue: Both Dimensions with c_scale
+❌ **Wrong:**
+```
+c_scale,h_300,w_400
+```
+
+✅ **Correct:**
+```
+c_scale,w_400
+```
+or
+```
+c_fill,h_300,w_400
+```
+
+**Why:** Using both dimensions with `c_scale` distorts the image. Specify one dimension, or use `c_fill` to crop.
+
+### Issue: Aspect Ratio Syntax
+❌ **Wrong:**
+```
+c_fill,ar_16/9,w_800
+```
+
+✅ **Correct:**
+```
+c_fill,ar_16:9,w_800
+```
+
+**Why:** Aspect ratio uses colon (`:`) not slash (`/`).
+
+## Format Issues
+
+### Issue: PNG for Large Images
+❌ **Wrong:**
+```
+c_scale,w_2000/f_png
+```
+
+✅ **Correct:**
+```
+c_scale,w_2000/f_auto/q_auto
+```
+
+**Why:** PNG creates very large files. Use `f_auto` to let Cloudinary choose the best format.
+
+### Issue: Transparency Lost
+❌ **Wrong:**
+```
+e_background_removal/f_jpg
+```
+
+✅ **Correct:**
+```
+e_background_removal/f_png
+```
+
+**Why:** JPEG doesn't support transparency. Use PNG, WebP, or `f_auto`.
+
+## Quality Issues
+
+### Issue: Over-Compression
+❌ **Wrong:**
+```
+q_auto:eco
+```
+
+✅ **Correct:**
+```
+q_auto
+```
+or
+```
+q_80
+```
+
+**Why:** `q_auto:eco` is very aggressive. Use standard `q_auto` or specify quality level.
+
+### Issue: Large File Size
+❌ **Wrong:**
+```
+c_scale,w_2000/f_png
+```
+
+✅ **Correct:**
+```
+c_scale,w_2000/f_auto/q_auto
+```
+
+**Why:** Always use `f_auto/q_auto` for optimization unless specific format required.
+
+## URL Structure Issues
+
+### Issue: Missing Asset Type
+❌ **Wrong:**
+```
+https://res.cloudinary.com/demo/upload/c_scale,w_300/sample.jpg
+```
+
+✅ **Correct:**
+```
+https://res.cloudinary.com/demo/image/upload/c_scale,w_300/sample.jpg
+```
+
+**Why:** The asset type (`/image/`, `/video/`, or `/raw/`) is required between the cloud name and delivery type.
+
+**URL structure must be:**
+```
+https://res.cloudinary.com/<cloud_name>/<asset_type>/<delivery_type>/<transformations>/<public_id>
+```
+
+### Issue: Wrong Asset Type
+❌ **Wrong if there is no video with public ID `sample`:**
+```
+https://res.cloudinary.com/demo/video/upload/sample.jpg
+```
+
+✅ **Correct for an image with public ID `sample`:**
+```
+https://res.cloudinary.com/demo/image/upload/sample.jpg
+```
+
+**Why:** Asset type must match the type of the uploaded asset. Images use `/image/`, videos use `/video/`, other files use `/raw/`.  
+
+If there is a video with public ID `sample` then `https://res.cloudinary.com/demo/video/upload/sample.jpg` is the correct way to deliver an image thumbnail from the video.
+
+## Debugging Workflow
+
+When a transformation doesn't work:
+
+1. **Verify URL structure**
+   - Check cloud name exists: `/<cloud_name>/`
+   - **Check asset type is present:** `/image/` or `/video/` or `/raw/` 
+   - Check delivery type: `/upload/` or `/fetch/` etc.
+   - Verify public ID exists and is spelled correctly
+
+2. **Check component separation**
+   - Commas within components: `c_scale,w_400`
+   - Slashes between components: `c_scale,w_400/f_auto/q_auto`
+
+3. **Validate parameter names**
+   - Cross-reference with [Transformation Reference](https://cloudinary.com/documentation/transformation_reference)
+   - Check for typos and abbreviations
+
+4. **Check action vs qualifier**
+   - Only one action per component
+   - Qualifiers in same component as action
+
+5. **Verify gravity compatibility**
+   - `g_auto` only works with certain crop modes
+   - Check crop mode compatibility
+
+6. **Test incrementally**
+   - Start with basic transformation
+   - Add parameters one at a time
+   - Identify which parameter causes the issue
+
+7. **Check browser console**
+   - Look for 404 errors (asset not found)
+   - Look for 400 errors (invalid transformation)
+
+8. **Use Cloudinary Media Inspector**
+   - Install browser extension
+   - Inspect transformation details
+   - View transformation breakdown
+
+## Common Error Messages
+
+### "Invalid transformation"
+- Check parameter names against documentation
+- Verify component structure (commas vs slashes)
+- Check for typos
+
+### "Resource not found"
+- Verify public ID is correct
+- Check asset type (image/video/raw)
+- Verify delivery type (upload/fetch/etc)
+
+### "Invalid crop mode"
+- Check crop mode compatibility with other parameters
+- Verify `g_auto` is used with compatible crop mode
+
+### "Invalid color"
+- Use `rgb:` prefix for hex colors: `rgb:ff6600`
+- Check named color spelling
+- Verify color format
+
+## Testing Tips
+
+1. **Start simple**: Begin with `c_scale,w_400/f_auto/q_auto`
+2. **Add incrementally**: Add one parameter at a time
+3. **Use browser DevTools**: Check network tab for errors
+4. **Test in isolation**: Remove other transformations to isolate issue
+5. **Check documentation**: Always verify parameter syntax
+
+## Quick Reference
+
+**Always separate with `/`:**
+- Different actions: `c_scale,w_400/e_sepia/f_auto/q_auto`
+
+**Always in same component:**
+- Action and its qualifiers: `co_yellow,l_text:Arial_40:Hello`
+- Border and radius: `bo_5px_solid_blue,r_20`
+
+**Always use:**
+- Crop mode with dimensions: `c_scale,w_400`
+- `fl_layer_apply` after overlays
+- `if_end` after conditionals
+
+**Never do:**
+- `g_auto` with `c_scale`, `c_fit`, `c_limit`, `c_pad`
+- Multiple actions in one component
+- Underscores in variable names
diff --git a/skills/cloudinary-transformations/references/examples.md b/skills/cloudinary-transformations/references/examples.md
new file mode 100644
index 0000000..2324455
--- /dev/null
+++ b/skills/cloudinary-transformations/references/examples.md
@@ -0,0 +1,712 @@
+# Cloudinary Transformation Examples
+
+Complete examples of common transformation patterns with explanations.
+
+## Basic Resizing
+
+### Scale by Width (Maintain Aspect Ratio)
+```
+c_scale,w_400
+```
+Resizes to 400px wide, height adjusts automatically.
+
+### Scale by Height (Maintain Aspect Ratio)
+```
+c_scale,h_300
+```
+Resizes to 300px tall, width adjusts automatically.
+
+### Fill Exact Dimensions
+```
+c_fill,g_auto,h_300,w_400
+```
+Crops and resizes to exactly 400x300, focusing on the most interesting part.
+
+### Fit Within Dimensions
+```
+c_fit,h_300,w_400
+```
+Fits entire image within 400x300 box without cropping.
+
+### Limit Maximum Size
+```
+c_limit,w_1000
+```
+Only scales down if larger than 1000px, never upscales.
+
+## Smart Cropping
+
+### Auto Crop with Face Detection
+```
+c_fill,g_face,h_200,w_200
+```
+Creates 200x200 thumbnail centered on detected face.
+
+### Auto Crop to Interesting Content
+```
+c_auto,g_auto,h_400,w_600
+```
+Automatically crops to the most interesting part of the image.
+
+### Thumbnail with Multiple Faces
+```
+c_thumb,g_faces,h_150,w_150
+```
+Creates thumbnail including all detected faces.
+
+## Optimization
+
+### Basic Optimization
+```
+f_auto/q_auto
+```
+Automatically selects best format (WebP, AVIF, etc.) and quality.
+
+### High-Quality Optimization
+```
+f_auto/q_auto:best
+```
+Higher quality automatic optimization.
+
+### Economy Optimization
+```
+f_auto/q_auto:eco
+```
+More aggressive compression for smaller files.
+
+### Retina Display
+```
+c_scale,w_400/f_auto/q_auto/dpr_auto
+```
+Automatically serves 2x or 3x resolution for high-DPI displays.
+
+**Note:** `dpr_auto` only works on Chromium-based browsers (Chrome, Edge, Opera, Samsung Internet) with Client Hints enabled. Falls back to `dpr_1.0` otherwise. For broader browser support, consider using explicit DPR values (e.g., `dpr_2.0`) or JavaScript-based responsive solutions.
+
+## Effects
+
+### Grayscale
+```
+e_grayscale/f_auto/q_auto
+```
+
+### Sepia Tone
+```
+e_sepia/f_auto/q_auto
+```
+
+### Blur
+```
+e_blur:800/f_auto/q_auto
+```
+Blur strength from 1-2000.
+
+### Sharpen
+```
+e_sharpen:100/f_auto/q_auto
+```
+
+### Cartoonify
+```
+e_cartoonify/f_auto/q_auto
+```
+
+### Pixelate Faces
+```
+e_pixelate_faces:20/f_auto/q_auto
+```
+
+### Background Removal
+```
+e_background_removal/f_png
+```
+Removes background, use PNG to preserve transparency.
+
+### Colorize
+```
+co_rgb:0044ff,e_colorize:40/f_auto/q_auto
+```
+Colorize with blue at 40% strength. Note: `co_` is a qualifier.
+
+## Overlays
+
+### Simple Logo Overlay
+```
+l_logo/c_scale,w_100/fl_layer_apply,g_north_west,x_10,y_10/f_auto/q_auto
+```
+Places 100px wide logo in top-left corner with 10px margins.
+
+### Semi-Transparent Watermark
+```
+l_watermark/c_scale,fl_relative,o_40,w_0.25/fl_layer_apply,g_south_east,x_20,y_20/f_auto/q_auto
+```
+Places watermark at 25% of image width, 40% opacity, bottom-right with 20px margins.
+
+### Text Overlay
+```
+co_white,l_text:Arial_60_bold:Hello%20World/fl_layer_apply,g_center/f_auto/q_auto
+```
+White text, 60px Arial Bold, centered.
+
+### Text with Background
+```
+b_black,co_white,l_text:Arial_40:Sale/fl_layer_apply,g_north,y_50/f_auto/q_auto
+```
+White text on black background at top.
+
+### Multiple Overlays
+```
+l_logo/c_scale,w_80/fl_layer_apply,g_north_west,x_10,y_10/l_badge/c_scale,w_60/fl_layer_apply,g_north_east,x_10,y_10/f_auto/q_auto
+```
+Logo in top-left, badge in top-right.
+
+## Borders & Shapes
+
+### Rounded Corners
+```
+c_fill,h_400,w_600/r_20/f_auto/q_auto
+```
+20px rounded corners.
+
+### Circle
+```
+c_fill,h_300,w_300/r_max/f_auto/q_auto
+```
+Perfect circle (requires square dimensions).
+
+### Border
+```
+bo_5px_solid_black/f_auto/q_auto
+```
+5px solid black border.
+
+### Border with Rounded Corners
+```
+c_fill,h_400,w_600/bo_5px_solid_rgb:0066ff,r_20/f_png/q_auto
+```
+Blue border following rounded corners. Note: border and radius in same component.
+
+### Outline for Transparent Images
+```
+co_rgb:0066ff,e_outline:outer:15:200/f_png
+```
+15px blue outline at 200 opacity for images with transparency.
+
+## Background Colors
+
+### Pad with Background
+```
+c_pad,b_lightblue,h_400,w_600/f_auto/q_auto
+```
+Pads image to 600x400 with light blue background.
+
+### Background After Removal
+```
+e_background_removal/b_lightblue,c_pad,w_1.0/f_png
+```
+Removes background, then adds light blue. Note: background as qualifier with pad.
+
+### Named Colors
+```
+c_pad,b_white,h_400,w_600/f_auto/q_auto
+```
+Common named colors: white, black, red, blue, green, yellow, etc.
+
+### RGB Colors
+```
+c_pad,b_rgb:ff6600,h_400,w_600/f_auto/q_auto
+```
+Custom RGB color.
+
+## Rotation & Flips
+
+### Rotate 90 Degrees
+```
+a_90/f_auto/q_auto
+```
+
+### Rotate Custom Angle
+```
+a_-15/f_auto/q_auto
+```
+Rotates -15 degrees.
+
+### Horizontal Flip
+```
+a_hflip/f_auto/q_auto
+```
+
+### Vertical Flip
+```
+a_vflip/f_auto/q_auto
+```
+
+### Rotate and Crop
+```
+a_45/c_fill,h_400,w_600/f_auto/q_auto
+```
+Rotates first, then crops to dimensions.
+
+## Variables
+
+### Square Dimensions
+```
+$size_300/c_fill,h_$size,w_$size/r_max/f_auto/q_auto
+```
+Creates 300x300 circle using variable.
+
+### Reusable Color
+```
+$brand_!0066ff!/bo_5px_solid_rgb:$brand,c_fill,h_400,w_600/co_rgb:$brand,l_text:Arial_40:Brand/fl_layer_apply,g_south/f_auto/q_auto
+```
+Uses brand color for border and text.
+
+### Template with Multiple Variables
+```
+$width_800,$height_600,$color_!blue!/b_$color,c_pad,h_$height,w_$width/f_auto/q_auto
+```
+Template for padded images with custom dimensions and color.
+
+### Date Variable in Text
+```
+$date_25/co_white,l_text:Arial_60:Day%20$(date)/fl_layer_apply,g_center/f_auto/q_auto
+```
+Displays "Day 25" using variable.
+
+## Conditionals
+
+### Resize Large Images Only
+```
+if_w_gt_1000/c_scale,w_1000/if_end/f_auto/q_auto
+```
+Only resizes if width exceeds 1000px.
+
+### Different Crop for Portrait vs Landscape
+```
+if_ar_gt_1.0/c_fill,h_400,w_600/if_else/c_fill,h_600,w_400/if_end/f_auto/q_auto
+```
+Landscape gets 600x400, portrait gets 400x600.
+
+### Add Badge to Sale Items
+```
+if_!sale!_in_tags/l_sale_badge/c_scale,w_100/fl_layer_apply,g_north_east,x_10,y_10/if_end/f_auto/q_auto
+```
+Only adds sale badge if "sale" tag exists.
+
+### Quality Based on Dimensions
+```
+if_w_gt_2000/q_90/if_else/q_auto/if_end/f_auto
+```
+Higher quality for large images.
+
+### Multiple Conditions
+```
+if_w_gt_800_and_h_gt_600/c_fill,h_600,w_800/if_else/c_fit,h_600,w_800/if_end/f_auto/q_auto
+```
+Fill if large enough, otherwise fit.
+
+## Complex Chained Transformations
+
+### Avatar Pipeline
+```
+c_thumb,g_face,h_400,w_400/e_improve/r_max/bo_3px_solid_white/f_auto/q_auto
+```
+1. Crop to face (400x400)
+2. Enhance quality
+3. Make circular
+4. Add white border
+5. Optimize
+
+### Product Image Pipeline
+```
+e_background_removal/c_pad,b_white,h_800,w_800/l_watermark/c_scale,fl_relative,o_30,w_0.2/fl_layer_apply,g_south_east,x_30,y_30/f_auto/q_auto
+```
+1. Remove background
+2. Pad to 800x800 with white
+3. Add watermark (20% width, 30% opacity)
+4. Position bottom-right
+5. Optimize
+
+### Social Media Post
+```
+c_fill,g_auto,h_630,w_1200/co_white,l_text:Arial_80_bold:Breaking%20News/b_black,fl_layer_apply,g_north,y_50/co_yellow,l_text:Arial_40:Read%20More/fl_layer_apply,g_south,y_50/f_auto/q_auto
+```
+1. Crop to 1200x630 (Facebook/Twitter size)
+2. Add bold white heading on black at top
+3. Add yellow call-to-action at bottom
+4. Optimize
+
+### Before/After Comparison
+```
+c_fill,h_400,w_300/l_same_image/c_fill,e_grayscale,h_400,w_300/fl_layer_apply,fl_splice,g_east/f_auto/q_auto
+```
+Creates side-by-side comparison with grayscale version.
+
+## Video Transformations
+
+### Video Thumbnail
+```
+c_fill,g_auto,h_360,w_640/f_jpg/q_auto
+```
+Extracts frame as thumbnail.
+
+### Video at Specific Time
+```
+c_fill,g_auto,h_360,so_5.0,w_640/f_jpg/q_auto
+```
+Thumbnail from 5 seconds in (`so_` = start offset).
+
+### Video Resize
+```
+c_scale,w_720/f_auto/q_auto
+```
+Resizes video to 720px wide.
+
+### Video with Overlay
+```
+l_logo/c_scale,w_100/fl_layer_apply,g_north_west,x_10,y_10/f_auto/q_auto
+```
+Adds logo throughout video.
+
+## Responsive Images
+
+### Automatic Breakpoints
+```
+c_fill,g_auto,w_auto:breakpoints/f_auto/q_auto/dpr_auto
+```
+Cloudinary generates optimal breakpoints.
+
+**Note:** Both `w_auto` and `dpr_auto` require Client Hints and only work on Chromium-based browsers. Without Client Hints support, `w_auto` is ignored and `dpr_auto` falls back to `dpr_1.0`.
+
+### Specific Breakpoints
+```
+c_fill,g_auto,w_auto:100:1600:80/f_auto/q_auto
+```
+Breakpoints from 100px to 1600px in 80px increments.
+
+**Note:** `w_auto` requires Client Hints and only works on Chromium-based browsers.
+
+### Art Direction
+```
+if_ar_gt_1.5/c_fill,h_400,w_800/if_else/c_fill,h_800,w_400/if_end/f_auto/q_auto
+```
+Different crops for different aspect ratios.
+
+## Advanced Patterns
+
+### Dynamic Text from Metadata
+```
+$title_!md:title!/co_white,l_text:Arial_50:$(title)/fl_layer_apply,g_north,y_30/f_auto/q_auto
+```
+Overlays text from asset metadata.
+
+### Conditional Watermark
+```
+if_!premium!_nin_tags/l_watermark/c_scale,fl_relative,o_50,w_0.3/fl_layer_apply,g_center/if_end/f_auto/q_auto
+```
+Only watermarks non-premium images.
+
+### Smart Crop with Fallback
+```
+c_fill,g_auto:subject,h_400,w_600/f_auto/q_auto
+```
+Tries to detect main subject, falls back to general auto.
+
+### Aspect Ratio Preservation
+```
+c_fill,ar_16:9,w_800/f_auto/q_auto
+```
+Maintains 16:9 aspect ratio at 800px wide.
+
+### Named Transformation
+```
+t_thumbnail/f_auto/q_auto
+```
+References a named transformation that's been defined for this product environment.
+
+## Additional Crop Modes
+
+### Limit Fill (c_lfill)
+```
+c_lfill,g_auto,h_400,w_600/f_auto/q_auto
+```
+Same as fill but only scales down, never upscales.
+
+### Fill with Padding (c_fill_pad)
+```
+c_fill_pad,g_auto,h_400,w_600/f_auto/q_auto
+```
+Fills dimensions with smart crop, adds padding if needed. Requires `g_auto`.
+
+### Auto with Padding (c_auto_pad)
+```
+c_auto_pad,g_auto,h_400,w_600/f_auto/q_auto
+```
+Automatically determines best crop, adds padding if needed. Requires `g_auto`.
+
+### Minimum Fit (c_mfit)
+```
+c_mfit,h_400,w_600/f_auto/q_auto
+```
+Scales up only (opposite of c_limit).
+
+### Imagga Smart Crop
+```
+c_imagga_crop,g_auto,h_400,w_600/f_auto/q_auto
+```
+Uses Imagga's smart cropping algorithm.
+
+## Advanced Gravity Options
+
+### Advanced Eyes Detection
+```
+c_fill,g_adv_eyes,h_300,w_300/f_auto/q_auto
+```
+Focuses on eyes for precise face cropping.
+
+### Multiple Faces
+```
+c_fill,g_faces,h_400,w_600/f_auto/q_auto
+```
+Includes all detected faces in the crop.
+
+### XY Center with Offsets
+```
+c_crop,g_xy_center,h_400,w_600,x_100,y_50/f_auto/q_auto
+```
+Centers crop at specific coordinates with offsets.
+
+## Flags and Special Options
+
+### Progressive Loading
+```
+c_scale,w_800/fl_progressive/f_jpg/q_auto
+```
+Delivers progressive JPEG for better perceived loading.
+
+### Lossy Conversion
+```
+c_scale,w_800/fl_lossy/f_png/q_auto
+```
+Delivers lossy PNG for smaller file size.
+
+### Force Download
+```
+c_scale,w_800/fl_attachment:my-image/f_auto/q_auto
+```
+Forces browser to download instead of display.
+
+### Preserve Transparency
+```
+c_scale,w_800/fl_preserve_transparency/f_png
+```
+Ensures transparency is maintained during transformations.
+
+### No Overflow
+```
+c_scale,w_2000/fl_no_overflow/f_auto/q_auto
+```
+Prevents upscaling beyond original dimensions.
+
+### Immutable Cache
+```
+c_scale,w_800/fl_immutable_cache/f_auto/q_auto
+```
+Enables aggressive CDN caching.
+
+### Region Relative Overlays
+```
+c_crop,h_400,w_600/l_badge/c_scale,fl_region_relative,w_0.3/fl_layer_apply,g_north_east/f_auto/q_auto
+```
+Sizes overlay relative to cropped region, not original image.
+
+## Arithmetic Transformations
+
+### Division
+```
+c_scale,w_div_2/f_auto/q_auto
+```
+Divides width by 2.
+
+### Multiplication
+```
+c_scale,w_mul_1.5/f_auto/q_auto
+```
+Multiplies width by 1.5.
+
+### Addition
+```
+c_crop,h_add_100,w_800/f_auto/q_auto
+```
+Adds 100 pixels to height.
+
+### Subtraction
+```
+c_crop,h_sub_50,w_800/f_auto/q_auto
+```
+Subtracts 50 pixels from height.
+
+### Using Initial Dimensions
+```
+c_scale,w_iw_div_2/f_auto/q_auto
+```
+Sets width to half of initial width (`iw` = initial width).
+
+### Aspect Ratio Calculations
+```
+c_scale,w_800,h_800_div_ar/f_auto/q_auto
+```
+Calculates height based on aspect ratio.
+
+## Context and Metadata Conditionals
+
+### Context-Based Conditional
+```
+if_ctx:!category!_eq_!featured!/l_featured_badge/fl_layer_apply,g_north_east/if_end/f_auto/q_auto
+```
+Adds badge if context category equals "featured".
+
+### Metadata Range Conditional
+```
+if_md:!price!_gt_100/l_premium_badge/fl_layer_apply,g_north_west/if_end/f_auto/q_auto
+```
+Adds premium badge if metadata price > 100.
+
+### Multiple Metadata Conditions
+```
+if_md:!stock!_gt_0_and_md:!featured!_eq_!true!/e_saturation:50/if_end/f_auto/q_auto
+```
+Increases saturation if in stock AND featured.
+
+## Advanced Text Overlays
+
+### Text with Stroke
+```
+co_white,l_text:Arial_60_bold_stroke:Hello/fl_layer_apply,g_center/f_auto/q_auto
+```
+White text with stroke outline.
+
+### Text with Letter Spacing
+```
+co_black,l_text:Arial_40_letter_spacing_10:SPACED/fl_layer_apply,g_center/f_auto/q_auto
+```
+Text with 10px letter spacing.
+
+### Text with Line Spacing
+```
+co_black,l_text:Arial_40_line_spacing_20:Line%20One%0ALine%20Two/fl_layer_apply,g_center/f_auto/q_auto
+```
+Multi-line text with custom line spacing.
+
+### Text with Border
+```
+bo_5px_solid_black,co_white,l_text:Arial_50:Bordered/fl_layer_apply,g_center/f_auto/q_auto
+```
+Text with border.
+
+## Advanced Color Transformations
+
+### Replace Color
+```
+e_replace_color:blue:50:white/f_auto/q_auto
+```
+Replaces blue colors (within 50 tolerance) with white.
+
+### Tint
+```
+co_rgb:ff0000,e_tint:50/f_auto/q_auto
+```
+Applies 50% red tint.
+
+### Contrast and Brightness
+```
+e_brightness:30/e_contrast:20/f_auto/q_auto
+```
+Increases brightness by 30 and contrast by 20.
+
+### Saturation
+```
+e_saturation:50/f_auto/q_auto
+```
+Increases saturation by 50.
+
+### Hue Shift
+```
+e_hue:40/f_auto/q_auto
+```
+Shifts hue by 40 degrees.
+
+## Generative AI Examples
+
+### Generative Fill
+```
+c_pad,ar_16:9,b_gen_fill,w_1200/f_auto/q_auto
+```
+Uses AI to fill padded areas with generated content.
+
+### Generative Replace
+```
+e_gen_replace:from_dog;to_cat/f_auto/q_auto
+```
+Replaces dogs with cats using AI.
+
+### Generative Restore
+```
+e_gen_restore/f_auto/q_auto
+```
+Restores and enhances old or low-quality images.
+
+### Generative Recolor
+```
+e_gen_recolor:prompt_golden%20hour%20lighting/f_auto/q_auto
+```
+Recolors image based on text prompt.
+
+## Quality Variations
+
+### Quality with Chroma Subsampling
+```
+c_scale,w_800/f_jpg/q_80:420
+```
+JPEG quality 80 with 4:2:0 chroma subsampling.
+
+### Quality Range
+```
+c_scale,w_800/f_auto/q_auto:low
+```
+Automatic quality with low setting for smaller files.
+
+## DPR and Responsive
+
+**Important:** `dpr_auto` and `w_auto` parameters only work on Chromium-based browsers (Chrome, Edge, Opera, Samsung Internet) with Client Hints enabled. They do NOT work inside named transformations. For broader browser support, see the [Responsive Images documentation](https://cloudinary.com/documentation/responsive_images).
+
+### Specific DPR
+```
+c_scale,w_400/dpr_2.0/f_auto/q_auto
+```
+Delivers 800px image for 2x displays. Explicit DPR values work in all browsers.
+
+### Auto Breakpoints
+```
+c_fill,g_auto,w_auto:breakpoints/f_auto/q_auto
+```
+Cloudinary generates optimal responsive breakpoints. Requires Client Hints support.
+
+### Breakpoints with Range
+```
+c_fill,g_auto,w_auto:100:1600:80/f_auto/q_auto
+```
+Breakpoints from 100px to 1600px in 80px steps. Requires Client Hints support.
+
+## Fetch Delivery Type
+
+### Fetch Remote Image
+```
+https://res.cloudinary.com/demo/image/fetch/c_scale,w_400/f_auto/q_auto/https://example.com/image.jpg
+```
+Fetches and transforms remote image.
+
+### Fetch with Signature
+```
+https://res.cloudinary.com/demo/image/fetch/s--signature--/c_scale,w_400/f_auto/q_auto/https://example.com/image.jpg
+```
+Fetches remote image with signed URL for security.
diff --git a/skills/cloudinary-transformations/references/named-transformations.md b/skills/cloudinary-transformations/references/named-transformations.md
new file mode 100644
index 0000000..a7dafe8
--- /dev/null
+++ b/skills/cloudinary-transformations/references/named-transformations.md
@@ -0,0 +1,145 @@
+# Named Transformations
+
+Named transformations allow you to save transformation chains with a name (e.g., `t_thumbnail`) and reuse them across your application.
+
+## When to Suggest Named Transformations
+
+- **Transformations used across multiple assets** - Consistency and easy updates
+- **Complex transformation chains** - Easier to maintain and read
+- **Saving money on expensive transformations** - Named transformations are required for baseline transformations, which save processing time and cost by avoiding regeneration of shared transformation steps.
+
+## Example
+
+```
+# Instead of repeating the same transformation:
+❌ c_thumb,g_face,h_200,w_200/r_max/e_sharpen/f_auto/q_auto
+
+# Create named transformation "avatar":
+✅ t_avatar/f_auto/q_auto
+```
+
+## How to Reference Named Transformations
+
+```
+t_<name>                           # Use named transformation
+t_<name>/c_scale,w_500            # Named transformation + additional changes
+c_fill,w_300/t_<name>             # Transform first, then apply named transformation
+```
+
+## Limitations of Named Transformations
+
+**Automatic parameters don't work inside named transformations:**
+- ❌ `f_auto` - Automatic format selection
+- ❌ `dpr_auto` - Automatic DPR matching
+- ❌ `w_auto` - Automatic width matching (with Client Hints)
+
+These parameters rely on runtime information from the client or CDN that isn't available when the named transformation is processed. Use them directly in the URL instead:
+
+```
+# ❌ Don't do this:
+t_product_thumb   # where product_thumb includes f_auto
+
+# ✅ Do this instead:
+t_product_thumb/f_auto/q_auto
+```
+
+See [Limitations of named transformations](https://cloudinary.com/documentation/image_transformations#limitations_of_named_transformations.md) for complete details.
+
+## Baseline Transformations
+
+Baseline transformations (`bl_<named transformation>`) cache the result of a named transformation so it doesn't have to be regenerated when combined with other transformations. This saves processing time and cost.
+
+### When to Use Baseline Transformations
+
+**Especially useful for:**
+- **Expensive AI transformations** (background removal, generative AI, upscaling) - Avoid re-processing
+- **Time-consuming operations** that you'll apply variations to
+- **Transformations with special transformation counts** (75-230 tx) that you need to reuse
+
+**Consider eagerly generating baselines:**
+- On upload using the [upload method](https://cloudinary.com/documentation/image_upload_api_reference#upload_method) or [upload preset](https://cloudinary.com/documentation/upload_presets)
+- For existing assets using the [explicit method](https://cloudinary.com/documentation/image_upload_api_reference#explicit_method)
+
+### Syntax
+
+```
+bl_<named transformation>/<additional transformations>
+```
+
+### Examples
+
+**Example 1: Background removal + grayscale baseline, then add effects**
+```
+# Named transformation "bg_rem_gray_jxl" contains:
+e_background_removal/f_jxl/q_100/e_grayscale
+
+# Use as baseline:
+bl_bg_rem_gray_jxl/e_cartoonify/f_auto/q_auto
+```
+Result: Background removed, grayscale applied once (cached), then cartoonify effect added.
+
+**Example 2: Same baseline, resize and add underlay**
+```
+bl_bg_rem_gray_jxl/c_fill,h_150/u_docs:sky/c_fill,h_150/fl_layer_apply
+```
+
+**Example 3: Video baseline with trimming**
+```
+# Named transformation "first5_rotate" contains:
+du_5/f_mp4/a_15
+
+# Use as baseline:
+bl_first5_rotate/e_loop:2/f_auto/q_auto
+```
+Result: Video trimmed to 5 seconds and rotated once (cached), then looped twice.
+
+### Critical Rules
+
+1. **Baseline must be the first component** in the transformation chain
+2. **Baseline must be the only transformation parameter** in that component
+   - ✅ `bl_bg_removed/c_scale,w_500`
+   - ❌ `bl_bg_removed,c_scale,w_500`
+
+3. **Named transformation must include a format** (`f_`)
+   - Use a supported format transformation (e.g., `f_jxl`, `f_png`, `f_jpg`)
+   - Cannot use `f_auto` in the named transformation (but you can use `f_auto` in subsequent components)
+
+4. **Prevent double lossy encoding**
+   - Consider using `f_jxl/q_100` in the baseline transformation to avoid quality loss
+   - JXL is lossless at q_100, preventing degradation from double encoding
+
+5. **Variables must be defined in the named transformation** if used in the baseline
+
+6. **Not supported for:**
+   - Fetched media (`/fetch/`)
+   - Incoming transformations
+
+### Cost Savings Example
+
+Without baseline:
+```
+# Every URL regenerates the background removal (75 tx each time)
+e_background_removal/c_scale,w_500/f_auto/q_auto     # 75 tx
+e_background_removal/c_fill,h_300,w_400/f_auto/q_auto  # 75 tx
+e_background_removal/e_grayscale/f_auto/q_auto       # 75 tx
+```
+
+With baseline:
+```
+# Named transformation "bg_removed" contains: e_background_removal/f_jxl/q_100
+# Baseline is generated once, then reused (75 tx only once)
+bl_bg_removed/c_scale,w_500/f_auto/q_auto           # 1 tx
+bl_bg_removed/c_fill,h_300,w_400/f_auto/q_auto     # 1 tx
+bl_bg_removed/e_grayscale/f_auto/q_auto            # 1 tx
+```
+
+**Total savings**: 225 tx → 78 tx (75 tx for initial baseline + 3 tx for variations)
+
+For more cost optimization strategies, see [transformation-costs.md](transformation-costs.md)
+
+## Implementation Note
+
+Named transformations are created in the Cloudinary Console or via API. When suggesting them to users, explain:
+1. The transformation would be saved in their Cloudinary account with a name
+2. They can then reference it using `t_<name>` in URLs
+3. For expensive operations, they can generate a baseline transformation eagerly or use `bl_<name>` to cache results
diff --git a/skills/cloudinary-transformations/references/responsive-images.md b/skills/cloudinary-transformations/references/responsive-images.md
new file mode 100644
index 0000000..abaabc3
--- /dev/null
+++ b/skills/cloudinary-transformations/references/responsive-images.md
@@ -0,0 +1,717 @@
+# Responsive Images & Client Hints
+
+Comprehensive guide to creating responsive images with Cloudinary, including `dpr_auto`, `w_auto`, and Client Hints configuration.
+
+## Overview
+
+Cloudinary provides several approaches for responsive images:
+1. **Client Hints** (`dpr_auto`, `w_auto`) - Automatic adaptation (Chromium-only)
+2. **Explicit DPR values** (`dpr_2.0`) - Universal browser support
+3. **JavaScript solutions** - Dynamic responsive images
+4. **Responsive breakpoints** (`w_auto:breakpoints`) - Multiple image sizes
+
+## Device Pixel Ratio (DPR)
+
+### Understanding DPR
+
+DPR represents the ratio between physical pixels and CSS pixels on a device:
+- **1x displays**: Standard screens (DPR = 1.0)
+- **2x displays**: Retina/HiDPI screens (DPR = 2.0)
+- **3x displays**: High-end mobile devices (DPR = 3.0)
+
+**Why it matters:** A 400px wide image needs to be 800px actual size on 2x displays to look sharp.
+
+### `dpr_auto` Parameter
+
+**Syntax:**
+```
+c_scale,w_400/dpr_auto/f_auto/q_auto
+```
+
+**What it does:** Automatically multiplies dimensions by the device's DPR
+- On 1x display: Delivers 400px image
+- On 2x display: Delivers 800px image  
+- On 3x display: Delivers 1200px image
+
+### Browser Compatibility
+
+**✅ Works on Chromium-based browsers:**
+- Google Chrome
+- Microsoft Edge
+- Opera
+- Samsung Internet
+- Brave
+
+**❌ Does NOT work on:**
+- Firefox
+- Safari (macOS and iOS)
+- Other non-Chromium browsers
+
+**Fallback behavior:** When Client Hints unavailable, treats request as `dpr_1.0`
+
+### Named Transformation Limitation
+
+`dpr_auto` does NOT work inside named transformations (similar to `f_auto` and `w_auto`).
+
+**Why:** Client Hints information isn't available when named transformation is processed. The CDN needs to "see" `dpr_auto` directly in the URL to adapt it.
+
+**❌ Don't do this:**
+```
+# Named transformation "product_thumb" contains: c_fill,w_300,h_300/dpr_auto/f_auto
+t_product_thumb
+```
+
+**✅ Do this instead:**
+```
+# Named transformation "product_thumb" contains: c_fill,w_300,h_300
+t_product_thumb/dpr_auto/f_auto/q_auto
+```
+
+## Enabling Client Hints
+
+Client Hints must be enabled for `dpr_auto` and `w_auto` to work.
+
+### HTML Configuration
+
+Add these `<meta>` tags to your HTML `<head>` **before** any `<link>`, `<style>`, or `<script>` elements:
+
+```html
+<meta http-equiv="Accept-CH" content="DPR, Viewport-Width, Width">
+<meta http-equiv="Delegate-CH" content="DPR https://res.cloudinary.com; Viewport-Width https://res.cloudinary.com; Width https://res.cloudinary.com">
+```
+
+**What these do:**
+- `Accept-CH`: Requests browser to send DPR, Viewport-Width, and Width hints
+- `Delegate-CH`: Tells browser to include hints for Cloudinary domain
+
+### HTTP Header Configuration
+
+Alternatively, configure via server HTTP headers:
+
+```http
+Accept-CH: DPR, Viewport-Width, Width
+Delegate-CH: DPR https://res.cloudinary.com; Viewport-Width https://res.cloudinary.com; Width https://res.cloudinary.com
+```
+
+**Use when:**
+- You control the web server configuration
+- Want to avoid adding meta tags to every page
+- Using a CDN with header configuration support
+
+### Verification
+
+Check if Client Hints are working:
+
+**Browser DevTools:**
+1. Open DevTools → Network tab
+2. Load page with Cloudinary images
+3. Find image request
+4. Check Request Headers for: `DPR`, `Viewport-Width`, `Width`
+
+**If headers are missing:** Client Hints aren't enabled or browser doesn't support them.
+
+## Automatic Width (`w_auto`)
+
+### Basic Usage
+
+**Syntax:**
+```
+c_fill,g_auto,w_auto/f_auto/q_auto
+```
+
+**What it does:** Uses `Width` Client Hint to deliver image sized for container width.
+
+**Requirements:**
+- Client Hints enabled (same as `dpr_auto`)
+- Chromium-based browser
+- `Width` hint sent by browser
+
+### Breakpoints
+
+**Automatic breakpoints:**
+```
+c_fill,g_auto,w_auto:breakpoints/f_auto/q_auto
+```
+Cloudinary generates optimal breakpoint set.
+
+**Custom breakpoint range:**
+```
+c_fill,g_auto,w_auto:100:1600:80/f_auto/q_auto
+```
+Creates breakpoints from 100px to 1600px in 80px increments.
+
+**Syntax:** `w_auto:min:max:step`
+- `min`: Minimum width (default 100)
+- `max`: Maximum width (default 3840)
+- `step`: Width increment (default calculated by Cloudinary)
+
+**Use cases:**
+- Responsive hero images
+- Gallery thumbnails that adapt to grid width
+- Product images in flexible layouts
+
+### Combining `dpr_auto` and `w_auto`
+
+```
+c_fill,g_auto,w_auto:breakpoints/dpr_auto/f_auto/q_auto
+```
+
+**Result:** Delivers optimal size for both container width AND device DPR.
+- 400px container on 2x display: ~800px image delivered
+
+**Important:** Both require Client Hints; fallback to standard behavior without them.
+
+## Alternative Approaches
+
+### 1. Explicit DPR Values (Universal Browser Support)
+
+**Best for:** Critical images that must look sharp on Retina displays
+
+```
+c_scale,w_400/dpr_2.0/f_auto/q_auto
+```
+
+**Pros:**
+- ✅ Works in all browsers
+- ✅ Predictable image size
+- ✅ No Client Hints required
+
+**Cons:**
+- ❌ Same 2x image delivered to 1x displays (larger file than needed)
+- ❌ Not adaptive to 3x displays
+
+**Best practice:** Use for hero images, logos, and critical visuals where sharpness matters.
+
+### 2. Multiple Image Variants with `<picture>` Element
+
+**Best for:** Art direction and format flexibility
+
+```html
+<picture>
+  <source 
+    media="(min-width: 1200px)" 
+    srcset="https://res.cloudinary.com/demo/image/upload/c_fill,w_1200/f_auto/q_auto/hero.jpg 1x,
+            https://res.cloudinary.com/demo/image/upload/c_fill,w_2400/f_auto/q_auto/hero.jpg 2x">
+  <source 
+    media="(min-width: 768px)" 
+    srcset="https://res.cloudinary.com/demo/image/upload/c_fill,w_768/f_auto/q_auto/hero.jpg 1x,
+            https://res.cloudinary.com/demo/image/upload/c_fill,w_1536/f_auto/q_auto/hero.jpg 2x">
+  <img 
+    src="https://res.cloudinary.com/demo/image/upload/c_fill,w_400/f_auto/q_auto/hero.jpg"
+    srcset="https://res.cloudinary.com/demo/image/upload/c_fill,w_800/f_auto/q_auto/hero.jpg 2x"
+    alt="Hero image">
+</picture>
+```
+
+**Pros:**
+- ✅ Works in all browsers
+- ✅ Different crops per viewport (art direction)
+- ✅ Explicit control over breakpoints
+
+**Cons:**
+- ❌ More verbose HTML
+- ❌ Manual breakpoint management
+
+### 3. JavaScript-Based Responsive Images
+
+**Best for:** Dynamic, framework-integrated solutions
+
+**Cloudinary JavaScript SDK:**
+```javascript
+import { Cloudinary } from '@cloudinary/url-gen';
+
+const cld = new Cloudinary({ cloud: { cloudName: 'demo' }});
+const image = cld.image('sample')
+  .resize(fill().width('auto').gravity('auto'))
+  .format('auto')
+  .quality('auto');
+```
+
+**React example:**
+```jsx
+import { AdvancedImage, responsive } from '@cloudinary/react';
+
+<AdvancedImage 
+  cldImg={myImage} 
+  plugins={[responsive({ steps: [800, 1200, 1600] })]} 
+/>
+```
+
+**Pros:**
+- ✅ Works in all browsers
+- ✅ Framework integration
+- ✅ Dynamic adaptation
+- ✅ Lazy loading support
+
+**Cons:**
+- ❌ Requires JavaScript
+- ❌ Additional library dependency
+
+### 4. Conditional Transformations (No JS Required)
+
+**Best for:** Server-side or URL-based responsive logic
+
+```
+if_w_gt_2000/c_scale,w_2000/if_else/if_w_gt_1000/c_scale,w_1000/if_else/c_scale,w_800/if_end/if_end/f_auto/q_auto
+```
+
+Adapts to original image size without client-side detection.
+
+**Pros:**
+- ✅ No JavaScript required
+- ✅ Works in all browsers
+- ✅ Based on actual asset dimensions
+
+**Cons:**
+- ❌ Not based on viewport/device
+- ❌ URL can become complex
+
+## Comparison Matrix
+
+| Approach | Browser Support | Client Hints Required | Named Transform Compatible | Complexity |
+|----------|----------------|----------------------|---------------------------|------------|
+| `dpr_auto` | Chromium only | Yes | No | Low |
+| `w_auto` | Chromium only | Yes | No | Low |
+| Explicit DPR | All browsers | No | Yes | Low |
+| `<picture>` element | All browsers | No | Yes | Medium |
+| JavaScript SDK | All browsers | No | Yes | Medium |
+| Conditionals | All browsers | No | Yes | Medium-High |
+
+## Best Practices
+
+### When to Use Client Hints (`dpr_auto`, `w_auto`)
+
+**Use when:**
+- Target audience primarily uses Chrome/Edge
+- Want simplest possible implementation
+- Can accept graceful degradation for other browsers
+- Not using named transformations for these parameters
+
+**Don't use when:**
+- Safari/Firefox users are significant portion of audience
+- Need predictable behavior across all browsers
+- Using within named transformations
+- SEO/crawler rendering is critical (many crawlers don't support Client Hints)
+
+### Recommended Hybrid Approach
+
+**For critical images:**
+```html
+<img 
+  src="https://res.cloudinary.com/demo/image/upload/c_fill,w_400/dpr_2.0/f_auto/q_auto/hero.jpg"
+  srcset="https://res.cloudinary.com/demo/image/upload/c_fill,w_400/dpr_2.0/f_auto/q_auto/hero.jpg 2x,
+          https://res.cloudinary.com/demo/image/upload/c_fill,w_400/dpr_3.0/f_auto/q_auto/hero.jpg 3x">
+```
+Works everywhere, looks sharp on all displays.
+
+**For content images (where Client Hints acceptable):**
+```html
+<img src="https://res.cloudinary.com/demo/image/upload/c_scale,w_800/dpr_auto/f_auto/q_auto/content.jpg">
+```
+Simple implementation, graceful fallback.
+
+### Performance Tips
+
+1. **Combine with lazy loading:**
+   ```html
+   <img loading="lazy" src="...dpr_auto..." />
+   ```
+
+2. **Use `q_auto` with DPR:**
+   ```
+   dpr_2.0/f_auto/q_auto
+   ```
+   Cloudinary adjusts quality to balance sharpness and file size.
+
+3. **Consider bandwidth:**
+   - `dpr_3.0` images are 9x larger than `dpr_1.0` (3² = 9)
+   - Most users don't notice difference between 2x and 3x
+   - Consider capping at `dpr_2.0` for better performance
+
+4. **Cache optimization:**
+   - Limit DPR/breakpoint combinations to reduce cache variations
+   - More variations = more unique cached assets
+
+## Debugging Client Hints
+
+### Issue: `dpr_auto` Not Working
+
+**Check:**
+1. **Browser compatibility**: Only Chromium-based browsers support Client Hints
+2. **Meta tags present**: Verify `<meta http-equiv="Accept-CH">` in HTML
+3. **Request headers**: Check DevTools → Network → Request Headers for `DPR` header
+4. **Named transformation**: Ensure `dpr_auto` is in URL, not inside named transformation
+
+**Common causes:**
+- Using Firefox or Safari (not supported)
+- Meta tags missing or in wrong location
+- Meta tags after `<link>` or `<script>` tags
+- `dpr_auto` inside named transformation
+
+### Issue: Different Image Sizes Than Expected
+
+**Remember:** `dpr_auto` multiplies your specified dimensions
+```
+w_400/dpr_auto on 2x display = 800px actual width
+```
+
+**To get 400px CSS width:**
+- Specify `w_400` in transformation
+- Browser will display at 400px CSS (800px physical on 2x)
+
+### Issue: Large File Sizes with `dpr_auto`
+
+**Cause:** Higher DPR = larger images (quadratic growth)
+- `dpr_1.0`: 400×300 = 120,000 pixels
+- `dpr_2.0`: 800×600 = 480,000 pixels (4x larger)
+- `dpr_3.0`: 1200×900 = 1,080,000 pixels (9x larger)
+
+**Solutions:**
+1. Use `q_auto` to optimize quality based on dimensions
+2. Consider `q_auto:eco` for 2x+ displays
+3. Limit max DPR: Use explicit `dpr_2.0` instead of `dpr_auto`
+4. Use format optimization: `f_auto` delivers WebP to supported browsers
+
+## Responsive Breakpoints
+
+### Automatic Breakpoint Generation
+
+```
+c_fill,g_auto,w_auto:breakpoints/f_auto/q_auto
+```
+
+**What it does:** Cloudinary analyzes image and generates optimal breakpoint set
+- Typically 5-10 breakpoints
+- Balanced between number of variants and file size optimization
+- Adapts to image content (more breakpoints for detailed images)
+
+**Use when:**
+- You don't know ideal breakpoint sizes
+- Want Cloudinary to optimize automatically
+- Content images with varying dimensions
+
+### Custom Breakpoint Range
+
+```
+w_auto:100:1600:80
+```
+
+**Syntax:** `w_auto:min:max:step`
+- **min**: Minimum width in pixels (default 100)
+- **max**: Maximum width in pixels (default 3840)
+- **step**: Increment between breakpoints (default: calculated by Cloudinary)
+
+**Examples:**
+```
+w_auto:200:1200:100        # 200, 300, 400... 1200 (11 breakpoints)
+w_auto:320:1920:320        # 320, 640, 960, 1280, 1600, 1920 (6 breakpoints)
+w_auto:100:2000            # Let Cloudinary calculate step size
+```
+
+**Use when:**
+- You know your layout breakpoints
+- Want to match CSS media queries
+- Need specific image sizes
+
+### Combining with DPR
+
+```
+c_fill,g_auto,w_auto:breakpoints/dpr_auto/f_auto/q_auto
+```
+
+**Result:** Adapts to BOTH container width AND device DPR
+- 600px container on 2x display: ~1200px image
+- 800px container on 1x display: ~800px image
+
+**Trade-off:** Creates many cached variations (breakpoints × DPR values)
+
+## Client Hints Headers Reference
+
+### Request Headers (Browser → Server)
+
+When Client Hints are enabled, browsers send:
+
+**DPR Header:**
+```
+DPR: 2.0
+```
+Indicates device pixel ratio.
+
+**Width Header:**
+```
+Width: 800
+```
+Indicates layout width of image in CSS pixels.
+
+**Viewport-Width Header:**
+```
+Viewport-Width: 1920
+```
+Indicates viewport width in CSS pixels.
+
+### Using in Server-Side Rendering
+
+Access Client Hints in server code:
+
+**Node.js/Express:**
+```javascript
+app.get('/image', (req, res) => {
+  const dpr = req.headers.dpr || '1.0';
+  const width = req.headers.width || '800';
+  
+  const imageUrl = `https://res.cloudinary.com/demo/image/upload/c_scale,w_${width}/dpr_${dpr}/f_auto/q_auto/sample.jpg`;
+  
+  res.send(`<img src="${imageUrl}">`);
+});
+```
+
+**Why:** Server can generate optimal image URLs based on actual device capabilities.
+
+## Real-World Patterns
+
+### Pattern 1: Progressive Enhancement
+
+**Base:** Works everywhere
+```html
+<img src="https://res.cloudinary.com/demo/image/upload/c_scale,w_800/dpr_2.0/f_auto/q_auto/product.jpg">
+```
+
+**Enhanced:** Better for Chrome/Edge users
+```html
+<meta http-equiv="Accept-CH" content="DPR">
+<img src="https://res.cloudinary.com/demo/image/upload/c_scale,w_800/dpr_auto/f_auto/q_auto/product.jpg">
+```
+
+### Pattern 2: Responsive Grid
+
+```html
+<meta http-equiv="Accept-CH" content="Width, DPR">
+
+<div class="grid">
+  <img src="https://res.cloudinary.com/demo/image/upload/c_fill,g_auto,w_auto:200:800:100/dpr_auto/f_auto/q_auto/img1.jpg">
+  <img src="https://res.cloudinary.com/demo/image/upload/c_fill,g_auto,w_auto:200:800:100/dpr_auto/f_auto/q_auto/img2.jpg">
+</div>
+```
+
+Each image adapts to grid cell width and device DPR.
+
+### Pattern 3: Named Transformation + Auto Parameters
+
+```
+# Named transformation "product_square":
+c_fill,g_auto,h_800,w_800
+
+# Usage:
+t_product_square/dpr_auto/f_auto/q_auto
+```
+
+Combines reusable named transformation with auto parameters.
+
+### Pattern 4: Art Direction with Client Hints
+
+```html
+<picture>
+  <source 
+    media="(min-width: 1200px)" 
+    srcset="https://res.cloudinary.com/demo/image/upload/c_fill,w_1200,ar_21:9/dpr_auto/f_auto/q_auto/hero.jpg">
+  <source 
+    media="(min-width: 768px)" 
+    srcset="https://res.cloudinary.com/demo/image/upload/c_fill,w_768,ar_16:9/dpr_auto/f_auto/q_auto/hero.jpg">
+  <img 
+    src="https://res.cloudinary.com/demo/image/upload/c_fill,w_400,ar_4:3/dpr_auto/f_auto/q_auto/hero.jpg">
+</picture>
+```
+
+Different aspect ratios per viewport + DPR adaptation.
+
+## Framework Integration
+
+### React with Cloudinary SDK
+
+```jsx
+import { Cloudinary } from '@cloudinary/url-gen';
+import { AdvancedImage, responsive } from '@cloudinary/react';
+import { fill } from '@cloudinary/url-gen/actions/resize';
+import { autoGravity } from '@cloudinary/url-gen/qualifiers/gravity';
+
+const cld = new Cloudinary({ cloud: { cloudName: 'demo' }});
+
+const MyImage = () => {
+  const img = cld.image('sample')
+    .resize(fill().width(800).gravity(autoGravity()))
+    .format('auto')
+    .quality('auto');
+  
+  return <AdvancedImage 
+    cldImg={img} 
+    plugins={[responsive({ steps: [400, 800, 1200, 1600] })]} 
+  />;
+};
+```
+
+### Vue with Cloudinary SDK
+
+```vue
+<template>
+  <cld-image 
+    cloudName="demo" 
+    publicId="sample"
+    :responsive
+    :plugins="[responsivePlugin]">
+    <cld-transformation 
+      crop="fill" 
+      width="800" 
+      gravity="auto" />
+  </cld-image>
+</template>
+
+<script>
+import { responsive } from '@cloudinary/vue';
+
+export default {
+  data() {
+    return {
+      responsivePlugin: responsive({ steps: [400, 800, 1200] })
+    };
+  }
+};
+</script>
+```
+
+### Next.js with Cloudinary Loader
+
+```javascript
+// next.config.js
+module.exports = {
+  images: {
+    loader: 'cloudinary',
+    path: 'https://res.cloudinary.com/demo/image/upload/',
+  },
+};
+```
+
+```jsx
+import Image from 'next/image';
+
+<Image 
+  src="sample.jpg" 
+  width={800} 
+  height={600}
+  alt="Sample"
+/>
+```
+
+Next.js automatically generates responsive variants.
+
+## Migration from Static to Responsive
+
+### Step 1: Audit Current Implementation
+
+Identify static image URLs:
+```html
+<!-- Static (non-responsive) -->
+<img src="https://res.cloudinary.com/demo/image/upload/w_800/product.jpg">
+```
+
+### Step 2: Add Client Hints
+
+Add meta tags to HTML `<head>`:
+```html
+<meta http-equiv="Accept-CH" content="DPR, Viewport-Width, Width">
+<meta http-equiv="Delegate-CH" content="DPR https://res.cloudinary.com; Viewport-Width https://res.cloudinary.com">
+```
+
+### Step 3: Update URLs
+
+**Option A:** Simple DPR adaptation (works for Chromium)
+```html
+<img src="https://res.cloudinary.com/demo/image/upload/c_scale,w_800/dpr_auto/f_auto/q_auto/product.jpg">
+```
+
+**Option B:** Full responsive (works for Chromium)
+```html
+<img src="https://res.cloudinary.com/demo/image/upload/c_fill,g_auto,w_auto:200:1600/dpr_auto/f_auto/q_auto/product.jpg">
+```
+
+**Option C:** Universal browser support
+```html
+<img 
+  src="https://res.cloudinary.com/demo/image/upload/c_scale,w_800/f_auto/q_auto/product.jpg"
+  srcset="https://res.cloudinary.com/demo/image/upload/c_scale,w_800/dpr_2.0/f_auto/q_auto/product.jpg 2x">
+```
+
+### Step 4: Test
+
+**Test in multiple browsers:**
+- Chrome (Client Hints should work)
+- Safari (should fallback gracefully)
+- Mobile devices (check 2x/3x displays)
+
+**Check DevTools:**
+- Network tab: Verify image sizes delivered
+- Request headers: Confirm DPR/Width hints sent (Chrome)
+- Rendered size: Images should look sharp
+
+## Performance Monitoring
+
+### Metrics to Track
+
+1. **Image byte size**: Should decrease for 1x displays when using `dpr_auto`
+2. **LCP (Largest Contentful Paint)**: Responsive images should improve load times
+3. **Cache hit rate**: Too many variations can reduce cache effectiveness
+
+### Optimization Tips
+
+1. **Limit breakpoint count**: 5-8 breakpoints is usually sufficient
+2. **Use `q_auto`**: Automatically optimizes quality based on dimensions
+3. **Consider CDN caching**: More variations = more cached assets
+4. **Monitor Client Hints adoption**: Track browser usage to assess benefit
+
+## Troubleshooting
+
+### Images Too Large on Mobile
+
+**Check:**
+- Is `w_auto` working? (requires Client Hints + Chromium)
+- Did you set max width in `w_auto:min:max` range?
+- Consider using explicit `<picture>` element for better control
+
+**Fix:**
+```
+<!-- Add max width -->
+c_fill,g_auto,w_auto:100:1000/dpr_auto/f_auto/q_auto
+```
+
+### Images Blurry on Retina Displays
+
+**Check:**
+- Is `dpr_auto` in the URL?
+- Are Client Hints enabled and working?
+- Is browser Chromium-based?
+
+**Fix for all browsers:**
+```html
+<img 
+  srcset="url/dpr_1.0/... 1x,
+          url/dpr_2.0/... 2x">
+```
+
+### Too Many Cached Variations
+
+**Cause:** Many breakpoints × DPR values = cache fragmentation
+
+**Solutions:**
+1. Reduce breakpoint count
+2. Use fewer DPR values (cap at 2.0)
+3. Use named transformations to share common processing
+4. Consider single 2x image for simpler caching
+
+## Additional Resources
+
+- [Responsive Images using Client Hints](https://cloudinary.com/documentation/responsive_server_side_client_hints.md)
+- [Responsive Images Overview](https://cloudinary.com/documentation/responsive_images.md)
+- [Responsive images using HTML and dynamic image transformations](https://cloudinary.com/documentation/responsive_html.md)
+- [Responsive images using JavaScript frontend frameworks](https://cloudinary.com/documentation/responsive_client_side_fe_frameworks.md)
+- [Responsive images using the cloudinary-core JS library](https://cloudinary.com/documentation/responsive_client_side_js.md)
+- [Cloudinary SDKs](https://cloudinary.com/documentation/cloudinary_sdks.md)
+- [React SDK Documentation](https://cloudinary.com/documentation/react_integration.md)
diff --git a/skills/cloudinary-transformations/references/transformation-costs.md b/skills/cloudinary-transformations/references/transformation-costs.md
new file mode 100644
index 0000000..f2eb5f8
--- /dev/null
+++ b/skills/cloudinary-transformations/references/transformation-costs.md
@@ -0,0 +1,26 @@
+# Transformation Costs & Cost Reduction
+
+**Important**: Different transformations have different costs. Be aware of high-cost operations and warn the user before generating transformations that cost more than a standard transformation.
+
+**Note:** "tx" = transformation credits. Numbers shown (e.g., 75 tx) indicate additional transformation credits consumed per use.
+
+## Standard Transformations
+- Basic image transformations: 1 transformation credit (1 tx)
+- Video transformations: Counted per second (varies by resolution and codec)
+
+## High-Cost Effects (per use)
+- **Generative AI**: `e_gen_background_replace` (230 tx), `e_gen_replace` (120 tx), `e_gen_restore` (100 tx)
+- **AI Enhancement**: `e_auto_enhance` (100 tx), `e_enhance` (100 tx)
+- **Background Removal**: `e_background_removal` (75 tx), `e_extract` (75 tx)
+- **Generative Edits**: `b_gen_fill` (50 tx), `e_gen_recolor` (50 tx), `e_gen_remove` (50 tx)
+- **Upscale**: `e_upscale` (10-100 tx depending on input size)
+
+## Strategies to Reduce Costs
+
+1. **Use baseline transformations** for expensive effects: Baseline transformations (`bl_<named>`) cache expensive operations (like `e_background_removal`, 75 tx) so they don't have to be regenerated for each variation. See [named-transformations.md](named-transformations.md#baseline-transformations) for complete details on syntax, rules, and cost savings examples.
+2. **Reuse derived assets**: Multiple requests to the same transformation URL don't incur additional costs
+3. **Avoid unnecessary variations**: Different parameter orders create separate derived assets (e.g., `w_200,h_200` vs `h_200,w_200`)
+4. **Consider format costs**: AVIF images cost 1 tx per 2MP (or part thereof)
+5. **Video considerations**: HD video (1080p) costs more than SD (720p); AV1 codec costs significantly more than H.264
+
+For complete transformation cost details, see [How are transformations counted?](https://cloudinary.com/documentation/transformation_counts.md)
diff --git a/skills/cloudinary-transformations/references/video-transformations.md b/skills/cloudinary-transformations/references/video-transformations.md
new file mode 100644
index 0000000..ca8a88b
--- /dev/null
+++ b/skills/cloudinary-transformations/references/video-transformations.md
@@ -0,0 +1,69 @@
+# Video-Specific Transformations
+
+## Important: Format Parameter for Videos
+
+**Critical:** When using `f_auto` on video URLs, you must specify `f_auto:video` to ensure a video is returned (not an image thumbnail):
+
+```
+f_auto:video                   # Returns video in optimal format (NOT an image)
+f_auto                         # May return an image ⚠️
+```
+
+**Always use `f_auto:video` or a specific video format** (`f_mp4`, `f_webm`, etc.) when transforming videos.
+
+## Video Codec (`vc_`)
+
+```
+vc_auto                        # Automatic codec selection (recommended)
+vc_h264:high:4.1               # H.264 with profile and level
+vc_h265, vc_vp8, vc_vp9, vc_av1  # Other codecs
+vc_none                        # Remove video, keep audio only
+```
+
+**Key options:** h264 profiles (`baseline`, `main`, `high`), levels (`3.0`-`5.2`)
+
+## Trimming Videos (`so_`, `eo_`, `du_`)
+
+```
+so_6.5                         # Start at 6.5 seconds
+eo_10                          # End at 10 seconds
+du_15                          # Duration of 15 seconds
+so_10p, eo_90p, du_30p         # Percentage-based (0p-100p)
+```
+
+**Value formats:** Seconds (float) or percentage (`10p`)
+
+## Audio Control (`ac_`)
+
+```
+ac_none                        # Remove audio track (for autoplay)
+ac_aac, ac_mp3, ac_vorbis, ac_opus  # Audio codecs
+```
+
+## Frame Rate (`fps_`)
+
+```
+fps_30                         # Set FPS (ensures audio sync)
+fps_20-25                      # FPS range
+```
+
+## Video Concatenation (`fl_splice`)
+
+**Pattern:**
+1. Declare: `fl_splice,l_video:<public_id>`
+2. Transform overlay (optional)
+3. Apply: `fl_layer_apply` (with `so_0` to splice at beginning)
+
+```
+c_fill,h_300,w_450/du_5/fl_splice,l_video:second_clip/c_fill,h_300,w_450/du_5/fl_layer_apply
+```
+
+**Important:** Both videos should be resized to matching dimensions before splicing
+
+## Common Video Patterns
+
+```
+du_5/vc_auto/f_auto:video/q_auto                             # 5-second video preview
+ac_none/vc_h264/f_mp4/q_auto                                 # Silent video (autoplay)
+c_limit,h_720/vc_auto/f_auto:video/q_auto                    # 720p cap with auto format
+```
diff --git a/templates/.cursorrules.template b/templates/.cursorrules.template
deleted file mode 100644
index c95f311..0000000
--- a/templates/.cursorrules.template
+++ /dev/null
@@ -1,874 +0,0 @@
-# Cloudinary React SDK Patterns & Common Errors
-
-**Scope**: These rules apply to **React (web)** with the browser Upload Widget. The **default** is **Vite** (create-cloudinary-react uses Vite). They also work with **other bundlers** (Create React App, Next.js, Parcel, etc.): only **how you read env vars** changes; see **"Other bundlers (non-Vite)"** below. Rules-only users: see **"Project setup (rules-only / without CLI)"** for the reusable Cloudinary instance, env, Upload Widget (unsigned/signed), and video player. For **React Native** uploads (including signed upload), see: https://cloudinary.com/documentation/react_native_image_and_video_upload#signed_upload — same “never expose secret, generate signature on backend” principle, but React Native uses the `upload()` method and backend SDKs differently.
-
-## Official Documentation
-- **Transformation Rules**: https://cloudinary.com/documentation/cloudinary_transformation_rules.md
-- **Transformation Reference**: https://cloudinary.com/documentation/transformation_reference.md
-- **React Image Transformations & Plugins**: https://cloudinary.com/documentation/react_image_transformations.md#plugins
-- **React Video Transformations**: https://cloudinary.com/documentation/react_video_transformations.md
-- **Cloudinary Video Player** (standalone player): https://cloudinary.com/documentation/cloudinary_video_player.md
-- **Video Player React Tutorial**: https://cloudinary.com/documentation/video_player_react_tutorial.md
-- **Upload Widget (signed uploads)**: https://cloudinary.com/documentation/upload_widget.md#signed_uploads
-- **Upload assets in Next.js (backend signature)**: https://cloudinary.com/documentation/upload_assets_in_nextjs_tutorial.md
-- **Cloudinary Node.js SDK (server-side signing)** — use **v2**: `import { v2 as cloudinary } from 'cloudinary'`; do not use v1 (e.g. 1.47.0). https://cloudinary.com/documentation/node_integration.md
-- **React Native image and video upload (signed)**: https://cloudinary.com/documentation/react_native_image_and_video_upload.md#signed_upload
-- Always consult the official transformation rules when creating transformations
-- Use only officially supported parameters from the transformation reference
-
-**Golden rule for @cloudinary/url-gen:** When generating overlay or transformation code, use **only** the "Import reference" table and "Canonical overlay block" in these rules. Copy those import paths and usage patterns exactly; do not guess or derive paths (e.g. `text` and `image` are from `qualifiers/source`, not `actions/overlay`; `Position` is from `qualifiers/position`, not `positioning/Position`).
-
----
-
-# 📋 PATTERNS (How to Do It Right)
-
-## Project setup (rules-only / without CLI)
-
-If the user is **not** using the create-cloudinary-react CLI and only has these rules, generate the following so they get correct config, env, and widget setup.
-
-**1. Environment (.env)**  
-Create a `.env` file in the project root with **Vite prefix** (required for client access):
-- `VITE_CLOUDINARY_CLOUD_NAME=your_cloud_name` (required)
-- `VITE_CLOUDINARY_UPLOAD_PRESET=your_unsigned_preset_name` (optional; required for unsigned upload widget)
-- Save the `.env` file after editing it, then restart the dev server so changes load correctly. Use `import.meta.env.VITE_*` in code, not `process.env`.
-
-**2. Reusable Cloudinary instance (config)**  
-Create a config file (e.g. `src/cloudinary/config.ts`) so the rest of the app can use a single `cld` instance:
-```ts
-import { Cloudinary } from '@cloudinary/url-gen';
-
-const cloudName = import.meta.env.VITE_CLOUDINARY_CLOUD_NAME;
-if (!cloudName) {
-  throw new Error('VITE_CLOUDINARY_CLOUD_NAME is not set. Add it to .env with the VITE_ prefix.');
-}
-
-export const cld = new Cloudinary({ cloud: { cloudName } });
-export const uploadPreset = import.meta.env.VITE_CLOUDINARY_UPLOAD_PRESET || '';
-```
-- Use **this** pattern for the reusable instance. Everywhere else: `import { cld } from './cloudinary/config'` (or the path the user chose) and call `cld.image(publicId)` / `cld.video(publicId)`.
-
-**3. Upload Widget (unsigned, from scratch)**  
-
-**Strict pattern (always follow this exactly):**
-1. **Script in `index.html`** (required): Add `<script src="https://upload-widget.cloudinary.com/global/all.js" async></script>` to `index.html`. Do **not** rely only on dynamic script injection from React — it's fragile.
-2. **Poll in useEffect** (required): In `useEffect`, poll with `setInterval` (e.g. every 100ms) until `typeof window.cloudinary?.createUploadWidget === 'function'`. Only then create the widget. A single check (even in `onload`) is **not** reliable because `window.cloudinary` can exist before `createUploadWidget` is attached.
-3. **Add a timeout**: Set a timeout (e.g. 10 seconds) to stop polling and show an error if the script never loads. Clear both interval and timeout in cleanup.
-4. **Create widget once**: When `createUploadWidget` is available, create the widget and store it in a **ref**. Clear the interval and timeout. Pass options: `{ cloudName, uploadPreset, sources: ['local', 'camera', 'url'], multiple: false }`.
-5. **Open on click**: Attach a click listener to a button that calls `widgetRef.current?.open()`. Remove the listener in useEffect cleanup.
-
-❌ **Do NOT**: Check only `window.cloudinary` (not enough); do a single check in `onload` (unreliable); skip the script in `index.html`; poll forever without a timeout.
-- **Signed uploads**: Do not use only `uploadPreset`; use the pattern under "Secure (Signed) Uploads" (uploadSignature as function, fetch api_key, server includes upload_preset in signature).
-
-**4. Video player**  
-- Use imperative video element only (create with document.createElement, append to container ref, pass to videoPlayer). See "Cloudinary Video Player (The Player)" for the full pattern.
-
-**5. Summary for rules-only users**  
-- **Env**: Use your bundler's client env prefix and access (Vite: `VITE_` + `import.meta.env.VITE_*`; see "Other bundlers" if not Vite).
-- **Reusable instance**: One config file that creates and exports `cld` (and optionally `uploadPreset`) from `@cloudinary/url-gen`; use it everywhere.
-- **Upload widget**: Script in index.html (required); in useEffect, **poll** until `createUploadWidget` is a function, then create widget once and store in ref; unsigned = cloudName + uploadPreset; signed = use uploadSignature function and backend.
-- **Video player**: Imperative video element (createElement, append to container ref, pass to videoPlayer); dispose + removeChild in cleanup; fall back to AdvancedVideo if init fails.
-
-**If the user is not using Vite:** Use their bundler's client env prefix and access in the config file and everywhere you read env. Examples: Create React App → `REACT_APP_CLOUDINARY_CLOUD_NAME`, `process.env.REACT_APP_CLOUDINARY_CLOUD_NAME`; Next.js (client) → `NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME`, `process.env.NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME`. The rest (cld instance, widget options, video player) is the same.
-
-## Environment Variables
-- **Default: Vite** — Vite requires `VITE_` prefix; use `import.meta.env.VITE_CLOUDINARY_CLOUD_NAME` (not `process.env`). Restart dev server after changing `.env`.
-- ✅ CORRECT (Vite): `VITE_CLOUDINARY_CLOUD_NAME=mycloud` in `.env`; `import.meta.env.VITE_CLOUDINARY_CLOUD_NAME`
-
-## Other bundlers (non-Vite)
-- **Only the env access changes.** All other patterns (reusable `cld`, Upload Widget, Video Player, overlays, signed uploads) are bundler-agnostic.
-- **Create React App**: Prefix `REACT_APP_`; access `process.env.REACT_APP_CLOUDINARY_CLOUD_NAME`, `process.env.REACT_APP_CLOUDINARY_UPLOAD_PRESET`. Restart dev server after `.env` changes.
-- **Next.js (client)**: Prefix `NEXT_PUBLIC_` for client; access `process.env.NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME`, etc. Server-side can use `process.env.CLOUDINARY_*` without `NEXT_PUBLIC_`.
-- **Parcel / other**: Check the bundler's docs for "exposing environment variables to the client" (often a prefix or allowlist). Use that prefix and the documented access (e.g. `process.env.*`).
-- **Config file**: In `src/cloudinary/config.ts` (or equivalent), read cloud name and upload preset using the **user's bundler** env API (e.g. for CRA: `process.env.REACT_APP_CLOUDINARY_CLOUD_NAME`). Same `new Cloudinary({ cloud: { cloudName } })` and exports; only the env read line changes.
-
-## Upload Presets
-- **Unsigned** = client-only uploads (no backend). **Signed** = backend required, more secure. See **"Signed vs unsigned uploads"** below for when to use which.
-- ✅ Create unsigned upload preset (for simple client uploads): https://console.cloudinary.com/app/settings/upload/presets
-- ✅ Set preset in `.env`: `VITE_CLOUDINARY_UPLOAD_PRESET=your-preset-name`
-- ✅ Use in code: `import { uploadPreset } from './cloudinary/config'`
-- ⚠️ If upload preset is missing, the Upload Widget will show an error message
-- ⚠️ Upload presets must be set to "Unsigned" mode for client-side usage (no API key/secret needed)
-- **When unsigned upload fails**: First check that the user configured their upload preset:
-  1. Is `VITE_CLOUDINARY_UPLOAD_PRESET` set in `.env`? (must match preset name exactly)
-  2. Does the preset exist in the dashboard under Settings → Upload → Upload presets?
-  3. Is the preset set to **Unsigned** (not Signed)?
-  4. Was the dev server restarted after adding/updating `.env`?
-
-## Installing Cloudinary packages
-- ✅ **Install the latest**: When adding Cloudinary packages, use `npm install <package>` **with no version** so npm installs the latest compatible version (e.g. `npm install cloudinary-video-player`). In package.json use a **caret range** (e.g. `"cloudinary-video-player": "^1.0.0"`) so future installs get the latest compatible. Do not pin to an exact version unless you have verified it exists on npm.
-- ✅ **Package names only**: Use **only** these names: `@cloudinary/react`, `@cloudinary/url-gen`, `cloudinary-video-player` (standalone player), `cloudinary` (Node server-side only). Do not invent names (e.g. no `@cloudinary/video-player`).
-- ❌ **WRONG**: `npm install cloudinary-video-player@1.2.3` or `"cloudinary-video-player": "1.2.3"` (exact pin) — versions may not exist and break installs.
-- ✅ **Correct**: `npm install cloudinary-video-player` (no version) or in package.json: `"cloudinary-video-player": "^1.0.0"` (caret = latest compatible).
-
-## Import Patterns
-- ✅ Import Cloudinary instance: `import { cld } from './cloudinary/config'`
-- ✅ Import components: `import { AdvancedImage, AdvancedVideo } from '@cloudinary/react'`
-- ✅ Import plugins: `import { responsive, lazyload, placeholder } from '@cloudinary/react'`
-- ✅ **For transformations and overlays**, use **only** the exact paths in "Import reference: @cloudinary/url-gen" and the "Canonical overlay block" below. Do **not** guess subpaths (e.g. `text` and `image` are from `qualifiers/source`, not `actions/overlay`).
-
-## Import reference: @cloudinary/url-gen (use these exact paths only)
-
-**Rule:** Do not invent or guess import paths for `@cloudinary/url-gen`. Use **only** the paths in the table and canonical block below. Copy the import statements exactly; do not derive paths (e.g. `@cloudinary/url-gen/overlay` exports only `source` — `text` and `image` are from **`qualifiers/source`**; `Position` is from **`qualifiers/position`**, not `positioning/Position`). Wrong paths cause "module not found" or "does not exist".
-
-| Purpose | Exact import |
-|--------|----------------|
-| Cloudinary instance (config) | `import { Cloudinary } from '@cloudinary/url-gen';` |
-| Resize (fill) | `import { fill } from '@cloudinary/url-gen/actions/resize';` |
-| Resize (scale, for overlays) | `import { scale } from '@cloudinary/url-gen/actions/resize';` |
-| Delivery format/quality | `import { format, quality } from '@cloudinary/url-gen/actions/delivery';` |
-| Format qualifier (auto) | `import { auto } from '@cloudinary/url-gen/qualifiers/format';` |
-| Quality qualifier (auto) | `import { auto as autoQuality } from '@cloudinary/url-gen/qualifiers/quality';` |
-| Effects (e.g. blur) | `import { blur } from '@cloudinary/url-gen/actions/effect';` |
-| Overlay source | `import { source } from '@cloudinary/url-gen/actions/overlay';` |
-| Overlay text / image (source types) | `import { text, image } from '@cloudinary/url-gen/qualifiers/source';` |
-| Overlay image transformation | `import { Transformation } from '@cloudinary/url-gen/transformation/Transformation';` |
-| Position (overlay) | `import { Position } from '@cloudinary/url-gen/qualifiers/position';` |
-| Gravity/compass | `import { compass } from '@cloudinary/url-gen/qualifiers/gravity';` |
-| Text style (overlay) | `import { TextStyle } from '@cloudinary/url-gen/qualifiers/textStyle';` |
-| Types | `import type { CloudinaryImage, CloudinaryVideo } from '@cloudinary/url-gen';` |
-
-**Canonical overlay block (copy these imports and patterns exactly):**
-```ts
-// Overlay imports — text/image from qualifiers/source, NOT actions/overlay
-import { source } from '@cloudinary/url-gen/actions/overlay';
-import { text, image } from '@cloudinary/url-gen/qualifiers/source';
-import { Position } from '@cloudinary/url-gen/qualifiers/position';
-import { TextStyle } from '@cloudinary/url-gen/qualifiers/textStyle';
-import { compass } from '@cloudinary/url-gen/qualifiers/gravity';
-import { Transformation } from '@cloudinary/url-gen/transformation/Transformation';
-import { scale } from '@cloudinary/url-gen/actions/resize';
-
-// Text overlay (compass with underscores: 'south_east', 'center')
-cld.image('id').overlay(
-  source(text('Hello', new TextStyle('Arial', 60).fontWeight('bold')).textColor('white'))
-    .position(new Position().gravity(compass('center')))
-);
-
-// Image overlay (logo/image with resize)
-cld.image('id').overlay(
-  source(image('logo').transformation(new Transformation().resize(scale().width(100))))
-    .position(new Position().gravity(compass('south_east')).offsetX(20).offsetY(20))
-);
-```
-
-- **Components** (AdvancedImage, AdvancedVideo, plugins) come from **`@cloudinary/react`**, not from `@cloudinary/url-gen`.
-- **Transformation actions and qualifiers** (resize, delivery, effect, overlay, etc.) come from **`@cloudinary/url-gen/actions/*`** and **`@cloudinary/url-gen/qualifiers/*`** with the exact subpaths above.
-- If an import fails, verify the package version (`@cloudinary/url-gen` in package.json) and the [Cloudinary URL-Gen SDK docs](https://cloudinary.com/documentation/sdks/js/url-gen/index.html) or [Transformation Builder reference](https://cloudinary.com/documentation/sdks/js/transformation_builder_reference).
-
-## Creating Image & Video Instances
-- ✅ Create image instance: `const img = cld.image(publicId)`
-- ✅ Create video instance: `const video = cld.video(publicId)` (same pattern as images)
-- ✅ Public ID format: Use forward slashes for folders (e.g., `'folder/subfolder/image'`)
-- ✅ Public IDs are case-sensitive and should not include file extensions
-- ✅ **Sample assets**: Cloudinary may provide sample assets under `samples/`. **Assume they might not exist** (users can delete them); always handle load errors and provide fallbacks (see Image gallery). When they exist, use them for examples and demos instead of requiring uploads first.
-- ✅ **Sample public IDs that may be available** (use for galleries, demos; handle onError if missing):
-  - Images: `samples/cloudinary-icon`, `samples/two-ladies`, `samples/food/spices`, `samples/landscapes/beach-boat`, `samples/bike`, `samples/landscapes/girl-urban-view`, `samples/animals/reindeer`, `samples/food/pot-mussels`
-  - Video: `samples/elephants`
-- ✅ **Default / most reliable**: Start with `samples/cloudinary-icon` for a single image; use the list above for galleries or variety. Prefer uploaded assets when the user has them.
-- ✅ Examples:
-  ```tsx
-  const displayImage = cld.image('samples/cloudinary-icon');
-  const displayVideo = cld.video('samples/elephants');
-  // Gallery: e.g. ['samples/bike', 'samples/landscapes/beach-boat', 'samples/food/spices', ...]
-  ```
-
-## Transformation Patterns
-
-### Image Transformations
-- ✅ Chain transformations on image instance:
-  ```tsx
-  const img = cld.image('id')
-    .resize(fill().width(800).height(600))
-    .effect(blur(800))
-    .delivery(format(auto()))
-    .delivery(quality(autoQuality()));
-  ```
-- ✅ Pass to component: `<AdvancedImage cldImg={img} />`
-
-### Video Transformations
-- ✅ Chain transformations on video instance (same pattern as images):
-  ```tsx
-  const video = cld.video('id')
-    .resize(fill().width(800).height(600))
-    .delivery(format(auto()));
-  ```
-- ✅ Pass to component: `<AdvancedVideo cldVid={video} />`
-- ✅ Video transformations work the same way as image transformations
-
-### Transformation Best Practices
-- ✅ Format and quality must use separate `.delivery()` calls
-- ✅ Always end with auto format/quality: `.delivery(format(auto())).delivery(quality(autoQuality()))` unless user specifies a particular format or quality
-- ✅ Use `gravity(auto())` unless user specifies a focal point
-- ✅ Same transformation syntax works for both images and videos
-
-## Plugin Patterns
-- ✅ **When the user asks for lazy loading or responsive images**: Use the **Cloudinary plugins** from `@cloudinary/react` — `responsive()`, `lazyload()`, `placeholder()` — with `AdvancedImage`. Do not use only native `loading="lazy"` or CSS-only responsive; the Cloudinary plugins handle breakpoints, lazy loading, and placeholders for Cloudinary URLs.
-- ✅ Import plugins from `@cloudinary/react`
-- ✅ Pass plugins as array: `plugins={[responsive(), lazyload(), placeholder()]}`
-- ✅ Recommended plugin order:
-  1. `responsive()` - First (handles breakpoints)
-  2. `placeholder()` - Second (shows placeholder while loading)
-  3. `lazyload()` - Third (delays loading until in viewport)
-  4. `accessibility()` - Last (if needed)
-- ✅ Always add `width` and `height` attributes to prevent layout shift
-- ✅ Example:
-  ```tsx
-  <AdvancedImage
-    cldImg={img}
-    plugins={[responsive(), placeholder({ mode: 'blur' }), lazyload()]}
-    width={800}
-    height={600}
-  />
-  ```
-
-## Responsive Images Pattern
-- ✅ **Responsive images**: Use the Cloudinary `responsive()` plugin with `fill()` resize (not only CSS). **Lazy loading**: Use the Cloudinary `lazyload()` plugin with `AdvancedImage` (not only `loading="lazy"`).
-- ✅ Use `responsive()` plugin with `fill()` resize
-- ✅ Combine with `placeholder()` and `lazyload()` plugins
-- ✅ Example:
-  ```tsx
-  const img = cld.image('id').resize(fill().width(800));
-  <AdvancedImage 
-    cldImg={img} 
-    plugins={[responsive(), placeholder({ mode: 'blur' }), lazyload()]} 
-    width={800}
-    height={600}
-  />
-  ```
-
-## Image gallery with lazy loading and responsive
-- ✅ **When the user asks for an image gallery with lazy loading and responsive**: Use Cloudinary **plugins** with `AdvancedImage`: `responsive()`, `lazyload()`, `placeholder()` (see Plugin Patterns). Use `fill()` resize with the responsive plugin. Add `width` and `height` to prevent layout shift.
-- ✅ **Sample assets in galleries**: Use the sample public IDs from "Creating Image & Video Instances" (e.g. `samples/bike`, `samples/landscapes/beach-boat`, `samples/food/spices`, `samples/two-ladies`, `samples/landscapes/girl-urban-view`, `samples/animals/reindeer`, `samples/food/pot-mussels`, `samples/cloudinary-icon`). **Assume any sample might not exist** — users can delete them. Start with one reliable sample (e.g. `samples/cloudinary-icon`) or a short list; add **onError** handling and remove/hide failed images. Prefer **uploaded** assets when available (e.g. from UploadWidget) over samples.
-- ✅ **Handle load errors**: Use `onError` on `AdvancedImage` to hide or remove failed images (e.g. set state to filter out the publicId, or hide the parent). Provide user feedback (e.g. "Some images could not be loaded. Try uploading your own!") and upload functionality so users can add their own images.
-- ✅ **Fallback**: Default gallery list can be a subset of the sample list (e.g. `['samples/cloudinary-icon', 'samples/bike', 'samples/landscapes/beach-boat']`); when user uploads, append `result.public_id`. If an image fails to load, remove it from the list or hide it so the UI doesn't show broken images.
-
-## Image Overlays (text or logos)
-- ✅ **When the user asks for image overlays with text or logos**: Use `@cloudinary/url-gen` overlay APIs. Copy imports and patterns from the **"Import reference"** table and **"Canonical overlay block"** in these rules. Do not import `text` or `image` from `actions/overlay` — they are from **`qualifiers/source`**; only `source` is from `actions/overlay`.
-- ✅ **Import** `source` from `actions/overlay`; **`text` and `image` from `qualifiers/source`**. Also: `Position` from `qualifiers/position`, `TextStyle` from `qualifiers/textStyle`, `compass` from `qualifiers/gravity`, `Transformation` from `transformation/Transformation`, `scale` from `actions/resize`.
-- ✅ **compass()** takes **string** values, with **underscores**: `compass('center')`, `compass('south_east')`, `compass('north_west')`. ❌ WRONG: `compass(southEast)` or `'southEast'` (no camelCase).
-- ✅ **Overlay image**: Use `new Transformation()` **inside** `.transformation()`: `image('logo').transformation(new Transformation().resize(scale().width(100)))`. ❌ WRONG: `image('logo').transformation().resize(...)` (`.transformation()` does not return a chainable object).
-- ✅ **Text overlay**: `fontWeight` goes on **TextStyle**: `new TextStyle('Arial', 60).fontWeight('bold')`. `textColor` goes on the **text source** (chained after `text(...)`): `text('Hello', new TextStyle('Arial', 60)).textColor('white')`.
-- ✅ **Position** is chained **after** `source(...)`, not inside: `source(image('logo').transformation(...)).position(new Position().gravity(compass('south_east')).offsetX(20).offsetY(20))`.
-- ✅ **Image overlay pattern**: `baseImage.overlay(source(image('id').transformation(new Transformation().resize(scale().width(100)))).position(new Position().gravity(compass('south_east')).offsetX(20).offsetY(20)))`. (Import `scale` from `@cloudinary/url-gen/actions/resize` if needed.)
-- ✅ **Text overlay pattern**: `baseImage.overlay(source(text('Your Text', new TextStyle('Arial', 60).fontWeight('bold')).textColor('white')).position(new Position().gravity(compass('center'))))`.
-- ✅ Docs: React Image Transformations and transformation reference for overlay syntax.
-
-## Upload Widget Pattern
-- ✅ Use component: `import { UploadWidget } from './cloudinary/UploadWidget'`
-
-**Strict initialization pattern (always follow this exactly):**
-1. ✅ **Script in `index.html`** (required):
-  ```html
-  <script src="https://upload-widget.cloudinary.com/global/all.js" async></script>
-  ```
-2. ✅ **Poll in useEffect until `createUploadWidget` is available** (required): Use `setInterval` (e.g. every 100ms) to check `typeof window.cloudinary?.createUploadWidget === 'function'`. Only create the widget when this returns `true`. Clear the interval once ready.
-3. ✅ **Add a timeout** (e.g. 10 seconds) to stop polling and show an error state if the script never loads. Clear both interval and timeout in cleanup and when ready.
-4. ✅ **Create widget once**, store in a ref. Cleanup: clear interval, clear timeout, remove click listener.
-
-❌ **Do NOT**: Check only `window.cloudinary` (the function may not be attached yet); do a single check in `onload` (unreliable timing); skip `index.html` and rely only on dynamic injection; poll forever without a timeout.
-
-- ✅ Create unsigned upload preset in dashboard at `settings/upload/presets`
-- ✅ Add to `.env`: `VITE_CLOUDINARY_UPLOAD_PRESET=your_preset_name`
-- ✅ Handle callbacks:
-  ```tsx
-  <UploadWidget
-    onUploadSuccess={(result) => {
-      console.log('Public ID:', result.public_id);
-    }}
-    onUploadError={(error) => {
-      console.error('Upload failed:', error);
-    }}
-  />
-  ```
-- ✅ Upload result contains: `public_id`, `secure_url`, `width`, `height`, etc.
-
-## Signed vs unsigned uploads (when to use which)
-
-**Unsigned uploads** (simpler, no backend required):
-- Use when: Quick prototypes, low-risk apps, or when anyone with the preset name may upload.
-- Preset: Create an **Unsigned** upload preset in Cloudinary dashboard (Settings → Upload → Upload presets). Put preset name in `.env` as `VITE_CLOUDINARY_UPLOAD_PRESET`.
-- Client: Widget needs only `cloudName` and `uploadPreset`. No API key or secret; no backend.
-- Trade-off: Anyone who knows the preset name can upload. Use only when that is acceptable.
-
-**Signed uploads** (more secure, backend required):
-- Use when: Production apps, authenticated users, or when you need to control who can upload.
-- Preset: Create a **Signed** upload preset in the dashboard. The backend generates a signature using your API secret; the client never sees the secret.
-- Client: Widget gets `api_key` (from your backend), `uploadPreset`, and an `uploadSignature` **function** that calls your backend for each upload. API secret stays on server only.
-- Trade-off: Requires a backend (Node/Express, Next.js API route, etc.) to sign requests. More secure; signature validates each upload.
-
-**Rule of thumb**: **Default to unsigned uploads** unless the user explicitly asks for "secure" or "signed" uploads. Do not default to signed — it requires a running backend and will fail out of the box. Use **signed** only when the user explicitly requests secure/signed uploads or needs to restrict who can upload.
-
-## Secure (Signed) Uploads
-
-**Golden rules**: (1) **Never expose or commit the API secret** — it must live only in server env and server code. (2) **Never commit the API key or secret** — use `server/.env` (or equivalent) and ensure it is in `.gitignore`. (3) The **api_key** is not secret and may be sent to the client (e.g. in the signature response); only **api_secret** must stay server-only.
-
-**When the user asks for secure uploads**: Use a signed upload preset and generate the signature on the server. The client may receive `uploadSignature`, `uploadSignatureTimestamp`, `api_key`, and `cloudName` from your backend; it must **never** receive or contain the API secret.
-
-### Where to put API key and secret (server-only, never committed)
-
-- **Do not put them in the root `.env`** used by Vite. Keep root `.env` for `VITE_CLOUDINARY_CLOUD_NAME` and `VITE_CLOUDINARY_UPLOAD_PRESET` only.
-- **Create `server/.env`** (in a `server/` folder) and put there: `CLOUDINARY_CLOUD_NAME`, `CLOUDINARY_API_KEY`, `CLOUDINARY_API_SECRET`. No `VITE_` prefix. Load this file only in the server process (e.g. `dotenv.config({ path: 'server/.env' })`).
-- **Never commit API key or secret**: Add `server/.env` to `.gitignore`. Use env vars for all credentials; never hardcode or commit them.
-- **In code**: Read `process.env.CLOUDINARY_API_SECRET` and `process.env.CLOUDINARY_API_KEY` only in server/API code. Never in React components or any file Vite bundles.
-- **Next.js**: `CLOUDINARY_*` in root `.env.local` is server-only (browser only sees `NEXT_PUBLIC_*`). For Vite + Node in same repo, prefer `server/.env` and load it only in the server.
-- **Server SDK**: Use the **Cloudinary Node.js SDK v2** for server-side signing: `import { v2 as cloudinary } from 'cloudinary'` (package name: `cloudinary`). Do **not** use v1 (e.g. 1.47.0) — v1 does not expose `cloudinary.utils.api_sign_request` the same way. Install: `npm install cloudinary` (v2).
-
-### How the client gets credentials (working pattern — use this)
-
-Use **`uploadSignature` as a function** (not `signatureEndpoint`). The widget calls the function with `params_to_sign`; your function calls your backend and passes the signature back. This pattern is reliable across widget versions.
-
-1. **Fetch `api_key` from server first** (before creating the widget). API key is not secret; safe to use in client. Your backend returns it from the sign endpoint (e.g. `/api/sign-image`).
-
-2. **Set `uploadSignature` to a function** that receives `(callback, params_to_sign)` from the widget. Inside the function, add `upload_preset` to `params_to_sign` (use your signed preset name, e.g. from env or a constant), POST to your backend with `{ params_to_sign: paramsWithPreset }`, then call `callback(data.signature)` with the response.
-
-3. **Include `uploadPreset` in the widget config** (your signed preset name). The widget needs it so it includes it in `params_to_sign`. **Default:** Cloudinary accounts have a built-in signed preset `ml_default` (users can delete it). If the user has not created their own signed preset, use `ml_default`; otherwise use the preset name from their dashboard.
-
-4. **Server endpoint**: Accept `params_to_sign` from the request body. Always include `upload_preset` in the object you sign (add it if the client did not send it). Use `cloudinary.utils.api_sign_request(paramsToSign, process.env.CLOUDINARY_API_SECRET)` to generate the signature. Return `{ signature, timestamp, api_key, cloud_name }`. Never return the API secret.
-
-**Preset name:** Use `ml_default` when the user has not specified a signed preset (Cloudinary provides it by default; users can delete it — then they must create one in the dashboard). Otherwise use the user's preset name.
-
-**Generic client pattern** (preset: use `ml_default` if it exists / user hasn't specified one; endpoint is up to the user):
-```tsx
-// Fetch api_key from server first, then:
-widgetConfig.api_key = data.api_key; // from your sign endpoint
-widgetConfig.uploadPreset = 'ml_default'; // default signed preset (or user's preset if they created one)
-widgetConfig.uploadSignature = function(callback, params_to_sign) {
-  const paramsWithPreset = { ...params_to_sign, upload_preset: 'ml_default' };
-  fetch('/api/sign-image', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ params_to_sign: paramsWithPreset }),
-  })
-    .then(r => r.json())
-    .then(data => data.signature ? callback(data.signature) : callback(''))
-    .catch(() => callback(''));
-};
-```
-
-**Generic server pattern** (Node/Express with SDK v2):
-```ts
-// import { v2 as cloudinary } from 'cloudinary';
-const params = req.body.params_to_sign || {};
-const paramsToSign = { ...params, upload_preset: params.upload_preset || 'ml_default' };
-const signature = cloudinary.utils.api_sign_request(paramsToSign, process.env.CLOUDINARY_API_SECRET);
-res.json({ signature, timestamp: paramsToSign.timestamp, api_key: process.env.CLOUDINARY_API_KEY, cloud_name: process.env.CLOUDINARY_CLOUD_NAME });
-```
-
-- ❌ **Avoid `signatureEndpoint`** — it may not be called reliably by all widget versions. Prefer the `uploadSignature` function.
-- ✅ Docs: [Upload widget — signed uploads](https://cloudinary.com/documentation/upload_widget.md#signed_uploads), [Upload assets in Next.js](https://cloudinary.com/documentation/upload_assets_in_nextjs_tutorial.md).
-
-### Rules for secure uploads
-- ✅ Use a **signed** upload preset (dashboard → Upload presets → Signed). Do not use an unsigned preset when the user wants secure uploads. **Default:** Accounts have a built-in signed preset `ml_default` — use it if the user hasn't created their own (they can delete `ml_default`, in which case they must create a signed preset in the dashboard).
-- ✅ Generate the signature **on the server only** using Cloudinary Node.js SDK **v2** (`cloudinary.utils.api_sign_request`). Never put `CLOUDINARY_API_SECRET` in a `VITE_` variable or in client-side code.
-- ✅ Keep `server/.env` in `.gitignore`; never commit API key or secret.
-- ✅ Use **`uploadSignature` as a function** (not `signatureEndpoint`) for reliable signed uploads.
-- ✅ Include **`uploadPreset` in the widget config** so the widget includes it in `params_to_sign`.
-- ✅ **Server must include `upload_preset` in the signed params** (add it if the client did not send it).
-
-### What not to do
-- ❌ **Never** put the API secret in a `VITE_` (or `NEXT_PUBLIC_`) variable or in any file sent to the browser.
-- ❌ **Never** commit the API key or secret; use env vars and ignore `server/.env` in git.
-- ❌ **Do not** generate the signature in client-side JavaScript (it would require the secret in the client).
-- ❌ **Do not** use an unsigned preset when the user explicitly wants secure/signed uploads.
-- ❌ **Do not** omit `uploadPreset` from the widget config when using signed uploads (widget needs it in `params_to_sign`).
-- ❌ **Do not** use Cloudinary Node SDK v1 (e.g. 1.47.0) for signing — use v2 (`import { v2 as cloudinary } from 'cloudinary'`).
-- ❌ **Do not** rely on `signatureEndpoint` alone; use the `uploadSignature` function for reliability.
-
-## Video Patterns
-
-- ✅ **Display a video** → Use **AdvancedVideo** (`@cloudinary/react`). It just displays a video (with optional transformations). Not a full player.
-- ✅ **A video player** → Use **Cloudinary Video Player** (`cloudinary-video-player`). That is the actual player (styled UI, controls, playlists, etc.).
-
-### ⚠️ IMPORTANT: Two Different Approaches
-
-**1. AdvancedVideo** (`@cloudinary/react`) — For **displaying** a video
-- React component similar to `AdvancedImage`; just displays a video with Cloudinary transformations
-- Not a full "player" — it's video display (native HTML5 video with optional controls)
-- Use when: user wants to show/display a video. Works with `cld.video()` like images with `cld.image()`
-
-**2. Cloudinary Video Player** (`cloudinary-video-player`) — The **player**
-- Full-featured video player (styled UI, controls, playlists). Use when the user asks for a "video player."
-- **Use imperative video element only** (create with document.createElement, append to container ref); do not pass a React-managed `<video ref>`. See "Cloudinary Video Player (The Player)" below.
-
-### AdvancedVideo (React SDK - For Displaying a Video)
-- ✅ **Purpose**: Display a video with Cloudinary transformations (resize, effects, etc.). It is **not** a full player — it is for showing a video. For a player, use Cloudinary Video Player.
-- ✅ **Package**: `@cloudinary/react` (same as AdvancedImage)
-- ✅ **Import**: `import { AdvancedVideo } from '@cloudinary/react'`
-- ✅ **NO CSS IMPORT NEEDED**: AdvancedVideo uses native HTML5 video - no CSS import required
-- ❌ **WRONG**: `import '@cloudinary/react/dist/cld-video-player.css'` (this path doesn't exist)
-- ✅ **Create video instance**: `const video = cld.video(publicId)` (like `cld.image()`)
-- ✅ **Apply transformations**: Chain transformations like images:
-  ```tsx
-  const video = cld.video('video-id')
-    .resize(fill().width(800).height(600))
-    .delivery(format(auto()));
-  ```
-- ✅ **Use component**:
-  ```tsx
-  <AdvancedVideo
-    cldVid={video}
-    controls
-    autoplay
-    muted
-  />
-  ```
-- ✅ **Documentation**: https://cloudinary.com/documentation/react_video_transformations.md
-
-### Cloudinary Video Player (The Player)
-Use when the user asks for a **video player** (styled UI, controls, playlists). For just **displaying** a video, use AdvancedVideo instead.
-
-**Rule: imperative element only.** Do **not** pass a React-managed `<video ref={...} />` to the player — the library mutates the DOM and React will throw removeChild errors. Create the video element with `document.createElement('video')`, append it to a container ref, and pass that element to `videoPlayer(el, ...)`.
-
-- **Package**: `cloudinary-video-player`. Install with `npm install cloudinary-video-player` (no version).
-- **Import**: `import { videoPlayer } from 'cloudinary-video-player'` (named) and `import 'cloudinary-video-player/cld-video-player.min.css'` (no `dist/` in path). The package only exposes paths under `lib/` via `exports`; use `cld-video-player.min.css` (no `dist/`), which resolves to `lib/cld-video-player.min.css`.
-- ❌ **WRONG**: `import 'cloudinary-video-player/dist/cld-video-player.min.css'` — package `exports` do not expose `dist/`; the valid path is `cloudinary-video-player/cld-video-player.min.css`.
-- **player.source()** takes an **object**: `player.source({ publicId: 'samples/elephants' })`. Not a string.
-- **Cleanup**: Call `player.dispose()`, then **only if** `el.parentNode` exists call `el.parentNode.removeChild(el)` (avoids NotFoundError).
-- **If init fails** (CSP, extensions, timing): render **AdvancedVideo** with the same publicId. Do not relax CSP in index.html or ask the user to disable extensions.
-
-**Poster options**: Always include `posterOptions` for a predictable poster image with a fallback color:
-- `transformation: { startOffset: '0' }` — use the first frame of the video as the poster (consistent and loads reliably)
-- `posterColor: '#0f0f0f'` — if the poster image fails to load, shows a dark background instead of blank/broken
-- These can be overridden via props (e.g. `posterOptions={{ transformation: { startOffset: '5' } }}` for a different frame)
-
-**Example (copy this pattern):**
-```tsx
-const containerRef = useRef<HTMLDivElement>(null);
-const playerRef = useRef<ReturnType<typeof videoPlayer> | null>(null);
-useLayoutEffect(() => {
-  if (!cloudName || !containerRef.current?.isConnected) return;
-  const el = document.createElement('video');
-  el.className = 'cld-video-player cld-fluid';
-  containerRef.current.appendChild(el);
-  try {
-    const player = videoPlayer(el, {
-      cloudName,
-      secure: true,
-      controls: true,
-      fluid: true,
-      posterOptions: {
-        transformation: { startOffset: '0' },
-        posterColor: '#0f0f0f',
-      },
-    });
-    player.source({ publicId: 'samples/elephants' });
-    playerRef.current = player;
-  } catch (err) { console.error(err); }
-  return () => {
-    if (playerRef.current) {
-      try { playerRef.current.dispose(); } catch (e) { console.warn(e); }
-      playerRef.current = null;
-    }
-    if (el.parentNode) el.parentNode.removeChild(el);
-  };
-}, [cloudName]);
-return <div ref={containerRef} />;
-```
-Docs: https://cloudinary.com/documentation/cloudinary_video_player.md
-
-### When to Use Which?
-- ✅ **Use AdvancedVideo** when: User wants to **display** or **show** a video (no full player). It just displays a video with transformations.
-- ✅ **Use Cloudinary Video Player** when: User asks for a **video player** — the actual player with styled UI, controls, and optional features (playlists, ads, etc.).
-
-## TypeScript Patterns
-
-### Type Imports
-- ✅ Import types from `@cloudinary/url-gen`:
-  ```tsx
-  import type { CloudinaryImage } from '@cloudinary/url-gen';
-  import type { CloudinaryVideo } from '@cloudinary/url-gen';
-  ```
-- ✅ Type image instance: `const img: CloudinaryImage = cld.image('id')`
-- ✅ Type video instance: `const video: CloudinaryVideo = cld.video('id')`
-
-### Upload Result Types
-- ✅ Define interface for upload results:
-  ```tsx
-  interface CloudinaryUploadResult {
-    public_id: string;
-    secure_url: string;
-    url: string;
-    width: number;
-    height: number;
-    format: string;
-    resource_type: string;
-    bytes: number;
-    created_at: string;
-    // Add other fields as needed
-  }
-  ```
-- ✅ Type upload callbacks:
-  ```tsx
-  onUploadSuccess?: (result: CloudinaryUploadResult) => void;
-  ```
-- ❌ **WRONG**: `onUploadSuccess?: (result: any) => void`
-- ✅ **CORRECT**: Use proper interface or type definition
-
-### Environment Variable Typing
-- ✅ Create `vite-env.d.ts` for type safety:
-  ```tsx
-  /// <reference types="vite/client" />
-  
-  interface ImportMetaEnv {
-    readonly VITE_CLOUDINARY_CLOUD_NAME: string;
-    readonly VITE_CLOUDINARY_UPLOAD_PRESET?: string;
-  }
-  
-  interface ImportMeta {
-    readonly env: ImportMetaEnv;
-  }
-  ```
-- ✅ Access with type safety: `import.meta.env.VITE_CLOUDINARY_CLOUD_NAME`
-
-### Type Guards and Safety
-- ✅ Type guard for window.cloudinary (check `createUploadWidget`, not just `cloudinary`):
-  ```tsx
-  function isUploadWidgetReady(): boolean {
-    return typeof window !== 'undefined' && 
-           typeof window.cloudinary?.createUploadWidget === 'function';
-  }
-  ```
-- ✅ Use type guards before accessing (but **always poll with timeout** in useEffect — don't rely on a single check):
-  ```tsx
-  // In useEffect, poll until ready with timeout:
-  const interval = setInterval(() => {
-    if (isUploadWidgetReady()) {
-      clearInterval(interval);
-      clearTimeout(timeout);
-      window.cloudinary.createUploadWidget(...);
-    }
-  }, 100);
-  const timeout = setTimeout(() => {
-    clearInterval(interval);
-    console.error('Upload widget script failed to load');
-  }, 10000);
-  // Cleanup: clearInterval(interval); clearTimeout(timeout);
-  ```
-
-### Ref Typing Patterns
-- ✅ Type refs properly:
-  ```tsx
-  // Video element ref
-  const videoRef = useRef<HTMLVideoElement>(null);
-  
-  // Button ref
-  const buttonRef = useRef<HTMLButtonElement>(null);
-  
-  // Widget ref (use unknown if types not available)
-  const widgetRef = useRef<unknown>(null);
-  ```
-
-### Type Narrowing
-- ✅ Handle optional values with type narrowing:
-  ```tsx
-  const preset = uploadPreset || undefined; // Type: string | undefined
-  
-  // Type narrowing in conditionals
-  if (uploadPreset) {
-    // TypeScript knows uploadPreset is string here
-    console.log(preset.length);
-  }
-  ```
-
-### Avoid `any` Type
-- ❌ **WRONG**: `const result: any = ...`
-- ✅ **CORRECT**: Use proper interface or `unknown` with type guards
-- ✅ **CORRECT**: `const result: unknown = ...` then narrow with type guards
-- ✅ When types aren't available, use `unknown` and narrow:
-  ```tsx
-  function handleResult(result: unknown) {
-    if (result && typeof result === 'object' && 'public_id' in result) {
-      // TypeScript knows result has public_id
-      const uploadResult = result as CloudinaryUploadResult;
-    }
-  }
-  ```
-
-## Best Practices
-- ✅ Always use `fill()` resize with automatic gravity for responsive images
-- ✅ Always end transformations with `.delivery(format(auto())).delivery(quality(autoQuality()))` unless the user specifies a format or quality
-- ✅ Use `placeholder()` and `lazyload()` plugins together
-- ✅ Always add `width` and `height` attributes to `AdvancedImage`
-- ✅ Store `public_id` from upload success, not full URL
-- ✅ Video player: use imperative element only; dispose in useLayoutEffect cleanup and remove element with `if (el.parentNode) el.parentNode.removeChild(el)`; always include `posterOptions` with `transformation: { startOffset: '0' }` and `posterColor: '#0f0f0f'` for reliable poster display
-- ✅ Use TypeScript for better autocomplete and error catching
-- ✅ Prefer `unknown` over `any` when types aren't available
-- ✅ Use type guards for runtime type checking
-- ✅ Define interfaces for Cloudinary API responses
-- ✅ Create `vite-env.d.ts` for environment variable typing
-- ✅ Use proper HTML element types for refs
-
----
-
-# ⚠️ COMMON ERRORS & SOLUTIONS
-
-## Environment Variable Errors
-
-### "Where do I create the Cloudinary instance?" / "Config with Vite prefix"
-- ❌ Problem: User is using rules only (no CLI) and doesn't have a Cloudinary config file, or is using wrong env (e.g. process.env, or missing VITE_ prefix).
-- ✅ Create a **single config file** (e.g. `src/cloudinary/config.ts`) that: imports `Cloudinary` from `@cloudinary/url-gen`, reads `import.meta.env.VITE_CLOUDINARY_CLOUD_NAME`, validates it, creates `export const cld = new Cloudinary({ cloud: { cloudName } })`, and exports `uploadPreset = import.meta.env.VITE_CLOUDINARY_UPLOAD_PRESET || ''`. Use **VITE_** prefix in `.env`; access with `import.meta.env.VITE_*` only. See PATTERNS → "Project setup (rules-only / without CLI)" for exact code.
-
-### "Cloud name is required"
-- ❌ Problem: `VITE_CLOUDINARY_CLOUD_NAME` not set or wrong prefix
-- ✅ Solution:
-  1. Check `.env` file exists in project root
-  2. Verify variable is `VITE_CLOUDINARY_CLOUD_NAME` (with `VITE_` prefix!)
-  3. Restart dev server after adding .env variables
-
-### "VITE_ prefix required" or env var is undefined
-- ❌ Problem: Variable doesn't have the right prefix for the bundler, or wrong access (e.g. process.env in Vite, or no prefix in CRA).
-- ✅ **Vite**: Use `VITE_` prefix in `.env` and `import.meta.env.VITE_CLOUDINARY_CLOUD_NAME` (not `process.env`).
-- ✅ **Not Vite?** Use your bundler's client env prefix and access: Create React App → `REACT_APP_` and `process.env.REACT_APP_CLOUDINARY_CLOUD_NAME`; Next.js (client) → `NEXT_PUBLIC_` and `process.env.NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME`. See PATTERNS → "Other bundlers (non-Vite)".
-- Restart dev server after changing `.env`.
-
-## Import Errors
-
-### "Cannot find module" or wrong import
-- ❌ Problem: Importing from wrong package or wrong subpath; agent often invents paths that don't exist.
-- ✅ **Use only the exact paths** in PATTERNS → "Import reference: @cloudinary/url-gen (use these exact paths only)". Do **not** guess subpaths (e.g. `@cloudinary/url-gen/resize` or `@cloudinary/url-gen/overlay` — use `actions/resize`, `actions/overlay` with the exact export names from the table).
-- ✅ Components and plugins: `@cloudinary/react` (not `@cloudinary/url-gen`). Cloudinary instance and transformation actions/qualifiers: `@cloudinary/url-gen` with the exact subpaths from the Import reference (e.g. `actions/resize`, `actions/delivery`, `qualifiers/format`, `qualifiers/quality`, `actions/overlay`, `qualifiers/gravity`, `qualifiers/textStyle`, `qualifiers/position`, `transformation/Transformation`).
-- ✅ If a path fails, check package.json has `@cloudinary/url-gen` and match the import to the Import reference table exactly.
-
-## Transformation Errors
-
-### "Transformation not working" or image looks wrong
-- ❌ Problem: Incorrect transformation syntax
-- ✅ Solution:
-  1. Check transformation is chained: `cld.image('id').resize(...).effect(...)`
-  2. Verify actions are imported from correct modules
-  3. Ensure image public_id is correct and accessible
-  4. Check transformation syntax matches v2 (not v1)
-  5. Format/quality must be separate: `.delivery(format(auto())).delivery(quality(autoQuality()))`
-
-### Wrong transformation syntax
-- ❌ WRONG: `<AdvancedImage src="image.jpg" width={800} />`
-- ✅ CORRECT: 
-  ```tsx
-  const img = cld.image('image.jpg').resize(fill().width(800));
-  <AdvancedImage cldImg={img} />
-  ```
-
-## Plugin Errors
-
-### "Responsive images not working" or "Placeholder issues"
-- ❌ Problem: Plugins not configured correctly
-- ✅ Solution:
-  1. Must use `responsive()` plugin with `fill()` resize
-  2. Include both `placeholder()` and `lazyload()` plugins
-  3. Check image is accessible and public_id is correct
-  4. Verify plugins are in array: `plugins={[responsive(), placeholder(), lazyload()]}`
-  5. Always add `width` and `height` attributes
-
-### Plugins not working
-- ❌ WRONG: `<AdvancedImage cldImg={img} lazyLoad placeholder />`
-- ✅ CORRECT: `<AdvancedImage cldImg={img} plugins={[lazyload(), placeholder()]} />`
-- ✅ Plugins must be imported from `@cloudinary/react`, not `@cloudinary/url-gen`
-
-## Upload Widget Errors
-
-### Upload fails (unsigned uploads) — first check upload preset
-- ❌ Problem: Upload fails when using unsigned upload
-- ✅ **Debug checklist** (in order):
-  1. **Is the upload preset configured?** Check `.env` has `VITE_CLOUDINARY_UPLOAD_PRESET=your-preset-name` (exact name, no typos)
-  2. **Does the preset exist?** Cloudinary dashboard → Settings → Upload → Upload presets
-  3. **Is it Unsigned?** Preset must be "Unsigned" for client-side uploads (no API key/secret in browser)
-  4. **Env reloaded?** Restart the dev server after any `.env` change
-- ✅ If all above are correct, then check: script loaded in `index.html`, cloud name set, and network/console for the actual error message
-
-### "Upload preset not found" or "Invalid upload preset"
-- ❌ Problem: Preset doesn't exist or is signed
-- ✅ Solution:
-  1. Create unsigned upload preset in Cloudinary dashboard
-  2. Go to `settings/upload/presets` > Add upload preset
-  3. Set to "Unsigned" mode
-  4. Copy exact preset name to `.env` as `VITE_CLOUDINARY_UPLOAD_PRESET`
-  5. Restart dev server
-
-### "Cannot upload large images" or "Upload fails for large files"
-- ❌ Problem: File too large or script not loaded
-- ✅ Solution:
-  1. Use chunked uploads for files > 20MB
-  2. Check upload preset has appropriate limits in dashboard
-  3. Verify `window.cloudinary` script is loaded in `index.html`
-  4. Consider using server-side upload for very large files
-
-### Widget not opening
-- ❌ Problem: Script not loaded, or widget created before `createUploadWidget` was available
-- ✅ Solution:
-  1. Ensure script is in `index.html`: `<script src="https://upload-widget.cloudinary.com/global/all.js" async></script>`
-  2. In `useEffect`, **poll** with `setInterval` until `typeof window.cloudinary?.createUploadWidget === 'function'` — only then create the widget. Do **not** check only `window.cloudinary`.
-  3. Verify upload preset is set correctly
-
-### "createUploadWidget is not a function"
-- ❌ Problem: **Race condition** — the script loads **async**, so `window.cloudinary` can exist before `createUploadWidget` is attached. A single check (even in `onload`) is **not** reliable.
-- ✅ **Always poll**: In `useEffect`, use `setInterval` to check `typeof window.cloudinary?.createUploadWidget === 'function'`. Only create the widget when this returns `true`. Clear the interval once ready.
-- ❌ **Do NOT**: Check only `window.cloudinary`; do a single check in `onload`; skip the script in `index.html`.
-- ✅ See PATTERNS → Upload Widget Pattern and Project setup → Upload Widget for the strict pattern.
-
-### Video player: "Invalid target for null#on" or React removeChild or NotFoundError
-- ❌ Problem: Passing a React-managed `<video ref={...} />` to the player causes removeChild errors (the player mutates the DOM). Or container/ref not in DOM yet when init runs.
-- ✅ **Use imperative video element only**: Create the video with `document.createElement('video')`, append to a container ref, pass that element to `videoPlayer(el, ...)`. Check `containerRef.current?.isConnected` before init. In cleanup: dispose, then `if (el.parentNode) el.parentNode.removeChild(el)`. See PATTERNS → Cloudinary Video Player (The Player).
-
-### Video player: failed HEAD or CORS-like console noise
-- Failed HEAD/analytics from the player does **not** necessarily mean playback fails. Do not add a preflight GET. If video doesn't play, use the imperative pattern and fall back to AdvancedVideo when init fails.
-
-### Video player blocked by CSP or extensions
-- **Do not** relax CSP in index.html or ask the user to disable extensions. **Fall back to AdvancedVideo** with the same publicId when the player fails to initialize.
-
-### User needs secure/signed uploads
-- ❌ Problem: User asks for secure uploads; unsigned preset or client-side secret is not acceptable.
-- ✅ Use signed preset + server-side signature. Use **`uploadSignature` as a function** (not `signatureEndpoint`); fetch `api_key` from server first; include `uploadPreset` in widget config; server must include `upload_preset` in signed params. Use Cloudinary Node SDK **v2** on server. Never expose or commit the API secret.
-- ✅ See PATTERNS → "Signed vs unsigned uploads" and "Secure (Signed) Uploads" → "How the client gets credentials (working pattern)".
-
-### "Where do I put my API key and secret?" / "Never commit API key or secret"
-- ❌ Problem: User needs to store `CLOUDINARY_API_KEY` and `CLOUDINARY_API_SECRET` securely, or is told to "create a .env file" and worries it will overwrite the existing Vite `.env`.
-- ✅ Do not put them in root `.env`. Create `server/.env` with `CLOUDINARY_CLOUD_NAME`, `CLOUDINARY_API_KEY`, `CLOUDINARY_API_SECRET`; add `server/.env` to `.gitignore`; load only in the server. Never commit API key or secret.
-- ✅ See PATTERNS → "Secure (Signed) Uploads" → "Where to put API key and secret (server-only, never committed)".
-
-### "Invalid Signature" or "Missing required parameter - api_key"
-- ❌ Problem: Signed upload fails with "Invalid Signature" or "Missing required parameter - api_key".
-- ✅ **Use the working pattern:** (1) Use **`uploadSignature` as a function** (not `signatureEndpoint`). (2) **Fetch `api_key` from server** before creating the widget (API key is not secret). (3) **Include `uploadPreset` in widget config** so the widget includes it in `params_to_sign`. (4) **Server must include `upload_preset` in the signed params** (add it if the client did not send it). (5) Use **Cloudinary Node.js SDK v2** on the server (`import { v2 as cloudinary } from 'cloudinary'`), not v1 (e.g. 1.47.0).
-- ✅ **Common mistakes:** Using `signatureEndpoint` instead of `uploadSignature` function; omitting `uploadPreset` from widget config; server not adding `upload_preset` to signature params; using SDK v1 for signing; not fetching `api_key` from server before creating the widget. If using `ml_default`, ensure it still exists (user may have deleted it); otherwise create a signed preset in the dashboard.
-- ✅ See PATTERNS → "Secure (Signed) Uploads" → "How the client gets credentials (working pattern)".
-
-## Video Errors
-
-### "AdvancedVideo not working" or "Video not displaying"
-- ❌ Problem: Wrong component or incorrect setup
-- ✅ Solution:
-  1. Verify you're using `AdvancedVideo` from `@cloudinary/react` (not video player)
-  2. Check video instance is created: `const video = cld.video(publicId)`
-  3. **NO CSS IMPORT NEEDED** - AdvancedVideo doesn't require CSS import
-  4. ❌ **WRONG**: `import '@cloudinary/react/dist/cld-video-player.css'` (this path doesn't exist)
-  5. Verify public ID is correct and video exists in Cloudinary
-  6. Check transformations are chained correctly (same as images)
-
-### "Failed to resolve import @cloudinary/react/dist/cld-video-player.css"
-- ❌ Problem: Trying to import CSS that doesn't exist in `@cloudinary/react`
-- ✅ Solution:
-  1. **Remove the CSS import** - AdvancedVideo doesn't need it
-  2. The `cld-video-player.css` file is only for `cloudinary-video-player` package
-  3. AdvancedVideo uses native HTML5 video elements - no CSS required
-  4. If you need styled video player, use `cloudinary-video-player` instead
-
-### "Video player not working" or "Player not initializing"
-- ✅ **Use imperative video element only** (see PATTERNS → Cloudinary Video Player): createElement, append to container ref, pass to videoPlayer; cleanup: dispose then `if (el.parentNode) el.parentNode.removeChild(el)`. If init still fails (CSP, extensions), **fall back to AdvancedVideo** with the same publicId. Do not relax CSP or ask the user to disable extensions.
-
-### Cloudinary package install fails or "version doesn't exist"
-- ❌ Problem: Agent pinned a Cloudinary package to a specific version (e.g. `cloudinary-video-player@1.2.3`) that doesn't exist on npm, or used a wrong package name.
-- ✅ **Install latest**: Use `npm install <package>` with **no version** so npm gets the latest compatible. In package.json use a **caret** (e.g. `"cloudinary-video-player": "^1.0.0"`). Use only correct package names: `@cloudinary/react`, `@cloudinary/url-gen`, `cloudinary-video-player`, `cloudinary`. See PATTERNS → "Installing Cloudinary packages".
-
-### Confusion between AdvancedVideo and Video Player
-- **AdvancedVideo** = for **displaying** a video (not a full player). **Cloudinary Video Player** = the **player** (styled UI, controls, playlists, etc.).
-- ❌ WRONG: Using `cloudinary-video-player` when you just need to display a video
-- ✅ CORRECT: Use `AdvancedVideo` when you need to display/show a video
-- ❌ WRONG: Using `AdvancedVideo` when the user asks for a "video player"
-- ✅ CORRECT: Use `cloudinary-video-player` when they want a video player (or playlists, ads, etc.)
-
-### Memory leak from video player
-- ❌ WRONG: Not disposing player in cleanup
-- ✅ CORRECT: Always dispose in cleanup; wrap in try-catch so disposal errors don't throw:
-  ```tsx
-  return () => {
-    if (playerRef.current) {
-      try { playerRef.current.dispose(); } catch (e) { console.warn(e); }
-      playerRef.current = null;
-    }
-  };
-  ```
-
-### Video player: "source is not a function" or video not playing
-- **player.source()** takes an **object**: `player.source({ publicId: 'samples/elephants' })`, not a string. Use named import: `import { videoPlayer } from 'cloudinary-video-player'`. See PATTERNS → Cloudinary Video Player (The Player).
-
-### Video player: poster image missing, wrong frame, or broken
-- ❌ Problem: Video player shows no poster, wrong poster frame, or blank area before video loads.
-- ✅ **Always include `posterOptions`** in the player config: `posterOptions: { transformation: { startOffset: '0' }, posterColor: '#0f0f0f' }`. This uses the first frame as the poster (reliable) and provides a dark fallback color if the poster fails to load.
-- ✅ **Override if needed**: Pass different values via props, e.g. `startOffset: '5'` for a frame 5 seconds in, or a different `posterColor` for your design.
-
-### Overlay: "Cannot read properties of undefined" or overlay not showing
-- ❌ Problem: Wrong overlay API usage (Overlay.source, compass constants, .transformation().resize, fontWeight on wrong object).
-- ✅ Import `source` directly from `@cloudinary/url-gen/actions/overlay` (not `Overlay.source`). Use **string** values for compass: `compass('south_east')` (underscores, not camelCase). Use `new Transformation()` inside `.transformation()`. Put `fontWeight` on **TextStyle**; put `textColor` on the **text source**. See PATTERNS → Image Overlays (text or logos).
-
-### Overlay: wrong import path for `text` or `image`
-- ❌ Problem: Importing `text` or `image` from `@cloudinary/url-gen/actions/overlay` — that module only exports `source`.
-- ✅ **`text` and `image`** come from **`@cloudinary/url-gen/qualifiers/source`**. Use the "Canonical overlay block" in these rules: `import { text, image } from '@cloudinary/url-gen/qualifiers/source';`
-
-### Gallery: sample images not loading or 404s
-- ❌ Problem: Assuming sample public IDs (e.g. from the samples list) always exist; users can delete them.
-- ✅ Assume samples might not exist. Use the sample list from PATTERNS → "Creating Image & Video Instances" (e.g. `samples/cloudinary-icon`, `samples/bike`, `samples/landscapes/beach-boat`, `samples/food/spices`, etc.); use **onError** on `AdvancedImage` to hide or remove failed images; prefer uploaded assets when available. See PATTERNS → Image gallery with lazy loading and responsive.
-
-## TypeScript Errors
-
-### "TypeScript errors on transformations"
-- ❌ Problem: Missing types or wrong imports
-- ✅ Solution:
-  1. Import types from `@cloudinary/url-gen`
-  2. Use proper action imports: `import { fill } from '@cloudinary/url-gen/actions/resize'`
-  3. Type the image instance if needed: `const img: CloudinaryImage = cld.image('id')`
-  4. Ensure all imports are from correct modules
-
-### "Type 'any' is not assignable" or "Parameter 'result' implicitly has 'any' type"
-- ❌ Problem: Using `any` type or missing type definitions
-- ✅ Solution:
-  1. Define interface for upload results: `interface CloudinaryUploadResult { ... }`
-  2. Type callbacks: `onUploadSuccess?: (result: CloudinaryUploadResult) => void`
-  3. Use `unknown` instead of `any` when types aren't available
-  4. Add type guards to narrow `unknown` types
-
-### "Property 'cloudinary' does not exist on type 'Window'"
-- ❌ Problem: Missing type declaration for window.cloudinary
-- ✅ Solution:
-  ```tsx
-  declare global {
-    interface Window {
-      cloudinary?: {
-        createUploadWidget: (config: any, callback: any) => any;
-      };
-    }
-  }
-  ```
-- ✅ Or use type guard: `if (typeof window.cloudinary !== 'undefined')`
-
-### "Property 'VITE_CLOUDINARY_CLOUD_NAME' does not exist on type 'ImportMetaEnv'"
-- ❌ Problem: Missing type definitions for Vite environment variables
-- ✅ Solution:
-  1. Create `vite-env.d.ts` file
-  2. Add interface: `interface ImportMetaEnv { readonly VITE_CLOUDINARY_CLOUD_NAME: string; }`
-  3. Reference Vite types: `/// <reference types="vite/client" />`
-
-### "Type 'null' is not assignable to type 'RefObject'"
-- ❌ Problem: Incorrect ref typing
-- ✅ Solution:
-  1. Use proper HTML element type: `useRef<HTMLVideoElement>(null)`
-  2. Use `unknown` for widget refs if types aren't available: `useRef<unknown>(null)`
-  3. Check for null before accessing: `if (ref.current) { ... }`
-
----
-
-## Quick Reference Checklist
-
-When something isn't working, check:
-- [ ] **Rules-only?** → Create config file with reusable `cld` and export `uploadPreset`; use your bundler's client env prefix in .env; create Upload Widget in useEffect with ref (see "Project setup (rules-only / without CLI)").
-- [ ] **Not Vite?** → Use your bundler's env prefix and access (e.g. REACT_APP_ + process.env.REACT_APP_*; NEXT_PUBLIC_ + process.env.NEXT_PUBLIC_*). See "Other bundlers (non-Vite)".
-- [ ] Environment variables use the correct prefix for your bundler (Vite: VITE_; CRA: REACT_APP_; Next client: NEXT_PUBLIC_); **never** put API secret in client-exposed vars
-- [ ] Dev server was restarted after .env changes
-- [ ] **@cloudinary/url-gen imports?** → Use only the exact paths from PATTERNS → "Import reference" and "Canonical overlay block" (e.g. `text`/`image` from `qualifiers/source`, not `actions/overlay`)
-- [ ] Imports are from correct packages (components/plugins from @cloudinary/react; actions/qualifiers from @cloudinary/url-gen with exact paths)
-- [ ] Transformations are chained on image instance
-- [ ] Format/quality use separate `.delivery()` calls
-- [ ] Plugins are in array format
-- [ ] Upload widget script is loaded in `index.html`
-- [ ] **"createUploadWidget is not a function"?** → In useEffect, **poll** with setInterval until `typeof window.cloudinary?.createUploadWidget === 'function'`. Do NOT check only `window.cloudinary`; do NOT rely on a single onload check
-- [ ] **Video player?** → **Imperative element only**: createElement('video'), append to container ref, pass to videoPlayer(el, ...); include `posterOptions: { transformation: { startOffset: '0' }, posterColor: '#0f0f0f' }` for reliable poster; player.source({ publicId }); cleanup: dispose then if (el.parentNode) el.parentNode.removeChild(el). CSS: cloudinary-video-player/cld-video-player.min.css. If init fails, fall back to AdvancedVideo (do not relax CSP).
-- [ ] **Upload fails (unsigned)?** → Is `VITE_CLOUDINARY_UPLOAD_PRESET` set? Preset exists and is Unsigned in dashboard?
-- [ ] **Upload default?** → Default to **unsigned** uploads (cloudName + uploadPreset); use signed only when the user explicitly asks for secure/signed uploads (signed requires a running backend)
-- [ ] **Secure uploads?** → Use `uploadSignature` as function (not `signatureEndpoint`); fetch `api_key` from server first; include `uploadPreset` in widget config; server includes `upload_preset` in signed params; use Cloudinary Node SDK v2 on server; never expose or commit API secret
-- [ ] **Where do API key/secret go?** → **Do not** put in root `.env`. Use **`server/.env`**; add to `.gitignore`; load only in server. **Never commit** API key or secret
-- [ ] Upload preset is unsigned (for simple client uploads)
-- [ ] **Installing Cloudinary packages?** → Install latest: use `npm install <package>` with no version; in package.json use caret (^) so npm gets latest compatible; do not pin to exact versions
-- [ ] **Image overlays?** → Import `source` (not Overlay.source); `compass('south_east')` (strings with underscores); `new Transformation()` inside `.transformation()`; fontWeight on TextStyle, textColor on text source
-- [ ] **Image gallery?** → Use responsive/lazyload/placeholder plugins; use sample list (samples/cloudinary-icon, samples/bike, samples/landscapes/beach-boat, samples/food/spices, etc.); assume samples might not exist; use onError; prefer uploaded assets
-- [ ] TypeScript types are properly imported
-- [ ] Upload result types are defined (not using `any`)
-- [ ] Environment variables are typed in `vite-env.d.ts`
-- [ ] Refs are properly typed with HTML element types
\ No newline at end of file