Bring the repository up to the Cloudinary agent-readable documentation standard,
following the structure shipped in cloudinary_npm (PRs #742 and #744).

Documentation, shipped inside the Composer package so it is always version-matched
to the installed code:

- docs/ — 13 task pages with an index carrying the agent-rules banner. Every
  snippet was executed against a live cloud before being committed.
- examples/ — 12 runnable files, one per task page, all verified green.

Repository files:

- README.md restructured: quick start, common tasks, when to use this SDK,
  compatibility, and a read path for coding agents.
- AGENTS.md (six sections) plus CLAUDE.md; SECURITY.md with private vulnerability
  reporting; context7.json.

Packaging:

- .gitattributes decides what ships. docs/ and examples/ reach users at
  vendor/cloudinary/cloudinary_php/; tests/, tools/, samples/, apidocs/, and the
  lint/test configs no longer do.
- The Sami API-doc tooling moves from docs/ to apidocs/ so that docs/ can hold the
  Markdown task docs, which is the path agents look for. tools/update_version.sh
  is updated to match.

Corrections found by executing the documented calls rather than reading the source:

- The API accessors are methods. The previous README documented
  $cloudinary->uploadApi->upload(...), which is a fatal error; it is
  $cloudinary->uploadApi()->upload(...).
- ApiUtils is Cloudinary\Api\ApiUtils, although the file sits in src/Api/Utils/.
- There is no uploadLarge(); upload() chunks automatically above chunk_size.
- A partial configuration array replaces rather than merges, so passing only
  'logging' discards credentials from CLOUDINARY_URL.

Three integration tests asserted the exact shape of API responses and broke when
the API added fields:

- testListFacebookImages and testFacebookImagesWidthHeight asserted that Facebook
  assets carry no width or height. They now do. Raw assets still legitimately have
  none, so the two cases are split: raw asserts absence, Facebook asserts the values
  are integers when present.
- testCreateDateMetadataField asserted that `restrictions` equals exactly
  ['readonly_ui' => true]. The API now also returns `hidden_ui` and
  `excluded_from_search`.

The metadata fix is in the shared assertion loop, so every metadata test now checks
that the expected keys are present and correct rather than that they are the only
keys. Added fields no longer read as regressions.