Document Cloudinary mu/ and fetch/ folder convention so agents construct valid image URLs

[ooloth]

Why

The build rejects any Cloudinary URL not containing /mu/ or /fetch/ in its path, but the meaning of these folders is undocumented — an agent adding image support will place images in the wrong location and face an opaque validation failure, then may disable the check to unblock itself.

Current state

io/cloudinary/validation.ts rejects Cloudinary URLs that do not contain /mu/ or /fetch/ in their path. There is no comment in the file or in CLAUDE.md explaining what these two path segments represent, why they are required, or how an agent should construct a valid Cloudinary URL when adding image support to a new page or section.

Ideal state

• A comment in io/cloudinary/validation.ts explains: mu/ is the Cloudinary upload folder for owned images managed in this project; fetch/ is used for externally-hosted images proxied through Cloudinary for optimisation.
• The comment states that any image added to the site must be placed in one of these two locations.
• CLAUDE.md echoes this convention so an agent reads it before touching any image-related code.
• An agent knows how to construct a valid Cloudinary URL without needing to read validation source code.

Out of scope

• Changing the folder structure in Cloudinary.
• Changing the validation logic itself.

Starting points

• io/cloudinary/validation.ts — the path validation to annotate; read this first
• .claude/CLAUDE.md — the file to update with the folder convention

QA plan

1. Read io/cloudinary/validation.ts — expect a comment explaining mu/ as the owned-image upload folder and fetch/ as the proxy folder for external images.
2. Read CLAUDE.md — expect a note on the Cloudinary folder convention.
3. Construct a test Cloudinary URL using each folder prefix and confirm it passes the validation.

Done when

validation.ts contains a comment fully explaining the mu/ and fetch/ folder conventions, and CLAUDE.md echoes the constraint so an agent does not need to read validation source code to know where to place images.

[ooloth]

Additional context from a DX gap scan:

The isCloudinaryUrl function in io/cloudinary/validation.ts is also the enforcement point for a constraint not currently documented: the /mu/ folder path is specifically where alt text is managed via the Cloudinary API (images there have structured alt text fetched at build time), and /fetch/ is used to proxy and transform external images (e.g. iTunes artwork). Images outside these two paths will not have alt text enforced — a developer adding an image with a direct Cloudinary URL pointing to a different folder path would get a build-stopping Zod error with no understanding of why the folder restriction exists or what it implies for accessibility.

The comment in validation.ts should cover both the folder convention (already tracked in this issue) and the alt text enforcement implication: images must live in /mu/ or be proxied via /fetch/ specifically because alt text is only managed for assets in those locations.

---

Generated by Claude Code