Settings

Settings is where you configure Brisal — how it looks, and which providers, models, and agents are available to you. This page is about the shape of settings: how to reach it, and the one idea that makes the whole thing predictable — the two-tier scope model. The individual toggles are documented on the concept page each one belongs to; the links throughout point you there.

How to reach Settings

Settings lives behind the gear icon in the header. Opening it gives you four destinations:

There is no single “Settings home” screen; the gear is a menu that jumps you straight to one of these areas. Appearance and Hotkeys are two tabs of the same Settings screen because they share the merge model below.

Two tiers: system and workspace

Almost everything you can configure exists in one of two tiers:

• System — the machine-wide layer. The defaults and the built-in catalog that every workspace starts from. Think of it as Brisal’s factory floor.
• Workspace — the per-workspace layer that sits on top of the system tier. This is where you actually work and customize. Each workspace is isolated: a change in one never leaks into another.

The reason two tiers exist is compartmentalization — one client’s provider keys, agents, and color scheme stay walled off from the next. The system tier gives you a shared starting point so you’re not rebuilding that setup for every workspace.

The one subtlety: two tiers, two ways they combine

Here’s the crux, and the thing worth getting straight. Both tiers use the same words — system and workspace — but the tiers combine in two different ways, depending on what you’re configuring.

Merge — appearance and shortcuts

For appearance (mode, font size, palette) and keyboard shortcuts, the two tiers merge into one effective result:

• The system tier holds a complete set of defaults.
• A workspace overrides only the fields it sets — leave a field alone and it keeps inheriting the system value.
• Which wins: for a single-value setting (mode, font size, palette), the workspace value wins when present, otherwise the system default applies. Shortcuts merge the same way, field by field — a workspace adds, re-binds, or unbinds a system shortcut, and leaving one alone keeps the system default.

The result is one concrete configuration per workspace, with no “unset” gaps. See Appearance & Theming for the actual controls.

Copy — providers, models, and agents

For providers, models, and agents, the tiers do not merge. Each tier is its own independent list:

• The system tier is a read-only catalog — the built-ins Brisal ships. You can look, but you don’t edit it here.
• To use one, you copy it into a workspace, which gives you an independent, fully-editable copy. The verb differs by kind — you connect a provider, add a model, clone an agent — but the shape is the same: copy-then-own. The copy is a real copy, not a live link; later changes to the original don’t flow into it.

So there’s no “which tier wins” here — the system catalog and your workspace’s copies are two separate lists that coexist. The system tier is the shelf; your workspace is your own bag.

What you can hand-edit on disk

Brisal’s configuration is plain files on disk, so some of it is hand-editable — but the safe, supported path is the UI wherever one exists.

• Palettes are meant to be edited on disk — a palette is just a token-only CSS file you drop into a workspace’s themes/ folder, and it shows up in the picker. This is by design.
• Everything else: prefer the UI. Provider, model, and agent config lives in files too, but editing through the app keeps validation and secure key storage intact. (API keys are never written into config files — they live in your OS credential store; see Providers.)
• The exact file locations and field tables are collected in Config files.

What’s shipped today

The two-tier model is fully in place, but a couple of edges are still being wired up — flagged here so the picture is honest.

What to read next

Settings is the doorway; the concepts it configures are where the detail lives:

• Appearance & Theming — the merge model in action: mode, font size, and palettes-as-data.
• Providers, Models, Agents — the copy model in action: a read-only system catalog you copy into a workspace.
• Skills — the four-tier model, and the external-skills opt-in that Settings exposes.
• Workspaces — the tier that everything customizable sits in, and why the isolation exists.