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](../../common/PROP-000.xml) 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).

REQ {#new-subsystem}. `vibe-settings` is a **new crate**, parallel to `vibe-core`'s project-config — owning its own schema, loaders, resolver, and persistence. Project-config is reused only as architectural reference (how layering is *not* done today), never as the object of extension.

REQ {#frontend-agnostic}. The crate is **frontend-agnostic** — zero rendering dependencies (no `ratatui`/`crossterm`/GUI toolkit). Preferences are data + logic-on-data; any surface (the TUI, a future GUI, the headless AIUI) reads them through the resolver (§5). This is what makes the AIUI and the settings-UI (PROP-041) possible.

REQ {#three-levels}. Preferences resolve over **three file layers**, lowest-to-highest precedence:

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

A higher layer **overrides** a lower one per the merge semantics (§4). L3 wins among file layers; `--set`/`--config` CLI flags and `VIBE_*` env vars override every file layer. This law is the direct answer to the VSCode precedence-confusion pain (`vibevm/vibespecs/research` §4.1.1, issue #228983): there is one documented order, machine-readable, and introspectable (§8).

REQ {#cli-layers-not-replaces} (Δ-11, imperative 10). A CLI `--config <file>` flag **adds a layer** above the file layers (it does not replace them, à la Helix `-c` — `vibevm/vibespecs/research` §4.4.3); a `--set key=value` flag sets one key in that top layer. Cascade shadows (a higher layer overriding a lower) are **reported**, never silent (the `.editorconfig root=true` pitfall, §4.4.6).

REQ {#file-layout} (Δ-05, imperative 5). Exactly these files carry preferences:

REQ {#role-marker}. Each file carries a header comment naming its role and precedence (e.g. `# L2 — repo-shared (committed). Overrides L1; overridden by L3 and CLI/env.`), so a reader never confuses layers (the `.idea` what-to-commit pain, §4.2.1).

REQ {#dotvibe-not-cache} (risk R1). `.vibe/` today is a cache dir (`.vibe/cache/...`, [PROP-000 §13](../../common/PROP-000.xml)). Preference files live at `.vibe/settings.toml` / `.vibe/settings.local.toml` — siblings of `cache/`, never inside it. The layout is fixed by this contract so cache-vs-prefs never collide.

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.

REQ {#merge-algorithm} (Δ-01, imperative 3). Layers merge left-to-right (lowest → highest) by **deep-merge** (`vibevm/vibespecs/research` §2.4 — the VSCode `ConfigurationModel.mergeContents` semantics, re-implemented clean-room):

REQ {#merge-strategy-opt-in} (Δ-01). A schema key may declare a `merge` strategy for arrays: `replace` (default) | `append` | `prepend` | `merge-by-key`. The default `replace` is the safe, predictable choice; opt-in strategies are explicit per-key so no array is ever merged silently.

REQ {#null-semantics} (imperative; §4.3.4). `null` means **"explicitly unset — shadow the parent with empty"**; deleting a key means **"fall back to the parent layer"**. The two are distinct and documented.

REQ {#resolved-prefs} (Δ-02). A single resolver entry point produces a **`ResolvedPrefs`** — the composed view over `default + L1 + L2 + L3 (+ CLI/env)`, with **per-field provenance**. Consumers (the TUI, the future vibe app, the AIUI) read resolved values through this one entry; no consumer reads a raw layer.

REQ {#inspect} (Δ-02, Δ-12; `vibevm/vibespecs/research` §2.8). `inspect(key)` returns, for one key:

This is the **key AIUI API** (the VSCode `IConfigurationValue<T>` shape, clean-room) — one operation yields the effective value *and* which layer established it *and* whether a higher layer shadows it. This is what IntelliJ lacks (`vibevm/vibespecs/research` §3.9 — three disconnected query paths, no unified introspection); vibevm designs it in from day one.

REQ {#unified-introspection} (Δ-12). The schema is a **single typed, tagged, enumerable tree**: `keys() → Iterator<KeyMeta>`, `get(path) → Value`, `set(path, value, layer)`. An agent (or test, or CLI) can enumerate every setting and read/write it **without knowing service class names or parsing files** — the introspection bottleneck of IntelliJ (§3.9) is avoided by construction.

REQ {#get-section}. `get(section)` returns a whole namespace as a typed value (e.g. all `tree.*` prefs), mirroring VSCode's section access.

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

REQ {#schema-fields}. A `KeyMeta` carries: `path` (dotted), `type` (bool/int/string/enum/array/table), `default`, `description` (mandatory, non-empty), `scope` (§7), `applies` (§10), `merge` (§4), `deprecated`/`replaced_by` (below), `restricted` (§11.3-equivalent for untrusted L2).

REQ {#deprecation} (Δ-08, imperative 8). A key may be `deprecated` with a `replaced_by` target. Boot emits a warning naming the migration; `vibe prefs migrate` rewrites the file automatically. No "greyed-out-in-JSON" non-migration (the VSCode §4.1.6 / IntelliJ PersistentStateComponent §4.2.5 pain).

REQ {#diff-from-default} (Δ-08; `vibevm/vibespecs/research` §3.4). Persistence writes **only non-default values** (IntelliJ's `SkipDefaultValuesSerializationFilters`, clean-room): tiny files, clean diffs, trivial reset-to-default (delete the key). A file that drifts back to byte-identical-with-default is collapsed to empty.

REQ {#scope-metadata} (Δ-07; `vibevm/vibespecs/research` §2.2). Every key declares a **`scope`** governing where it may be set and whether it roams:

REQ {#scope-matrix}. The scope→writable-layer matrix is encoded in the resolver; writing a key to a layer that its scope forbids is a typed error (the VSCode scope-target validation, `vibevm/vibespecs/research` §2.2), never a silent drop.

REQ {#show-origins} (Δ-03, imperative 2). `vibe prefs show-origins [key]` prints, for every key (or the one named), the **resolved value and its origin** — which layer set it, with `file:line` where known (the git `--show-origin` + VSCode `inspect()` combined). This is the first-class answer to "which layer is winning?" (§4.1.1) and the debugging surface for the AIUI.

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

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.

REQ {#path-classifier} (Δ-06; `vibevm/vibespecs/research` §3.2). The layer of a file is **mechanically determined by its path**, overriding any declaration (IntelliJ's `getEffectiveRoamingType` — path-macro-beats- declaration, clean-room): `settings.local.toml` is L3 *because of its name*, not because its author remembered to mark it so. This makes the `badWorkspaceComponents`-style blacklist (§3.2) impossible — the wrong layer cannot be chosen by mistake.

REQ {#change-events} (Δ-09; `vibevm/vibespecs/research` §2.8). The resolver emits a **granular change event** when a layer mutates: `{ affected_keys: Set<path>, source_layer }`. A subscriber filters by `affects(namespace)` (prefix-match) so a TUI component re-renders only its own keys, not everything (VSCode `IConfigurationChangeEvent`, clean-room).

REQ {#applies} (Δ-09, imperative 9). Each key declares `applies = "live" | "reload" | "restart"` — whether a change takes effect immediately, on next surface reload, or only after restart. A surface shows the indicator (the hot-reload-vs-restart pain, §4.3.2) so the user is never left guessing.

REQ {#file-watch}. Layer files are watched; an external edit reloads the layer and re-resolves (the VSCode debounced file-watcher, §2.3) — edit your `~/.vibe/settings.toml` in `$EDITOR` and the TUI picks it up.

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.

REQ {#restricted-l2} (`vibevm/vibespecs/research` §2.5). A key may be `restricted` — its value is read from L2 (the committed, possibly-cloned repo) only when the project is **trusted**; in an untrusted clone, restricted keys fall back to L1/default (the VSCode `restricted`/trust-gating pattern, clean-room).

REQ {#crate-boundary}. `vibe-settings` owns: the schema/registry, the three loaders, the `ResolvedPrefs` resolver + inspect/get/set API, change-events, validation, the `vibe prefs` command plumbing (logic; the CLI surface lives in `vibe-cli`). It depends on `vibe-core` only for shared error/path utilities, never on `vibe-cli` or any rendering crate.

REQ {#vs-project-config}. Project-config (`Manifest`/`UserConfig`) and app-prefs (`vibe-settings`) are **disjoint**: different files (`vibe.toml`/`~/.config/vibe/config.toml` vs `~/.vibe/`/`.vibe/`), different commands (`vibe show config` vs `vibe prefs`), different schemas. The two never merge into one resolver (risk R8 — collision).

REQ {#vs-vibe-actions}. `vibe-settings` is the *data* layer (what the prefs are); `vibe-actions` ([PROP-039](../vibe-actions/PROP-039-action-system.xml)) is the *behaviour* layer (what the TUI does). A preference may gate an action's enablement (the action reads `ResolvedPrefs`), but the two crates do not depend on each other's internals.

REQ. The crate follows the AI-Native Rust discipline (`spec://org.vibevm.ai-native/core-ai-native`): cells with single registration points and no sibling-cell coupling; `specmark::scope!` on every file citing the governing PROP-040 anchor; per-fn `#[spec(implements = "spec://…#…")]` where a fn implements a specific REQ; `anyhow` at the command edge, typed errors citing REQs in library layers; no `unwrap`/`expect` in domain logic; the ≤600-line file budget; green `conform` + `specmap` at every commit. Each REQ anchor here is an addressable target the code traces to.

The settings UI (TUI surface) is [PROP-041](PROP-041-settings-ui.xml): the Configurable-EP-style page registry (Δ-15), the settings-tree widget, per-type edit forms, the provenance view, validation rendering, and search (Δ-16). It consumes this crate's inspect/get/set API and is built on the TUI (PROP-037) in Step 4 of the meta-plan.