# Best practices for ids, tags and made-by

Every asset carries a few fields besides its file: an id, a kind, tags, where players see it, and how it was made. Asset Goes Here uses them to group the Library, decide who can claim what, scope guest links and fill in the AI disclosure. Choosing them well from the first request keeps a project easy to work in when it reaches hundreds or thousands of assets. This page says what each field is for and how to choose values for it. The second half covers strings files and translations.

## The short version

| Field | Use it for | Example |
| --- | --- | --- |
| `id` | Where the asset sits in the project: area, then subject, then the one asset | `char.mira.portrait_worried` |
| `kind` | What kind of file to make | `image`, `audio`, `strings` |
| Tags | What the asset is and who it is for, across areas. Queues, reservations and guest links match them | `role=portrait`, `character=mira` |
| `used_in` | Where players see it | `game`, `store`, `marketing` |
| Provenance and `made_by` | How the file was made, and by what or whom | `ai-assisted`, `Flux, retouched by Jane` |

As a rule of thumb, the id says where an asset lives, tags say what it is and who it is for, and made-by says who or what made it.

## Ids and prefixes

An id is lowercase words of letters, digits and underscores, separated by dots, such as `card.ember_wolf.art`. It can't be changed once the asset exists, and it doesn't have to match the file's path, so choose it for how you want to browse the project rather than to copy your folders.

Read an id from left to right as a path through the project:

- **The first part is the area**, such as `char`, `card`, `ui`, `sfx`, `music`, `localization` or `marketing`.
- **The middle parts narrow it to one subject**: a character, a card, a screen, a map.
- **The last part is the asset itself**: an expression, a state, a size.

### What prefixes drive

- **Library groups.** The Library offers the groups one level below the prefix you're in, with how many assets each holds. Under `char.` you pick `mira.` or `bram.`; under `char.mira.` the tiles are labelled by the rest of their id, such as `portrait_worried`, and crumbs take you back up.
- **Exact counts.** On the **By kind & status** side of the filter panel, a prefix that ends at a dot combines with kind, status, how the file was made and whether it is published, and every value shows how many assets it lists. That makes a prefix the way to answer "how many of Mira's portraits still need review?" at a glance.
- **Queues and handoffs.** `agh next`, `agh list`, `agh brief`, `agh openai` and guest links all take `--prefix`, so one prefix hands a whole character or screen to one artist or tool.
- **Ids Asset Goes Here makes for you.** A translation's id is its source's id plus the language, such as `ui.menu.strings.fr`, and an image variant's is the master's plus its name, such as `char.mira.portrait_worried.thumb`. They land in the same group as the asset they come from.

### Good habits

- **Give siblings the same shape.** Use `char.<name>.<asset>` for every character, rather than `char.mira_worried` for one and `char.bram.angry` for another. Groups only line up when the depth and order match.
- **Leave out what changes.** Status, kind, who is making it and version numbers don't belong in an id. Asset Goes Here tracks all of them, and they would make the id wrong later.
- **Plan for growth.** If a group could grow past a screenful, give it another level now, such as `card.base.ember_wolf` and `card.expansion_1.frost_hare`, since ids can't be renamed later.
- **Adopted files** get their id from their path, so `art/cards/Ember Wolf.png` becomes `art.cards.ember_wolf`. Run `agh adopt --dry-run` to see the ids first, and adopt through the API with an `id` for each file when you want a different shape. See [Adopting files already in your repository](/docs/adopt).

## Tags

A tag is a `key=value` pair, such as `role=card_art`. Keys and values are stored in lowercase with spaces trimmed from the ends. An asset has one value per key and at most 20 tags, with keys up to 64 characters and values up to 128.

### Keys worth having

| Key | What it says | Example values |
| --- | --- | --- |
| `role` | What the asset does in the game | `card_art`, `portrait`, `backdrop`, `icon`, `dialogue`, `bark`, `lore`, `ui_label` |
| `character` | Who it shows, or who speaks or voices it | `mira`, `bram` |
| `creature`, `location`, `faction` | Your game's own nouns | `ember_wolf`, `kesterholm` |
| `act`, `chapter`, `milestone` | When it is needed | `act_1`, `demo`, `launch` |

Use `role` rather than wishing for more kinds. A kind tells the maker what file to produce (`image`, `audio`, `text`, `strings`, `model` or `file`); `role` tells them what it is for. A portrait and a backdrop are both images, and dialogue and UI labels are both strings.

A few keys mean something to Asset Goes Here itself:

- `style` names the asset's style guide. It is set from the request's style; see [Style guides](/docs/style-guides).
- `disclosure` files an asset under another category in the AI disclosure, such as `disclosure=story-and-writing`; see [Approving, reviewing and publishing](/docs/review).
- `variant` is added to each image variant with its name; see [Image variants](/docs/image-variants).

### What tags drive

- **Claim queues.** `agh next --tag role=card_art`, `agh openai --tag`, and the filters on **Open requests** let an artist or tool take only the work that fits them.
- **Reservations and claim limits.** On Team and Enterprise, an admin can reserve every request tagged `character=bram` for Bram's voice actor, or limit a tool to `role=icon`. They match requests made later too, so tag new requests the same way from the start. See [Reservations](/docs/reservations) and [Claim limits](/docs/claim-limits).
- **Join request openings** can reserve matching work by tag. See [Join requests](/docs/join-requests).
- **Guest links** can reach every request with a tag, now and later. See [Hiring outside help](/docs/hire).
- **The By tag side of the Library's filter panel** lists each key with its most used values and how many assets in the project have each one.
- **Translations and variants inherit them.** A translation takes its source's tags, and a variant takes its master's.

### Good habits

- **Agree on a short list of keys before the first batch**, and write them down where your coding agents read, such as your repository's `AGENTS.md`. **Edit tags** in the Library suggests the keys and values other assets already use, so pick from it rather than typing a near-copy.
- **Keep values to a short list.** A value that only one asset has is really an id. The By tag side shows a key's 200 most used values, so a key with a different value on every asset is hard to use there.
- **Spell values one way**: `card_art`, not `card art` or `cards`. Case doesn't matter, since tags are stored in lowercase, but spaces, underscores and plurals do.
- **Don't tag what is already a field.** Kind, status, provenance, `used_in` and a translation's language each have a filter of their own, so a tag such as `lang=fr` or `ai=yes` would only drift out of step with them.
- **Fix tags in place.** Admins and developers change one asset's tags with **Edit tags** in the Library, or with `agh mark <id> --tag key=value --remove-tag oldkey`. A revision can change tags too.

## A prefix, a tag, or both?

The Library's filter panel has two sides that never combine, so every count it shows is exactly how many assets a pick lists:

- **By kind & status** narrows by id prefix, kind, status, how the file was made and whether it is published.
- **By tag** picks one tag value, or one made-by name, at a time, counted across the whole project.

Choose with that in mind:

- When you'll want to see a group together with its progress, such as which of Act 1's portraits still need review, make the group part of the id.
- When you'll want to gather things from different areas, such as everything for Bram (his portraits, his barks, his voice lines), or a queue or reservation should match it, make it a tag.
- When it is both, use both. `char.bram.portrait_angry` tagged `character=bram` and `role=portrait` is the usual case, not a duplicate.

The CLI and API combine every filter freely, such as `agh list --prefix char.bram. --tag role=portrait --status delivered`. The panel keeps the two sides apart only so its counts stay exact.

## Where players see it: used_in

`used_in` is `game` (the default), `store` or `marketing`. Steam's AI disclosure covers store pages and marketing as well as the game, and the disclosure report files store and marketing material by this field. Set it on capsule art, store screenshots, trailers and press images when you request them.

## How it was made: provenance and made_by

Provenance is `human`, `ai-assisted`, `ai` or `unknown`. `ai-assisted` covers a person reworking AI output and AI reworking a person's work. `made_by` is free text naming the tool, model, service or person. Both are written to `.agh/provenance.yaml` with each published file, and the AI disclosure lists every distinct `made_by` behind AI and AI-assisted files, so the names you choose are the names the public may read.

- **Reuse a name.** `agh made-by list` (MCP `list_made_by`) shows the names your files already use, most used first, and the By tag side of the Library lists them with counts. A name that differs from one in use only in capitals, spaces or punctuation is saved in the existing spelling.
- **Be specific.** Name the tool or model, such as `OpenAI image generation` or `Flux 1.1 Pro`, rather than `AI`. Name a person by the name they want credited. For work hired outside Asset Goes Here, name the person and, if you like, the service, such as `Jane Doe via Fiverr`; a guest link uses its own name this way.
- **Say both for mixed work.** A file a person touched up is `ai-assisted`, with a made-by such as `Flux, retouched by Jane` or `DeepL, edited by Jeanne`.
- **Keep notes out of it.** A note in place of a name, such as where a file was restored from, is refused. Post it in the asset's conversation instead.
- **Correct it at review.** **Record as** on the review page, or `agh review <id> --accept --provenance ai-assisted --made-by "..."`, fixes how a delivery was made before you accept it. `agh mark <id> --provenance ... --made-by ...` (MCP `set_provenance`) fixes it later.
- **Merge spellings.** `agh made-by rename "ChatGPT ImageGen" "OpenAI built-in image generator" --to "OpenAI image generation"` (MCP `rename_made_by`) merges names across the project. Publish your disclosure again afterwards if it is public.
- **Adopted files** are `unknown` unless you say otherwise or the repository's provenance file does. Give `--provenance` and `--made-by` when you adopt a folder you know about, and fix the rest as you find out.

## Strings files and translations

Writing comes in two kinds. Use `strings` for keyed lines the game looks up, such as UI labels, item names, barks and dialogue by id. Use `text` for a whole piece of writing read as one, such as a lore entry or a store blurb. Tag either with a `role`, such as `role=dialogue` or `role=ui_label`. [Writing and translations](/docs/translations) lists the formats each kind reads.

### How much goes in one file

Each strings file is one asset, with its own claim, review, conversation and one translation per language. Size the files around how the writing gets done:

- **One file per unit a writer owns**: a map, a chapter, a quest line, or a group of related screens. A reviewer can read it in one sitting, and different writers or languages can work on different files at once.
- **Not one file per line or per page.** That turns one script into hundreds of assets, each claimed and reviewed on its own, and every language multiplies them.
- **A large file is fine.** You don't have to reopen the whole file to change a few lines: a revision can name just the keys to change or add. Split a file only where different people, languages or release dates pull it apart.

### Keys

- **Name keys after where the line appears**, from general to specific, such as `menu.settings.audio_volume` or `comic.the_village_p3.panel_2.balloon_1`. Code looks lines up by key and translations are matched by key, so a renamed key counts as one key removed and another added in every language.
- **Keep the file in reading order.** `agh strings` and the key picker on **Ask for a new version** list keys in file order, so a file in order reads like a script.
- **Give each line its context in a comment**: who speaks, where it shows, how much room it has. Translators see these comments beside the line in `agh strings`. In PO they are `#.` or `#` lines.
- **Set `max_length` in the spec** when lines must fit a box, such as `--spec max_length=45`. Review then flags longer lines, counted in characters as players see them.
- **Keep placeholders and markup in the text**, such as `{name}`, `%s` or `[b]`. Review flags a translation whose placeholders differ from the source's.

### Revise keys, not files

To change a few lines, ask for a new version of just those keys:

```text
agh revise localization.story.act_1 --note "Mira is angrier here; she has just found the cart empty" \
      --key comic.the_village_p3.panel_2.balloon_1 --key comic.the_village_p3.panel_3.caption
```

On the web, open the asset in the Library and choose **Ask for a new version**. For a strings file the form lists every key with its current text, in file order, with a search box that matches the key or the text; tick the lines, or choose **+ Add a new key**. The writer reads those lines and their neighbours (`agh strings <id> --around 1`), and the reviewer is warned if a key outside the list changed or a chosen key was left alone. See [Revising an asset](/docs/revise).

### Translations

- **Put the language in the path**, such as `locale/en/menu.po` or `i18n/en.json`. Asking for translations with `--locales fr,es` then puts each one at the same path in its language, with an id such as `ui.menu.strings.fr`. For any other layout, give `--locale-path`.
- **Use a column per language only when your engine wants one.** Godot and Roblox can read a single CSV with a `keys` column and one column per language; Asset Goes Here keeps each column as its own translation. Otherwise keep one file per language.
- **Let the language be the `locale` field, not a tag.** `agh next --locale fr`, the Library's language chips and per-language guest links all use it.
- **Accept the source first.** A translation can't be claimed until its source has an accepted file. Once a new version of the source is accepted, each translation reopens for only the keys that were added, changed or removed.
- **Record how each translation was made**: an untouched machine translation is `ai`, a person's edit of one is `ai-assisted` with a made-by such as `DeepL, edited by Jeanne`, and a translator's own work is `human`. The AI disclosure counts translations per language.

### A worked example: dialogue for a comic

A story game shows its scenes as comic pages, with a balloon or caption per line. Its dialogue is organized like this, and it has held up well:

- **One PO file per map**, such as `localization/en/story/act_1.po`, with Spanish at `localization/es/story/act_1.po`. Each map is one strings asset, `localization.story.act_1`, tagged `role=dialogue` and `act=act_1`, and its Spanish is `localization.story.act_1.es`.
- **One key per balloon or caption**, such as `comic.the_village_p3.panel_2.balloon_1`, with a comment saying where it shows and who speaks: `#. panel 2 · Mira`. The keys are in page, panel and balloon order, so the file reads top to bottom like the script.
- **Layout lives in the game, words live in the file.** Each page's layout in the engine points only at keys, so rewriting a line never touches code. A new balloon is a new key in Asset Goes Here and a layout change in the game.
- **One file per page was tried and dropped.** It meant hundreds of assets for one act, each claimed and reviewed on its own. One file per map, with revisions by key, keeps the work small without the overhead.

Rewriting a scene then goes like this:

- **Ask for a new version of the scene's keys**, with a note saying what should change and, for a new scene, who speaks and what happens. Use **+ Add a new key** for any new balloon.
- **The writer** reads just those lines and the ones around them, and delivers the file.
- **Review** warns if the delivery changed a line nobody picked, or left a picked line as it was. Accept it.
- **The Spanish file reopens** for only the keys that changed. Review flags missing keys, broken placeholders and lines left in English.
- **Publish** sends both languages in one pull request.
