docs: add agent-readable documentation and repository metadata

[const-cloudinary]

Goal

Ship version-matched documentation inside the published gem, so an AI coding agent working in a user's project reads docs that match the installed code instead of relying on stale training data. Follows the standard established in cloudinary_npm (#742, #744).

Agent read path, verified against a real install:

ruby -e 'puts Gem::Specification.find_by_name("cloudinary").gem_dir + "/docs"'
# => $(gem env gemdir)/gems/cloudinary-<version>/docs

Added

• docs/ — 17 Markdown task pages, shipped in the gem. Index carries the agent-rules banner and locator one-liner.
  • Core: platform-capabilities, get-credentials, require-and-call, configure, upload-image, upload-large-video, sign-browser-upload, transform-and-deliver-image, transform-and-deliver-video, search-and-manage-assets, moderate-upload, use-structured-metadata, troubleshoot-errors.
  • Rails (no npm equivalent): use-with-rails, upload-with-activestorage, upload-with-carrierwave.
• examples/ — 12 runnable files, 1:1 with the task docs, cross-linked.
• AGENTS.md (6 sections) + CLAUDE.md (@AGENTS.md).
• LICENSE — MIT, canonical text, at root.
• SECURITY.md — private vulnerability reporting.
• context7.json.

Changed

• README.md — restructured: install, quick start, common tasks, when to use, compatibility, documentation, AI agent read paths, support, security. Dead Travis CI badge replaced with GitHub Actions.
• cloudinary.gemspec — ship docs/ and examples/ explicitly; add documentation_uri, source_code_uri, bug_tracker_uri.
• .gitignore — artifacts produced by running the examples.

No changes to lib/ or spec/. No changelog entry (docs-only).

Behaviours corrected by execution

Every snippet was run against a live cloud rather than read from source. Docs were wrong on these until tested:

• upload_large defaults to resource_type: :raw — a video uploaded without it succeeds silently as an untransformable blob.
• overwrite: false does not raise; it returns the existing asset with existing => true.
• folder:examples matches 0 of 61 images on a dynamic-folder environment (the default for new clouds). Docs use public_id:examples/*.
• Upload response has no moderation_status key; resource() and update() have both it and moderation.
• Cloudinary::Api and Cloudinary::Search raise bare RuntimeError for missing config; Uploader and Utils raise CloudinaryException. rescue CloudinaryException misses the Admin API path.
• URLs are HTTPS by default; ?_a= analytics param is appended; /v1/ placeholder appears when the public_id contains a slash and no version is known.
• CLOUDINARY_CLOUD_NAME causes CLOUDINARY_URL to be ignored entirely, not merged.
• Undefined structured-metadata keys reject the whole upload. Search rejects leading wildcards and bare *.

Verification

Check	Result
Examples run live	12/12 pass (Rails 8.1.1, CarrierWave 3.1.3 installed)
Examples, no credentials	12/12 friendly message, exit 1, no stack trace
Ruby syntax	12/12 examples, 45/45 doc snippets
Internal links and anchors	121/121 resolve
External URLs	52/52 return 200
SDK symbols named in docs	all resolve against the real library
Built .gem contents	17 docs + 12 examples, 0 stray artifacts
Existing specs	no regression (10 failures on branch = 10 on master)

Notes

• Badges sit above the H1, matching this gem's previous README and RubyGems convention. cloudinary_npm places them below the one-liner.
• context7.json carries the account-scoped key from cloudinary_npm. It is inert until the library is submitted at context7.com — still outstanding.
• GitHub repo metadata (description, homepage, topics) not changed — outward-facing, needs a maintainer decision.
• #595 adds .cursor/ and copilot files this standard excludes, and is superseded by this PR.
• samples/ flagged as legacy in AGENTS.md; not modified.