> ## Documentation Index
> Fetch the complete documentation index at: https://soulforge.proxysoul.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Presets

> Shareable config bundles loaded by name, path, or URL.

Presets are reusable config bundles — task router rules, agent features, theme, instruction files, custom providers — that merge into your `AppConfig` at boot. Useful for syncing settings across machines, sharing a team setup, or pinning a known-good config to a repo.

## Three ways to load

Presets resolve in this order — later wins:

1. **Global** — `~/.soulforge/config.json` → `presets[]`
2. **Project** — `<cwd>/.soulforge/config.json` → `presets[]`
3. **CLI** — `--plugin <spec>` (stackable) or `SOULFORGE_PRESETS=spec1,spec2`

```json theme={null}
{
  "presets": [
    "team/standard",
    "./presets/local.json",
    "https://example.com/forge-preset.json"
  ]
}
```

```bash theme={null}
# One-off CLI overlay (multiple --plugin flags stack)
soulforge --plugin team/standard --plugin ./extra.json

# Same via env
SOULFORGE_PRESETS=team/standard,./extra.json soulforge
```

## Spec formats

| Form          | Example                                  |
| ------------- | ---------------------------------------- |
| Registry id   | `team/standard`                          |
| Absolute path | `/etc/forge/preset.json`                 |
| Relative path | `./presets/local.json`, `../shared.json` |
| Home path     | `~/forge/preset.json`                    |
| URL           | `https://example.com/preset.json`        |

Specs must be at least 2 characters and match `^(https?:\/\/|\.\/|\.\.\/|\/|~\/)|^[a-zA-Z0-9][a-zA-Z0-9._/-]{1,}$`. Invalid specs are logged and skipped.

## Wizard

```bash theme={null}
soulforge --presets
# or
soulforge presets
```

Interactive picker — browse the registry, preview overlays, add to global or project scope.

## Boot output

By default preset resolution is silent on success. Failures print one short line to stderr (one bad preset never blocks boot — fail-open). For full traces:

```bash theme={null}
soulforge --verbose-presets
```

You'll see one line per spec (`ok` or `fail`) with the resolved source.

## How merging works

Presets are resolved to plain `AppConfig` patches, then merged on top of `DEFAULT_CONFIG` in load order. The diff against defaults becomes the `presetOverlay` — applied before `loadConfig()` returns, so every consumer sees the merged shape transparently.

Your `~/.soulforge/config.json` is never rewritten. Removing the preset entry restores the prior behaviour on next launch.

## Authoring

A preset is a JSON file (or registry-hosted JSON) with any subset of `AppConfig` fields:

```json theme={null}
{
  "name": "team-standard",
  "description": "Team default router + theme + privacy",
  "config": {
    "theme": { "name": "catppuccin" },
    "taskRouter": {
      "spark": "anthropic/claude-haiku-4-5",
      "ember": "anthropic/claude-sonnet-4-5"
    },
    "agentFeatures": {
      "desloppify": true,
      "tierRouting": true
    },
    "forbiddenPatterns": ["*.env", "secrets/**"]
  }
}
```

Drop it under `~/.soulforge/presets/<name>.json` to make it discoverable, or host anywhere reachable by HTTPS.

## Environment

| Variable            | Purpose                                                        |
| ------------------- | -------------------------------------------------------------- |
| `SOULFORGE_PRESETS` | Comma-separated specs (set automatically by `--plugin` flags). |

## See also

* [Configuration](/reference/configuration) — the AppConfig shape presets layer onto.
* [Task router](/recipes/task-router) — the most-changed slot in shared presets.