@sous-io/sous 0.2.36 → 1.0.1

package/docs/markdown/config-discovery.md

@@ -1,7 +1,9 @@
 # Discovery and Overrides
 
 How sous locates a project's configuration, and every way to override it. Discovery runs on
-every command; there is no opt-out.
+every command; there is no opt-out. It runs once, when sous starts, and finds exactly one project:
+every sous process (a CLI run, watch mode, or `sous mcp` for its whole life) serves the project it
+started in.
 
 ## Locating the primary config
 
@@ -14,10 +16,19 @@ Precedence, highest first. Flags beat env vars; both beat walk-up discovery:
 5. Walk UP from the working directory to the filesystem root, taking the first `.sous/`
    directory that holds a primary config. A `.sous/` without one does not stop the walk.
 
-A primary config is named `sous.config.js`, `sous.config.mjs`, `sous.config.json`,
-`sous.config.jsonc` or `sous.config.yaml`. The `.jsonc` form is JSON with comments: line comments,
+A primary config is named `sous.config.js`, `sous.config.mjs`, `sous.config.ts`,
+`sous.config.json`, `sous.config.jsonc` or `sous.config.yaml`. The `.jsonc` form is JSON with comments: line comments,
 block comments and trailing commas are all allowed in it.
 
+## The project root
+
+The project root is the directory that holds the `.sous/` directory the config was found in. When
+`--config` names a file outside any `.sous/`, the root is the parent of the directory holding that
+file. A project cannot set its root anywhere else: sous publishes it as the auto-variable
+`${projectRoot}`, and setting `projectRoot` in any `_vars` block is an error.
+
+## How a location value is read
+
 Every flag or env value resolves with the same rules. It may point at:
 
 - a config file directly,
@@ -29,22 +40,22 @@ bare `export SOUS_CONFIG=`) is treated as unset and falls through to the next ti
 hijacks resolution. Error messages name the source that was actually set (`--sous-dir`,
 `SOUS_CONFIG`, and so on), not a generic flag.
 
-## Locating the conf.d layer directory
+## Locating the conf.d directory
 
 Precedence: `--sous-confd <path>` flag, then `SOUS_CONFD` env var, then the default
-`<sousDir>/conf.d`. An override flows everywhere the default would: layer enumeration, the
-duplicate-baseName check, and watch-mode reload.
+`<sousDir>/conf.d`. An override applies everywhere the default would: finding the `conf.d` files,
+the check for file names that differ only by extension (below), and reloading in watch mode.
 
 ## Env file layering
 
-After discovery, sous loads two optional files from the discovered `.sous/` into the process
-environment:
+After discovery, sous reads two optional files from the discovered `.sous/` into the environment
+every plugin sees:
 
 - `.env.local`: gitignored; machine-specific values and secrets
 - `.env`: committed; team-shared defaults
 
 Load order is `.env.local` first, then `.env`, and no load ever overwrites a value that is
-already set. Effective precedence is therefore: real shell environment, then `.env.local`, then
+already set. Config expressions read the result as `env.<NAME>`. Effective precedence is therefore: real shell environment, then `.env.local`, then
 `.env`. The syntax is deliberately small (not a shell): `KEY=value` lines, `#` comments, an
 optional `export ` prefix, single or double quoted values (`\n` and `\t` expand inside double
 quotes), and inline `# comment` stripped from unquoted values. Lines without `=` are ignored.
@@ -60,12 +71,12 @@ All are hard `ConfigError`s; sous never guesses:
 - **No config found**: the error lists every directory checked during the walk and names the two
   fixes: run `sous init` in the project's root directory, which writes the config and everything
   else a first build needs, or pass `--config <path>`.
-- **Multiple primary configs**: two or more of `sous.config.js|mjs|json|jsonc|yaml` in the same
+- **Multiple primary configs**: two or more of `sous.config.js|mjs|ts|json|jsonc|yaml` in the same
   `.sous/` is an error naming every candidate.
-- **Duplicate layer baseNames**: any two loaded files (primary or conf.d) whose names differ
-  only by extension is an error naming both files, because their merge order would otherwise
-  depend on extension. `500-repos.json` and `500-repos.jsonc` collide for the same reason, which
-  is what keeps a layer sous is migrating to `.jsonc` from being loaded twice.
+- **Names that differ only by extension**: any two loaded files (primary or conf.d) whose names
+  differ only by extension is an error naming both files, because their merge order would
+  otherwise depend on the extension. `500-repos.json` and `500-repos.jsonc` collide for the same reason, which
+  is what keeps a file sous is migrating to `.jsonc` from being loaded twice.
 
 ## Interaction with `sous launch` pass-through
 

package/docs/markdown/config-inspection.md

@@ -2,42 +2,60 @@
 
 ## The validation pipeline
 
-Every command validates the config on load, in this order:
+Every command builds and validates the config before it does its work, in this order:
 
-1. The kernel merges all layers (any layer failure names the file).
-2. The legacy-schema guard rejects the removed multi-project keys (`projects`,
+1. Sous builds the config from every file, recipe and plugin (any config file failure names the
+   file; see [Layers and merging](config-layers.md)). Config expressions are evaluated as each file
+   is applied.
+2. A check for the old config format rejects the removed multi-project keys (`projects`,
    `defaultProject`) with a migration message.
-3. A strict schema validates the merged result: unknown keys at ANY level are rejected with the
-   full path and a typo hint; a target must have exactly one of `entryPoint` / `entryGlob`;
-   `version`, when present, must be `1` (anything else fails as unsupported by this sous
-   version).
+3. The built config is checked against the schema of every config key. Each plugin declares the
+   keys it reads, with their schema and defaults, so a key no loaded plugin declares is unknown.
+   Unknown keys at ANY level are rejected with the full path and a typo hint; a target must have
+   exactly one of `entryPoint`, `entryGlob` or `content`; `version`, when present, must be `1`
+   (anything else fails as unsupported by this sous version). Validation runs after values
+   resolve, so a value built from a variable is checked.
 4. Variable resolution and substitution run as values are used; `sous config validate` runs them
    eagerly (below).
 
-Validation applies to the MERGED config only. A `conf.d/` fragment on its own does not need to
-be a complete config; it only needs to use schema-known keys.
+Validation applies to the BUILT config only. A `conf.d/` file on its own does not need to be a
+complete config; it only needs to use known keys.
 
 ## The JSON Schema artifact
 
-Sous ships `sous.config.schema.json` at the package root (generated from the same schema that
-validates at load time). A JSON config can bind it for editor autocompletion and external
-tooling:
+Sous ships `sous.config.schema.json` at the package root, for editor autocompletion and external
+tooling. A JSON config can bind it:
 
 ```json
 { "$schema": "./path/to/sous.config.schema.json" }
 ```
 
-The `$schema` key is accepted at the top level and ignored by sous itself. A config written by
-`sous init --format json` binds it to the same artifact as published on GitHub for the running
-version, so an editor resolves it without a path into the installed package; point it at the
-package-local copy instead when the editor should work offline.
+The `$schema` key is accepted at the top level and ignored by sous itself. Point it at the
+package-local copy, or at the artifact published on GitHub for the version you run.
+
+?> Because each plugin declares its own config keys, the published schema file may not know a key
+that a plugin adds. An editor may flag such a key even though sous accepts it; `sous config validate`
+is the check that counts.
 
 ## sous config show
 
-Prints the full merged config as pretty JSON: the config as written, after layer merging but
-BEFORE variable resolution. Output is machine-readable by contract: the decorative header and
-any error text go to stderr, so `sous config show | jq .` always receives either valid JSON or
-nothing. Colorized only when stdout is a TTY.
+Prints the full built config as pretty JSON, with config expressions evaluated: what sous will do on
+this machine. Output is machine-readable by contract: the decorative header and any error text go to
+stderr, so `sous config show | jq .` always receives either valid JSON or nothing. Colorized only
+when stdout is a TTY.
+
+- `--layers` shows each change, in order, and what made it (a file, a recipe or a plugin): for a
+  config file, the expression as written, what it evaluated to and the values it read; for code,
+  each builder operation it ran and the primitive patches it made
+  ([Patches](config-layers.md#patches) explains both). It ends with the result and the number of passes the config took to
+  settle.
+- `--raw` prints each config file as written, in order.
+
+```text
+confd/620-no-diagrams.js
+  removeWhere compilation.targets                  ← a builder operation
+    removeIndex compilation.targets[7]             ← a primitive patch
+```
 
 ## sous config get
 
@@ -51,22 +69,26 @@ sous config get compilation.targets[0].entryPoint
 Scalars print raw (no quotes); objects and arrays print as pretty JSON. A missing path exits
 non-zero with a message on stderr.
 
-`--layers` adds provenance: for each loaded layer whose cumulative merge CHANGED the value at
-that path, one line prints the layer file and the old and new values, starting from `(unset)`.
-This answers "which file set this?" directly:
+`--layers` adds where the value came from: every file, recipe or plugin that changed the value at
+that path, in order, with its change. This answers "which file or plugin set this?" directly:
 
-```bash
-sous config get tools.claude.command --layers
+```text
+$ sous config get subscriptions."tool-usage/automated-browser-tasks".enabled --layers
+conf.d/510-subscriptions.jsonc   (not set)
+conf.d/610-mac.jsonc             { "$if": { "expr": "host.platform == 'darwin'", "then": false } }
+                                 → false   (host.platform = "darwin")
+result                           false     (settled after 1 pass)
 ```
 
+`sous plugins show` lists every plugin and what it adds or replaces, and `--timings` on any command
+prints how long each step took, each config file included.
+
 ## sous config validate
 
-Runs the whole pipeline eagerly: discovery, kernel merge, legacy guard, schema, then FULL
+Runs every check above at once: discovery, the config build, the old-format check, schema, then FULL
 variable resolution including compilation, tools and watch config. This surfaces the errors
 schema validation alone cannot: variable cycles, undefined `${refs}`, and bad substitutions in
-entry points and destinations. On success it prints a short summary (config file, layer count,
-target count, tools) and exits 0; on failure it prints the `ConfigError` and exits non-zero.
+entry points and destinations. On success it prints a short summary of the config and exits 0; on failure it prints the `ConfigError` and exits non-zero.
 
-All three commands honor the same config-locating flags and env vars as every other command
-(`--config`/`-c`/`--sous-config`, `--sous-dir`, `--sous-confd`, `SOUS_CONFIG`, `SOUS_DIR`,
-`SOUS_CONFD`); see [Discovery and overrides](config-discovery.md).
+All three commands honor the same config-locating flags and env vars as every other command; see
+[Discovery and overrides](config-discovery.md).

package/docs/markdown/config-layers.md

@@ -1,92 +1,194 @@
 # Layers and Merging
 
-Every config source (the primary file plus each `conf.d/` layer) is loaded by one subprocess,
-the config kernel, which merges everything into a single cumulative config and returns it as
-plain JSON.
+Sous builds one config for a project from many sources: the primary `sous.config.*` file, each
+file in `conf.d/`, the config files recipes ship, the entries sous adds itself (the official
+repository and the `core` subscription), and any plugin that changes the config. Sous combines
+them all before any command does its work, and again after a command that changed the config.
 
-## Load order
+## Which files are read
 
-1. The primary `sous.config.*` file.
-2. Every `*.js|mjs|json|jsonc|yaml` file directly inside `conf.d/` (non-recursive), sorted BYTEWISE
-   by filename. The sort is locale-independent and per-machine stable, but it is not numeric:
-   `10-a.json` sorts before `2-b.json` because the character `1` precedes `2`. Zero-pad numeric
-   prefixes (`02-`, `10-`) when ordering matters.
+- The primary `sous.config.*` file in `.sous/`.
+- Every file directly inside `conf.d/` (not its subdirectories).
 
-A `.jsonc` layer is JSON with comments: line comments, block comments and trailing commas are all
-allowed in it, and it merges exactly like a `.json` one. The layers sous manages for you are
-written that way, so each can say in the file itself what it holds.
+A `.json`, `.jsonc` or `.yaml` file is parsed; a `.js`, `.mjs` or `.ts` file is imported in
+the sous process itself. A `.jsonc` file is JSON with comments: line comments, block comments and
+trailing commas are all allowed in it. A file is read from disk once per build.
 
-## JSON forcing
+## Load order, and why your files win
 
-Each layer's contribution passes through a JSON round-trip BEFORE merging:
+The `conf.d/` files are applied after the primary config, in the order of the number each name
+starts with. Files with the same number are applied in filename order (bytewise, the same on every
+machine), and a file whose name starts with no number is applied as if it were numbered 500; a number above 9999 counts as 9999:
 
-- Functions and `undefined` values are dropped.
-- `RegExp` becomes `{}`; `Date` becomes its ISO string.
-- The final merged config is round-tripped once more on the way out.
+```text
+plugins and recipes → sous.config.* → conf.d/500-repos → conf.d/510-subscriptions → conf.d/610-mac
+```
 
-Write configs as plain data; behavior belongs in `configure()` (below), which runs inside the
-kernel before serialization.
+Give every file a number of the same length (three digits, as the files sous writes have) so the
+order is obvious from a directory listing.
 
-## Deep merge semantics
+Your files are applied last, after every plugin and recipe. Whenever a plugin or a recipe's config
+file changes the config, sous applies your `sous.config.*` and `conf.d` files again after it. So
+when a plugin or a recipe sets a key that one of your files also sets, your value wins:
 
-Applied key by key when a later layer meets the cumulative config:
+```js
+// .sous/sous.config.js (excerpt)
+export const config = {
+  compilation: {
+    includeSourceComments: false,
+  },
+};
+```
+
+If a plugin sets `compilation.includeSourceComments` to `true`, the result is still `false`. In a
+project whose files do not set it, the result is `true`.
+
+Sous repeats this until nothing changes. A file that is applied again never doubles its own array
+items. A config that never settles (two files that keep changing a value the other reads, for
+example) stops sous with a `ConfigError` naming the values that kept changing and where each change
+came from. Validation runs last, after variables resolve.
+
+## Merge semantics
+
+A config file is merged key by key into the config built so far:
 
 - plain object + plain object: recurse
-- array + array: CONCATENATE, cumulative first, layer second. No dedupe; loading the same
-  fragment twice duplicates its array entries. There is no declarative way to remove or replace
-  an array entry; use `configure()` and mutate directly when you need that.
-- anything else (scalar, mixed types, null): the later layer replaces
-- an own `__proto__`, `constructor`, or `prototype` key in layer data is skipped
-  (prototype-pollution guard)
-
-## The JS/MJS layer contract
-
-A `.js` or `.mjs` layer may export a config object, a configure function, or both:
-
-- **Object**: `export const config = {...}`, or a default export that is a non-function object.
-  Merged first.
-- **Function**: `export function configure(currentConfig, builder)`, or a default export that is
-  a function. Runs AFTER the object (if any) merges. It may be async and is awaited. It may
-  mutate `currentConfig` by reference freely. A returned object is merged after it resolves,
-  UNLESS the return value IS `currentConfig` itself (the mutate-and-return-for-chaining idiom),
-  which is skipped so arrays are not duplicated by a self-merge.
-
-## The builder
-
-`configure` receives a builder with:
-
-- `builder.config`: the live cumulative config (same object as `currentConfig`)
-- `builder.sousDir`, `builder.confDir`: resolved directories
-- `builder.currentFile`: absolute path of the layer being loaded
-- `builder.env(name, fallback)`: read an environment variable (env files are already loaded at
-  this point)
-- `builder.merge(obj)`: JSON-force `obj` and deep-merge it into the cumulative config
-- `builder.loadConfig(path)`: load another file (any supported extension) under the full layer
-  contract, including its own nested `configure`. Async.
-- `builder.loadConfigs(globPattern)`: glob, sort matches bytewise, and load each. Async.
-
-Builder path arguments resolve BEFORE variable resolution, so user `_vars` do not exist yet.
-Only the auto-vars may appear in them: `${sousDir}`, `${sousConfDir}`, `${sousRootPath}`,
-`${sousVersion}`. Any other `${name}` in a builder path is a hard error listing the allowed
-names. Relative paths resolve against the directory of `builder.currentFile`. Load cycles (a
-file loading itself, directly or indirectly) are detected and reported.
+- array + array: CONCATENATE, existing items first, the file's second. Duplicates are kept.
+- anything else (scalar, mixed types, null): the later file replaces
+- an own `__proto__`, `constructor`, or `prototype` key in file data is skipped
+
+To remove or replace an array item without code, write a [patch file](#patch-files).
+
+## Plain JSON data
+
+The config is always plain JSON data, so `sous config show` can print it exactly. Every value passes
+through a JSON round-trip: functions and `undefined` values are dropped, and a regular expression is
+written as a string `/.../`. [Config expressions](configuration.md#config-expressions) rely on
+`undefined` values being dropped.
+
+## JavaScript and TypeScript files
+
+A `.js`, `.mjs` or `.ts` config file may export plain data (`export const config = {...}`, or a
+default export that is an object), which is merged like a JSON file. It may also export
+`configure(config)`, which is given a builder object for changing the config:
+
+```js
+// .sous/conf.d/620-no-diagrams.js
+export function configure(config) {
+  config.atPath("compilation.targets").removeWhere((target) => target.id === "diagrams");
+}
+```
+
+`configure` runs again whenever sous applies the file again, so it must give the same result for
+the same input. When a `.js` file changes on disk during watch mode, it is imported again.
+
+Some of the builder's operations (the full list, with each one's documentation, is the `DocumentNode`
+type in `packages/plugin-api/src/node.ts`):
+
+```js
+const node = config.atPath("compilation.targets");
+
+// Inspecting
+node.exists();
+node.type();                   // "object" | "array" | "string" | "number" | "boolean" | "null"
+node.isArray();
+node.isObject();
+node.get();
+node.valueOr(fallback);
+
+// Objects and values
+node.set(value);
+node.delete();
+node.rename("newKey");
+node.merge(object);            // key by key; arrays joined
+node.replace(object);          // whole
+config.atPath("tools").keys();
+
+// Arrays
+node.append(item);
+node.prepend(item);
+node.insertAt(2, item);
+node.removeAt(2);
+node.removeWhere((target) => target.id === "diagrams");
+node.upsertWhere((target) => target.id === "diagrams", item);   // replace the match, or append
+node.findWhere((target) => target.id === "diagrams");           // a node for the match, to edit in place
+node.atIndex(0);
+node.move(from, to);
+node.dedupe();
+
+// The whole config
+config.root().merge(data);
+```
+
+?> A `configure(currentConfig, builder)` written for sous 0.2.x, which changes `currentConfig` in
+place and calls the old builder (`builder.merge`, `builder.loadConfig`, `builder.loadConfigs`,
+`builder.env`), keeps working. Sous records what it changed like any other change.
+
+## Patches
+
+Every change to the config, from a file, a recipe or a plugin, ends up as primitive operations,
+each called a patch:
+
+| `op` | What it does |
+| --- | --- |
+| `setKey` | sets one key of an object |
+| `deleteKey` | deletes one key of an object |
+| `renameKey` | renames one key of an object |
+| `setIndex` | sets one item of an array |
+| `insertAt` | inserts one item into an array |
+| `removeIndex` | removes one item from an array |
+
+Every other builder operation is built from these. `removeWhere` above, for example, records one
+`removeIndex` per matching item. `sous config show --layers` shows both: each operation a file or
+plugin ran, and the patches it made.
+
+### Patch files
+
+A file of raw patches can sit in `conf.d/` or beside `sous.config.*`:
+
+- A `.patch.json` file holds one patch, unless its top-level object has a single key, `$patches`,
+  holding an array: then each item is a patch.
+- A `.patch.jsonl` file holds one patch per line, so a tool or an agent can add a line without
+  parsing the file.
+
+```jsonc
+// .sous/conf.d/720-my-special-thing.patch.json: several patches, so a single $patches key
+{
+    "$patches": [
+        { "op": "setKey", "path": "compilation", "key": "overwriteUntracked", "value": false },
+        { "op": "deleteKey", "path": "tools", "key": "codex" }
+    ]
+}
+```
+
+```jsonl
+// .sous/conf.d/721-my-list-of-things.patch.jsonl: one patch per line
+{"op": "insertAt", "path": "compilation.targets", "index": 0, "value": {"id": "first", "entryPoint": "a.tpl.md"}}
+{"op": "setKey", "path": "_vars", "key": "machineRole", "value": "laptop"}
+```
+
+!> An index written in a patch file is never recomputed: `removeIndex 7` removes whatever is at
+index 7 at that point. Use patch files for arrays only when you know the order the files, recipes and
+plugins before it apply in. Key and path operations have no such catch.
 
 ## Failure behavior
 
-Any layer failure (a JSON/YAML parse error, an import error, a `configure` throw, a load cycle,
-the legacy multi-project schema) halts the whole load with an error naming the layer file. There
-is no warn-and-skip; a broken layer never silently drops out of the merge.
+Any config file failure (a JSON/YAML parse error, an import error, a `configure` throw) halts sous
+with a `ConfigError` naming the file. There is no warn-and-skip; a broken file never silently drops
+out of the config.
 
 ## The managed 5xx layer band
 
-`conf.d/500-*` through `conf.d/599-*` is reserved for layers the sous CLI writes on your behalf.
-They are `.jsonc`, and each one opens with a header comment saying what it holds.
+`conf.d/500-*` through `conf.d/599-*` is reserved for files the sous CLI writes on your behalf.
+They are `.jsonc`, and each one opens with a header comment saying what it holds. They are ordinary
+config files, merged like any other: sous always reads the built config, never one file on its own.
 
 **Sous edits these files by key; you may edit them too.** A write rewrites only the bytes of the
 entry that changes, so your comments, your key order and your formatting survive it, and repeated
 edits produce minimal version-control diffs. Sous never edits a hand-written primary config or a
-layer outside the 5xx band. To override a managed value rather than change it in place, add a
-higher-sorting layer (for example `conf.d/600-overrides.json`).
+file outside the 5xx band. To override a managed value rather than change it in place, add a
+higher-sorting file (for example `conf.d/600-overrides.json`), or a
+[config expression](configuration.md#config-expressions) that switches it on some machines only.
 
 Where a comment is impossible because a format really is strict JSON, the convention is a `//`
 key, which sous ignores wherever it appears.

package/docs/markdown/config-variables.md

@@ -10,12 +10,23 @@ This page is about the config side only.
 Later scopes override earlier ones:
 
 ```
-auto-vars  ->  _env scope  ->  _vars  ->  compilation._vars  ->  target._vars  ->  output._vars
+auto-vars  ->  recipe answers  ->  _env scope  ->  _vars  ->  compilation._vars  ->  target._vars  ->  output._vars
 ```
 
-Nested `_vars` blocks (on `compilation`, on a target, on an output) resolve with their parent
-scope inherited, so a target var may reference a top-level var, and an output var may override
-both for that output only.
+`_vars` may be set at four levels, each inheriting the levels above it, inner values winning:
+
+```text
+root _vars
+└── compilation._vars
+    └── compilation.targets[]._vars
+        └── targets[].outputs[]._vars
+```
+
+So a target var may reference a top-level var, and an output var may override both for that output
+only. A [config expression](configuration.md#config-expressions) sees the `_vars` of every level
+that contains it, and no others; an expression under `subscriptions`, `repos` or any other top-level
+key sees only the root `_vars`. Recipe outputs also get a scope per recipe, holding that recipe's
+answers (see [Recipe variables](repositories-variables.md)).
 
 ## Auto-vars
 
@@ -23,6 +34,7 @@ Always injected first, before `_env` and `_vars`:
 
 | Variable | Value |
 |----------|-------|
+| `projectRoot` | the project root: the directory that holds `.sous/` (see [The project root](config-discovery.md#the-project-root)) |
 | `sousDir` | the discovered `.sous/` directory holding the active config |
 | `sousConfDir` | the `conf.d/` drop-in directory for the active config |
 | `sousConfigPath` | absolute path of the active primary config file |
@@ -31,6 +43,10 @@ Always injected first, before `_env` and `_vars`:
 | `sousTemplatePath` | absolute path of the `.tpl.` file being rendered (render time only) |
 | `sousTemplateDir` | directory of the `.tpl.` file being rendered (render time only) |
 
+!> Sous sets `projectRoot`. Setting it in any `_vars` block is an error saying so. A config that
+wrote `projectRoot: "${sousDir}/.."` before 1.0 drops that line; every `${projectRoot}` keeps
+working.
+
 The `sous*` namespace is reserved: defining any var whose name starts with `sous` earns a
 warning and risks colliding with a future auto-var.
 
@@ -42,14 +58,31 @@ shell environment, `.sous/.env.local`, or `.sous/.env` (first writer wins, in th
 mapped env var that is not set anywhere is a hard `ConfigError` telling you which file to define
 it in.
 
-## Fixpoint resolution
+## Variables set in a later file
+
+A [config expression](configuration.md#config-expressions) always sees a variable's final value,
+even when a later file sets it. Sous notes every variable an expression reads, and when that
+variable's value changes, it applies the file again
+([Layers and merging](config-layers.md#load-order-and-why-your-files-win)):
+
+```text
+Files: sous.config (machineRole: laptop) → 610-browser ($if machineRole == 'laptop') → 700-ci (machineRole: ci)
+
+610-browser reads machineRole → "laptop" → enabled: true; 700-ci then sets "ci"
+610-browser is applied again: machineRole is now "ci" → enabled: false
+nothing it read changed → done
+```
+
+A variable still unknown when the config settles is an error naming it.
+
+## Variables that refer to other variables
 
-Each `_vars` block resolves by a fixpoint loop, not top-to-bottom: every round re-scans the
-still-unresolved entries and finalizes any whose `${refs}` all resolve, repeating until a round
-finalizes nothing. Declaration order therefore never matters; `{ file: "${root}/x", root:
+A variable may refer to others in the same `_vars` block, in any order. Sous resolves every entry
+whose `${refs}` are all known, then tries the rest again, until nothing more resolves. Declaration
+order therefore never matters; `{ file: "${root}/x", root:
 "/data" }` resolves as readily as the reverse.
 
-If entries remain unresolved when progress stops, that is a hard `ConfigError`. The message
+If entries remain unresolved at the end, that is a hard `ConfigError`. The message
 separates:
 
 - **Cycles**: entries that reference each other (members are named), and
@@ -64,8 +97,8 @@ reference.
 ## Path normalization
 
 Absolute `entryPoint`, `entryGlob`, `globBase`, `destinationFile` and `destinationDir` values
-are normalized after substitution, so the common `${sousDir}/..` idiom collapses to the real
-parent directory. This matters: prune compares tracked outputs against `destinationDir` by
+are normalized after substitution, so a path such as `${sousDir}/../docs` collapses to the real
+directory. This matters: prune compares tracked outputs against `destinationDir` by
 string prefix, and watch mode matches event paths against watched entries; both need the
 normalized form.