Settings, paths and environment

The folder: ~/.vibe/

04 The settings home is ~/.vibe (owner, 2026-08-20). This document previously named ~/.config/vibe/config.toml; the code has treated ~/.vibe as canonical all along and the XDG path only as a legacy location an operator is invited to migrate out of. The correction is to this document, not to the tree.

05 Registries keep their own file, and the reason is that one of the two is shareable and the other is not (owner, 2026-08-20). A team can hand a colleague registry.toml — «here is where we get packages from» — without handing over every personal preference in config.toml. Merging them would make the shareable thing inseparable from the private one. This is already how the tree works, so the decision costs nothing to keep and would cost a migration to undo.

06On Windows the folder is %USERPROFILE%\.vibe\. The older location under ~/.vibevm/ is never read; move anything you kept there.

Inside a project

08 L2 — repo-shared (.vibe/settings.toml inside the repo, committed): the team's preferences for this project (analogue: VSCode .vscode/settings.json; IntelliJ .idea/ shared *.xml, RoamingType.DEFAULT).

09Preferences merge layer by layer: a scalar from a higher layer replaces, tables merge deeply, arrays replace as a whole. vibe prefs list shows every resolved value with its origin, vibe prefs show-origins the contribution of each layer, and vibe prefs set writes one key into one layer.

10 Scalars (string/number/boolean): last-wins (the higher layer's value replaces).

11 Arrays: replace, not concatenate — a higher-layer array fully replaces the lower one (the non-obvious VSCode semantics; the dotnet #118204 trap is avoided by making this explicit and documented).

12The three layers are the machine, ~/.vibe/settings.toml, the repository, .vibe/settings.toml, and your own copy for one project, .vibe/settings.local.toml, which vibe init adds to .gitignore so it is never committed by accident. The precedence between them is one fixed law, written in the binary. A missing or broken file counts as absent with a warning, never as an error. Every key is declared with a type and a default, and an unknown key is a loud warning at boot and in vibe prefs check. These files hold how vibe looks and behaves for you; project properties live in the manifest, and a committed settings file may carry no secrets. The commands are vibe prefs get, set with --layer, list, check, migrate and show-origins.

13 L1 — user-machine (~/.vibe/, e.g. ~/.vibe/settings.toml): this user's global defaults on this machine (analogue: VSCode User settings; IntelliJ Application options/*.xml).

14 L3 — user-project (.vibe/settings.local.toml, gitignored): this user's fine-tuning for this specific project (analogue: IntelliJ $WORKSPACE_FILE$ = .idea/workspace.xml, personal, RoamingType.DISABLED).

15 REQ {#gitignore-autogen} (Δ-06, imperative 6). vibe init writes a .gitignore entry for .vibe/settings.local.toml (and the L3 pattern) so a personal file is never accidentally committed — the IntelliJ workspace.xml "keeps popping up" pain (§4.2.3) avoided by default, not by user discipline.

16 REQ {#precedence-law} (Δ-11, imperative 1). The precedence is a law, fixed in one place (this section) and encoded in the binary, never ambiguous:

17 REQ {#missing-is-default}. A missing or corrupt file falls back to defaults — never a hard error (analogous to PROP-037 §9). A parse error is reported as a non-fatal diagnostic and the layer is treated as absent.

18 REQ {#schema-first} (Δ-04, imperative 4). The preference surface is schema-first: every key is declared with type, default, and metadata. Unknown keys (typos, retired names) produce a loud warning at boot and at vibe prefs check — never a silent ignore (the VSCode JSON-schema-gap pain, §4.1.5; the IntelliJ un-validated-XML pain).

19 REQ {#app-prefs-not-project}. The system stores application/user preferences — how vibevm's surfaces look and behave for this user (the TUI's palette/glyph/tier/mode/sort/shape/fold; future vibe-app prefs). It does not store project properties. vibe.toml (the vibe-PROJECT manifest — package/deps/build, the pom.xml analogue, governed by PROP-000 §4 and the Manifest/UserConfig types) is a separate subsystem this contract does not extend or mutate. The split mirrors IntelliJ .idea/ (IDE settings) vs pom.xml (build), and VSCode .vscode/settings.json (workspace UI) vs package.json (project).

20 REQ {#no-secrets-in-committed} (imperative 7; secrets-hygiene flow). Preference files are non-secret (UI look/behaviour). The schema forbids a committed .vibe/settings.toml from carrying a [secret]-style section; vibe prefs check refuses such a file (the .idea/.vscode keystore-leak vector, §4.3.3). Secrets belong in vibe.toml's api_key_env (env-var name) or a per-user keychain — never in app-prefs.

21 REQ {#prefs-command}. The vibe prefs command surface: vibe prefs get <key>, vibe prefs set <key> <value> [--layer L1|L2|L3], vibe prefs list, vibe prefs check (validate all layers), vibe prefs migrate, vibe prefs show-origins [key]. (Distinct from vibe show config, which remains the project-config view.)

22vibe prefs without arguments opens a settings screen in the terminal: a tree of pages on the left, drawn by the same widget as vibe tree, and a form on the right. Editing a field writes to a layer you choose, your own project layer by default inside a project and the machine layer outside one. A field shows its provenance on demand, the winning layer and the shadowed ones, and lets you set or clear one layer without touching the others. A search finds settings by key, name, description and synonyms.

23 REQ {#tree-widget}. The left pane is a tree of pages (groups → pages) rendered through the PROP-037 Tree widget (so it inherits its glyphs, theme, fold, keyboard model — no bespoke renderer). ↑/↓ move, ←/→ fold/expand, Enter opens the focused page's form (§4) in the right pane.

24 REQ {#tree-context}. The tree respects the active project context (which repo's .vibe/ is L2); a no-project session shows only L1 (user-machine) pages.

25 REQ {#write-layer-choice}. Editing a field writes to a chosen layer (default L3 for a project session, L1 for a no-project session), selected in the form — never silently to the wrong layer (the VSCode .vscode-overwrites-contributors pain, §4.1.2). Writing to a layer the key's scope forbids is refused with the reason (PROP-040 §7).

26 REQ {#provenance-view} (PROP-040 §5, §8). A field shows its provenance on demand: the resolved value plus each layer's contribution (default / L1 / L2 / L3 / CLI / env), the winning origin (file:line where known), and which layers are shadowed. This is the visual form of vibe prefs show-origins (PROP-040 §8) — the first-class answer to "which layer is winning?".

27 REQ {#provenance-edit}. From the provenance view the user can override at a specific layer (set L3 without touching L2, or clear L3 to fall back to L2) — direct, layer-aware editing, not a single mystery write.

28 REQ {#settings-search} (Δ-15; the archived settings study §3.7). A search (the vibe-actions Search Everywhere engine, PROP-039 §10 — the same engine the vibe tree TUI uses) finds settings by key, display name, description, and synonyms. Selecting a result opens the owning page with that field focused. The search index is built from the page registry (§2) so a new page is searchable with no extra wiring.

Environment variables

30 It resolves through the established CLI config layering — flag, then a VIBE_OFFLINE environment variable, then a user-config [net] key; the flag wins. This mirrors the resolved-posture pattern already used for --unattended / VIBE_UNATTENDED (output::resolve_unattended).

31 The environment variable VIBEVM_INDEX_URL_<REGISTRY> is the ladder's top rung — the operator's per-run re-point, no longer the only source. Until 2026-08-20 it was the sole locator, deliberately weaker than the manifest field it stood in for (per-shell, per-run, travelling with neither project nor lockfile) — which is why it never closed the requirement above. Now it overrides the key: env beats index_url beats the default, and none at either explicit rung disables the index. The name normalization (ASCII alphanumerics upper-cased, the rest to _``) is unchanged.

32 token_env defaulting. When auth = "token-env" and token_env is omitted, the env-var name is derived from the registry's host: lowercase host, dots and hyphens to underscores, prefixed with VIBEVM_REGISTRY_TOKEN_ and uppercased. For https://gitlab.company.com/vibespecs the default is VIBEVM_REGISTRY_TOKEN_GITLAB_COMPANY_COM. Operators who want stable env-var names across host migrations set token_env explicitly; everyone else gets a working default.

33 $VIBEVM_HOME / $VIBEVM_INSTALL_ROOT (env) → advisory. Still set durably for external JAVA_HOME-style tools, but no longer the source of truth. They may lag (new shells only); vibe vars (§2.14) reconciles, and a managed vibe whose current_exe-derived home disagrees with the env prints a one-line stderr warning at startup (suppressed outside a managed run).

Precedence

34For the same setting, a flag on the command line wins over an environment variable, which wins over the project's configuration, which wins over the user's, which wins over the built-in default. The same order holds for registries: a project's list wins over the machine's.

35 Project-level [[registry]] always overrides the user-level default — the same precedence the UserConfig [env] layer already follows (the project / live value wins).

Edge cases and rules

36Token files are surface secrets: restrict them to your user, never commit them, never paste their contents anywhere. vibe redacts a token in every output and error, and the discipline on your side is the same.

37 20. Token secrecy and adapter scope

38 Decision. Publish tokens, registry-API tokens, and any LLM-provider keys handled by vibevm are surface secrets in the sense of the secrets-hygiene flow (spec://org.vibevm.world/secrets-hygiene/flows/secrets-hygiene/SECRETS-HYGIENE-PROTOCOL#surface-secret): their value MUST NOT appear on any surface vibevm produces, though their source (env-var name, file path) may be printed.

39vibe show config is the project-configuration view with the origin of each value; vibe prefs is the application-preference file. They are different files and different commands.