docs: add agent-readable documentation and repository metadata by const-cloudinary · Pull Request #742 · cloudinary/cloudinary_npm

const-cloudinary · 2026-08-17T13:16:29Z

Ship version-matched Markdown task docs and runnable examples inside the published package so they always match the installed version. Add LICENSE, SECURITY.md, AGENTS.md, and context7.json.

docs/: 12 self-contained task guides, published with the package
examples/: 5 complete runnable scripts
LICENSE: MIT (previously only declared in package.json)
SECURITY.md: private vulnerability reporting and disclosure process
AGENTS.md + CLAUDE.md: contributor guide for coding agents
context7.json: Context7 library ownership verification
README: restructured around install, quick start, and common tasks
package.json: publish docs/, examples/, SECURITY.md, CHANGELOG.md

Brief Summary of Changes

What Does This PR Address?

Are Tests Included?

Yes
No

Reviewer, Please Note:

Ship version-matched Markdown task docs and runnable examples inside the published package so they always match the installed version. Add LICENSE, SECURITY.md, AGENTS.md, and context7.json. - docs/: 12 self-contained task guides, published with the package - examples/: 5 complete runnable scripts - LICENSE: MIT (previously only declared in package.json) - SECURITY.md: private vulnerability reporting and disclosure process - AGENTS.md + CLAUDE.md: contributor guide for coding agents - context7.json: Context7 library ownership verification - README: restructured around install, quick start, and common tasks - package.json: publish docs/, examples/, SECURITY.md, CHANGELOG.md Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

eitanp461 · 2026-08-18T11:18:29Z

@@ -0,0 +1,47 @@
+# Migrate to the v2 API


Shouldn't this file explain when this is necessary/applicable?

eitanp461 · 2026-08-18T11:19:15Z

+                                   // "Cannot read properties of undefined".
+```
+
+Either import the root and use `.v2` everywhere, or (recommended) import `.v2` once and


Wouldn't it be better for this advice to be decisive? Why is it an either/or?

eitanp461 · 2026-08-18T11:20:31Z

+## When to use
+
+Content uploaded by users must be reviewed before it is delivered. Moderation in
+Cloudinary is stateful: assets are `pending` until a decision is recorded, and your


Do we need to explain here what "pending" status means? (It can mean different things for delivery, viewing in the console and maybe other areas)

eitanp461 · 2026-08-18T11:21:36Z

+## Related
+
+- Runnable example: `examples/moderate-upload.js`
+- Hosted reference: https://cloudinary.com/documentation/cloudinary_moderation


Shouldn't this link to the markdown version https://cloudinary.com/documentation/cloudinary_moderation.md?

(Applicable to all links in this PR)

eitanp461 · 2026-08-19T06:42:03Z

+## Pattern: analysis to reviewed metadata
+
+The robust AI workflow is not "run a model, trust the output" — it is:
+
+1. Run AI analysis on the asset (captioning, tagging — for example the
+   [Analyze API](https://cloudinary.com/documentation/analyze_api_guide), subscription required).
+2. Have a human or business rule review/normalize the output.
+3. Write the **approved** values as structured metadata.
+4. Search, route, and deliver based on that metadata.
+
+This keeps model output out of your delivery path until it has been accepted.


What is this based on? Why is there promoting a human in the loop?

eitanp461 · 2026-08-19T06:43:30Z

@@ -0,0 +1,53 @@
+/**
+ * Sign a browser upload on your server.


Why do you need to mention this is from a browser?

Suggested change

* Sign a browser upload on your server.

* Sign an upload on your server.

eitanp461 · 2026-08-19T06:45:40Z

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


What is this key?

- moderate-upload: pending does not block delivery; document statuses, automatic moderator values, and pipe-list ordering - platform-capabilities: restructure into use-case tables; add Start here section covering Skills, MCP servers, CLI, and documentation indexes - get-credentials: new page for provisioning a cloud or signing up - import-and-call: replaces migrate-to-v2 - sign-browser-upload: state signature validity; note signed-parameter rule - upload-image: separate per-request, environment, and chunk size limits - search-and-manage-assets: structured error handling; search syntax reference - use-structured-metadata: normalize model output against the schema - troubleshoot-errors: 423 Processing; platform status page - prefer asset_id for stored references - link documentation as Markdown from docs/ and examples/ Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

const-cloudinary · 2026-08-19T12:12:17Z

All 36 comments addressed. Flagging only where I did not apply it as written:

.md links (moderate-upload.md:68, docs/README.md:44) — everything in docs/ and examples/ ends in .md. README/SECURITY link HTML first with an (md) companion, since they are the npm and GitHub landing pages. Convention stated once in docs/README.md.
migrate-to-v2.md:1, :23 — page removed rather than fixed. Replaced by docs/import-and-call.md.
sign-browser-upload.md:39, :41 — covered in Rules bullet 1 and an inline comment, not at the lines you marked. Inline blocks there duplicated Rules eight lines below.
platform-capabilities.md:12 — "image & video tags" phrasing dropped in the restructure rather than moved.
upload-image.md:40, search-and-manage-assets.md:43 — asset_id adopted, with one caveat kept: cloudinary.url() and api.update have no asset_id form, so a stored asset_id needs a lookup first.
moderate-upload.md:62 — blocking delivery of non-approved assets is described as configurable for the product environment via support.
use-structured-metadata.md:56 — dropped the human-in-the-loop framing entirely; step 2 is now normalize against your schema.

Verified against a live account: all 5 examples and every doc snippet run green; lint clean, 315 unit tests passing.

eitanp461 · 2026-08-19T12:42:29Z

+
+## Automatic moderation
+
+Pass an add-on name instead of `manual` to get an automated verdict:


Mention that these add-ons need to be enabled by the user, and terms of service need to accepted by the user

njb90

Looks great - worth addressing the issue Eitan raised on the exception response structure. The additional examples here will also greatly improve context7.

Report errors the way an SDK user sees them, not as HTTP status codes: - Troubleshooting entries are keyed on the message the SDK actually returns (`Invalid api_key`, `api_secret mismatch`, `Rate limit exceeded`, `You don't have an active subscription for <add-on>`) instead of `401 Unauthorized` / `420 Rate limit exceeded`. - Docs and examples log `message` from the rejection rather than building a string or dumping the whole object, which on Admin and Search calls carries the api_secret. - Note that add-ons must be registered in the console, and that some third-party add-ons also require accepting the provider's terms of service. Also: `upload-large-video.js` no longer downloads the sample video over an explicitly supplied path; a missing file now fails instead of looking like a successful upload. Messages verified against a live cloud. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

const-cloudinary requested review from eitanp461 and njb90 August 17, 2026 13:16

eitanp461 requested changes Aug 19, 2026

View reviewed changes

const-cloudinary marked this pull request as ready for review August 19, 2026 12:12

eitanp461 reviewed Aug 19, 2026

View reviewed changes

eitanp461 approved these changes Aug 19, 2026

View reviewed changes

njb90 approved these changes Aug 19, 2026

View reviewed changes

const-cloudinary and others added 2 commits August 19, 2026 17:38

Merge branch 'master' into docs/agent-readable-docs-and-metadata

db635f1

const-cloudinary merged commit 0956154 into master Aug 19, 2026
10 checks passed

const-cloudinary deleted the docs/agent-readable-docs-and-metadata branch August 19, 2026 15:14

This was referenced Aug 19, 2026

docs: agent-optimize README + add AGENTS.md/CLAUDE.md and IDE pointer files #741

Closed

docs: split transform-and-deliver into image and video pairs #744

Merged

Navigation Menu

Uh oh!

docs: add agent-readable documentation and repository metadata - #742

docs: add agent-readable documentation and repository metadata#742
const-cloudinary merged 4 commits into
masterfrom
docs/agent-readable-docs-and-metadata

const-cloudinary commented Aug 17, 2026

Uh oh!

Uh oh!

eitanp461 Aug 18, 2026

Uh oh!

eitanp461 Aug 18, 2026

Uh oh!

eitanp461 Aug 18, 2026

Uh oh!

eitanp461 Aug 18, 2026

Uh oh!

eitanp461 Aug 19, 2026

Uh oh!

Uh oh!

eitanp461 Aug 19, 2026

Uh oh!

Uh oh!

eitanp461 Aug 19, 2026

Uh oh!

const-cloudinary commented Aug 19, 2026

Uh oh!

eitanp461 Aug 19, 2026

Uh oh!

njb90 left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	* Sign a browser upload on your server.
	* Sign an upload on your server.


		## Automatic moderation

		Pass an add-on name instead of `manual` to get an automated verdict:

Uh oh!

Conversation

const-cloudinary commented Aug 17, 2026

Brief Summary of Changes

What Does This PR Address?

Are Tests Included?

Reviewer, Please Note:

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

const-cloudinary commented Aug 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

njb90 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants