# set_auto_theme

Change Auto, the account's theme choice that follows the sun or the phone's light or dark setting.

## What it is for

`set_auto_theme` sets Auto, the theme choice that changes with the time of day or with the phone's own light or dark setting. Auto holds up to three themes (dark, normal and, optionally, bright) and a trigger that decides which one shows. The tool changes what Auto holds, for the whole account, and sends nothing to a device. It does not put a device on Auto: that is [set_active](set_active.md) with `auto`.

## What to know first

**Auto is the account's, not a device's.** Every device whose theme is `auto`, and every default that is `auto`, follows it. A device on any other theme does not change. Before it is ever set, Auto is Dark when dark, Daylight otherwise, no bright theme, the phone's setting, no offset.

**Only what is given changes.** The other slots, the trigger and the offset are kept. A call is all or nothing: one theme that is not found saves nothing.

**`sun` switches at civil dusk and dawn where the phone is,** moved by `dusk_offset_min` (minus 60 to plus 60 minutes; a plus value is later into the evening and earlier in the morning). `os` follows the phone's light or dark setting and ignores the offset.

**The bright theme follows the phone's light setting, not a light reading.** With `os`, a phone set to light shows the bright theme when one is set; the normal theme then shows only by the header button. `sun` picks dark or normal (run: the app's tests).

## Generated table

**Tool:** `set_auto_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
Change Auto, the account's theme choice that follows the sun or the phone's light or dark setting. To put a device on Auto use set_active with theme "auto". Saves the account's Auto settings and sends nothing to a device; needs the appearance permission. Only what is given changes, and devices set to Auto follow it. Guide: set_auto_theme.
```

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

| Input | Type | Required | Bounds | Field |
|---|---|---|---|---|
| `dark` | text | no | - | `auto_theme.dark` (ui_prefs) |
| `normal` | text | no | - | `auto_theme.normal` (ui_prefs) |
| `bright` | text or null | no | - | `auto_theme.bright` (ui_prefs) |
| `trigger` | `"sun"` or `"os"` | no | - | `auto_theme.trigger` (ui_prefs) |
| `dusk_offset_min` | integer | no | -60 to 60 | `auto_theme.dusk_offset_min` (ui_prefs) |

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

```text
dark: The theme Auto uses when dark: an id, built-in id or name
normal: The theme Auto uses otherwise: an id, built-in id or name
bright: A theme for bright light: an id, built-in id or name; null = none
trigger: sun = civil dusk and dawn where the phone is; os = the phone's light or dark setting
dusk_offset_min: Whole minutes to shift dusk and dawn, -60 to 60
```

## When to use it, and when not

| The shooter wants | Use | Why |
|---|---|---|
| The look to follow dusk and dawn, or the phone's dark mode, and which themes it uses | `set_auto_theme` | Sets the three slots and the trigger |
| One device to follow Auto, or to stop | [set_active](set_active.md) | `theme: auto` puts the device on Auto; any other theme takes it off |
| One device to show a particular theme | [set_active](set_active.md) | Changes that device's own choice |
| To see what Auto holds now | [list_appearance](list_appearance.md) | Its details give `auto_theme` |
| A new theme to put in a slot | [create_theme](create_theme.md) | Makes it; then name it here |
| To look at a change first | [preview_appearance](preview_appearance.md) | Shows it on a device, saves nothing |

## The inputs

**`dark`, `normal`, `bright`** The theme for each slot: an id, a built-in id or a name that matches exactly one record, built-ins included. The word `auto` is not a slot, and a version in a name (`Dusk@1`) is not found. `bright` as `null` removes the bright slot; `dark` and `normal` take no `null`. A slot not given is kept as it is, or is the default above when Auto was never set.

**`trigger`** `sun` or `os`. A trigger not given is kept.

**`dusk_offset_min`** Whole minutes, minus 60 to plus 60. Kept when the trigger is `os`, and not spoken then. Not given: kept.

An input the tool does not have is dropped, and the reply names it; a call that holds nothing else is refused as having nothing to change ([the connector overview](connector.md)).

## What it returns

**The spoken line:** `Auto now uses Dusk when it's dark and Daylight otherwise, and Night in bright light, switching at civil dusk and dawn shifted by -20 min. Devices set to Auto follow it.` The bright clause appears only when a bright theme is set. The ending is `following the phone's light or dark setting` for `os`, and for `sun` with no offset `switching at civil dusk and dawn`. A theme is spoken by its name; a several-word name is in quotation marks, and a slot whose stored theme was deleted is `a deleted theme` (run).

**The details** hold `auto_theme`: `dark`, `normal` and `bright` as ids (a built-in id or a record id, `bright` `null` when none), `trigger` and `dusk_offset_min`. They are the whole of Auto after the change, not only what was given.

## 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

| The words | The cause | Say to the shooter |
|---|---|---|
| `Tell me what to change about Auto.` | No input was given (inputs the tool does not have count as none) | Ask what to change |
| `No theme called` and the text | A slot names no theme, two, a version, or `auto` | `list_appearance` shows the themes; use the id |
| `Nothing saved —` and the server's reason in quotation marks | The server turned the settings record down | Say that it was not saved |

A value outside a bound (`dusk_offset_min` past 60, or not a whole number), a trigger that is neither `sun` nor `os`, and a `null` for `dark` or `normal` are turned away by the input check; see [the connector overview](connector.md). A device that is not connected or does not answer is not a case here: no device is contacted.

## What it reads and changes

**It reads** the account's themes and its settings record (for the current Auto and to find the ids). No profile, no session, no device.

**It saves** the account's settings record with the key `auto_theme` and no other (the record carries no mark of who saved it; run); the server keeps the settings record's other keys. The whole of Auto is sent, with what was given laid over what was stored. Devices pick it up when they sync (read). Nothing is sent to a device.

**What a device does with it** (run: the app's own tests, `autoslot`, `auto-sun` and `resolve-appearance`; the half hour is read): only a device whose theme is `auto`, by its own choice or by its default, follows Auto. With `sun` it works out dusk and dawn for the phone's last position fix, or, with none, from the Calculator's latitude and the time zone's meridian (good to about half an hour), and with neither it follows the phone's light or dark setting as `os` does, the bright theme included. The header button on the device can hold another slot until the next change.

**It does not** change a theme or a device's choice, and it makes no version.

## Below this page

- [set_active](set_active.md): putting a device or a default on Auto.
- [the connector overview](connector.md), [the family page](appearance.md): themes, Auto, and what the settings record is.

## Worked examples

**1. The first change of Auto: a dark theme and the sun as the trigger**

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

Call:
```json
{"dark":"Dusk","trigger":"sun","dusk_offset_min":-20}
```

Spoken line:
```text
Auto now uses Dusk when it's dark and Daylight otherwise, switching at civil dusk and dawn shifted by -20 min. Devices set to Auto follow it.
```

Details:
```json
{
 "auto_theme": {
  "dark": "fixture-theme",
  "normal": "builtin:daylight",
  "bright": null,
  "trigger": "sun",
  "dusk_offset_min": -20
 }
}
```

Saved a new display preferences record.

**2. A bright-light theme, then none**

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

Call 1:
```json
{"bright":"builtin:daylight"}
```

Spoken line:
```text
Auto now uses Dark when it's dark and Daylight otherwise, and Daylight in bright light, following the phone's light or dark setting. Devices set to Auto follow it.
```

Details:
```json
{
 "auto_theme": {
  "dark": "builtin:dark",
  "normal": "builtin:daylight",
  "bright": "builtin:daylight",
  "trigger": "os",
  "dusk_offset_min": 0
 }
}
```

Saved a new display preferences record.

Call 2:
```json
{"bright":null}
```

Spoken line:
```text
Auto now uses Dark when it's dark and Daylight otherwise, following the phone's light or dark setting. Devices set to Auto follow it.
```

Details:
```json
{
 "auto_theme": {
  "dark": "builtin:dark",
  "normal": "builtin:daylight",
  "bright": null,
  "trigger": "os",
  "dusk_offset_min": 0
 }
}
```

Saved the display preferences record, changed: `auto_theme.bright`.

**3. Back to the phone setting, with an offset kept**

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

Call 1:
```json
{"trigger":"sun","dusk_offset_min":30}
```

Spoken line:
```text
Auto now uses Dark when it's dark and Daylight otherwise, switching at civil dusk and dawn shifted by 30 min. Devices set to Auto follow it.
```

Details:
```json
{
 "auto_theme": {
  "dark": "builtin:dark",
  "normal": "builtin:daylight",
  "bright": null,
  "trigger": "sun",
  "dusk_offset_min": 30
 }
}
```

Saved a new display preferences record.

Call 2:
```json
{"trigger":"os"}
```

Spoken line:
```text
Auto now uses Dark when it's dark and Daylight otherwise, following the phone's light or dark setting. Devices set to Auto follow it.
```

Details:
```json
{
 "auto_theme": {
  "dark": "builtin:dark",
  "normal": "builtin:daylight",
  "bright": null,
  "trigger": "os",
  "dusk_offset_min": 30
 }
}
```

Saved the display preferences record, changed: `auto_theme.trigger`.

**4. Nothing to change**

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

Call:
```json
{}
```

The tool refuses:
```text
Tell me what to change about Auto.
```

**5. A name two themes have, then the id of one of them**

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
{"dark":"Dusk"}
```

The tool refuses:
```text
No theme called "Dusk". list_appearance shows them.
```

Call 2:
```json
{"dark":"fixture-theme-b"}
```

Spoken line:
```text
Auto now uses Dusk when it's dark and Daylight otherwise, following the phone's light or dark setting. Devices set to Auto follow it.
```

Details:
```json
{
 "auto_theme": {
  "dark": "fixture-theme-b",
  "normal": "builtin:daylight",
  "bright": null,
  "trigger": "os",
  "dusk_offset_min": 0
 }
}
```

Saved a new display preferences record.

**6. A slot given a version, and the word for Auto itself**

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 1:
```json
{"dark":"Dusk@1"}
```

The tool refuses:
```text
No theme called "Dusk@1". list_appearance shows them.
```

Call 2:
```json
{"normal":"auto"}
```

The tool refuses:
```text
No theme called "auto". list_appearance shows them.
```

---

[All reference pages](index.md)