docs: correct verified URL output and apply npm/python review feedback

Fixes found by executing the snippets, plus the review comments from the
reference PRs (cloudinary_npm#742, pycloudinary#449) that still applied here.

Corrections caught by running the code:

- transform-and-deliver-video.md showed a /v1/ segment on a non-nested
  public_id in four places. The image page documents the rule correctly —
  /v1/ appears only when the public_id contains a slash — so the two pages
  contradicted each other. All four now match generated output exactly.
- getenv() returns false when unset and fromCloudinaryUrl() requires a
  string, so the no-credentials path raised a TypeError instead of the SDK's
  ConfigurationException. troubleshoot-errors.php leaked a PHP signature
  dump; it now matches the other eleven examples.
- Documented URLs omitted the ?_a= analytics parameter the SDK adds by
  default, so actual output did not match the page. Documented what it is
  and how to disable it.

Review feedback applied:

- Exception structure: ApiError is a bare Exception, so getCode() is 0 and
  there is no structured error body. Added the HTTP status column and a
  section stating that the exception class is the only machine-readable
  signal.
- 423 (Processing) is unmapped in BaseApiClient and surfaces as GeneralError
  carrying the raw response body, so it cannot be caught by type.
  Documented with a message-matching retry.
- Moderation is not access control: whether pending, approved, or rejected
  assets are deliverable is product-environment configurable, and the Media
  Library and CDN are separate surfaces.
- Moderation add-ons need account enablement and sometimes provider terms
  acceptance — neither of which an agent can do.
- Upload size limits are per product environment; raising chunk_size does
  not raise the ceiling. Added mitigations and an upgrade path.
- Prefer asset_id for stored references; links to the search expression and
  transformation references; concrete one-hour signature lifetime; signed
  parameters must match what the client posts.

Also tagged two illustrative blocks as plain rather than php: conflicting
use statements and a bare class name are not runnable snippets and would
otherwise be false positives for a snippet parser.

Verified: 56 php blocks across docs/ parse clean, examples lint with zero
phpcs errors, all twelve exit 1 with a readable message when credentials
are absent, unit suite 375/375, all internal links and anchors resolve.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: const-cloudinary

docs/configure-cloudinary.md

@@ -97,7 +97,10 @@ first and override the property:
 ```php
 use Cloudinary\Configuration\Configuration;
 
-$configuration = Configuration::fromCloudinaryUrl(getenv('CLOUDINARY_URL'));
+// `?: ''` matters: getenv() returns false when unset, and fromCloudinaryUrl() requires a
+// string, so without it an unset variable raises a TypeError instead of the SDK's
+// ConfigurationException.
+$configuration = Configuration::fromCloudinaryUrl(getenv('CLOUDINARY_URL') ?: '');
 $configuration->logging->enabled = false;
 
 $cloudinary = new Cloudinary($configuration);

docs/import-and-call.md

@@ -58,7 +58,7 @@ $result->getArrayCopy();     // array, for json_encode() or var_dump()
 The classmap autoloader means a file's path is not always its namespace. The signing
 helper lives at `src/Api/Utils/ApiUtils.php` but is namespaced `Cloudinary\Api`:
 
-```php
+```
 use Cloudinary\Api\ApiUtils;          // correct
 use Cloudinary\Api\Utils\ApiUtils;    // Error: Class not found
 ```

docs/moderate-upload.md

@@ -60,12 +60,18 @@ the asset.
 | `moderation_status` | Same status, flattened. Admin API responses only. |
 | `public_id` | Needed to approve or reject later. |
 
-## A pending asset is still delivered
+## What `pending` means depends on your product environment
 
-Queuing for moderation does not hide the asset. Until you act on it, its delivery URL
-works. If content must not be visible before review, upload it as
+`pending` is a moderation state, not a guaranteed access state. Whether a pending asset is
+publicly deliverable is governed by a product-environment setting, so it differs between
+accounts — on many it **is** deliverable while awaiting review, which surprises people.
+
+Do not rely on moderation as an access-control mechanism in either direction. Verify the
+behaviour on your own environment, and if content must not be reachable before review,
+enforce that explicitly: upload as
 [`'type' => 'private'`](https://cloudinary.com/documentation/upload_images.md) or into a
-restricted folder, and publish after approval.
+restricted folder, then publish after approval. The same applies to what the asset looks
+like in the Media Library versus on the CDN — those are separate surfaces.
 
 ## Approving and rejecting
 
@@ -81,7 +87,9 @@ $cloudinary->adminApi()->update('docs/needs-review', [
 ]);
 ```
 
-Rejected assets are moved out of delivery; approved ones stay.
+How each state maps to delivery is again environment-configurable — commonly `rejected`
+is taken out of delivery and `approved` stays, but confirm it on your environment rather
+than assuming it.
 
 ## Listing the queue
 
@@ -98,8 +106,13 @@ foreach ($pending['resources'] as $asset) {
 ## Automatic moderation is an add-on
 
 `'moderation' => 'manual'` needs no add-on. Automatic kinds — AI-based visual moderation,
-perceptual duplicate detection — must be enabled on your account first. Without a
-subscription the call fails at request time.
+perceptual duplicate detection — must be enabled on your account first, which the account
+owner does in the Console; some add-ons also require accepting the provider's terms of
+service before the first call will succeed. An agent cannot do either step: if the call
+fails for this reason, tell the user what to enable rather than retrying.
+
+The available kinds and their provider-specific response shapes are listed in
+[moderation add-ons](https://cloudinary.com/documentation/moderation_addons.md).
 
 Because the verdict is model output, assert on the **shape** of the response — that a
 status exists and is one of the expected values — not on a specific verdict for a given
@@ -119,3 +132,5 @@ image.
 - [Upload an image](upload-image.md)
 - [Search and manage assets](search-and-manage-assets.md)
 - [What this SDK does and does not do](platform-capabilities.md)
+- [Moderation add-ons](https://cloudinary.com/documentation/moderation_addons.md) — the
+  kinds beyond `manual`, and what each returns.

docs/platform-capabilities.md

@@ -48,7 +48,7 @@ Any documentation URL returns Markdown if you append `.md`.
 | Search by expression | `$cloudinary->searchApi()` | [Search and manage assets](search-and-manage-assets.md) |
 | List, rename, delete, tag | `$cloudinary->adminApi()`, `$cloudinary->uploadApi()` | [Search and manage assets](search-and-manage-assets.md) |
 | Find visually similar assets | `$cloudinary->adminApi()->visualSearch()` | [Search and manage assets](search-and-manage-assets.md) |
-| Attach structured fields | `$cloudinary->adminApi()->addMetadataField()` | [Use structured metadata](use-structured-metadata.md) |
+| Track typed, validated business data per asset — owner, campaign, licence expiry — and search on it | `$cloudinary->adminApi()->addMetadataField()` | [Use structured metadata](use-structured-metadata.md) |
 | Bundle assets into an archive | `$cloudinary->uploadApi()->createArchive()` | [Search and manage assets](search-and-manage-assets.md) |
 
 ### Analyze and moderate

docs/search-and-manage-assets.md

@@ -51,7 +51,8 @@ Runnable version: [`examples/search-and-manage-assets.php`](../examples/search-a
 | `created_at>2026-01-01` | Uploaded since that date |
 | `context.alt:shirt*` | Context field prefix match |
 
-Combine with `AND`, `OR`, `NOT`.
+Combine with `AND`, `OR`, `NOT`. Full grammar:
+[search expressions reference](https://cloudinary.com/documentation/search_expressions.md).
 
 ### Leading wildcards are rejected
 

docs/sign-browser-upload.md

@@ -5,8 +5,9 @@
 Letting a browser or mobile app upload straight to Cloudinary without routing the bytes
 through your server — and without ever exposing your `api_secret`.
 
-Your server signs a short-lived set of parameters; the client posts the file plus that
-signature directly to Cloudinary.
+Your server signs a set of parameters; the client posts the file plus that signature
+directly to Cloudinary. The signature covers a `timestamp` and is accepted for
+**one hour** from it — generate one per upload attempt rather than caching.
 
 ## Complete flow
 
@@ -23,7 +24,10 @@ use Cloudinary\Cloudinary;
 $cloudinary = new Cloudinary();
 $cloud      = $cloudinary->configuration->cloud;
 
-// Only the parameters the client is allowed to send. Every one of these is signed.
+// Only the parameters the client is allowed to send. Every entry in this array is
+// covered by the signature, and every signed entry must also be POSTed by the client —
+// the two sets have to match exactly. To let the client set something (a tag, a folder),
+// add it here; anything absent here cannot be sent.
 $params = [
     'timestamp' => time(),
     'folder'    => 'user-uploads',
@@ -91,7 +95,7 @@ Invalid Signature <hash>. String to sign - 'folder=user-uploads&timestamp=178758
 
 ## Signatures are short-lived
 
-`timestamp` is part of the signature and Cloudinary rejects stale ones (about an hour).
+`timestamp` is part of the signature and Cloudinary rejects one older than an hour.
 Generate a signature per upload attempt; do not cache or reuse them.
 
 ## Alternative: unsigned uploads

docs/transform-and-deliver-image.md

@@ -33,11 +33,21 @@ echo $url, PHP_EOL;
 Output:
 
 ```
-https://res.cloudinary.com/<cloud_name>/image/upload/c_fill,g_auto,h_400,w_400/f_auto/q_auto/sample
+https://res.cloudinary.com/<cloud_name>/image/upload/c_fill,g_auto,h_400,w_400/f_auto/q_auto/sample?_a=BAAHWXGY
 ```
 
 Runnable version: [`examples/transform-and-deliver-image.php`](../examples/transform-and-deliver-image.php).
 
+### The `?_a=` suffix
+
+Generated URLs carry an `_a` query parameter — anonymous SDK-version telemetry, no
+account or asset data. It does not affect delivery or caching. The examples below omit it
+for readability; real output always includes it. To turn it off:
+
+```php
+$cloudinary = new Cloudinary('cloudinary://key:secret@cloud?analytics=false');
+```
+
 ## Result fields to keep
 
 The builder is not a response object — it produces a string. Cast it explicitly when you
@@ -128,3 +138,8 @@ This is expected and the URL resolves correctly. To emit a real version, pass th
 - [Transform and deliver a video](transform-and-deliver-video.md)
 - [Upload an image](upload-image.md)
 - [Troubleshoot errors](troubleshoot-errors.md)
+- [Transformation reference](https://cloudinary.com/documentation/transformation_reference.md)
+  — every parameter, with the URL syntax each one produces.
+- [Transformation builder skill](https://cloudinary.com/documentation/cloudinary_llm_mcp.md)
+  — install it (`npx skills add cloudinary-devs/skills`) rather than guessing at
+  transformation chains.

docs/transform-and-deliver-video.md

@@ -31,11 +31,15 @@ echo $url, PHP_EOL;
 Output:
 
 ```
-https://res.cloudinary.com/<cloud_name>/video/upload/c_fill,h_360,w_640/f_auto/q_auto/v1/my-video
+https://res.cloudinary.com/<cloud_name>/video/upload/c_fill,h_360,w_640/f_auto/q_auto/my-video?_a=BAAHWXGY
 ```
 
 Runnable version: [`examples/transform-and-deliver-video.php`](../examples/transform-and-deliver-video.php).
 
+The trailing `?_a=` is anonymous SDK-version telemetry, present on every generated URL.
+See [Transform and deliver an image](transform-and-deliver-image.md#the-_a-suffix) for
+how to disable it. The path examples below omit it for readability.
+
 ## Result fields to keep
 
 `$cloudinary->video()` builds a string, like the image builder. Cast explicitly outside
@@ -58,15 +62,15 @@ use Cloudinary\Transformation\VideoEdit;
 
 // First five seconds.
 $cloudinary->video('my-video')->videoEdit(VideoEdit::trim()->startOffset(0)->endOffset(5));
-// -> /video/upload/eo_5,so_0/v1/my-video
+// -> /video/upload/eo_5,so_0/my-video
 
 // Quieter audio.
 $cloudinary->video('my-video')->videoEdit(VideoEdit::volume(-20));
-// -> /video/upload/e_volume:-20/v1/my-video
+// -> /video/upload/e_volume:-20/my-video
 
 // Auto-generated highlight preview.
 $cloudinary->video('my-video')->videoEdit(VideoEdit::preview(5));
-// -> /video/upload/e_preview:duration_5/v1/my-video
+// -> /video/upload/e_preview:duration_5/my-video
 ```
 
 ## Generating a `<video>` tag

docs/troubleshoot-errors.md

@@ -9,22 +9,69 @@ account, or the input.
 
 All API failures extend `Cloudinary\Api\Exception\ApiError`:
 
-| Exception | Typical cause |
-|---|---|
-| `BadRequest` | Malformed input — wrong `resource_type`, bad search expression, undefined metadata key. |
-| `AuthorizationRequired` | Bad or mismatched credentials; a feature not enabled for the account. |
-| `NotFound` | No asset with that `public_id` and `resource_type`. |
-| `AlreadyExists` | The identifier is taken. |
-| `NotAllowed` | The operation is forbidden on this account or asset. |
-| `RateLimited` | Too many requests — or an unsubscribed add-on. |
-| `GeneralError` | Server-side failure with no more specific type. |
+| Exception | HTTP | Typical cause |
+|---|---|---|
+| `BadRequest` | 400 | Malformed input — wrong `resource_type`, bad search expression, undefined metadata key. |
+| `AuthorizationRequired` | 401 | Bad or mismatched credentials; a feature not enabled for the account. |
+| `NotAllowed` | 403 | The operation is forbidden on this account or asset. |
+| `NotFound` | 404 | No asset with that `public_id` and `resource_type`. |
+| `AlreadyExists` | 409 | The identifier is taken. |
+| `RateLimited` | 420, 429 | Too many requests — or an unsubscribed add-on. |
+| `GeneralError` | 500, anything unmapped | Server-side failure, or a status this SDK has no specific class for. |
 
 Configuration problems throw from a **different namespace**:
 
-```php
+```
 Cloudinary\Exception\ConfigurationException  // not under Api\Exception
 ```
 
+### Only the message is preserved
+
+This SDK constructs exceptions with the server's error message and nothing else. There is
+no status-code getter and no structured error body — `getCode()` returns `0`:
+
+```php
+try {
+    $cloudinary->adminApi()->asset('missing');
+} catch (ApiError $e) {
+    $e->getMessage();   // 'Resource not found - missing'
+    $e->getCode();      // 0 — not the HTTP status
+    get_class($e);      // Cloudinary\Api\Exception\NotFound — this is the signal
+}
+```
+
+Branch on the **exception class**, not on a code parsed out of the message. The class is
+the only reliable machine-readable part.
+
+### 423 and other unmapped statuses
+
+Only the statuses in the table have their own class. Anything else — notably **423
+(asset still processing)** — becomes a `GeneralError` whose message is the raw response
+body rather than the parsed error text:
+
+```
+GeneralError: Server returned unexpected status code - 423 - {"error":{"message":"..."}}
+```
+
+So a 423 cannot be distinguished by type. If you need to retry on it, match the status in
+the message:
+
+```php
+use Cloudinary\Api\Exception\GeneralError;
+
+try {
+    $cloudinary->adminApi()->asset('still-processing');
+} catch (GeneralError $e) {
+    if (str_contains($e->getMessage(), 'status code - 423')) {
+        // Asset is still being processed — back off and retry.
+    }
+
+    throw $e;
+}
+```
+
+Cloudinary platform status: [status.cloudinary.com](https://status.cloudinary.com).
+
 ## Catching them
 
 ```php
@@ -108,7 +155,9 @@ handler, so one failure can look like three. To handle errors yourself without t
 ```php
 use Cloudinary\Configuration\Configuration;
 
-$configuration = Configuration::fromCloudinaryUrl(getenv('CLOUDINARY_URL'));
+// getenv() returns false when unset; fromCloudinaryUrl() requires a string, so `?: ''`
+// yields the SDK's ConfigurationException instead of a raw PHP TypeError.
+$configuration = Configuration::fromCloudinaryUrl(getenv('CLOUDINARY_URL') ?: '');
 $configuration->logging->enabled = false;
 
 $cloudinary = new Cloudinary($configuration);

docs/upload-image.md

@@ -43,7 +43,7 @@ Runnable version: [`examples/upload-image.php`](../examples/upload-image.php).
 | Field | Why it matters |
 |---|---|
 | `public_id` | The delivery handle. Every transformation URL is built from it. |
-| `asset_id` | Immutable identifier. Survives renames — prefer it for lookups you store. |
+| `asset_id` | Immutable identifier. **Store this one.** Survives renames and moves; `public_id` does not. |
 | `secure_url` | Ready-to-use HTTPS delivery URL of the original. |
 | `version` | Cache-busting number; changes on every re-upload to the same `public_id`. |
 | `format`, `width`, `height`, `bytes` | What the server actually stored, after any incoming transformation. |