# Configuration

pixtuoid stores its settings in `~/.config/pixtuoid/config.toml` (respecting
`$XDG_CONFIG_HOME`). The file is created on first launch. **Every user setting is
optional** — omit a key to use its default. CLI flags override the file
(e.g. `pixtuoid run --theme dracula`).

## Example

```toml
theme = "cyberpunk"
max-desks = 8
pack-dir = "~/.config/pixtuoid/packs/robot"

# One stanza per pet. Omit the whole section to show all pets with default
# names; use `pets = []` to disable all pets. `name` is optional (shown in
# the pet's hover tooltip). Keep [[pets]] last — it's a table section.
[[pets]]
kind = "cat"
name = "Whiskers"   # optional — omit for "Office Cat"

[[pets]]
kind = "dog"        # name omitted → "Office Dog"
```

## User settings (safe to edit)

| Key | Default | Description |
|-----|---------|-------------|
| `theme` | `"normal"` | Color theme — `normal`, `cyberpunk`, `dracula`, `tokyo-night`, `catppuccin`, `gruvbox`. |
| `max-desks` | auto | Cap desks per floor (≥ 1; `0` is ignored with a warning). If unset, auto-computed from terminal size. Excess agents overflow to additional floors. |
| `pack-dir` | — | Custom sprite pack directory. Supports `~` expansion. See [Custom sprite packs](#custom-sprite-packs). |
| `[[pets]]` | all kinds, default names | One stanza per pet. `kind` (`"cat"`/`"dog"`) is required; `name` is optional (the hover-tooltip label, default `Office Cat`/`Office Dog`). Omit the section for all pets; `pets = []` for none; an unknown `kind` is skipped without affecting other settings. Keep it last (it's a table section). |

## System-managed (don't edit — pixtuoid writes these for you)

| Key | Purpose |
|-----|---------|
| `last-seen-version` | Tracks the highest version you've launched, so the "what's new" popup only fires once per upgrade. Pixtuoid overwrites this on every launch. |

## Themes

Press `t` in the TUI to switch themes with a live preview picker (`j`/`k` or
`↑`/`↓` to navigate); your choice is written back to `config.toml` and persists
across sessions. Override for a single run with `--theme <name>`. Six themes ship
built-in: `normal`, `cyberpunk`, `dracula`, `tokyo-night`, `catppuccin`,
`gruvbox`.

## Custom sprite packs

Create your own character sprites:

```bash
pixtuoid init-pack ./my-pack     # extract skeleton template
# edit the .sprite files in ./my-pack
pixtuoid validate-pack ./my-pack # check for missing animations
pixtuoid run --pack-dir ./my-pack
```

A **robot** pack ships as an example at `crates/pixtuoid/sprites/robot/`. See the
[sprite format docs](../crates/pixtuoid/CLAUDE.md) for palette keys and animation requirements.

## Logging & troubleshooting

The TUI owns your terminal (alternate screen), so runtime diagnostics go to a
**log file** instead of stderr:

| | |
|-----|-----|
| Default path | `~/.cache/pixtuoid/log` (or `$XDG_STATE_HOME/pixtuoid/log` if set) |
| Custom path | set `$PIXTUOID_LOG=/path/to/file` |
| Level | `warn` and above by default; `--log-level debug` or `trace` (or `$RUST_LOG`) raises it |
| Rotation | one generation: past 5 MB the file rotates to `<name>.old` at startup |

Warnings about a misconfigured `config.toml` (unknown theme, bad `[[pets]]`
kind, malformed TOML) are also printed to stderr **before** the office takes
over the screen — scroll back after quitting to see them. If a data source
dies mid-run (e.g. the hook listener), the footer shows a persistent ⚠ warning
and the full error is in the log file.

Crashes are reported separately to `~/.cache/pixtuoid/crash.log`.

Non-TUI commands (`--headless`, `install-hooks`, …) log to stderr directly.
