@@ -5,36 +5,29 @@ project, read [`docs/`](docs/README.md) instead — task-oriented pages for agen
 
 ## Commands
 
-**Use JDK 11.** The Gradle 6.0.1 wrapper cannot run on a modern JVM: under JDK 17+ it fails
-before any task with `Could not initialize class org.codehaus.groovy.reflection.ReflectionCache`.
+Use JDK 8 or 11; CI runs on JDK 8. The Gradle 6.0.1 wrapper fails on JDK 17 and later before any
+task runs.
 
 ```bash
-export JAVA_HOME=/path/to/jdk-11
-./gradlew :cloudinary-core:jar :cloudinary-http5:jar        # build the two artifacts users depend on
-./gradlew :cloudinary-core:test                             # unit tests, no cloud needed
-./gradlew :cloudinary-http5:test -DCLOUDINARY_URL="cloudinary://key:secret@cloud"   # live integration tests
-./gradlew createTestSubAccount -PmoduleName=http5           # throwaway cloud -> tools/cloudinary_url.txt
+./gradlew :cloudinary-core:jar :cloudinary-http5:jar :cloudinary-taglib:jar   # build the published modules
+./gradlew :cloudinary-core:test                          # unit tests, no cloud needed
+./gradlew createTestSubAccount -PmoduleName=http5        # throwaway cloud -> tools/cloudinary_url.txt
+source tools/cloudinary_url.txt                          # sets CLOUDINARY_URL
+./gradlew ciTest -p cloudinary-http5 -DCLOUDINARY_URL="$CLOUDINARY_URL"   # integration tests, as CI runs them
 ```
 
-`CLOUDINARY_URL` is read as a **system property** by the tests (see `java_shared.gradle`), not
-from the environment. `tools/cloudinary_url.txt` is git-ignored and **contains live
-credentials — never commit it or paste its contents anywhere.**
+Gradle passes `-DCLOUDINARY_URL` to the test JVM as the `CLOUDINARY_URL` environment variable
+(`java_shared.gradle`). `tools/cloudinary_url.txt` is git-ignored and contains live credentials;
+never commit it or paste its contents anywhere.
 
 ## Testing
 
-- `cloudinary-core` tests are offline. Everything else needs a live product environment.
-- Do not share one product environment between doc verification and the integration suite.
-  Doc probes leave mandatory metadata fields and pending moderated assets behind, and
-  `ApiTest.testGetResourcesWithMetadata` then fails for reasons unrelated to the branch. Use a
-  fresh sub-account for each.
-- For docs-only changes, run the suite against the base branch and compare failure counts
-  rather than asserting "tests pass". The integration suite takes about 3.5 minutes plus a
-  throwaway cloud.
-- Before committing a `docs/` change, two cheap checks: every `java` snippet compiles against
-  the built jars (wrap fragments in a harness with the ambient names — `cloudinary`, `file`,
-  `publicId` — declared as fields, then `javac`; this catches invented methods, which is the
-  whole point), and every internal link, cross-page anchor, and external URL resolves. GitHub
-  **preserves underscores** in heading slugs, so a naive slugifier reports false positives.
+- `cloudinary-core` tests run offline. `cloudinary-http5` tests need a live product environment.
+  `cloudinary-taglib` has no tests.
+- Use a fresh sub-account for each integration run. Assets and metadata fields left by earlier
+  runs can fail unrelated tests.
+- `java` snippets in `docs/` must compile against the built jars, and links in `docs/` must
+  resolve.
 
 ## Project structure
 
@@ -44,108 +37,76 @@ credentials — never commit it or paste its contents anywhere.**
 | `cloudinary-http5/` | Yes | Apache HttpClient 5 transport. **This is what users depend on.** |
 | `cloudinary-taglib/` | Yes | JSP tags. Targets `javax.*`, not Jakarta EE 9+. |
 | `cloudinary-test-common/` | Yes | Shared test helpers. Not for application code. |
-| `docs/` | No | Task pages for agents *using* the SDK. Every claim produced by running something. |
+| `docs/` | No | Task pages for agents *using* the SDK. |
 | `examples/` | No | One runnable program per doc page where the task is genuinely runnable. |
 | `samples/` | No | Legacy sample applications. Not in the build. |
 | `tools/` | No | Release and test-cloud scripts. |
 
-`settings.gradle` includes only the four modules. The `cloudinary-http42/43/44` directories
-present in a working copy are **untracked leftovers** from the 1.x line — not in git, not in the
-build. Do not add them back and do not "tidy" them as part of unrelated work.
+`settings.gradle` includes the four modules above.
 
 `org.cloudinary.json` inside `cloudinary-core` is a vendored JSON implementation. It exists to
 keep the core dependency-free. Do not replace it with Jackson or Gson.
 
-**`docs/` is deliberately not packaged into any jar.** A survey of 15 widely-used Java libraries
-on Maven Central — Guava, OkHttp, Jackson, Gson, commons-lang3, SLF4J, Retrofit, AWS SDK v2,
-google-cloud-storage, Stripe, Twilio, SendGrid, java-jwt, Spring Core, jsoup — found that only
-jsoup ships any Markdown: its 3 KB project README in `META-INF/`. Everything else carries
-manifests, licences, and machine-consumed config only. Embedding these pages would grow
-`cloudinary-core` by 27%, from 175 KB to 223 KB, for files no runtime reads, and retrieval
-through `unzip -p` is slower than reading the repository or Cloudinary's `llms.txt`. Java's
-convention for documentation attached to an artifact is the `-javadoc.jar`, which this SDK
-already publishes. Reversing this needs a reason better than "other Cloudinary SDKs do it".
-
-`examples/` is likewise not shipped: loose `.java` files inside a library artifact are dead
-weight, and each doc page carries its full flow inline. Keep examples uniform — one entry point
-taking no arguments, no CLI parsing, constants at the top, one error-handling block mapping every
-failure to a non-zero exit with a readable message and no stack trace.
+`docs/` and `examples/` are not packaged into any jar; the published `-javadoc.jar` is the
+documentation attached to each artifact.
+
+Keep examples uniform: one entry point taking no arguments, no CLI parsing, constants at the top,
+and one error-handling block mapping every failure to a non-zero exit with a readable message.
 
 ## Code style
 
 - The build targets **Java 8** (`sourceCompatibility = 1.8` in `java_shared.gradle`). Do not use
   newer language features in `src/main`.
-- There is **no linter, formatter, or static-analysis tool**, deliberately. Match the surrounding
-  code and do not introduce one as a side effect.
+- There is no linter, formatter, or static-analysis tool. Match the surrounding code.
 - Options are untyped `Map`s built with `ObjectUtils.asMap(k, v, ...)`; responses are `Map`s keyed
   by the raw API field names (`public_id`, `secure_url`, `asset_id`). There are no typed response
   objects.
 - `Cloudinary` is safe to share as a singleton. `Url` is a **mutable** builder and is not
   thread-safe; call `cloudinary.url()` per URL.
-- In docs, prefer `asset_id` (immutable) over `public_id` (changes on rename) when showing how to
-  store a reference. Only six `Api` methods accept an asset ID; nothing in `Uploader` does.
-- Docs describe **this SDK**, not how it differs from other Cloudinary SDKs. Link Cloudinary docs
-  in `.md` form (`https://cloudinary.com/documentation/<page>.md`); the repository `README.md`
-  may link HTML, since people read it. Do not recommend third-party packages — community
-  Java/Spring integrations exist and are not maintained by Cloudinary.
-- Docs are reference documentation: state what the API does and how to use it. Do not frame
-  documented behaviour as a bug or an oversight, and do not tell the reader what they might
-  wrongly assume.
-- Docs and README carry **no version literal**. Install snippets use `X.Y.Z` and point at the
-  Maven Central badge and a `maven-metadata.xml` one-liner. The literal once drifted to a
-  never-published `2.3.1` while Central was at `2.4.0`, and nothing rewrites `docs/` at release.
+
+## Docs
+
+- Docs describe this SDK. Link Cloudinary documentation in `.md` form
+  (`https://cloudinary.com/documentation/<page>.md`); `README.md` may link HTML. Do not recommend
+  third-party packages.
+- Prefer `asset_id` (immutable) over `public_id` (changes on rename) when showing how to store a
+  reference. Five `Api` methods accept an asset ID; nothing in `Uploader` does.
+- `README.md` shows the released version, which the release script updates. Pages in `docs/` use
+  `X.Y.Z`, because the release script does not touch them.
 
 ## Git workflow
 
 - Branch from `master`; keep changes focused; one topic per pull request.
-- Do not edit `CHANGELOG.md` or bump the version. Releases are a separate process:
-  `tools/update_version.sh` rewrites `Cloudinary.VERSION` in `Cloudinary.java` and `version=`
-  in `gradle.properties`. **It greps the `VERSION` line with a regex; do not reformat it.** Its
-  `sed` over `README.md` is now a harmless no-op. `Cloudinary.VERSION` feeds the `User-Agent` and
-  the `_a=` analytics parameter, so drift misreports SDK usage rather than breaking visibly.
+- Do not edit `CHANGELOG.md` or bump the version. Releases run `tools/update_version.sh <version>`,
+  which rewrites `Cloudinary.VERSION` in `Cloudinary.java`, `version=` in `gradle.properties`, and
+  the version in `README.md`. It reads the `VERSION` line with a regex; do not reformat it.
 - Keep secrets out of everything — code, tests, fixtures, docs, commit messages. Grep the diff
   for `cloudinary://` with real values before pushing.
 - Never commit `tools/cloudinary_url.txt`, `/out/`, or media left behind by running examples.
 
 ## Boundaries
 
 **Always**
-- Produce every claim in `docs/` by running something — not by reading source, and not by
-  copying another Cloudinary SDK's docs. Behaviour differs between the SDKs.
+- Verify claims in `docs/` against the source and, where possible, by running them. Do not copy
+  another Cloudinary SDK's docs; behaviour differs between the SDKs.
 - Keep `docs/` and `examples/` consistent with the code they document.
 - Keep API secrets out of examples, docs, tests, and fixtures.
 
 **Ask first**
-- Changing the published artifact list, packaging, or what ships inside a jar — including
-  moving `docs/` into `src/main/resources`.
-- Adding a dependency. `cloudinary-core` has no runtime dependencies at all, which is a feature
-  for consumers.
-- Changing public API signatures or behaviour. This is a widely deployed library; a behaviour
-  change can break callers. Document current behaviour and raise an issue before changing it.
-- Changing any of these documented behaviours. Each is part of the public contract as observed
-  by execution and described in `docs/`; changing one is a behaviour change for existing
-  callers:
-  1. `Configuration.from()` parses with `java.net.URI`, so a cloud name containing an
-     underscore yields `null` cloud name, key, and secret (`getHost()` and `getUserInfo()`
-     return `null` for a hostname with an underscore). Such environments are configured with a
-     `Map`. An alternative implementation would parse `getAuthority()` directly.
-  2. Error types differ by entry point: `java.lang.RuntimeException` carrying a message for
+- Changing the published artifact list, packaging, or what ships inside a jar.
+- Adding a dependency. `cloudinary-core` has no runtime dependencies.
+- Changing public API signatures or behaviour. Document current behaviour and raise an issue
+  before changing it. This includes these behaviours, which `docs/` describes and callers may
+  depend on:
+  1. Error types differ by entry point: `java.lang.RuntimeException` carrying a message for
      uploads (`AbstractUploaderStrategy.processResponse`), typed `ApiException` subclasses for
      the Admin API, and `java.lang.UnknownError` (an `Error`, not an `Exception`) when no HTTP
      adapter is present.
-  3. `Api.CLOUDINARY_API_ERROR_CLASSES` maps HTTP 400/401/403/404/409/420/500 to typed
-     exceptions; other status codes become `GeneralError`. This includes 429, which is not
-     routed to `RateLimited`.
-  4. `EnumMetadataField` has a package-private constructor and no factory, unlike
+  2. `EnumMetadataField` has a package-private constructor and no factory, unlike
      `SetMetadataField`. Application code uses `new MetadataField<String>(MetadataFieldType.ENUM)`.
-  5. `ProgressCallback` overloads compile on `cloudinary-http5` and throw
-     `IllegalArgumentException: Progress callback is not supported` when called. Progress
-     reporting is available in the Android SDK.
-  6. `Url.resourcType(String)` is retained alongside `resourceType(String)` for compatibility.
-     Both work.
-  7. `Cloudinary.VERSION` and `version=` in `gradle.properties` are maintained separately and
-     can drift; during 2.3.x they read `2.3.1` and `2.3.2`. Both read `2.5.0` at the time of
-     writing.
+  3. `ProgressCallback` overloads compile on `cloudinary-http5` and throw
+     `IllegalArgumentException: Progress callback is not supported` when called.
+  4. `Url.resourcType(String)` is retained alongside `resourceType(String)` for compatibility.
 - Touching `publish.gradle`, `gradle.properties`, `MAVEN_CENTRAL_PUBLISHING_GUIDE.md`, or the
   release script.
 - Adding a typed response object, a linter, or a formatter.
 
@@ -9,18 +9,16 @@ Upload, transform, optimize, and manage images and videos with Cloudinary from J
 
 ## Install
 
-Use the version shown on the Maven Central badge above.
-
 ```xml
 <dependency>
     <groupId>com.cloudinary</groupId>
     <artifactId>cloudinary-http5</artifactId>
-    <version>X.Y.Z</version>
+    <version>2.6.0</version>
 </dependency>
 ```
 
 ```groovy
-implementation 'com.cloudinary:cloudinary-http5:X.Y.Z'
+implementation 'com.cloudinary:cloudinary-http5:2.6.0'
 ```
 
 For JSP tags, also add `cloudinary-taglib`.
 
@@ -53,10 +53,13 @@ Configuration configuration = new Configuration();
 configuration.cloudName = "my-cloud";
 configuration.apiKey = "123456789012345";
 configuration.apiSecret = "abcdeghijklmnopqrstuvwxyz12";
+configuration.secure = true;
 Cloudinary cloudinary = new Cloudinary(configuration);
 ```
 
-`Configuration` fields are public and mutable. A `Configuration.Builder` is also available.
+`Configuration` fields are public and mutable. A `Configuration.Builder` is also available. Both
+start with `secure` set to `false` and analytics off, so set `secure` explicitly; without it,
+`url().generate(...)` returns `http://` URLs.
 
 ## Cloud names containing an underscore
 
@@ -74,7 +77,14 @@ Configuration.from("cloudinary://key:secret@my_cloud").cloudName;  // null
 Configuration.from("cloudinary://key:secret@my_cloud").apiKey;     // null
 ```
 
-The exception appears on the first call that needs credentials:
+The exception appears on the first call that needs configuration. Signed uploads and Admin API
+calls check credentials first:
+
+```
+java.lang.IllegalArgumentException: Must supply api_key
+```
+
+URL generation and unsigned uploads check the cloud name:
 
 ```
 java.lang.IllegalArgumentException: Must supply cloud_name in tag or in configuration
@@ -106,16 +116,16 @@ A `null` check here at startup distinguishes "credentials absent or unparseable"
 
 | Field / key | Default | Meaning |
 |---|---|---|
-| `secure` | `true` | Generate `https://` delivery URLs. Set `false` only when there is a specific reason to. |
+| `secure` | `true` from a `Map` or `CLOUDINARY_URL`; `false` from `new Configuration()` or `Configuration.Builder` | Generate `https://` delivery URLs. |
 | `cname` | unset | Custom delivery domain. |
 | `private_cdn` | `false` | Use a private CDN distribution. |
 | `upload_prefix` | `https://api.cloudinary.com` | API base. Change only for testing against a different endpoint. |
-| `timeout` | `0` (no explicit timeout) | Request timeout in seconds. |
+| `timeout` | `0` (the SDK sets none; HttpClient's default 3-minute read timeout applies) | Request timeout in seconds. |
 | `force_version` | `true` | Include the version segment in delivery URLs. |
-| `analytics` | enabled | Appends a `_a=` query parameter to generated URLs. See below. |
+| `analytics` | enabled from a `Map` or `CLOUDINARY_URL`; off from `new Configuration()` or `Configuration.Builder` | Appends a `_a=` query parameter to generated URLs. See below. |
 
-`secure` defaults to `true`, so `url().generate(...)` returns an `https://` URL unless configured
-otherwise. The upload response contains both `url` (http) and `secure_url` (https); read
+With configuration from a `Map` or `CLOUDINARY_URL`, `secure` defaults to `true`, so
+`url().generate(...)` returns an `https://` URL unless configured otherwise. The upload response contains both `url` (http) and `secure_url` (https); read
 `secure_url`.
 
 ### The `_a=` query parameter
@@ -127,9 +137,11 @@ https://res.cloudinary.com/my-cloud/image/upload/sample.jpg?_a=DAGCg+ALZAA0
 ```
 
 This parameter encodes the SDK and language version; it is not a cache-buster. It appears on URLs
-built by `url().generate()` and is not present in the `secure_url` field of an upload response.
+built by `url().generate()` and is not present in the `secure_url` field of an upload response. It
+is not added to a URL that already has a query string, such as one carrying an auth token.
 
-To turn it off, supply your own `Analytics` instance or disable it in configuration:
+`cloudinary.setAnalytics(...)` changes the value of `_a=`. To turn it off, disable it in
+configuration:
 
 ```java
 Cloudinary cloudinary = new Cloudinary(ObjectUtils.asMap(
 
@@ -10,12 +10,11 @@
 Store `asset_id` as your durable reference. Store `public_id` only if you need to reconstruct a
 URL, and re-read it when you need it.
 
-Six `Api` methods accept an `asset_id`:
+Five `Api` methods accept an `asset_id`:
 
 ```
 Api.resourceByAssetID(String, Map)
 Api.resourcesByAssetIDs(Iterable, Map)
-Api.resourcesByAssetFolder(String, Map)
 Api.deleteResourcesByAssetIds(Iterable, Map)
 Api.restoreByAssetIds(Iterable, Map)
 Api.deleteBackedUpAssets(String, String[], Map)
 
@@ -43,12 +43,13 @@ does not compile.
 Return that map to the client as JSON. It contains the API key and a signature but not the API
 secret.
 
-### What you sign is what you constrain
+### The signed map is the full parameter set
 
-The signature covers exactly the parameters you put in the map. Parameters you do not sign are set
-by the client.
+The upload must send exactly the parameters in the signed map, with the same values. Cloudinary
+rejects the upload with `Invalid Signature` if the client adds a parameter, omits one, or changes a
+value. Only `file`, `cloud_name`, `resource_type`, and `api_key` are outside the signature.
 
-Sign every parameter you want to fix:
+Put every parameter the upload needs into the map on the server:
 
 ```java
 params.put("timestamp", System.currentTimeMillis() / 1000L);
 
@@ -12,7 +12,8 @@ String url = cloudinary.url().generate("docs_sample.jpg");
 
 Two properties of that output:
 
-- It is `https`. `secure` defaults to `true`.
+- It is `https`. `secure` defaults to `true` when configuration comes from a `Map` or
+  `CLOUDINARY_URL`; with `new Configuration()` or `Configuration.Builder`, set it explicitly.
 - The `?_a=` parameter is SDK analytics. See
   [configure-cloudinary.md](configure-cloudinary.md) to disable it.
 
 
@@ -54,7 +54,7 @@ Note:
 
 - Pass the public ID without an extension. `videoTag` appends `.webm`, `.mp4`, and `.ogv`
   itself, and derives the `.jpg` poster from the same ID.
-- The poster is a generated thumbnail of the first frame.
+- The poster is a generated thumbnail of the middle frame.
 - Default source formats are WebM, MP4, and OGV.
 
 For attribute values that come from user input, use `generate()` and let your template engine
 
@@ -108,8 +108,10 @@ try {
 }
 ```
 
-Only `ApiException` subclasses are thrown in practice, but the `throws Exception` declaration means
-the compiler requires the broader catch. Catch `ApiException` first, then `Exception`.
+Besides `ApiException` subclasses, an Admin API call throws `RuntimeException: Invalid JSON response
+from server ...` when the response body is not JSON, such as an HTML 502 page from a proxy, and
+`IllegalArgumentException: Must supply api_key` when credentials are missing. The `Exception`
+branch catches both. Catch `ApiException` first, then `Exception`.
 
 Neither block catches `UnknownError`; see the next section.