From 5a55f6be8a28fc99b6716817fd079ac7bcfe1bcf Mon Sep 17 00:00:00 2001
From: Parth <parth@mehrotra.me>
Date: Mon, 24 Aug 2026 16:11:42 +0000
Subject: [PATCH 01/11] ci: run the headless build, then smoke-test what it
 installed

The workflows named packages and asserted on paths, which meant every
new package needed a matrix row and every moved file needed a workflow
edit. They now do what a person does on a new machine -- bootstrap,
`zig build headless`, check the result -- and the checking moved into
zig/smoke.zig, where it can import the package lists instead of
repeating them.

The build had to change to make that honest:

  - login_shell.zig called std.c.getpwuid from build.zig. On linux the
    build runner is not linked against libc, so this was a compile
    error for the entire build graph: every `zig build <anything>` on
    every linux runner and every container failed identically before
    doing any work. macOS links libc unconditionally, which is why it
    was the only platform where anything passed. $SHELL answers the
    same question without libc.

  - login-shell is no longer part of headless. chsh wants a PAM
    password and appends to /etc/shells, so a group that claims to
    install unattended cannot contain it. It is its own `interactive`
    group; `zig build` still runs everything.

zig/smoke.zig asserts against the lists in config.zig,
nvim_plugins.zig and treesitter.zig, so adding a grammar or a plugin
extends the tests for free. It checks that the binaries run, that
every config link resolves, that neovim starts on the real config with
nothing in :messages, that every grammar actually loads, and that fish
sources the shipped conf.d.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U73fQ6rCbAPPf1YRHga95Q
---
 .github/workflows/ci.yml      | 182 +++-----------------------------
 .github/workflows/distros.yml | 115 ++++----------------
 build.zig                     |  37 ++++++-
 zig/packages/config.zig       |   2 +-
 zig/packages/login_shell.zig  |  13 ++-
 zig/packages/lua_ls.zig       |   2 +-
 zig/packages/nvim_plugins.zig |   4 +-
 zig/packages/treesitter.zig   |   4 +-
 zig/smoke.zig                 | 193 ++++++++++++++++++++++++++++++++++
 9 files changed, 273 insertions(+), 279 deletions(-)
 create mode 100644 zig/smoke.zig

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 9765f3ee..81aaf5ba 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -13,13 +13,14 @@ defaults:
   run:
     shell: bash
 
+# One job per platform, and it does what a person does on a new machine:
+# bootstrap, install, check that the result works. Nothing in here knows the
+# name of a package -- `zig build headless` owns that list, and `zig build
+# smoke` owns what "works" means. See zig/smoke.zig.
 jobs:
-  # Does bootstrap.sh produce the zig that build.zig.zon asks for, twice in a
-  # row, on every runner GitHub offers?
-  bootstrap:
-    name: bootstrap ${{ matrix.os }}
+  headless:
+    name: ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
-    continue-on-error: ${{ matrix.experimental || false }}
     strategy:
       fail-fast: false
       matrix:
@@ -27,187 +28,30 @@ jobs:
           - ubuntu-24.04
           - ubuntu-24.04-arm
           - ubuntu-22.04
-          - ubuntu-22.04-arm
           - macos-26
           - macos-26-intel
           - macos-15
-        include:
-          # zig ships .zip for windows and bootstrap.sh asks for .tar.xz
-          # unconditionally, so these stay red until that is handled.
-          - os: windows-2025
-            experimental: true
-          - os: windows-11-arm
-            experimental: true
     steps:
       - uses: actions/checkout@v5
 
       - uses: actions/cache@v4
         with:
-          path: ~/.local/share/zig
+          path: |
+            ~/.local/share/zig
+            ~/.cache/zig
           key: zig-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('build.zig.zon') }}
 
       - run: ./bootstrap.sh
 
-      - name: version matches minimum_zig_version
-        run: |
-          want=$(sed -n 's/.*minimum_zig_version = "\([^"]*\)".*/\1/p' build.zig.zon)
-          got=$("$HOME/.local/bin/zig" version)
-          echo "want=$want got=$got"
-          test "$want" = "$got"
-
-      - name: running it again is a no-op
+      - name: bootstrap again, expecting a no-op
         run: ./bootstrap.sh
 
-  # One cell per package per OS. Slow, but a red square names the package and
-  # the platform without anyone reading a log.
-  packages:
-    name: ${{ matrix.step }} ${{ matrix.os }}
-    runs-on: ${{ matrix.os }}
-    strategy:
-      fail-fast: false
-      matrix:
-        # Trim this list first if the queue gets painful; the OS axis finds
-        # far more than the step axis does.
-        os:
-          - ubuntu-24.04
-          - ubuntu-24.04-arm
-          - ubuntu-22.04
-          - macos-26
-          - macos-26-intel
-          - macos-15
-        step:
-          - ripgrep
-          - zls
-          - lua-ls
-          - treesitter
-          - nvim-plugins
-          - config
-          - rust
-          - fish
-          - nvim
-        include:
-          - step: ripgrep
-            smoke: rg --version
-          - step: zls
-            smoke: zls --version
-          - step: lua-ls
-            smoke: test -x "$HOME/.local/share/lua-language-server/bin/lua-language-server"
-          - step: treesitter
-            smoke: |
-              ls "$HOME/.local/share/nvim/site/parser/"
-              test "$(ls "$HOME/.local/share/nvim/site/parser/" | wc -l)" -eq 8
-              test -d "$HOME/.local/share/nvim/site/queries/rust"
-          - step: nvim-plugins
-            smoke: |
-              ls "$HOME/.local/share/nvim/site/pack/dotfiles/start/"
-              test -f "$HOME/.local/share/nvim/site/pack/dotfiles/start/telescope-fzf-native.nvim/build/libfzf.so"
-          - step: config
-            smoke: |
-              test -d "$HOME/.config/nvim"
-              test -d "$HOME/.config/wezterm"
-              test -d "$HOME/.config/sway"
-              test -f "$HOME/.config/fish/conf.d/dotfiles.fish"
-              test -f "$HOME/.config/git/config"
-          - step: rust
-            smoke: |
-              "$HOME/.cargo/bin/cargo" --version
-              "$HOME/.cargo/bin/rustup" component list --installed | grep -q rust-analyzer
-          - step: fish
-            smoke: |
-              fish --version
-              fish -c 'echo hello from fish'
-          - step: nvim
-            smoke: nvim --version
-    steps:
-      - uses: actions/checkout@v5
-
-      - uses: actions/cache@v4
-        with:
-          path: ~/.local/share/zig
-          key: zig-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('build.zig.zon') }}
-
-      # The package cache, not the build cache: this is what stops 54 jobs
-      # re-downloading the same pinned tarballs.
-      - uses: actions/cache@v4
-        with:
-          path: ~/.cache/zig
-          key: zigpkg-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('build.zig.zon') }}
-
-      - run: ./bootstrap.sh
-
       - run: echo "$HOME/.local/bin" >> "$GITHUB_PATH"
 
-      - name: zig build ${{ matrix.step }}
-        run: zig build ${{ matrix.step }} --summary all
+      - run: zig build headless --summary all
 
-      - name: smoke
-        run: ${{ matrix.smoke }}
+      - run: zig build smoke
 
       - name: what landed
-        if: always()
+        if: failure()
         run: find "$HOME/.local/bin" "$HOME/.local/share" -maxdepth 3 2>/dev/null | sort | head -60
-
-  # The whole group at once, minus login-shell. See the note in the PR: chsh
-  # needs a PAM password on linux runners and would mutate the runner anyway,
-  # so it cannot be part of an unattended build.
-  integration:
-    name: integration ${{ matrix.os }}
-    runs-on: ${{ matrix.os }}
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-24.04, ubuntu-24.04-arm, macos-26, macos-26-intel]
-    steps:
-      - uses: actions/checkout@v5
-
-      - uses: actions/cache@v4
-        with:
-          path: ~/.local/share/zig
-          key: zig-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('build.zig.zon') }}
-
-      - uses: actions/cache@v4
-        with:
-          path: ~/.cache/zig
-          key: zigpkg-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('build.zig.zon') }}
-
-      - run: ./bootstrap.sh
-      - run: echo "$HOME/.local/bin" >> "$GITHUB_PATH"
-
-      - name: build everything headless except the login shell
-        run: |
-          zig build nvim rust fish lua-ls zls ripgrep nvim-plugins treesitter config --summary all
-
-      # The real test: does neovim start with this config, find its parsers,
-      # and load every plugin, without a single error? --headless writes
-      # normal messages to stderr, so a non-empty stderr proves nothing --
-      # :messages has to be read back and scanned instead.
-      - name: nvim starts clean with the real config
-        run: |
-          cat > /tmp/startup.lua <<'LUA'
-          local out = vim.api.nvim_exec2("messages", { output = true }).output
-          io.stdout:write(out .. "\n")
-          if out:match("E%d+:") or out:match("Error detected") or out:match("Error executing") then
-            io.stdout:write("^ nvim reported errors during startup\n")
-            vim.cmd("cq")
-          end
-          LUA
-          nvim --headless -c 'luafile /tmp/startup.lua' +qa
-
-      - name: treesitter parsers actually load
-        run: |
-          cat > /tmp/parsers.lua <<'LUA'
-          local bad = {}
-          for _, lang in ipairs({ "rust", "zig", "nix", "toml", "json", "bash", "fish", "yaml" }) do
-            local ok, err = pcall(vim.treesitter.language.add, lang)
-            if not ok then table.insert(bad, lang .. " (" .. tostring(err) .. ")") end
-          end
-          if #bad > 0 then
-            io.stdout:write("failed to load: " .. table.concat(bad, ", ") .. "\n")
-            vim.cmd("cq")
-          end
-          io.stdout:write("all 8 parsers loaded\n")
-          LUA
-          nvim --headless -c 'luafile /tmp/parsers.lua' +qa
-
-      - name: fish runs the shipped config
-        run: fish -l -c 'echo $PATH; type -q nvim; and echo nvim visible to fish'
diff --git a/.github/workflows/distros.yml b/.github/workflows/distros.yml
index 1e32b622..a9c9400e 100644
--- a/.github/workflows/distros.yml
+++ b/.github/workflows/distros.yml
@@ -16,7 +16,7 @@ defaults:
     shell: bash
 
 # Containers are driven with `docker run` from an ubuntu runner rather than
-# `container:` — actions/checkout needs a glibc node, which alpine does not
+# `container:` -- actions/checkout needs a glibc node, which alpine does not
 # have, and the point here is to test images that are deliberately bare.
 env:
   RUN: >-
@@ -56,40 +56,39 @@ jobs:
             eval "$SCRIPT"
           '
 
-  # The same images with the smallest set of packages that makes bootstrap
-  # work. If a row here needs something new, that is the documented floor.
-  bootstrap:
-    name: bootstrap ${{ matrix.image }}
+  # The same thing ci.yml does, on distros GitHub does not offer as a runner.
+  # `setup` is the finding: it is the documented floor for that distro, and it
+  # grows only when a row here goes red.
+  headless:
+    name: ${{ matrix.image }}
     runs-on: ubuntu-24.04
+    continue-on-error: ${{ matrix.experimental || false }}
     strategy:
       fail-fast: false
       matrix:
         include:
-          - image: alpine:3.22
-            setup: apk add --no-cache ca-certificates tar xz
-          - image: debian:13
-            setup: apt-get update && apt-get install -y --no-install-recommends ca-certificates curl xz-utils
           - image: debian:12
-            setup: apt-get update && apt-get install -y --no-install-recommends ca-certificates curl xz-utils
-          - image: ubuntu:22.04
-            setup: apt-get update && apt-get install -y --no-install-recommends ca-certificates curl xz-utils
+            setup: apt-get update && apt-get install -y --no-install-recommends ca-certificates curl xz-utils gcc libc6-dev
           - image: fedora:43
-            setup: dnf install -y tar xz
-          - image: archlinux:latest
-            setup: pacman -Sy --noconfirm --needed curl tar xz
+            setup: dnf install -y tar xz gcc glibc-devel
           - image: rockylinux/rockylinux:9
-            setup: dnf install -y tar xz
+            setup: dnf install -y tar xz gcc glibc-devel
+          # musl: zls and lua-language-server publish glibc-only binaries, so
+          # this row documents that gap rather than gating the build on it.
+          - image: alpine:3.22
+            setup: apk add --no-cache ca-certificates tar xz gcc musl-dev
+            experimental: true
     steps:
       - uses: actions/checkout@v5
-      - name: bootstrap and re-bootstrap
+      - name: bootstrap, install, smoke test
         env:
           SETUP: ${{ matrix.setup }}
           SCRIPT: |
             ./bootstrap.sh
-            want=$(sed -n 's/.*minimum_zig_version = "\([^"]*\)".*/\1/p' build.zig.zon)
-            got=$("$HOME/.local/bin/zig" version)
-            echo "want=$want got=$got"; test "$want" = "$got"
             ./bootstrap.sh
+            export PATH="$HOME/.local/bin:$PATH"
+            zig build headless --summary all
+            zig build smoke
         run: |
           $RUN ${{ matrix.image }} sh -euc '
             cp -a /src /work && cd /work
@@ -100,7 +99,7 @@ jobs:
   # zig bundles clang, lld, musl and headers for 76 targets. If that claim is
   # real, the tree-sitter grammars compile on an image with no gcc, no clang,
   # no make and no pkg-config. This is the load-bearing assumption of the whole
-  # repo, so it gets its own job.
+  # repo, so it is the one job that names a package on purpose.
   no-system-compiler:
     name: no cc ${{ matrix.image }}
     runs-on: ubuntu-24.04
@@ -126,80 +125,6 @@ jobs:
             export PATH="$HOME/.local/bin:$PATH"
             zig build treesitter --summary all
             ls "$HOME/.local/share/nvim/site/parser/"
-            test "$(ls "$HOME/.local/share/nvim/site/parser/" | wc -l)" -eq 8
-        run: |
-          $RUN ${{ matrix.image }} sh -euc '
-            cp -a /src /work && cd /work
-            eval "$SETUP"
-            eval "$SCRIPT"
-          '
-
-  # Prebuilt-download packages on musl and on old glibc. ripgrep picks the musl
-  # tarball on alpine and the gnu one elsewhere; zls and lua-ls have no musl
-  # build at all, which is the thing to find out.
-  prebuilts:
-    name: prebuilts ${{ matrix.image }} ${{ matrix.step }}
-    runs-on: ubuntu-24.04
-    continue-on-error: ${{ matrix.experimental || false }}
-    strategy:
-      fail-fast: false
-      matrix:
-        step: [ripgrep, zls, lua-ls]
-        image: ["alpine:3.22", "debian:12", "rockylinux/rockylinux:9"]
-        include:
-          # ripgrep should pass here — it has a musl tarball. zls and lua-ls
-          # ship glibc-only builds, so this row is where that shows up.
-          - image: "alpine:3.22"
-            setup: apk add --no-cache ca-certificates tar xz
-            experimental: true
-          - image: debian:12
-            setup: apt-get update && apt-get install -y --no-install-recommends ca-certificates curl xz-utils
-          - image: rockylinux/rockylinux:9
-            setup: dnf install -y tar xz
-    steps:
-      - uses: actions/checkout@v5
-      - env:
-          SETUP: ${{ matrix.setup }}
-          SCRIPT: |
-            ./bootstrap.sh
-            export PATH="$HOME/.local/bin:$PATH"
-            zig build ${{ matrix.step }} --summary all
-            find "$HOME/.local/bin" "$HOME/.local/share" -maxdepth 2 2>/dev/null | sort
-        run: |
-          $RUN ${{ matrix.image }} sh -euc '
-            cp -a /src /work && cd /work
-            eval "$SETUP"
-            eval "$SCRIPT"
-          '
-
-  # rust and fish are the packages that reach outside zig: rustup-init writes
-  # $HOME/.cargo, and cargo needs a linker. This job documents what that costs
-  # per distro.
-  toolchain:
-    name: rust+fish ${{ matrix.image }}
-    runs-on: ubuntu-24.04
-    continue-on-error: ${{ matrix.experimental || false }}
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - image: debian:12
-            setup: apt-get update && apt-get install -y --no-install-recommends ca-certificates curl xz-utils gcc libc6-dev
-          - image: alpine:3.22
-            setup: apk add --no-cache ca-certificates tar xz gcc musl-dev
-            experimental: true
-    steps:
-      - uses: actions/checkout@v5
-      - env:
-          SETUP: ${{ matrix.setup }}
-          SCRIPT: |
-            ./bootstrap.sh
-            export PATH="$HOME/.local/bin:$PATH"
-            zig build rust --summary all
-            "$HOME/.cargo/bin/cargo" --version
-            zig build fish --summary all
-            "$HOME/.local/bin/fish" --version
-            "$HOME/.local/bin/fish" -c 'echo hello from fish'
         run: |
           $RUN ${{ matrix.image }} sh -euc '
             cp -a /src /work && cd /work
diff --git a/build.zig b/build.zig
index df0286c3..00a78730 100644
--- a/build.zig
+++ b/build.zig
@@ -1,11 +1,13 @@
 const std = @import("std");
 const Env = @import("zig/Env.zig");
 
+// Everything here has to run start to finish with nobody watching: no password
+// prompt, no tty, no machine state changed outside the install prefix. That is
+// what makes `zig build headless` the one command CI runs.
 const headless = .{
     @import("zig/packages/neovim.zig"),
     @import("zig/packages/rust.zig"),
     @import("zig/packages/fish.zig"),
-    @import("zig/packages/login_shell.zig"),
     @import("zig/packages/lua_ls.zig"),
     @import("zig/packages/zls.zig"),
     @import("zig/packages/ripgrep.zig"),
@@ -14,6 +16,12 @@ const headless = .{
     @import("zig/packages/config.zig"),
 };
 
+// chsh wants a PAM password and writes to /etc/shells. Nothing unattended can
+// do that, so it is its own group rather than a footnote in headless.
+const interactive = .{
+    @import("zig/packages/login_shell.zig"),
+};
+
 const gui = .{
     @import("zig/packages/brew.zig"),
 };
@@ -22,8 +30,11 @@ pub fn build(b: *std.Build) void {
     const env = Env.init(b);
     const all = b.getInstallStep();
 
-    all.dependOn(group(env, "headless", "everything that runs without a display", headless));
+    all.dependOn(group(env, "headless", "everything that installs unattended", headless));
+    all.dependOn(group(env, "interactive", "steps that will prompt you", interactive));
     all.dependOn(group(env, "gui", "desktop applications", gui));
+
+    smoke(env);
 }
 
 fn group(env: Env, name: []const u8, description: []const u8, comptime packages: anytype) *std.Build.Step {
@@ -31,3 +42,25 @@ fn group(env: Env, name: []const u8, description: []const u8, comptime packages:
     inline for (packages) |pkg| step.dependOn(pkg.install(env));
     return step;
 }
+
+// `zig build smoke` asks the installed tree whether it works, which is a
+// different question from whether it built. It deliberately does not depend on
+// the headless step: after an install you want to re-check without rebuilding,
+// and in CI a smoke failure should be a separate red square from a build one.
+fn smoke(env: Env) void {
+    const b = env.b;
+
+    const tests = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("zig/smoke.zig"),
+            .target = b.graph.host,
+            .optimize = .Debug,
+        }),
+    });
+
+    const run = b.addRunArtifact(tests);
+    run.setEnvironmentVariable("DOTFILES_PREFIX", env.prefix);
+    run.has_side_effects = true;
+
+    b.step("smoke", "check that an installed dotfiles actually works").dependOn(&run.step);
+}
diff --git a/zig/packages/config.zig b/zig/packages/config.zig
index 6d01350d..12a14aab 100644
--- a/zig/packages/config.zig
+++ b/zig/packages/config.zig
@@ -4,7 +4,7 @@ const Env = @import("../Env.zig");
 pub const name = "config";
 pub const description = "symlink dotfiles into ~/.config";
 
-const links = [_][2][]const u8{
+pub const links = [_][2][]const u8{
     .{ "fish/conf.d/dotfiles.fish", ".config/fish/conf.d/dotfiles.fish" },
     .{ "wezterm", ".config/wezterm" },
     .{ "nvim", ".config/nvim" },
diff --git a/zig/packages/login_shell.zig b/zig/packages/login_shell.zig
index b2828fec..fa8d3e9f 100644
--- a/zig/packages/login_shell.zig
+++ b/zig/packages/login_shell.zig
@@ -3,7 +3,11 @@ const Env = @import("../Env.zig");
 const fish = @import("fish.zig");
 
 pub const name = "login-shell";
-pub const description = "make the fish we build the login shell";
+pub const description = "make the fish we build the login shell (asks for a password)";
+
+// $SHELL rather than getpwuid: build.zig is compiled without libc on linux, so
+// any std.c call in here is a compile error for the whole build graph, not just
+// for this step.
 
 pub fn install(env: Env) *std.Build.Step {
     const b = env.b;
@@ -12,7 +16,7 @@ pub fn install(env: Env) *std.Build.Step {
 
     const shell = b.pathJoin(&.{ env.prefix, "bin", "fish" });
 
-    if (currentShell()) |current| {
+    if (b.graph.environ_map.get("SHELL")) |current| {
         if (std.mem.eql(u8, current, shell)) return step;
     }
 
@@ -37,11 +41,6 @@ pub fn install(env: Env) *std.Build.Step {
     return step;
 }
 
-fn currentShell() ?[]const u8 {
-    const pw = std.c.getpwuid(std.c.getuid()) orelse return null;
-    return std.mem.span(pw.shell orelse return null);
-}
-
 fn isRegistered(b: *std.Build, shell: []const u8) bool {
     const io = b.graph.io;
     const text = std.Io.Dir.cwd().readFileAlloc(io, "/etc/shells", b.allocator, .limited(64 * 1024)) catch return false;
diff --git a/zig/packages/lua_ls.zig b/zig/packages/lua_ls.zig
index a992aaa4..8f30a2a6 100644
--- a/zig/packages/lua_ls.zig
+++ b/zig/packages/lua_ls.zig
@@ -4,7 +4,7 @@ const Env = @import("../Env.zig");
 pub const name = "lua-ls";
 pub const description = "lua-language-server, from its prebuilt release";
 
-const subdir = "share/lua-language-server";
+pub const subdir = "share/lua-language-server";
 
 pub fn install(env: Env) *std.Build.Step {
     const b = env.b;
diff --git a/zig/packages/nvim_plugins.zig b/zig/packages/nvim_plugins.zig
index f7af472e..3d6a11cb 100644
--- a/zig/packages/nvim_plugins.zig
+++ b/zig/packages/nvim_plugins.zig
@@ -4,9 +4,9 @@ const Env = @import("../Env.zig");
 pub const name = "nvim-plugins";
 pub const description = "neovim plugins, pinned in build.zig.zon";
 
-const pack = "share/nvim/site/pack/dotfiles/start";
+pub const pack = "share/nvim/site/pack/dotfiles/start";
 
-const plugins = [_][2][]const u8{
+pub const plugins = [_][2][]const u8{
     .{ "plenary", "plenary.nvim" },
     .{ "telescope", "telescope.nvim" },
     .{ "web_devicons", "nvim-web-devicons" },
diff --git a/zig/packages/treesitter.zig b/zig/packages/treesitter.zig
index 7dfe7a21..4afa2dcf 100644
--- a/zig/packages/treesitter.zig
+++ b/zig/packages/treesitter.zig
@@ -4,14 +4,14 @@ const Env = @import("../Env.zig");
 pub const name = "treesitter";
 pub const description = "tree-sitter grammars, compiled by zig";
 
-const Grammar = struct {
+pub const Grammar = struct {
     lang: []const u8,
     dep: []const u8,
     scanner: bool = false,
     flags: []const []const u8 = &.{},
 };
 
-const grammars = [_]Grammar{
+pub const grammars = [_]Grammar{
     .{ .lang = "rust", .dep = "ts_rust", .scanner = true },
     .{ .lang = "zig", .dep = "ts_zig" },
     .{ .lang = "nix", .dep = "ts_nix", .scanner = true },
diff --git a/zig/smoke.zig b/zig/smoke.zig
new file mode 100644
index 00000000..dfe4ecc5
--- /dev/null
+++ b/zig/smoke.zig
@@ -0,0 +1,193 @@
+//! Smoke tests for an installed dotfiles tree.
+//!
+//! `zig build headless` answers "did it build". These answer "does the machine
+//! work", which is the only question worth asking afterwards, so they run
+//! against $DOTFILES_PREFIX and never look at the build graph.
+//!
+//! The lists they check against are imported from the packages themselves, so
+//! adding a grammar or a plugin extends the tests without touching this file.
+
+const std = @import("std");
+const testing = std.testing;
+
+const config = @import("packages/config.zig");
+const lua_ls = @import("packages/lua_ls.zig");
+const nvim_plugins = @import("packages/nvim_plugins.zig");
+const treesitter = @import("packages/treesitter.zig");
+
+const gpa = testing.allocator;
+
+fn env(key: []const u8) ?[]const u8 {
+    return testing.environ.getPosix(key);
+}
+
+fn prefix() []const u8 {
+    return env("DOTFILES_PREFIX") orelse
+        @panic("DOTFILES_PREFIX is not set; run this as `zig build smoke`");
+}
+
+const Path = struct {
+    buf: [std.fs.max_path_bytes]u8 = undefined,
+
+    /// Resolve a path relative to the install prefix.
+    fn in(p: *Path, parts: []const []const u8) []const u8 {
+        var w: std.Io.Writer = .fixed(&p.buf);
+        w.writeAll(prefix()) catch @panic("path too long");
+        for (parts) |part| {
+            w.writeByte('/') catch @panic("path too long");
+            w.writeAll(part) catch @panic("path too long");
+        }
+        return w.buffered();
+    }
+
+    /// Resolve a path relative to $HOME. Only rustup lands outside the prefix.
+    fn home(p: *Path, parts: []const []const u8) []const u8 {
+        var w: std.Io.Writer = .fixed(&p.buf);
+        w.writeAll(env("HOME") orelse @panic("HOME is not set")) catch @panic("path too long");
+        for (parts) |part| {
+            w.writeByte('/') catch @panic("path too long");
+            w.writeAll(part) catch @panic("path too long");
+        }
+        return w.buffered();
+    }
+};
+
+fn expectExists(path: []const u8, options: std.Io.Dir.AccessOptions) !void {
+    std.Io.Dir.cwd().access(testing.io, path, options) catch |err| {
+        std.debug.print("missing: {s} ({s})\n", .{ path, @errorName(err) });
+        return error.NotInstalled;
+    };
+}
+
+/// Run a command and require a clean exit. When `needle` is given it has to
+/// appear on stdout or stderr -- plenty of tools report their version on
+/// either, and which one is not what is being tested here.
+fn expectRun(argv: []const []const u8, needle: ?[]const u8) !void {
+    const result = std.process.run(gpa, testing.io, .{ .argv = argv }) catch |err| {
+        std.debug.print("could not run {s}: {s}\n", .{ argv[0], @errorName(err) });
+        return error.CommandFailed;
+    };
+    defer gpa.free(result.stdout);
+    defer gpa.free(result.stderr);
+
+    const failed = switch (result.term) {
+        .exited => |code| code != 0,
+        else => true,
+    };
+    if (failed or (needle != null and
+        std.mem.indexOf(u8, result.stdout, needle.?) == null and
+        std.mem.indexOf(u8, result.stderr, needle.?) == null))
+    {
+        std.debug.print(
+            \\command: {s}
+            \\term: {any}
+            \\stdout: {s}
+            \\stderr: {s}
+            \\
+        , .{ argv[0], result.term, result.stdout, result.stderr });
+        if (failed) return error.CommandFailed;
+        std.debug.print("expected the output to mention \"{s}\"\n", .{needle.?});
+        return error.UnexpectedOutput;
+    }
+}
+
+test "the binaries we install run" {
+    var p: Path = .{};
+
+    try expectRun(&.{ p.in(&.{ "bin", "nvim" }), "--version" }, "NVIM");
+    try expectRun(&.{ p.in(&.{ "bin", "rg" }), "--version" }, "ripgrep");
+    try expectRun(&.{ p.in(&.{ "bin", "zls" }), "--version" }, null);
+    try expectRun(&.{ p.in(&.{ "bin", "fish" }), "--version" }, "fish");
+    try expectRun(&.{ p.home(&.{ ".cargo", "bin", "cargo" }), "--version" }, "cargo");
+
+    // lua-language-server has no --version that exits, so this is the most an
+    // install check can honestly claim.
+    try expectExists(p.in(&.{ lua_ls.subdir, "bin", "lua-language-server" }), .{ .execute = true });
+}
+
+test "rust-analyzer is in the toolchain" {
+    var p: Path = .{};
+    try expectRun(
+        &.{ p.home(&.{ ".cargo", "bin", "rustup" }), "component", "list", "--installed" },
+        "rust-analyzer",
+    );
+}
+
+test "every config link resolves" {
+    var p: Path = .{};
+    var buf: [std.fs.max_path_bytes]u8 = undefined;
+
+    for (config.links) |link| {
+        const path = p.home(&.{link[1]});
+
+        // readLink proves it is ours rather than a file that happened to be
+        // there; access follows it, which proves the far end still exists.
+        _ = std.Io.Dir.cwd().readLink(testing.io, path, &buf) catch |err| {
+            std.debug.print("not a symlink: {s} ({s})\n", .{ path, @errorName(err) });
+            return error.NotLinked;
+        };
+        try expectExists(path, .{});
+    }
+}
+
+test "every plugin is unpacked" {
+    var p: Path = .{};
+
+    for (nvim_plugins.plugins) |plugin| {
+        try expectExists(p.in(&.{ nvim_plugins.pack, plugin[1] }), .{});
+    }
+
+    // The one plugin with a compiled component; telescope falls back to a slow
+    // pure-lua sorter if this is missing rather than saying anything.
+    try expectExists(
+        p.in(&.{ nvim_plugins.pack, "telescope-fzf-native.nvim", "build", "libfzf.so" }),
+        .{},
+    );
+}
+
+test "every grammar is compiled" {
+    var p: Path = .{};
+
+    inline for (treesitter.grammars) |grammar| {
+        try expectExists(p.in(&.{ "share/nvim/site/parser", grammar.lang ++ ".so" }), .{});
+        try expectExists(p.in(&.{ "share/nvim/site/queries", grammar.lang }), .{});
+    }
+}
+
+/// nvim --headless writes ordinary messages to stderr, so a non-empty stderr
+/// proves nothing. :messages has to be read back and scanned instead.
+const startup =
+    "lua local out = vim.api.nvim_exec2('messages', {output=true}).output " ++
+    "io.stdout:write(out) " ++
+    "if out:match('E%d+:') or out:match('Error detected') or out:match('Error executing') " ++
+    "then vim.cmd('cq') end";
+
+test "nvim starts clean with the shipped config" {
+    var p: Path = .{};
+    try expectRun(&.{ p.in(&.{ "bin", "nvim" }), "--headless", "-c", startup, "+qa" }, null);
+}
+
+/// Compiled and installed is not the same as loadable: a grammar built against
+/// the wrong ABI only fails here.
+const load_parsers = blk: {
+    var langs: []const u8 = "";
+    for (treesitter.grammars, 0..) |grammar, i| {
+        langs = langs ++ (if (i == 0) "" else ",") ++ "'" ++ grammar.lang ++ "'";
+    }
+    break :blk "lua local bad = {} " ++
+        "for _, lang in ipairs({" ++ langs ++ "}) do " ++
+        "local ok, err = pcall(vim.treesitter.language.add, lang) " ++
+        "if not ok then bad[#bad+1] = lang .. ': ' .. tostring(err) end end " ++
+        "if #bad > 0 then io.stdout:write(table.concat(bad, '\\n')) vim.cmd('cq') end";
+};
+
+test "nvim loads every grammar" {
+    var p: Path = .{};
+    try expectRun(&.{ p.in(&.{ "bin", "nvim" }), "--headless", "-c", load_parsers, "+qa" }, null);
+}
+
+test "fish runs the shipped config" {
+    var p: Path = .{};
+    // conf.d sets these; if the symlink or fish_add_path broke, this is empty.
+    try expectRun(&.{ p.in(&.{ "bin", "fish" }), "-l", "-c", "echo $EDITOR" }, "nvim");
+}

From 620f95fce2bbefbfbd67b320dca63f47db611668 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 24 Aug 2026 16:15:19 +0000
Subject: [PATCH 02/11] distros: report the bare-image floor instead of
 asserting it

Four of the seven images do not ship curl or xz, so four of the seven
squares were red by design. A matrix that is expected to be part red is
a matrix nobody reads. One job now runs all seven and writes the answer
to the step summary, always green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U73fQ6rCbAPPf1YRHga95Q
---
 .github/workflows/distros.yml | 48 ++++++++++++++++-------------------
 1 file changed, 22 insertions(+), 26 deletions(-)

diff --git a/.github/workflows/distros.yml b/.github/workflows/distros.yml
index a9c9400e..b10c7bf4 100644
--- a/.github/workflows/distros.yml
+++ b/.github/workflows/distros.yml
@@ -24,37 +24,33 @@ env:
     -e SETUP -e SCRIPT -w /
 
 jobs:
-  # What does bootstrap.sh actually require? Stock image, nothing added.
-  # A red square here is a finding to write down, not a build to fix in a rush.
+  # Which images can run bootstrap.sh with nothing added? This reports rather
+  # than asserts: half of these are expected to be missing curl or xz, and a
+  # square that is red on purpose is a square nobody reads. The answer lands in
+  # the run summary instead.
   bare:
-    name: bare ${{ matrix.image }}
+    name: bare images
     runs-on: ubuntu-24.04
-    continue-on-error: true
-    strategy:
-      fail-fast: false
-      matrix:
-        image:
-          - alpine:3.22
-          - debian:13
-          - debian:12
-          - ubuntu:22.04
-          - fedora:43
-          - archlinux:latest
-          - rockylinux/rockylinux:9
     steps:
       - uses: actions/checkout@v5
-      - name: bootstrap with nothing installed
-        env:
-          SETUP: ":"
-          SCRIPT: |
-            ./bootstrap.sh
-            "$HOME/.local/bin/zig" version
+      - name: what does bootstrap.sh need?
         run: |
-          $RUN ${{ matrix.image }} sh -euc '
-            cp -a /src /work && cd /work
-            eval "$SETUP"
-            eval "$SCRIPT"
-          '
+          echo "| image | bootstrap.sh as shipped |" >> "$GITHUB_STEP_SUMMARY"
+          echo "| --- | --- |" >> "$GITHUB_STEP_SUMMARY"
+          for image in alpine:3.22 debian:13 debian:12 ubuntu:22.04 \
+                       fedora:43 archlinux:latest rockylinux/rockylinux:9; do
+            if out=$($RUN "$image" sh -euc '
+                       cp -a /src /work && cd /work
+                       ./bootstrap.sh && "$HOME/.local/bin/zig" version
+                     ' 2>&1); then
+              note="works"
+            else
+              note="$(printf '%s' "$out" | grep -Eio '[a-z0-9_-]+: (not found|Cannot exec)' | sort -u | paste -sd' ' -)"
+              note="needs: ${note:-see logs}"
+            fi
+            echo "| \`$image\` | $note |" >> "$GITHUB_STEP_SUMMARY"
+            echo "$image: $note"
+          done
 
   # The same thing ci.yml does, on distros GitHub does not offer as a runner.
   # `setup` is the finding: it is the documented floor for that distro, and it

From 28e01b5a81378e4b28b8fcabd56c6d0848b792ad Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 24 Aug 2026 16:19:46 +0000
Subject: [PATCH 03/11] ci: cap job runtime and show the smoke tally

A passing `zig build` prints nothing, so a green smoke step was
indistinguishable from one that did no work; --summary all makes the
test count visible. timeout-minutes stops a hung step from running
until GitHub's six hour default.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U73fQ6rCbAPPf1YRHga95Q
---
 .github/workflows/ci.yml      | 5 ++++-
 .github/workflows/distros.yml | 3 ++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 81aaf5ba..efe094a8 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -21,6 +21,7 @@ jobs:
   headless:
     name: ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
+    timeout-minutes: 60
     strategy:
       fail-fast: false
       matrix:
@@ -50,7 +51,9 @@ jobs:
 
       - run: zig build headless --summary all
 
-      - run: zig build smoke
+      # --summary all so a green run still shows the test tally rather than
+      # silence, which is what a passing zig build prints.
+      - run: zig build smoke --summary all
 
       - name: what landed
         if: failure()
diff --git a/.github/workflows/distros.yml b/.github/workflows/distros.yml
index b10c7bf4..79c21fa4 100644
--- a/.github/workflows/distros.yml
+++ b/.github/workflows/distros.yml
@@ -58,6 +58,7 @@ jobs:
   headless:
     name: ${{ matrix.image }}
     runs-on: ubuntu-24.04
+    timeout-minutes: 60
     continue-on-error: ${{ matrix.experimental || false }}
     strategy:
       fail-fast: false
@@ -84,7 +85,7 @@ jobs:
             ./bootstrap.sh
             export PATH="$HOME/.local/bin:$PATH"
             zig build headless --summary all
-            zig build smoke
+            zig build smoke --summary all
         run: |
           $RUN ${{ matrix.image }} sh -euc '
             cp -a /src /work && cd /work

From 81086778ec42bedb9eb97a3ec1824b66d259736d Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 24 Aug 2026 16:22:10 +0000
Subject: [PATCH 04/11] ci: make a failure the last thing in the log

--summary all prints a ninety line green tree and the failing step's
own output is interleaved thousands of lines above it, so finding out
what broke meant scrolling past every parser that compiled fine.
--summary failures prints only the subtree that failed. The 'what
landed' find dump went with it: it added sixty lines of
lua-language-server paths between the reader and the error, and the
smoke tests report what is missing far more precisely.

Also corrects the note on the alpine row. zls and lua-ls install fine
on musl -- they are tarball extractions. 58 of 59 steps pass there and
neovim's own build is the one that does not.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U73fQ6rCbAPPf1YRHga95Q
---
 .github/workflows/ci.yml      | 12 +++++-------
 .github/workflows/distros.yml |  8 +++++---
 2 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index efe094a8..bb8b7b0f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -49,12 +49,10 @@ jobs:
 
       - run: echo "$HOME/.local/bin" >> "$GITHUB_PATH"
 
-      - run: zig build headless --summary all
+      # --summary failures, not all: a 90-line green tree buries the one
+      # step that broke thousands of lines above the end of the log.
+      - run: zig build headless --summary failures
 
-      # --summary all so a green run still shows the test tally rather than
-      # silence, which is what a passing zig build prints.
+      # --summary all here: it is four lines, and it turns a silent pass
+      # into a visible test tally.
       - run: zig build smoke --summary all
-
-      - name: what landed
-        if: failure()
-        run: find "$HOME/.local/bin" "$HOME/.local/share" -maxdepth 3 2>/dev/null | sort | head -60
diff --git a/.github/workflows/distros.yml b/.github/workflows/distros.yml
index 79c21fa4..afc61bc9 100644
--- a/.github/workflows/distros.yml
+++ b/.github/workflows/distros.yml
@@ -70,8 +70,10 @@ jobs:
             setup: dnf install -y tar xz gcc glibc-devel
           - image: rockylinux/rockylinux:9
             setup: dnf install -y tar xz gcc glibc-devel
-          # musl: zls and lua-language-server publish glibc-only binaries, so
-          # this row documents that gap rather than gating the build on it.
+          # musl: 58 of 59 steps pass here. rust, fish, the prebuilts, the
+          # grammars and the config links are all fine; neovim's own build is
+          # the single thing that fails, and the smoke tests never get to say
+          # whether the glibc-only zls and lua-ls binaries would have run.
           - image: alpine:3.22
             setup: apk add --no-cache ca-certificates tar xz gcc musl-dev
             experimental: true
@@ -84,7 +86,7 @@ jobs:
             ./bootstrap.sh
             ./bootstrap.sh
             export PATH="$HOME/.local/bin:$PATH"
-            zig build headless --summary all
+            zig build headless --summary failures
             zig build smoke --summary all
         run: |
           $RUN ${{ matrix.image }} sh -euc '

From d93e9ad568c19c298b57a3971884ff71eacd84ec Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 24 Aug 2026 16:29:22 +0000
Subject: [PATCH 05/11] ci: name the two platforms that cannot build neovim

Both were failing in nvim and nowhere else, but for unrelated reasons,
and only one of them is ours:

  alpine: libuv wants linux/errqueue.h and alpine ships no kernel
  headers by default. linux-headers joins the setup line -- that is
  the documented floor growing, which is what the job is for. The row
  stays experimental because zls and lua-language-server are
  glibc-only, so the smoke tests should now be the next thing to fail.

  ubuntu-24.04-arm: nlua0, the bootstrap lua neovim builds to generate
  its own headers, segfaults on aarch64 linux. Every invocation dies
  with SIGSEGV in gen_declarations.lua. Nothing in this repo is on
  that stack, so the row is experimental rather than fixed, and it is
  kept rather than deleted so it goes green on its own.

Both were invisible before: with --summary all the error was
interleaved thousands of lines above the summary.

Also limits the push trigger to master. With push and pull_request
both unfiltered, every commit on a branch with a PR open built the
entire matrix twice.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U73fQ6rCbAPPf1YRHga95Q
---
 .github/workflows/ci.yml      | 14 +++++++++++++-
 .github/workflows/distros.yml | 14 +++++++++-----
 2 files changed, 22 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index bb8b7b0f..4400dec2 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,7 +1,10 @@
 name: ci
 
+# push is limited to master: with both triggers unfiltered, every commit
+# on a branch with a PR open builds the whole matrix twice.
 on:
   push:
+    branches: [master]
   pull_request:
   workflow_dispatch:
 
@@ -22,16 +25,25 @@ jobs:
     name: ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
     timeout-minutes: 60
+    continue-on-error: ${{ matrix.experimental || false }}
     strategy:
       fail-fast: false
       matrix:
         os:
           - ubuntu-24.04
-          - ubuntu-24.04-arm
           - ubuntu-22.04
           - macos-26
           - macos-26-intel
           - macos-15
+        include:
+          # nlua0 -- the bootstrap lua neovim builds to generate its own
+          # headers with -- segfaults on aarch64 linux. Every invocation of it
+          # dies with SIGSEGV while running gen_declarations.lua, so this is
+          # neither flaky nor ours: nothing in this repo is on the stack.
+          # Left running rather than deleted so the row turns green by itself
+          # when neovim fixes it.
+          - os: ubuntu-24.04-arm
+            experimental: true
     steps:
       - uses: actions/checkout@v5
 
diff --git a/.github/workflows/distros.yml b/.github/workflows/distros.yml
index afc61bc9..d71963f5 100644
--- a/.github/workflows/distros.yml
+++ b/.github/workflows/distros.yml
@@ -1,7 +1,10 @@
 name: distros
 
+# push is limited to master: with both triggers unfiltered, every commit
+# on a branch with a PR open builds the whole matrix twice.
 on:
   push:
+    branches: [master]
   pull_request:
   workflow_dispatch:
   schedule:
@@ -70,12 +73,13 @@ jobs:
             setup: dnf install -y tar xz gcc glibc-devel
           - image: rockylinux/rockylinux:9
             setup: dnf install -y tar xz gcc glibc-devel
-          # musl: 58 of 59 steps pass here. rust, fish, the prebuilts, the
-          # grammars and the config links are all fine; neovim's own build is
-          # the single thing that fails, and the smoke tests never get to say
-          # whether the glibc-only zls and lua-ls binaries would have run.
+          # musl: linux-headers is here because libuv wants linux/errqueue.h
+          # and alpine does not ship kernel headers by default -- exactly the
+          # kind of finding this job exists for. Still experimental: zls and
+          # lua-language-server publish glibc-only binaries, so the smoke tests
+          # are expected to be the next thing that fails.
           - image: alpine:3.22
-            setup: apk add --no-cache ca-certificates tar xz gcc musl-dev
+            setup: apk add --no-cache ca-certificates tar xz gcc musl-dev linux-headers
             experimental: true
     steps:
       - uses: actions/checkout@v5

From 27b8e15405e7241ad3b6095e7b28b5cb6355592c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 24 Aug 2026 16:37:50 +0000
Subject: [PATCH 06/11] smoke: run lua-language-server instead of stat-ing it

alpine passing 8/8 after the linux-headers fix made the gap obvious:
every other binary here is a static zig or rust build, so "the file
exists" and "the file runs on this libc" are the same claim for them
and different claims for lua-language-server, which is the one
dynamically linked thing we install. It was the only check that stopped
at access(), which is precisely where it mattered least.

Running language servers means something can wait on stdin forever if
it does not like its arguments, so expectRun now carries a 60s timeout.
Verified it fires: a 60s sleep comes back as error.Timeout in 2.6s
rather than hanging until the runner gives up.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U73fQ6rCbAPPf1YRHga95Q
---
 .github/workflows/distros.yml | 13 ++++++++-----
 zig/smoke.zig                 | 17 +++++++++++++----
 2 files changed, 21 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/distros.yml b/.github/workflows/distros.yml
index d71963f5..44fdc495 100644
--- a/.github/workflows/distros.yml
+++ b/.github/workflows/distros.yml
@@ -73,11 +73,14 @@ jobs:
             setup: dnf install -y tar xz gcc glibc-devel
           - image: rockylinux/rockylinux:9
             setup: dnf install -y tar xz gcc glibc-devel
-          # musl: linux-headers is here because libuv wants linux/errqueue.h
-          # and alpine does not ship kernel headers by default -- exactly the
-          # kind of finding this job exists for. Still experimental: zls and
-          # lua-language-server publish glibc-only binaries, so the smoke tests
-          # are expected to be the next thing that fails.
+          # musl. linux-headers is here because libuv wants linux/errqueue.h
+          # and alpine ships no kernel headers by default -- exactly the kind
+          # of finding this job exists for. With it, the whole build and all
+          # eight smoke tests pass, so the old note that zls is glibc-only was
+          # wrong: it is a static zig binary. lua-language-server is the one
+          # thing here that is not static, and the smoke tests now run it
+          # instead of stat-ing it, so this row is where that gets answered.
+          # Experimental until it has answered.
           - image: alpine:3.22
             setup: apk add --no-cache ca-certificates tar xz gcc musl-dev linux-headers
             experimental: true
diff --git a/zig/smoke.zig b/zig/smoke.zig
index dfe4ecc5..60f8cad7 100644
--- a/zig/smoke.zig
+++ b/zig/smoke.zig
@@ -62,8 +62,16 @@ fn expectExists(path: []const u8, options: std.Io.Dir.AccessOptions) !void {
 /// Run a command and require a clean exit. When `needle` is given it has to
 /// appear on stdout or stderr -- plenty of tools report their version on
 /// either, and which one is not what is being tested here.
+///
+/// Everything here is a language server or a shell, so everything here will
+/// happily wait on stdin forever if it decides it did not understand the
+/// arguments. The timeout turns that into a failed test instead of a job that
+/// runs until the runner gives up.
 fn expectRun(argv: []const []const u8, needle: ?[]const u8) !void {
-    const result = std.process.run(gpa, testing.io, .{ .argv = argv }) catch |err| {
+    const result = std.process.run(gpa, testing.io, .{
+        .argv = argv,
+        .timeout = .{ .duration = .{ .raw = .fromSeconds(60), .clock = .awake } },
+    }) catch |err| {
         std.debug.print("could not run {s}: {s}\n", .{ argv[0], @errorName(err) });
         return error.CommandFailed;
     };
@@ -100,9 +108,10 @@ test "the binaries we install run" {
     try expectRun(&.{ p.in(&.{ "bin", "fish" }), "--version" }, "fish");
     try expectRun(&.{ p.home(&.{ ".cargo", "bin", "cargo" }), "--version" }, "cargo");
 
-    // lua-language-server has no --version that exits, so this is the most an
-    // install check can honestly claim.
-    try expectExists(p.in(&.{ lua_ls.subdir, "bin", "lua-language-server" }), .{ .execute = true });
+    // Run it rather than stat it. lua-language-server is the one thing here
+    // that is not a static zig or rust binary, so "the file is present" and
+    // "the file runs on this libc" are genuinely different claims.
+    try expectRun(&.{ p.in(&.{ lua_ls.subdir, "bin", "lua-language-server" }), "--version" }, null);
 }
 
 test "rust-analyzer is in the toolchain" {

From 7a2d25b5d0d569a475087b08db490c421d359f7c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 24 Aug 2026 16:48:00 +0000
Subject: [PATCH 07/11] distros: record what musl actually does

7 of 8 smoke tests pass on alpine. Everything builds and everything
runs except lua-language-server, which fails to spawn:

  could not run .../bin/lua-language-server: FileNotFound

A glibc ELF on musl -- execve cannot find its interpreter. It is the
only dynamically linked thing we install, and it is the check that
until this morning stopped at access(), which is why nobody had
noticed either way.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U73fQ6rCbAPPf1YRHga95Q
---
 .github/workflows/distros.yml | 23 +++++++++++++++--------
 1 file changed, 15 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/distros.yml b/.github/workflows/distros.yml
index 44fdc495..8121588e 100644
--- a/.github/workflows/distros.yml
+++ b/.github/workflows/distros.yml
@@ -73,14 +73,21 @@ jobs:
             setup: dnf install -y tar xz gcc glibc-devel
           - image: rockylinux/rockylinux:9
             setup: dnf install -y tar xz gcc glibc-devel
-          # musl. linux-headers is here because libuv wants linux/errqueue.h
-          # and alpine ships no kernel headers by default -- exactly the kind
-          # of finding this job exists for. With it, the whole build and all
-          # eight smoke tests pass, so the old note that zls is glibc-only was
-          # wrong: it is a static zig binary. lua-language-server is the one
-          # thing here that is not static, and the smoke tests now run it
-          # instead of stat-ing it, so this row is where that gets answered.
-          # Experimental until it has answered.
+          # musl, and the answer is now precise: 7 of 8 smoke tests pass.
+          #
+          # linux-headers is here because libuv wants linux/errqueue.h, which
+          # alpine does not ship. With it, everything builds -- neovim, fish,
+          # the grammars -- and everything runs except lua-language-server,
+          # which fails to spawn at all:
+          #
+          #   could not run .../bin/lua-language-server: FileNotFound
+          #
+          # That is a glibc ELF on musl: execve cannot find its interpreter.
+          # It is the only dynamically linked thing we install, so it is the
+          # only one that can fail this way. zls is fine -- static zig binary,
+          # which is why the old "zls and lua-ls are glibc-only" note was half
+          # wrong. Fixing it means a musl build of lua-language-server, which
+          # upstream does not publish, so the row stays experimental.
           - image: alpine:3.22
             setup: apk add --no-cache ca-certificates tar xz gcc musl-dev linux-headers
             experimental: true

From 06eedc7b9cc10ecd16ee3d4e5aa1ed30e937a3b8 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 24 Aug 2026 18:14:55 +0000
Subject: [PATCH 08/11] login-shell: make chsh work unattended, back inside
 headless

Reverts the split into an 'interactive' group. login-shell belongs in
headless; what did not belong was a step that could only run with a
human at the keyboard.

chsh as an ordinary user asks PAM for a password, which needs a
terminal. Under sudo it does not ask, and sudo was already required
here to append to /etc/shells, so this asks for nothing it was not
already asking for. As root -- which is every container -- there is
nothing to elevate and often no sudo to elevate with, so the choice is
made at run time by id -u rather than baked in.

The /etc/shells check moved from configure time to run time along with
it, which also drops isRegistered: grep -qxF answers the same question
at the moment it matters instead of one build phase earlier.

Verified the script against stubbed chsh/sudo: as root it skips sudo,
as a normal user it uses it, a second run does not duplicate the
/etc/shells line, and a shell that does not execute fails the step
instead of chsh-ing you into a broken login.

Containers need chsh to exist for this, which is the documented floor
growing again: passwd on debian, util-linux-user on fedora and rocky,
shadow on alpine.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U73fQ6rCbAPPf1YRHga95Q
---
 .github/workflows/distros.yml |  8 ++++----
 build.zig                     | 14 +++-----------
 zig/packages/login_shell.zig  | 32 ++++++++++++--------------------
 3 files changed, 19 insertions(+), 35 deletions(-)

diff --git a/.github/workflows/distros.yml b/.github/workflows/distros.yml
index 8121588e..90eee5db 100644
--- a/.github/workflows/distros.yml
+++ b/.github/workflows/distros.yml
@@ -68,11 +68,11 @@ jobs:
       matrix:
         include:
           - image: debian:12
-            setup: apt-get update && apt-get install -y --no-install-recommends ca-certificates curl xz-utils gcc libc6-dev
+            setup: apt-get update && apt-get install -y --no-install-recommends ca-certificates curl xz-utils gcc libc6-dev passwd
           - image: fedora:43
-            setup: dnf install -y tar xz gcc glibc-devel
+            setup: dnf install -y tar xz gcc glibc-devel util-linux-user
           - image: rockylinux/rockylinux:9
-            setup: dnf install -y tar xz gcc glibc-devel
+            setup: dnf install -y tar xz gcc glibc-devel util-linux-user
           # musl, and the answer is now precise: 7 of 8 smoke tests pass.
           #
           # linux-headers is here because libuv wants linux/errqueue.h, which
@@ -89,7 +89,7 @@ jobs:
           # wrong. Fixing it means a musl build of lua-language-server, which
           # upstream does not publish, so the row stays experimental.
           - image: alpine:3.22
-            setup: apk add --no-cache ca-certificates tar xz gcc musl-dev linux-headers
+            setup: apk add --no-cache ca-certificates tar xz gcc musl-dev linux-headers shadow
             experimental: true
     steps:
       - uses: actions/checkout@v5
diff --git a/build.zig b/build.zig
index 00a78730..d5b4bc39 100644
--- a/build.zig
+++ b/build.zig
@@ -1,13 +1,12 @@
 const std = @import("std");
 const Env = @import("zig/Env.zig");
 
-// Everything here has to run start to finish with nobody watching: no password
-// prompt, no tty, no machine state changed outside the install prefix. That is
-// what makes `zig build headless` the one command CI runs.
+// Everything that runs without a display, and the one command CI runs.
 const headless = .{
     @import("zig/packages/neovim.zig"),
     @import("zig/packages/rust.zig"),
     @import("zig/packages/fish.zig"),
+    @import("zig/packages/login_shell.zig"),
     @import("zig/packages/lua_ls.zig"),
     @import("zig/packages/zls.zig"),
     @import("zig/packages/ripgrep.zig"),
@@ -16,12 +15,6 @@ const headless = .{
     @import("zig/packages/config.zig"),
 };
 
-// chsh wants a PAM password and writes to /etc/shells. Nothing unattended can
-// do that, so it is its own group rather than a footnote in headless.
-const interactive = .{
-    @import("zig/packages/login_shell.zig"),
-};
-
 const gui = .{
     @import("zig/packages/brew.zig"),
 };
@@ -30,8 +23,7 @@ pub fn build(b: *std.Build) void {
     const env = Env.init(b);
     const all = b.getInstallStep();
 
-    all.dependOn(group(env, "headless", "everything that installs unattended", headless));
-    all.dependOn(group(env, "interactive", "steps that will prompt you", interactive));
+    all.dependOn(group(env, "headless", "everything that runs without a display", headless));
     all.dependOn(group(env, "gui", "desktop applications", gui));
 
     smoke(env);
diff --git a/zig/packages/login_shell.zig b/zig/packages/login_shell.zig
index fa8d3e9f..a0a0be7f 100644
--- a/zig/packages/login_shell.zig
+++ b/zig/packages/login_shell.zig
@@ -3,12 +3,11 @@ const Env = @import("../Env.zig");
 const fish = @import("fish.zig");
 
 pub const name = "login-shell";
-pub const description = "make the fish we build the login shell (asks for a password)";
+pub const description = "make the fish we build the login shell";
 
 // $SHELL rather than getpwuid: build.zig is compiled without libc on linux, so
 // any std.c call in here is a compile error for the whole build graph, not just
 // for this step.
-
 pub fn install(env: Env) *std.Build.Step {
     const b = env.b;
     const step = b.step(name, description);
@@ -20,18 +19,21 @@ pub fn install(env: Env) *std.Build.Step {
         if (std.mem.eql(u8, current, shell)) return step;
     }
 
-    const register = if (isRegistered(b, shell)) "" else b.fmt(
-        "printf '%s\\n' \"{s}\" | sudo tee -a /etc/shells >/dev/null\n",
-        .{shell},
-    );
-
+    // chsh as an ordinary user asks PAM for a password, which needs a terminal
+    // and so cannot run unattended. Under sudo it does not ask, and sudo was
+    // already required here to append to /etc/shells. As root -- every
+    // container -- there is nothing to elevate and no sudo to elevate with, so
+    // decide at run time rather than baking one of the two in.
     const run = b.addSystemCommand(&.{
         "/bin/sh", "-c",
         b.fmt(
             \\set -e
-            \\"{0s}" -c 'exit 0'
-            \\{1s}chsh -s "{0s}"
-        , .{ shell, register }),
+            \\shell="{s}"
+            \\"$shell" -c 'exit 0'
+            \\if [ "$(id -u)" = 0 ]; then sudo=; else sudo=sudo; fi
+            \\grep -qxF "$shell" /etc/shells || printf '%s\n' "$shell" | $sudo tee -a /etc/shells >/dev/null
+            \\$sudo chsh -s "$shell" "$(id -un)"
+        , .{shell}),
     });
     run.has_side_effects = true;
 
@@ -40,13 +42,3 @@ pub fn install(env: Env) *std.Build.Step {
     step.dependOn(&run.step);
     return step;
 }
-
-fn isRegistered(b: *std.Build, shell: []const u8) bool {
-    const io = b.graph.io;
-    const text = std.Io.Dir.cwd().readFileAlloc(io, "/etc/shells", b.allocator, .limited(64 * 1024)) catch return false;
-    var lines = std.mem.tokenizeScalar(u8, text, '\n');
-    while (lines.next()) |line| {
-        if (std.mem.eql(u8, std.mem.trim(u8, line, " \t\r"), shell)) return true;
-    }
-    return false;
-}

From 1852c4376b7ce9d90c6d92f065c1790f18fb2476 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 24 Aug 2026 19:01:24 +0000
Subject: [PATCH 09/11] login-shell: stop guarding the /etc/shells append

Drops the grep. Checked what the guard was buying and it was buying
nothing:

  - getusershell(), which is what every consumer of /etc/shells goes
    through, just enumerates the file. Five duplicate lines iterate as
    five entries with no error, and chsh exits 0 against that file.
    Callers ask 'is this shell in here', which a repeated line answers
    the same way a single one does.

  - the append is not what makes the next line work anyway. chsh only
    consults /etc/shells for non-root callers, and this one is always
    root: setting a shell that appears nowhere in the file succeeds.
    It is there so the file stays honest about which shells are login
    shells, not as a precondition.

So the worst case is a couple of duplicate lines during the window
before $SHELL flips and the step stops running at all.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U73fQ6rCbAPPf1YRHga95Q
---
 zig/packages/login_shell.zig | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/zig/packages/login_shell.zig b/zig/packages/login_shell.zig
index a0a0be7f..0345ffb1 100644
--- a/zig/packages/login_shell.zig
+++ b/zig/packages/login_shell.zig
@@ -24,6 +24,14 @@ pub fn install(env: Env) *std.Build.Step {
     // already required here to append to /etc/shells. As root -- every
     // container -- there is nothing to elevate and no sudo to elevate with, so
     // decide at run time rather than baking one of the two in.
+    //
+    // The /etc/shells line is appended without checking whether it is already
+    // there. Duplicates cost nothing: getusershell() enumerates the file and
+    // every consumer is asking "is this shell in here", so a repeated line is
+    // answered the same way as a single one. Nothing depends on the append
+    // either -- chsh only consults /etc/shells for non-root callers, and this
+    // one is always root -- so it is here to keep the file honest about which
+    // shells are login shells, not to make the next line work.
     const run = b.addSystemCommand(&.{
         "/bin/sh", "-c",
         b.fmt(
@@ -31,7 +39,7 @@ pub fn install(env: Env) *std.Build.Step {
             \\shell="{s}"
             \\"$shell" -c 'exit 0'
             \\if [ "$(id -u)" = 0 ]; then sudo=; else sudo=sudo; fi
-            \\grep -qxF "$shell" /etc/shells || printf '%s\n' "$shell" | $sudo tee -a /etc/shells >/dev/null
+            \\printf '%s\n' "$shell" | $sudo tee -a /etc/shells >/dev/null
             \\$sudo chsh -s "$shell" "$(id -un)"
         , .{shell}),
     });

From 4d57ae8a07bea36a21916f3e324ad2ccf7911259 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 24 Aug 2026 19:06:41 +0000
Subject: [PATCH 10/11] distros: make the bare-image report readable

Same job, more lines, no cleverness. The two moving parts are now named
functions -- bootstrap_in and missing_commands -- the image list is one
per line, and the markdown table is assembled once at the end instead of
being appended to from inside the loop.

Fixes a latent bug while it is in there. The old form was

  note="$(printf ... | grep ... | sort -u | paste ...)"
  note="needs: ${note:-see logs}"

and that fallback could never fire: GitHub runs the step under
bash -e -o pipefail, so an image that failed for a reason the grep has
no pattern for made the assignment exit 1 and took the whole step with
it. Verified both halves -- the old form exits 1 without printing the
fallback, the new one reports 'unclear, read the log' and carries on.

The output is also plainer, because the command names are now cut out
of the matches rather than shown raw:

  before   needs: wget: not found xz: Cannot exec
  after    missing: wget xz

Tested against fixtures reproducing each real image's output, plus an
unrecognised failure.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U73fQ6rCbAPPf1YRHga95Q
---
 .github/workflows/distros.yml | 72 ++++++++++++++++++++++++++++-------
 1 file changed, 59 insertions(+), 13 deletions(-)

diff --git a/.github/workflows/distros.yml b/.github/workflows/distros.yml
index 90eee5db..12c55224 100644
--- a/.github/workflows/distros.yml
+++ b/.github/workflows/distros.yml
@@ -38,23 +38,69 @@ jobs:
       - uses: actions/checkout@v5
       - name: what does bootstrap.sh need?
         run: |
-          echo "| image | bootstrap.sh as shipped |" >> "$GITHUB_STEP_SUMMARY"
-          echo "| --- | --- |" >> "$GITHUB_STEP_SUMMARY"
-          for image in alpine:3.22 debian:13 debian:12 ubuntu:22.04 \
-                       fedora:43 archlinux:latest rockylinux/rockylinux:9; do
-            if out=$($RUN "$image" sh -euc '
-                       cp -a /src /work && cd /work
-                       ./bootstrap.sh && "$HOME/.local/bin/zig" version
-                     ' 2>&1); then
-              note="works"
+          images=(
+            alpine:3.22
+            debian:13
+            debian:12
+            ubuntu:22.04
+            fedora:43
+            archlinux:latest
+            rockylinux/rockylinux:9
+          )
+
+          # Run bootstrap.sh in a stock image with nothing installed, and
+          # repeat everything it said. The exit status is the verdict; the
+          # output only gets read when that verdict is failure.
+          #
+          # Spelled out rather than reusing $RUN because this job passes no
+          # SETUP or SCRIPT: there is nothing to configure, which is the point.
+          bootstrap_in() {
+            local image=$1
+            docker run --rm -v "$PWD:/src:ro" -w / "$image" sh -euc '
+              cp -a /src /work
+              cd /work
+              ./bootstrap.sh
+              "$HOME/.local/bin/zig" version
+            ' 2>&1
+          }
+
+          # Reduce that output to the commands the image turned out to lack:
+          #
+          #   ./bootstrap.sh: 38: wget: not found      \
+          #   tar (grandchild): xz: Cannot exec         > becomes "wget xz"
+          #
+          # grep exits 1 when nothing matches, which means the image failed
+          # for a reason we have no name for. That is a real answer, not an
+          # error, so it must not abort the step -- hence the || true, without
+          # which `set -e` would kill the job before the fallback below.
+          missing_commands() {
+            grep -Eio '[a-z0-9_-]+: (not found|cannot exec)' \
+              | cut -d: -f1 \
+              | sort -u \
+              | paste -sd' ' - \
+              || true
+          }
+
+          rows=()
+          for image in "${images[@]}"; do
+            if output=$(bootstrap_in "$image"); then
+              verdict='works as shipped'
             else
-              note="$(printf '%s' "$out" | grep -Eio '[a-z0-9_-]+: (not found|Cannot exec)' | sort -u | paste -sd' ' -)"
-              note="needs: ${note:-see logs}"
+              missing=$(missing_commands <<<"$output")
+              verdict="missing: ${missing:-unclear, read the log}"
             fi
-            echo "| \`$image\` | $note |" >> "$GITHUB_STEP_SUMMARY"
-            echo "$image: $note"
+
+            echo "$image -> $verdict"
+            rows+=("| \`$image\` | $verdict |")
           done
 
+          # One place that knows the table's shape, written once at the end.
+          {
+            echo '| image | bootstrap.sh as shipped |'
+            echo '| --- | --- |'
+            printf '%s\n' "${rows[@]}"
+          } >> "$GITHUB_STEP_SUMMARY"
+
   # The same thing ci.yml does, on distros GitHub does not offer as a runner.
   # `setup` is the finding: it is the documented floor for that distro, and it
   # grows only when a row here goes red.

From 770fdd42806c27ff3893a7c665d4f57de602564e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 24 Aug 2026 19:59:38 +0000
Subject: [PATCH 11/11] drop the two platforms that cannot pass, trim the
 comments

ubuntu-24.04-arm and the alpine headless row were both red on purpose
and both blocked on upstream bugs rather than anything here:

  aarch64: neovim's nlua0 build helper dies because lua_newstate()
  returns null for the LuaJIT it is built against. Reported upstream as
  neovim/neovim#40149, open since June with no response.

  alpine: lua-language-server is the one dynamically linked binary we
  install and upstream publishes no musl build, so it cannot spawn.

Removing them takes continue-on-error and the experimental flag with
them, so every remaining square is one that has to be green. alpine
still appears under no-system-compiler, which passes.

Also cuts the comments back to the ones that answer 'why is this
written this way' rather than restating the code.
---
 .github/workflows/ci.yml      | 27 ++++-----------
 .github/workflows/distros.yml | 65 ++++++++---------------------------
 build.zig                     |  7 ++--
 zig/packages/login_shell.zig  | 19 +++-------
 zig/smoke.zig                 | 40 ++++++++-------------
 5 files changed, 42 insertions(+), 116 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 4400dec2..34f8cbf5 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,7 +1,7 @@
 name: ci
 
-# push is limited to master: with both triggers unfiltered, every commit
-# on a branch with a PR open builds the whole matrix twice.
+# push only on master: with both triggers unfiltered, a branch with a PR open
+# builds everything twice.
 on:
   push:
     branches: [master]
@@ -16,16 +16,14 @@ defaults:
   run:
     shell: bash
 
-# One job per platform, and it does what a person does on a new machine:
-# bootstrap, install, check that the result works. Nothing in here knows the
-# name of a package -- `zig build headless` owns that list, and `zig build
-# smoke` owns what "works" means. See zig/smoke.zig.
+# What a person does on a new machine: bootstrap, install, check it works.
+# `zig build headless` owns the package list, zig/smoke.zig owns what "works"
+# means, and nothing here knows either.
 jobs:
   headless:
     name: ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
     timeout-minutes: 60
-    continue-on-error: ${{ matrix.experimental || false }}
     strategy:
       fail-fast: false
       matrix:
@@ -35,15 +33,6 @@ jobs:
           - macos-26
           - macos-26-intel
           - macos-15
-        include:
-          # nlua0 -- the bootstrap lua neovim builds to generate its own
-          # headers with -- segfaults on aarch64 linux. Every invocation of it
-          # dies with SIGSEGV while running gen_declarations.lua, so this is
-          # neither flaky nor ours: nothing in this repo is on the stack.
-          # Left running rather than deleted so the row turns green by itself
-          # when neovim fixes it.
-          - os: ubuntu-24.04-arm
-            experimental: true
     steps:
       - uses: actions/checkout@v5
 
@@ -61,10 +50,8 @@ jobs:
 
       - run: echo "$HOME/.local/bin" >> "$GITHUB_PATH"
 
-      # --summary failures, not all: a 90-line green tree buries the one
-      # step that broke thousands of lines above the end of the log.
+      # failures, not all: a 90 line green tree buries the step that broke.
       - run: zig build headless --summary failures
 
-      # --summary all here: it is four lines, and it turns a silent pass
-      # into a visible test tally.
+      # all here: four lines, and it turns a silent pass into a test tally.
       - run: zig build smoke --summary all
diff --git a/.github/workflows/distros.yml b/.github/workflows/distros.yml
index 12c55224..2e225a66 100644
--- a/.github/workflows/distros.yml
+++ b/.github/workflows/distros.yml
@@ -1,7 +1,7 @@
 name: distros
 
-# push is limited to master: with both triggers unfiltered, every commit
-# on a branch with a PR open builds the whole matrix twice.
+# push only on master: with both triggers unfiltered, a branch with a PR open
+# builds everything twice.
 on:
   push:
     branches: [master]
@@ -18,19 +18,17 @@ defaults:
   run:
     shell: bash
 
-# Containers are driven with `docker run` from an ubuntu runner rather than
-# `container:` -- actions/checkout needs a glibc node, which alpine does not
-# have, and the point here is to test images that are deliberately bare.
+# docker run rather than `container:` -- actions/checkout needs a glibc node,
+# which alpine does not have, and these images are deliberately bare.
 env:
   RUN: >-
     docker run --rm -v ${{ github.workspace }}:/src:ro
     -e SETUP -e SCRIPT -w /
 
 jobs:
-  # Which images can run bootstrap.sh with nothing added? This reports rather
-  # than asserts: half of these are expected to be missing curl or xz, and a
-  # square that is red on purpose is a square nobody reads. The answer lands in
-  # the run summary instead.
+  # Which images run bootstrap.sh with nothing added? Reports rather than
+  # asserts: several are expected to lack curl or xz, and a square that is red
+  # on purpose is a square nobody reads.
   bare:
     name: bare images
     runs-on: ubuntu-24.04
@@ -48,12 +46,7 @@ jobs:
             rockylinux/rockylinux:9
           )
 
-          # Run bootstrap.sh in a stock image with nothing installed, and
-          # repeat everything it said. The exit status is the verdict; the
-          # output only gets read when that verdict is failure.
-          #
-          # Spelled out rather than reusing $RUN because this job passes no
-          # SETUP or SCRIPT: there is nothing to configure, which is the point.
+          # Exit status is the verdict; output is only read when it fails.
           bootstrap_in() {
             local image=$1
             docker run --rm -v "$PWD:/src:ro" -w / "$image" sh -euc '
@@ -64,15 +57,9 @@ jobs:
             ' 2>&1
           }
 
-          # Reduce that output to the commands the image turned out to lack:
-          #
-          #   ./bootstrap.sh: 38: wget: not found      \
-          #   tar (grandchild): xz: Cannot exec         > becomes "wget xz"
-          #
-          # grep exits 1 when nothing matches, which means the image failed
-          # for a reason we have no name for. That is a real answer, not an
-          # error, so it must not abort the step -- hence the || true, without
-          # which `set -e` would kill the job before the fallback below.
+          # "wget: not found" and "xz: Cannot exec" become "wget xz". grep
+          # exits 1 on no match, which means a failure we have no name for --
+          # an answer, not an error, so it must not trip `set -e`.
           missing_commands() {
             grep -Eio '[a-z0-9_-]+: (not found|cannot exec)' \
               | cut -d: -f1 \
@@ -94,7 +81,6 @@ jobs:
             rows+=("| \`$image\` | $verdict |")
           done
 
-          # One place that knows the table's shape, written once at the end.
           {
             echo '| image | bootstrap.sh as shipped |'
             echo '| --- | --- |'
@@ -102,13 +88,11 @@ jobs:
           } >> "$GITHUB_STEP_SUMMARY"
 
   # The same thing ci.yml does, on distros GitHub does not offer as a runner.
-  # `setup` is the finding: it is the documented floor for that distro, and it
-  # grows only when a row here goes red.
+  # `setup` is the finding: the documented floor for that distro.
   headless:
     name: ${{ matrix.image }}
     runs-on: ubuntu-24.04
     timeout-minutes: 60
-    continue-on-error: ${{ matrix.experimental || false }}
     strategy:
       fail-fast: false
       matrix:
@@ -119,24 +103,6 @@ jobs:
             setup: dnf install -y tar xz gcc glibc-devel util-linux-user
           - image: rockylinux/rockylinux:9
             setup: dnf install -y tar xz gcc glibc-devel util-linux-user
-          # musl, and the answer is now precise: 7 of 8 smoke tests pass.
-          #
-          # linux-headers is here because libuv wants linux/errqueue.h, which
-          # alpine does not ship. With it, everything builds -- neovim, fish,
-          # the grammars -- and everything runs except lua-language-server,
-          # which fails to spawn at all:
-          #
-          #   could not run .../bin/lua-language-server: FileNotFound
-          #
-          # That is a glibc ELF on musl: execve cannot find its interpreter.
-          # It is the only dynamically linked thing we install, so it is the
-          # only one that can fail this way. zls is fine -- static zig binary,
-          # which is why the old "zls and lua-ls are glibc-only" note was half
-          # wrong. Fixing it means a musl build of lua-language-server, which
-          # upstream does not publish, so the row stays experimental.
-          - image: alpine:3.22
-            setup: apk add --no-cache ca-certificates tar xz gcc musl-dev linux-headers shadow
-            experimental: true
     steps:
       - uses: actions/checkout@v5
       - name: bootstrap, install, smoke test
@@ -155,10 +121,9 @@ jobs:
             eval "$SCRIPT"
           '
 
-  # zig bundles clang, lld, musl and headers for 76 targets. If that claim is
-  # real, the tree-sitter grammars compile on an image with no gcc, no clang,
-  # no make and no pkg-config. This is the load-bearing assumption of the whole
-  # repo, so it is the one job that names a package on purpose.
+  # zig bundles clang, lld, musl and headers for 76 targets. If that is real,
+  # the tree-sitter grammars compile with no gcc, clang, make or pkg-config.
+  # The load-bearing claim of the repo, so it gets to name a package.
   no-system-compiler:
     name: no cc ${{ matrix.image }}
     runs-on: ubuntu-24.04
diff --git a/build.zig b/build.zig
index d5b4bc39..1818d070 100644
--- a/build.zig
+++ b/build.zig
@@ -1,7 +1,6 @@
 const std = @import("std");
 const Env = @import("zig/Env.zig");
 
-// Everything that runs without a display, and the one command CI runs.
 const headless = .{
     @import("zig/packages/neovim.zig"),
     @import("zig/packages/rust.zig"),
@@ -35,10 +34,8 @@ fn group(env: Env, name: []const u8, description: []const u8, comptime packages:
     return step;
 }
 
-// `zig build smoke` asks the installed tree whether it works, which is a
-// different question from whether it built. It deliberately does not depend on
-// the headless step: after an install you want to re-check without rebuilding,
-// and in CI a smoke failure should be a separate red square from a build one.
+// Deliberately independent of the headless step, so it can re-check an
+// existing install without rebuilding.
 fn smoke(env: Env) void {
     const b = env.b;
 
diff --git a/zig/packages/login_shell.zig b/zig/packages/login_shell.zig
index 0345ffb1..00ed8bd8 100644
--- a/zig/packages/login_shell.zig
+++ b/zig/packages/login_shell.zig
@@ -6,8 +6,7 @@ pub const name = "login-shell";
 pub const description = "make the fish we build the login shell";
 
 // $SHELL rather than getpwuid: build.zig is compiled without libc on linux, so
-// any std.c call in here is a compile error for the whole build graph, not just
-// for this step.
+// a std.c call here fails to compile the whole build graph.
 pub fn install(env: Env) *std.Build.Step {
     const b = env.b;
     const step = b.step(name, description);
@@ -19,19 +18,9 @@ pub fn install(env: Env) *std.Build.Step {
         if (std.mem.eql(u8, current, shell)) return step;
     }
 
-    // chsh as an ordinary user asks PAM for a password, which needs a terminal
-    // and so cannot run unattended. Under sudo it does not ask, and sudo was
-    // already required here to append to /etc/shells. As root -- every
-    // container -- there is nothing to elevate and no sudo to elevate with, so
-    // decide at run time rather than baking one of the two in.
-    //
-    // The /etc/shells line is appended without checking whether it is already
-    // there. Duplicates cost nothing: getusershell() enumerates the file and
-    // every consumer is asking "is this shell in here", so a repeated line is
-    // answered the same way as a single one. Nothing depends on the append
-    // either -- chsh only consults /etc/shells for non-root callers, and this
-    // one is always root -- so it is here to keep the file honest about which
-    // shells are login shells, not to make the next line work.
+    // sudo so chsh does not ask PAM for a password; skipped as root, where
+    // there is nothing to elevate and often no sudo. The /etc/shells line is
+    // appended unconditionally -- duplicates are harmless.
     const run = b.addSystemCommand(&.{
         "/bin/sh", "-c",
         b.fmt(
diff --git a/zig/smoke.zig b/zig/smoke.zig
index 60f8cad7..7dd11009 100644
--- a/zig/smoke.zig
+++ b/zig/smoke.zig
@@ -1,11 +1,7 @@
-//! Smoke tests for an installed dotfiles tree.
+//! Smoke tests for an installed dotfiles tree, run against $DOTFILES_PREFIX.
 //!
-//! `zig build headless` answers "did it build". These answer "does the machine
-//! work", which is the only question worth asking afterwards, so they run
-//! against $DOTFILES_PREFIX and never look at the build graph.
-//!
-//! The lists they check against are imported from the packages themselves, so
-//! adding a grammar or a plugin extends the tests without touching this file.
+//! The lists come from the packages themselves, so adding a grammar or a
+//! plugin extends the tests without touching this file.
 
 const std = @import("std");
 const testing = std.testing;
@@ -40,7 +36,7 @@ const Path = struct {
         return w.buffered();
     }
 
-    /// Resolve a path relative to $HOME. Only rustup lands outside the prefix.
+    /// Resolve a path relative to $HOME, for the rustup files outside the prefix.
     fn home(p: *Path, parts: []const []const u8) []const u8 {
         var w: std.Io.Writer = .fixed(&p.buf);
         w.writeAll(env("HOME") orelse @panic("HOME is not set")) catch @panic("path too long");
@@ -59,14 +55,9 @@ fn expectExists(path: []const u8, options: std.Io.Dir.AccessOptions) !void {
     };
 }
 
-/// Run a command and require a clean exit. When `needle` is given it has to
-/// appear on stdout or stderr -- plenty of tools report their version on
-/// either, and which one is not what is being tested here.
-///
-/// Everything here is a language server or a shell, so everything here will
-/// happily wait on stdin forever if it decides it did not understand the
-/// arguments. The timeout turns that into a failed test instead of a job that
-/// runs until the runner gives up.
+/// Run a command and require a clean exit. `needle` may appear on either
+/// stream, since tools disagree about where to print a version. The timeout is
+/// because a language server given arguments it dislikes waits on stdin.
 fn expectRun(argv: []const []const u8, needle: ?[]const u8) !void {
     const result = std.process.run(gpa, testing.io, .{
         .argv = argv,
@@ -108,9 +99,8 @@ test "the binaries we install run" {
     try expectRun(&.{ p.in(&.{ "bin", "fish" }), "--version" }, "fish");
     try expectRun(&.{ p.home(&.{ ".cargo", "bin", "cargo" }), "--version" }, "cargo");
 
-    // Run it rather than stat it. lua-language-server is the one thing here
-    // that is not a static zig or rust binary, so "the file is present" and
-    // "the file runs on this libc" are genuinely different claims.
+    // Run it rather than stat it: this is the only dynamically linked binary
+    // we install, so present and runnable are different questions.
     try expectRun(&.{ p.in(&.{ lua_ls.subdir, "bin", "lua-language-server" }), "--version" }, null);
 }
 
@@ -146,8 +136,7 @@ test "every plugin is unpacked" {
         try expectExists(p.in(&.{ nvim_plugins.pack, plugin[1] }), .{});
     }
 
-    // The one plugin with a compiled component; telescope falls back to a slow
-    // pure-lua sorter if this is missing rather than saying anything.
+    // Telescope silently falls back to a slow pure-lua sorter without this.
     try expectExists(
         p.in(&.{ nvim_plugins.pack, "telescope-fzf-native.nvim", "build", "libfzf.so" }),
         .{},
@@ -163,8 +152,8 @@ test "every grammar is compiled" {
     }
 }
 
-/// nvim --headless writes ordinary messages to stderr, so a non-empty stderr
-/// proves nothing. :messages has to be read back and scanned instead.
+/// nvim --headless writes ordinary messages to stderr, so :messages has to be
+/// read back and scanned instead.
 const startup =
     "lua local out = vim.api.nvim_exec2('messages', {output=true}).output " ++
     "io.stdout:write(out) " ++
@@ -176,8 +165,7 @@ test "nvim starts clean with the shipped config" {
     try expectRun(&.{ p.in(&.{ "bin", "nvim" }), "--headless", "-c", startup, "+qa" }, null);
 }
 
-/// Compiled and installed is not the same as loadable: a grammar built against
-/// the wrong ABI only fails here.
+/// Installed is not loadable: a wrong-ABI grammar only fails here.
 const load_parsers = blk: {
     var langs: []const u8 = "";
     for (treesitter.grammars, 0..) |grammar, i| {
@@ -197,6 +185,6 @@ test "nvim loads every grammar" {
 
 test "fish runs the shipped config" {
     var p: Path = .{};
-    // conf.d sets these; if the symlink or fish_add_path broke, this is empty.
+    // Set by conf.d; empty if the symlink or fish_add_path broke.
     try expectRun(&.{ p.in(&.{ "bin", "fish" }), "-l", "-c", "echo $EDITOR" }, "nvim");
 }