# create_theme

Make a new theme of the shooter's as a copy of a built-in, one of their themes, or an older version, under a name they give.

## What it is for

`create_theme` makes a new theme of the shooter's from a copy of an existing one: a built-in, one of their own, or one of its older versions. The copy has a new name and its own history, which starts at version 1. It is how a built-in look becomes editable. The tool changes no existing theme and does not make the copy active on any device ([the family page](appearance.md)).

## What to know first

**The copy is not used anywhere until a device is told to.** The reply says so. `set_active` puts it on a device or makes it the default; `edit_theme` changes it.

**`from` picks the source: its newest version unless one is written.** Give a built-in or an own theme by id or name, or `<id>@<version>` for an older live version. A name two records share is answered as no such theme; give the id.

**The name is trimmed, and nothing else is checked.** A name that another theme or a built-in already has is accepted (neither can then be reached by name), and a name of spaces is saved as an empty name.

**The copy must pass the theme rules.** A source whose background picture is no longer in the account is refused, naming `list_assets`.

## Generated table

**Tool:** `create_theme` · **Family:** Appearance · **Scope:** `appearance` · **Save scope:** none · **Changes:** records · **Runs:** no solver work in the connector

**Description** (what the connector sends to an assistant, word for word):

```text
Make a new theme of the shooter's as a copy of a built-in, one of their themes, or an older version, under a name they give. To change an existing theme use edit_theme; set_active puts the new one on a device. Saves it as version 1; needs the appearance permission. A name another theme has is accepted, and then only the id finds either: ask for the name, do not invent one. Guide: create_theme.
```

**Inputs** (3; read from the input schema the connector sends):

| Input | Type | Required | Bounds | Field |
|---|---|---|---|---|
| `from` | text | yes | - | - (selects a record) |
| `name` | text | yes | 1 to 60 characters | `name` (theme) |
| `request` | text | yes | 1 to 300 characters | `note` (theme) |

**Sent with the inputs** (each input's own description, word for word; an input not listed is sent without one):

```text
from: What to copy: a built-in id, a theme id or name (its latest version), or "<id>@<version>"
name: The new theme's name; ask for it
request: The shooter's request in their own words; stored as the version's note, so "undo that" can find it
```

## When to use it, and when not

| The shooter wants | Use | Why |
|---|---|---|
| A new look, or an editable copy of a built-in or of a look they like | `create_theme` | A new theme of their own, version 1 |
| An existing own theme changed | [edit_theme](edit_theme.md) | Saves its next version; no second theme |
| An old look of one theme back as that theme | [restore_version](restore_version.md) | History of the same theme, no copy |
| The new theme on a device | [set_active](set_active.md) | This tool leaves every device as it was |
| A new arrangement of the Calculator | [create_layout](create_layout.md) | A layout is not a theme |
| To see the themes and their ids first | [get_theme](get_theme.md) | Reads one theme in full |

Ask for the new theme's name if the shooter has not said one. A name that is already taken is saved, so check `list_appearance` first when the name matters.

## The inputs

**`from`** selects the source theme (see "What to know first"). A source written `<id>@<version>` must have that live version: a deleted version, or one that never existed, is answered as no such theme (run, with a stored version that was deleted).

**`name`** is the new theme's name, trimmed of spaces at both ends before it is saved. Nothing else is checked: no other theme or built-in is compared with it.

**`request`** is the shooter's words, stored as the new theme's first note.

## What it returns

On success the spoken line is `Created theme '<name>' from <source>. Nothing uses it yet; set_active puts it on a device.` The name is the one just given. The source is a built-in's name, or an own theme's stored name with its version (`'Dusk' v2`); a stored name of several words is spoken in quotation marks with the stored-text note (run).

| Key | Holds |
|---|---|
| `theme_id` | The new theme's id: pass it to `set_active` and `edit_theme` |
| `version` | `1`, or the number the server gave if it renumbered the save |
| `based_on` | The source: a built-in's id, or `<id>@<version>` of the version copied |

## Worked examples

Every example below was run by the documentation generator against a made-up account, never a real one. Numbers are rounded to three places; generated ids and times are shown as placeholders. Two things are printed more briefly than the tool sent them, and nothing else is changed. A list of plain values stands on one line, whole up to 12 entries (a longer one, and a list of objects past 3, ends with a count of the rest). A reply that puts stored text in quotation marks also carries a note saying so, which an example leaves out and marks instead; no reply below carried it.

## When it refuses

| Refusal | Cause | Tell or ask the person |
|---|---|---|
| `No theme ` followed by `from` as given and `. list_appearance shows the themes.` | No theme matches, two records have that name, or the written version is not a live one | Look at `list_appearance`; use the id |
| `Nothing saved — ` and the rules the copy breaks, joined with `; ` | The source does not pass the theme rules | Say nothing was made |
| `Nothing saved — ` and then `there's no background image ` and the reference, ` in your account; list_assets shows what is there.` | The source's picture is not in `list_assets`; the check is on the copy, so a source whose stored picture left the account is refused whatever name is given (run), and the reference is spoken quoted and cut to 40 characters | Offer `edit_theme` on the source with another background first |
| `Nothing saved — ` and the server's reason in quotation marks | The server turned the save down | Say nothing was made |

The input check turns away a name of no characters or of more than 60, a request of none or of more than 300, and a missing `from`, `name` or `request`; the rule is on [the connector overview](connector.md). An input the tool does not have is dropped, and the reply names it (since 2026-10-15). On a link without the scope `appearance` the tool is not offered (run).

## What it reads and changes

**Reads** the account's themes (to find the source) and, when the copy has an image background, the list of uploaded pictures. **Saves** one new theme: a new id, version 1, `source` Claude, the request as note, `based_on` the source's version. Every other member of the content is copied from the source as it is. It changes no existing theme, makes none active, and sends no command to a device.

## Below this page

- [list_assets](list_assets.md): the pictures an image background can use.
- [the connector overview](connector.md), [the family page](appearance.md)

## Worked examples

**1. A copy of a built-in theme**

Starting point: one theme and one layout of the shooter's, and one phone. Link scopes: `read`, `appearance`.

Call:
```json
{"from":"builtin:dark","name":"Night copy","request":"night copy"}
```

Spoken line:
```text
Created theme 'Night copy' from Dark. Nothing uses it yet; set_active puts it on a device.
```

Details:
```json
{
 "theme_id": "(a generated id)",
 "version": 1,
 "based_on": "builtin:dark"
}
```

Saved a new theme at version 1.

**2. A copy of one of the shooter's themes, by its name**

Starting point: one theme and one layout of the shooter's, and one phone. Link scopes: `read`, `appearance`.

Call:
```json
{"from":"Dusk","name":"Dusk warm","request":"a warmer one"}
```

Spoken line:
```text
Created theme 'Dusk warm' from 'Dusk' v1. Nothing uses it yet; set_active puts it on a device.
```

Details:
```json
{
 "theme_id": "(a generated id)",
 "version": 1,
 "based_on": "fixture-theme@1"
}
```

Saved a new theme at version 1.

**3. A copy of an earlier version**

Starting point: one theme whose stored versions are 1 (named Dawn, saved in the app), 2 (deleted), 3 (named Dusk, saved by Claude with the note larger text) and 4 (named Dusk, saved in the app); one layout at versions 1 and 2, the second with a title on its first section; and one phone. Link scopes: `read`, `appearance`.

Call:
```json
{"from":"Dusk@3","name":"Dawn two","request":"the third one"}
```

Spoken line:
```text
Created theme 'Dawn two' from 'Dusk' v3. Nothing uses it yet; set_active puts it on a device.
```

Details:
```json
{
 "theme_id": "(a generated id)",
 "version": 1,
 "based_on": "fixture-theme@3"
}
```

Saved a new theme at version 1.

**4. A name another theme has, and a name a built-in has**

Starting point: a theme at version 2, a layout, one uploaded image of 48 kB, two share links (one for the theme, and a later one for the layout that was stopped) and one phone. Link scopes: `read`, `appearance`.

Call 1:
```json
{"from":"Dusk","name":"Dusk","request":"second Dusk"}
```

Spoken line:
```text
Created theme 'Dusk' from 'Dusk' v2. Nothing uses it yet; set_active puts it on a device.
```

Details:
```json
{
 "theme_id": "(a generated id)",
 "version": 1,
 "based_on": "fixture-theme@2"
}
```

Saved a new theme at version 1.

Call 2:
```json
{"from":"fixture-theme","name":"Dark","request":"named like a built-in"}
```

Spoken line:
```text
Created theme 'Dark' from 'Dusk' v2. Nothing uses it yet; set_active puts it on a device.
```

Details:
```json
{
 "theme_id": "(a generated id)",
 "version": 1,
 "based_on": "fixture-theme@2"
}
```

Saved a new theme at version 1.

**5. A name of spaces**

Starting point: one theme and one layout of the shooter's, and one phone. Link scopes: `read`, `appearance`.

Call:
```json
{"from":"Dusk","name":"   ","request":"blank name"}
```

Spoken line:
```text
Created theme '' from 'Dusk' v1. Nothing uses it yet; set_active puts it on a device.
```

Details:
```json
{
 "theme_id": "(a generated id)",
 "version": 1,
 "based_on": "fixture-theme@1"
}
```

Saved a new theme at version 1.

**6. A source with two themes of one name, then one by its id**

Starting point: three themes of the shooter's (two named Dusk, and one named Daylight, as a built-in theme is), three layouts (two named Bench, and one named Compact, as a built-in layout is) and one phone. Link scopes: `read`, `appearance`.

Call 1:
```json
{"from":"Dusk","name":"Dusk warm","request":"a warmer one"}
```

The tool refuses:
```text
No theme Dusk. list_appearance shows the themes.
```

Call 2:
```json
{"from":"fixture-theme-b","name":"Dusk warm","request":"a warmer one"}
```

Spoken line:
```text
Created theme 'Dusk warm' from 'Dusk' v1. Nothing uses it yet; set_active puts it on a device.
```

Details:
```json
{
 "theme_id": "(a generated id)",
 "version": 1,
 "based_on": "fixture-theme-b@1"
}
```

Saved a new theme at version 1.

**7. A version the theme does not have**

Starting point: one theme and one layout of the shooter's, and one phone. Link scopes: `read`, `appearance`.

Call:
```json
{"from":"Dusk@9","name":"Dusk nine","request":"number nine"}
```

The tool refuses:
```text
No theme Dusk@9. list_appearance shows the themes.
```

---

[All reference pages](index.md)