fix: harden canonical PHP quickstart

.github/workflows/test.yml

@@ -3,6 +3,7 @@ name: Tests
 on:
   push:
     branches: [main]
+    tags: ["v*"]
   pull_request:
 
 jobs:
@@ -32,6 +33,40 @@ jobs:
       - name: Run unit tests
         run: vendor/bin/phpunit
 
+  clean-install:
+    name: Packaged Composer example
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.3"
+          extensions: curl, json
+          coverage: none
+
+      - name: Install exact Composer archive and run recovery fixtures
+        env:
+          SDK_VERSION: ${{ startsWith(github.ref, 'refs/tags/v') && github.ref_name || '2.1.0' }}
+        run: ./scripts/clean-install-smoke.sh
+
+  live:
+    name: Live canonical first request
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.3"
+          extensions: curl, json
+          coverage: none
+
+      - name: Install dependencies
+        run: composer update --no-interaction --prefer-dist --no-progress
+
       # Optional live smoke test. IMPORTANT: do NOT gate this step with
       # `if: ${{ secrets.* }}` - the secrets context is unavailable in
       # step-level `if` expressions and invalidates the whole workflow file.

CHANGELOG.md

@@ -1,12 +1,30 @@
 # Changelog
 
+## 2.1.0 (2026-07-19)
+
+### Fixed
+
+- Reject successful latest-price responses that contain no usable price.
+- Preserve the production `source` field on the immutable `Price` DTO.
+- Correct the no-code `latest()` documentation to reflect the production
+  singleton response while retaining legacy list-envelope compatibility.
+
+### Changed
+
+- Publish an executable `OILPRICEAPI_KEY` first request with actionable missing
+  configuration, 401, 403, and 429 recovery.
+- Replace mutable product claims with links to the reviewed product-facts,
+  pricing, catalog, and data-rights contracts.
+- Add a Composer archive clean-install smoke, strict production first-request
+  guard, and public-claim drift test.
+
 ## 2.0.0 (2026-07-03)
 
 Ground-up rewrite of the PHP SDK.
 
 ### Added
 
-- `OilPriceAPI\Client` with `latest()`, `pastDay()`, `pastWeek()`, `pastMonth()`, `pastYear()`, `demoPrices()`, and the `raw()` escape hatch for any endpoint.
+- `OilPriceAPI\Client` with `latest()`, `pastDay()`, `pastWeek()`, `pastMonth()`, `pastYear()`, `demoPrices()`, and a `raw()` escape hatch for versioned GET endpoints.
 - Keyless demo mode via `/v1/demo/prices`; helpful `AuthenticationException` (with signup URL) when keyed endpoints are called without a key.
 - `OILPRICEAPI_KEY` environment variable fallback.
 - Immutable `Price` DTO (`code`, `price`, `currency`, `updatedAt` as `DateTimeImmutable`, `change24h`, plus `name`/`unit`/`type`/`formatted`) with `toArray()`.