craft-libs/docs/settings-storage.md

Settings storage across the Craft apps

How every Craft app stores its settings, and what goes where. The shared code is craft-settings; this page is the policy it implements. Discussion: storytold/craft-libs#12.

What goes where

Kind	Where	Why
Settings people might edit	config.toml in the config folder	One readable file with comments, atomic saves, backup, recovery, migrations
Window and UI state	ui.ron / app.ron beside config.toml	Changes every session; not worth comments or hand edits
Caches and models	Platform cache folder (paths::cache_dir); %LOCALAPPDATA% on Windows so it does not roam	Disposable, large
Recovery and autosave files	Platform data folder (paths::data_dir)	Not settings; must survive a settings reset
Settings that belong to a library or project (LightCraft)	Inside that folder, via SettingsStore::open_at	Travels with the library
API keys and tokens	The OS keychain	Never in a plain-text file

The config folder

First match wins. The store reports which rule applied, so apps can show the path in their about or settings screen.

1. An override passed by the app, such as a --config-dir flag
2. <APP>_CONFIG_DIR, for example PHOTOCRAFT_CONFIG_DIR (one per app, so redirecting one app does not move the others). Set but empty means isolated: nothing is read or written anywhere, the same as DesignCraft's existing behaviour, so tests and agents can never touch a user's real settings
3. Portable mode: a marker file next to the executable (next to the .app on macOS, since writing inside a signed bundle breaks its signature). The default is a file named portable with settings in config/ beside it; apps that already ship portable builds keep their own names (PhotoCraft: portable.txt or PhotoCraft.portable, folder PhotoCraftData)
4. The platform default:

Apps can also open a store with Location::Memory (for a switch like DESIGNCRAFT_NO_PREFS): settings work in memory and nothing touches the disk.

Platform	Folder
Linux / BSD	$XDG_CONFIG_HOME/<app>/, or ~/.config/<app>/ if unset
macOS	~/Library/Application Support/<app>/
Windows	%APPDATA%\<app>\ (Roaming)

<app> is the app's lowercase id (photocraft, designcraft, …) on every platform, macOS included (decided in #12). Existing Linux folder names do not change; the Launcher moves from ai.storyteller.artcraft-launcher to artcraft-launcher.

If the folder cannot be created or written (a portable marker in /Applications, an AppImage mount), the store opens read-only and says so at startup.

Files in the folder

• config.toml: starts with schema_version = N, then one [section] per settings area. Written on first launch so people can find it. 0600 on Unix.
• config.toml.bak: the previous version, refreshed before every save.
• config.broken-<unix-ts>.toml: a file that was not valid TOML, moved aside and never deleted.

Saving and recovery

• Saves happen during use, half a second after the last change, atomically through craft-atomic. A failed save leaves the old file intact and is retried with backoff; the app shows the error.
• A file with a TOML syntax error is moved aside and defaults are used. A file that parses but has a value that no longer fits (a renamed theme, a typo in a hand edit) is not treated as broken: only that [section] falls back to defaults and the app is told which one.
• A file written by a newer build is shown but never overwritten.
• Comments, key order and keys the app does not know survive saves. If two instances of an app are open, each re-reads the file before writing so those survive; known keys are last-writer-wins.

Migration

• Schema changes: Settings::migrate upgrades the document one version at a time before it is parsed. A failed step leaves the file untouched and the store read-only.
• Older per-app files (prefs.json, ui.json, *.ron): imported on the first run that finds no config.toml, using the app's existing parser. The old file is left in place, so rolling back to an older build keeps working; apps can remove it a few releases later.

Where the apps are today

From the audit in #12 (Linux defaults, from source; overrides and portable mode change them). Before an app moves over, check where it saves on macOS and Windows so the importer finds the old files there too.

App	Today	Moving to craft-settings
PhotoCraft	~/.config/photocraft/preferences.json + eframe ui.ron; atomic saves with retries; portable via portable.txt/PhotoCraft.portable → PhotoCraftData/	Import preferences.json; keep ui.ron; keep its portable names via PORTABLE_MARKERS/PORTABLE_DIR
DesignCraft	~/.config/designcraft/prefs.json + ui.json; saves on exit, ignores failures; empty DESIGNCRAFT_CONFIG_DIR and DESIGNCRAFT_NO_PREFS touch nothing	Import prefs.json; keep ui.json; gain save-during-use and error reporting; DESIGNCRAFT_NO_PREFS → Location::Memory
EffectCraft	~/.config/effectcraft/prefs.json, shortcuts.json, script_settings.json; atomic	Import all three into sections of one config.toml
FilmCraft	~/.local/share/filmcraft/preferences.json; atomic	Import from the data folder; settings move to the config folder
GridCraft	~/.config/gridcraft/prefs.json + ui.json; saves on exit, ignores failures	Same as DesignCraft
LightCraft	global ui.json; library prefs.json, presets.json, view.json; atomic, backups, overwrite protection	Global settings via open; library settings via open_at(library_dir)
VectorCraft	~/.config/vectorcraft/ui.json with engine preferences inside; atomic, ignores failures	Split engine preferences out into config.toml; keep UI state in ui.json
ArtCraft Launcher	~/.local/share/ai.storyteller.artcraft-launcher/app.ron (eframe)	Import from app.ron; needs its own tick timer while in the tray

Adoption order: PhotoCraft and DesignCraft first (closest to and furthest from the target behaviour), then the rest.

Not yet

• Reloading settings when the file changes on disk while the app runs
• Removing imported legacy files
• Settings on the web (wasm32), where only the trait, document helpers and error types exist