Moving settings out of WORKFLOW.md
Itervox reads its settings from layered JSONC files — your user file
(~/.itervox/settings.jsonc), the project file (.itervox/settings.jsonc,
committed) and the project-local file (.itervox/settings.local.jsonc,
gitignored) — all described by one published schema.
Since #239 that covers every runtime section: agent, automations,
dependencies, hooks, hub, polling, server, tracker and workspace.
WORKFLOW.md holds the prompt: its body is the Liquid prompt template, and it
stays the import and export format.
Nothing breaks. A workflow that keeps these sections in its front matter
loads and behaves exactly as before, with itervox_schema_version: 2 (no schema
bump). The order is: defaults < your user file (~/.itervox/settings.jsonc) <
WORKFLOW.md front matter < the project file < the project-local file. The
one change in precedence: when the project or local file and the front matter
set the same key, the file wins. Your user file holds personal defaults for
every project, so a project’s own front matter still wins over it.
New projects start migrated. itervox init (every template) and
itervox quickstart write the layered sections to .itervox/settings.jsonc;
this guide is for projects created before that.
What you see before migrating
Section titled “What you see before migrating”itervox doctorprints onedeprecated:line per front-matter key, naming.itervox/settings.jsoncas where it moves.- The daemon’s startup log names the deprecated keys once.
- A key set both in the front matter and in the project or local settings
file is reported once as a conflict (a
WARNING:line initervox doctor, one startup-log line), naming the file whose value is in effect. A user-file value under the front matter is not a conflict.
Migrate
Section titled “Migrate”Preview first; --dry-run writes nothing:
itervox init --update --workflow WORKFLOW.md --dry-runIt prints the keys that would move and the full .itervox/settings.jsonc it
would write. Then run it:
itervox init --update --workflow WORKFLOW.mdWhat it does:
- Writes
WORKFLOW.md.bakwith the workflow as it was, before anything else (an existing backup is not overwritten without--force). - Runs the schema-2 steps it always ran (profile prompts to files, the guardrails block).
- Moves every layered front-matter key into
.itervox/settings.jsonc. YAML comments above, beside and below a moved key become//comments in the same place; a settings file that already exists keeps its own comments and keys. A key the settings file already sets keeps the file’s value — it was already the one in effect — and the front-matter copy is dropped. - Checks that the merged configuration is the same before and after, and refuses the move (writing nothing) if it is not.
Before:
---itervox_schema_version: 2# How Itervox reaches the team's issues.tracker: kind: linear # the team's tracker api_key: $LINEAR_API_KEY project_slug: corehooks: timeout_ms: 90000---Work on {{ issue.identifier }}: {{ issue.title }}.After, .itervox/settings.jsonc:
{ "$schema": "https://itervox.dev/schema/settings.schema.json", // How Itervox reaches the team's issues. "tracker": { "kind": "linear", // the team's tracker "api_key": "$LINEAR_API_KEY", "project_slug": "core", }, "hooks": { "timeout_ms": 90000, },}and WORKFLOW.md keeps the marker and the prompt:
---itervox_schema_version: 2---Work on {{ issue.identifier }}: {{ issue.title }}.What stays in WORKFLOW.md
Section titled “What stays in WORKFLOW.md”- The body (the prompt template) and
itervox_schema_version. - The sections that are not layered:
guardrails,memory,sessions,pr_events. agent.profiles(the profile editor writes them there),agent.available_models(itervox models refreshwrites it there unless a settings file sets it) and the legacyagent.reviewer_prompt(whichitervox init --update --forcemoves into the reviewer’s INSTRUCTIONS.md).- A key holding an inline secret — see below.
Secrets
Section titled “Secrets”Settings files never hold a secret, only a $VAR reference to one:
"api_key": "$LINEAR_API_KEY", with the value in the environment or
.itervox/.env. The move copies a $VAR reference as written (it is never
resolved). A key holding the secret itself (api_key: lin_…, or a URL with a
password) stays in WORKFLOW.md, and the migration names it without printing
the value: put the value in .itervox/.env, set the key to $VAR, and run
itervox init --update again. The Settings page and itervox config set
refuse to write an inline secret.
After migrating
Section titled “After migrating”- Saves. Dashboard and TUI saves of the moved sections (tracker states, the failed state, the project filter and tracker scope, the dependency analysis mode, automations) write the settings file — the project file, or the project-local file when it already sets the key — through the same comment-preserving writer as every other setting. The Settings page’s All settings section lists the new sections, and its layer tab picks the file a save writes.
- Reloads. The daemon watches
.itervox/settings.jsonc,.itervox/settings.local.jsoncand~/.itervox/settings.jsonctogether withWORKFLOW.md, so a hand edit of any of them is applied live, with the same debounce, validation and drain-then-reload as aWORKFLOW.mdedit. A file that does not exist yet is picked up when you create it; deleting one reloads without it. Saves from the Settings page never reload, anditervox config setoritervox init --updatereload a running daemon once. An edit that does not load keeps the running config and shows on the dashboard banner, naming the file and line. See What an edit toWORKFLOW.mdor a settings file does. - Commit
.itervox/settings.jsoncwithWORKFLOW.md. Keep.itervox/settings.local.jsoncand.itervox/.envout of git (itervox init --updatemakes sure they are ignored). - Remove
WORKFLOW.md.bakonce you have reviewed the result.
Moving back
Section titled “Moving back”The front matter still works, so moving a key back is a hand edit: set it in
the front matter and delete it from the project and local settings files
(they would win). itervox export --symphony writes a Symphony WORKFLOW.md from the
merged configuration wherever the keys live.