fix(config): rank env vars and --config-set above project entries

dev/config.example.toml

@@ -238,7 +238,7 @@
 #
 # Entries are keyed by project identifier — `<host>/<owner>/<repo>` derived from the primary remote URL (no `.git` suffix), or the canonical repo path when there is no remote. Run `wt config show` inside the repo to see the identifier for the current project; it appears in the `PROJECT CONFIG` section as `Identifier: …`.
 #
-# Scalar values (like `worktree-path`) replace the global value; everything else (hooks, aliases, etc.) appends, global first.
+# Scalar values (like `worktree-path`) replace the global value; everything else (hooks, aliases, etc.) appends, global first. An entry outranks the global key of the same name, and both lose to a `WORKTRUNK_` env var or `--config-set` — see how the layers rank (https://worktrunk.dev/config/#precedence).
 #
 # [projects."github.com/user/repo"]
 # worktree-path = ".worktrees/{{ branch | sanitize }}"

docs/content/config.md

@@ -344,7 +344,7 @@ User config can include a `[projects]` table for project-specific settings — w
 
 Entries are keyed by project identifier — `<host>/<owner>/<repo>` derived from the primary remote URL (no `.git` suffix), or the canonical repo path when there is no remote. Run `wt config show` inside the repo to see the identifier for the current project; it appears in the `PROJECT CONFIG` section as `Identifier: …`.
 
-Scalar values (like `worktree-path`) replace the global value; everything else (hooks, aliases, etc.) appends, global first.
+Scalar values (like `worktree-path`) replace the global value; everything else (hooks, aliases, etc.) appends, global first. An entry outranks the global key of the same name, and both lose to a `WORKTRUNK_` env var or `--config-set` — see [how the layers rank](@/config.md#precedence).
 
 ```toml
 [projects."github.com/user/repo"]
@@ -634,7 +634,7 @@ On first run without shell integration, Worktrunk offers to install it. On first
 
 ## Environment variables
 
-All user config options can be overridden with environment variables using the `WORKTRUNK_` prefix.
+All user config options can be overridden with environment variables using the `WORKTRUNK_` prefix, which [outrank config files](@/config.md#precedence).
 
 ### Naming convention
 
@@ -675,12 +675,27 @@ Override the LLM command in CI to use a mock:
 
 ## Inline config overrides (`--config-set`)
 
-`--config-set <toml>` overrides any user config key for a single invocation, with higher priority than both config files and `WORKTRUNK_` env vars. The value is a TOML fragment, so arrays and tables work directly; the flag is global (works before or after the subcommand), repeatable, and a later `--config-set` replaces an earlier one for the same key.
+`--config-set <toml>` overrides any user config key for a single invocation, ahead of every other source. The value is a TOML fragment, so arrays and tables work directly; the flag is global (works before or after the subcommand), repeatable, and a later `--config-set` replaces an earlier one for the same key.
 
 {{ terminal(cmd="wt --config-set list.full=true list|||wt step copy-ignored --config-set 'step.copy-ignored.exclude=[__WT_QUOT__target__WT_QUOT__, __WT_QUOT__dist__WT_QUOT__]'") }}
 
 This composes with aliases — an alias body can invoke `wt --config-set … <command>` to render a named view without changing the saved config.
 
+## Precedence
+
+Sources rank by how close they are to the invocation, which puts user config above system config. Within a config file, [an entry keyed to the project](@/config.md#user-project-specific-settings) outranks the global key of the same name. So `worktree-path` comes from the first of these that sets it:
+
+1. `--config-set 'worktree-path = …'`
+2. `WORKTRUNK_WORKTREE_PATH`
+3. `[projects."github.com/owner/repo"]` in the config file
+4. global `worktree-path` in the config file
+
+A `--config-set` that names a project entry applies to that project alone, and beats a global `--config-set` of the same key — it is both the highest layer and the most specific key:
+
+{{ terminal(cmd="wt --config-set 'projects.__WT_QUOT__github.com/owner/repo__WT_QUOT__.worktree-path = __WT_QUOT__/tmp/scratch__WT_QUOT__' switch --create feature") }}
+
+Ranking only matters where one value has to win. Hooks, aliases and `step.copy-ignored.exclude` accumulate rather than replace, so an env-set hook and a project's hook both run.
+
 ## Command reference
 
 {% terminal() %}

plugins/worktrunk/skills/worktrunk/reference/config.md

@@ -341,7 +341,7 @@ User config can include a `[projects]` table for project-specific settings — w
 
 Entries are keyed by project identifier — `<host>/<owner>/<repo>` derived from the primary remote URL (no `.git` suffix), or the canonical repo path when there is no remote. Run `wt config show` inside the repo to see the identifier for the current project; it appears in the `PROJECT CONFIG` section as `Identifier: …`.
 
-Scalar values (like `worktree-path`) replace the global value; everything else (hooks, aliases, etc.) appends, global first.
+Scalar values (like `worktree-path`) replace the global value; everything else (hooks, aliases, etc.) appends, global first. An entry outranks the global key of the same name, and both lose to a `WORKTRUNK_` env var or `--config-set` — see [how the layers rank](https://worktrunk.dev/config/#precedence).
 
 ```toml
 [projects."github.com/user/repo"]
@@ -629,7 +629,7 @@ On first run without shell integration, Worktrunk offers to install it. On first
 
 ## Environment variables
 
-All user config options can be overridden with environment variables using the `WORKTRUNK_` prefix.
+All user config options can be overridden with environment variables using the `WORKTRUNK_` prefix, which [outrank config files](https://worktrunk.dev/config/#precedence).
 
 ### Naming convention
 
@@ -672,7 +672,7 @@ $ WORKTRUNK_COMMIT__GENERATION__COMMAND="echo 'test: automated commit'" wt merge
 
 ## Inline config overrides (`--config-set`)
 
-`--config-set <toml>` overrides any user config key for a single invocation, with higher priority than both config files and `WORKTRUNK_` env vars. The value is a TOML fragment, so arrays and tables work directly; the flag is global (works before or after the subcommand), repeatable, and a later `--config-set` replaces an earlier one for the same key.
+`--config-set <toml>` overrides any user config key for a single invocation, ahead of every other source. The value is a TOML fragment, so arrays and tables work directly; the flag is global (works before or after the subcommand), repeatable, and a later `--config-set` replaces an earlier one for the same key.
 
 ```bash
 $ wt --config-set list.full=true list
@@ -681,6 +681,23 @@ $ wt step copy-ignored --config-set 'step.copy-ignored.exclude=["target", "dist"
 
 This composes with aliases — an alias body can invoke `wt --config-set … <command>` to render a named view without changing the saved config.
 
+## Precedence
+
+Sources rank by how close they are to the invocation, which puts user config above system config. Within a config file, [an entry keyed to the project](https://worktrunk.dev/config/#user-project-specific-settings) outranks the global key of the same name. So `worktree-path` comes from the first of these that sets it:
+
+1. `--config-set 'worktree-path = …'`
+2. `WORKTRUNK_WORKTREE_PATH`
+3. `[projects."github.com/owner/repo"]` in the config file
+4. global `worktree-path` in the config file
+
+A `--config-set` that names a project entry applies to that project alone, and beats a global `--config-set` of the same key — it is both the highest layer and the most specific key:
+
+```bash
+$ wt --config-set 'projects."github.com/owner/repo".worktree-path = "/tmp/scratch"' switch --create feature
+```
+
+Ranking only matters where one value has to win. Hooks, aliases and `step.copy-ignored.exclude` accumulate rather than replace, so an env-set hook and a project's hook both run.
+
 ## Command reference
 
 ```

src/cli/mod.rs

@@ -2232,7 +2232,7 @@ User config can include a `[projects]` table for project-specific settings — w
 
 Entries are keyed by project identifier — `<host>/<owner>/<repo>` derived from the primary remote URL (no `.git` suffix), or the canonical repo path when there is no remote. Run `wt config show` inside the repo to see the identifier for the current project; it appears in the `PROJECT CONFIG` section as `Identifier: …`.
 
-Scalar values (like `worktree-path`) replace the global value; everything else (hooks, aliases, etc.) appends, global first.
+Scalar values (like `worktree-path`) replace the global value; everything else (hooks, aliases, etc.) appends, global first. An entry outranks the global key of the same name, and both lose to a `WORKTRUNK_` env var or `--config-set` — see [how the layers rank](@/config.md#precedence).
 
 ```toml
 [projects."github.com/user/repo"]
@@ -2520,7 +2520,7 @@ On first run without shell integration, Worktrunk offers to install it. On first
 
 ## Environment variables
 
-All user config options can be overridden with environment variables using the `WORKTRUNK_` prefix.
+All user config options can be overridden with environment variables using the `WORKTRUNK_` prefix, which [outrank config files](@/config.md#precedence).
 
 ### Naming convention
 
@@ -2563,14 +2563,31 @@ $ WORKTRUNK_COMMIT__GENERATION__COMMAND="echo 'test: automated commit'" wt merge
 
 ## Inline config overrides (`--config-set`)
 
-`--config-set <toml>` overrides any user config key for a single invocation, with higher priority than both config files and `WORKTRUNK_` env vars. The value is a TOML fragment, so arrays and tables work directly; the flag is global (works before or after the subcommand), repeatable, and a later `--config-set` replaces an earlier one for the same key.
+`--config-set <toml>` overrides any user config key for a single invocation, ahead of every other source. The value is a TOML fragment, so arrays and tables work directly; the flag is global (works before or after the subcommand), repeatable, and a later `--config-set` replaces an earlier one for the same key.
 
 ```console
 $ wt --config-set list.full=true list
 $ wt step copy-ignored --config-set 'step.copy-ignored.exclude=["target", "dist"]'
 ```
 
 This composes with aliases — an alias body can invoke `wt --config-set … <command>` to render a named view without changing the saved config.
+
+## Precedence
+
+Sources rank by how close they are to the invocation, which puts user config above system config. Within a config file, [an entry keyed to the project](@/config.md#user-project-specific-settings) outranks the global key of the same name. So `worktree-path` comes from the first of these that sets it:
+
+1. `--config-set 'worktree-path = …'`
+2. `WORKTRUNK_WORKTREE_PATH`
+3. `[projects."github.com/owner/repo"]` in the config file
+4. global `worktree-path` in the config file
+
+A `--config-set` that names a project entry applies to that project alone, and beats a global `--config-set` of the same key — it is both the highest layer and the most specific key:
+
+```console
+$ wt --config-set 'projects."github.com/owner/repo".worktree-path = "/tmp/scratch"' switch --create feature
+```
+
+Ranking only matters where one value has to win. Hooks, aliases and `step.copy-ignored.exclude` accumulate rather than replace, so an env-set hook and a project's hook both run.
 <!-- subdoc: show -->
 <!-- subdoc: approvals -->
 <!-- subdoc: alias -->

src/config/mod.rs

@@ -8,8 +8,11 @@
 //! 3. **Project config** (`.config/wt.toml`) - Lifecycle hooks, checked into git
 //!
 //! System and user configs share the same schema and are merged via
-//! `deep_merge_table` (user values override system values at the key level).
-//! Project config is independent — different schema, different purpose.
+//! `merge_layer`, which ranks each layer above the one beneath it as a whole:
+//! a user value overrides the system value for the same key, and a user global
+//! key also outranks a system `[projects."…"]` entry that would otherwise be
+//! the more specific match. Project config is independent — different schema,
+//! different purpose.
 //!
 //! See `wt config --help` for complete documentation.