Config

One TOML file holds every setting: ~/.config/pal/config.toml ($XDG_CONFIG_HOME/pal/config.toml when that variable is set, on macOS too). The file is the source of truth. The Settings window reads and writes it, and a hand edit is picked up live. A key you do not set has its default; an empty or missing file is all defaults.

The file

#:schema https://raw.githubusercontent.com/zcag/pal/main/core/schema/config.schema.json
# pal settings. The settings view writes this file; editing by hand is fine too.

[general]
hotkey = "ctrl+space"      # global hotkey, or several: ["cmd+space", "ctrl+space"]; "" turns it off (bind `pal toggle` instead)
theme = "system"           # system | light | dark
position = "top"           # top | centre | last
launch_at_login = false
menu_bar_icon = true
check_updates = true
selection_snapshot = true         # {selection}: fall back to a copy shortcut when the app hides its selection from the accessibility API
deeplink_confirm = true    # a pal:// link that acts asks first; false never asks; ["timer"] asks except for those extensions
extension_dirs = ["~/dotfiles/pal-extensions"]   # extra extension roots, loaded after the store

# Per-palette settings, keyed by palette id. Absent palette: all defaults.
[palettes.clipboard-history]
alias = "cb"               # extra keyword on the palette's row at the root
hotkey = "ctrl+shift+v"    # opens pal straight inside this palette

[palettes.windows]
hold = "alt+tab"           # the switcher chord (the manifest suggests this one; "" turns it off)

[palettes.calc]
icon = "∑"                 # replaces the extension's icon on the palette row

[palettes.windows]
enabled = false            # no rows in the index, no palette row

[palettes.emoji.settings]  # settings the extension declared for this palette
columns = 8

# Features: what pal does on its own, one table each (docs/features.md).
[features.clipboard]
exclude_apps = ["com.1password.1password"]

[features.mouse]
reverse_mouse = true

# Extension settings, keyed by extension name. Shape is whatever the
# extension declared in its pal.json.
[extensions.clipboard]
primary_action = "copy"

[extensions.apps]
folders = ["~/Applications/Nix Apps"]

[extensions.github]
token = "keychain:pal/github-token"   # a secret reference, never the value

# Extensions from registries: what is installed, what is off, which
# registries to follow. pal writes it when you install from Settings, the
# Store or the CLI (docs/registry.md).
[store]
auto_update = true
installed = ["weather", "acme:todo"]   # "registry:name" when not pal's own
disabled = ["hue"]

[[store.registries]]
name = "acme"
url = "https://acme.github.io/pal/index.json"
key = "RWQ..."             # pinned when added

The first line is taplo's schema directive, pointing at the committed schema's URL (core/schema/config.schema.json on main), so an editor with TOML schema support (VS Code "Even Better TOML", nvim through taplo) validates keys and completes them; taplo fetches it. The first launch writes those two header lines and nothing else into the config directory.

[general]

Hotkey syntax: modifiers first, + between, one main key, case does not matter. Modifiers: ctrl (or control), alt (or option), cmd (or command, super), shift, cmdorctrl (Cmd on macOS, Ctrl elsewhere). Keys: letters, digits, space, enter, f1..f12, punctuation and the rest of the usual key names. A general.hotkey entry that does not parse is reported and skipped; when none parses the first falls back to ctrl+space and is logged, so pal stays reachable. A hotkey another app already holds is reported and skipped: the other entries still register, and when none of them could be had the previous root hotkeys stay registered. Settings > Shortcuts says "Not registered" with the OS's reason under that entry's field, and the Overview names it. On macOS cmd+space is Spotlight's until "Show Spotlight search" is unticked under System Settings > Keyboard > Keyboard Shortcuts > Spotlight; pal reads that binding, says so in Settings, and while the key is wanted and held polls it every 2 s so the registration lands as soon as it is freed. On Linux the hotkey reaches only X11 clients; Wayland sessions bind pal toggle in the compositor.

Theme file

general.theme_file names a TOML file of the --pal-* tokens a user may override (pal_core::theme): the colours, the tag palette, the brand tiles, the radii and the two font stacks. Geometry, spacing and motion stay pal's. A file has a name, keys shared by both schemes at the top level, and a [light] and a [dark] section for the rest:

name = "Catppuccin Frappé"
radius_row = 6            # both schemes

[light]
accent = "#8839ef"
bg = "#eff1f5"

[dark]
accent = "#ca9ee6"
bg = "#303446"

A theme file applies over the design (general.design): its colours win, the design's type and layout stay.

The section applied is the scheme in force: theme = "dark" pins dark, "system" follows the OS and swaps the section when the OS flips. Every window (the panel, the HUD, Settings, the bar popover) sets the section's variables on its :root, so a themed panel and a themed Settings window agree. The file is watched (an mtime poll every second): a save applies live, as a config edit does.

Two examples ship in examples/themes/: Catppuccin Frappé (with Latte as its light section) and Rosé Pine Dawn (with Rosé Pine as its dark one). Settings > General > Theme file lists the files in <config dir>/themes/ (the folder is made with the two examples in it the first time that page looks for it; "Open themes folder" seeds an empty one), sets theme_file to the chosen name, and "Edit theme file" opens the file in the editor. Its diagnostics show under the picker and in the log (lines starting theme).

Every key is checked: an unknown key is a warning naming its dotted path (light.accnet: not a theme token), a value of the wrong shape is dropped with a warning (dark.accent: ignored: expected a colour), and the rest applies. A file that does not parse is one error with its line and no theme. A colour is #rgb, #rgba, #rrggbb, #rrggbbaa, or an rgb(), rgba(), hsl(), hsla() call; a radius is a number of pixels (14, 6.5, "14px"); a font is a stack as CSS writes it.

The tokens, each <key> driving --pal-<key> with _ as -:

The values pal ships with are in app/src/ui/tokens.css (--pal-*, light and dark), the place to read what each token looks like before overriding it; the brief (app/design/brief.html) shows them on the components.

[palettes.<id>]

Settings pal provides to every palette without the extension declaring them. A palette absent from the file gets the defaults.

The id is the extension's name when the palette is named like it (apps, emoji, calc, system, windows, bookmarks), else <extension>-<palette> (clipboard-history; a script palette named otp is scripts-otp). Bare keys, no quoting.

[bar]

Bar items: what extensions put on the macOS menu bar or on sketchybar (the design in docs/design/bar.md; what an extension declares in Extensions). Every item is keyed <extension>/<id>. Not drawn on Linux: the table is read and kept there, declared items are listed by pal bar list, but nothing is drawn and no item renders (Settings > Bar says so).

Appearance. [bar.menubar] and [bar.sketchybar] both take these keys, how that target draws every item; each is overridable per item below. The same key means the same thing on both targets where the target can (Settings > Bar > Defaults shows each with its description and the target's caveat).

On sketchybar a crowded bar makes room by itself: when the items right of the notch (or left of it) would run into each other, the one nearest the collision drops its title (its glyph, segments and count stay) until they fit, and gets its text back when there is room again. An urgent item and one with no icon keep their text; order decides who goes first (the nearer the notch, the sooner).

The menu bar's title is a plain system-font string (tray-icon sets no attributes), so size (icon_size, text_size), font, width, opacity under 100 and a set badge_color make the renderer prerender the title into the icon image next to the glyph (bar/glyph.rs, the system's own SF Pro or SF Mono read from /System/Library/Fonts); an emoji icon stays title text, an image icon keeps its picture and its title text. sketchybar has no way to unset a property, so an item whose size or font goes back to the bar's own is removed and added afresh, which gives it the bar's --defaults again.

Per item, [bar.items."<extension>/<id>"] (the key needs quoting):

A change re-targets, moves or removes items live. pal only ever touches sketchybar items named pal.<extension>.<id> (a segment is pal.<extension>.<id>.<segment>, a count badge pal.<extension>.<id>.badge); the bar's own items are never touched, and every pal item is removed on quit. A bar restarted by its own rc (which wipes its items) gets pal's back at the next probe, or at once with pal bar sync at the end of the rc.

Rules: presence, urgency and appearance by state

An extension's bar item states its facts with every render (power/level, power/charging, spotify/playing, calendar/phase: the States palette lists them, and the item's pane under Settings > Bar shows them live) and declares in its pal.json the rules that turn those into how the item draws: while a rule's when (a state expression, as [states] below) holds, the item is hidden, urgent, moved, or drawn with the appearance keys of this table. Rules apply in the extension's order, later wins. The extension no longer decides presentation in its code, so every one of those decisions is yours to move:

[bar.items."power/battery".rules.low]
when = "power.level < 25"            # the extension's rule, its threshold moved

[bar.items."power/battery".rules.fine]
hidden = false                       # keep the healthy battery on the strip

[bar.items."media/now-playing".rules.paused]
hidden = false                       # a paused track stays, muted (the rule's own tint)

[bar.items."power/battery".rules.focus]   # a rule of your own
when = "not working"
hidden = true
color = "muted"

A key you set replaces the extension's for that rule; a key you leave keeps the extension's. Settings > Bar lists an item's rules with the condition, what each does, whether it holds now and where it comes from, and edits them the same way. A rule's hidden is decided at draw time after the render (the item keeps rendering, since its facts come from the render); show_when/hide_when above hold an item off without a render. A rule's color wins over a muted the render answered, since the rule is the decision; the item-level color key above leaves muted alone.

[states]

Named variables the whole of pal reads (docs/design/states.md): the bar items' show_when/hide_when, an extension's state.get, pal state. A state is yours: it exists because [states.<name>] is here, or because pal state set <name> … was run once. pal ships no meaning for "working"; it ships hour and weekday and you write the rule.

[states.working]
expr = "weekday not in ['sat', 'sun'] and hour >= 9 and hour < 18 or sessions.working > 0"
description = "On the clock"      # what the States palette shows

[states.deep]                     # no expr: only ever set by hand or from outside
default = false

[bar.items."github/prs"]
show_when = "working"

Names. Lowercase letters, digits, _. The built-ins are reserved (hour, minute, weekday, date, front_app, awake_since, network, theme, locked, idle, host, panel); an extension's are <key>/<name> (sessions/working, gmail@work/unread) and only it can feed them.

Resolution. A value set by hand (pal state set, the palette; with an optional expiry) wins, else expr, else what an extension or a built-in published, else default. pal state reset <name> drops the manual value. The manual and published layers survive a relaunch (states.json under pal's data directory, next to bar.json); the built-ins are read afresh.

[groups]

Devices you use together (docs/design/controls.md): one remote then drives the TV's volume, inputs and power. Settings › Groups is where you make one; the file mirrors it. An extension in no group is served by itself, as if this table were not here.

[groups.living-room]
title = "Living room"
members = ["appletv", "samsungtv"]
volume = "samsungtv"      # the Apple TV's remote sets the TV's volume
inputs = "samsungtv"

Power has no key: it is every member's (the power button wakes or sleeps them all). Players are never grouped: every one reaches Now Playing.

Settings › Groups (also pal settings groups, the root's Settings › Groups) has a card per group: its name, its devices with the device each drives, where the sound and the inputs come from (only among members that have them; no row when none does), and who turns on and off together. "New group" makes one at once ("Living room", then "Group 2") and asks which devices: the installed ones, and the ones a registry offers (their index entry's controls), which install on the pick and then join. A device joining binds the sound and the inputs to the TV (the member with inputs) when nothing serves them yet, so an Apple TV and a Samsung TV need no pick. A device in another group moves.

The id is lowercase letters, digits, - and _. Settings writes the table through these app commands (for a page of your own on the same bridge): groups_create { title, members? } (answers the id, the title slugged), groups_rename { id, title }, groups_delete { id }, groups_set_members { id, members } (a binding to a member that left is unset with it), groups_bind { id, control: "volume" | "inputs", member | null }; controls_published answers what every extension published, by key then control (the devices' names), and pal://controls says when it changed.

[features]

One table per feature, what pal does on its own (Features, each feature's keys there): [features.clipboard], [features.expansion], [features.switcher], [features.sidebar] (below), [features.reserve], [features.mouse], [features.keycast]. Settings › Features writes them. A feature's commands take hotkeys in [features.<id>.hotkeys], command id to chord (reverse_mouse = "ctrl+alt+r"). A table naming no feature, or a key its feature does not have, is a warning.

A file from before features existed (settings under [extensions.mouse], [extensions.keycast], [extensions.clipboard]'s retention, [extensions.snippets] expand*, [extensions.window-management] keep_below_bar, [general] app_switcher, [sidebar]) is rewritten once when pal starts: the keys move to their feature's table with their comments, and the file as it was is kept next to it as config.pre-features.toml.

[features.sidebar]

A live palette docked to a screen edge (the design in docs/design/switcher.md): it peeks the moment the pointer touches the edge (delay), centred on the pointer, and closes grace after the pointer has left; a click into the peek, a key while it is up, or its hotkey engages it (key: typing filters, Enter runs, Escape hides). Every row wears its number, and cmd+N (ctrl+N on Linux) runs row N without a search, so the numbers on screen are the promise. One sidebar; macOS only for now: on Linux the table is read and validated, nothing is built.

[features.sidebar]
palette = "windows/windows"   # any palette; unset or "" = no sidebar (the default)
edge = "right"                # left | right
display = "cursor"            # cursor | primary | a display's name
width = 280
peek = true
delay = 0                     # ms the pointer rests at the edge before the peek
grace = 150                   # ms after the pointer has left before a peek closes
hotkey = "ctrl+opt+tab"

Settings › Features edits the whole table as the Sidebar card (the switch puts windows/windows in palette and Off writes ""; the palette, the edge, the display by the names the OS reports, the width, the peek and the hotkey each write their key, a value at its default leaving the file).

show_when / hide_when (the sidebar following a named state, as a bar item does) are not read yet.

[extensions.<name>]

Extension settings, keyed by extension name. The shape is whatever the extension declared in its pal.json; the defaults live there and the Palettes page lists them for the bundled extensions.

The values an extension sees are the manifest's defaults with every key you set on top, one level deep: a key you set replaces the default whole (a list is not appended to, a table not merged). Keys the manifest does not declare pass through, so a setting written ahead of an upgrade is not lost. A declared setting set to its default is unset by the settings view, so the file only holds what differs.

Changes reach a running extension without a restart: the core pushes the resolved values and lists the extension's palettes again. Three exceptions: emoji's columns is read once at load (edit the file, then Settings > Restart extension host); the scripts extension discovers its palettes once at import, so its config, skip, v1_repo and ttl need a host restart too (timeout and preview_max apply to the next run); and the clipboard recorder, which runs in pal itself rather than in the host, reads exclude_apps, max_entries and max_age_days once at startup, so those want pal relaunched.

[store]

Extensions installed from registries, and the registries themselves. pal writes this table whenever you install, remove, disable or enable an extension or add or remove a registry, from Settings, the Store palette or the CLI (CLI), so the file is a record you can back up, version and restore; editing it by hand is fine too.

[[store.registries]]

One table per registry, in the order bare names are looked up in (pal's own always first):

A table named pal sets only pal's own registry's channel and auto_update; its URL and keys are built in:

[[store.registries]]
name = "pal"
channel = "edge"           # every build pushed to main, before it is released

Each registry's index is cached under pal's cache directory (registries/<name>/) with when it was last checked and why that check failed, if it did; Settings and pal registry list show both. A check that fails (unreachable, a bad signature, an index older than the cached one) never replaces the cached copy.

[instances]

One extension, several configured copies: two GitHub accounts, two Slack workspaces, two Home Assistant homes. Only an extension whose pal.json declares "multi": true has instances (github, slack and home-assistant among the bundled ones). The default instance is the extension's bare name and the tables you already have; another one exists because its table does, keyed <name>@<suffix>:

[instances."github@work"]        # the instance exists because this table does (empty is fine)
title = "Work"                   # the display name; default: the suffix capitalised
tint = "amber"                   # one of the twelve brand colours; default: picked from the suffix
badge = "W"                      # one or two characters on the tile's corner; default: the title's first letter
enabled = true                   # false parks it: not loaded, rows gone, settings kept

[instances.github]               # optional: name the default once a second exists
title = "Personal"

[extensions."github@work"]       # its settings; inherits [extensions.github], except secrets
token = "keychain:pal/github@work-token"

[palettes."github@work-prs"]     # per-palette keys, per instance (hotkey, alias, icon, enabled, tier)
hotkey = "ctrl+alt+w"

[bar.items."github@work/notifications"]   # bar items, per instance
order = 30

The suffix is lowercase letters, digits, - and _ (up to 32, starting with a letter or digit), and never default; the key needs quotes in TOML because of the @. It is fixed at creation: it sits in file paths (the storage file storage/github@work.json, the index cache), in the frecency record and in links (pal://open/github@work/prs), so renaming means removing and adding; the title is what you rename.

Inheritance. [extensions."github@work"] layers over [extensions.github], which layers over the manifest's defaults, each one level deep, a set key replacing whole. Two kinds of setting never inherit from the default instance: one declared kind: "secret" (a token identifies the account) and one declared scope: "instance" (Slack's workspace, Home Assistant's url); those fall to the manifest default until set for the instance. [palettes."github@work-prs"].settings inherits [palettes.github-prs].settings the same way; the pal-provided palette keys (enabled, alias, hotkey, hold, icon, tier, item_hotkeys) never inherit, since a hotkey cannot be shared and an alias or icon is what tells the two apart. A secret reference is looked up per instance, so keychain:pal/github@work-token is its own keychain item.

What an instance gets. Its own palettes at the root, titled with the instance's title ("Pull Requests (Work)", or where the manifest's title says {instance}), its tile in the instance's tint with the badge in the corner (the default instance keeps the plain tile), its own bar items (github@work/notifications), storage, cache, frecency and deep links. The extension's code is shared and runs once per instance, each in its own worker of the extension host, so nothing one instance caches leaks into another. Every instance of a multi extension runs in a worker, the default too, even when alone.

A change under [instances] takes effect at once: the running pal reloads the extension's instances (every one, like a file change to its code), so an added table lists its palettes within a second and a removed or parked one takes its rows and bar items away, an open level of it popping to the root. A [instances."x@y"] for an extension without "multi": true is not loaded and shows as a warning (x does not support instances, or x is not installed) in the diagnostics strip and on the Overview. Keys the schema does not know under an instance table are warnings, like everywhere else.

In Settings and from the shell. Settings > Extensions shows a multi extension's instances as a section of its pane: one row each (the badged tile, the title, the key, "default", an on/off switch, Rename, Remove) and "Add another account", an inline form that slugs a suffix from the title, checks it live and offers the tint; the Settings section below has a segmented control per instance, an inherited value carrying a "From Gmail (Personal)" note and a secret or scope: "instance" field reading "Set for this instance". A value typed equal to the inherited one leaves the file, so the instance keeps following. The Palettes page groups per instance ("Gmail (Work) › Inbox (Work)"), the Bar page's rows read "Gmail (Work) › Unread", the Overview's needs-setup rows name the instance. pal instance list|add|remove (docs/cli.md) and pal://instance/add/<name>/<suffix>, pal://instance/remove/<key> (docs/links.md) do the same edits. Removing an instance unsets every table of its own ([instances.<key>], [extensions.<key>], its [palettes."<key>*"] and [bar.items."<key>/*"]), deletes its storage file and index cache and forgets its frecency; the keychain items stay, as they do for a removed extension.

Secrets

A setting of kind secret never sits in the file as plain text. The file holds a reference:

• keychain:<service>/<account> or keychain:<account> (service pal): the OS store. On macOS that is the Keychain, as a generic password; on Linux the Secret Service (gnome-keyring, KWallet's compat service) through the secret-tool CLI from libsecret, as an item with the attributes service and account. The Settings window writes the value there under pal/<extension>-<key> and puts keychain:pal/<extension>-<key> in the file. By hand: security add-generic-password -s pal -a github-token -w on macOS, secret-tool store --label="pal github-token" service pal account github-token on Linux.
• env:<NAME>: an environment variable of the pal process.

A setting the extension declared kind: "secret" reaches it resolved: the values it gets (at import and on every change) carry the secret itself, fetched from the store by the core (core/src/config/secrets.rs, resolve_declared). Anything that is not a reference passes through as itself. A reference the store fails to answer (a locked keychain, a denied prompt) stays as the reference string and is logged as secrets unresolved; the extension still loads. Settings of any other kind are never resolved, even when their value looks like a reference, and neither is a key the manifest does not declare. A reference with nothing behind it (a setting synced from another machine whose key was never added here) is left out, so the extension sees the setting unset and Settings shows the field as "Add your key". Removing a secret in Settings unsets the key; the keychain item stays. On Linux without secret-tool on PATH (package libsecret on Arch, libsecret-tools on Debian and Ubuntu) or without a Secret Service on the session bus, every keychain: reference is unresolved and the log says which of the two is missing; env: references work everywhere.

Sync

Signed in to a pal account (Settings › Account, docs/design/accounts.md), the file syncs between your machines, except the keys that belong to one machine. The core sees the file as dotted keys, one per value (general.theme, palettes.files.enabled; an array is one value, so store.installed is one key), and only what the file says: a default the file leaves out is no value, so setting a key back to its default (which unsets it) removes it on the other machines too. A key changed here goes up a few seconds later; another machine's change arrives when the panel opens (at most once a minute) and every 15 minutes, written through the same edit path as Settings, so your comments and formatting stay. Config keys merge by latest; the server keeps every version, and Settings › Account › History puts back the settings of any earlier day.

These stay on this machine (core/src/config/sync.rs LOCAL; * is any one key), and Settings marks the rows that set them "this Mac only":

On top of the table, an extension's, palette's, bar item's or feature's declared setting of kind hotkey or path, or one that says "local": true, stays local (extensions.<key>.<id>, palettes.<id>.settings.<id>, bar.items."<key>/<id>".settings.<id>, features.<id>.<setting>). Everything else syncs, the installed and turned-off extensions included (a new machine installs them), and a secret setting's keychain: reference: the value itself never leaves the keychain, so it is added once on the new machine.

Live reload

pal watches the config file's directory (editors save by writing a new file and renaming it over the old one, and a watch on the old file would go quiet after the first save). Events within 150 ms collapse into one reload, and a reload only fires when the bytes changed. After a reload the hotkeys are re-registered, palettes are removed or listed as enabled says, extensions get their new values, launch_at_login and menu_bar_icon are applied, and both windows follow theme.

A save that does not parse keeps the last good config live and adds an error diagnostic; nothing blanks while you are mid-edit. A deleted file is a reload to the defaults.

Crash relaunch

pal runs under the OS's service manager so that a crash brings it back and a quit does not. On macOS the agent is a LaunchAgent labelled after the bundle (io.cagdas.pal) with RunAtLoad and KeepAlive { SuccessfulExit = false }: launchd restarts pal after a non-zero exit or a signal, within about five seconds (ThrottleInterval), and leaves it alone after pal quit or the menu's Quit, which exit 0. launch_at_login only decides where the plist lives: on, ~/Library/LaunchAgents/, which launchd loads at login; off, ~/Library/Application Support/pal/launchd/, which nothing loads at login and pal bootstraps itself for the session. A pal started by hand (open -a pal, a terminal) hands itself over to the agent at startup, so the process you see is always the supervised one; that costs one extra startup and happens at most once a minute, so a manager that will not start pal cannot loop. On Linux the unit is ~/.config/systemd/user/pal.service with Restart=on-failure (a transient unit of the same name when the setting is off); without systemd the XDG entry starts pal at login and nothing relaunches it. Debug builds do none of this. After a relaunch pal shows "pal restarted after a crash" once, logs the report it found, and Settings > About lists the last crash (the .ips under ~/Library/Logs/DiagnosticReports, or the coredumpctl entry) and the last Rust panic (<data dir>/<profile>/last-panic.txt, written by pal's own panic hook with the message and a backtrace). Nothing is uploaded.

Edits the settings view makes go through toml_edit: comments, key order and spacing you wrote survive.

Diagnostics

The Settings window shows a strip at the bottom when the file has problems, one line each:

1 error in config.toml. The file did not parse, so pal is still using the last settings that did.
✕ error   unknown variant `blue`, expected one of `system`, `light`, `dark`   line 3

2 warnings in config.toml. Unknown keys stay in the file and are ignored.
! warning   unknown key  general.hotkeys
! warning   unknown key  palettes.clipboard.enabld

• A warning is an unknown key, shown as its dotted path. The key stays in the file and is ignored; a typo'd key does not reach the real one. No line number: the parser does not report where an ignored key sits.
• An error means the file did not parse (bad TOML, or a value outside its enum such as theme = "blue"); it carries the 1-based line, and the line is a button that opens the file in your editor. The config shown is the last good one, or the defaults at startup.

PAL_CONFIG and profiles

PAL_CONFIG=<path> makes pal use that file instead of the default. The index cache and the frecency file are keyed by config file: they live under <data dir>/pal/<profile>/, where <profile> is default for ~/.config/pal/config.toml and the first 8 hex digits of the sha256 of the file's canonical path otherwise. Two config files never share a cache or a search history, since a palette enabled in one may not be in the other. The profile is logged at startup. clipboard.db and storage/ (what extensions keep through the storage API: quicklinks, snippets) stay one level up and are shared by every profile: they are your data, not a view of one config, so a quicklink made under a test profile shows up in all of them.

The data dir is ~/Library/Application Support/pal on macOS and ~/.local/share/pal on Linux ($XDG_DATA_HOME/pal when set). The extension store, extensions/ in it, is shared by every profile.

A symlinked config file (dotfiles setups) is followed: edits and the watch go to the real file, so a write never replaces the link with a plain file. The watch follows the link once, at startup; re-pointing it later is not seen.

Coming from the previous pal

The previous pal (the v0.1.x and v0.2.x releases on GitHub, "v1" below and in the code) kept its config at the same path in another shape ([palette.<name>] tables, general.default_frontend). The first launch that finds one there migrates it, and logs each step as a migrate line:

• the v1 file is kept whole as config.v1.toml next to it (written and read back before the original is touched);
• in that copy, a base that no longer exists on disk but does under the scripts extension's v1_repo (the v1 checkout, ~/proj/pal-v1 by default) is pointed there;
• a new config.toml is written from the template, with [extensions.scripts] config set to the copy's absolute path, so every [palette.*] table keeps running through Scripts, and [extensions.bookmarks] file set to v1's palette.bookmarks.data when there was one. v1 had no hotkey key; everything else starts from the defaults.

A config.v1.toml already there with other content stops the migration (the log says so; move it away). A file already in this shape, or an empty or missing one, is not touched: the template is written when there is no file. cargo run -p pal-core --example migrate runs the same code on PAL_CONFIG, for a dry run on a copy.

Rendered from docs/config.md in the pal repo, 2026-11-02.