# Style guides

A style guide holds a look or a voice once, so each request can name it instead of repeating it. Without one, every comic portrait in a project starts with the same long "Bold hand-inked comic illustration…" paragraph, and changing the look means editing every brief. With one, the brief says only what the asset is, such as "Maren at the hall door, holding the ledger", and the request names `living_comic`. Style guides come with every plan.

## What a style holds

A style has an id (one lowercase word with underscores, such as `living_comic` or `cartoon`), a name and an optional description. It has a section for each area it covers:

| Area | Covers | Holds |
| --- | --- | --- |
| Images | image requests | the look in words, do and don't notes, reference assets |
| Writing | text and strings requests | the voice in words, do and don't notes, sample assets |
| Audio | sound effects, music and narration | the sound in words, do and don't notes, reference clips |
| Models | 3D models | shapes, shading and materials in words, notes, reference models |

References are assets already in the project, up to 12 per section. Pick the ones that show the style best, such as accepted portraits for images.

A section can also hold up to 12 samples: images, clips or lines that show the style but aren't project assets. Picking a style in a [style study](/docs/style-studies) saves its kept tiles here. Samples count toward the version like words and references.

Each section has its own version. Saving a change to its words, notes or references makes the next version, and the old one is kept under **History**. Changing only the Writing section leaves Images at its version, so only writing is marked out of date.

## Add and edit styles

Admins and developers manage styles under **Project › Style guides** on the web page. **New style** opens the editor: tick each area the style covers and fill it in. **Edit** on a style changes it. Artists can read styles there too.

They can also save a style from a file with `agh style save`, and coding agents connected to Asset Goes Here as an admin or developer can save one with the `save_style` tool. Both take the same fields as the editor:

```yaml
# living_comic.yaml
id: living_comic
name: Living comic
description: Portraits and backgrounds in the comic chapters
default: true
sections:
  - area: images
    prompt: Bold hand-inked comic illustration with heavy, irregular black brush contours
    do: [Crosshatch the shadows]
    dont: [Soft gradients, Airbrushed skin]
    references: [character.maren.bust_portrait, location.aberlis_hall.day]
  - area: writing
    prompt: Grim and terse; short sentences.
    samples:
      - label: Ward
        text: It burns. Ward it.
```

```text
agh style save --from living_comic.yaml
agh style show living_comic --format json > living_comic.json   # edit it, then save it back
agh style save --from living_comic.json
```

A section in the file replaces that area's words, notes and references, and a field left out of a section keeps what it had. Areas the file doesn't mention keep their sections; `remove: [audio]` takes one out. A project that needs several looks, such as comic portraits and an illustrated map, keeps one style for each.

One style can be the **project default**. New requests that name no style get the default, for the areas it covers. Making a style the default stops any other being it.

Deleting a style leaves the assets that named it as they are: they keep their `style` tag and what they were made with.

## Name a style on a request

A request names its style with `style`. Asset Goes Here keeps it as the request's `style` tag.

```text
agh request comic.maren.door --kind image --path art/maren/door.png \
  --brief "Maren at the Aberlis hall door, holding the ledger" --style living_comic
```

In a `--from` file, give each entry `style: living_comic`, or pass `--style` once for every entry that has none. Coding agents pass `style` to `request_assets`, and `list_styles` shows the project's styles.

- Leave `style` out and the request gets the project's default style, if there is one and it covers the request's kind.
- `--style none` asks for no style, even when there is a default.
- A style that doesn't exist is refused, with the ids that do.
- A `style` tag given among the tags, as some projects did before style guides, stays an ordinary tag. It counts as a style only when a style has that id.

Reviewers can change a request's style under **Approve**: **Edit** has a style picker. Changing the `style` tag anywhere else, such as in the Library, changes it too.

## Name a style on a revision

A revision can move an asset to another style, or take its style off. In the Library, **Ask for a new version** has a **Style** picker: it starts on the asset's own style, and lists the other styles that cover its kind and **No style**. The new version is made in the style picked, with its words and references.

```text
agh revise location.aberlis_hall.night --note "Redo in rendered ink" --style rendered_ink
agh revise location.aberlis_hall.night --note "Drop the style" --style none
```

Coding agents pass `style` to `request_revision`. Left out, the asset keeps its style.

## Attach a style to an existing asset

An asset already in the Library can be put in a style without asking for a new version, such as art accepted before the project had style guides. Open it in the Library: its **Style** row says **none · Attach a style**, and picking a style attaches it at once. **Change** and **Remove** change it later. Admins and developers attach styles, on every plan.

```text
agh mark location.aberlis_hall.day --style living_comic
agh mark location.aberlis_hall.day --style none     # take it off
```

Coding agents call `set_style`. An attached style counts the accepted file as in the style's current version, so the asset shows **attached** rather than **made with**, and goes out of date like any other when the style moves on. On an open request, the same call changes the style its maker gets.

To see which style an image fits before attaching one, [compare it with the project's styles](/docs/style-checks#compare-an-image-with-every-style).

## What the maker gets

The style travels with the request. `agh show`, `get_asset` and the claim tools return it as `style`: the style's id and name, the area, the version, its words, its do and don't notes, and its references. Claiming a request gives the newest version of the style, so a request approved before the style changed is made in the style as it is now.

`agh openai` puts the style's words and notes in its prompt, before the brief.

When a file is delivered, Asset Goes Here records the style version it was made against.

## Out of date

When a style moves on, the assets made with an earlier version are out of date. They show **Style out of date** in the Library, and their page says which version they were made with. On **Style guides**, each style lists its out-of-date assets, and **Request redraws** asks for a new version of each one with `agh revise`'s note "Redo in living_comic v3". Each current file stays until a new one is accepted.

From the CLI:

```text
agh style list                     # styles, their areas and versions, and how many assets name each
agh style show living_comic        # the words, notes and references
agh style save --from style.yaml   # create or change a style (admins and developers)
agh style out-of-date living_comic # assets made with an older version
agh revise comic.maren.side --note "Redo in living_comic v3"
```

## API

| Route | Who | What |
| --- | --- | --- |
| `GET /projects/{id}/styles` | members | Every style, with how many assets name it. |
| `GET /projects/{id}/styles/{style}` | members | One style with its history. |
| `PUT /projects/{id}/styles/{style}` | admins, developers | Creates or changes a style: `name`, `description`, `default`, `sections` (each with `area`, `prompt`, `do`, `dont`, `references` and `samples`) and `remove` (areas to take out). `agh style save` and the MCP tool `save_style` call it. |
| `DELETE /projects/{id}/styles/{style}` | admins, developers | Deletes a style. |
| `GET /projects/{id}/styles/{style}/out-of-date` | members | Assets made with an earlier version, with `madeWith` and `current`. |
| `PATCH /projects/{id}/assets/{asset}` with `style` | admins, developers | Attaches a style to the asset, or takes it off with `none`. |
| `POST /projects/{id}/assets/{asset}/revise` with `style` | admins, developers, agents | Asks for a new version in that style. |
