# Build an AOW Workshop theme with Codex

A companion to **Systems for Humans — Omarchy Fieldwork, OMA-02**. Production experiment recorded 11 September 2026. Local review edition; this episode has not been published.

The useful connection is **source palette → installed templates → generated application configuration → visible interface**. We built a light theme, made the selected menu row stronger, tested a shell restart, and restored the original theme.

## 1. Check your installation

This experiment used a disposable VM derived from our previous widget lab, not a clean stock installation. Package versions were Omarchy 4.0.2-1, Hyprland 0.56.2-1, Foot 1.27.0-2 and Neovim 0.12.5-1. The bundled `/usr/share/omarchy/version` contained `4.0.0.alpha`; this discrepancy is preserved in the evidence. Other releases can have different commands and files.

```bash
pacman -Q omarchy hyprland foot neovim
omarchy theme current
ls /usr/share/omarchy/default/themed
```

Read the [official theme manual](https://omarchy.org/manual/making-your-own-theme/) and compare it with your installed tools. This guide targets the named-token `colors.toml` format and the installed `shell.<section>.toml` override mechanism we inspected.

## 2. Save a way back

Choose a new backup directory. The exclusive `mkdir` stops this sequence from overwriting an existing baseline.

```bash
backup="$HOME/aow-theme-backup"
mkdir "$backup" && {
  omarchy theme current > "$backup/theme-name.txt"
  cp -a "$HOME/.local/state/omarchy/current/theme" "$backup/generated-theme"
  readlink "$HOME/.local/state/omarchy/current/background" > "$backup/background-path.txt"
}
```

Keep a screenshot of the original terminal and menu. Our original theme was Tokyo Night. Use your own recorded theme name for recovery; the command later in this guide is specific to our lab. A theme backup is not a backup of your personal files or the whole operating system.

## 3. Give the agent a bounded job

Our recorded prompt asked Codex to create a new user-owned `aow-workshop` folder inside `~/.config/omarchy/themes`, inspect the installed format, use ivory `#F5F0E3`, ink `#242D2B`, teal `#28767A` and restrained amber `#D49A35`, check readable text pairs, avoid packaged-default changes, and wait before applying. Authentication happened off camera. No credentials belong in the theme archive.

You can use the included theme without an agent: inspect it, then copy the supplied `aow-workshop` directory into `~/.config/omarchy/themes/`. Stop if that destination already exists and compare versions rather than overwriting it. The downloaded folder is a local copy; do not assume all remote-theme installation paths accept executable files such as a validator. The color and wallpaper files are the theme itself.

## 4. Read the source connection

The primary file contains named roles:

```toml
mode = "light"
accent = "#28767A"
background = "#F5F0E3"
foreground = "#242D2B"
```

Our actual file has additional selection, muted and ANSI colors. In the installed Foot template, `background={{ background_strip }}` becomes `background=F5F0E3` in `~/.local/state/omarchy/current/theme/foot.ini`. The `_strip` suffix removes the leading hash. Theme selection regenerates these files, so make persistent changes in the source theme.

`backgrounds/aow-workshop.svg` is original vector artwork; the bundled PNG is the wallpaper. `shell.menu.toml` and `shell.launcher.toml` override only those sections, retaining generated defaults elsewhere.

## 5. Check colors before applying

Our validator runs installed templates in a temporary folder inside the theme. It does not call theme-set. Inspect it before running:

```bash
cd "$HOME/.config/omarchy/themes/aow-workshop"
python3 validate.py
```

It rendered 17 installed templates, parsed TOML/JSON and checked 60 specified text pairs. Ink/ivory is 12.43:1; teal/ivory is 4.66:1; brand amber/ivory is 2.18:1. We kept amber decorative and used darker ochre for warning text. These checks do not certify arbitrary ANSI combinations, transparent surfaces, every editor plugin or the entire desktop.

## 6. Apply and compare the same surfaces

```bash
omarchy theme set aow-workshop
```

The command changed the wallpaper, top bar, terminal and border without rebooting in our test. Open the same menu, notification and editor content to compare. We used Foot with a 14-point font for recording. Neovim's initial launch performed parser setup; that was a first-run editor event, separate from theme generation. Our capture input initially dropped a tilde in an editor path; reopening with the full absolute path corrected the test without saving anything.

## 7. Make one small refinement

After seeing the root menu, we requested a stronger selected-row fill. The two functional changes were:

```diff
# shell.menu.toml and shell.launcher.toml
-selected-background-alpha = 0.08
+selected-background-alpha = 0.16
```

Ink text stayed unchanged. Reapplying the same theme regenerated the overrides and visibly darkened the selected Apps row. The static selected-row contrast remained 9.25:1. The archive includes both revisions and their exact diff. The runtime observation is of the menu; the launcher's override was validated in generated configuration, not separately exercised on screen.

## 8. Test persistence and restore

```bash
omarchy restart shell
omarchy theme current
# Open the menu and a fresh terminal again.
omarchy theme set tokyo-night
```

After shell restart, the AOW selection fill persisted. A new terminal also used the AOW palette. After restoring Tokyo Night, the terminal, menu and reopened editor returned to its colors. A recursive comparison of generated theme files against our saved baseline found no differences; the original wallpaper path returned, and packaged-theme checksums were unchanged. The custom theme remained in its own folder.

We did not test a full reboot, all applications, other hardware, remote installation or every accessibility interaction. If your original theme had a different wallpaper choice, restore that saved background explicitly and compare it; theme selection alone should not be assumed to restore every personal preference.

## Results

| Surface / transition | Observed result |
|---|---|
| Foot, top bar, active border, wallpaper | Changed after apply |
| Root menu and notification | AOW palette visible |
| Neovim | Palette visible when file reopened |
| Menu selection refinement | Stronger fill visible after reapply |
| Shell restart / fresh terminal | AOW appearance persisted |
| Tokyo Night restore | Generated files matched saved baseline |
| Packaged themes | Checksums unchanged |
| Full reboot, all apps and hardware | Not tested |

The recording preserves the real build and troubleshooting. The narrated edit uses selected excerpts, enlarged details and explicitly labeled pauses for explanation. No desktop behavior is simulated.

## Verification commands from the lab

Before the change, we saved the generated theme directory and a checksum inventory of packaged themes. After selecting Tokyo Night again, we ran:

```bash
# Lab paths: use the backup path you actually created.
diff -qr "$HOME/aow-theme-evidence/original-generated" \
  "$HOME/.local/state/omarchy/current/theme"
sha256sum -c "$HOME/aow-theme-evidence/packaged-themes.sha256"
readlink "$HOME/.local/state/omarchy/current/background"
```

The diff emitted no differences. Every packaged-theme checksum matched. The final background symlink target equaled the saved target. The recording shows the UI restore; these additional file checks ran through the lab control connection and are preserved as separate evidence.