docs: add agent-readable documentation and repository metadata

.gitignore

@@ -8,7 +8,7 @@ bin
 !lib
 test_cache/
 .nyc_output
-docs
+out/
 coverage
 # contains temporary cloudianry_url for test accounts
 tools/cloudinary_url.sh

AGENTS.md

@@ -0,0 +1,77 @@
+# Contributor guide for coding agents
+
+This file is for agents contributing to this repository. If you are *using* the installed
+`cloudinary` package in another project, read the bundled docs in
+`node_modules/cloudinary/docs/` instead.
+
+## Commands
+
+```bash
+npm install              # install dependencies
+npm test                 # lint + unit tests + type declaration tests
+npm run test:unit        # mocha unit tests only (mocked, no network)
+npm run lint             # eslint
+npm run dtslint          # TypeScript declaration tests
+npm run test-with-temp-cloud  # full integration tests against a temporary cloud (CI)
+```
+
+Unit tests require a `CLOUDINARY_URL` in the environment or a `.env` file;
+any syntactically valid value works for mocked tests:
+`CLOUDINARY_URL=cloudinary://key:secret@test-cloud`.
+
+## Testing
+
+- `test/unit/` is mocked and must never perform network calls.
+- `test/integration/` requires a real or temporary Cloudinary environment; do not run it
+  by default and do not add tests there that consume paid add-ons without a skip guard.
+- Nondeterministic AI output (captions, tags, moderation verdicts) must be asserted by
+  request shape, state transition, and response schema — never by exact output values.
+
+## Project structure
+
+- `cloudinary.js` — package entry point; exposes the legacy v1 API and `require('cloudinary').v2`.
+- `lib/` — implementation. `lib/v2/` wraps the v1 modules with promise support.
+- `lib/analysis/` — Analyze API (`analyze_uri`).
+- `types/index.d.ts` — TypeScript declarations, tested by `npm run dtslint`.
+- `examples/` — small, runnable task examples shipped in the npm package.
+- `docs/` — version-matched Markdown docs shipped in the npm package.
+- `samples/` — legacy full applications; not part of the tested example set.
+- `test/` — `unit/`, `integration/`, shared helpers in `spechelper.js` and `testUtils/`.
+- `tools/scripts/` — shell entry points used by the npm scripts.
+
+## Code style
+
+- CommonJS modules, ES6+ syntax, two-space indent; eslint config is authoritative.
+- Public API methods accept an options object and an optional Node-style callback and
+  return a Promise, following the existing pattern:
+
+```js
+exports.example_method = function example_method(public_id, callback, options = {}) {
+  return call_api("post", ["example"], { public_id }, callback, options);
+};
+```
+
+## Git workflow
+
+- Branch from `master`; keep changes focused; one topic per pull request.
+- Run `npm test` before opening a PR.
+- Do not rewrite published changelog entries; add new entries at the top.
+- Never commit generated output (`out/`, `coverage/`), credentials, or `.env` files.
+
+## Boundaries
+
+**Always**
+- Update `types/index.d.ts` and tests when public behavior changes.
+- Keep `docs/` and `examples/` consistent with the code they document.
+- Keep API secrets out of examples, docs, tests, and fixtures.
+
+**Ask first**
+- Changing supported Node versions, dependencies, or `package.json.files`.
+- Renaming or removing any public method or exported symbol.
+- Changing release, CI, or publishing configuration.
+
+**Never**
+- Commit credentials or real account identifiers.
+- Perform live network calls in unit or example tests.
+- Document a Cloudinary platform capability as an SDK method unless this package
+  implements it (see docs/platform-capabilities.md).

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2011-2026 Cloudinary Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,103 +1,127 @@
-Cloudinary Node SDK
-=========================
-## About
-The Cloudinary Node SDK allows you to quickly and easily integrate your application with Cloudinary.
-Effortlessly optimize, transform, upload and manage your cloud's assets.
+# Cloudinary Node.js SDK
 
+Upload, transform, optimize, and manage images and videos with Cloudinary from Node.js — the `cloudinary` package on npm.
 
-#### Note
-This Readme provides basic installation and usage information. 
-For the complete documentation, see the [Node SDK Guide](https://cloudinary.com/documentation/node_integration).
+[![CI](https://github.com/cloudinary/cloudinary_npm/actions/workflows/ci.yml/badge.svg)](https://github.com/cloudinary/cloudinary_npm/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/cloudinary.svg)](https://www.npmjs.com/package/cloudinary)
+[![License](https://img.shields.io/npm/l/cloudinary.svg)](LICENSE)
 
-## Table of Contents
-- [Key Features](#key-features)
-- [Version Support](#Version-Support)
-- [Installation](#installation)
-- [Usage](#usage)
-    - [Setup](#Setup)
-    - [Transform and Optimize Assets](#Transform-and-Optimize-Assets)
-    - [Generate Image and HTML Tags](#Generate-Image-and-Video-HTML-Tags)
+## Install
 
-
-## Key Features
-- [Transform](https://cloudinary.com/documentation/node_video_manipulation#video_transformation_examples) and
- [optimize](https://cloudinary.com/documentation/node_image_manipulation#image_optimizations) assets.
-- Generate [image](https://cloudinary.com/documentation/node_image_manipulation#deliver_and_transform_images) and
- [video](https://cloudinary.com/documentation/node_video_manipulation#video_element) tags.
-- [Asset Management](https://cloudinary.com/documentation/node_asset_administration).
-- [Secure URLs](https://cloudinary.com/documentation/video_manipulation_and_delivery#generating_secure_https_urls_using_sdks).
-
-
-
-## Version Support
-| SDK Version | Node version |
-|-------------|--------------|
-| 1.x.x       | Node@6 & up  |
-| 2.x.x       | Node@9 & up  |
-
-## Installation
 ```bash
 npm install cloudinary
 ```
 
-# Usage
-### Setup
-```js
-// Require the Cloudinary library
-const cloudinary = require('cloudinary').v2
-```
+## Quick start
 
-### Transform and Optimize Assets
-- [See full documentation](https://cloudinary.com/documentation/node_image_manipulation).
+Set your API environment variable (Console > Settings > API Keys):
 
-```js
-cloudinary.url("sample.jpg", {width: 100, height: 150, crop: "fill", fetch_format: "auto"})
+```bash
+export CLOUDINARY_URL=cloudinary://<api_key>:<api_secret>@<cloud_name>
 ```
 
-### Upload
-- [See full documentation](https://cloudinary.com/documentation/node_image_and_video_upload).
-- [Learn more about configuring your uploads with upload presets](https://cloudinary.com/documentation/upload_presets). 
+Upload an image and get an optimized delivery URL:
+
 ```js
-cloudinary.v2.uploader.upload("/home/my_image.jpg", {upload_preset: "my_preset"}, (error, result)=>{
-  console.log(result, error);
+const cloudinary = require('cloudinary').v2;
+
+async function main() {
+  // Upload a remote image (a local file path works the same way)
+  const result = await cloudinary.uploader.upload(
+    'https://res.cloudinary.com/demo/image/upload/sample.jpg',
+    { public_id: 'quickstart-sample' }
+  );
+  console.log(`Uploaded: ${result.public_id}`);
+
+  // Build a 400x400 auto-cropped URL with automatic format and quality
+  const url = cloudinary.url(result.public_id, {
+    width: 400,
+    height: 400,
+    crop: 'fill',
+    gravity: 'auto',
+    fetch_format: 'auto',
+    quality: 'auto',
+    secure: true
+  });
+  console.log(`Optimized URL: ${url}`);
+}
+
+main().catch((error) => {
+  console.error(`Quick start failed: ${error.message}`);
+  console.error('Check that CLOUDINARY_URL is set (Console > Settings > API Keys).');
+  process.exitCode = 1;
 });
 ```
-### Large/Chunked Upload
-- [See full documentation](https://cloudinary.com/documentation/node_image_and_video_upload#node_js_video_upload).
-```js
-   cloudinary.v2.uploader.upload_large(LARGE_RAW_FILE, {
-          chunk_size: 7000000
-        }, (error, result) => {console.log(error)});
-```
-### Security options
-- [See full documentation](https://cloudinary.com/documentation/solution_overview#security).
 
-## Contributions
-- Ensure tests run locally (add test command)
-- Open a PR and ensure tests pass
+Save as `quickstart.js` and run `node quickstart.js`. [Create a free account](https://cloudinary.com/users/register_free) if you don't have one — or run `npx @cloudinary/cloud` to [provision one without signing up](docs/get-credentials.md).
+
+## Common tasks
+
+- [Get Cloudinary credentials](docs/get-credentials.md)
+- [Upload an image](docs/upload-image.md)
+- [Upload a large video](docs/upload-large-video.md)
+- [Sign a browser upload](docs/sign-browser-upload.md)
+- [Transform and deliver media](docs/transform-and-deliver-media.md)
+- [Search and manage assets](docs/search-and-manage-assets.md)
+- [Moderate an upload](docs/moderate-upload.md)
+- [Use structured metadata](docs/use-structured-metadata.md)
+- [Troubleshoot errors](docs/troubleshoot-errors.md)
+
+Runnable versions live in [`examples/`](examples/) — each is a complete file you can run directly.
+
+## When to use this SDK
+
+Use this package in **Node.js server-side code**: uploads, signed operations, asset
+administration, search, moderation, and delivery URL generation.
+
+For other jobs, better-fitting tools exist:
+
+- Browser or frontend framework rendering: [@cloudinary/url-gen](https://www.npmjs.com/package/@cloudinary/url-gen) and the [frontend SDKs](https://cloudinary.com/documentation/frontend_sdks) ([md](https://cloudinary.com/documentation/frontend_sdks.md)).
+- Complete in-browser upload UI: [Upload Widget](https://cloudinary.com/documentation/upload_widget) ([md](https://cloudinary.com/documentation/upload_widget.md)).
+- Text-to-image generation and image-to-video: [platform APIs](https://cloudinary.com/documentation/image_generation_addon) ([md](https://cloudinary.com/documentation/image_generation_addon.md)), not wrapped by this package.
+- Multi-step media workflow automation: [MediaFlows](https://cloudinary.com/documentation/mediaflows_user_guide) ([md](https://cloudinary.com/documentation/mediaflows_user_guide.md)).
+- Interactive agent-driven asset operations: [Cloudinary MCP servers and Skills](https://cloudinary.com/documentation/cloudinary_llm_mcp) ([md](https://cloudinary.com/documentation/cloudinary_llm_mcp.md)).
+
+The full capability map — plus the Skills, MCP servers, and CLI worth setting up first —
+is in [docs/platform-capabilities.md](docs/platform-capabilities.md).
+
+## Status and compatibility
+
+Stable, actively maintained. See [CHANGELOG.md](CHANGELOG.md).
+
+| SDK version | Node.js |
+|-------------|---------|
+| 2.x         | 9 and later |
+| 1.x         | 6 and later (no longer maintained) |
+
+## Documentation
+
+- [Bundled task docs](docs/README.md) — ship inside the package, version-matched.
+- [Node SDK guide](https://cloudinary.com/documentation/node_integration) — the full documentation ([md](https://cloudinary.com/documentation/node_integration.md)).
+
+Documentation links in this README point at the browsable HTML page, with an `(md)`
+companion link that returns the same page as raw Markdown. Inside `docs/` and `examples/`
+the links are Markdown-only, since those files are written to be read by coding agents.
+Either form works for any page: add `.md` for Markdown, drop it for HTML.
 
+## For AI coding agents
 
-## Get Help
-If you run into an issue or have a question, you can either:
-- Issues related to the SDK: [Open a Github issue](https://github.com/cloudinary/cloudinary_npm/issues).
-- Issues related to your account: [Open a support ticket](https://cloudinary.com/contact)
+- Contributing to this repo: read [AGENTS.md](AGENTS.md).
+- Using the installed package: the docs in `node_modules/cloudinary/docs/` match your
+  installed version and are the source of truth; start with
+  [platform-capabilities](docs/platform-capabilities.md) before assuming a feature exists.
 
+## Support
 
-## About Cloudinary
-Cloudinary is a powerful media API for websites and mobile apps alike, Cloudinary enables developers to efficiently manage, transform, optimize, and deliver images and videos through multiple CDNs. Ultimately, viewers enjoy responsive and personalized visual-media experiences—irrespective of the viewing device.
+- SDK bugs and feature requests: [GitHub issues](https://github.com/cloudinary/cloudinary_npm/issues)
+- Account and platform questions: [Cloudinary support](https://support.cloudinary.com)
 
+## Security
 
-## Additional Resources
-- [Cloudinary Transformation and REST API References](https://cloudinary.com/documentation/cloudinary_references): Comprehensive references, including syntax and examples for all SDKs.
-- [MediaJams.dev](https://mediajams.dev/): Bite-size use-case tutorials written by and for Cloudinary Developers
-- [DevJams](https://www.youtube.com/playlist?list=PL8dVGjLA2oMr09amgERARsZyrOz_sPvqw): Cloudinary developer podcasts on YouTube.
-- [Cloudinary Academy](https://training.cloudinary.com/): Free self-paced courses, instructor-led virtual courses, and on-site courses.
-- [Code Explorers and Feature Demos](https://cloudinary.com/documentation/code_explorers_demos_index): A one-stop shop for all code explorers, Postman collections, and feature demos found in the docs.
-- [Cloudinary Roadmap](https://cloudinary.com/roadmap): Your chance to follow, vote, or suggest what Cloudinary should develop next. 
-- [Cloudinary Facebook Community](https://www.facebook.com/groups/CloudinaryCommunity): Learn from and offer help to other Cloudinary developers.
-- [Cloudinary Account Registration](https://cloudinary.com/users/register/free): Free Cloudinary account registration.
-- [Cloudinary Website](https://cloudinary.com): Learn about Cloudinary's products, partners, customers, pricing, and more.
+See [SECURITY.md](SECURITY.md) for private vulnerability reporting. Keep your
+`api_secret` in server-side code; for client uploads, use the server-signed pattern in
+[Sign a browser upload](docs/sign-browser-upload.md).
 
+## License
 
-## Licence
-Released under the MIT license.
+Released under the MIT license — see [LICENSE](LICENSE). Copyright (c) Cloudinary Ltd.

SECURITY.md

@@ -0,0 +1,37 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Supported |
+|---------|-----------|
+| 2.x     | Yes       |
+| 1.x     | No        |
+
+## Reporting a vulnerability
+
+Report vulnerabilities privately through [GitHub private vulnerability reporting](https://github.com/cloudinary/cloudinary_npm/security/advisories/new) for this repository.
+
+If you cannot use GitHub reporting, contact Cloudinary support at [support.cloudinary.com](https://support.cloudinary.com/hc/en-us/requests/new) and mark the ticket as a security issue.
+
+Use these private channels for anything security-sensitive; public GitHub issues are for regular bugs and feature requests.
+
+## What to include in a report
+
+- The affected package version and Node.js version.
+- A minimal reproduction or proof of concept.
+- The impact you believe the issue has (for example: credential exposure, signature bypass, request forgery).
+- Any suggested remediation, if you have one.
+
+## Response and disclosure process
+
+- We acknowledge reports and keep you informed while the issue is investigated.
+- Fixes are released as patched package versions; the changelog notes security-relevant changes without disclosing exploit details before users can upgrade.
+- Please give us reasonable time to release a fix before public disclosure.
+
+## Security guidance for SDK users
+
+- Your `api_secret` is a server-side credential. Keep it on your server; browsers, mobile binaries, and repositories should only ever hold delivery URLs or short-lived signatures.
+- Provide credentials through the `CLOUDINARY_URL` environment variable rather than hardcoding them.
+- For uploads initiated from a browser or mobile app, generate the signature on your server. See [docs/sign-browser-upload.md](docs/sign-browser-upload.md).
+- For unsigned uploads, use a deliberately restricted [unsigned upload preset](https://cloudinary.com/documentation/upload_presets) ([md](https://cloudinary.com/documentation/upload_presets.md)).
+- Cloudinary platform security documentation: https://cloudinary.com/documentation/solution_overview#security

context7.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/cloudinary/cloudinary_npm",
+  "public_key": "pk_obmsxAKm09jm0si62jh1m"
+}