---
name: settings
description: The agent + vault control panel — a guided interview to tune ANY setting and write it to every file that holds it. Use when the owner says "settings", "tune / adjust / change your settings", "change your address" / "change your name" / "rename you", "tune your personality / voice / style", "change the digest", "add / rename an area", "first-time setup", "personalize", "reconfigure", or "let's set you up". Runs the full first-time pass — the owner's setup interview, also launched by `alexandria interview` — OR jumps to a single setting. Writes both Agent/config.json (structured) and the Config/Content files (prose), keeping them in sync — including propagating an ADDRESS change to every file that embeds it. NOT the daily debrief, and NOT for filing pasted content (that's vault-ingestion).
served: true
---

# Settings — tune the agent + vault

Your control panel. The owner can **tune any setting** — your name, personality, voice, working style, the digest, areas, team, modules, their own details — and you **write it to every file that holds it**, keeping the structured source (`Agent/config.json`) and the prose files in sync. Run it as a **full first-time pass** (walk all categories) or **jump to one setting** to refine. Re-runnable anytime; everything here is **Config/Content — the owner's to change; `update` never overwrites it.**

**Where this runs.** Primarily in **a coding agent opened at the vault** (Claude Code auto-loads this playbook there) — this is where a **new owner lands right after the technician install.** Their vault ships with **`agent.personalized: false`**, so their first message (even a plain **"Hello"**) is routed here by AGENTS.md's *First run* block: you introduce yourself, offer setup, and — on a yes — run this full pass. It also runs in **any chat client connected to the brain's MCP server** — Claude Desktop, claude.ai, a ChatGPT connector, the desktop app — triggered by **"set up my agent"** (first-time) or **"settings"** (to tune one thing). None of those auto-load playbooks the way a coding agent at a checkout does, so the server hands this file over instead: the **`onboarding` tool serves this very file** plus live setup state, and `skills()` / `skill_read('settings')` reach it too. (See *Over chat (the vault MCP)* below for the tool-by-tool verb map.) Either way, make edits through the connected vault (the local MCP or the GitHub connector) and **commit to `main`.** A freshly-deployed vault is deliberately **identity-neutral** — `agent.address` holds the placeholder **"Alexandria"** (the *software's* name — never introduce yourself by it, and never offer it as a default; the first-run pass replaces it, and the legacy `agent.name` key is mirrored for compatibility) *and the vault doesn't even know the owner's name yet* (the technician install collects only delivery/plumbing). So a first-time pass **starts by naming the agent**, **then takes the owner's own details** (which also creates their personal Area), and **ends by handing over the standing context** (the now-correctly-named block for the owner to paste into their assistant — the technician deliberately left it un-pasted) **and setting `agent.personalized: true`** (see *First-time pass — the order* and *Finish*). This full first-time pass **is the owner's *interview*** — the owner starts it by saying **"Hello"** or running **`alexandria interview`** (which opens the vault straight here).

## How settings are stored (know this before writing)
- **Structured facts** live in `Agent/config.json` — the source the engine reads at runtime (name, character, owner, areas, digests, automation, modules).
- **Prose** lives in the Config `.md` files — authored, not generated (`Soul.md` voice, `Working Style.md` rules, `Digest Prompt.md` style).
- Several `.md` files were **rendered once from config.json at install** and then hand-edited — so they **embed** structured values (above all, your **name**). Changing such a value means updating config.json **and** those files **surgically** (find/replace the value; **never re-render** — that would wipe the owner's prose edits).

**The loop for every change:** ask → draft → confirm → write. At **a vault checkout** (operator context) the confirm step may show file-level detail; **over chat, never** — describe what will change in the owner's language ("I'll go by Margo and your personal Area gets created"), not filenames. **Commit once** at the end (`settings: <what changed> <date>`). Write through the vault's normal transport (see AGENTS "Transports").

## The settings map — what lives where
| Setting | `config.json` | Also update (it embeds the value) |
|---|---|---|
| **Address** (the brain's) | `agent.address` (+ mirror the legacy `agent.name`) | `Identity.md`, `Soul.md`, `User.md`, `Digest Prompt.md`, `Standing Context.md` — **and the owner must (re-)paste `Standing Context.md`** into their assistant's standing-instructions field (the address is baked into what they pasted; on the first-run pass this is step 8) |
| **Personality** | `agent.character` | `Soul.md` `## Character` |
| **Voice** | — | `Soul.md` `## Voice` (prose) |
| **Working style** | — | `Working Style.md` (rules) |
| **Digest style** | — | `Digest Prompt.md` (targeted edits; keep the format contract) |
| **Digest time / routing / weather** | `automation.send_hour_local`, `owner_digests[]`, `automation.weather` | — (engine reads config live) |
| **Owner details** | `owner.*` | the owner's **name is embedded across the vault** as the sentinel **`«Owner»`** — find/replace it across the Config/Content files, skipping `.claude/` (see *Owner details* below); plus `User.md` `## Owner`; **first-run: `alexandria seed-area`** creates their `Areas/<owner>/` personal Area |
| **Areas** | `areas[]` | the `Areas/<Area>/` folder + `<Area>.md` + `<Area> TODO.md`; `User.md` area list |
| **Team** | `team[]` | `Roster.md` |
| **Modules** | `modules.enabled` | needs a render — see the category below |
| **Agent email / runner / repo / maintainer** | `agent.email`, `automation.runner`, `repo`, `alexandria.maintainer` | rarely changed; config.json only |
| **People / frameworks** | — | `People/<Name>.md`, `Areas/<owner>/Concepts/` |

## The first-run interview is DRIVEN — don't run it from this file

**Over MCP, a fresh vault's setup interview is served by the server, one question at a
time.** Call **`interview_next`**, ask the owner **exactly the question it returns, as your
whole message**, and send their reply to **`interview_answer`** — which performs the write
itself and hands back a one-line outcome plus the next question. Repeat until `done`.

That is the whole procedure. **Do not** read the categories below and compose your own
interview out of them: this file is a *reference manual* — file lists, propagation rules,
tool verbs — and an interview improvised from it is how owners ended up with five questions
in one message and a running commentary about which files were being patched.

What you get for free by using the driven flow, and would have to remember otherwise:
one question per message; progress the owner can feel (`progress` is in every response);
smart defaults phrased as yes/no; clean skip and resume across a dropped session; and
**no machinery in what you say**, because the payload never contains a path, a tool name
or a placeholder token. If the owner asks what's left, `interview_status` has the agenda —
don't volunteer it.

**Still true while you're in it:** confirmations are the returned `outcome` line and nothing
more; fix any misfire silently rather than handing the owner a repair task; and **don't
raise digests or email** — both ship off, and on a local brain (software in `.alexandria/app/`) email delivery is **not available at all** for now; never offer to set it up (on runner-tier vaults they're later settings the owner asks for).

**Everything below is for tuning ONE setting later** ("change your name", "add an area") —
a lookup, not an interview. That is what the rest of this file is for.

## Over chat (the vault MCP)
The whole pass — first-run and later tuning — also runs from a chat client on the vault's MCP server. **Detection:** `capabilities()` → `personalized: false` means first-run; start with `onboarding()` (live state, a read-only install health check, and this playbook). Surface any install-health **ERROR**s before interviewing — the owner-name **WARN** is expected on a neutral vault. The steps and order are exactly the ones below; only the verbs differ:

| Step | At a vault checkout | Over MCP |
|---|---|---|
| **Address** | edit config.json + find/replace across files | `config_set` `agent.address` (+ `agent.name`, the legacy mirror), then `note_patch` the old address in `Agent/Identity.md`, `Agent/Soul.md`, `Agent/User.md`, `Agent/Digest Prompt.md`, `Agent/Standing Context.md` |
| **Owner details** | `alexandria seed-area` + edits | `seed_area` (the full name) + `area_add` (same name, the standard personal description "Personal & life — (name)'s health, family, finances, and personal admin."), `config_set` `owner.name` / `owner.short_name` / `owner.timezone_default` / `owner.emails`, then `grep` the `«Owner»` sentinel and `note_patch` each hit |
| **Personality & voice / working style / digest** | edit the Config files | `read_file` → `note_patch`/`note_save` on `Agent/Soul.md`, `Agent/Working Style.md`, `Agent/Digest Prompt.md`; `config_set` `agent.character`, `automation.send_hour_local`, `automation.weather`, `owner_digests` |
| **Areas** | config + folders | `area_add` per area (+ routing via `config_set owner_digests`); `area_rename` / `area_remove` to change one later — each moves the folder, both same-named notes and the config entry together; reflect the list in `Agent/User.md` via `note_patch` |
| **Extras — modules** | config + "update yourself" | `config_set` `modules.enabled`, then the owner says **"update yourself"** — module files render via the update flow, never over MCP |
| **Hand over the standing context** | show the file | `read_file` `Agent/Standing Context.md` and show the block; the owner pastes it into their assistant's standing-instructions field |
| **Finish** | flip + commit once | `config_set` `agent.personalized` → `true` (only after `owner.name` is set — the validator upgrades the missing-owner WARN to an ERROR on a personalized vault and refuses the flip) |

**Carve-outs over MCP** — say them, don't fight them: **secrets, seats, and `modules.enabled` rendering** stay owner-on-the-box. Areas are no longer among them — `area_add`/`area_rename`/`area_remove` do the whole move (folder, `<Area>.md`, `<Area> TODO.md`, config entry, digest routing) in one commit; `area_rename` also repoints wikilinks by default, so say what it rewrote. **Every write auto-commits** — there is no batch commit over MCP, so "commit once at the end" becomes: sequence writes deliberately and summarize what changed at the end. **`note_patch` replaces one exact occurrence** — the `«Owner»` sentinel appears many times per file, so patch hit-by-hit with enough surrounding context to be unique (`grep` shows the lines).

## First-time pass — the order
On a fresh vault (the owner just said **"Hello"**), walk the categories in **this order** — each step feeds the next, and the vault starts identity-neutral so the early steps aren't optional:
1. **Address** (the brain's) — the owner's first decision: ask them to pick your address, clearly and concisely. A brain running Alexandria has an **address**, not a name — the owner has the name; the address is what they call this brain. **Make no comment that you already have one, and offer no default** — "Alexandria" is the software, and the config placeholder is never volunteered as a fallback. Keep the machinery out of what you say — don't tell the owner their details get written "everywhere"; just ask, then do it. → propagate the chosen address across the vault (`agent.address`, mirrored to the legacy `agent.name`).
2. **Owner details** — get the owner's **full name first** (it's how you'll address them, and it names their personal Area) → run `alexandria seed-area` to build that Area, **and propagate the name across the vault** by replacing the `«Owner»` sentinel across the Config/Content files (see *Owner details* under Categories). Then short name, timezone (confirm the auto-detected one), emails.
3. **Personality & voice**.
4. **Working style**.
5. **Areas** — their real areas of responsibility. **Ask; don't propose.** A brain ships with
   **no default areas** (`Travel` is the sole exception — the engine's location source, registered
   out of the box, so don't ask whether to add it). Every other area comes from the owner naming
   it. Do not offer a plausible-sounding list — `Investments`, `Finances`, `Board` — because an
   area is not a suggestion: it becomes a folder, a to-do list the digests scan, and a routing
   target, so one the owner merely didn't object to is clutter they now have to maintain. There is
   no per-area privacy flag to offer either: brain access is the boundary (see *How settings are
   stored*).
6. **Extras** — team, modules, people, frameworks (offer; don't force).
7. **Hand over the standing context** — the finalizing step, and the reason it comes *last*: only now that the owner's name and your address are set does `Agent/Standing Context.md` read correctly (the technician left it un-pasted precisely because it embeds both names, and an assistant reading its own settings can't reach the brain's Config at that moment). Show the owner the finalized block and have them paste it into their assistant's **standing-instructions field** — **Claude** calls it your **profile** (Settings → Profile), **ChatGPT** calls it **custom instructions**, other apps have their own name for the same box — so every future chat there opens with brain context and the *right* names. Skippable if they only ever work at a checkout.

Then **Finish** (set `agent.personalized: true`). The owner can **skip any step** and return later via **"settings"**.

**Not in first setup — don't raise them:** **digests** (a brain ships with
`automation.runner: "none"` and no `owner_digests` — daily briefs are a deliberate
later opt-in, configured via "settings" once the owner asks for them) and **email**
(no mailbox is configured; see the email note above). Mentioning either during setup
invites the owner to configure machinery they haven't asked for.

## Categories
For a one-off tweak, ask **"what would you like to tune?"** and jump straight to a category below.

### Address
Confirm the new address, then: set `agent.address` in `config.json` **and mirror it to the legacy `agent.name`** (older engine code and templates read it); **find/replace the old address → the new one** across `Identity.md`, `Soul.md`, `User.md`, `Digest Prompt.md`, and `Standing Context.md` (leave everything else intact). **Also re-alias the agent mailbox** — the neutral vault ships `agent.email`/`ingress_email` as `<owner>+alexandria@…`; swap the `+alexandria` tag for the new address (e.g. `<owner>+pascal@…`). Then tell the owner to **paste `Standing Context.md`** into their assistant's standing-instructions field — the address is baked into the block, so it must carry the new one. (On the **first-run pass** this is the finalizing **step 8**, their *first* paste; on a later change it's a **re-paste**, replacing the block with the old address.)

### Personality & voice → `Soul.md`
- **Character** (the adjectives): update `agent.character` in config.json **and** the `## Character` line.
- **Voice** (how you *sound* — formality, warmth, humor, verbosity, sign-off, words to favor/avoid): rewrite the `## Voice` bullets, keeping the "speak as <name>, first person" anchor.

### Working style → `Working Style.md`
Durable rules under its three headings — **Preferences** (deliverable format/length), **Working & decision style** (fast vs deliberate, options vs a recommendation, bluntness, async vs realtime), **Standing constraints** (never-do's, approval gates, egress rules). One rule per line in the file's format: `- [<today>] (confidence: high) <rule> — src: settings`. Only real, stated rules — don't pad.

### Digest → `Digest Prompt.md` + config.json
- **Style** — tight vs thorough; briefing depth per item; which sections matter; greeting tone; always-include/omit. Make **targeted edits inside the fenced block**, preserving its structure + HTML rules (you're tuning style, not rewriting the engine's contract).
- **Timing / routing / weather** — send hour → `automation.send_hour_local`; who gets what → `owner_digests[]` (keep it a conflict-free partition: any dedicated digests + one `rest` catch-all); the weather line → `automation.weather`.

### Owner details → config.json + `User.md` + the whole vault + their personal Area
Name / short name / aliases / timezone / emails: update `owner.*` in config.json **and** the `## Owner` block in `User.md`.

**Propagate the name across the vault — a neutral vault embeds it as the sentinel `«Owner»`.** A freshly-deployed vault has no owner name, so every place that addresses the owner renders the placeholder **`«Owner»`** — in `Identity.md`, `Soul.md`, `User.md`, `Working Style.md`, `Digest Prompt.md`, `Standing Context.md`, `SECRETS.md`, the Travel schedule, and any enabled module's digest prompt. As soon as you have the name, **find/replace `«Owner»` → the owner's name**: their **short name** in prose (the possessives, e.g. "«Owner»'s time" → "Sam's time") and their **full name** in `User.md`'s `## Owner` `**Name:**` field. **Grep the vault for `«Owner»`** so nothing is missed — but **skip the playbooks — `Agent/skills/` and `.claude/skills/`** (they *document* this token — including this file; they aren't owner-name slots, so replacing them would corrupt the playbook). Grepping the token across the Config/Content prose (rather than a fixed file list) catches every current *and future* file that embeds the name — the owner-side twin of the agent-**Name** propagation above. (`SECRETS.md` and `Standing Context.md` are Core and will also re-render correctly from `config.json` on the next `update`, but replace the token now so the vault reads right immediately.)

**On the first-run pass the vault is nameless** — as soon as you have the owner's **full name**, run **`alexandria seed-area --vault . --name "<Full Name>"`** (over MCP: the **`seed_area`** tool, plus **`area_add`** for the matching config entry) to create their personal Area (`Areas/<Name>/` + the `Concepts/` scaffold) that the technician install deliberately left out. It's **write-once** (safe to re-run; never clobbers their notes).

### Areas → config.json + the area folder
- **Add** — append to `areas[]` (`name`, a real 2–3 sentence `description`, `threads`); create `Areas/<Area>/<Area>.md` (a genuine folder note) + `Areas/<Area>/<Area> TODO.md`; add it to `User.md`'s area list.
- **Rename** — update `areas[]`, `git mv` the folder + its notes, fix the `[[wikilinks]]`, update `User.md`.
- **Edit** — description / threads: update `areas[]` and the area's home note.

### Team → config.json + `Roster.md`
Add/remove members in `team[]` (name, role, email, scope, timezone, send hour, reply) and reflect them in `Roster.md`. (Requires the `team-digests` module — see below.)

### Modules → config.json (+ an update)
Enable/disable in `modules.enabled`. **Enabling adds files** (a render), which the in-vault agent can't do — so after the config edit, tell the owner to say **"update yourself"** (the `alexandria-update` flow renders the newly-enabled module's files). Disabling: remove it from `modules.enabled`; its files can be cleaned up on the owner's say-so.

### People & frameworks → content
- **People** — the owner's key contacts: one `People/<Name>.md` each (from `People/_template.md`) — frontmatter + `## Context`, letting History/threads accrue.
- **Frameworks** — the owner's own theses / mental models: `Areas/<owner>/Concepts/` notes (`type: concept`) in their words.

## Finish
Summarize what changed in which files. **If this was the first-run pass** (the vault shipped un-personalized), set **`agent.personalized: true`** in `Agent/config.json` now — that flips the vault out of first-run mode so you stop greeting the owner as brand-new. Then **commit once** (`settings: <summary> <date>`). **The standing context block:** on the **first-run pass** that's **step 8** above — the owner's *first* paste of `Standing Context.md` into their assistant's standing-instructions field, now that it carries the real names (don't skip it if they use a chat client at all). On a **later one-off change**, if the **agent or owner name changed**, remind them to **re-paste** it (both names are baked into what they pasted before). Note they can say **"settings"** anytime to tune more, and that you keep sharpening Working Style automatically from the daily debrief.
