# Startup configuration

Native pardes builds read a per-user `pardes` file before the first frame:

- Unix: `$XDG_CONFIG_HOME/pardes`, falling back to `~/.config/pardes`.
- macOS: `$XDG_CONFIG_HOME/pardes` when that variable is set, otherwise
  `~/Library/Application Support/pardes`.
- Windows: `%LOCALAPPDATA%\pardes`, with `%USERPROFILE%\AppData\Local\pardes`
  as the fallback.

On the two unixes `XDG_CONFIG_HOME` counts only when it is ABSOLUTE, as the
XDG base-directory specification requires; an empty or relative value falls
back to the home-directory form. Windows never consults it. A file of 1 MiB or
more, or one that cannot be read, is treated as no file at all — the path
still resolves, because "nothing is there yet" is the answer `Config` exists
to give. There is one case with no path at all: a native launch with no `HOME`
set, which `Config` reports as such.

`Config` (`SPC f c`, or the word executed anywhere) prints the resolved path
into a `+Config` output pane, so the machine answers this rather than the list
above. The path is printed whether or not a file is there — that is the case
you ask in — and the row is ordinary text, so a right click on it opens the
file.

The browser build has no local user-config path and does not load this file.
(Nor does it have the `Font` builtin, or a language backend, or ptys of its
own — see `docs/web.md`.)

The format is one existing builtin command per line, using the same spelling
and argument parsing as commands executed inside pardes:

```text
Theme acme
Font DejaVuSansMono-Regular
Shell zsh
Wrap
```

A line matches a builtin whose name takes NO argument only as that whole word:
`Kill` runs, `Kill something` does not. Builtins that take one (`Theme`,
`Font`, `Shell`, `Restore`, `Find`, `Grep`, `Rename`, `WsSymbols`, `Look`,
`Exec`) take everything after the name as the argument.

`Theme <name>` wants one of the 228 names in the ring. Do not derive the
spelling — read it off `ThemeSel` (`SPC t t`), which lists every one as the
exact `Theme <name>` line that selects it. The generator lowercases, folds
punctuation runs to a single `_` and then TRIMS leading and trailing ones
(`penumbra+.toml` is `penumbra`, not `penumbra_`), and it suffixes every theme
that came from zed with `_zed` so it cannot collide with a helix theme of the
same name (zed's "Ayu Mirage" is `ayu_mirage_zed`; `ayu_mirage` is helix's).
A name that is not in the ring is ignored.

`Shell <name>` sets the binary that the NEXT terminal pane execs; panes
already open keep the shell they are running. A bare name is resolved against
the handful of directories a shell actually lives in, not `$PATH`.

`Font` and `FontSel` exist ONLY in the SDL GUI and native macOS builds — a
terminal's font belongs to its emulator and a browser's to the page — so a
`Font` line is one of the silently-ignored ones everywhere else. Both builds
resolve the name by walking the font directories on every lookup, so a face
installed a moment ago is findable.

What happens to a codepoint the chosen face has no glyph for differs by shell.
The SDL GUI falls back through a chain it builds itself: embedded Adwaita
Mono, then installed `NotoSansMono-Regular`, `DejaVuSansMono`,
`SymbolsNerdFont-Regular`, `NotoSansSymbols2-Regular`,
`NotoSansSymbols-Regular`, and `DejaVuSans`, in that order, missing entries
skipped; the rasterized glyphs are retained in its GPU atlas. The macOS shell
has none of that and needs none: it embeds no font, substitutes the system
monospaced face (else Menlo) when the NAME you asked for will not load, and
leaves per-codepoint fallback to CoreText's own cascade when it draws. What it
caches is glyph ids, not pixels.

Blank, unknown, malformed, or unsuccessful lines are ignored silently, and a
bad line does not prevent later lines from running. Top-level text that is not
a builtin is not sent to a shell. (`Exec ...` remains an ordinary builtin and
therefore keeps its normal behavior.) Key bindings remain compile-time choices
in `src/config.zig`; this startup file does not remap them.