# Settings spaces

Insula keeps configuration in three spaces: this computer (global `~/.insula`), the open project (`<project>/.insula`), and your signed-in account (across machines). Where something lives determines who shares it, what overrides what, and whether it follows you to another computer.

## Global (this computer)

Global settings live under `~/.insula/` (or the platform home equivalent on Windows). Open **Settings** from the top bar at any time; that window is not tied to a project.

From Settings you configure:

- Providers and Active Models (Chat, Build, Embeddings, Image)
- Theme
- Editor preferences (word wrap, minimap, line numbers, font size, tab size)
- Agent preferences (terminal allowlist, compaction)
- Insight preferences (image understanding)

The same home directory also holds personal rules, skills, Global macros, and `languages.json`.

Machine-only project data (Insight index, plans, chats, kanban, notes) lives under `~/.insula/projects/...`. That data stays on this computer and is never part of the repository.

## Project (shareable)

Project settings live under `<project>/.insula/`. Opening a project does not create this directory. Add it when you want shared configuration: ask the agent to load `skill_bootstrap-insula`, or create the files yourself. Confirm before anything is written.

A project `.insula` may contain:

| Kind | Path | Purpose |
|------|------|---------|
| Rules | `rules/` | Conventions delivered to the agent for this project |
| Skills | `skills/<name>/SKILL.md` | Procedures the agent can load (`/skill_...`) |
| Macros | `macros/` | Local Command Panel macros for this project |
| Languages | `languages.json` | Optional editor language and language-server overrides |

Commit these files when the team should share them. Keep provider keys, theme, Insight indexes, kanban, notes, and plans out of project `.insula`; those belong under global home storage.

## How layers combine

| Kind | Behavior |
|------|----------|
| Rules | If the project has `rules/`, those rules fully replace global rules for that project |
| Skills | Global and project skills merge; when names match, the project skill is used |
| Languages | Shipped defaults, then global `languages.json`, then project `languages.json`; matching extension keys or server ids use the project entry |
| Macros | Global, Local, and Account are three separate sets. The Command Panel scope selects which set you edit and fire |

## Account (across machines)

Account features live in the **Account** window (dash → Account), separate from Settings.

1. **Sign in** unlocks account features through the browser login flow.
2. **Cloud backup** (signed in, then enable backup) syncs providers (including API keys and Active Models) and app preferences (theme, editor, agent, Insight). When both this computer and Insula already have providers, choose **Restore from Insula** or **Keep this computer**.
3. **Account macros** sync when you are signed in. Cloud backup does not need to be enabled. Edit them in the Command Panel under the Account scope.

These stay on the local machine: project files, Insight indexes, plans, session transcripts, Global macros, and Local macros.

On a remote connection, Settings from this computer can be pushed to the host so agents match. Project `.insula` and language configuration stay with the remote host. See [Remote servers](/wiki/08-remote-servers).

## Practical workflows

1. Personal defaults on one machine: use Settings and files under `~/.insula`.
2. Team conventions: put rules, skills, and optional Local macros or `languages.json` in `<project>/.insula` and commit them. Adding project `rules/` turns off personal global rules for that project.
3. Same setup on a second machine: sign in, enable Cloud backup for providers and app preferences, and use Account macros for portable prompts.
4. Project-only shortcuts: use Local macros in the Command Panel while a project is open.

## Related topics

- [Skills and rules](/wiki/03-skills-and-rules)
- [Models](/wiki/04-models)
- [Macros](/wiki/06-macros)
- [Insight DB](/wiki/07-insight-db)
- [Remote servers](/wiki/08-remote-servers)