cloudinary · dawid-ai · Jul 21, 2026
diff --git a/.cursor/rules/cloudinary.mdc b/.cursor/rules/cloudinary.mdc
@@ -0,0 +1,14 @@
+---
+description: Cloudinary WordPress plugin — canonical agent conventions
+alwaysApply: true
+---
+
+Follow [`AGENTS.md`](../../AGENTS.md) at the repo root for all build/test/lint, distribution, hooks, and conventions.
+
+This is the official Cloudinary plugin for WordPress/WooCommerce — a site plugin installed from the WordPress.org directory, not a code SDK. It does not wrap or require `cloudinary_php`.
+
+Non-negotiables:
+- Edit `src/`; never hand-edit the compiled `js/` and `css/` (webpack builds them via `npm run build`).
+- Build toolchain is Node >=22 / npm >=10 (per `.nvmrc` and `engines`) — ignore any "Node 16" reference.
+- `STABLETAG` in `cloudinary.php`/`readme.txt` is a build-time version placeholder — do not hardcode a version.
+- PHP must pass `composer lint` (WordPress + VIP standards) and target PHP 7.4+. License GPL-2.0. Branch/PR against `master`.
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -0,0 +1,10 @@
+# Copilot instructions — cloudinary_wordpress
+
+This is the official Cloudinary plugin for WordPress/WooCommerce (a site plugin installed from the WordPress.org directory, not a code SDK).
+
+**See [`AGENTS.md`](../AGENTS.md) at the repo root for the canonical instructions** — distribution/versions, contributor setup (Node >=22, `npm install`, `npm run build`, wp-env for e2e), build/test/lint commands, developer hooks, and conventions.
+
+Key reminders:
+- Edit `src/` — never the compiled `js/` and `css/` (built by webpack via `npm run build`).
+- `STABLETAG` in `cloudinary.php`/`readme.txt` is a build-time version placeholder — don't hardcode a version.
+- PHP must pass `composer lint` (WordPress + VIP standards) and run on PHP 7.4+. License is GPL-2.0. PR against `master`.
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,88 @@
+# AGENTS.md — cloudinary_wordpress
+
+## What this is (one line)
+The official Cloudinary plugin for WordPress/WooCommerce: it syncs the WordPress media library to Cloudinary and rewrites front-end image/video URLs to be optimized and CDN-delivered. It is a **site plugin**, configured in `wp-admin`, not a code SDK.
+
+## When to use / when NOT to use
+- **Use this when:** the target is a **WordPress or WooCommerce site** that should optimize and deliver media through Cloudinary. Installed by end users from the **WordPress.org plugin directory**; connected with a `cloudinary://<api_key>:<api_secret>@<cloud_name>` string in the admin UI. No application code needed for basic use.
+- **Do NOT use this when:** you're building a **custom PHP application** and want to call Cloudinary in code — use [`cloudinary_php`](https://github.com/cloudinary/cloudinary_php). This plugin does **not** wrap or require the PHP SDK; it builds delivery URLs and calls the Cloudinary API itself (only runtime PHP dep is `ext-json`).
+- **Siblings:** other platform integrations are `cloudinary_magento2`, `cloudinary_sap_commerce`, `cloudinary_sfcc_site_cartridge`, `cloudinary_commercetools`. For an agent/no-code path see [Cloudinary MCP servers](https://github.com/cloudinary/mcp-servers).
+
+## Distribution & versions
+- **Distribution channel:** WordPress.org plugin directory. Slug: `cloudinary-image-management-and-manipulation-in-the-cloud-cdn`. **Not** published to Composer/Packagist for site use.
+- **Current version:** 3.3.4 (source of truth: `.version` and `package.json`). In `cloudinary.php` and `readme.txt` the version reads `STABLETAG` — that's a **build-time placeholder** replaced at release. Do not hand-set it.
+- **Runtime requirements:** WordPress 5.6+ (tested to 7.0), PHP 7.4+. `cloudinary.php` guards on `version_compare(phpversion(),'7.4','>=')` before loading.
+
+## Setup for contributors
+This is a WordPress plugin built with `@wordpress/scripts` (webpack). **Build toolchain needs Node >=22 and npm >=10** (`.nvmrc` = 22, `engines.node` = ">=22", CI uses Node 22 — the old README's "Node v16" is stale).
+
+```bash
+nvm use            # Node 22 (per .nvmrc)
+npm install        # installs JS deps; postinstall runs `composer install` for PHP tooling
+npm run build      # compile src/ -> js/ and css/ via wp-scripts (webpack)
+npm run dev        # wp-scripts start (watch mode)
+```
+
+For end-to-end tests, the repo uses `@wordpress/env` (Docker):
+```bash
+npm run env:start  # boots WordPress at http://localhost:8888 (wp-env, needs Docker)
+npm run env:stop
+```
+
+## Minimal developer hook example
+Extension is via WordPress filters/actions from a theme/plugin, not by editing this repo. Verified hook:
+```php
+// Add a global transformation to every delivered image (php/class-media.php:994).
+add_filter( 'cloudinary_transformations', function ( $transformations, $attachment_id ) {
+	$transformations[] = array( 'effect' => 'sharpen:80' );
+	return $transformations;
+}, 10, 2 );
+```
+Other verified hooks: `cloudinary_is_media` (`php/class-media.php:331`), `cloudinary_can_sync_asset` (`php/class-sync.php:339`), `cloudinary_is_deliverable` (`php/class-delivery.php:419`), action `cloudinary_register_sync_types` (`php/class-sync.php:679`), action `cloudinary_init_delivery` (`php/class-delivery.php:850`). Full list: <https://cloudinary.com/documentation/wordpress_developers#actions_and_filters>.
+
+WP-CLI (registered in `instance.php` as the `cloudinary` namespace): `wp cloudinary sync` (`php/traits/trait-cli.php:144`), `wp cloudinary analyze` (`php/traits/trait-cli.php:202`).
+
+## Build / test / lint (from CI: .github/workflows/ci.yml)
+```bash
+npm ci                                  # clean install (CI)
+npm run lint                            # runs lint:php (phpcs), lint:js (wp-scripts), lint:style
+npm run build                           # webpack production build
+
+# End-to-end (Playwright on wp-env, Docker required):
+npx playwright install --with-deps chromium
+npm run build
+npm run env:start
+npm run test:e2e                        # playwright test --config tests/e2e/playwright.config.js
+npm run env:stop
+
+# Single e2e test file:
+npx playwright test tests/e2e/<file>.spec.js --config tests/e2e/playwright.config.js
+
+# PHP-only lint / auto-fix (Composer scripts):
+composer lint                           # phpcs (WordPress/VIP coding standards)
+composer fix                            # phpcbf
+```
+CI matrix: PHP **7.4 and 8.3**, Node **22**. The `build` job runs `npm ci` → `npm run lint` → `npm run build`; the `e2e` job builds, boots wp-env, and runs Playwright (needs the `CLOUDINARY_E2E_URL` secret for live-cloud e2e).
+
+## Conventions & gotchas
+- **Edit `src/`, not the compiled output.** JS/CSS in `js/` and `css/` are built from `src/` by webpack — never hand-edit the compiled files; run `npm run build`.
+- **`STABLETAG` is a build-time placeholder** for the version in `cloudinary.php` and `readme.txt` (replaced by grunt-text-replace / release-it at release). Don't hardcode a version there.
+- PHP lives in namespaced `Cloudinary\` classes under `php/`; bootstrap is `cloudinary.php` → `instance.php` → `new Cloudinary\Plugin()`.
+- PHP must pass **WordPress + VIP coding standards** (phpcs via `composer lint`) and stay compatible with **PHP 7.4**.
+- Release tooling (Grunt `grunt-wp-deploy` to the WP.org SVN, `release-it`) is maintainer-only — don't run `npm run deploy`.
+- **License: GPL-2.0** — keep new files GPL-compatible.
+- **`npm run readme` is currently broken** (aliases a `composer readme` script that isn't defined). Don't rely on it.
+
+## Canonical docs
+- WordPress integration guide: https://cloudinary.com/documentation/wordpress_integration
+- Developer hooks (actions & filters): https://cloudinary.com/documentation/wordpress_developers#actions_and_filters
+- Plugin listing: https://wordpress.org/plugins/cloudinary-image-management-and-manipulation-in-the-cloud-cdn/
+- Transformation & API references: https://cloudinary.com/documentation/cloudinary_references
+
+## Agent / MCP note
+For autonomous Cloudinary operations outside WordPress, prefer the [Cloudinary MCP servers](https://github.com/cloudinary/mcp-servers). Use this repo for changes to the WordPress plugin itself.
+
+## Commit / PR conventions
+- Branch off and PR against `master`. Keep the CI matrix green (PHP 7.4 & 8.3, Node 22).
+- Run `npm run lint` and `npm run build` before pushing; add/adjust Playwright e2e coverage for behavior changes.
+- Edit `src/`; never commit hand-edited `js/`/`css/` build output or a hardcoded version in place of `STABLETAG`.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,50 @@
+@AGENTS.md
+
+# CLAUDE.md — cloudinary_wordpress
+
+## Claude Code-specific notes
+
+**Primary reference:** `AGENTS.md` (imported above) covers distribution, setup, build/test/lint, hooks, and gotchas. Read it before touching any file.
+
+## What this repo is
+
+`cloudinary_wordpress` is the **WordPress/WooCommerce site plugin** for Cloudinary: it syncs the media library to Cloudinary and rewrites front-end image/video URLs to be optimized and CDN-delivered. Users install it from the **WordPress.org plugin directory** (not Composer) and connect it with a `cloudinary://<api_key>:<api_secret>@<cloud_name>` string in `wp-admin`. It is **not** a code SDK. It does **not** wrap or require `cloudinary_php` — point custom-PHP-app builders to `cloudinary_php` instead.
+
+## Key constraints
+
+- **Build needs Node >=22 and npm >=10** (`.nvmrc` = 22, `engines.node` = ">=22", CI Node 22). Ignore any "Node 16" reference — it's stale.
+- **Edit `src/`, never the compiled `js/` and `css/`.** They're built by webpack (`npm run build`).
+- **`STABLETAG`** in `cloudinary.php` and `readme.txt` is a **build-time placeholder** for the version — do not replace it with a hardcoded version. Current version is 3.3.4 (`.version`, `package.json`).
+- **PHP 7.4 floor.** Code must pass WordPress + VIP coding standards (`composer lint` → phpcs) and run on the CI matrix (PHP 7.4 & 8.3).
+- **Branch target:** `master`. License is **GPL-2.0** — keep new files GPL-compatible.
+- **`npm run readme` is broken** (missing `composer readme` script) — don't rely on it.
+
+## Verified build/test commands
+
+```bash
+npm install                 # postinstall runs composer install (PHP tooling)
+npm run lint                # lint:php (phpcs) + lint:js + lint:style
+npm run build               # webpack production build (src/ -> js/, css/)
+npm run dev                 # wp-scripts watch mode
+
+# End-to-end (Docker + wp-env):
+npx playwright install --with-deps chromium
+npm run build
+npm run env:start           # WordPress at http://localhost:8888
+npm run test:e2e            # playwright test --config tests/e2e/playwright.config.js
+npm run env:stop
+
+# Single e2e file:
+npx playwright test tests/e2e/<file>.spec.js --config tests/e2e/playwright.config.js
+
+# PHP lint / auto-fix:
+composer lint               # phpcs
+composer fix                # phpcbf
+```
+
+## Verified developer extension points
+
+- Filters: `cloudinary_transformations` (`php/class-media.php:994`), `cloudinary_is_media` (`php/class-media.php:331`), `cloudinary_can_sync_asset` (`php/class-sync.php:339`), `cloudinary_is_deliverable` (`php/class-delivery.php:419`).
+- Actions: `cloudinary_register_sync_types` (`php/class-sync.php:679`), `cloudinary_init_delivery` (`php/class-delivery.php:850`).
+- WP-CLI: `wp cloudinary sync` (`php/traits/trait-cli.php:144`), `wp cloudinary analyze` (`php/traits/trait-cli.php:202`).
+- Full hook reference: <https://cloudinary.com/documentation/wordpress_developers#actions_and_filters>.