From 86c3dc62479f3356d4ae7d1f2fa58876887e2369 Mon Sep 17 00:00:00 2001
From: torabit <torabit.humble@gmail.com>
Date: Tue, 8 Sep 2026 03:51:40 +0900
Subject: [PATCH 1/6] docs(hook): decide how a sourced target follows an apply

A target whose output a shell sources cannot be reached by `reload`. The shell
that has the wrong colours is vanadis's parent, and no process replaces its
parent's image, so `exec zsh` is unreachable however it is spelled. fzf is the
entry `docs/config.md` names for this, and `LS_COLORS`, `GREP_COLORS` and a
pager named through a variable are the same shape.

`vanadis hook <shell>` prints a snippet to `eval`, the way direnv, mise,
starship and zoxide do. The snippet sources the outputs of the targets marked
`shell = "zsh"` and registers a prompt hook that sources each again when its
own mtime has moved. The state file is not the signal: `apply --only nvim`
moves it without touching a shell target, and watching it would put
`$XDG_STATE_HOME` and a file format into a snippet that otherwise needs only a
path.

The decisions the document records: a per-target `shell` key rather than a
top-level table, because a table naming targets is a second place a name is
written; paths baked into the snippet rather than a config parse per prompt,
with re-`eval` as the answer to staleness; zsh and fish detecting a change with
no fork, and bash spending one `stat`, with the `stat` chosen when the snippet
is generated rather than branched at runtime; a stamp file compared with `-nt`
rejected for bash because cleaning it up needs the one `EXIT` trap the user
also has; one hook after a second `eval`, and the exit status restored so a
prompt that shows it is not lied to.

The zsh row of the `reload` table now says what does reach it. The same row in
the shipped skill, and the CI that runs the snippet under each shell, land with
the implementation.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011wxMB7uC4uxSJ2dfHi8ucf
---
 docs/config.md |   8 +-
 docs/hook.md   | 257 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 264 insertions(+), 1 deletion(-)
 create mode 100644 docs/hook.md

diff --git a/docs/config.md b/docs/config.md
index 28484ec..0a9372f 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -12,6 +12,8 @@ the file it was taken from.
 `[[targets]]` entry from a config file that already exists.
 [docs/schemes.md](schemes.md) decides the one path this document does not cover: the cache
 `vanadis remote update` writes the tinted-theming collection into.
+[docs/hook.md](hook.md) decides how a target whose output a shell sources follows an apply,
+which is the one case [`reload`](#reload) below cannot reach.
 
 ## Layout
 
@@ -231,7 +233,11 @@ still reachable by writing a script and naming it here.
 | herdr, a terminal multiplexer | `herdr server reload-config` | yes |
 | starship, a shell prompt | next prompt | nothing to run |
 | nvim, btop, hunk, lazygit — an editor, a system monitor, a diff viewer, a git UI | restart the program | not a command |
-| zsh with fzf, a shell and a fuzzy finder | `exec zsh` | no: it replaces the user's shell, and vanadis is a child process |
+| zsh with fzf, a shell and a fuzzy finder | the shell sources the output again | no: `exec zsh` replaces the user's shell, and vanadis is a child process |
+
+The last row is the one `reload` cannot be spelled for at all, because the shell to fix is
+vanadis's parent. [docs/hook.md](hook.md) decides `vanadis hook`, the prompt hook that lets such
+a target follow an apply, and the `shell` key that marks it.
 
 So `reload` is optional and absent means nothing runs. It is not a hook system, and there is
 no `pre` counterpart: nothing in the corpus needs work done before a write.
diff --git a/docs/hook.md b/docs/hook.md
new file mode 100644
index 0000000..39c6999
--- /dev/null
+++ b/docs/hook.md
@@ -0,0 +1,257 @@
+# hook
+
+This document decides how a target whose output is read by a shell follows a theme change in a
+shell that is already running. [docs/config.md](config.md) decides `config.toml`, the paths,
+and `reload`, which runs a command after a write. That command cannot reach the shell that
+started vanadis, and this is what covers the targets that need it to.
+
+## The problem
+
+`reload` runs argv directly, in a child process. The shell that has the wrong colours is
+vanadis's parent, and no process can replace its parent's image.
+
+```toml
+reload = ["exec", "zsh"]
+```
+
+That entry fails before reaching the question: `exec` is a shell builtin, and `reload` takes no
+shell. Spelling it `["zsh", "-c", "exec zsh"]` runs a shell, replaces that shell with another
+one, and exits. The user's shell is untouched either way.
+
+So the whole class of targets whose output is *sourced* rather than *read from a path* has no
+way to follow an apply. fzf is the entry [docs/config.md](config.md#reload) names, because it
+takes its colours from `FZF_DEFAULT_OPTS` in the environment. `LS_COLORS`, `GREP_COLORS` and a
+pager named through a variable are the same shape. The count matters: this is not one tool with
+an awkward interface, it is every tool configured through the environment.
+
+The knowledge the fix needs is vanadis's, not the user's. Where the sourced file is, how to
+detect a change without forking, and the per-shell syntax for registering a prompt hook are all
+things `config.toml` already holds or vanadis already knows. Written by hand into a `.zshrc`,
+that knowledge is copied, not referenced, and cannot be corrected when a path moves.
+
+## The mechanism
+
+```
+vanadis hook <zsh|fish|bash>
+```
+
+Prints a snippet to stdout, to be evaluated by the shell it names:
+
+```zsh
+eval "$(vanadis hook zsh)"
+```
+
+The snippet sources the outputs of the targets that name that shell, once at evaluation, and
+registers a prompt hook that sources each of them again when its file has changed. This is the
+shape `direnv hook zsh`, `mise activate zsh`, `starship init zsh` and `zoxide init zsh` already
+have, and a user who has one of them in an rc file recognises the line without being taught it.
+
+**`hook`, not `init`.** `vanadis init` is the command that turns a config file that already
+exists into a template, a theme and a target ([docs/init.md](init.md)). The name is taken, and
+taking it twice for two unrelated jobs is worse than differing from starship.
+
+**Every failure prints nothing on stdout.** A config that will not load, a shell name that is
+not one of the three, a target whose `output` cannot be resolved: all of them report on stderr
+and exit non-zero with stdout empty. `eval` of an empty string is a no-op, so a failure cannot
+leave a half-written snippet in the user's shell. That is
+[Order](config.md#order)'s guarantee in the shape a command that writes to a shell can have it.
+
+`hook` reads `config.toml` and nothing else. It resolves no theme, reads no state file and does
+not scan `themes/`, because the snippet holds paths and no colours. A machine that has applied
+nothing yet emits the same snippet as one that has.
+
+## The change signal is the output's own mtime
+
+Not the state file's, for three reasons. It is direct: the file the shell sources is the file
+whose change matters. `apply --only nvim` writes the state file without touching a shell
+target's output, and watching the state file would re-source for nothing. And the snippet then
+needs no knowledge of `$XDG_STATE_HOME` or of the state file format, only of the output path,
+which it has to hold anyway.
+
+**A missing output sources nothing and is not an error.** The hook runs on every prompt, so
+anything it says, it says forever. An output that has never been applied is the ordinary state
+of a machine between a `git clone` and a first `vanadis apply`. The recorded mtime stays empty
+until the file appears, at which point it differs and the file is sourced.
+
+**The resolution is one second.** `zstat +mtime` and `path mtime` both report seconds. Two
+applies inside the same second as the shell's last observation are seen as one, and the shell
+keeps the colours of the first until the next apply moves the mtime again. Reaching for
+sub-second stamps to close that is not done: the gap needs two applies in the same second, and
+a prompt hook only fires when a person is at the keyboard.
+
+## Saying a target is sourced
+
+A per-target key, beside `reload`:
+
+```toml
+[[targets]]
+name = "fzf"
+template = "templates/fzf/colours.zsh.in"
+output = "~/.config/fzf/colours.zsh"
+shell = "zsh"
+```
+
+| key | required | value |
+| --- | --- | --- |
+| `shell` | no | `zsh`, `fish` or `bash`: the shell whose `hook` sources this output |
+
+Any other value is rejected when the config loads, the way every other enumerated value in the
+file is. A typo is then a config error and not a target that silently never sources.
+
+**A shell name, not a boolean.** The output is a file in that shell's syntax; a `.zshrc`
+fragment is not something fish can source. A user with both shells keeps a zsh target and a
+fish target side by side, rendered from two templates, and each `hook` sources its own. A
+boolean would make that config unsayable and would leave `vanadis hook fish` guessing.
+
+**Per target, not a top-level table.** A `[shell]` table listing target names would be a second
+place where a target's name is written, which is what
+[docs/config.md](config.md#layout) declined for themes and for the same reason: two places
+that can disagree. `shell` sits where `reload` sits, because it answers the same question — how
+a write reaches the tool — for the targets `reload` cannot answer it for.
+
+**`shell` and `reload` are independent.** Both may be present. `reload` runs in vanadis's
+process tree at apply time; `shell` reaches a shell vanadis is a child of, at that shell's next
+prompt. Nothing about one implies the other.
+
+Several targets may name the same shell. They are sourced in the order they appear in
+`config.toml`, which is the order [Order](config.md#order) already gives writes and reloads.
+Each is compared and sourced on its own, so a change to one does not re-source the others.
+
+## The snippet
+
+Three invariants, in every shell that ships.
+
+**A second `eval` leaves one hook registered.** Re-evaluating the snippet is how a user picks
+up a config change ([below](#the-paths-are-baked-in)), so it has to be free. zsh gets it from
+`add-zsh-hook`, which deduplicates by function name. fish gets it from redefining the handler
+function, which replaces the old one along with its event binding. bash has neither, and guards
+the `PROMPT_COMMAND` append by testing for the function name first.
+
+**The hook leaves the exit status it found.** A prompt that shows the last command's status
+reads `$?` after the hook has run. A hook that returns the status of its own `stat` call makes
+every failed command look successful, or the reverse. The status is saved on entry and returned
+on exit.
+
+**The hook touches nothing the user named.** Every function and variable it defines is prefixed
+`_vanadis_`. The zsh function runs under `emulate -L zsh`, so a user's `setopt` does not change
+what the snippet means.
+
+### Per shell
+
+| shell | mtime | prompt hook | forks per prompt |
+| --- | --- | --- | --- |
+| zsh | `zstat -A ... +mtime` from `zsh/stat` | `add-zsh-hook precmd` | none |
+| fish | `path mtime` | `function ... --on-event fish_prompt` | none |
+| bash | `stat` | `PROMPT_COMMAND` | one |
+
+**bash forks once per prompt.** It has no builtin that reads an mtime. Which `stat` to write is
+settled when the snippet is generated, not when it runs: vanadis knows the system it is on, so
+the emitted snippet carries `stat -c %Y` or `stat -f %m` and no runtime branch. The cost is one
+fork per prompt, which is less than the `PROMPT_COMMAND` of anyone who displays a git branch.
+
+The alternative that avoids the fork is rejected [below](#rejected-alternatives). Shipping bash
+with a source-at-startup snippet and no following is rejected too: a bash user who runs
+`vanadis cycle` in another terminal is exactly the person this document exists for, and half an
+answer here would have to be explained everywhere `hook` is mentioned.
+
+**The recorded mtime is one variable per target**, named by the target's position, not an
+associative array keyed by path. bash 3.2 is the bash macOS ships and it has no associative
+arrays. The paths are baked in, so their positions are too, and nothing is lost.
+
+### When no target names the shell
+
+`vanadis hook fish` on a config with no fish target prints nothing on stdout, one line on
+stderr, and exits zero. `eval` reads stdout, so the shell starts with no hook and the user sees
+why. Exiting non-zero was considered: it makes `$?` immediately after the `eval` line non-zero
+for a shell that started correctly, which is a worse thing to hand a `.zshrc` than a message.
+
+A shell name that is not one of the three is refused by the argument parser, before any file is
+read. It is the same treatment `--variant` gives a background that is not `light` or `dark`.
+
+## The paths are baked in
+
+The emitted snippet holds resolved output paths as literals. It does not read `config.toml`,
+and it does not run vanadis.
+
+The cost is a snippet that goes stale when a target's `output` moves or a `shell` key is added.
+Re-evaluating is the fix, and it is the user's to run — the same answer direnv, mise, starship
+and zoxide give for the same staleness. It is a good trade twice over. A config parse per
+prompt is a `vanadis` process per prompt, which is what
+[docs/config.md](config.md#querying) already refused for `get` when it declined to scan
+`themes/` for a command a prompt hook calls. And a baked snippet keeps working in a shell whose
+`$PATH` no longer has vanadis on it, which a shell in a container or a rescue environment
+routinely does not.
+
+## What is sourced is the user's
+
+The file the hook sources is whatever the user's template rendered. vanadis does not parse it,
+does not check that it is valid shell, and does not sandbox it. A template that renders a
+syntax error breaks every shell started after the next apply, and the fix is to fix the
+template.
+
+That is the same trust `eval "$(vanadis hook zsh)"` already grants, stated out loud because the
+indirection hides it: the user evaluates one line, and what runs is a file written by a
+different command at a different time.
+
+It also sets what belongs in a shell target's template. Exports and variable assignments follow
+the theme. A template that starts a program or writes a file is a template that does it in
+every new shell.
+
+## Checking the snippet in CI
+
+The snippet is generated text that is only correct if a shell accepts it. CI evaluates it under
+each of the three shells and asserts the behaviour, rather than comparing it against an
+expected string: a string assertion establishes that the generator did not change, and says
+nothing about whether zsh can parse the result.
+
+What is asserted, per shell: evaluating the snippet sources the output; evaluating it twice
+registers one hook; touching the output re-sources it at the next prompt; leaving the output
+alone does not; and the exit status of the command before the prompt survives.
+
+This is also what fixes the versions claimed. `path mtime` is not in every fish that is
+installed anywhere, and the fish CI runs on is the fish this document claims.
+
+## Rejected alternatives
+
+**Watching the state file.** Covered above: it changes when a target that is not this one is
+applied, and it makes the snippet depend on a path and a file format it otherwise never needs.
+
+**A top-level `[shell]` or `[hook]` table.** A second place naming targets, and it cannot hold
+two shells without becoming the per-target key with extra steps.
+
+**Reading `config.toml` at prompt time.** A fork and a TOML parse per prompt, to remove a
+staleness that one `eval` fixes.
+
+**A stamp file per shell, compared with `[[ output -nt stamp ]]`.** bash's `-nt` is a builtin
+and `: > "$stamp"` updates a stamp without forking, so this does reach zero forks per prompt.
+It needs a stamp per shell process, since a shared one would let the first shell to notice a
+change stop every other shell from noticing it. That means a file under a runtime directory
+named by `$$`, and an `EXIT` trap to remove it. bash has one `EXIT` trap, and installing ours
+silently replaces the user's. A fork per prompt is a smaller thing to spend than that.
+
+**vanadis emitting the exports itself**, as `eval "$(vanadis env zsh)"` printing
+`export FZF_DEFAULT_OPTS=...` derived from tokens. It removes the rendered file and with it the
+mtime question. It also needs vanadis to know which environment variables which tools read,
+which is a list of tools — and vanadis carries no list of tools. The template already expresses
+this and expresses more of it: `FZF_DEFAULT_OPTS` is one string a user assembles from many
+tokens, in an order only they know.
+
+**One aggregated file that every shell target renders into.** It would let the snippet hold one
+path. Nothing in `[[targets]]` would name that file, so `check` could not compare it against
+anything, and vanadis would be writing an output it does not otherwise account for.
+
+**A daemon watching outputs with inotify.** It fixes the fork and the one-second resolution
+together, and costs a process to start, supervise and stop, plus a decision about what happens
+to a shell whose daemon died. A prompt hook has no lifetime beyond the shell it is in.
+
+**`vanadis hook --install`, editing the user's rc file.** The line to add is one line, and a
+tool that writes into `.zshrc` has to decide how to find the file, where in it to write, and
+what to do when the user has moved the line. Printing the line and letting the user place it is
+what every tool in this shape does.
+
+## Acceptance
+
+- `eval "$(vanadis hook zsh)"` in one shell, `vanadis cycle` in another, and the first shell's
+  `FZF_DEFAULT_OPTS` holds the new theme's colours at its next prompt, with no `exec zsh`.
+- A second `eval` in the same shell leaves one hook registered, not two.
+- `vanadis apply --only nvim`, where `nvim` is not a shell target, re-sources nothing.

From 8d0e02c8bc74d0444b8c929eb4896d4e2c568d1b Mon Sep 17 00:00:00 2001
From: torabit <torabit.humble@gmail.com>
Date: Tue, 8 Sep 2026 03:54:19 +0900
Subject: [PATCH 2/6] docs(hook): drop the rejected alternatives the body
 already decides

The state file as the signal, a top-level table, and a config read at prompt
time are each argued where they come up. Restating them under Rejected
alternatives said the same thing twice and made the section long enough to read
as the point of the document. What is left is the five the body never raises.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011wxMB7uC4uxSJ2dfHi8ucf
---
 docs/hook.md | 10 ++--------
 1 file changed, 2 insertions(+), 8 deletions(-)

diff --git a/docs/hook.md b/docs/hook.md
index 39c6999..f39527e 100644
--- a/docs/hook.md
+++ b/docs/hook.md
@@ -213,14 +213,8 @@ installed anywhere, and the fish CI runs on is the fish this document claims.
 
 ## Rejected alternatives
 
-**Watching the state file.** Covered above: it changes when a target that is not this one is
-applied, and it makes the snippet depend on a path and a file format it otherwise never needs.
-
-**A top-level `[shell]` or `[hook]` table.** A second place naming targets, and it cannot hold
-two shells without becoming the per-target key with extra steps.
-
-**Reading `config.toml` at prompt time.** A fork and a TOML parse per prompt, to remove a
-staleness that one `eval` fixes.
+The state file as the signal, a top-level table naming shell targets, and a config read at
+prompt time are each decided in the section above that raises them.
 
 **A stamp file per shell, compared with `[[ output -nt stamp ]]`.** bash's `-nt` is a builtin
 and `: > "$stamp"` updates a stamp without forking, so this does reach zero forks per prompt.

From 7b0d768a005250d7ac959853ddf1c0a5d93b5bc7 Mon Sep 17 00:00:00 2001
From: torabit <torabit.humble@gmail.com>
Date: Tue, 8 Sep 2026 04:05:25 +0900
Subject: [PATCH 3/6] feat(hook): print the snippet a shell evaluates to follow
 an apply

`docs/hook.md` decides this. A target whose output a shell sources cannot be
reached by `reload`, because the shell holding the stale colours is vanadis's
parent. `vanadis hook <zsh|fish|bash>` prints a snippet to evaluate: it sources
the output of every target marked `shell`, and registers a prompt hook that
sources it again when that file's mtime moves.

The snippet holds resolved paths as literals and never runs vanadis again, so a
prompt costs no process and a shell that has lost vanadis from `$PATH` keeps
following. zsh reads the mtime with `zstat` and fish with `path mtime`, neither
forking; bash has no such builtin and spends one `stat`, written in at
generation time from the system vanadis is on rather than branched at runtime.

Three invariants hold in every shell. A second evaluation leaves one hook
registered, by `add-zsh-hook`, by redefining the fish handler, and by a
`PROMPT_COMMAND` append guarded on the function name. The hook returns the exit
status it found, so a prompt showing `$?` is not lied to. Every name it defines
is prefixed `_vanadis_`, and the zsh helper is emulated so a user's `setopt`
cannot change what it means.

`hook` reads `config.toml` and nothing else: no theme is resolved, no state file
is read, `themes/` is not scanned. Every failure leaves stdout empty, so a
config that will not load cannot leave half a snippet in the user's shell. A
config that loads and names no target for that shell reports on stderr and exits
zero, because the shell it is starting is otherwise fine.

`tests/hook.rs` evaluates what is printed in a real interactive shell and reads
what that shell prints back, because asserting the snippet as a string would
establish only that the generator did not change. CI installs the three shells,
and the tests refuse to skip a missing shell when `CI` is set.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011wxMB7uC4uxSJ2dfHi8ucf
---
 .github/workflows/ci.yml                    |   5 +
 docs/examples/config.toml                   |   8 +-
 docs/hook.md                                |   7 +
 skills/vanadis/SKILL.md                     |   5 +-
 skills/vanadis/references/reload.md         |  45 ++-
 src/config.rs                               | 112 ++++++-
 src/hook.rs                                 | 284 ++++++++++++++++
 src/lib.rs                                  |   4 +-
 src/main.rs                                 |  59 +++-
 tests/config.rs                             |  15 +-
 tests/fixtures/hook/config.toml             |  36 ++
 tests/fixtures/hook/templates/fish.in       |   1 +
 tests/fixtures/hook/templates/posix.in      |   1 +
 tests/fixtures/hook/themes/nord.toml        |  46 +++
 tests/fixtures/hook/themes/paper-light.toml |  46 +++
 tests/hook.rs                               | 348 ++++++++++++++++++++
 16 files changed, 1012 insertions(+), 10 deletions(-)
 create mode 100644 src/hook.rs
 create mode 100644 tests/fixtures/hook/config.toml
 create mode 100644 tests/fixtures/hook/templates/fish.in
 create mode 100644 tests/fixtures/hook/templates/posix.in
 create mode 100644 tests/fixtures/hook/themes/nord.toml
 create mode 100644 tests/fixtures/hook/themes/paper-light.toml
 create mode 100644 tests/hook.rs

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index cac15a8..cf29deb 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -24,6 +24,11 @@ jobs:
       - name: clippy
         run: cargo clippy --all-targets -- -D warnings
 
+      # tests/hook.rs evaluates the emitted snippet in each shell `vanadis hook` claims, and
+      # refuses to skip a shell when `CI` is set.
+      - name: shells
+        run: sudo apt-get update && sudo apt-get install -y zsh fish
+
       - name: test
         run: cargo test --all-targets
 
diff --git a/docs/examples/config.toml b/docs/examples/config.toml
index 489bd47..98ba332 100644
--- a/docs/examples/config.toml
+++ b/docs/examples/config.toml
@@ -80,10 +80,12 @@ name = "starship"
 template = "templates/starship/starship.toml.in"
 output = "~/.config/starship.toml"
 
-# fzf reads these colours from the environment, so the shell has to be replaced for a change
-# to show. `exec zsh` replaces the user's shell and vanadis runs as a child process, so it
-# cannot be a reload command.
+# fzf reads these colours from the environment, so a write is not enough on its own: the
+# shell has to source the file again. No `reload` can do that, because the shell that needs
+# fixing is vanadis's parent. `shell` marks the target instead, and the prompt hook that
+# `eval "$(vanadis hook zsh)"` registers sources the file again whenever it changes.
 [[targets]]
 name = "zsh"
 template = "templates/zsh/palette.zsh.in"
 output = "~/.config/zsh/palette.zsh"
+shell = "zsh"
diff --git a/docs/hook.md b/docs/hook.md
index f39527e..ac94fd3 100644
--- a/docs/hook.md
+++ b/docs/hook.md
@@ -41,6 +41,13 @@ Prints a snippet to stdout, to be evaluated by the shell it names:
 eval "$(vanadis hook zsh)"
 ```
 
+fish reads it the way fish reads every tool in this shape, because `eval` there would need the
+output collected into one argument first:
+
+```fish
+vanadis hook fish | source
+```
+
 The snippet sources the outputs of the targets that name that shell, once at evaluation, and
 registers a prompt hook that sources each of them again when its file has changed. This is the
 shape `direnv hook zsh`, `mise activate zsh`, `starship init zsh` and `zoxide init zsh` already
diff --git a/skills/vanadis/SKILL.md b/skills/vanadis/SKILL.md
index 835d6ac..d73bbb4 100644
--- a/skills/vanadis/SKILL.md
+++ b/skills/vanadis/SKILL.md
@@ -63,6 +63,7 @@ not travel with it.
 | `vanadis get --json` | the whole resolved theme, flat, keyed by token path |
 | `vanadis render <template> --theme <id>` | one template against one named theme, to stdout. Reads no target and writes no file — this is how a theme is written out as a base16 scheme or any other format |
 | `vanadis render --target <name>` | what an apply would write for that target, to stdout, writing no file. The theme resolves the way `check` resolves it, so `render --target x > <its output>` leaves `check --only x` clean |
+| `vanadis hook <zsh\|fish\|bash>` | the snippet a shell evaluates to follow an apply, for a target marked `shell` — `eval "$(vanadis hook zsh)"`, or `vanadis hook fish \| source` |
 | `vanadis init <file>` | interactive. Hand it to the user — see below. |
 
 `apply` overwrites files the user wrote. Show `vanadis apply <theme> --diff` and get their
@@ -196,7 +197,8 @@ what lets `check` say a colour value is well-formed at all.
 6. **Add the values to the theme** under the names you chose, as lowercase `#rrggbb` literals
    or as `{{colors.x}}` references to colours it already carries.
 7. **Append the `[[targets]]` entry.** `name`, `template`, `output`. Leave `reload` out unless
-   you know the command — see [references/reload.md](references/reload.md).
+   you know the command, and add `shell` when the output is a file a shell sources rather than
+   a config a tool reads — see [references/reload.md](references/reload.md).
 8. **Verify.** This is the step that makes the work checkable:
 
    ```
@@ -230,6 +232,7 @@ first apply of a target you just wrote.
 | `template` | yes | path to the template |
 | `output` | yes | path to write |
 | `reload` | no | argv to run after writing, as an array — no shell |
+| `shell` | no | `zsh`, `fish` or `bash`: the shell whose `vanadis hook` sources this output — see [references/reload.md](references/reload.md) |
 | `themes` | no | `{ light = "...", dark = "..." }`, this target's own themes |
 
 `name` identifies the target, not the tool. One program with three config files is three
diff --git a/skills/vanadis/references/reload.md b/skills/vanadis/references/reload.md
index b7a42bc..c660a9f 100644
--- a/skills/vanadis/references/reload.md
+++ b/skills/vanadis/references/reload.md
@@ -29,7 +29,7 @@ There is no `pre` counterpart and no hook system.
 | btop | system monitor | restart | not a command |
 | hunk | diff viewer | restart | not a command |
 | lazygit | git UI | restart | not a command |
-| zsh with fzf | shell and fuzzy finder | `exec zsh` — fzf reads its colours from the environment | **no**: it replaces the user's shell, and vanadis is a child process |
+| zsh with fzf | shell and fuzzy finder | the shell sources the output again — fzf reads its colours from the environment | **no**: mark the target `shell = "zsh"` and use [the prompt hook](#a-target-a-shell-sources) |
 | rio | terminal emulator | rereads its config; note it runs on the machine the terminal is on, which over SSH is not the machine vanadis runs on | nothing to run |
 
 Two of these nine have a command vanadis can usefully run. That ratio is the normal case, not a
@@ -39,6 +39,49 @@ gap in the format.
 showing the old theme with no error anywhere — the file on disk is correct and `vanadis check`
 is clean.
 
+## A target a shell sources
+
+`reload` cannot reach a tool configured through the environment. The shell holding the stale
+colours is vanadis's parent, and no process replaces its parent's image, so `exec zsh` is
+unreachable however it is written. `reload = ["exec", "zsh"]` fails before that: `exec` is a
+shell builtin and `reload` takes no shell.
+
+Mark the target with the shell that sources its output:
+
+```toml
+[[targets]]
+name = "zsh"
+template = "templates/zsh/palette.zsh.in"
+output = "~/.config/zsh/palette.zsh"
+shell = "zsh"
+```
+
+`zsh`, `fish` and `bash`. The value names the shell whose syntax the output is written in, so a
+zsh target and a fish target sit side by side, each rendered from its own template.
+
+Then the user adds one line to their rc file:
+
+```zsh
+eval "$(vanadis hook zsh)"
+```
+
+```fish
+vanadis hook fish | source
+```
+
+That registers a prompt hook which sources the output again whenever the file changes, so an
+`apply` or a `cycle` run in another terminal reaches this shell at its next prompt. The paths
+are written into the snippet, so the line has to be re-run after an `output` moves or a target
+is added.
+
+`shell` does not replace `reload`. Both may be present: `reload` runs a command after the
+write, and `shell` reaches a shell vanadis cannot run a command in.
+
+**What belongs in such a template.** Exports and variable assignments. The file is sourced in
+every new shell and again on every change, so a template that starts a program or writes a file
+does that each time. A template that renders invalid shell syntax breaks every shell started
+after the next apply.
+
 ## Working out a tool that is not in the table
 
 Ask in this order, and stop at the first yes.
diff --git a/src/config.rs b/src/config.rs
index 06dd9a5..ecefd46 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -36,6 +36,52 @@ impl fmt::Display for TargetName {
     }
 }
 
+/// A shell that sources a target's output.
+///
+/// `vanadis hook <shell>` prints the snippet that sources every target carrying this shell,
+/// and sources it again when its output changes. See `docs/hook.md`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum Shell {
+    /// zsh, which reads an mtime with `zstat` and hooks `precmd`.
+    Zsh,
+    /// fish, which reads an mtime with `path mtime` and hooks the `fish_prompt` event.
+    Fish,
+    /// bash, which forks `stat` and appends to `PROMPT_COMMAND`.
+    Bash,
+}
+
+impl Shell {
+    /// Every shell `hook` emits for, in the order `--help` lists them.
+    pub const ALL: [Self; 3] = [Self::Zsh, Self::Fish, Self::Bash];
+
+    /// Parses `text` as a shell name, returning `None` when it names none of them.
+    #[must_use]
+    pub fn parse(text: &str) -> Option<Self> {
+        match text {
+            "zsh" => Some(Self::Zsh),
+            "fish" => Some(Self::Fish),
+            "bash" => Some(Self::Bash),
+            _ => None,
+        }
+    }
+
+    /// The name the config file and the command line both write.
+    #[must_use]
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Zsh => "zsh",
+            Self::Fish => "fish",
+            Self::Bash => "bash",
+        }
+    }
+}
+
+impl fmt::Display for Shell {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.as_str())
+    }
+}
+
 /// The themes a bare `vanadis apply --variant` resolves through.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Auto {
@@ -110,6 +156,7 @@ pub struct Target {
     template: PathBuf,
     output: PathBuf,
     reload: Vec<String>,
+    shell: Option<Shell>,
     themes: Option<Themes>,
 }
 
@@ -138,6 +185,12 @@ impl Target {
         &self.reload
     }
 
+    /// The shell whose `hook` sources this output, or `None` when no shell does.
+    #[must_use]
+    pub fn shell(&self) -> Option<Shell> {
+        self.shell
+    }
+
     /// The target's own themes, or `None` when it follows the theme being applied.
     #[must_use]
     pub fn themes(&self) -> Option<&Themes> {
@@ -222,6 +275,14 @@ pub enum Problem {
         /// The value, as the file writes it.
         value: String,
     },
+    /// A `shell` naming a shell `hook` does not emit for.
+    #[error("line {line}: targets.shell is `{value}`, and the shells are zsh, fish and bash")]
+    Shell {
+        /// The value, as the file writes it.
+        value: String,
+        /// The line the key is written on.
+        line: usize,
+    },
     /// A path starting with `~` when there is no home directory to expand it to.
     #[error("line {line}: {key} starts with `~`, and there is no home directory")]
     Home {
@@ -245,6 +306,7 @@ impl Problem {
             | Self::Repeated { line, .. }
             | Self::Short { line, .. }
             | Self::Theme { line, .. }
+            | Self::Shell { line, .. }
             | Self::Home { line, .. } => *line,
         }
     }
@@ -530,7 +592,7 @@ impl Parse<'_> {
         for (key, item) in table {
             let at = self.line_of(table.key(key));
             match key {
-                "name" | "template" | "output" | "reload" => {}
+                "name" | "template" | "output" | "reload" | "shell" => {}
                 "themes" => {
                     if let Some(inner) = item.as_table_like() {
                         themes = Some(self.themes(inner));
@@ -549,12 +611,14 @@ impl Parse<'_> {
         let template = self.path(table, "template", line);
         let output = self.path(table, "output", line);
         let reload = self.reload(table);
+        let shell = self.shell(table);
 
         Some(Target {
             name: name?,
             template: template?,
             output: output?,
             reload,
+            shell,
             themes,
         })
     }
@@ -598,6 +662,28 @@ impl Parse<'_> {
         reload
     }
 
+    /// Reads a target's `shell`, which is `None` when the target has none.
+    ///
+    /// A value that names no shell is a problem rather than a `None`, so a typo is a config
+    /// error and not a target that silently never sources.
+    fn shell(&mut self, table: &Table) -> Option<Shell> {
+        let item = table.get("shell")?;
+        let at = self.line_of(table.key("shell"));
+        let Some(text) = item.as_str() else {
+            self.wrong_type("targets.shell", at, item);
+            return None;
+        };
+
+        let shell = Shell::parse(text);
+        if shell.is_none() {
+            self.problems.push(Problem::Shell {
+                value: text.to_owned(),
+                line: at,
+            });
+        }
+        shell
+    }
+
     /// Reads a target's `themes`, which names a theme for one mode or both.
     fn themes(&mut self, table: &dyn TableLike) -> Themes {
         let mut themes = BTreeMap::new();
@@ -792,6 +878,30 @@ mod tests {
         assert!(target(TARGET).reload().is_empty());
     }
 
+    #[test]
+    fn reads_the_shell_whose_hook_sources_a_target() {
+        let source = format!("{TARGET}shell = \"fish\"\n");
+        assert_eq!(target(&source).shell(), Some(Shell::Fish));
+    }
+
+    #[test]
+    fn leaves_a_target_no_shell_sources_unmarked() {
+        assert_eq!(target(TARGET).shell(), None);
+    }
+
+    #[test]
+    fn reports_a_shell_hook_does_not_emit_for() {
+        // A typo is a config error rather than a target that silently never sources.
+        let source = format!("{TARGET}shell = \"nu\"\n");
+        assert_eq!(
+            problems(&source),
+            vec![Problem::Shell {
+                value: "nu".to_owned(),
+                line: 5,
+            }]
+        );
+    }
+
     #[test]
     fn reads_the_per_target_theme_override() {
         let source =
diff --git a/src/hook.rs b/src/hook.rs
new file mode 100644
index 0000000..c8c62a2
--- /dev/null
+++ b/src/hook.rs
@@ -0,0 +1,284 @@
+//! The snippet `vanadis hook` prints for a shell to evaluate.
+//!
+//! `docs/hook.md` decides it. The snippet holds resolved output paths as literals and never
+//! runs vanadis again, so a prompt costs no process and a shell that has lost vanadis from
+//! `$PATH` keeps following. Three invariants hold in every shell: a second evaluation leaves
+//! one hook registered, the hook returns the exit status it found, and every name it defines
+//! is prefixed `_vanadis_`.
+
+use std::fmt::Write as _;
+use std::path::Path;
+
+use crate::config::Shell;
+
+/// How `stat` is asked for an mtime in seconds.
+///
+/// Which one to write is settled when the snippet is generated, because vanadis knows the
+/// system it is running on. The snippet carries no runtime branch.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Stat {
+    /// GNU and busybox: `stat -c %Y`.
+    Gnu,
+    /// The BSDs, macOS among them: `stat -f %m`.
+    Bsd,
+}
+
+impl Stat {
+    /// The one the system this build runs on has.
+    pub const HOST: Self = if cfg!(any(
+        target_os = "macos",
+        target_os = "ios",
+        target_os = "freebsd",
+        target_os = "openbsd",
+        target_os = "netbsd",
+        target_os = "dragonfly"
+    )) {
+        Self::Bsd
+    } else {
+        Self::Gnu
+    };
+
+    /// The arguments that print an mtime in seconds and nothing else.
+    #[must_use]
+    fn arguments(self) -> &'static str {
+        match self {
+            Self::Gnu => "-c %Y",
+            Self::Bsd => "-f %m",
+        }
+    }
+}
+
+/// The snippet that sources `outputs` and follows them, for `shell`.
+///
+/// `outputs` is in the order the targets appear in `config.toml`, which is the order
+/// [`crate::apply`] writes them in.
+#[must_use]
+pub fn snippet(shell: Shell, outputs: &[&Path], stat: Stat) -> String {
+    match shell {
+        Shell::Zsh => zsh(outputs),
+        Shell::Fish => fish(outputs),
+        Shell::Bash => bash(outputs, stat),
+    }
+}
+
+/// The comment the snippet opens with, naming what it is and how to refresh it.
+fn preamble(shell: Shell) -> String {
+    format!(
+        "# vanadis hook {shell}. Sources the output of every target marked `shell = \"{shell}\"`,\n\
+         # and sources it again when that file changes. Written by `vanadis hook {shell}`: the\n\
+         # paths below are literals, so run `eval \"$(vanadis hook {shell})\"` again after moving\n\
+         # an output or adding a target.\n"
+    )
+}
+
+/// The name of the variable holding the mtime last seen for the output at `index`.
+fn variable(index: usize) -> String {
+    format!("_vanadis_mtime_{index}")
+}
+
+/// `text` as one single-quoted word, for a shell that takes a backslash literally there.
+fn quoted(text: &str) -> String {
+    format!("'{}'", text.replace('\'', r"'\''"))
+}
+
+/// `text` as one single-quoted word, for fish, where a backslash is an escape.
+fn quoted_fish(text: &str) -> String {
+    format!("'{}'", text.replace('\\', r"\\").replace('\'', r"\'"))
+}
+
+/// `path` as the shell writes it, which is lossy only for a path that is not UTF-8.
+fn display(path: &Path) -> String {
+    path.to_string_lossy().into_owned()
+}
+
+/// zsh: `zstat` from `zsh/stat`, and `add-zsh-hook`, which deduplicates by function name.
+fn zsh(outputs: &[&Path]) -> String {
+    let mut snippet = preamble(Shell::Zsh);
+
+    // Only the builtin, because `zmodload zsh/stat` also defines a `stat` that shadows the
+    // user's.
+    snippet.push_str(
+        "\nzmodload -F zsh/stat b:zstat\n\
+         autoload -Uz add-zsh-hook\n\n\
+         # Reports whether $1 has moved since the run recorded in the variable named by $2,\n\
+         # and records the new mtime when it has. Emulated, so a user's setopt cannot change\n\
+         # what it means; the source itself runs outside this, in the options the user set.\n\
+         _vanadis_moved() {\n\
+         \temulate -L zsh\n\
+         \tlocal -a info\n\
+         \tzstat -A info +mtime -- $1 2>/dev/null || return 1\n\
+         \t[[ ${(P)2} == $info[1] ]] && return 1\n\
+         \ttypeset -g $2=$info[1]\n\
+         }\n\n",
+    );
+
+    for index in 0..outputs.len() {
+        let _ = writeln!(snippet, "typeset -g {}=", variable(index));
+    }
+
+    snippet.push_str("\n_vanadis_hook() {\n\tlocal _vanadis_status=$?\n");
+    for (index, output) in outputs.iter().enumerate() {
+        let path = quoted(&display(output));
+        let _ = writeln!(
+            snippet,
+            "\t_vanadis_moved {path} {} && source {path}",
+            variable(index)
+        );
+    }
+    snippet.push_str("\treturn $_vanadis_status\n}\n\n");
+
+    snippet.push_str("add-zsh-hook precmd _vanadis_hook\n_vanadis_hook\n");
+    snippet
+}
+
+/// fish: `path mtime`, and a handler function, which replaces its own previous definition.
+fn fish(outputs: &[&Path]) -> String {
+    let mut snippet = preamble(Shell::Fish);
+    snippet.push('\n');
+
+    for index in 0..outputs.len() {
+        let _ = writeln!(snippet, "set -g {} ''", variable(index));
+    }
+
+    snippet.push_str(
+        "\nfunction _vanadis_hook --on-event fish_prompt \
+         --description 'vanadis: follow the applied theme'\n\
+         \tset -l _vanadis_status $status\n",
+    );
+    for (index, output) in outputs.iter().enumerate() {
+        let path = quoted_fish(&display(output));
+        let variable = variable(index);
+        let _ = write!(
+            snippet,
+            "\tif test -e {path}\n\
+             \t\tset -l _vanadis_now (path mtime {path})\n\
+             \t\tif test \"$_vanadis_now\" != \"${variable}\"\n\
+             \t\t\tset -g {variable} $_vanadis_now\n\
+             \t\t\tsource {path}\n\
+             \t\tend\n\
+             \tend\n"
+        );
+    }
+    snippet.push_str("\treturn $_vanadis_status\nend\n\n_vanadis_hook\n");
+    snippet
+}
+
+/// bash: one `stat` per prompt, and a `PROMPT_COMMAND` append guarded by the function name.
+fn bash(outputs: &[&Path], stat: Stat) -> String {
+    let mut snippet = preamble(Shell::Bash);
+
+    let _ = write!(
+        snippet,
+        "\n# Reports whether $1 has moved since the run recorded in the variable named by $2,\n\
+         # and records the new mtime when it has. bash has no builtin that reads an mtime, so\n\
+         # this is the one fork a prompt costs.\n\
+         _vanadis_moved() {{\n\
+         \tlocal now\n\
+         \tnow=$(stat {} -- \"$1\" 2>/dev/null) || return 1\n\
+         \t[ -n \"$now\" ] || return 1\n\
+         \t[ \"$now\" = \"${{!2}}\" ] && return 1\n\
+         \tprintf -v \"$2\" %s \"$now\"\n\
+         }}\n\n",
+        stat.arguments()
+    );
+
+    for index in 0..outputs.len() {
+        let _ = writeln!(snippet, "{}=", variable(index));
+    }
+
+    snippet.push_str("\n_vanadis_hook() {\n\tlocal _vanadis_status=$?\n");
+    for (index, output) in outputs.iter().enumerate() {
+        let path = quoted(&display(output));
+        let _ = writeln!(
+            snippet,
+            "\t_vanadis_moved {path} {} && . {path}",
+            variable(index)
+        );
+    }
+    snippet.push_str("\treturn $_vanadis_status\n}\n\n");
+
+    // `${PROMPT_COMMAND[*]}` reads it whether it is a string or, since 5.1, an array.
+    snippet.push_str(
+        "[[ ${PROMPT_COMMAND[*]:-} == *_vanadis_hook* ]] ||\n\
+         \tPROMPT_COMMAND=\"_vanadis_hook${PROMPT_COMMAND:+;$PROMPT_COMMAND}\"\n\
+         _vanadis_hook\n",
+    );
+    snippet
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn zsh_snippet(outputs: &[&str]) -> String {
+        let paths: Vec<&Path> = outputs.iter().map(Path::new).collect();
+        snippet(Shell::Zsh, &paths, Stat::Gnu)
+    }
+
+    #[test]
+    fn writes_every_output_as_a_quoted_literal() {
+        let snippet = zsh_snippet(&["/home/ada/.config/fzf/colours.zsh"]);
+        assert!(
+            snippet.contains("source '/home/ada/.config/fzf/colours.zsh'"),
+            "{snippet}"
+        );
+    }
+
+    #[test]
+    fn closes_a_quote_a_path_opens() {
+        // A single quote in a path would otherwise end the literal and hand the rest of the
+        // path to the shell as code.
+        let snippet = zsh_snippet(&["/home/ada/it's/colours.zsh"]);
+        assert!(
+            snippet.contains(r"'/home/ada/it'\''s/colours.zsh'"),
+            "{snippet}"
+        );
+    }
+
+    #[test]
+    fn escapes_a_backslash_for_fish_only() {
+        let path = Path::new(r"/home/ada/a\b.fish");
+        assert!(snippet(Shell::Fish, &[path], Stat::Gnu).contains(r"'/home/ada/a\\b.fish'"));
+        assert!(snippet(Shell::Zsh, &[path], Stat::Gnu).contains(r"'/home/ada/a\b.fish'"));
+    }
+
+    #[test]
+    fn gives_each_output_its_own_variable() {
+        let snippet = zsh_snippet(&["/one.zsh", "/two.zsh"]);
+        assert!(
+            snippet.contains("_vanadis_moved '/one.zsh' _vanadis_mtime_0"),
+            "{snippet}"
+        );
+        assert!(
+            snippet.contains("_vanadis_moved '/two.zsh' _vanadis_mtime_1"),
+            "{snippet}"
+        );
+    }
+
+    #[test]
+    fn writes_the_stat_of_the_system_it_generated_on() {
+        let path = Path::new("/one.bash");
+        assert!(snippet(Shell::Bash, &[path], Stat::Gnu).contains("stat -c %Y"));
+        assert!(snippet(Shell::Bash, &[path], Stat::Bsd).contains("stat -f %m"));
+    }
+
+    #[test]
+    fn forks_nothing_for_zsh_or_fish() {
+        // Both read an mtime from a builtin. Only bash spends the external `stat`.
+        let path = Path::new("/one");
+        for shell in [Shell::Zsh, Shell::Fish] {
+            let snippet = snippet(shell, &[path], Stat::Gnu);
+            assert!(!snippet.contains("stat -c"), "{shell}: {snippet}");
+            assert!(!snippet.contains("stat -f"), "{shell}: {snippet}");
+        }
+    }
+
+    #[test]
+    fn restores_the_exit_status_in_every_shell() {
+        let path = Path::new("/one");
+        for shell in Shell::ALL {
+            let snippet = snippet(shell, &[path], Stat::Gnu);
+            assert!(snippet.contains("_vanadis_status"), "{shell}: {snippet}");
+        }
+    }
+}
diff --git a/src/lib.rs b/src/lib.rs
index ecb115e..d6316d7 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -10,6 +10,7 @@ pub mod catalog;
 pub mod check;
 pub mod config;
 pub mod diff;
+pub mod hook;
 pub mod import;
 pub mod init;
 pub mod paint;
@@ -25,8 +26,9 @@ pub mod vocabulary;
 pub use apply::{Applied, ApplyError, Plan, Rendered, apply, landing, plan, render};
 pub use catalog::{Catalog, CatalogError};
 pub use check::{CheckError, Disk, Finding, Report, check, compare};
-pub use config::{Config, ConfigError, Cycle, Target, TargetName};
+pub use config::{Config, ConfigError, Cycle, Shell, Target, TargetName};
 pub use diff::unified;
+pub use hook::Stat;
 pub use import::{ImportError, Imported, import};
 pub use init::{Answer, Binding, Colour, InitError, Occurrence, Scan, Unhandled};
 pub use paint::Paint;
diff --git a/src/main.rs b/src/main.rs
index 7e87616..b1ab1b6 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -9,10 +9,11 @@ use std::process::ExitCode;
 
 use anyhow::Context as _;
 use clap::{ArgGroup, Parser, Subcommand, ValueEnum};
+use vanadis::hook::snippet;
 use vanadis::init::{Answer, Binding, Colour, Draft};
 use vanadis::{
-    Cache, Catalog, Config, Disk, Environment, Paint, Plan, State, System, TargetName, Template,
-    Theme, ThemeId, TokenPath, Tokens, Variant,
+    Cache, Catalog, Config, Disk, Environment, Paint, Plan, Shell, Stat, State, System, Target,
+    TargetName, Template, Theme, ThemeId, TokenPath, Tokens, Variant,
 };
 
 #[derive(Parser)]
@@ -113,6 +114,11 @@ enum Command {
         #[arg(long, conflicts_with_all = ["template", "theme"])]
         variant: Option<Background>,
     },
+    /// Print the snippet a shell evaluates to follow an apply, for `eval`.
+    Hook {
+        /// The shell to print for.
+        shell: ShellArg,
+    },
     /// Find a cached scheme by identifier, variant, name or author.
     Search {
         /// What to look for, compared without case against every column printed.
@@ -139,6 +145,26 @@ enum RemoteCommand {
     Update,
 }
 
+/// [`Shell`], spelled as a command line argument.
+///
+/// A name that is not one of these is refused by the parser, before any file is read.
+#[derive(Clone, Copy, ValueEnum)]
+enum ShellArg {
+    Zsh,
+    Fish,
+    Bash,
+}
+
+impl From<ShellArg> for Shell {
+    fn from(shell: ShellArg) -> Self {
+        match shell {
+            ShellArg::Zsh => Self::Zsh,
+            ShellArg::Fish => Self::Fish,
+            ShellArg::Bash => Self::Bash,
+        }
+    }
+}
+
 /// [`Variant`], spelled as a command line argument.
 #[derive(Clone, Copy, ValueEnum)]
 enum Background {
@@ -219,6 +245,7 @@ fn main() -> anyhow::Result<ExitCode> {
             theme.as_deref(),
             variant.map(Variant::from),
         ),
+        Command::Hook { shell } => hook(&environment, Shell::from(shell)),
         Command::Search { query } => search(&environment, &query),
     }
 }
@@ -533,6 +560,34 @@ fn current(environment: &Environment) -> anyhow::Result<ExitCode> {
     Ok(ExitCode::SUCCESS)
 }
 
+/// Prints the snippet `shell` evaluates to follow an apply.
+///
+/// Only `config.toml` is read: the snippet holds paths and no colours, so no theme is
+/// resolved, no state file is read and `themes/` is not scanned. `docs/hook.md` decides the
+/// rest.
+///
+/// Nothing reaches stdout unless the whole snippet was built, so a config that will not load
+/// cannot leave half of one in the user's shell. A config that loads and names no target for
+/// this shell is not a failure: it reports on stderr and exits zero, because `eval` reads
+/// stdout and the shell it is starting is otherwise fine.
+fn hook(environment: &Environment, shell: Shell) -> anyhow::Result<ExitCode> {
+    let config = Config::load(&environment.config_dir()?, environment.home())?;
+    let outputs: Vec<&Path> = config
+        .targets()
+        .iter()
+        .filter(|target| target.shell() == Some(shell))
+        .map(Target::output)
+        .collect();
+
+    if outputs.is_empty() {
+        eprintln!("no target is marked `shell = \"{shell}\"`, so there is nothing to source");
+        return Ok(ExitCode::SUCCESS);
+    }
+
+    print!("{}", snippet(shell, &outputs, Stat::HOST));
+    Ok(ExitCode::SUCCESS)
+}
+
 /// Prints what one token resolves to, or every token the theme defines.
 ///
 /// Only the theme asked for is read. Scanning `themes/` would parse every other file and
diff --git a/tests/config.rs b/tests/config.rs
index dfe1a14..a658208 100644
--- a/tests/config.rs
+++ b/tests/config.rs
@@ -2,7 +2,7 @@
 
 use std::path::{Path, PathBuf};
 
-use vanadis::{Config, TargetName, Variant};
+use vanadis::{Config, Shell, TargetName, Variant};
 
 fn root() -> PathBuf {
     Path::new(env!("CARGO_MANIFEST_DIR")).to_owned()
@@ -59,3 +59,16 @@ fn expands_an_output_path_against_the_home_directory() {
         Path::new("/home/ada/.config/bat/themes/vanadis.tmTheme")
     );
 }
+
+#[test]
+fn marks_the_target_a_shell_sources() {
+    // The zsh palette is the reference config's one target read from the environment, which
+    // is what `vanadis hook zsh` exists for. See `docs/hook.md`.
+    let config = reference();
+    let zsh = config
+        .targets()
+        .iter()
+        .find(|target| target.name() == &TargetName::parse("zsh").unwrap())
+        .unwrap();
+    assert_eq!(zsh.shell(), Some(Shell::Zsh));
+}
diff --git a/tests/fixtures/hook/config.toml b/tests/fixtures/hook/config.toml
new file mode 100644
index 0000000..0b963ad
--- /dev/null
+++ b/tests/fixtures/hook/config.toml
@@ -0,0 +1,36 @@
+# The tree tests/hook.rs drives. Outputs are relative, so they land in the copy of this
+# directory the test makes rather than anywhere on the machine.
+#
+# One target per shell, and one that names no shell at all, so a `hook` can be asked for a
+# shell nothing sources.
+
+[auto]
+light = "paper-light"
+dark = "nord"
+
+[cycle]
+themes = ["paper-light", "nord"]
+
+[[targets]]
+name = "zsh"
+template = "templates/posix.in"
+output = "out/colours.zsh"
+shell = "zsh"
+
+[[targets]]
+name = "bash"
+template = "templates/posix.in"
+output = "out/colours.bash"
+shell = "bash"
+
+[[targets]]
+name = "fish"
+template = "templates/fish.in"
+output = "out/colours.fish"
+shell = "fish"
+
+# Reached by no `hook`, so an apply of this target alone re-sources nothing.
+[[targets]]
+name = "plain"
+template = "templates/posix.in"
+output = "out/plain.conf"
diff --git a/tests/fixtures/hook/templates/fish.in b/tests/fixtures/hook/templates/fish.in
new file mode 100644
index 0000000..f073123
--- /dev/null
+++ b/tests/fixtures/hook/templates/fish.in
@@ -0,0 +1 @@
+set -g VANADIS_BG '{{colors.bg}}'
diff --git a/tests/fixtures/hook/templates/posix.in b/tests/fixtures/hook/templates/posix.in
new file mode 100644
index 0000000..8c89bae
--- /dev/null
+++ b/tests/fixtures/hook/templates/posix.in
@@ -0,0 +1 @@
+VANADIS_BG='{{colors.bg}}'
diff --git a/tests/fixtures/hook/themes/nord.toml b/tests/fixtures/hook/themes/nord.toml
new file mode 100644
index 0000000..1c8e4a4
--- /dev/null
+++ b/tests/fixtures/hook/themes/nord.toml
@@ -0,0 +1,46 @@
+[meta]
+format = 1
+name = "Nord"
+variant = "dark"
+
+[colors]
+bg = "#2e3440"
+
+# The core vocabulary, so `check` passes on this tree. Every token points at the one
+# colour the templates read; what matters here is that the core is complete.
+[role]
+bg = "{{colors.bg}}"
+fg = "{{colors.bg}}"
+comment = "{{colors.bg}}"
+keyword = "{{colors.bg}}"
+string = "{{colors.bg}}"
+error = "{{colors.bg}}"
+ok = "{{colors.bg}}"
+warn = "{{colors.bg}}"
+visual = "{{colors.bg}}"
+linenr = "{{colors.bg}}"
+accent = "{{colors.bg}}"
+accent-alt = "{{colors.bg}}"
+accent-warm = "{{colors.bg}}"
+inactive = "{{colors.bg}}"
+border = "{{colors.bg}}"
+selection-bg = "{{colors.bg}}"
+hover-bg = "{{colors.bg}}"
+
+[ansi]
+0 = "{{colors.bg}}"
+1 = "{{colors.bg}}"
+2 = "{{colors.bg}}"
+3 = "{{colors.bg}}"
+4 = "{{colors.bg}}"
+5 = "{{colors.bg}}"
+6 = "{{colors.bg}}"
+7 = "{{colors.bg}}"
+8 = "{{colors.bg}}"
+9 = "{{colors.bg}}"
+10 = "{{colors.bg}}"
+11 = "{{colors.bg}}"
+12 = "{{colors.bg}}"
+13 = "{{colors.bg}}"
+14 = "{{colors.bg}}"
+15 = "{{colors.bg}}"
diff --git a/tests/fixtures/hook/themes/paper-light.toml b/tests/fixtures/hook/themes/paper-light.toml
new file mode 100644
index 0000000..dde11d7
--- /dev/null
+++ b/tests/fixtures/hook/themes/paper-light.toml
@@ -0,0 +1,46 @@
+[meta]
+format = 1
+name = "Paper Light"
+variant = "light"
+
+[colors]
+bg = "#eeeeee"
+
+# The core vocabulary, so `check` passes on this tree. Every token points at the one
+# colour the templates read; what matters here is that the core is complete.
+[role]
+bg = "{{colors.bg}}"
+fg = "{{colors.bg}}"
+comment = "{{colors.bg}}"
+keyword = "{{colors.bg}}"
+string = "{{colors.bg}}"
+error = "{{colors.bg}}"
+ok = "{{colors.bg}}"
+warn = "{{colors.bg}}"
+visual = "{{colors.bg}}"
+linenr = "{{colors.bg}}"
+accent = "{{colors.bg}}"
+accent-alt = "{{colors.bg}}"
+accent-warm = "{{colors.bg}}"
+inactive = "{{colors.bg}}"
+border = "{{colors.bg}}"
+selection-bg = "{{colors.bg}}"
+hover-bg = "{{colors.bg}}"
+
+[ansi]
+0 = "{{colors.bg}}"
+1 = "{{colors.bg}}"
+2 = "{{colors.bg}}"
+3 = "{{colors.bg}}"
+4 = "{{colors.bg}}"
+5 = "{{colors.bg}}"
+6 = "{{colors.bg}}"
+7 = "{{colors.bg}}"
+8 = "{{colors.bg}}"
+9 = "{{colors.bg}}"
+10 = "{{colors.bg}}"
+11 = "{{colors.bg}}"
+12 = "{{colors.bg}}"
+13 = "{{colors.bg}}"
+14 = "{{colors.bg}}"
+15 = "{{colors.bg}}"
diff --git a/tests/hook.rs b/tests/hook.rs
new file mode 100644
index 0000000..bf0a036
--- /dev/null
+++ b/tests/hook.rs
@@ -0,0 +1,348 @@
+//! `vanadis hook`, driven by evaluating what it prints in the shell it printed for.
+//!
+//! Asserting the snippet as a string would establish that the generator did not change and
+//! nothing about whether a shell can parse the result, so every test here starts a real
+//! interactive shell and reads what it prints. `docs/hook.md` decides the behaviour.
+//!
+//! A shell that is not installed is skipped, and skipping is refused under `CI`, so removing
+//! the step that installs the shells fails the run rather than quietly passing it.
+
+use std::fs;
+use std::io::Write as _;
+use std::path::{Path, PathBuf};
+use std::process::{Command, Output, Stdio};
+
+/// One shell, and the lines that ask it what this test needs to know.
+struct Shell {
+    /// What `vanadis hook` is asked for, which is also the program to run.
+    name: &'static str,
+    /// The arguments that start it interactive, reading commands from stdin, with no rc file.
+    arguments: &'static [&'static str],
+    /// Evaluating the snippet, given the command that prints it.
+    evaluate: &'static str,
+    /// Printing the colour the sourced output sets, prefixed `bg=`.
+    show: &'static str,
+    /// Printing every prompt hook it has registered, one per line.
+    hooks: &'static str,
+    /// Printing the exit status of the command before it, prefixed `status=`.
+    status: &'static str,
+}
+
+const ZSH: Shell = Shell {
+    name: "zsh",
+    arguments: &["-f", "-is"],
+    evaluate: "eval \"$(@vanadis@ hook zsh)\"",
+    show: "print \"bg=$VANADIS_BG\"",
+    hooks: "print -l $precmd_functions",
+    status: "print \"status=$?\"",
+};
+
+const BASH: Shell = Shell {
+    name: "bash",
+    arguments: &["--norc", "--noprofile", "-i"],
+    evaluate: "eval \"$(@vanadis@ hook bash)\"",
+    show: "echo \"bg=$VANADIS_BG\"",
+    hooks: "echo \"$PROMPT_COMMAND\" | tr ';' '\\n'",
+    status: "echo \"status=$?\"",
+};
+
+const FISH: Shell = Shell {
+    name: "fish",
+    arguments: &["--no-config", "-i"],
+    // A fish snippet is piped into `source`, which is what fish users write for every tool in
+    // this shape. `eval` would need the output collected into one argument first.
+    evaluate: "@vanadis@ hook fish | source",
+    show: "echo \"bg=$VANADIS_BG\"",
+    hooks: "functions --handlers-type fish_prompt",
+    status: "echo \"status=$status\"",
+};
+
+/// A copy of the `hook` fixture, and an empty state directory beside it.
+fn workspace(test: &str) -> (PathBuf, PathBuf) {
+    let root = Path::new(env!("CARGO_TARGET_TMPDIR")).join(test);
+    let _ = fs::remove_dir_all(&root);
+
+    let config = root.join("config");
+    copy(
+        &Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/hook"),
+        &config,
+    );
+
+    let state = root.join("state");
+    fs::create_dir_all(&state).unwrap();
+    (config, state)
+}
+
+fn copy(from: &Path, to: &Path) {
+    fs::create_dir_all(to).unwrap();
+    for entry in fs::read_dir(from).unwrap() {
+        let entry = entry.unwrap();
+        let target = to.join(entry.file_name());
+        if entry.file_type().unwrap().is_dir() {
+            copy(&entry.path(), &target);
+        } else {
+            fs::copy(entry.path(), &target).unwrap();
+        }
+    }
+}
+
+fn vanadis(config: &Path, state: &Path, arguments: &[&str]) -> Output {
+    Command::new(env!("CARGO_BIN_EXE_vanadis"))
+        .args(arguments)
+        .env("VANADIS_CONFIG", config)
+        .env("XDG_STATE_HOME", state)
+        .output()
+        .unwrap()
+}
+
+fn stdout(output: &Output) -> String {
+    String::from_utf8(output.stdout.clone()).unwrap()
+}
+
+fn stderr(output: &Output) -> String {
+    String::from_utf8(output.stderr.clone()).unwrap()
+}
+
+/// Whether this machine has `shell`, refusing to skip under `CI`.
+///
+/// The CI workflow installs all three. A skip there would mean the gate stopped covering a
+/// shell without anything saying so.
+fn installed(shell: &Shell) -> bool {
+    let found = Command::new(shell.name)
+        .arg("--version")
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .status()
+        .is_ok();
+
+    assert!(
+        found || std::env::var_os("CI").is_none(),
+        "{} is not installed, and CI is supposed to install it",
+        shell.name
+    );
+    if !found {
+        eprintln!("skipping: {} is not installed", shell.name);
+    }
+    found
+}
+
+/// Runs `script` in `shell`, with `@vanadis@` standing for the binary under test.
+///
+/// The shell is interactive and reads its commands from stdin, so a prompt is drawn between
+/// them and every prompt hook runs the way it does for a person at a keyboard. Prompts go to
+/// stderr, so what comes back is only what the script printed.
+fn drive(shell: &Shell, config: &Path, state: &Path, script: &str) -> String {
+    let binary = env!("CARGO_BIN_EXE_vanadis");
+    let script = script.replace("@vanadis@", binary);
+
+    let mut child = Command::new(shell.name)
+        .args(shell.arguments)
+        .env("VANADIS_CONFIG", config)
+        .env("XDG_STATE_HOME", state)
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn()
+        .unwrap();
+    child
+        .stdin
+        .take()
+        .unwrap()
+        .write_all(script.as_bytes())
+        .unwrap();
+
+    let output = child.wait_with_output().unwrap();
+    stdout(&output)
+}
+
+/// Backdates every file in `directory`, so the write that follows lands on a different mtime.
+///
+/// An mtime is seconds, and a test that applies twice inside one second would otherwise be
+/// asking the hook to see a change `docs/hook.md` says it cannot. A person switching themes
+/// never hits that; a test run does.
+fn age(directory: &Path) {
+    let long_ago = std::time::SystemTime::UNIX_EPOCH + std::time::Duration::from_secs(1_000_000);
+    for entry in fs::read_dir(directory).unwrap() {
+        let file = fs::OpenOptions::new()
+            .write(true)
+            .open(entry.unwrap().path())
+            .unwrap();
+        file.set_times(fs::FileTimes::new().set_modified(long_ago))
+            .unwrap();
+    }
+}
+
+/// The colour the fixture's themes carry, so a test can name the one it expects.
+const NORD: &str = "#2e3440";
+const PAPER: &str = "#eeeeee";
+
+#[test]
+fn sources_the_output_when_the_snippet_is_evaluated() {
+    for shell in [ZSH, BASH, FISH] {
+        if !installed(&shell) {
+            continue;
+        }
+        let (config, state) = workspace(&format!("hook-eval-{}", shell.name));
+        vanadis(&config, &state, &["apply", "nord"]);
+
+        let script = format!("{}\n{}\n", shell.evaluate, shell.show);
+        let printed = drive(&shell, &config, &state, &script);
+        assert!(
+            printed.contains(&format!("bg={NORD}")),
+            "{}: {printed}",
+            shell.name
+        );
+    }
+}
+
+#[test]
+fn sources_again_at_the_next_prompt_when_a_cycle_moves_the_output() {
+    for shell in [ZSH, BASH, FISH] {
+        if !installed(&shell) {
+            continue;
+        }
+        let (config, state) = workspace(&format!("hook-cycle-{}", shell.name));
+        vanadis(&config, &state, &["apply", "nord"]);
+        age(&config.join("out"));
+
+        // The cycle steps nord to paper-light. The `bg=` after it is printed at a prompt the
+        // hook has run at, which is the whole claim.
+        let script = format!("{}\n@vanadis@ cycle\n{}\n", shell.evaluate, shell.show);
+        let printed = drive(&shell, &config, &state, &script);
+        assert!(
+            printed.contains(&format!("bg={PAPER}")),
+            "{}: {printed}",
+            shell.name
+        );
+    }
+}
+
+#[test]
+fn leaves_one_hook_registered_after_a_second_evaluation() {
+    for shell in [ZSH, BASH, FISH] {
+        if !installed(&shell) {
+            continue;
+        }
+        let (config, state) = workspace(&format!("hook-twice-{}", shell.name));
+        vanadis(&config, &state, &["apply", "nord"]);
+
+        let script = format!("{0}\n{0}\n{1}\n", shell.evaluate, shell.hooks);
+        let printed = drive(&shell, &config, &state, &script);
+        let registered = printed.matches("_vanadis_hook").count();
+        assert_eq!(registered, 1, "{}: {printed}", shell.name);
+    }
+}
+
+#[test]
+fn returns_the_exit_status_the_command_before_the_prompt_left() {
+    for shell in [ZSH, BASH, FISH] {
+        if !installed(&shell) {
+            continue;
+        }
+        let (config, state) = workspace(&format!("hook-status-{}", shell.name));
+        vanadis(&config, &state, &["apply", "nord"]);
+
+        // `false` runs, the hook runs at the prompt after it, and the status read on the next
+        // line is the one a prompt showing `$?` would display.
+        let script = format!("{}\nfalse\n{}\n", shell.evaluate, shell.status);
+        let printed = drive(&shell, &config, &state, &script);
+        assert!(printed.contains("status=1"), "{}: {printed}", shell.name);
+    }
+}
+
+#[test]
+fn sources_nothing_when_an_apply_names_no_shell_target() {
+    for shell in [ZSH, BASH, FISH] {
+        if !installed(&shell) {
+            continue;
+        }
+        let (config, state) = workspace(&format!("hook-only-{}", shell.name));
+        vanadis(&config, &state, &["apply", "nord"]);
+        age(&config.join("out"));
+
+        // `plain` is the target no `hook` sources. Applying paper-light into it alone must
+        // leave the shell on nord, because no file the hook watches was written. The cycle
+        // after it is what keeps this from passing in a shell where the hook never ran.
+        let script = format!(
+            "{}\n@vanadis@ apply paper-light --only plain\n{1}\n@vanadis@ cycle\n{1}\n",
+            shell.evaluate, shell.show
+        );
+        let printed = drive(&shell, &config, &state, &script);
+        let seen: Vec<&str> = printed
+            .lines()
+            .filter(|line| line.starts_with("bg="))
+            .collect();
+        assert_eq!(
+            seen,
+            [format!("bg={NORD}"), format!("bg={PAPER}")],
+            "{}: {printed}",
+            shell.name
+        );
+    }
+}
+
+#[test]
+fn prints_a_snippet_holding_the_output_of_every_target_that_names_the_shell() {
+    let (config, state) = workspace("hook-outputs");
+    let output = vanadis(&config, &state, &["hook", "zsh"]);
+    assert!(
+        stdout(&output).contains("out/colours.zsh"),
+        "{}",
+        stdout(&output)
+    );
+}
+
+#[test]
+fn reads_no_state_file_and_no_theme() {
+    // Nothing has been applied, and the outputs do not exist yet. The snippet holds paths, so
+    // it is the same snippet either way.
+    let (config, state) = workspace("hook-unapplied");
+    let output = vanadis(&config, &state, &["hook", "zsh"]);
+    assert!(output.status.success(), "{}", stderr(&output));
+}
+
+#[test]
+fn says_so_on_stderr_and_exits_zero_when_no_target_names_the_shell() {
+    let root = Path::new(env!("CARGO_TARGET_TMPDIR")).join("hook-none");
+    let _ = fs::remove_dir_all(&root);
+    let config = root.join("config");
+    copy(
+        &Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/apply"),
+        &config,
+    );
+    let state = root.join("state");
+    fs::create_dir_all(&state).unwrap();
+
+    let output = vanadis(&config, &state, &["hook", "zsh"]);
+    assert!(output.status.success(), "{}", stderr(&output));
+    assert_eq!(stdout(&output), "");
+    assert!(
+        stderr(&output).contains("shell = \"zsh\""),
+        "{}",
+        stderr(&output)
+    );
+}
+
+#[test]
+fn refuses_a_shell_it_does_not_emit_for() {
+    let (config, state) = workspace("hook-unknown");
+    let output = vanadis(&config, &state, &["hook", "nu"]);
+    assert!(!output.status.success());
+    assert_eq!(stdout(&output), "");
+}
+
+#[test]
+fn prints_nothing_when_the_config_will_not_load() {
+    // A failure that reached stdout would be evaluated by the shell that ran the command.
+    let root = Path::new(env!("CARGO_TARGET_TMPDIR")).join("hook-broken");
+    let _ = fs::remove_dir_all(&root);
+    let config = root.join("config");
+    fs::create_dir_all(&config).unwrap();
+    fs::write(config.join("config.toml"), "[[targets]]\nname = \"a\"\n").unwrap();
+    let state = root.join("state");
+    fs::create_dir_all(&state).unwrap();
+
+    let output = vanadis(&config, &state, &["hook", "zsh"]);
+    assert!(!output.status.success());
+    assert_eq!(stdout(&output), "");
+}

From fc4b40c209e17888cf951acdb3c9d6bbd251c4d1 Mon Sep 17 00:00:00 2001
From: torabit <torabit.humble@gmail.com>
Date: Tue, 8 Sep 2026 04:08:54 +0900
Subject: [PATCH 4/6] test(hook): give fish a terminal, since it draws no
 prompt without one fish emits `fish_prompt` only while drawing a prompt, and
 it draws none when its input is a pipe, `-i` or not. The three tests that
 need a prompt therefore passed nothing to the hook and read the colours the
 evaluation itself had sourced. zsh and bash run precmd and `PROMPT_COMMAND`
 either way, which is why they were green here and on this machine.

`script` allocates a terminal and connects the shell to it, so fish runs its
reader the way it does for a person. Only fish gets one: a terminal makes the
other two draw prompts into the output for nothing. What comes back carries
carriage returns, so they are dropped before the lines are read.

The handler probe falls back to `functions --handlers`, because the type filter
is the part of that command this has not run anywhere yet.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011wxMB7uC4uxSJ2dfHi8ucf
---
 tests/hook.rs | 46 ++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 42 insertions(+), 4 deletions(-)

diff --git a/tests/hook.rs b/tests/hook.rs
index bf0a036..49f3e94 100644
--- a/tests/hook.rs
+++ b/tests/hook.rs
@@ -26,6 +26,12 @@ struct Shell {
     hooks: &'static str,
     /// Printing the exit status of the command before it, prefixed `status=`.
     status: &'static str,
+    /// Whether it needs a terminal before it will draw a prompt at all.
+    ///
+    /// fish emits `fish_prompt` only when it is drawing a prompt, and it draws none for a
+    /// pipe, `-i` or not. zsh and bash run their prompt hooks either way, and giving them a
+    /// terminal would only add the escape sequences a redraw writes.
+    terminal: bool,
 }
 
 const ZSH: Shell = Shell {
@@ -35,6 +41,7 @@ const ZSH: Shell = Shell {
     show: "print \"bg=$VANADIS_BG\"",
     hooks: "print -l $precmd_functions",
     status: "print \"status=$?\"",
+    terminal: false,
 };
 
 const BASH: Shell = Shell {
@@ -44,6 +51,7 @@ const BASH: Shell = Shell {
     show: "echo \"bg=$VANADIS_BG\"",
     hooks: "echo \"$PROMPT_COMMAND\" | tr ';' '\\n'",
     status: "echo \"status=$?\"",
+    terminal: false,
 };
 
 const FISH: Shell = Shell {
@@ -53,8 +61,9 @@ const FISH: Shell = Shell {
     // this shape. `eval` would need the output collected into one argument first.
     evaluate: "@vanadis@ hook fish | source",
     show: "echo \"bg=$VANADIS_BG\"",
-    hooks: "functions --handlers-type fish_prompt",
+    hooks: "functions --handlers-type fish_prompt; or functions --handlers",
     status: "echo \"status=$status\"",
+    terminal: true,
 };
 
 /// A copy of the `hook` fixture, and an empty state directory beside it.
@@ -135,8 +144,7 @@ fn drive(shell: &Shell, config: &Path, state: &Path, script: &str) -> String {
     let binary = env!("CARGO_BIN_EXE_vanadis");
     let script = script.replace("@vanadis@", binary);
 
-    let mut child = Command::new(shell.name)
-        .args(shell.arguments)
+    let mut child = started(shell)
         .env("VANADIS_CONFIG", config)
         .env("XDG_STATE_HOME", state)
         .stdin(Stdio::piped())
@@ -152,7 +160,37 @@ fn drive(shell: &Shell, config: &Path, state: &Path, script: &str) -> String {
         .unwrap();
 
     let output = child.wait_with_output().unwrap();
-    stdout(&output)
+    // A terminal ends its lines with a carriage return, and prints the prompt and the echo of
+    // what was typed around them. Only the lines the script printed are read, so the rest is
+    // noise this leaves in place.
+    stdout(&output).replace('\r', "")
+}
+
+/// The command that starts `shell`, under `script` when it needs a terminal.
+///
+/// `script` allocates one and connects the child to it, so the shell runs its reader the way
+/// it does for a person. Its two spellings differ, and neither accepts the other's.
+fn started(shell: &Shell) -> Command {
+    if !shell.terminal {
+        let mut command = Command::new(shell.name);
+        command.args(shell.arguments);
+        return command;
+    }
+
+    let line = std::iter::once(shell.name)
+        .chain(shell.arguments.iter().copied())
+        .collect::<Vec<_>>()
+        .join(" ");
+    let mut command = Command::new("script");
+    if cfg!(target_os = "macos") {
+        command
+            .args(["-q", "/dev/null"])
+            .arg(shell.name)
+            .args(shell.arguments);
+    } else {
+        command.args(["-q", "-c", &line, "/dev/null"]);
+    }
+    command
 }
 
 /// Backdates every file in `directory`, so the write that follows lands on a different mtime.

From 843e4c67fbe50f5dd108c1c047d172c9c7b6f21b Mon Sep 17 00:00:00 2001
From: torabit <torabit.humble@gmail.com>
Date: Tue, 8 Sep 2026 10:27:03 +0900
Subject: [PATCH 5/6] test(hook): read the colour out of the text, not off the
 start of a line

A terminal writes the prompt and the echo of what was typed around what the
script prints, so under fish the `bg=` marker is no longer at the start of its
line and the filter collected nothing. The two tests that used `contains` were
blind to this and passed; the one that compared the whole sequence failed.

Every test now compares the sequence of colours, found by scanning for `bg=`
followed by one. The echo of `bg=$VANADIS_BG` does not match it, which is what
makes the marker readable from the middle of a line.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011wxMB7uC4uxSJ2dfHi8ucf
---
 tests/hook.rs | 32 ++++++++++++++++----------------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/tests/hook.rs b/tests/hook.rs
index 49f3e94..974de09 100644
--- a/tests/hook.rs
+++ b/tests/hook.rs
@@ -210,6 +210,18 @@ fn age(directory: &Path) {
     }
 }
 
+/// Every colour the script printed, in the order it printed them.
+///
+/// The marker is read out of the text rather than off the start of a line, because a terminal
+/// writes the prompt and the echo of what was typed around it. `bg=$VANADIS_BG`, which is the
+/// echo of the command itself, does not match: the marker is `bg=` followed by a colour.
+fn colours(printed: &str) -> Vec<String> {
+    printed
+        .match_indices("bg=#")
+        .map(|(at, _)| printed[at + 3..].chars().take(7).collect())
+        .collect()
+}
+
 /// The colour the fixture's themes carry, so a test can name the one it expects.
 const NORD: &str = "#2e3440";
 const PAPER: &str = "#eeeeee";
@@ -225,11 +237,7 @@ fn sources_the_output_when_the_snippet_is_evaluated() {
 
         let script = format!("{}\n{}\n", shell.evaluate, shell.show);
         let printed = drive(&shell, &config, &state, &script);
-        assert!(
-            printed.contains(&format!("bg={NORD}")),
-            "{}: {printed}",
-            shell.name
-        );
+        assert_eq!(colours(&printed), [NORD], "{}: {printed}", shell.name);
     }
 }
 
@@ -247,11 +255,7 @@ fn sources_again_at_the_next_prompt_when_a_cycle_moves_the_output() {
         // hook has run at, which is the whole claim.
         let script = format!("{}\n@vanadis@ cycle\n{}\n", shell.evaluate, shell.show);
         let printed = drive(&shell, &config, &state, &script);
-        assert!(
-            printed.contains(&format!("bg={PAPER}")),
-            "{}: {printed}",
-            shell.name
-        );
+        assert_eq!(colours(&printed), [PAPER], "{}: {printed}", shell.name);
     }
 }
 
@@ -306,13 +310,9 @@ fn sources_nothing_when_an_apply_names_no_shell_target() {
             shell.evaluate, shell.show
         );
         let printed = drive(&shell, &config, &state, &script);
-        let seen: Vec<&str> = printed
-            .lines()
-            .filter(|line| line.starts_with("bg="))
-            .collect();
         assert_eq!(
-            seen,
-            [format!("bg={NORD}"), format!("bg={PAPER}")],
+            colours(&printed),
+            [NORD, PAPER],
             "{}: {printed}",
             shell.name
         );

From 93267d665fb0429dac1b4b6591b89f5f9bede5aa Mon Sep 17 00:00:00 2001
From: torabit <torabit.humble@gmail.com>
Date: Tue, 8 Sep 2026 10:28:14 +0900
Subject: [PATCH 6/6] docs(hook): record that fish draws no prompt for a pipe

The three shells are not interchangeable to drive. fish emits `fish_prompt`
only while drawing a prompt and draws none for a pipe, so a piped fish answers
every question about a prompt with the state the evaluation itself left, and
answers it green. This cost two CI rounds to find and would cost them again.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011wxMB7uC4uxSJ2dfHi8ucf
---
 docs/hook.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/hook.md b/docs/hook.md
index ac94fd3..08bd42d 100644
--- a/docs/hook.md
+++ b/docs/hook.md
@@ -218,6 +218,13 @@ alone does not; and the exit status of the command before the prompt survives.
 This is also what fixes the versions claimed. `path mtime` is not in every fish that is
 installed anywhere, and the fish CI runs on is the fish this document claims.
 
+**fish needs a terminal before any of that can be asked.** It emits `fish_prompt` only while
+drawing a prompt, and it draws none when its input is a pipe, `-i` or not, so a piped fish
+answers every prompt question with the state the evaluation itself left. zsh and bash run
+`precmd` and `PROMPT_COMMAND` either way. The fish run is therefore given one, and what comes
+back carries the prompt and the echo of what was typed around what the script printed, which is
+why the assertion reads its marker out of the text rather than off the start of a line.
+
 ## Rejected alternatives
 
 The state file as the signal, a top-level table naming shell targets, and a config read at