[manojkrgupta]

What this adds

A new page, Organize repositories and access with folders (platform/administration/iam-organizations/manage-folders.md), plus a link to it from the IAM overview's "Organizations and folders" section.

Folders appear in one sentence of the IAM overview and in the Custom Assembly overlay docs, but nothing explains:

• How to create and manage a folder.
• How a repository in a folder is addressed when you pull it.
• How to scope a pull token or role-binding to a folder, and how access set at the organization reaches into folders.

Customers have asked how to pull from cgr.dev/<org>/<folder>/<image> with a single pull token, and the docs don't answer it.

What the page covers

• Managing folders with chainctl iam folders (create, list, describe, update, delete).
• The path rule: cgr.dev/<org>/<folder>[/<folder>…]/<repository>:<tag>. The last segment is always the repository. Pulling never creates folders.
• How access works: roles apply downward. A pull token or role-binding at the organization covers every folder, and one at a folder covers only that folder and the folders inside it.
• A current Custom Assembly limitation in folders: builds there can only use packages from images in that folder.
• Troubleshooting for failed pulls from a folder.

How I checked the behaviour

I checked the path rule and the downward access rule against the registry and IAM implementation: how a repository path is split into its group path and repository name, and how a role-binding's location is matched against the resource's location. I checked the command syntax against the current chainctl source.

Please check

• Custom Assembly limitation. The paragraph in "Custom Assembly in folders" describes current behaviour. Please confirm with the product owner that it's still accurate, and whether to keep it on the page or link to a known-issues page instead.
• Generated chainctl reference. chainctl iam folders create exists, but the generated reference (chainctl-docs/chainctl_iam_folders*.md) doesn't list it yet. I left the generated files alone, since they come from the autodocs workflow.
• Not tested end to end: the artifact-manager troubleshooting step, and chainctl images repos list --parent=<folder> output against a real folder.
• Console steps. The page covers chainctl only. Happy to add Console steps if you want them.

Weight 15 places the page between the IAM overview (10) and "How to manage IAM organizations" (20).

🤖 Generated with Claude Code

[vercel]

@manojkrgupta is attempting to deploy a commit to the Chainguard Team on Vercel.

A member of the Team first needs to authorize it.