Replace config update --print with --output

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### Improved
 
+- **Config migration output names its destination**: `wt config update --output <path>` writes the migration artifact to that file instead of applying it in place, and `--output=-` writes it to stdout. Output mode includes project config when run from a linked worktree. (Breaking: `--print` was removed.)
+
 - **`wt switch --execute` takes a program, not a shell string**: `-x` names one program, with everything after `--` passed as literal argv. Worktrunk spawns it as a child rather than running it in your interactive shell, so shell functions and its `cd` no longer reach you. `-x sh -- -c '…'` recovers shell syntax, not functions. (Breaking: existing `-x` strings, plus `WORKTRUNK_DIRECTIVE_EXEC_FILE` and `WORKTRUNK_SHELL`.) ([#3977](https://github.com/max-sixty/worktrunk/pull/3977), closes [#2860](https://github.com/max-sixty/worktrunk/issues/2860), fixes [#3944](https://github.com/max-sixty/worktrunk/issues/3944), thanks @omgreenfield for testing the migration path)
 
 - **Worktrunk decides tracking for the branches it creates**: a new branch gets an upstream only when its name matches the remote branch it starts from, whatever `branch.autoSetupMerge` says: `--create release --base origin/release` tracks, `--create feature --base origin/release` does not. Under `autoSetupMerge = false` this previously exited 128 after creating the worktree. ([#3913](https://github.com/max-sixty/worktrunk/pull/3913), [#3950](https://github.com/max-sixty/worktrunk/pull/3950), fixes [#3937](https://github.com/max-sixty/worktrunk/issues/3937), thanks @mjakl for reporting and diagnosing)

docs/src/content/docs/config.md

@@ -809,6 +809,80 @@ Global Options:
           Skip approval prompts
 ```
 
+## wt config update
+
+Update deprecated config settings.
+
+Updates deprecated settings in user and project config files
+to their current equivalents, removes deprecated keys that have no equivalent
+and reports each one, and adopts defaults that a future release switches —
+currently `[list] json-schema = 2` — so the switch happens as a reviewed config
+edit rather than at upgrade. Shows a diff and asks for confirmation.
+
+Migrations are computed in memory on demand; nothing is written outside this
+command. Set `--output <path>` to write a migrated config to that destination
+instead of applying it in place. Use `-` for stdout. When both user and project
+config need migration, stdout emits a labeled inspection artifact and file
+output fails rather than combining the configs.
+
+Output artifacts omit deprecated `approved-commands`; only in-place updates
+move those entries to `approvals.toml`.
+
+### Examples
+
+Preview and apply updates:
+```console
+$ wt config update
+```
+
+Apply without confirmation:
+```console
+$ wt config update --yes
+```
+
+Write the migration artifact to a file:
+```console
+$ wt config update --output migrated.toml
+```
+
+Write the migration artifact to stdout:
+```console
+$ wt config update --output=-
+```
+
+### Command reference
+
+```text wt-command-reference
+wt config update - Update deprecated config settings
+
+Usage: wt config update [OPTIONS]
+
+Options:
+      --output <PATH>
+          Output migrated config (- for stdout)
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+Global Options:
+  -C <path>
+          Working directory for this command
+
+      --config <path>
+          User config file path
+
+      --config-set <toml>
+          Override config with inline TOML, e.g. --config-set list.full=true (repeatable)
+
+  -v, --verbose...
+          Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug
+          logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to
+          apply the same level everywhere — including shell completion, which no flag can reach
+
+  -y, --yes
+          Skip approval prompts
+```
+
 ## wt config approvals
 
 Manage command approvals.

docs/tests/built-site.test.mjs

@@ -223,7 +223,7 @@ test('build preserves the public route contract', async () => {
   assert.ok(configToc, 'config page is missing its desktop table of contents');
   assert.equal(
     [...configToc.matchAll(/<a href="#[^"]+"/g)].length,
-    32,
+    33,
     'config table of contents should expose overview and structural section headings only',
   );
   for (const [id, title] of [

src/cli/config.rs

@@ -1,3 +1,5 @@
+use std::path::PathBuf;
+
 use clap::{Args, Subcommand};
 
 use super::SwitchFormat;
@@ -594,7 +596,13 @@ currently `[list] json-schema = 2` — so the switch happens as a reviewed confi
 edit rather than at upgrade. Shows a diff and asks for confirmation.
 
 Migrations are computed in memory on demand; nothing is written outside this
-command. Use `--print` to see the migrated TOML without touching any file.
+command. Set `--output <path>` to write a migrated config to that destination
+instead of applying it in place. Use `-` for stdout. When both user and project
+config need migration, stdout emits a labeled inspection artifact and file
+output fails rather than combining the configs.
+
+Output artifacts omit deprecated `approved-commands`; only in-place updates
+move those entries to `approvals.toml`.
 
 ## Examples
 
@@ -608,15 +616,20 @@ Apply without confirmation:
 $ wt config update --yes
 ```
 
-Print the migrated config to stdout (no changes written):
+Write the migration artifact to a file:
+```console
+$ wt config update --output migrated.toml
+```
+
+Write the migration artifact to stdout:
 ```console
-$ wt config update --print
+$ wt config update --output=-
 ```"#
     )]
     Update {
-        /// Print the migrated config to stdout instead of writing it
-        #[arg(long)]
-        print: bool,
+        /// Output migrated config (`-` for stdout)
+        #[arg(long, value_name = "PATH")]
+        output: Option<PathBuf>,
     },
 
     /// Manage command approvals

src/cli/mod.rs

@@ -2597,6 +2597,7 @@ $ wt --config-set 'projects."github.com/owner/repo".worktree-path = "/tmp/scratc
 
 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: update -->
 <!-- subdoc: approvals -->
 <!-- subdoc: alias -->
 <!-- subdoc: state -->"#)]