Request and review

Placeholders

A placeholder is the file your game uses until a request is fulfilled: a grey box where the lantern keeper will stand, a beep where the door creak will go, a labelled card where the potion icon will sit. Attach one to a request and everyone working on it sees what the real file has to fit. Every plan includes placeholders.

A placeholder isn't a reference. A reference is art to match; a placeholder shows the size, framing and timing the real file must fit, and makers are told not to copy it.

Three ways to get one

Upload a file: the stand-in you already use, of any kind agh previews.
Use the file at its path: the file already at the request's path on the project's repository branch. agh copies it as it is.
Make a quick stand-in: agh makes one in the format the request's path names, with no AI and nothing to pay for:

Request	Stand-in	Formats
Image	A dark hatched card at the spec's `size` (256×256 without one), labelled with the asset's id and size	PNG, JPEG, WebP, SVG
Audio	A soft beep at the start of every second, for the spec's `duration` (1 second without one)	WAV, Ogg Opus
Model	A plain grey box, sphere, capsule or cylinder of the width, depth and height you give in metres, with its origin at the base so it stands on the floor	.glb, .gltf, .obj
Text	One line naming the request and its brief	.txt, .md

agh can't make stand-ins for other formats, such as .fbx, .rbxm or .mp3; upload a placeholder for those.

From the command line

agh request ui.icon.potion --kind image --path ui/icons/potion.png --brief "Red health potion" \
  --spec size=128x128 --stand-in --save-placeholder
agh request char.npc.keeper --kind model --path characters/keeper.glb --brief "Lantern keeper" \
  --stand-in capsule --size 0.6x0.6x1.8 --save-placeholder
agh placeholder ui.banner.title ./banner_temp.png     # attach a file to an existing request
agh placeholder ui.banner.title --placeholder-from-repo
agh placeholder ui.banner.title --remove
agh get ui.icon.potion --which placeholder            # download it

--save-placeholder writes the placeholder at the request's path under the current folder, so the game can load it at once. A file already there is left alone. In a --from file, give an entry placeholder: {source: stand-in, shape: capsule, size: 0.6x0.6x1.8} or placeholder: {source: repository}.

For coding agents

Over MCP, give a request in request_assets a placeholder ({source: "stand-in"}, with shape and size for a model, or {source: "repository"}). The result's placeholders holds a one-hour download link for each, so the agent can save the file at the request's path and keep coding; placeholderProblems says why one couldn't be made. set_placeholder attaches one later, or a file uploaded with start_upload (placeholder: true).

Over HTTP, PUT /projects/{project}/assets/{id}/placeholder takes source (upload, repository or stand-in), with uploadId, fileName and contentType from POST .../placeholder/uploads for an upload, or shape and size for a stand-in model. DELETE takes it off, and GET .../file?which=placeholder downloads it.

In the web app

Admins and developers attach a placeholder from Add placeholder… on each request in Approve, or from the request's page in the Library. Open requests, claims, Library tiles and guest links show it with a dashed Placeholder badge, and review shows it beside the delivery in the place of the file it replaces.

What happens to it

Only admins, developers and agents attach, replace or remove one. Anyone who can see the request can download it, and so can a guest whose link reaches the request.
agh never publishes a placeholder and never lists it in .agh/provenance.yaml.
It counts toward the project's storage until a delivery is accepted. Then agh drops it, and it stops counting. A request that already has an accepted file doesn't take one.
When storage is full, attaching one is refused like any upload; the request itself is still saved.

For agents: this page as Markdown is at /docs/placeholders.md, and the CLI prints it with agh guide placeholders.