Настройки, пути и окружение

Папка: ~/.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.

06На Windows папка — %USERPROFILE%\.vibe\. Старое место под ~/.vibevm/ не читается никогда; перенесите всё, что там держали.

Внутри проекта

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).

09Предпочтения сливаются слой за слоем: скаляр из более высокого слоя заменяет, таблицы сливаются глубоко, массивы заменяются целиком. vibe prefs list показывает каждое разрешённое значение с его происхождением, vibe prefs show-origins — вклад каждого слоя, а vibe prefs set пишет один ключ в один слой.

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).

12Три слоя: машина, ~/.vibe/settings.toml, репозиторий, .vibe/settings.toml, и ваша собственная копия для одного проекта, .vibe/settings.local.toml, которую vibe init добавляет в .gitignore, чтобы она никогда не закоммитилась случайно. Старшинство между ними — один фиксированный закон, записанный в бинарнике. Отсутствующий или сломанный файл считается отсутствующим с предупреждением, никогда не ошибкой. Каждый ключ объявлен с типом и умолчанием, а неизвестный ключ — громкое предупреждение на старте и в vibe prefs check. Эти файлы держат то, как vibe выглядит и ведёт себя для вас; свойства проекта живут в манифесте, а закоммиченный файл настроек не может нести секретов. Команды: vibe prefs get, set с --layer, list, check, migrate и 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 без аргументов открывает экран настроек в терминале: дерево страниц слева, отрисованное тем же виджетом, что и vibe tree, и форма справа. Правка поля пишет в слой, который вы выбираете: по умолчанию ваш собственный проектный слой внутри проекта и машинный слой вне его. Поле по запросу показывает происхождение, побеждающий слой и затенённые, а задать или очистить можно один слой, не трогая остальные. Поиск находит настройки по ключу, имени, описанию и синонимам.

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.

Переменные окружения

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).

Старшинство

34Для одной и той же настройки флаг в командной строке побеждает переменную окружения, та побеждает конфигурацию проекта, та — пользовательскую, та — встроенное умолчание. Тот же порядок для реестров: список проекта побеждает список машины.

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

Особые случаи и правила

36Файлы токенов — поверхностные секреты: ограничьте их своим пользователем, никогда не коммитьте, никогда никуда не вставляйте их содержимое. vibe затирает токен в каждом выводе и ошибке, и дисциплина с вашей стороны та же.

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 — вид конфигурации проекта с происхождением каждого значения; vibe prefs — файл предпочтений приложения. Это разные файлы и разные команды.