---
name: noctalia-template-offline-render
description: "Recover from missing noctalia-generated theme files (niri noctalia.kdl include, ghostty/alacritty noctalia theme) using the offline noctalia theme --render CLI when msg templates-apply is a no-op"
---

# Noctalia template offline render

## Failure signature
- niri: `failed to read included config from ~/.config/niri/noctalia.kdl: No such file or directory`; desktop runs but with DEFAULT config (niri 26.04 falls back, does not exit): no custom keybinds/rules, no noctalia autostart, default output placement.
- ghostty: `theme "noctalia" not found, tried ~/.config/ghostty/themes/noctalia`.
- alacritty: import of `~/.config/alacritty/themes/noctalia.toml` missing.

## Root cause pattern
Upstream dotfiles commits theme switches (niri include, ghostty `theme = noctalia`, alacritty import) that depend on noctalia TEMPLATE-GENERATED files. Those files are per-host outputs (rendered from the local palette) and are intentionally NOT in the repo. On any host where `templates-apply` never ran, they don't exist.

## Fix (offline, works while a session runs)
Built-in templates live at /usr/share/noctalia/assets/templates/ and are declared in builtin.toml. Render each needed one with the live palette:

```bash
# niri include (plain host-local file; do NOT symlink into repo — regenerated per host)
noctalia theme --theme-json ~/.config/noctalia/colors.json \
  --render "/usr/share/noctalia/assets/templates/niri/niri.kdl:$HOME/.config/niri/noctalia.kdl"

# ghostty
mkdir -p ~/.config/ghostty/themes && \
noctalia theme --theme-json ~/.config/noctalia/colors.json \
  --render "/usr/share/noctalia/assets/templates/ghostty/ghostty:$HOME/.config/ghostty/themes/noctalia"

# alacritty
mkdir -p ~/.config/alacritty/themes && \
noctalia theme --theme-json ~/.config/noctalia/colors.json \
  --render "/usr/share/noctalia/assets/templates/alacritty/alacritty.toml:$HOME/.config/alacritty/themes/noctalia.toml"
```

All template tokens (primary, surface, error, primary_container, …) resolve from the flat 16-key colors.json; container tokens are derived, never blank.

## Verify
1. `niri validate` → "config is valid" (rc 0)
2. `ghostty +validate-config` → rc 0
3. On next login: journal shows `loaded config from config.kdl` with NO parse WARN, custom output placement (compare `niri msg outputs` vs display.kdl), noctalia autostarted (`pgrep noctalia`).

## Traps
- `noctalia msg templates-apply` on 5.0.1 returns "ok" but applies NOTHING (opt-in config schema this build does not act on). Do not trust its exit code.
- Niri config errors at boot are NOT fatal — the compositor keeps running on defaults, which looks like "some settings silently stopped working", not a crash.
- Regenerate after any palette change; the rendered files are static snapshots.